Vertical Scrolling with DLIs: A Smooth Scroller Under a Fixed Status Bar

Two captures of an Atari text screen scrolling numbered MAP LINE rows, showing different rows; in both, a red bar reading STATUS: THIS LINE STAYS PUT sits at exactly the same height

Most scrolling games need two things at once: a playfield that glides smoothly up or down, and a score line that stays perfectly still. On the Atari both come from the display list. Vertical fine scrolling is switched on per mode line, and a display list interrupt (DLI) recolours or re-fonts the status area. The two interact, though. Fine scrolling changes the height of some mode lines, and DLIs are tied to mode lines, so some DLIs ride up and down with the scroll while others stay fixed. This guide explains which is which, with a tested example.

What you'll learn: exactly how VSCROL changes line heights, why the total height of a scrolled region is constant, where to put a DLI so it doesn't move, what happens to DLIs inside the region, VSCROL's timing deadlines, and a complete scroller.

What you need: MADS, an emulator, and the basics from Fine Scrolling on the Atari and Display List Interrupts. The program here was assembled with MADS and run in atari800.

1. What VSCROL actually does

Bit 5 of a mode-line instruction ($20) enables vertical scrolling for that line. The rule is precise:

  • When the bit changes from 0 to 1, the first line with the bit set is shortened from the top: it starts at the scan line given by VSCROL.
  • Lines in the middle of the region display normally.
  • When the bit changes from 1 back to 0, the first line without it, the "buffer" line, is shortened at the bottom: it ends at the scan line given by VSCROL.

So a region of three mode 2 lines, with the bit on the first two, occupies (8 − VSCROL) + 8 + (VSCROL + 1) = 17 scan lines whatever VSCROL is. Raising VSCROL by one takes a scan line off the top line and adds one to the buffer line: the content moves up one line, and the region's top and bottom edges don't move at all. That is what makes a fixed status bar possible.

2. Where DLIs end up

A DLI fires at the start of the last scan line of the mode line whose DLI bit is set. Combine that with the rules above:

  • A DLI on the buffer line fires at the bottom edge of the region, which is fixed. Use this for a status bar below a scrolling window: it never moves.
  • A DLI on a line inside the region fires at the end of that line, which moves with the content. That is what you want for effects attached to the map, such as a colour band that belongs to a stretch of water. It is wrong for anything that should stay put.
  • A DLI above the region is unaffected.

When the LMS address steps down a whole row (the coarse part of the scroll), the content of each line changes but the line structure doesn't, so map-attached DLIs must change in step. Typically the VBI picks which colours each DLI will load from a table indexed by the current map row. Advanced DLI Techniques covers that table-driven style.

3. The timing deadlines

There are three deadlines for writing VSCROL, all relative to the scan line where it matters:

  • by cycle 0 to set the starting row when entering a scrolled region,
  • by cycle 108 to set the ending row of the buffer line,
  • by cycle 5 for the change to affect DLIs.

Writing VSCROL once per frame in the vertical blank, as the example does, meets all of them easily. Writing it mid-screen, to run two independently scrolling windows for instance, needs a DLI with WSYNC so that the write lands at a known point on the line.

4. The example

The program fills 64 lines of "map" text at $4000, shows 20 of them in a scrolling window, and puts a status line underneath. The display list, at the end of the listing, is the heart of it:

  • $62: mode 2 with LMS and vertical scroll. The LMS address is labelled lms so the VBI can change it.
  • 19 × $22: mode 2 with vertical scroll.
  • $82: the buffer line. Mode 2 with the DLI bit, without the scroll bit. It shows the next map row and ends the region.
  • $42: the status line with its own LMS, unscrolled.
; Smooth vertical scrolling window with a fixed status bar below it.
; 20 visible text lines scroll through 64 lines of "map"; a DLI on the
; buffer line recolours the status bar, which never moves.
SDMCTL  = $022F
SDLSTL  = $0230
COLOR2  = $02C6
COLOR1  = $02C5
VDSLST  = $0200
NMIEN   = $D40E
WSYNC   = $D40A
VSCROL  = $D405
COLPF2  = $D018
COLPF1  = $D017
SETVBV  = $E45C
XITVBV  = $E462
MAP     = $4000             ; 64 lines x 40 bytes
PTR     = $CB

        org $3000
start   jsr makemap
        lda #0
        sta SDMCTL
        lda #<dlist
        sta SDLSTL
        lda #>dlist
        sta SDLSTL+1
        lda #<dli
        sta VDSLST
        lda #>dli
        sta VDSLST+1
        ldy #<vbi
        ldx #>vbi
        lda #7
        jsr SETVBV
        lda #$C0
        sta NMIEN
        lda #$22
        sta SDMCTL
loop    jmp loop

; VBI: one scan line per frame. After 8, move the LMS address down a row.
vbi     inc fine
        lda fine
        cmp #8
        bne setv
        lda #0
        sta fine
        clc                 ; coarse step: LMS += 40
        lda lms
        adc #40
        sta lms
        bcc c1
        inc lms+1
