20 - Graphics I

 "A key ring is a handy little gadget that allows you to lose all
your keys at once."

                YOUR SECOND GFA BASIC 3.XX MANUAL
                             - or -
        HOW I LEARNED TO STOP WORRYING AND LOVE GFA-BASIC
                             PART 21
               CHAPTER TWENTY - GRAPHICS (PART 1)
                          by Han Kempen

Resolutions

 The ST(E) can use three resolutions:  High,  Medium or Low. Here
is an overview:
                         High      Medium      Low
     width (pixels)      640        640        320
     x-coordinate       0-639      0-639      0-319
     height (pixels)     400        200        200
     y-coordinate       0-399      0-199      0-199
     bit-planes            1          2          4
     colours               2          4         16
     colour-index        0-1        0-3        0-15
     scanline (bytes)     80        160        160
     scanlines           400        200        200

 The  number  of bit-planes tells you how many bits are  used  to
determine  the  colour of one pixel.  With one bit you  can  have
colour-index &X0 or &X1, i.e. two colours (black and white). With
two bits you have four colours:  &X00,  &X01,  &X10 and &X11. And
with four bits 16 colours.  The colour-index points to a table of
colour-registers ('palette'),  so the actual colour of a pixel is
determined by the colour-index and the palette.  To make the life
of  programmers more exciting,  there are two  different  colour-
index  tables (see next paragraph).  The current number  of  bit-
planes can be determined in two ways:

     bit.planes&=INT{L~A}                         ! uses Line-A
     bit.planes&=LOG(WORK_OUT(13))/LOG(2)         ! alternative

 WORK_OUT(13) holds the number of colours that can be used on the
screen.

 For High resolution it's easy to understand how the colour-index
of a pixel is coded in RAM.  Screen-RAM starts at  memory-address
XBIOS(2)  (Physbase)  for  the physical screen  and  at  XBIOS(3)
(Logbase)  for  the  logical screen.  In  the  default  situation
physical  and  logical  screen start at  the  same  address.  The
'screen-unit'  is  one word (16 bits).  The first  pixel  of  the
screen at (0,0) is stored in bit 15 of the first unit of  screen-
RAM,  the second pixel (1,0) in bit 14, etc. Bit 15 of the second
unit determines the colour-index of (16,0), etc.

 For  Medium resolution the screen-unit is two consecutive  words
(32 bits).  The colour-index is stored in two bits of course, but
the bits lie 16 bits apart.  The first pixel of the screen  (0,0)
is  stored  in bit 31 and bit 15 of the first  unit.  The  second
pixel (1,0) in bit 30 and 14,  etc.  Bit 31 and 15 of the  second
unit determine the colour-index of (16,0), etc.

 You guessed right,  for Low resolution the screen-unit has to be
four  consecutive words (64 bits).  The bits 63/47/31/15  of  the
first   unit  determine  the  colour-index  of  (0,0)  and   bits
62/46/30/14  of  (1,0).  Bits  63/47/31/15  of  the  second  unit
determine the colour-index of (16,0), etc.

 A horizontal line from left to right on the monitor is called  a
scanline.  The  number  of scanlines is therefore  equal  to  the
height  of  the screen in pixels.  The length of  a  scanline  in
screen-RAM is determined by the width of the screen in pixels and
the number of bit-planes.  In High resolution we have 640  pixels
and  with  1  bit  for one  pixel  that's  80  bytes.  In  Medium
resolution  we  also have 640 pixels,  but with 2  bits  for  one
pixel,  or 160 bytes.  And in Low resolution there are 320 pixels
with 4 bits for one pixel,  so we get 160 bytes  too.  INT{L~A+2}
also gives the scanline-width.

 Perhaps you find all this a bit complicated.  Don't  worry,  you
only need to understand about scanlines and bit-planes if  you're
going to use BMOVE or the Line-A BITBLT-command.

 In the paragraph 'Setscreen (XBIOS 5)' in chapter 9,  I  already
