CHAPTER 8
     
     
                           THE DISPLAY HANDLER (S:)
     
     
     The display handler manages the computer's video display.  Although no
     data ever leaves the computer through it, the display is treated like
     any other CIO device.  Data sent to the screen may be displayed as
     either characters or point by point graphics.  Although it is only
     visible in the 40 column text mode, mode 0, there is a cursor on the
     screen in all of the text or graphics modes.  Whenever a character or
     graphics point is put on the screen, the cursor moves just as in mode
     0.
     
     The display is capable of both input and output.  Information can be
     put on the screen with any of the CIO output commands.  An input
     command will find whatever is on the screen at the position of the
     cursor.
     
     When text or graphics is sent to the screen it is actually stored in
     an area of memory called the display buffer.  What you see on the
     screen is the computer's interpretation of the data stored there. 
     This will be explained further as each mode is covered.
     
     
     DISPLAY HANDLER SPECIAL FUNCTIONS:
     
          DRAW
          FILL
     
     SPECIAL ERROR STATUSES:
     
          $84 (132) Invalid special command.
          $8D (141) Cursor out of range.
          $91 (145) Nonexistant screen mode.
          $93 (147) Insufficient ram for screen mode.
     
     
     TEXT MODE 0
     
     In graphics mode 0, data passes through CIO, and is stored in the
     display buffer in the following format.
     
           7 6 5 4 3 2 1 0
          -----------------
          |I|    Data     |
          -----------------
     
     I  1 = displays character in inverse video.
     
     
     Bits 0 through 6 select one of the 128 characters in the ATASCII set.


     If bit seven = 1, the character is displayed in inverse video. 
     Converting the above byte to decimal will give the BASIC ASC(x)
     equivalent.
     
     
     The characters displayed in the text modes are determined by tHE
     ATASCII character set.  This is a bit by bit representation of how the
     characters appear on the screen.  The character set starts $E000
     (57344) in the operating system ROM.  From there, for 1K of memory,
     each eight bytes holds a "bit map" of a particular character.  Below
     is how the letter A is stored in the character set.
     
     
                     Letter A as represented in the C-set
     
              7 6 5 4 3 2 1 0
             -----------------
      $E208  |0 0 0 0 0 0 0 0|
             -----------------
             |0 0 0 1 1 0 0 0|        * *
             -----------------
             |0 0 1 1 1 1 0 0|      * * * *
             -----------------
             |0 1 1 0 0 1 1 0|    * *     * *
             -----------------
             |0 1 1 0 0 1 1 0|    * *     * *
             -----------------
             |0 1 1 1 1 1 1 0|    * * * * * *
             -----------------
             |0 1 1 0 0 1 1 0|    * *     * *
             -----------------
      $E20F  |0 0 0 0 0 0 0 0|
             -----------------
     
     XL and XE models have an international character set starting at $CC00
     (55224).  In this character set the graphics characters are replaced
     by international characters.
     
     Custom characters sets may be loaded at any free address which is a
     multiple of 1,024 ($0400, or 1K).  The database variable CHBAS [$02F4
     (756)] stores the most significant byte (MSB) of the address of the
     active C-set.  Since the LSB of the C-set address is always $00, no
     LSB is needed to find it.
     
     The data stored in the display buffer does not use the ATASCII code. 
     A special code needed by the ANTIC chip is used.
     
                    DISPLAY CODE / ATASCII CODE CONVERSION:
     
            ATASCII                       display
     
      $00 - $1F ( 0 - 31)     =     $40 - $5F (64 - 95)
      $20 - $5F (32 - 95)     =     $00 - $3F ( 0 - 63)
      $60 - $7F (96 - 127)    =     unchanged
     
     
     The codes for inverse video (the above codes with bit 7 set (= 1) or
     the above codes + 128 in decimal) are treated likewise.
     
     When you first turn on the computer, BASIC opens channel 0 to the
     screen editor (E:).  The screen editor uses both the keyboard handler
     and the screen handler, in mode 0, to display characters when they are
     typed in.
     
     
     TEXT MODES 1 AND 2
     
     Graphics modes 1 and 2 offer a split screen configuration if desired. 
     The split screen has four lines of mode 0 at the bottom of the
     screen.
     
     In mode 1 the screen holds 20 characters horizontally and 24
     characters vertically.  In mode 2 the characters are twice as tall so
     the screen holds 12 vertically.
     
     In BASIC, characters are sent to the screen with the PRINT command. 
     Since BASIC uses channel 6 for graphics you must specify channel 6 in
     the command.  For example:
     
     
      ? #6;"HELLO"
     
     
     If you use a comma in place of the semicolon, ten spaces will print
     before the "HELLO"
     
     You can also use the PLOT and DRAWTO commands.  In this case the COLOR
     command determines the character, as well as the color to be
     displayed.
     
     Data passes through CIO in the following form:
     
     
           7 6 5 4 3 2 1 0
          -----------------
          |  C  |    D    |
          -----------------
     
      C determines the color.
     
          C         Default   Color     Shadow
                    Color     Register  Register
     
          0         green     COLPF1    COLOR1
          1         gold      COLPF0    COLOR0
          2         gold      COLPF0    COLOR0
          3         green     COLPF1    COLOR1
          4         red       COLPF3    COLOR3
          5         blue      COLPF2    COLOR2
          6         blue      COLPF2    COLOR2
          7         red       COLPF3    COLOR3
     
     D is a 5 bit ATASCII code which selects the character to be displayed.
     The database variable CHBAS selects between upper case (CHBAS=$E0
     (224)) and lower case (CHBAS=$E2 (226)).
     
     
     GRAPHICS MODES 3 THROUGH 11
     
     Modes 3 through 8 offer a split screen mode.  In modes 9 through 11
     special programming is required for split screens.
     
     These modes use dot by dot (pixel by pixel) graphics instead of
     character sets.  Before explaining how graphics are sent to the screen
     through CIO, I will describe how the data in the display buffer is
     interpreted by the ANTIC chip.
     
     
     Mode 8 is the simplest of the graphics modes.  Each byte of the
     display buffer controls eight pixels horizontally.  The first 40 bytes
     of the display buffer control the first horizontal line of graphics. 
     This makes a total of 320 pixels horizontally.  If one of the eight
     bits of a byte is a 1 then the pixel it controls is on.  If a bit is a
     0 then it's pixel is off.  For example, if a particular byte is equal
     to $9B (binary 10011011) then its' part of the screen would look
     like...
     
       *  ** **
     
      (10011011)
                                                                           


     In reality the pixels are assigned to different color registers.  A
     color register is a byte of memory which controls the color of all
     pixels assigned to it.  In mode 8, if a bit is = 0 it's pixel is
     assigned to the register called COLBK.  If a bit is one, it's pixel is
     assigned to COLPF0.  See COLORS below for more information on the
     color registers.
     
     You may notice a close similarity between mode 0 and mode 8.  The
     major difference between these modes is where the dot by dot
     information comes from.  In mode 8 this information comes from the
     display buffer.  In mode 0 the display buffer contains codes telling
     what characters to display.  The actual dot by dot information comes
     for the character set at $E000.
     
     In mode 7 each pixel is controlled by two bits.  Therefore each byte
     only controls four pixels.  There are also only 1/4 as many pixels on
     the screen as in mode 8.  See mode 3 below for an explanation of how
     the each byte affects the pixels.
     
     
     In a graphics mode, when CIO sends a byte of data to the screen
     handler, that byte has information for only one pixel.  Do not confuse
     a byte which CIO sends to the screen handler with the bytes in the
     display buffer.
     
     CIO sends data to or retrieves data from the screen in the following
     forms.
     
     
           7 6 5 4 3 2 1 0
          -----------------
          |0 0 0 0 0 0| D |   Modes 3,5,7 -- D = color
          -----------------
     
          -----------------
          |0 0 0 0 0 0 0|D|   Modes 4,6,8 -- D = Color
          -----------------
     
          -----------------
          |0 0 0 0|   D   |   Modes 9,10,11 -- D = data
          -----------------
     
     
     Mode 3 uses a screen which is 40 pixels horizontally and 24
     vertically.  Each pixel is a square the size of a mode 0 character. 
     It requires 273 bytes of RAM where each byte controls 4 pixels.  Each
     pair of bits controls which of the four color registers their pixel is
     assigned to.
     
                        display buffer byte for mode 3
     
     
           7 6 5 4 3 2 1 0
          -----------------
          | D | D | D | D |
          -----------------
           P1  P2  P3  P4
     
     
      Pixel/color register assignments:
     
      D = 00    COLBK    (COLOR4)
          01    COLPF0   (COLOR0)
          10    COLPF1   (COLOR1)
          11    COLPF2   (COLOR2)
     
     
     Mode 4 uses a screen of 80 columns by 48 rows.  Each pixel is half the
     size of those in mode 3.  Mode 4 requires 537 bytes of RAM where each
     byte controls 8 pixels.  This mode is very similar to mode 8 except
     there are fewer but larger pixels.
     
     Mode 5 uses a screen of 80 columns by 48 rows.  The pixels are the
     same size as in mode 4.  Mode 5 requires 1,017 bytes of RAM where each
     byte controls 4 pixels in the same manner as in mode 3.
     
     Mode 6 uses a screen of 160 columns by 96 rows.  It requires 2,025
     bytes of RAM where each byte controls 8 pixels as in mode 4.
     
     Mode 7 uses a screen of 160 columns by 96 rows.  It requires 3,945
     bytes of RAM where each byte controls 4 pixels as in modes 3 and 5.
     
     
     Modes 8 through 11 (and 15 on XL and XE models) each require 7,900
     bytes of RAM and are very similar in display set up.  The main
     differences between these modes is the interpretation of data in the
     display buffer.
     
     Mode 15 (sometimes called mode 7.5) uses a screen of 160 columns by
     192 rows.  Each byte controls 4 pixels as in mode 7.  The main
     difference between mode 15 and its related modes is bit 0 of each
     instruction byte in the display list (the program which the ANTIC chip
     uses).  If this bit is 0 the screen is interpreted as mode 15.  If the
     bit is 1 the screen is interpreted as modes 8 through 11.
     
     Modes 8 through 11 are set up identically in memory, including the
     display list.  The only difference is the data in the PRIOR register
     of the GTIA chip.  The shadow register for PRIOR is GPRIOR [$026F
     (623)].
     
     Mode 8 (PRIOR = $00 - $3F (0 - 63)), uses a screen of 320 columns by
     192 rows.  Each byte controls 8 pixels as in modes 4 and 6.
     
     Mode 9 (PRIOR = $40 - $7F (64 - 127)) uses a screen of 80 columns by
     192 rows.  Each byte controls 2 pixels.  The pixels are all of the
     same color, controlled by COLBK.  Each half of a byte in the display
     buffer controls the luminance of the assigned pixel.  The format of
     each byte is as follows.
     
     
           7 6 5 4 3 2 1 0
          -----------------
          | data  |  data |
          -----------------
           pixel 1|pixel 2
     
     
     Mode 10 (PRIOR = $80 - $BF (128 - 191), is the same as mode 9 except 9
     color luminance combinations are available.  The data in each half
     byte chooses one of the 9 color registers for the assigned pixel.
     
     Mode 11 (PRIOR = $C0 - FF (192 - 255), is the same as mode 9 except
     there is one brightness but 16 colors.  The pixel data chooses one of
     the 16 available colors.  The luminance is that of the background
     (COLBK).
     
     
     USING THE SCREEN HANDLER
     
     
     OPENING A CHANNEL TO THE SCREEN HANDLER
     
     When a channel is opened to the screen handler the following actions
     take place:
     
     The area of memory to be used for the screen data is cleared.
     
     A display list (program for the ANTIC chip) is set up for the proper
     graphics mode.
     
     The top-of-free-memory pointer, MEMTOP [$02E5,2 (741)], is set to
     point to the last free byte before the display list.
     
     Before opening a channel to the screen handler, the pointer to the
     highest memory address needed by the program, APPMHI [$000E,2 (14)],
     should be properly set.  This will prevent the screen handler from
     erasing part of the program when it sets-up the screen data region.
     
     
     When the channel is opened, two special options can be sent with the
     direction parameter (ICAX1).
     
                             ICAX1 for screen open
     
     
               7 6 5 4 3 2 1 0
              -----------------
              |    C S W R    |
              -----------------
               1 6 3 1 8 4 2 1
               2 4 2 6
               8
     
      C   1 = don't clear the screen
      S   1 = split screen
      R   1 = input
      W   1 = output
     
     Before the open command, the graphics mode number is placed into
     ICAX2.
     
                             ICAX2 for screen open
     
               7 6 5 4 3 2 1 0
              -----------------
              |       : mode  |
              -----------------
     
       mode = $00 through $0B  (0 - 11 (0 - 15 on XL/XE))
     
     To open a channel to the screen in BASIC use the GRAPHICS command.
                                                                           




                           BASIC screen open format
     
      GRAPHICS mode
     
                                 For Example:
     
      GRAPHICS 8
     
     This will set up a mode 8 graphics screen and open channel 6 to it. 
     If the graphics mode is 1 - 8, a split screen will be set up.  For
     example, GRAPHICS 8 will set up a mode 8 screen with a four line text
     window at the bottom.
     
     If 16 is added to the mode number, a full screen will be set-up.  For
     example, GRAPHICS 8+16 or GRAPHICS 24 will set up a mode 8 screen,
     with no text window, a full 192 pixels high.  If the number 32 is
     added to the mode number, the screen will not clear when the channel
     opens.
     
     If you want to use a channel other than #6, you will have to use the
     open command.  It is used in the following format.
     
                     screen open without GRAPHICS command
     
      OPEN #channel,direction/special,mode,S:
     
                                 For example:
     
      OPEN #1,8,7,S:
     
     This will open channel 1 to a mode 7 screen for output only.  For use
     of special parameters, see ICAX1 above.
     
     USING AN OPEN CHANNEL TO THE SCREEN
     
     Once a channel is opened to the screen it is used like any other input
     or output device.  In other words, data is placed on the screen by the
     PRINT and PUT commands.  Data is retrieved from the screen with the
     INPUT and GET commands.  The part of the screen which the data will be
     put in or taken from is determined by the X,Y coordinants in the
     database variables COLCRS [$0055,2 (85)] and ROWCRS [$0054 (84)]. 
     What appears on the screen depends on what graphics mode the computer
     is in.
     
     Before sending data to the screen in BASIC, a color register must be
     assigned to the data.  Once a point is plotted on the screen, it's
     color will be determined by the color register it was assigned to.
     
     To assign a color to a ploted point, the COLOR command us used as
     follows.
     
                             COLOR command format
     

      COLOR register
     
                                 For example,
     
      COLOR 1
     
     After using the above command, all points plotted will be controlled
     by color register 1.  To change color registers, use the COLOR command
     again.
     
     In assembly language, the color is determined by the data sent to the
     screen.  See the above section on graphics modes for color
     information.
     
     In BASIC the PLOT command is used to put data on the screen.  The PLOT
     command is used as follows.
     
                            The BASIC PLOT command
     
      PLOT x,y
     
     x and y are the horizontal and vertical coordinates for the plotted
     point.
     
     
     In modes 3 through 11 a single point will be plotted.  In modes 1 and
     2 a text character will be printed on the screen by the PLOT command.
     
     The PRINT and PUT commands can also be used in basic.  What appears on
     the screen depends on the graphics mode.
     
     In modes 1 and 2 the ATASCII characters sent to the screen will be
     printed just as in mode 0.  See the paragraph on modes 1 and 2 above
     for more information.  In the other modes what appears depends on how
     the ANTIC chip interprets the data bytes sent to the screen.  For
     example, in mode 8, even numbered characters will be single pixels in
     color 1.  Odd numbered characters will be in color 0 (background).
     
     There are two special commands for the screen handler, DRAW and FILL
     
     DRAW (ICCOM = $11 (17))
     
     The draw command works exactly like the plot command except a straight
     line is drawn from the previous pixel to the new one.  In BASIC it is
     used in the following format.
     
                            the BASIC DRAW command
     
      DRAWTO x,y
     
     
     FILL (ICCOM = $12 (18))


     Fill works like draw except the area to the right of the drawn line
     will be filled with the color in FILDAT [$02FD (765)].  The fill
     command expects to find a boundary to the right.  If no boundary is
     found, the entire horizontal screen between the ends of the line is
     filled.
     
     To use the fill command in BASIC the XIO command must be used in the
     following format.
     
      POSITION x,y
      XIO 18 #6,0,0,"E:"
     
     Note that the cursor is first moved by the POSITION command.  Below is
     an example of how to prepare for and use the fill command.
     
                            using the fill command
     
     
        2nd DRAWTO  .____.  DRAWTO here
                    |    |
                    |    |
                    |    |
       fill to here !    !  PLOT here
     
     
     This will draw and fill a box on the screen.
     
     THE COLOR REGISTERS
     
     There are nine bytes of memory which control the colors on the screen.
     These bytes are called color registers.  The color registers have the
     following names and relationships.
                                                                           


                       Color registers and relationships
     
     Register Register          modes
     name     address
                                0 & 8    1 & 2    3 5 7    4 & 6   9 & 11  
     10
     
              HEX      decimal  COLOR numbers
     
     PCOLR0   $02C0     704                                                
     0
     PCOLR1   $02C1     705                                                
     1
     PCOLR2   $02C2     706                                                
     2
     PCOLR3   $02C3     707                                                
     3
     COLOR0   $02C4     708              0  - 63    1        1             
     4
     COLOR1   $02C5     709     1 - 255  64 -127    2                      
     5
     COLOR2   $02C6     710     0        128-191    3                      
     6
     COLOR3   $02C7     711              192-255                           
     7
     COLOR4   $02C8     712     border   backgnd    0     backgnd  backgnd 
     8
     
     
     The color numbers are in decimal.  These are actually shadow
     registers.  See the O.S. equates below for relationships.  In modes 0
     - 3 the COLOR number actually determines the character printed
     
     The register to which a pixel/character is assigned to is determined
     by the data byte sent to the screen through CIO.
     
     The data in the color registers in in the following format.
     
                          Color register data format
     
     
                7 6 5 4 3 2 1 0
               -----------------
               | color |bright |
               -----------------
     
          color  = one of 16 possible colors
          bright = one of 8 possible brightnesses 
                  (even numbers, 0 - E)
     
     
     In basic, the COLOR command is used to assign color registers.  The
     corresponding registers depends on the graphics mode.  For example,
     COLOR 0 is COLOR2 in mode 8.  In most other modes COLOR 0 is COLOR4. 
     See the above chart for the register relationships.
     
     To change the contents of the color registers in BASIC, the SETCOLOR
     command is used.  In all modes except mode 10, the SETCOLOR command
     refers to the registers COLOR0 to COLOR4.
     
                        SETCOLOR/register relationships
     
          SETCOLOR 0    COLPF0    (COLOR0)
          SETCOLOR 1    COLPF1    (COLOR1)
          SETCOLOR 2    COLPF2    (COLOR2)
          SETCOLOR 3    COLPF3    (COLOR3)
          SETCOLOR 4    COLBK     (COLOR4)
     
     The format for the SETCOLOR command is...
     
     
                            SETCOLOR command format
     
      SETCOLOR register,hue,brightness
     
      register   = 0 - 4 (0 - 8 in mode 10)
      hue        = 0 - 15 (16 colors)
      brightness = 0 - 16 (even numbers only (8 brightnesses)
     
     
     The following chart gives the colors represented by the hue number.
     
     
                       colors represented by hue numbers
     
     
     0    grey           8    blue
     1    gold           9    cyan
     2    gold-orange   10    blue-green
     3    red-orange    11    blue-green
     4    orange        12    green
     5    magenta       13    yellow-green
     6    purple-blue   14    yellow
     7    blue          15    yellow-red
     
     
     The attract mode
     
     If a key is not pressed for more than 9 minutes the computer will
     enter the attract mode.  This mode is used to prevent burning of the
     TV phosphors by lowering the brightness and constantly changing the
     colors.  The attract mode timer, ATRACT [$004D (77)], is set to 254
     ($FE) when the the attract mode is entered.  To force the computer out
     of the attract mode, poke a number less than 127 into ATRACT.
     
                   Useful database variables and OS equates

    
     APPMHI $000E,2      (14): lower limit for screen region
     ATRACT $004D        (77): attract mode timer and flag
     LMARGN $0052        (82): left margin
     RMARGN $0053        (83): right margin
     ROWCRS $0054        (84): horizontal cursor position
     COLCRS $0055,2      (85): vertical cursor position
     DINDEX $0057        (87): current graphics mode
     SAVMSC $0058,2      (88): starting address of display buffer
     OLDROW $005A        (90): previous cursor position
     OLDCOL $005B,2      (91):    "       "        "
     OLDCHR $005D        (93): character currently at the text cursor
     OLDADR $005E,2      (94): memory address of cursor
     RAMTOP $006A       (106): end-of-RAM + 1 (MSB only)
     SDLSTL $0230,2     (560): shadow register of display list address
     TXTROW $0290       (656): text window cursor position
     TXTCOL $0291,2     (657):  "      "     "      "
     TXTMSC $0294,2     (660): starting address of text window data buffer
     RAMSIZ $02E4       (740): permanent end-of-RAM + 1 (MSB only)
     CRSINH $02F0       (752): cursor inhibit, 1 = no cursor
     FILDAT $02FD       (765): color data for fill
     DSPFLG $02FE       (766):  if >0 screen control codes are displayed as
                                ATASCII characters (EOL is uneffected)
     SSFLAG $02FF       (767): > 0 = stop screen print
     COLPM0 $D012     (53266): actual color registers
     COLPM1 $D013     (53267): loaded from shadow
     COLPM2 $D014     (53268): registers during
     COLPM3 $D015     (53269): vertical blank
     COLPF0 $D016     (53270):
     COLPF1 $D017     (53271): see above
     COLPF2 $D018     (53272): for use
     COLPF3 $D019     (53273):
     COLBK  $D020     (53274):
     
     
     
                              OS shadow registers


     
     PCOLR0 $02C0       (704): COLPM0
     PCOLR1 $02C1       (705): COLPM1
     PCOLR2 $02C2       (706): COLPM2
     PCOLR3 $02C3       (707): COLPM3
     COLOR0 $02C4       (708): COLPF0
     COLOR1 $02C5       (709): COLPF1
     COLOR2 $02C6       (710): COLPF2
     COLOR3 $02C7       (711): COLPF3
     COLOR4 $02C8       (712): COLBK

------------------------------------------------------------
[BACK] [CONTENTS] [NEXT]