<appendix id="video-display">
<title>VDG Display System Functions</title>

<section>
<title>The Video Display Generator</title>
<para>
NitrOS-9 allows the VDG display to be used in
alphanumeric, semigraphic, and graphics modes. There are many
built-in functions to control the display, which are activated by
used of various ASCII control character. Thus, these functions are
available for use by software written in any language using standard
output statements (such as &quot;PRINT&quot; in BASIC). The Color Computer's Basic09
language has a Graphics Interface Module that can automatically
generate these codes using Basic09 RUN statements.
</para>
<para>
The display system has two display modes: Alphanumeric
(&quot;Alpha&quot;) mode and Graphics mode. The Alphanumeric mode also
includes &quot;semigraphic&quot; box-graphics. The Color Computer's display
system uses a separate - memory area for each display mode so
operations on the Alpha display do not affect the Graphics display,
and visa-versa. Either display can be selected under software
control.
</para>
<para>
8-bit characters sent to the display system are interpreted
according to their numerical value, as shown in the chart below.
</para>

<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="2in"/>
<colspec colwidth="3in"/>
<thead>
<row>
<entry>Character Range (Hex)</entry>
<entry>Mode/Used For</entry>
</row>
</thead>
<tbody>
<row>
<entry>00 - 0E</entry>
<entry>Alpha Mode - cursor and screen control</entry>
</row>
<row>
<entry>0F - 1B</entry>
<entry>Graphics Mode - drawing and screen control</entry>
</row>
<row>
<entry>1C - 20</entry>
<entry>Not used</entry>
</row>
<row>
<entry>20 - SF</entry>
<entry>Alpha Mode - upper case characters</entry>
</row>
<row>
<entry>60 - 7F</entry>
<entry>Alpha Mode - lower case characters</entry>
</row>
<row>
<entry>80 - FF</entry>
<entry>Alpha Mode - Semigraphic patterns</entry>
</row>
</tbody>
</tgroup>
</informaltable>


<para>
The graphics and alphanumeric functions are handled by the OS-9
device driver module called &quot;CCIO&quot;.
</para>
</section>
<section>
<title>Alpha Mode Display</title>
<para>
This is the &quot;standard&quot; operational mode. It is used to display
alphanumeric characters and semigraphic box graphics, and simulates
the operation of a typical computer terminal with functions for
scrolling, cursor positioning, clear screen, line delete, etc.
</para>
<para>
Each 8-bit character is assumed to be an ASCII character and is
displayed if its high order bit (sign bit) is cleared. Lower case
letters are displayed in reverse video. If the high order bit of
the character is set it is assumed to be a &quot;Semigraphic 6&quot; graphics
box. See the Color Computer manual for an explanation of semigraphics
functions.
</para>

<table frame="none">
<title>Alpha Mode Command Codes</title>
<tgroup cols="2">
<colspec colwidth="0.6in"/>
<colspec colwidth="4in"/>
<thead>
<row rowsep="1">
<entry>Control Code</entry>
<entry>Name/Function</entry>
</row>
</thead>
<tbody>
<row>
<entry>01</entry>
<entry>HOME - return cursor to upper left hand corner of screen</entry>
</row>
<row>
<entry>02</entry>
<entry>CURSOR XY - move cursor to character X of line Y. The
binary value minus 32 of the two characters following 
the control character are used as the X and Y 
coordinates. For example, to position the cursor at character 5 of line 10,
you must give X=37 and Y42</entry>
</row>
<row>
<entry>03</entry>
<entry>ERASE LINE - erases all characters on the cursor's line.</entry>
</row>
<row>
<entry>06</entry>
<entry>CURSOR RIGHT - move cursor right one character position</entry>
</row>
<row>
<entry>08</entry>
<entry>CURSOR LEFT - move cursor left one character position</entry>
</row>
<row>
<entry>09</entry>
<entry>CURSOR UP - move cursor up one line</entry>
</row>
<row>
<entry>10</entry>
<entry>CURSOR DOWN (linefeed) move cursor down one line</entry>
</row>
<row>
<entry>12</entry>
<entry>CLEAR SCREEN - erase entire screen and home cursor</entry>
</row>
<row>
<entry>13</entry>
<entry>RETURN - return cursor to leftmost character of line</entry>
</row>
<row>

<entry>14</entry>
<entry>DISPLAY ALPHA - switch screen from graphic mode to alpha
numeric mode</entry>
</row>
</tbody>
</tgroup>
</table>

