Custom Display Lists: Mixing Text and Graphics Modes

A screen with two lines of large GRAPHICS 2 text, two lines of GRAPHICS 1 text and eighteen lines of normal 40-column text

Atari BASIC's GRAPHICS statement gives you one mode per screen, plus an optional four-line text window. The hardware is far more flexible: ANTIC will happily display any sequence of mode lines you list. A title in big GRAPHICS 2 letters, a subtitle in GRAPHICS 1, a block of 40-column text and a strip of bitmap graphics can all share a single screen — this is how many commercial programs and magazine games got their polished look.

What you'll learn: how to plan a mixed-mode screen on paper, how to build and install a display list from BASIC, how to put text on it without the OS garbling it, and how the same thing looks in assembly language.

What you need: Atari BASIC on any 8-bit Atari (or emulator); for the assembly example, the MADS cross-assembler. Read the companion guide Display Lists Explained first if the terms LMS and JVB are new to you.

Step 1: design the screen on paper

Start by laying out the screen as a stack of mode lines and adding up the scan lines as you go. Our screen:

Lines ANTIC mode BASIC equivalent Scan lines Bytes of screen data
2 7 GRAPHICS 2 2 × 16 = 32 2 × 20 = 40
2 6 GRAPHICS 1 2 × 8 = 16 2 × 20 = 40
18 2 GRAPHICS 0 18 × 8 = 144 18 × 40 = 720
Total 192 800

192 scan lines is exactly a standard screen, and 800 bytes fits comfortably inside the 960-byte screen buffer that a GRAPHICS 0 statement has already reserved — so we can borrow that memory instead of reserving our own.

The display list bytes follow directly:

112,112,112          24 blank scan lines (overscan)
71,lo,hi             mode 7 + LMS (64+7) and the screen address
7                    second mode 7 line
6,6                  two mode 6 lines
2 (x18)              eighteen mode 2 lines
65,lo,hi             JVB back to the start of the list

That is 30 bytes. We will put it on page 6 (addresses 1536–1791), the 256 bytes the OS and BASIC leave free for the user, which also guarantees it cannot straddle a 1K boundary.

Step 2: build and install it from BASIC

10 REM MIXED-MODE SCREEN DEMO
20 GRAPHICS 0:POKE 752,1:PRINT CHR$(125)
30 SC=PEEK(88)+256*PEEK(89):DL=1536
40 SH=INT(SC/256):SL=SC-256*SH
50 FOR I=0 TO 2:POKE DL+I,112:NEXT I
60 POKE DL+3,71:POKE DL+4,SL:POKE DL+5,SH
70 POKE DL+6,7:POKE DL+7,6:POKE DL+8,6
80 FOR I=9 TO 26:POKE DL+I,2:NEXT I
90 POKE DL+27,65:POKE DL+28,0:POKE DL+29,6
100 POKE 559,0:POKE 560,0:POKE 561,6:POKE 559,34

Line 20 opens a fresh GRAPHICS 0 screen and sets CRSINH (752) to hide the cursor, which would otherwise be drawn as an inverse block somewhere in our borrowed memory. Line 30 reads SAVMSC (88/89), the start of screen RAM. Lines 50–90 write the 30 bytes. Note the JVB at line 90 points back to 1536 = page 6, low byte 0.

Line 100 follows De Re Atari's safe-switch recipe: turn ANTIC's DMA off by writing 0 to SDMCTL (559), store the new address in SDLSTL/SDLSTH (560/561), then turn DMA back on with the default value 34. The OS copies 560/561 into ANTIC at the next vertical blank.

Step 3: put text on the screen

The OS doesn't know you changed anything. It still believes this is a 24-line, 40-column GRAPHICS 0 screen, and if you PRINT to it, characters land where that layout would put them. A classic failure: insert one 20-byte line into a 40-byte screen and everything below is shifted half a line sideways.

The reliable approach is to bypass the OS and POKE character codes straight into screen memory, using your own map of where each line starts:

  • mode 7 line 1 at SC, line 2 at SC+20
  • mode 6 lines at SC+40 and SC+60
  • mode 2 line n (0–17) at SC+80+40*n

Screen memory holds ANTIC internal character codes, not ATASCII. The conversion is simple: ATASCII 32–95 become 0–63, ATASCII 0–31 become 64–95, and 96–127 stay the same. Add 128 for inverse video.

200 DIM A$(40)
210 A$="ATARI BASIC":P=SC+4:GOSUB 1000
220 A$="MIXED MODES":P=SC+24:GOSUB 1000
230 A$="TWO SIZES OF TEXT":P=SC+41:GOSUB 1000
240 A$="ON ONE SCREEN!":P=SC+63:GOSUB 1000
250 FOR N=0 TO 17
260 A$="This is ordinary 40-column text, line ":P=SC+80+40*N:GOSUB 1000
270 POKE P+38,16+INT(N/10):POKE P+39,16+N-10*INT(N/10)
280 NEXT N
290 GOTO 290
1000 REM POKE A$ INTO SCREEN AT P
1010 FOR K=1 TO LEN(A$):C=ASC(A$(K,K))
1020 IF C<32 THEN C=C+64:GOTO 1050
1030 IF C<96 THEN C=C-32
1050 POKE P+K-1,C:NEXT K:RETURN