pointed out that resolution switching is possible,  but generally
should be avoided. In two cases a resolution switch seems useful:
(1)  to show a Low-resolution picture from a program  running  in
Medium  and (2) to show text in Medium resolution from a  program
running  in Low.  If you switched from Low to Medium  resolution,
graphic commands are restricted to 'Low'  coordinates,  i.e.  the
left part of the Medium screen. But you can RC_COPY from the left
half  to the right half,  so it is possible to draw on  the  full
Medium screen after all.

SETCOLOR and VSETCOLOR

 There are several ways to determine the colour that will be used
by certain commands:

     COLOR colour    ! colour used by most graphic commands
     DEFFILL colour  ! colour used by (POLY)FILL, PBOX, PCIRCLE,
                         PELLIPSE
     DEFMARK colour  ! colour used by POLYMARK
     DEFTEXT colour  ! colour used by TEXT

 With the commands COLOR, DEFFILL, DEFMARK and DEFTEXT you choose
the colour with a VDI colour-index (0-3 in Medium resolution,  0-
15 in Low resolution).  You can change the colour that's assigned
to a VDI colour-index with SETCOLOR,  but unfortunately  SETCOLOR
uses a different table:

VDI colour-index  : 0  1 2  3  4  5  6  7  8  9 10 11 12 13 14 15
SETCOLOR (Low rez): 0 15 1  2  4  6  3  5  7  8  9 10 12 14 11 13
SETCOLOR (Med rez): 0  3 1  2

 From this table it follows you would have to use  SETCOLOR-index
2 to change VDI colour-index 3:

     SETCOLOR 2,r,g,b
     COLOR 3             ! use colour &Hrgb for graphics

 This  is not a bug,  but a consequence of two different  colour-
tables that are used by GEM and GEMDOS.  By the way,  all  Line-A
commands use the SETCOLOR-table (hardware registers)!

 At  first sight VSETCOLOR looks like an ideal solution  to  this
problem:

     VSETCOLOR index,r,g,b
     COLOR index         ! use colour &Hrgb for graphics

 This index is the VDI colour-index,  so you would use 'VSETCOLOR