</section>
<section>
<title>Graphics Mode Display</title>
<para>
This mode is used to display high-resolution 2- or 4-color
graphics, and it includes commands to: set color; plot and erase
individual points; draw and erase lines; position the graphics
cursor; and draw circles.
</para>
<para>
The DISPLAY GRAPHICS command must be executed before any other
graphics mode command is used. It causes the graphics screen to be
displayed and sets a current display format and color. The Li.u.t
time the DISPLAY GRAPHICS command is given, a 6144 byte display
memory is allocated by OS-9, so there must be at least this much
continuous free memory available (the OS-9 &quot;MFREE&quot; command can be
used to check free memory). This memory is retained until the END
GRAPHICS command is given, even if the program that initiated
Graphics mode finishes, so it important that the END GRAPHICS
command be used to give up the display memory when Graphics mode is
no longer needed.
</para>
<para>
Graphics mode supports two basic formats: Two-Color which has
256 horizontal by 192 vertical points (G6R mode); and Four Color
which has 128 horizontal by 192 vertical points (G6C mode). Two
color sets are available in either mode. Regardless of the
resolution of the format selected, all Graphics mode commands use a
256 by 192 point coordinate system. The X and Y coordinates are
always positive numbers which assume that point 0,0 is the lower
lefthand corner of the screen.
</para>
<para>
An invisible Graphics Cursor is used by many command to reduce
the amount of output required to generate graphics. This cursor can
be explicitly set to any point using the SET GRAPHICS CURSOR
command. Also, all other commands that include X,Y coordinates
(such as SET POINT) move the graphics cursor to the specified
position.
</para>
<table frame="none">
<title>Graphics Mode Selection Codes</title>
<tgroup cols="2">
<colspec colwidth="1in"/>
<colspec colwidth="3in"/>
<thead>
<row rowsep="1">
<entry>Code</entry>
<entry>Format</entry>
</row>
</thead>
<tbody>
<row>
<entry>00</entry>
<entry>256 x 192 two-color graphics</entry>
</row>
<row>
<entry>01</entry>
<entry>128 x 192 four-color graphics</entry>
</row>
</tbody>
</tgroup>
</table>


<table frame="none">
 <title>Color Set and Current Foreground Color Selection Codes</title>
<tgroup cols="6">
<colspec colname="c1" colwidth="0.5in"/>
<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 align="center" namest="c3" nameend="c4">Two Color Format</entry>
<entry align="center" namest="c5" nameend="c6">Four Color Format</entry>
</row>
<row>
<entry align="center" namest="c2">Char</entry>
<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>

<para>
* Color sets 3 and 4 not available on PAL video system (European)
models. These color sets work only with NTSC (U.S., Canada, Japan)
models.
</para>

<table frame="none">
 <title>Graphics Mode Control Commands</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="0.8in"/>
<colspec colname="c1" colwidth="4in"/>
<thead>
<row rowsep="1">
<entry>Control Code</entry>
<entry>Name/Function</entry>
</row>
</thead>
<tbody>
<row>
<entry>15</entry>
<entry>DISPLAY GRAPHICS - switches screen to graphics mode.
This command must be given before any other
graphics commands are used. The first time this command
is given, a 6K byte display buffer is assigned. If 6K of
contiguous memory is not available an error is returned.
This command is followed by two characters which specify
the graphics mode and current color/color set, respectively.</entry>
</row>
<row>
<entry>16</entry>
<entry>PRESET SCREEN - presets entire screen to color code
passed in next character.</entry>
</row>
<row>
<entry>17</entry>
<entry>SET COLOR - selects foreground color (and color set)
passed in next character, but does not change graphics
mode.</entry>
</row>
<row>
<entry>18</entry>
<entry>QUIT GRAPHICS - disables graphics mode and returns the
6K byte graphics memory area to OS-9 for other use, and
switches to alpha mode.</entry>
</row>
<row>
<entry>19</entry>
<entry>ERASE GRAPHICS - erases all points to background color
and homes graphics cursor to the desired position.</entry>
</row>
<row>
<entry>20</entry>
<entry>HOME GRAPHICS CURSOR - moves graphics cursor to coordinates
0,0 (lower left hand corner).</entry>
</row>
<row>
<entry>21</entry>
<entry>SET GRAPHICS CURSOR - moves graphics cursor to given
coordinates X,Y. The binary value of the two characters that immediately
follow are used as the X and Y values, respectively.</entry>
</row>
<row>
<entry>22</entry>
<entry>DRAW LINE - draws a line of the current foreground
color from the current graphics cursor position to the
given X,Y coordinates. The binary value of the two
characters that immediately follow are used as the X
and Y values, respectively. The graphics cursor is
moved to the end point of the line.</entry>
</row>
<row>
<entry>23</entry>
<entry>ERASE LINE - same as DRAW LINE except the line is
&quot;drawn&quot; in the current background color, thus erasing
the line.</entry>
</row>
<row>
<entry>24</entry>
<entry>SET POINT - sets the pixel-at point X,Y to the current
foreground color. The binary value of the two
characters that immediately follow are used as the x
and Y values, respectively. The graphics cursor is
moved to the point Set.</entry>
</row>
<row>
<entry>25</entry>
<entry>ERASE POINT - same as DRAW POINT except the point is
&quot;drawn&quot; in the current background color, thus erasing
the point.</entry>
</row>
<row>
<entry>26</entry>
<entry>DRAW CIRCLE - draws a circle of the current foreground
color with its center at the current graphics cursor
position using a radius R which is obtained using the
binary value of the next character. The graphics
cursor position is not affected by this command.</entry>
</row>
</tbody>
</tgroup>
</table>

