APPENDIX EIGHT
Display Lists
A display list is a short program for the ANTIC chip, telling it how to
display data on the screen. This program includes such instructions as
how many blank lines to place on the screen for top boundaries, where
the screen display data is stored, what mode the line(s) to be displayed
are in, whether or not there is an interrupt to execute and where to find
the display list itself.

There are nine pre-programmed display lists (ten with the GTIA) you
use in BASIC, one for each GRAPHICS mode. You can examine the
display lists for each mode by running the program at location 560.
You can change these lists to suit your own needs without much effort.
It is quite easy to design and implement your own display list once you
know where it's located and what the proper instructions are.

Certain techniques, such as horizontal and vertical fine scrolling,
require that you modify the display list in order to properly display
your screen data. Sometimes you want to be able to display data in
more than one mode or mix graphics and text in the same screen.
These are all done by modifying the display list.

The smallest display list is for GRAPHICS 2, so I'll use it as an
example. It consists of a mere twenty odd bytes, but the format is the
same for every list; it's just the instructions that change. Use the
program listed in the Memory Map to examine the list or use a simple
two-liner such as:

10   GRAPHICS 2: P = PEEK(560) + PEEK
   (561) * 256
20   FOR N = 0 TO 23: PRINT PEEK(P +
   N);"	";: NEXT N

When you RUN this example, you should get this:

112 112 112 71 112 158 7 7 7 7 7 7 7 7 7 66
  96 159 2 2 2 65 88 158

Or something similar depending on your available memory. If you
change the GR.2 to GR.2 + 16, you will get:

112 112 112 71 112 158 7 7 7 7 7 7 7 7 7 7 7
  65 92 158

The display list instruction set is discussed at location 560, but here's a
chart to summarize it:

 Instruction   BASIC   Scan   Pixels  Bytes  Comments
Decimal   Hex   mode   lines   line   line
                                             Blank instructions
  0        0     --       1     --     --    1 blank line
 16       10     --       2     --     --    2 blank lines
 32       20     --       3     --     --    3 blank lines
 48       30     --       4     --     --    4 blank lines
 64       40     --       5     --     --    5 blank lines
 80       50     --       6     --     --    6 blank lines
 96       60     --       7     --     --    7 blank lines
112       70     --       8     --     --    8 blank lines
                                             Display instructions
  2        2      0       8     40     40    text mode 0
  3        3     --      10     40     40    text mode *
  4        4     --       8     40     40    text mode *
  5        5     --      16     40     40    text mode *
  6        6      1       8     20     20    text mode l
  7        7      2      16     20     20    text mode 2

  8        8      3       8     40     10    graphics mode 3
  9        9      4       4     80     10    graphics mode 4
 10        A      5       4     80     20    graphics mode 5
 11        B      6       2    160     20    graphics mode 6
 12        C     --       1    160     20    graphics mode *
 13        D      7       2    160     40    graphics mode 7
 14        E     --       1    160     40    graphics mode *
 15        F      8       1    320     40    graphics mode 8
                                             Jump instructions
                                             (three bytes long)
  1        1     --      --     --     --    jump to location
 65       41     --      --     --     --    jump and wait for
                                             VBLANK

Modes marked with an asterisk (*) have no equivalent in BASIC.
These are the instructions in the display list. You can alter the display
instructions by setting the bits for horizontal or vertical scroll, load
memory scan (tells ANTIC where the next line(s) to be displayed are in
memory and what mode to use for them) and enable a display list
interrupt. These are:

Function                   add
                         decimal   hex   bit
Vertical scroll             16     10    4
Horizontal scroll           32     20    5
Load memory scan            64     40    6
Display list interrupt     128     80    7

The LMS instruction is a three-byte instruction; the second and third
bytes are the LSB and MSB of the address where the line or screen data
is to be displayed. You can add any or all of these modifications to the
text or graphics mode instructions. You can only add the interrupt
modification to blank line or jump instructions. The two bytes that
follow the jump instructions are the LSB and MSB of the address to
which the ANTIC jumps to continue or repeat the list.
So let's analyze the DL for GRAPHICS 2 that we printed above:

112     These three instructions print
112     24 blank scan lines at the top
112     of the screen
71      GR.2 with LMS instruction added
112     Address of the first line of screen data
158     158 * 256 + 112 = 40560
7       Display the rest of the data in
7       GR.2, so we have a total of
7       ten GR.2 lines, or 10 * 16 =
7       160 scan lines used.
7
7
7
7
7
66      GR.0 with LMS instruction added
96      Address of the text window at bottom
159     159 * 256 + 96 = 40800
2       GR.0 for text window, so we have
2       a total of four lines
2
65      Jump and wait for vertical blank
88      Address of display list itself
158     158 * 256 + 88 = 40536
        (return to the top of this list)

Now examine the list for GR.2 + 16. You can see that it adds two 7's
to replace the GR.0 lines at the bottom of the screen. A little math
shows us that the screen in both cases has a total of 192 scan lines.
That's an important number; if you want your screen to come out
properly, you must insure that you get as close to this figure as
possible; otherwise you'll end up with blank lines at the bottom of your
screen, or worse -- in the display itself.

You will find the value 112 in every Atari display list. The three of them
are used to bring the display to a readable location on your set. Try
replacing one or more of them with a zero to see what happens without
them. The jump instructions are also used to skip across a 1K
boundary, since the DL itself cannot cross a 1K boundary without such
a jump. Also, DL data cannot cross a 4K boundary, so you must use an
LMS instruction before crossing one.

The critical factor in designing your own display list is to make sure
that the data and the scan lines match. This may require you to
manipulate your data so that you have the proper number of bytes per
line so that the display appears correctly on the screen. Here are the
number of bits per pixel for each of the ANTIC modes:

 Mode                   Bits per
decimal   hex   BASIC    pixel
    2      2	  0        8       text modes
    3      3     --        8
    4      4     --        8
    5      5     --        8
    6      6      1        8
    7      7      2        8

    8      8      3        2       graphics modes
    9      9      4        1
   10      A      5        2
   11      B      6        1
   12      C     --        1
   13      D      7        2
   14      E     --        2
   15      F      8        1

You can have as many DL's as you wish, using the jump/vertical blank
instruction at the end of the DL to tell ANTIC where your new DL is
located. When placing your new DL (page six, unless used for other
routines, is a good protected place to put it), do a POKE 559,0 to
disable the DL fetch instructions, then POKE it with the proper value to
turn it back on afterwards. Be inventive and create your own screens
with varied lines of text and graphics.

I suggest that you read De Re Atari and Your Atari 400/800 for more
information. The latter has a few good examples of altered display lists
and tells how to create them. Two DL utilities are The Next Step from
Online and Tricky Tutorial #1 from Santa Cruz.