Fine Scrolling on the Atari: HSCROL, VSCROL and a Smooth Ticker
Coarse scrolling moves the screen a whole character at a time. Fine scrolling moves it by a single colour clock horizontally or a single scan line vertically — the buttery-smooth motion of scrolling shooters, platformers and demo-scene text tickers. ANTIC does the hard part in hardware; your job is to feed it two registers at the right moment and step the LMS addresses whenever a full character has scrolled by.
What you'll learn: how HSCROL and VSCROL work, the extra memory ANTIC fetches on scrolled lines, the "buffer line" rule for vertical scrolling, why it must be done in the vertical blank, and a complete smooth marquee in assembly.
What you need: the MADS assembler, an emulator or real Atari, and a good grasp of display lists and LMS coarse scrolling (see the companion guides).
Two registers, two enable bits
Fine scrolling takes just two steps:
- Set the scroll-enable bits in the display list instructions of the lines you want to scroll: bit 4 (+16) for horizontal, bit 5 (+32) for vertical.
- Store the scroll amount into HSCROL ($D404, 54276) or VSCROL ($D405, 54277). Neither has an OS shadow.
Only the low four bits count, so each register covers 0–15 colour clocks or scan lines. Every line with the matching enable bit set is affected; other lines are untouched — so you can scroll one window while a status line stays still.
Direction. HSCROL is the number of colour clocks to shift the playfield right. So to make text travel left you decrease HSCROL, and when it underflows you reset it and advance the LMS address by one byte. For VSCROL, the value is the scan line at which the first scrolled mode line starts, so increasing VSCROL moves the image up.
How far is one character? In ANTIC mode 2 (GRAPHICS 0) a character is 4 colour clocks wide and 8 scan lines tall; in modes 6 and 7 a character is 8 colour clocks wide; in mode 7 it is 16 scan lines tall. Fine-scroll through one character's width or height, then perform one coarse (LMS) step and start the fine value again.
The extra data ANTIC fetches
When a line has horizontal scrolling enabled, ANTIC fetches more data than it displays so that a partly-scrolled character can appear at the edge: a normal-width line fetches a wide playfield's worth (48 bytes instead of 40 in mode 2, 24 instead of 20 in modes 6 and 7), and a narrow line fetches a normal line's worth. Wide playfields don't grow further.
That is why De Re Atari's simple BASIC demonstration makes the lines below the scrolled ones shift sideways: ANTIC is consuming 48 bytes per line where the OS expects 40. With proper per-line LMS layout (each line pointing into its own long row of data, as in coarse scrolling) the issue disappears.
Fine scrolling at normal width also costs extra DMA cycles, which matters for DLI timing.
The buffer line for vertical scrolling
The mechanism: the first line of a vertically scrolled region is shortened from the top by VSCROL, and the first line after the region (the first line with bit 5 cleared) is shortened at the bottom, ending at scan line VSCROL. In practice that means: set the VS bit on all lines of the region except the last, which serves as the buffer that lets new data scroll smoothly into view. A region of three mode-2 lines with bit 5 set on the first two occupies (8 − VSCROL) + 8 + (VSCROL + 1) = 17 scan lines.
Why BASIC can't do this smoothly
As Mark Andrews put it bluntly in Antic's "Fine Scrolling World", fine scrolling in BASIC jerks and smears. Changing the scroll registers while ANTIC is part-way down the screen confuses the display, and BASIC can neither keep up with 60 updates a second nor time them. The standard solution is a short machine-language routine in the vertical blank interrupt, which runs once per frame while ANTIC is idle.
A smooth horizontal ticker in assembly
This program shows a static title in large mode 7 text and, beneath it, a mode 6 line (GRAPHICS 1 characters) whose message glides continuously right-to-left at one colour clock per frame. A deferred VBI does all the work.
; ticker.asm - mads ticker.asm -o:ticker.xex
SDMCTL = $022F
SDLSTL = $0230
HSCROL = $D404
SETVBV = $E45C
XITVBV = $E462
org $2000
main lda #0
sta SDMCTL
lda #<dlist
sta SDLSTL
lda #>dlist
sta SDLSTL+1
lda #$22
sta SDMCTL
lda #7
sta fine
sta HSCROL
lda #7 ; deferred VBI
ldy #<vbi
ldx #>vbi
jsr SETVBV
forever jmp forever
vbi dec fine ; move image one colour clock left
bpl setfs
lda #7 ; a whole character (8 colour clocks) done:
sta fine
inc lms ; coarse step: advance LMS by one byte
bne chk
inc lms+1
chk lda lms ; reached the duplicate copy?
cmp #<msgend
bne setfs
lda lms+1
cmp #>msgend
bne setfs
lda #<msg ; wrap seamlessly to the start
sta lms
lda #>msg
sta lms+1
setfs lda fine
sta HSCROL
jmp XITVBV
fine dta 7
.align $400
dlist dta $70,$70,$70
dta $47,a(title) ; mode 7 + LMS, not scrolled
dta $70
dta $56 ; mode 6 + LMS ($40) + HSCROL enable ($10)
lms dta a(msg) ; <- the VBI rewrites these two bytes
dta $70
dta $42,a(info) ; mode 2 + LMS
dta $02
dta $41,a(dlist)
title dta d' FINE SCROLLING '
info dta d' HSCROL fine steps + LMS coarse steps '
dta d' done in the vertical blank '
msg dta d'*** SMOOTH SCROLLING ON THE ATARI 8-BIT - '
dta d'ANTIC DOES THE HARD WORK, THE VBI DOES THE '
dta d'BOOKKEEPING *** '
msgend dta d'*** SMOOTH SCROLLING ON' ; first 24 chars again
dta d' '
run main
How it works
- The mode 6 instruction is
$56= 64 (LMS) + 16 (horizontal scroll) + 6. Its address operand has its own label,lms, so the VBI can rewrite it directly. Updating it during vertical blank, while ANTIC isn't reading the display list, avoids the tearing you'd get from BASIC. - A mode 6 character is 8 colour clocks wide, so the fine value runs 7, 6 … 0. On underflow it resets to 7 and the LMS address moves on by one byte. The two changes cancel except for one colour clock, so the motion stays perfectly even.
- Because the line has horizontal scrolling on at normal width, ANTIC fetches 24 bytes for it, not 20. The message therefore ends with a repeat of its first 24 characters: when LMS reaches
msgend, the screen looks exactly as it did atmsg, and the VBI jumps back without a visible seam. - SETVBV with A = 7 installs the deferred VBI safely, and a deferred VBI must exit through
JMP XITVBV($E462), as De Re Atari's Chapter 8 specifies. - Scan lines: 24 + 16 + 8 + 8 + 8 + 8 + 8 = 80 — far less than a full screen, which is perfectly legal.
Change the speed by decrementing fine by 2 per frame (with the reset logic adjusted), or slow it down by acting only every second frame.
Vertical fine scrolling
The same pattern works vertically. Give a block of mode 2 lines the VS bit ($62 for the first line with LMS, $22 for the rest) and leave it off the final buffer line. Then, in the VBI:
inc vfine ; scroll up one scan line
lda vfine
cmp #8 ; mode 2 characters are 8 lines tall
bcc vset
lda #0 ; full character: reset fine scroll...
sta vfine
lda vlms ; ...and move the LMS down one 40-byte row
clc
adc #40
sta vlms
bcc vset
inc vlms+1
vset lda vfine
sta VSCROL ; $D405
vlms labels the two LMS address bytes of the region's first line. If the region also scrolls horizontally, each line needs its own LMS and the rows must be laid out with a fixed stride (e.g. 256 bytes) — exactly as in the coarse-scrolling map example — and each coarse vertical step adds the stride to every LMS.
Pitfalls
- Odd HSCROL values in GTIA modes. GTIA modes 9–11 pair up colour clocks into 4-bit pixels regardless of scrolling, so only even HSCROL values scroll them correctly.
- High-resolution modes (GRAPHICS 8, ANTIC F) can only be scrolled in pairs of pixels, because HSCROL works in colour clocks.
- Modes 8 and 9 after scrolled lines. There is a hardware bug where an ANTIC mode 8 or 9 line following a horizontally scrolled line at normal or wide width can be corrupted with high HSCROL values; a fresh LMS on the mode 8/9 line helps.
- 4K boundaries. Rows must not cross a 4K boundary in mid-line, and LMS values must keep a line's whole fetch (including the extra bytes) inside one 4K block.
- DLIs near scrolled regions. Vertical scrolling can shorten the line carrying a DLI, moving the interrupt onto a DMA-heavy scan line. Keep DLIs away from the region's first and last lines.
Troubleshooting
- Screen jitters each time a character boundary passes: the fine reset and the LMS step are in the wrong order, or happen in different frames. Do both in the same VBI.
- Lines below the scrolled area are shifted: you are relying on OS-style contiguous screen memory; give lines their own LMS.
- Text jumps a whole character the wrong way: your HSCROL direction is reversed — increasing HSCROL moves the image right.
- Bottom of a vertically scrolled block pops into view: you set the VS bit on the last line too. Clear it to make a buffer line.
Further reading
- De Re Atari (Atari, 1982), Chapter 6 — the original description, including "linking fine scroll to coarse scroll".
- Mark Andrews, "Fine Scrolling World" Parts I and II, Antic, 1985, adapted from his book Atari Roots (Datamost, 1984).
- Altirra Hardware Reference Manual, section 4.7 — exact behaviour including scrolling quirks and the "GTIA 9++" VSCROL trick.
- Atari Graphics and Arcade Game Design by Jeffrey Stanton and Dan Pinal (Arrays, 1984).
Credits
- De Re Atari, Chapter 6: Scrolling — Chris Crawford (Section 6 of De Re Atari)
- Mapping the Atari (revised edition) — 559 SDMCTL, 54276 HSCROL, 54277 VSCROL — AtariArchives.org
- Altirra Hardware Reference Manual, section 4.7 Scrolling — Avery Lee (Altirra)
- Antic Vol. 4 No. 5 — Fine Scrolling World Part I (Mark Andrews) — AtariMagazines.com (Kevin Savetz)
- Best of Antic Volume 1 — Scrolling (James Capparell) — AtariMagazines.com (Kevin Savetz)
- De Re Atari, Chapter 8 (SETVBV and VBI exits) — Jim Dunion (Section 8 of De Re Atari)
