Vertical Scrolling with DLIs: A Smooth Scroller Under a Fixed Status Bar
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 labelledlmsso 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)