</section>
<section>
<title>Get Status Commands</title>
<para>
The Color Computer I/O driver includes OS-9 Get Status
commands that return the display status and joystick values,
respectively. These are accessable via the Basic09 Graphics
Interface Module, or by the assembly language  system calls listed
below:
</para>
<para>
GET DISPLAY STATUS:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="2in"/>
<colspec colwidth="3in"/>
<tbody>
<row>
<entry>Calling Format</entry>
<entry><literallayout class="monospaced">lda #1        (path number)
ldb #SS.DStat (Getstat code $12)
os9 I$GSTT     call OS-9</literallayout></entry>
</row>
<row>
<entry>Passed</entry>
<entry>nothing</entry>
</row>
<row>
<entry>Returns</entry>
<entry><literallayout>X = address of graphics display memory
Y = graphics cursor address x=MSB y =LSB
A = color code of pixel at cursor address</literallayout></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
GET JOYSTICK VALUES:
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="2in"/>
<colspec colwidth="3in"/>
<tbody>
<row>
<entry>Calling Format</entry>
<entry><literallayout class="monospaced">lda #1        (path number)
ldb #SS.Joy   (Getstat code $13)
os9 I$GSTT     call OS-9</literallayout></entry>
</row>
<row>
<entry>Passed</entry>
<entry>X = 0 for right joystick; 1 for left joystick</entry>
</row>
<row>
<entry>Returns</entry>
<entry><literallayout>X = selected joystick x value (0-63)
Y = selected joystick y value (0-63)
A = $FF if fire button on; $00 if off</literallayout></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<table frame="none">
<title>Display Control Codes Condensed Summary</title>
<tgroup cols="4">
<colspec colwidth="0.9in"/>
<colspec colwidth="0.9in"/>
<colspec colwidth="0.9in"/>
<colspec colwidth="2.5in"/>
<thead>
<row rowsep="1">
<entry>1st Byte</entry>
<entry>2nd Byte</entry>
<entry>3rd Byte</entry>
<entry>Function</entry>
</row>
</thead>
<tbody>
<row>
<entry>00</entry>
<entry></entry>
<entry></entry>
<entry>Null</entry>
</row>
<row>
<entry>01</entry>
<entry></entry>
<entry></entry>
<entry>Home Alpha Cursor</entry>
</row>
<row>
<entry>02</entry>
<entry>Column+32</entry>
<entry>Row+32</entry>
<entry>Position Alpha Cursor</entry>
</row>
<row>
<entry>03</entry>
<entry></entry>
<entry></entry>
<entry>Erase Line</entry>
</row>
<row>
<entry>06</entry>
<entry></entry>
<entry></entry>
<entry>Cursor Right</entry>
</row>
<row>
<entry>08</entry>
<entry></entry>
<entry></entry>
<entry>Cursor Left</entry>
</row>
<row>
<entry>09</entry>
<entry></entry>
<entry></entry>
<entry>Cursor Up</entry>
</row>
<row>
<entry>10</entry>
<entry></entry>
<entry></entry>
<entry>Cursor Down</entry>
</row>
<row>
<entry>12</entry>
<entry></entry>
<entry></entry>
<entry>Clear Screen</entry>
</row>
<row>
<entry>13</entry>
<entry></entry>
<entry></entry>
<entry>Carriage Return</entry>
</row>
<row>
<entry>14</entry>
<entry></entry>
<entry></entry>
<entry>Select Alpha Mode</entry>
</row>
<row>
<entry>15</entry>
<entry>Mode</entry>
<entry>Color Code</entry>
<entry>Select Graphics Mode</entry>
</row>
<row>
<entry>16</entry>
<entry>Color Code</entry>
<entry></entry>
<entry>Preset Screen</entry>
</row>
<row>
<entry>17</entry>
<entry>Color Code</entry>
<entry></entry>
<entry>Select Color</entry>
</row>
<row>
<entry>18</entry>
<entry></entry>
<entry>Quit Graphics Mode</entry>
</row>
<row>
<entry>19</entry>
<entry></entry>
<entry>Erase Screen</entry>
</row>
<row>
<entry>20</entry>
<entry></entry>
<entry>Home Graphics Cursor</entry>
</row>
<row>
<entry>21</entry>
<entry>X Coord</entry>
<entry>Y Coord</entry>
<entry>Move Graphics Cursor</entry>
</row>
<row>
<entry>22</entry>
<entry>X Coord</entry>
<entry>Y Coord</entry>
<entry>Draw Line to X/Y</entry>
</row>
<row>
<entry>23</entry>
<entry>X Coord</entry>
<entry>Y Coord</entry>
<entry>Erase Line to X/Y</entry>
</row>
<row>
<entry>24</entry>
<entry>X Coord</entry>
<entry>Y Coord</entry>
<entry>Set Point at X/Y</entry>
</row>
<row>
<entry>25</entry>
<entry>X Coord</entry>
<entry>Y Coord</entry>
<entry>Clear Point at X/Y</entry>
</row>
<row>
<entry>26</entry>
<entry>Radius</entry>
<entry></entry>
<entry>Draw Circle</entry>
</row>
</tbody>
</tgroup>
</table>

</section>
</appendix>