Line 270 writes the two-digit line number using internal codes 16–25, which are the digits 0–9.

Colour in the big text lines. In ANTIC modes 6 and 7 a character can only use 64 shapes, because the top two bits of each screen byte pick its colour register instead: codes 0–63 use playfield 0 (shadow 708), 64–127 playfield 1 (709), 128–191 playfield 2 (710) and 192–255 playfield 3 (711). Try changing line 230 to add 128 to each code and the subtitle will appear in a different colour. Lowercase letters will not appear as lowercase in these lines — with the default character base they come out as coloured uppercase/symbols — so stick to capitals or switch character sets.

In the mode 2 lines, by contrast, all 128 characters are available, and the text takes its luminance from 709 and its background from 710, just as in GRAPHICS 0.

Letting the OS draw for you (the trick)

If you really want PRINT and PLOT to work in one window, you can fool the OS: POKE location 87 (DINDEX) with the BASIC mode number of the window, POKE 88/89 with the address of the window's top-left byte, then POSITION 0,0 and print to channel 6 (for text modes 1 and 2) or plot as usual. Coordinates are then measured from the top-left of that window. It works, but the OS will happily write past the end of your window; keep each window's contents within its own lines.

A quick-and-dirty alternative from the same book: arrange lines in groups that use whole multiples of the normal line length (for example two 20-byte lines in place of one 40-byte line) so the horizontal shift cancels out. You still get vertical misplacement, because different modes use different numbers of scan lines.

The same screen in assembly (MADS)

In machine language, a display list is just data. With every line given its own LMS you can scatter the text wherever you like — this is the "windows" approach De Re Atari recommends for assembly programs, and the one Mark Andrews uses in his Antic tutorial on scrolling.

; Mixed-mode screen - assemble with: mads mixed.asm -o:mixed.xex
SDMCTL  = $022F
SDLSTL  = $0230

        org $2000
main    lda #0
        sta SDMCTL          ; ANTIC DMA off while we switch
        lda #<dlist
        sta SDLSTL
        lda #>dlist
        sta SDLSTL+1
        lda #$22            ; normal playfield + display list DMA
        sta SDMCTL
loop    jmp loop

        .align $100         ; keep the display list inside one page
dlist   dta $70,$70,$70             ; 24 blank lines
        dta $47,a(title)            ; mode 7 + LMS
        dta $46,a(sub)              ; mode 6 + LMS
        dta $70                     ; 8 blank lines as a spacer
        dta $42,a(body)             ; mode 2 + LMS
        :17 dta $02                 ; 17 more mode 2 lines
        dta $41,a(dlist)            ; JVB

title   dta d'   ATARI ROCKS!     '  ; 20 internal-code bytes
sub     dta d'  MIXED MODE DEMO   '
body    dta d'Every line of this screen is fetched by '
        dta d' ANTIC from wherever its LMS points.    '
        :640 dta 0                  ; rest of the 18 lines blank

        run main

Scan lines: 24 + 16 + 8 + 8 + 18 × 8 = 200 including the top blank lines, less than the 216 of a standard screen. MADS's dta d'...' produces internal (screen) codes directly, a() emits a little-endian address, and :17 dta $02 repeats the byte. Because the program never returns to the OS screen editor, nothing will overwrite your layout — but pressing RESET will restore the standard screen.

Hidden modes from BASIC

The same POKE technique unlocks ANTIC modes BASIC on the 400/800 can't select, such as the four-colour character modes 4 and 5, or mode 3 with true lowercase descenders. Orson Scott Card's article in COMPUTE!'s Second Book of Atari Graphics converts a fresh GRAPHICS 0 display list into ANTIC 4 simply by rewriting the mode bytes: since mode 4 has the same 24 × 40 layout as mode 2, the OS's PRINT positions still line up. (ANTIC 5 has only 12 lines, so half of the OS's text ends up "below" the screen.) On XL/XE machines these modes are directly available as GRAPHICS 12 and 13.

Troubleshooting

  • Screen goes black or rolls: count scan lines again; total must stay within roughly 192 (and never over 240).
  • Everything below one line is shifted sideways: you are printing through the OS on a mixed screen. POKE internal codes instead, or use the DINDEX/SAVMSC trick per window.
  • Stray inverse block on screen: the OS cursor. POKE 752,1 before switching, and avoid keyboard input to the editor.
  • The custom screen disappears: any GRAPHICS statement, RESET or DOS menu rebuilds the OS display list. Re-run your setup.
  • Garbage halfway down a big screen: the display data crossed a 4K boundary. Add an LMS at the first line past the boundary.

Further reading

  • De Re Atari (Atari, 1982), Chapter 2, "Writing to a custom display list screen".
  • Mapping the Atari by Ian Chadwick (COMPUTE! Books), locations 87–89 and 560–561.
  • COMPUTE!'s Second Book of Atari Graphics (COMPUTE! Books, 1984), especially the four-colour character mode articles.
  • Mark Andrews, Atari Roots: A Guide to Atari Assembly Language (Datamost, 1984), and his "Fine Scrolling World" series in Antic (September 1985).

Credits