2,r,g,b'  in  order to change VDI colour-index  2.  Sounds  quite
logical,   doesn't  it?   Unfortunately  VSETCOLOR  has  its  own
peculiarities, as you can read in the next paragraph ('VSETCOLOR-
bug').

 In High resolution you can invert the screen-colours with:

     VSETCOLOR 0,0       ! reverse High-screen (black background)
     VSETCOLOR 1,0       ! normal High-screen (black letters)

 An  inverted screen is perhaps slightly less suitable for  text,
but graphics look superb.

 In  Medium resolution text definitely looks better on a  reverse
screen:

     VSETCOLOR 0,0,0,0   ! black background
     VSETCOLOR 1,7,7,7   ! white letters

 Yellow  letters on a black background also look nice  in  Medium
resolution.

 VDI colour-index 0 (also SETCOLOR-index 0) determines the colour
of the background.  This index also determines the colour of  the
border  on  your colour monitor.  This means you can  change  the
border-colour,  although you can't draw or PRINT on the border of
your colour monitor.

    VSETCOLOR 0,r,g,b    ! change colour of background

 The  colour of all PRINTed text on the TOS-screen is  determined
by VDI colour-index 1,  unless you use the 'Esc b' command  (read
the paragraph 'PRINT' in chapter 9 again if your long-term memory
is too short):

     VSETCOLOR 1,r,g,b   ! change colour of all PRINTed text

 The SETCOLOR-index of the the PRINT-colour (VDI colour-index  1)
is easy to remember,  because all bits have to be 1. Therefore we
have  SETCOLOR-index  &X1 (decimal 1) in  High  resolution,  &X11
(decimal 3) in Medium and &X1111 (decimal 15) in Low.

VSETCOLOR-bug

 If you like, you can use the hexadecimal 3-nibble mix-value with
VSETCOLOR instead of the three separate values:

     VSETCOLOR index,&Hrgb    ! hexadecimal mix-value
     VSETCOLOR index,r,g,b    ! three separate values

 But you won't like it at all,  because the hexadecimal mix-value
is corrupted by GFA-Basic:  the r- and b-nibble are swapped.  You
could correct this yourself, but I can't recommend this:

     VSETCOLOR index,&Hbgr  ! becomes &Hrgb (correct the GFA-bug)

 GFA-Basic  3.5  (for the STE) has another surprise  if  you  use
VSETCOLOR  on a regular ST (not an STE).  The value of the  three
colour-bytes is halved:

     VSETCOLOR 0,7,6,4   ! &H764 on a STE, but becomes &H332 on
                               an ST

 Perhaps  this  is not a bug after all.  On an STE  you  can  use
values  0-15  for  each colour-nibble (16*16*16  =  4096  colours
possible),  while  the  ST  allows values 0-7 (for  8*8*8  =  512
different  colours).  But it makes life rather difficult  if  you
write  a  program that's supposed to run on any ST/STE  with  any
GFA-Basic version (3.0x or 3.5). I don't even want to think about
the TT.  Perhaps it's better to return to the despised  SETCOLOR-
command  in spite of the confusing colour-table.  SETCOLOR  works
fine  on  my  ST,  and the  hexadecimal  mix-value  also  behaves
properly:

     SETCOLOR 0,7,6,4    ! stays &H764 on my ST (what happens on
                               an STE?)
     SETCOLOR 0,&H764    ! stays &H764 also (no unwanted nibble-
                              swapping)

Palette

 Before  changing  colours,  you should always save  the  current
palette. And do restore the old palette before the user exits the
program.  I really hate programs that return to a pink or  yellow
desktop.  You can store the palette either in an integer array or
in a string. In both cases you need XBIOS 7 (Setcolor):

     DIM palet%(15)
     FOR i=0 TO 15
       palet%(i)=XBIOS(7,i,-1)               ! array-method
     NEXT i
     '
     FOR i=0 TO 15
       palet$=palet$+MKI$(XBIOS(7,i,-1))     ! string-method
     NEXT i

 The string-method is compatible with Degas. Restore (or install)
a  palette  with  XBIOS 7 for the array-method or  with  XBIOS  6
(Setpalette) for the string-method:

     FOR i=0 TO 15
       ~XBIOS(7,i,palet%(i))                 ! array-method
     NEXT i
     '
     ~XBIOS(6,L:V:palet$)                    ! string-method

 You can examine the rgb-value of a certain colour-index with:

     rgb$=RIGHT$(HEX$(XBIOS(7,index,-1)),3)  ! use SETCOLOR-
                                                  index!

DEFMARK

 The point as mark-symbol (No. 1) cannot be enlarged. Other mark-
symbols  can be enlarged,  but all lines in the symbol  retain  a
width of one pixel. The size of a symbol must be a multiple of 11
plus 6:  0,  17,  28,  39,  50. For a value in between, the prior
allowed size is chosen. Perhaps there is some magic hidden in the
allowed sizes, or am I missing something?

DEFFILL

 If you haven't defined your own Fill-pattern,  the  Atari-symbol
will  be used after DEFFILL 1,4,x.  The desktop  Fill-pattern  is
DEFFILL 1,2,4.

 The Fill-pattern string can consist of 16, 32 or 64 words (MKI$-
format). Word 1 to 16 is needed for bitplane 0 (High resolution),
word  17 to 32 for bitplane 1 (Medium resolution) and word 33  to
64  for  the  bitplanes  2  and  3  (Low  resolution).   In   all
resolutions,  the pattern occupies a rectangle of 16x16 pixels on
the screen.  The same 16x16 rectangle is also used for the mouse-
cursor and sprites.  You can always use a Fill-pattern in a lower
resolution,  e.g. a High-pattern in Medium or Low resolution, but
not the other way around.  There's gold in them thar  Fills.  You
could surprise the user with a bomb-pattern:

     RESTORE bomb.fill
     FOR i=1 TO 16
       READ pat$
       pat%=VAL("&X"+pat$)
       fill$=fill$+MKI$(pat%)
     NEXT i
     bomb.fill:
     DATA 0000011000000000
     DATA 0010100100000000
     DATA 0000000010000000
     DATA 0100100001000000
     DATA 0001000111110000
     DATA 0000000111110000
     DATA 0000011111111100
     DATA 0000111111111110
     DATA 0000110111111110
     DATA 0001111111111111
     DATA 0001111111101111
     DATA 0000111111101110
     DATA 0000111111011110
     DATA 0000011111111100
     DATA 0000001111111000
     DATA 0000000011100000

 Be  careful,  a screen filled with this pattern might provoke  a
heart-attack. If it does, you should blame the DEFFILL, not me.

 Many  Fill-patterns are available as files.  You can  use  these
with something like this:

     bytes=32                           ! 32 bytes for High res
     olution
     ' *** load Fill-pattern (32 bytes for High resolution) here
     INLINE fill1%,32
     pattern$=STRING$(bytes,0)          ! room for Fill-pattern
     BMOVE fill1%,V:pattern$,bytes      ! copy Fill-pattern
     DEFFILL ,pattern$                  ! activate Fill-pattern

 FILLing a screen with a pattern takes some time,  especially  in
High  resolution.  If you have to fill an area with an  irregular
border,  you'll  have  to  use  the  slow  FILL-command,  but  in
rectangular areas you should use the fast PBOX- or ARECT-command:

     DEFFILL colour,fill$               ! activate Fill-pattern
     BOUNDARY 0                         ! no borders
     PBOX 0,0,639,399                   ! for High res screen
     '
     ACLIP 1,0,0,639,399
     ARECT 0,0,639,399,1,0,fill%,15     ! altern. Line-A command
     ACLIP 0,0,0,639,399

 The Line-A method can be used in High resolution only, the PBOX-
method works in any resolution.

DEFLINE

 After 'DEFLINE ,n' all horizontal lines have a width of n pixels
(n should be odd),  except in Medium resolution.  I have  trouble
counting  the pixels in Medium resolution.  I think the width  of
horizontal lines is:

         n :   1 3 5 7 9
     width :   1 1 3 3 5 etc.

 Is this documented anywhere? If n is larger than 1, all vertical
lines are n+2 pixels wide!

 You  define  your own Line-patterns by using a  negative  16-bit
value   (from   -&X1  to  -&X1111111111111111).   Each  set   bit
corresponds  with a pixel in the Line-pattern (High  resolution).
The  highest bit (15) corresponds with the leftmost pixel of  the
pattern.  Don't  get confused if the editor changes the  negative
binary number you entered as a pattern. The editor uses a special
notation  for  negative  binary  numbers.   GFA-Basic  represents
integer  numbers  as  binary  strings  of  32  bits.   The   most
significant bit (31) determines the sign of the integer.  If this
bit is 0,  the remaining 31 bits represent an "ordinary" positive
number.  But if the most significant bit is 1, the remainder is a
negative  number in 'two's complement' notation.  I won't try  to
explain that.  In any case,  the next time you type -&X111 and  a
friend  is  watching you,  don't blink your  eyes,  but  casually
remark "of course the editor converts this into two's  complement
notation".

 After  'DEFLINE ,,2,2' you'll discover that the rounded  end  of
the line extends beyond the coordinates of the actual  line.  The
rounded end is created by drawing a filled circle with the centre
at the end of the line. No bug, just something to remember.

DEFTEXT

 You change the size of TEXT-letters with:

     DEFTEXT ,,,size

 Increasing  the size-variable does not always result  in  larger
letters:

     size
       3       barely readable in High resolution
       4       6x6 systemfont (icon-text)
       6       8x8 systemfont
     7-12      progressive magnifications of 8x8 systemfont
      13       8x16 systemfont
     14-26     progressive magnifications of 8x16 systemfont
     27-32     always size 26

 Text  with size=13 has almost the same height as  with  size=10,
but  the letters are much narrower.  Letters with size 11 and  12
are actually larger than letters with size 13.  Due to a  VDI-bug
sizes larger than 26 are converted to 26.

 In some publications you can read about 'shadowed text' (style =
32),  but unfortunately our GEM doesn't know this style.  You can
even find the mask for shadowed text with WORD{L~A+92},  but it's
0. For small letters you get a shadow-like effect this way:

     DEFTEXT 1,16,angle,13
     TEXT x,y,text$
     GRAPHMODE 2
     DEFTEXT ,17
     TEXT x,y,text$

 For  larger  letters (size > 20) you get a 3D-effect  with  this
method.

 I  never succeeded in finding the current text-style (useful  in
Procedure:   restore   original  style  later)  with  VDISYS   38
(vqt_attributes). Either a bug in GEM or my mistake. I don't want
to know, because the easy way is:

     txt.style=WORD{L~A+90}

 With DEFTEXT you can set the height of TEXT-letters (in pixels).
A  letter occupies more space though,  determined by the  letter-
box:

                    letter-height  letter-box     system-font
     DEFTEXT ,,,4         4          6 x 6        icon
     DEFTEXT ,,,6         6          8 x 8        Medium/Low res
     DEFTEXT ,,,13       13          8 x 16       High res

 The  letter-height is the distance from Descent-Line to  Ascent-
Line,  but  the Bottom-Line and Top-Line lie at least  one  pixel
lower/higher.  The height of the letter-box is the distance  from
Bottom-Line to Top-Line.  Most letters rest on the Base-Line, but
letters with a descender (g,j,p,  etc.) rest on the Descent-Line.
The  top of lowercase letters like a or c touches the  Half-Line.
If  you  are  still  with me,  from top to  bottom  we  have  the
following  lines  (the  letters  'I' and 'p'  are  shown  in  the
example, but the scale is wrong):

Top-Line            -------------------              -
Ascent-Line         ---*****-----------    -         |
                         *                 |         |
Half-Line           -----*------****---    |         |
                         *      *  *       |letter-  |letter-box
Base-Line           ---*****----****---    |height   |height
                                *          |         |
Descent-Line        ------------*------    -         |
Bottom-Line         -------------------              -

 Drop me a line if you don't understand this.

 DEFTEXT   won't  affect  the  text-style  used  by   ALERT   and
FILESELECT.  If  you really would like to be able to change  that
text-style, you need VDISYS 106 (vst_effects):

     CONTRL(1)=0
     CONTRL(3)=1
     CONTRL(6)=1
     INTIN(0)=style
     VDISYS 106

 Outlined  letters  (style-bit  4 set)  are  broader  than  other
letters, so you'll probably have to adjust the Alert-box width by
adding some (dummy) spaces.

 If  you  PRINT text in a window,  GFA actually  uses  the  TEXT-
command.  This means that DEFTEXT has the same effect on PRINT as
on  TEXT.  On  the  TOS-screen (not in a  window)  PRINT  is  not
influenced by DEFTEXT (see paragraph 'PRINT' in chapter 9).

GRAPHMODE

 Imagine  you're about to show the letter 'T' on the screen  with
TEXT.  I'll  assume the background-colour is white and the  text-
colour is black. TEXT grabs the letter 'T' from the current font-
table in the form of a white rectangle (letter-box) with a  black
'T' in it.  What will happen when TEXT puts the rectangle on  the
screen depends on GRAPHMODE and the background:

     GRAPHMODE 1 (Replace-mode)
     The background is completely ignored.  The letter-box is put
     on the screen,  covering anything under the box,  so  you'll
     allways see a black 'T' on a white rectangle.

     GRAPHMODE 2 (Transparent-mode)
     Only  the  black  pixels in the letter-box are  put  on  the
     screen. On a white background the result will be the same as
     with  GRAPHMODE 1.  But on a black background you  won't  be
     able to see the black 'T'.

     GRAPHMODE 3 (Xor-mode)
     The letter-box is 'Xorred' with the background.  Each  pixel
     of  the letter-box is compared with the corresponding  pixel
     of  the background.  If both are the same,  the result is  a
     white pixel.  If they are different,  the result is a  black
     pixel.  This means you can always read the letter,  whatever
     the  background.  But the main advantage of the Xor-mode  is
     that  you get the original background back if you 'Xor'  the
     same  rectangle  twice  on  the  same  spot.  This  mode  is
     therefore useful if you will be moving the 'T' around on the
     screen.
     GRAPHMODE 4 (Reverse Transparent-mode)
     First the letter-box is reversed, so we get a white 'T' on a
     black  rectangle.  Then  GRAPHMODE  2 is  used  to  put  the
     reversed letter-box on the screen.

 If you draw a rectangle with BOX in GRAPHMODE 3 (Xor-mode),  the
pixel in the left upper corner is not drawn.  Actually this pixel
is  drawn  twice,  and  in  GRAPHMODE  3  this  means  the  pixel
disappears. Use PLOT to draw this pixel:

     GRAPHMODE 3
     BOX x1,y1,x2,y2          ! draw the rectangle
     PLOT x1,y1               ! and fill the gap

 With  PBOX  in GRAPHMODE 3 you'll also get trouble in  the  same
corner. Avoid this by using the command 'BOUNDARY 0' first:

     GRAPHMODE 3
     BOUNDARY 0               ! no borders
     PBOX 50,50,100,100       ! draw the rectangle

 As  mentioned before,  GRAPHMODE 3 is especially useful  if  you
make a temporary drawing.  Draw the same picture a second time to
restore the original screen. In the following example this method
is used to draw a line:

     x=50                             ! start line at (50,50)
     y=50
     GRAPHMODE 3
     DEFMOUSE 0
     SHOWM
     MOUSE x1,y1,k
     REPEAT                           ! main loop
       LINE x,y,x1,y1                 ! draw line
       REPEAT
         MOUSE x2,y2,k
       UNTIL x2<>x1 OR y2<>y1 OR k>0  ! mouse moved
       LINE x,y,x1,y1                 ! erase line
       x1=x2
       y1=y2
     UNTIL k>0                        ! mouse-click: we're ready
     GRAPHMODE 1
     LINE x,y,x2,y2                   ! this is the final line

 You could also use the 'GRAPHMODE 3'-method for  animation,  but
the  XBIOS  5  (Setscreen)  method  is  more  suitable  (see  the
paragraph 'Animation').

 Don't try to draw in GRAPHMODE 3 with a linewidth greater than 1
pixel.  GEM  will surprise you with some modern art if you  can't
resist the temptation.

 If you want to confirm a particular choice of the user,  you can
invert the relevant part of the screen:

     GRAPHMODE 3
     DEFFILL color,1         ! contrasting colour (usually black)
     BOUNDARY 0
     PBOX x1,y1,x2,y2

 Do this once more to restore the original screen.

 You can 'grey out' an unavailable option on the screen with:

     GRAPHMODE 3
     DEFFILL color,2,2             ! same colour as used in box
     BOUNDARY 0
     PBOX x1,y1,x2,y2

 Do this once more to restore the original screen.

 The entire (High resolution) screen can be dimmed with:

     SGET dimmer.screen$
     GRAPHMODE 4
     DEFFILL 1,2,4
     BOUNDARY 0
     PBOX 0,0,639,399

 This  could be useful if the user has to wait during some  time-
consuming operation (like file-loading). Restore the screen with:

     SPUT dimmer.screen$

 After  using GRAPHMODE you should always return to  the  default
situation with 'GRAPHMODE 1'.

PLOT and DRAW

 You can use both 'PLOT x,y' and 'DRAW x,y' to set a point on the
screen. The size of the point can be changed:

     DEFLINE ,size,2,2        ! change size of points

 But the shapes you'll see don't look like points anymore, due to
the  same problem as described in the  paragraph  'DEFLINE'.  Use
PCIRCLE for proper fat points.

PLOT-bug

 PLOT doesn't work after 'DEFLINE ,size' if size > 1 (GFA-bug?).

PCIRCLE-bug

 With CLIP on,  a PCIRCLE touching the upper screen-border is not
filled properly in High resolution:

     CLIP 0,0,640,400         ! default with interpreter anyway
     PCIRCLE 0,0,50

 I  don't know if we should blame GFA or GEM for not filling  the
two top-lines in the circle.  With FILL you can correct this bug,
in this case by following the PCIRCLE-command with:

     DEFFILL 1,1
     FILL 0,0                 ! now the circle is properly filled

CURVE

 With the command CURVE you can draw a Bezier-curve:

     CURVE x1,y1,x2,y2,x3,y3,x4,y4

 The  Bezier-curve  starts at (x1,y1) and ends  at  (x4,y4).  The
other two points act like little magnets.  You can also use  this
command  to draw a 'normal' curve between two points  by  letting
the points (x3,y3) and (x4,y4) coincide. Try the following to see
what I mean:

     GRAPHMODE 3
     MOUSE x2,y2,k
     REPEAT
       CURVE 10,100,x2,y2,110,100,110,100    ! draw curve
       REPEAT
         MOUSE x,y,k
       UNTIL x<>x2 OR y<>y2
       CURVE 10,100,x2,y2,110,100,110,100    ! erase curve
       x2=x
       y2=y
     UNTIL k<>0                              ! exit after mouse

TEXT

 The coordinates used with TEXT determine the start of the  Base-
Line  of the text (see paragraph 'DEFTEXT').  The  descenders  of
letters like 'g',  'j',  and 'p' lie below the Base-Line. This is
especially  important,  not to say frustrating,  if you use  TEXT
with  an  angle  of 90,  180 or 270  degrees.  The  text  rotates
anticlockwise around the TEXT-coordinates!

 You can use TEXT to print "digital" numbers (ASCII-code 16-25):

     number$="24379"
     FOR i=1 TO LEN(number$)
       dig$=dig$+CHR$(BCLR(ASC(MID$(number$,i,1)),5))
     NEXT i
     TEXT x,y,dig$

SPRITE

 You could design and save sprites in vitro with one of the  many
Sprite-editors that are available. But it's also easy to create a
sprite in vivo in your GFA-program:

     RESTORE pattern.sprite1
     READ x,y,mode,msk.color,spr.color
     FOR i=1 TO 16
       READ msk$
       msk%=VAL("&X"+msk$)
       msk.pat$=msk.pat$+MKI$(msk%)
     NEXT i
     FOR i=1 TO 16
       READ spr$
       spr%=VAL("&X"+spr$)
       spr.pat$=spr.pat$+MKI$(spr%)
     NEXT i
     FOR i=1 TO 16
       pat$=pat$+MID$(msk.pat$,i*2-1,2)+MID$(spr.pat$,i*2-1,2)
     NEXT i
     s$=MKI$(x)+MKI$(y)+MKI$(mode)+MKI$(msk.color)
     s$=s$+MKI$(spr.color)+pat$
     '
     pattern.sprite1:
     ' *** x,y,mode(0=normal;-1=XOR),mask-colour,sprite-colour
     DATA 0,0,0,0,1
     ' *** mask-pattern (1 = pixel on , 0 = pixel off)
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     ' *** sprite-pattern
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000
     DATA 0000000000000000

 If  you copy this sprite you won't impress  anybody.  Switch  to
Overwrite-mode  in the GFA-editor and draw a nice  sprite-pattern
by  typing '1' for every pixel that should be visible.  The  mask
should  be  an  exact copy of the sprite-pattern if  you  need  a
transparant  sprite.  Making  the mask one pixel wider  than  the
sprite usually is a good idea. Leave the mask empty (all '0') and
the sprite will disappear behind objects on the screen.  Fill the
mask  with '1' and the 16x16 sprite will always  remain  visible.
Switch mask- and sprite-colour in the first DATA-line to create a
"reverse" sprite. Or use any SETCOLOR-index (!) that is available
in the current resolution.  In XOR-mode (same as GRAPHMODE 3) the
sprite is always visible whatever the background is.

 If you put a sprite on the screen, the background (16x16 pixels)
is temporarily saved. GFA automatically removes the old sprite if
you use new coordinates for your sprite:

     DO
       (...)
       VSYNC                  ! prevent blinking
       SPRITE s$,x,y          ! old sprite automatically removed
       (...)
     LOOP

 Using more than one sprite simultaneously,  it is essential  you
remove old sprites in reverse order yourself.  This is  necessary
because a sprite could overlap another sprite.  Removing the  top
sprite  first ensures that the original background will  reappear
after removing the last old sprite, e.g.:

     DO
       (...)
       SPRITE s2$             ! remove old sprites in reverse
                                         order...
       SPRITE s1$
       VSYNC                  ! prevent blinking
       SPRITE s1$,x1,y1       ! draw new sprites...
       SPRITE s2$,x2,y2
       (...)
     LOOP