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:

  1. 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.
  2. 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 at msg, 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