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

Go to chapter 7
Go to chapter 9