<appendix>
<title>The &b09; Graphics Interface Module</title>
<para>
The Graphics Interface module provides a simple and convenient
way to access the color graphics and joystick functions of the
Dragon Computer from &b09; programs. The module is a program
written in assembly language and stored in a file called "GFX". It
can be loaded into memory using the OS-9 "LOAD" command prior to or
after called &b09;, or it will be automatically called by &b09;
the first time it is referenced in a program if the "GFX" file is
located in the execution ("CMDS") directory.
</para>
<para>
"GFX" is called using the &b09; "RUN" statement. The first
parameter passed is the name of the graphics function desired.
Other parameters are used to pass coordinates, color modes, etc.
</para>
<para>
The are two basic graphics modes: 4-color having 128 by 192
pixel resolution, and 2-color having 256 by 192 pixel resolution.
The display is treated as a 256 by 192 point grid with coordinates
0,0 in the lower left-hand corner. X (horizontal) coordinates in
either mode must be in the range of 0 to 255. An X-coordinate
greater than 255 will cause a run-time error. Y coordinates
(vertical) must be in the range of 0 to 191. A number greater than
191 will be replaced by 191. Some of the graphics functions require
or optionally accept a color mode which controls the foreground
color and color set. The mode and color codes are given in the
table on the next page.
</para>
<beginpage/>
<table frame="none">
 <title>Color Graphics Modes and Color Codes</title>
