--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/nitros9guide/display.appendix	Sun Jul 07 09:54:04 2002 +0000
@@ -0,0 +1,661 @@
+<appendix>
+<title>Display System Functions</title>
+
+<section>
+<title>The Video Display</title>
+<para>
+Dragon Data OS-9 allows  the video 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 Dragon'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 Dragon 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 Dragon 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 Dragon 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>