I have had a few requests for a simple example in Atari Basic to
display an Envision screen from data statements.

Good news and bad news:    
Envision will write data statements for the character set, but not for
the map.  However, Envision *can* save raw screen information, which
can then be loaded from disk to be displayed in your Basic program.

Before your program can display your map or picture, you will need to
design it then export the apprpriate files.  Here is a step-by-step
guide showing how to do this:
1) Create your font and map.  The example programs use an Antic 4
screen at default resolution of 40x24.  If you want to simply plug in
your own screen without modifying code, do the same.

2) From the Edit screen, set the save options by pressing 'o'
3) Press 'n' to save to your harddisk instead of a disk image
4) Press 'b' to save as basic data statements
5) Enter '1000' or whatever line number you want the data statement to
start at
6) Enter '10' or whatever you want the space between statements to be
7) Enter 'e' to export the data
8) Enter 'font.lst' or whatever you want your file to be called.

9) Go to the Map screen by pressing 'm'
10) Save a raw file by pressing 'w' then entering a filename like
'screen.raw'
11) Save a map file by pressing 's' then entering a filename like
'screen.map'

You should have 3 files on your harddrive now:
font.list   <- Basic data statments for the font
screen.raw  <- Binary file for the screen (40*24 bytes)
screen.map  <- Normal Envision save file


The example .XFD image has 2 examples and the corresponding data
files.  You will find the following files:

screen.raw <- an example raw screen file
screen.map <- an example Envision map file
test1.bas  <- an example Basic program
test2.bas  <- another example program

The Basic program "test1.bas" redefines a font using data statements,
then reads the raw screen data from disk, copying it directly into 
screen memory.

For convenience, the program is shown here:
10 REM FIND MEMTOP, AND RESERVE SPACE FOR FONT
20 MEMTOP=PEEK(106)-4:POKE 106,MEMTOP

25 REM SET GRAPHICS MODE TO RESET MEMTOP, CHANGE TO ANTIC 4
30 GR.0:SC=PEEK(88)+PEEK(89)*256:DL=PEEK(560)+PEEK(561)*256:POKE
DL+3,68
40 FOR I=DL+6 TO DL+28:POKE I,4:NEXT I

45 REM REDEFINE CHARACTER SET, STARTING AT CHARACTER A (33*8)
50 CHR=MEMTOP*256:POKE 756,MEMTOP
60 FOR I=0 TO 17*8-1:READ A:POKE CHR+33*8+I,A:POKE 712,A:NEXT I

65 REM LOAD ENVISION .RAW SCREEN FROM DISK, MUST BE 40X24
70 TRAP 120:OPEN #1,4,0,"D1:SCREEN.RAW"
80 FOR I=0 TO 39*24:GET #1,N:POKE SC+I,N:NEXT I
90 CLOSE #1

100 POKE 708,6:POKE 710,4
110 GOTO 110
120 GR.0:?"Cannot find D1:SCREEN.RAW on disk.":END

490 REM DATA GENERATED BY ENVISION, BUT TRIMMED TO CHARACTERS USED 
500 DATA 0,0,0,0,3,13,53,213
510 DATA 3,13,53,213,85,85,85,85
520 DATA 192,112,92,87,85,85,85,85
530 DATA 0,0,0,0,192,112,92,87
540 DATA 213,53,13,3,0,0,0,0
550 DATA 85,85,85,85,213,53,13,3
560 DATA 85,85,85,85,87,92,112,192
570 DATA 87,92,112,192,0,0,0,0
580 DATA 85,85,85,85,87,93,117,213
590 DATA 87,93,117,213,85,85,85,85
600 DATA 213,117,93,87,85,85,85,85
610 DATA 85,85,85,85,213,117,93,87
620 DATA 192,192,192,192,192,192,192,192
630 DATA 213,245,205,195,192,192,192,192
640 DATA 192,192,192,192,195,205,245,213
650 DATA 0,12,0,0,0,192,0,0
660 DATA 0,0,0,0,48,0,0,0