c1      lda lms+1           ; wrap after 44 rows (64 - 20 visible)
        cmp #>[MAP+44*40]
        bne setv
        lda lms
        cmp #<[MAP+44*40]
        bne setv
        lda #<MAP
        sta lms
        lda #>MAP
        sta lms+1
setv    lda fine
        sta VSCROL
        jmp XITVBV

; DLI: fires on the last scan line of the buffer line, which ends at the same
; place on screen whatever VSCROL is, so the status bar never moves.
dli     pha
        lda #$34            ; red status bar
        sta WSYNC
        sta COLPF2
        lda #$0E
        sta COLPF1
        pla
        rti

makemap lda #<MAP           ; 64 lines: "MAP LINE nn" plus a ruler
        sta PTR
        lda #>MAP
        sta PTR+1
        ldx #0
mm1     ldy #39
        lda #0
mm2     sta (PTR),y
        dey
        bpl mm2
        ldy #0
mm3     lda mtext,y
        sta (PTR),y
        iny
        cpy #9
        bne mm3
        txa                 ; line number as two digits (binary to decimal)
        ldy #0
mm4     cmp #10
        bcc mm5
        sbc #10
        iny
        bne mm4
mm5     ora #$10
        pha
        tya
        ora #$10
        ldy #9
        sta (PTR),y
        pla
        iny
        sta (PTR),y
        txa                 ; a bar whose length follows the line number
        and #15
        clc
        adc #14
        tay
        lda #$0D            ; internal code of '-'
mm6     sta (PTR),y
        dey
        cpy #12
        bne mm6
        clc
        lda PTR
        adc #40
        sta PTR
        bcc mm7
        inc PTR+1
mm7     inx
        cpx #64
        bne mm1
        rts

mtext   dta d'MAP LINE '
fine    dta 0

dlist   dta $70,$70,$70
        dta $62             ; LMS + vertical scroll, mode 2
lms     dta a(MAP)
        :19 dta $22         ; 19 more scrolled lines
        dta $82             ; buffer line: scroll bit off, DLI on
        dta $42,a(status)   ; status bar (not scrolled)
        dta $41,a(dlist)
status  dta d'  STATUS: THIS LINE STAYS PUT           '

        run start

What each part does:

  • The VBI advances VSCROL one scan line per frame. After eight it resets to 0 and moves the LMS address on by 40 bytes, one text row. That is the fine-plus-coarse pattern from Fine Scrolling. When the window reaches the last full screen of the map it jumps back to the start. A real game would instead draw new rows into a circular buffer.
  • The DLI loads a red background and white text colour for the status line. It sits on the buffer line, so it fires at the same scan line every frame. In the two screenshots, taken at different moments, the map rows differ but the red bar is in exactly the same place.
  • The OS restores COLOR1 and COLOR2 to the hardware in every vertical blank, so the playfield returns to its normal colours at the top of the next frame without any extra code.

Assemble it with mads vscroll.asm -o:vscroll.xex and run it. The map scrolls up by one scan line every frame, 60 lines per second on NTSC.

5. Variations

  • Scroll downwards by decrementing VSCROL and stepping LMS back 40 bytes when it wraps below 0.
  • Status bar on top: put the status lines first and start the scrolled region after them. The region's top edge is fixed too, so a DLI on the last status line (above the region) stays put.
  • Two windows: give each region its own LMS, and write VSCROL for the second region from a DLI placed just above it, observing the deadlines in section 3.
  • Character modes 4 and 5 scroll the same way. For mode 5, which is 16 scan lines tall, count VSCROL to 16 instead of 8.

There is also a creative misuse. VSCROL and the row counter are 4-bit counters in every mode, so setting VSCROL to 13 when entering a one-scan-line mode F line makes ANTIC repeat that line for four scan lines, with the DMA cost of only one. This "GTIA 9++" trick gives low-resolution GTIA pictures much more cheaply than repeating lines with LMS.

Troubleshooting

  • The status bar jumps up and down with the scroll: the DLI is on a line inside the region. Move the DLI bit to the buffer line.
  • The window grows and shrinks: the scroll bit is on the buffer line too, or missing from the first line. The region must start with a scroll-bit line and end with a line without it.
  • One-line jitter in the status colours: the DLI writes its colours too late. Use WSYNC, and keep the work before the first store short.
  • A jump in the map every eight frames: VSCROL and the LMS step are out of step. Change both in the same VBI.

Further reading

  • Avery Lee, Altirra Hardware Reference Manual, chapter 4 (ANTIC): vertical scrolling, region heights, VSCROL deadlines and "GTIA 9++".
  • De Re Atari (Atari, Inc., 1982), chapter 6: scrolling.
  • On this site: Fine Scrolling on the Atari, Coarse Scrolling with LMS, Display List Interrupts, Advanced DLI Techniques.

Credits

  • Picture: Two moments of the example scroller: the map has moved, but the DLI-coloured status bar has not. — Program authors; screenshot by the site
  • Altirra Hardware Reference Manual — Vertical scrolling (region shortening rules, 17-line example, 4-bit counters, GTIA 9++, VSCROL deadlines cycle 0/108/5) — Avery Lee (Altirra)
  • De Re Atari, Chapter 6: Scrolling — Chris Crawford (Section 6 of De Re Atari)