Display List Interrupts (DLIs): More Colours, Mid-Screen Changes

A GRAPHICS 0 text screen with the middle eight lines shaded with horizontal rainbow colour bands

A display list interrupt (DLI) lets your program change the hardware while the picture is being drawn. ANTIC taps the 6502 on the shoulder at a scan line you choose, your short machine-language routine changes a colour register, a character set pointer or a player position, and the rest of the screen is drawn with the new value. This is where the Atari's famous rainbow title screens, multi-coloured playfields and "more sprites than the hardware has" come from.

What you'll learn: the sequence of events in a DLI, how to add one to a BASIC program with a handful of POKEs, how to use WSYNC for clean colour changes, how to run several different DLIs per frame in assembly, and the timing traps that cause flicker.

What you need: an Atari 8-bit or emulator (Altirra's debugger is excellent for this work), Atari BASIC for the first examples, and the MADS assembler for the last one. Read Display Lists Explained first.

How a DLI happens

De Re Atari narrates the chain of events:

  1. ANTIC reaches a display list instruction with bit 7 set (add 128 to the instruction byte).
  2. It waits until the last scan line of that mode line.
  3. If DLIs are enabled in NMIEN ($D40E, 54286), ANTIC raises the 6502's non-maskable interrupt.
  4. The OS NMI handler checks NMIST, sees a DLI, and jumps through the vector VDSLST at $0200/$0201 (512/513).
  5. Your routine changes hardware registers and ends with RTI.

Two consequences follow. First, put the DLI bit on the mode line above the one where you want the change. Second, the OS saves no registers for you — only the 6502's automatic push of the status register happens — so your routine must push and pull every register it touches.

Also remember that inside a DLI you must write the hardware registers (e.g. COLPF2 at $D018), not the OS shadows (710). The OS copies the shadows into the hardware every vertical blank; that is actually useful, because it automatically restores the top of the screen each frame.

VDSLST initially points at an RTI. Set your vector before enabling DLIs, or an early interrupt may jump somewhere unexpected.

A first DLI from BASIC

This is De Re Atari's classic first example. The machine code is 20 bytes, poked into page 6:

10 DLIST=PEEK(560)+256*PEEK(561)
20 POKE DLIST+15,130
30 FOR I=0 TO 19:READ A:POKE 1536+I,A:NEXT I
40 DATA 72,138,72,169,80,162,88
50 DATA 141,10,212,141,23,208
60 DATA 142,24,208,104,170,104,64
70 POKE 512,0:POKE 513,6
80 POKE 54286,192

Line 20 changes one GRAPHICS 0 mode line from 2 to 130 (128 + 2), giving it a DLI. Here is what the DATA decodes to:

        PHA             ; 72        save A
        TXA             ; 138
        PHA             ; 72        save X
        LDA #$50        ; 169,80    dark text luminance
        LDX #$58        ; 162,88    pink
        STA WSYNC       ; 141,10,212  ($D40A) wait for end of scan line
        STA COLPF1      ; 141,23,208  ($D017) character luminance
        STX COLPF2      ; 142,24,208  ($D018) text background
        PLA             ; 104
        TAX             ; 170
        PLA             ; 104
        RTI             ; 64

RUN it and the lower part of the screen turns pink with dark text, while the top stays the normal blue: every vertical blank the OS copies 709/710 back into the hardware for the top lines, and every frame the DLI overrides them partway down. Writing 192 to NMIEN enables both DLIs (bit 7) and the vertical blank interrupt (bit 6) — never clear bit 6 by accident, or the OS's VBI stops running.

WSYNC: why the line is clean

The DLI starts executing part-way across the last scan line, and the exact cycle varies. Without help, a colour change would appear at a jittery position mid-line. Writing anything to WSYNC ($D40A, 54282) halts the 6502 until the beam reaches the end of the line (the CPU normally restarts at cycle 105 of 114). Stores made right after WSYNC take effect during horizontal blank, off-screen, so the change appears neatly at the start of the next line.

The pattern is therefore always: save registers, pre-load the new values into A/X/Y, STA WSYNC, then store them to the hardware as quickly as possible.

A rainbow from one DLI

A DLI does not have to be short. This routine sits on one mode line and then changes the text background on each of the next 64 scan lines, hitting WSYNC once per line:

10 GRAPHICS 0:DL=PEEK(560)+256*PEEK(561)
20 FOR I=0 TO 30:READ A:POKE 1536+I,A:NEXT I
30 POKE 512,0:POKE 513,6
40 POKE DL+12,130:POKE 54286,192
50 FOR I=1 TO 22:PRINT "  RAINBOW BAND - LINE ";I:NEXT I
60 GOTO 60
100 DATA 72,138,72,162,0,138,141,10,212
110 DATA 141,24,208,232,232,224,128,208,243
120 DATA 173,198,2,141,10,212,141,24,208
130 DATA 104,170,104,64
        PHA
        TXA
        PHA
        LDX #0
LOOP    TXA             ; colour = X (hue and luminance both climb)
        STA WSYNC
        STA COLPF2      ; $D018
        INX
        INX
        CPX #128        ; 64 scan lines
        BNE LOOP        ; 208,243 = branch back 13 bytes
        LDA $02C6       ; restore the shadow colour (710)
        STA WSYNC
        STA COLPF2
        PLA
        TAX
        PLA
        RTI

DL+12 is the eighth text line of a GRAPHICS 0 screen (offset 3 is line 1, offset 6 is line 2), so the band starts at line 9. Without the final restore, the last rainbow colour would stay in place down to the bottom of the screen.

Several different DLIs per frame (assembly)

There is only one DLI vector, so the usual technique — recommended by De Re Atari as "the most general solution" — is for each DLI to point VDSLST at the next one when it has finished its time-critical work, and for a vertical blank routine to reset the vector to the first DLI each frame. Install the VBI through the OS routine SETVBV ($E45C) so both bytes change atomically: A = 6 for the immediate VBI or 7 for the deferred one, Y = low byte, X = high byte.

; chained DLIs - mads dli.asm -o:dli.xex
VDSLST = $0200
SDMCTL = $022F
SDLSTL = $0230
COLPF2 = $D018
COLBK  = $D01A
WSYNC  = $D40A
NMIEN  = $D40E
SETVBV = $E45C
SYSVBV = $E45F

        org $2000
main    lda #0
        sta SDMCTL
        lda #<dlist
        sta SDLSTL
        lda #>dlist
        sta SDLSTL+1
        lda #$22
        sta SDMCTL
        lda #6                  ; immediate VBI
        ldy #<vbi
        ldx #>vbi
        jsr SETVBV
        lda #<dli1              ; vector first...
        sta VDSLST
        lda #>dli1
        sta VDSLST+1
        lda #$C0                ; ...then enable DLI + VBI
        sta NMIEN
loop    jmp loop

dli1    pha
        lda #$34                ; red
        sta WSYNC
        sta COLPF2
        sta COLBK
        lda #<dli2              ; chain to the next DLI
        sta VDSLST
        lda #>dli2
        sta VDSLST+1
        pla
        rti

dli2    pha
        lda #$C4                ; green
        sta WSYNC
        sta COLPF2
        sta COLBK
        pla
        rti

vbi     lda #<dli1              ; restart the chain every frame
        sta VDSLST
        lda #>dli1
        sta VDSLST+1
        jmp SYSVBV              ; continue normal OS VBI processing

        .align $400
dlist   dta $70,$70,$70
        dta $42,a(screen)
        :6 dta $02
        dta $82                 ; line 8: DLI -> change from line 9
        :7 dta $02
        dta $82                 ; line 16: DLI -> change from line 17
        :8 dta $02
        dta $41,a(dlist)

screen  dta d'      THREE BANDS, TWO INTERRUPTS       '
        :920 dta 0

        run main

The immediate VBI ends with JMP SYSVBV so the OS still updates its clock, shadow registers and so on. (A deferred VBI would end with JMP XITVBV, $E462, but the OS skips deferred processing when it interrupts time-critical code, which could leave the chain un-reset for a frame.) If all your DLIs live in one page, you can save cycles by changing only the low byte of VDSLST — a trick from the Player/Missile Podcast DLI tutorial.

Timing: how much can a DLI do?

Think of a DLI in three phases. Before WSYNC, the beam is still drawing the last line; the routine is reached roughly 28–36 cycles into the line, and in the heaviest modes (BASIC 0, 7 and 8, 40 bytes per line) only about 15 cycles remain before the WSYNC deadline. After WSYNC there are only about 17–26 usable cycles of horizontal blank — enough to store roughly three registers. WSYNC must be written by cycle 103 or the CPU waits a whole extra line.

Practical rules that follow:

  • Load values into A, X and Y before WSYNC, then do nothing but stores after it.
  • Don't try to change more than about three colours at once; split the work across two DLIs (a one-line blank instruction with the DLI bit set is a cheap way to get a second one).
  • Character-mode lines steal many cycles on their first scan line; DLIs placed on blank lines have the most time.

Gotchas

  • Keyboard click jitter. The OS key-click uses WSYNC repeatedly, which can push your colour change down a line for a moment whenever a key is pressed. De Re Atari's options: test VCOUNT ($D40B) in the DLI, replace the keyboard handler, or just don't take keyboard input.
  • Attract mode. After several minutes without a keypress the OS dims and shifts screen colours to protect the TV, but only through the shadow registers. To make DLI colours follow suit, add two instructions: EOR COLRSH ($4F) and AND DRKMSK ($4E) before the store.
  • DLIs interrupting DLIs. A DLI is an NMI and can be interrupted by the next DLI or by the VBI. A long DLI that is still running when the next DLI line arrives will be suspended and resumed later, as the Player/Missile Podcast tutorial demonstrates; emulators differ in such edge cases.
  • Never put the DLI bit on the JVB. $C1 fires a DLI on every scan line until vertical blank, which can easily crash a program.
  • Disk and serial I/O can cause missed interrupts, so expect glitches during SIO transfers.

Troubleshooting

  • Nothing happens: NMIEN not written, the vector still points at RTI, or the DLI bit is on a line the OS replaced by a later GRAPHICS statement.
  • Machine locks up: a register not restored, a missing RTI, or NMIEN written as 128 (DLI only, VBI disabled).
  • Colour boundary shimmers left and right: no WSYNC, or stores done too late after it.
  • Top of screen has the "bottom" colour: you wrote shadows instead of hardware registers, or your VBI replaced the OS's shadow copying.

Further reading

  • De Re Atari (Atari, 1982), Chapter 5 — the original and still the clearest overview of DLI timing.
  • Mapping the Atari by Ian Chadwick (COMPUTE! Books) — VDSLST, NMIEN, WSYNC and VCOUNT entries.
  • Rob McMullen's "Atari 8-bit Display List Interrupts: A Complete(ish) Tutorial" (Player/Missile Podcast), with downloadable sources.
  • Altirra Hardware Reference Manual — exact cycle tables for NMI dispatch and WSYNC.
  • Atari Graphics and Arcade Game Design by Jeffrey Stanton and Dan Pinal (Arrays, 1984).

Credits