This document is not intended as a tutorial on how to use redefined
characters, but a few comments are in order.  When using a custom
character set, the first thing that needs to be decided is where to
store the character definitions.  A full character set takes 1024
bytes or 4 pages.  A typical place to store the character set is at
the top of memory.  Unfortunately, Basic also wants to store some
information in the same location (primarily the display list) - so we
must fool the operating system into thinking it has less memory then
it really does... letting us use that "hidden" space for our own
nefarious purposes.  Line 20 in the above program does just that, it
finds out how much memory is available, then reserves 4 pages for us.

Once memory has been reserved, a graphics command must be issued.
This causes the OS to move the display list to a lower location in
memory, giving us the ability to store information above!  Lines 30-40
change to display from Graphics 0 (Antic mode 2) to Antic mode 4.  We
also find out where screen memory starts, and save this information
for later.

Line 50 tells the OS where to find the new character set, then line 60
painstakingly defines the new characters.  We also flash the screen to
let the world know something is going on.  This example only defines
17 characters, but a full character set will have 128 to define, and
this can take a long time.  

The character set definition itself begins at line 500 and continues
to 660.  If you are defining the entire character set, the FOR loop
would normally look like:
 60 FOR I=0 TO 1023:READ A:POKE CHR+I,A:NEXT I
In our example above, however, we start storing the custom characters
at the letter 'A' which is 33 characters into the set.  

At this point, the character set is defined, but now we need to
display the screen.  The Envision .raw file is simply a binary dump of
the map - so all we need to do is open the file and copy the contents
directly to screen memory.  Lines 70-90 do just that, reading from the
file and poking the results directly to the screen.

Finally, line 110 changes the colors and then the program loops so
that the image can be appreciated.

The other Basic program "test2.bas" uses machine language
routines to load the .map file from disk.  The map file contains
both the screen information and the font information in the same file.
Using machine language to load from disk makes this example much
faster then the first program, which utilized GET statements only.
This example program only will display basic non-tiled maps.  For a
complete description of the .map file format, refer to the EnvisionPC
documentation.  However, the Basic program will read the first three
chunks of the .map file:

1) Header information - this includes the Antic mode, the size of the
map, and the color palette.
2) Map information - in a simple map, this is a 1:1 mapping with the
underlying characters.  In essence, this chunk is the same as the .raw
file used above.
3) Font information - the next 1024 bytes contain the complete font data. 


In both examples, the screen is limited to 40x24.  This makes it very
easy to poke the raw data directly onto the screen.   If you want a
larger screen, you will need to either throw away the data that falls
outside the screen or allow the user to scroll, which is no longer a
simple Basic program.  

...Actually, this is fairly trivial in assembly -- I may update the
xfd image at some point to include such an example. 

Until then, enjoy.

--Mark 
06/26/2006
============================================================================
Appendix A:

Good references for basic character set redefinition and much more:

--"Dr. C. Wacko's miracle guide to designing and programming your own
Atari computer arcade games" by David L Heller;  John F Johnson;
Robert Kurcina; Addison-Wesley, 1983. 

This was the first book I used to learn how to program the Atari lo
these many years ago.  A fun text, starting with the very
basics... and ends up with explaining fairly advanced material.

Good luck finding a copy, though!  Another excellent resource is:

--"Atari Graphics & Arcade Game Design" By Jeffrey Stanton with Dan
Pinal.

This is a more advanced book, and quickly moves into Assembly
language.  This book is preserved at the Atari Archive site:
http://www.atariarchives.org/agagd/

Finally,
--"De Re Atari: A Guide to Effective Programming" by Chris Crawford,
Lane Winner, Jim Cox, Amy Chen, Jim Dunion, Kathleen Pitta, Bob
Fraser, and Gus Makrea.

De Re Atari is the great-granddaddy of them all, and should be
considered required reading.  It can also be found at the Atari
Archive at: 
http://www.atariarchives.org/dere/


 