<tgroup cols="6">
<colspec colname="c1" colwidth="0.6in"/>
<colspec colname="c2" colwidth="0.4in"/>
<colspec colname="c3" colwidth="1in"/>
<colspec colname="c4" colwidth="1in"/>
<colspec colname="c5" colwidth="1in"/>
<colspec colname="c6" colwidth="1in"/>
<thead>
<row>
<entry morerows="1" namest="c2">Color Code</entry>
<entry align="center" namest="c3" nameend="c4">Two Color Format</entry>
<entry align="center" namest="c5" nameend="c6">Four Color Format</entry>
</row>
<row>
<entry namest="c3">Background</entry>
<entry namest="c4">Foreground</entry>
<entry namest="c5">Background</entry>
<entry namest="c6">Foreground</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="3" valign="middle">Color Set 1</entry>
<entry align="center">00</entry>
<entry align="left">Black</entry>
<entry align="left">Black</entry>
<entry align="left">Green</entry>
<entry align="left">Green</entry>
</row>
<row>
<entry align="center">01</entry>
<entry align="left">Black</entry>
<entry align="left">Green</entry>
<entry align="left">Green</entry>
<entry align="left">Yellow</entry>
</row>
<row>
<entry align="center">02</entry>
<entry namest="c5" align="left">Green</entry>
<entry align="left">Blue</entry>
</row>
<row rowsep="1">
<entry align="center">03</entry>
<entry namest="c5" align="left">Green</entry>
<entry align="left">Red</entry>
</row>
<row>
<entry morerows="3" valign="middle">Color Set 2</entry>
<entry align="center">04</entry>
<entry align="left">Black</entry>
<entry align="left">Black</entry>
<entry align="left">Buff</entry>
<entry align="left">Buff</entry>
</row>
<row>
<entry align="center" namest="c2">05</entry>
<entry align="left">Black</entry>
<entry align="left">Buff</entry>
<entry align="left">Buff</entry>
<entry align="left">Cyan</entry>
</row>
<row>
<entry align="center" namest="c2">06</entry>
<entry namest="c5" align="left">Buff</entry>
<entry align="left">Magenta</entry>
</row>
<row rowsep="1">
<entry align="center" namest="c2">07</entry>
<entry namest="c5" align="left">Buff</entry>
<entry align="left">Orange</entry>
</row>
<row>
<entry morerows="3" valign="middle">Color Set 3*</entry>
<entry align="center">08</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Black</entry>
</row>
<row>
<entry align="center" namest="c2">09</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Dark Green</entry>
</row>
<row>
<entry align="center" namest="c2">10</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Med. Green</entry>
</row>
<row rowsep="1">
<entry align="center" namest="c2">11</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Light Green</entry>
</row>
<row>
<entry morerows="3" valign="middle">Color Set 4*</entry>
<entry align="center">12</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Black</entry>
</row>
<row>
<entry align="center" namest="c2">13</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Green</entry>
</row>
<row>
<entry align="center" namest="c2">14</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Red</entry>
</row>
<row>
<entry align="center" namest="c2">15</entry>
<entry namest="c5" align="left">Black</entry>
<entry align="left">Buff</entry>
</row>
</tbody>
</tgroup>
</table>
<note>
<para>
Color Sets 3 and 4 are not available on PAL video system
(U.K. and European) models.
</para>
</note>
<bridgehead renderas="sect2">MODE</bridgehead>
<cmdsynopsis>
<command>RUN GFX("Mode",<replaceable>format,color</replaceable>)</command>
</cmdsynopsis>
<para>
MODE switches the screen from alphanumeric to graphics display mode,
and selects the screen mode and color mode. "Format" determines
between two-color (Format = 0), or four-color (Format = 1)
graphics modes. "Color" is the initial color code that specifies
the foreground color and color set.
</para>
<para>
This command must be given before aby other graphics command is
used. The first time MODE is called, it requests 6K bytres of memory
from OS-9 for use as the graphics display memory. MODE will return
an error if sufficient free memory is not available.
</para>
<para>
An example:
<programlisting>
RUN GFX("Mode",1,3)
</programlisting>
selects four-color mode graphics is used, and the initial
foreground color is red.
</para>
<bridgehead renderas="sect2">MOVE</bridgehead>
<cmdsynopsis>
<command>RUN GFX("Move",<replaceable>x,y</replaceable>)</command>
</cmdsynopsis>
<para>
MOVE positions the (invisible) graphics cursor to the specified
location without changing the display. X and Y are the coordinates
of the new position.
</para>
<para>
Example:
<programlisting>
RUN GFX("Move",0,0)
</programlisting>
This example positions the cursor in the lower left-hand corner.
</para>
<bridgehead renderas="sect2">COLOR</bridgehead>
<cmdsynopsis>
<command>RUN GFX("Color",<replaceable>color</replaceable>)</command>
</cmdsynopsis>
<para>
COLOR changes the current foreground color (and possibly the color
set). The current graphics mode and cursor position are not
changed. For example:
<programlisting>
RUN GFX("Color",0)
</programlisting>
changes the foreground color to green in four-color format (or
black in two-color format).
</para>
<bridgehead renderas="sect2">POINT</bridgehead>
<cmdsynopsis>
<command>RUN GFX("Point",<replaceable>x,y</replaceable>) or</command><sbr/>
<command>RUN GFX("Point",<replaceable>x,y,color</replaceable>)</command>
</cmdsynopsis>
<para>
POINT moves the graphics cursor to the specified X.Y coordinate and
sets the pixel at that coordinate to the current foreground color.
If the optional "Color" is specified, the current foreground color
is set to the given "Color". For example:
<programlisting>
RUN GFX("Point",0,192,1)
</programlisting>
Point moves the cursor to the upper left-hand corner and changes
the foreground color to green in two-color format, or it changes
the color to yellow in the four-color format.
</para>
<bridgehead renderas="sect2">CLEAR</bridgehead>
<cmdsynopsis>
<command>RUN GFX("Clear") or</command><sbr/>
<command>RUN GFX("Clear",<replaceable>color</replaceable>)</command>
</cmdsynopsis>
<para>
CLEAR resets all points on the screen to the background color, or
if the optional color is given presets the screen to that color.
The current graphics cursor is reset to (0,0).
</para>
<bridgehead renderas="sect2">LINE</bridgehead>
<cmdsynopsis>
<command>RUN GFX("Line",<replaceable>x2,y2</replaceable>)</command><sbr/>
<command>RUN GFX("Line",<replaceable>x2,y2,color</replaceable>)</command><sbr/>
<command>RUN GFX("Line",<replaceable>x1,y1,x2,y2</replaceable>)</command><sbr/>
<command>RUN GFX("Line",<replaceable>x1,y1,x2,y2,color</replaceable>)</command>
</cmdsynopsis>
<para>
LINE draw lines in various ways. If one coordinate is given, the
line will be drawn from the current graphics cursor position to the
coordinates specified. If two sets of coordinates are given, they
are used as the start and end points of the line. The line will be
drawn in the current foreground color unless a new color is given
as a parameter. After the line is drawn the graphics cursor will be
positioned at x2,y2. For example
<programlisting>
RUN GFX("Line",0,0,0,192)
</programlisting>
draws a line from (0,0) to (0,192).
<programlisting>
RUN GFX("line",24,65,2)
</programlisting>
draws a blue line (4-color mode) to point 24,65.
</para>
<bridgehead renderas="sect2">CIRCLE</bridgehead>
<cmdsynopsis>
<command>RUN GFX("Circle",<replaceable>radius</replaceable>)</command><sbr/>
<command>RUN GFX("Circle",<replaceable>radius,color</replaceable>)</command><sbr/>
<command>RUN GFX("Circle",<replaceable>x,y,radius</replaceable>)</command><sbr/>
<command>RUN GFX("Circle",<replaceable>x,y,radius,color</replaceable>)</command>
</cmdsynopsis>
<para>
CIRCLE draws a circle of the given radius. The current graphics
cursor position is assumed if no X,Y value is given. The current
foreground color is assumed if the Color parameter is not used.
The center of the circle must be on the screen.
</para>
<bridgehead renderas="sect2">ALPHA</bridgehead>
<cmdsynopsis>
<command>RUN GFX("Alpha")</command>
</cmdsynopsis>
<para>
Alpha is a quick convenient way of getting the screen back to
alphanumeric mode. When graphics mode is entered again, the screen
will show the previous unchanged graphics display.
</para>
<bridgehead renderas="sect2">QUIT</bridgehead>
<cmdsynopsis>
<command>RUN GFX("Quit")</command>
</cmdsynopsis>
<para>
QUIT switches the screen back to alpha mode and returns the 6K byte
graphics display memory to OS-9.
</para>
<bridgehead renderas="sect2">GLOC</bridgehead>
<cmdsynopsis>
<command>RUN GFX("Gloc",<replaceable>vdisp</replaceable>)</command>
</cmdsynopsis>
<para>
GLOC returns the address of the video display RAM as an integer number.
This address may be used in subsequent PEEK and POKE
operations to access the video display directly. GLOC can be used
to create special functions that are not available in the Graphics
Module.
</para>
<bridgehead renderas="sect2">GCOLR</bridgehead>
<cmdsynopsis>
<command>RUN GFX("Gcolr",<replaceable>color</replaceable>)</command><sbr/>
<command>RUN GFX("Gcolr",<replaceable>x,y,color</replaceable>)</command>
</cmdsynopsis>
<para>
GCOLR is used to read the color of the pixel at the current
graphics cursor position, or from the coordinates X,Y. The
parameter "Color" may be an integer or a byte variable in which the
color code is returned.
</para>
<bridgehead renderas="sect2">JOYSTK</bridgehead>
<cmdsynopsis>
<command>RUN GFX("Joystk",<replaceable>stick,fire,x,y</replaceable>)</command>
</cmdsynopsis>
<para>
JOYSTK returns the status of the specified joystick's Fire button,
and returns the X,Y position of the joystick. The Fire button may
be read as a BYTE, INTEGER, or a BOOLEAN value. Non-zero (TRUE)
means the button was pressed. The X,Y values returned may be BYTE
or INTEGER variables, and they will be in the range 0 to 63. The
Stick parameter may be BYTE or INTEGER, and should be 0 for
RIGHT, or 1 for LEFT, depending on whether the RIGHT or the LEFT
joystick is to be tested.
</para>
<para>
Example:
<programlisting>
RUN GRX("Joystk",1,leftfire,leftx,lefty)
</programlisting>
</para>
<bridgehead renderas="sect1">A Sample Graphics Program</bridgehead>
<para>
The program on the next page illustrates how the GFX module is
called and used. It creates an analog clock on the graphics
display.
</para>
<para>
<programlisting>
PROCEDURE clk
 0000      (* Simple Clock Simulator *)
 001C      DIM time(4),last(4),xx(3),yy(3):INTEGER
 0043      DIM x0,y0,radius,bkg:INTEGER
 0056      DIM i,j,x1,y1,x2,y2:INTEGER
 0071      DEG
 0073      bkg=0
 007A      x0=128
 0081      y0=96
 0088      radius=95
 008F      RUN GFX("MODE",1,bkg+1)
 00A5      RUN GFX("CLEAR")
 00B2      RUN GFX("CIRCLE",x0,y0,radius)
 00CF      FOR i=0 to 89 STEP 6
 00E4        x2=SIN(i)*radius
 00F4        y2=COS(i)*radius
 0104        x1=x2*.9
 0115        y1=y2*.9
 0126        j=MOD(i/30,3)+bkg+1
 013B        RUN GFX("LINE",x0+x1,y0+y1,x0+x2,y0+y2,j)
 016C        RUN GFX("LINE",x0-x1,y0-y1,x0-x2,y0-y2,j)
 019D        RUN GFX("LINE",x0+y1,y0-x1,x0+y2,y0-x2,j)
 01CE        RUN GFX("LINE",x0-y1,y0+x1,x0-y2,y0+x2,j)
 01FF      NEXT i
 020A      FOR i=1 TO 3
 021A        time(i)=0
 0225        xx(i)=x0
 0231        yy(i)=y0
 023D      NEXT i
 0248      LOOP
 024A        time$=DATE$
 0250        last=time
 0258        time(3)=VAL(MID$(time$,16,2))*6
 026E        time(2)=VAL(MID$(time$(13,2))*6
 0284        time(1)=MOD(VAL(MID$(time$,10,2))*30+time/2)/12,360)
 02A9        j=last(3)
 02B3        FOR i=3 TO 1 STEP -1
 02C9          IF i=3 OR j=0 OR ABS(time(i)-last(i+1))&lt;6 OR
               ABS(time(i)-j)&lt;6 THEN
 0300            RUN GFX("LINE",x0,y0,xx(i),yy(i),bkg)
 032B            xx(i)=x0+SIN(time(i))*radius*(.3+i*.2)
 035A            yy(i)=y0+COS(time(i))*radius*(.3+i*.2)
 0389            RUN GFX("LINE",x0,y0,xx(i),yy(i),bkg+i)
 03B7          ENDIF
 03B9        NEXT i
 03C4        WHILE time$=DATE$ DO
 03CF        ENDWHILE
 03D3      ENDLOOP
</programlisting>
</para>

</appendix>