A Finger on the Boxes

Back in Beat 6 you coloured one cell: ld ($5800), a. The address $5800 was baked into the instruction. To colour the cell next to it you'd write a whole new instruction with $5801 baked in, then $5802, and so on — a fresh line for every box. That doesn't scale, and last unit's eight-near-identical-pokes were the same problem wearing a different hat.

The fix is a pointer. HL is a sixteen-bit register pair, and you can treat it as a finger pointing at a box on the memory street from Beat 4:

• ld hl, $5800 — put the finger on the first colour cell.
• ld (hl), $17 — write into whatever box the finger is on.
• inc hl — move the finger one box along.

This is the HL we deferred back in Beat 5. The brackets mean the same as ever — (hl) is "the box HL points at", just like ($5800) was "the box at $5800" — except now the address can move.

What you'll see by the end

Three red cells in a row. We never wrote three addresses — we wrote one, into the box the finger pointed at, then nudged the finger along and wrote again. Point, write, step; point, write, step.

Walking the finger along

; ============================================================================
; PRIMER — Beat 9: A Finger on the Boxes
; ============================================================================
; Back in Beat 6 you coloured one cell with a fixed address:  ld ($5800), a.
; To colour the NEXT cell you'd need a whole new instruction with a new
; address baked in. That doesn't scale.
;
; A POINTER fixes this. HL is a 16-bit register pair you can use as a finger
; pointing at a box on the memory street:
;
;   ld hl, $5800   -- point the finger at the first colour cell
;   ld (hl), $17   -- write into the box the finger points at
;   inc hl         -- move the finger one box along
;
; (We deferred this in Beat 5 -- here it is. (HL) means "the box HL points
; at", just like ($5800) meant "the box at $5800" -- but now the address can
; MOVE.)
;
; We colour three cells in a row by writing, stepping, writing, stepping.
; ============================================================================

            org     32768

start:
            ld      hl, $5800        ; finger on the first colour cell (top-left)

            ld      (hl), $17        ; colour it       (PAPER red, INK white)
            inc     hl               ; step to the next cell
            ld      (hl), $17        ; colour it
            inc     hl               ; step again
            ld      (hl), $17        ; colour it

.loop:
            halt
            jr      .loop

            end     start

ld hl, $5800 aims the finger. Each ld (hl), $17 colours the cell it's resting on; each inc hl slides it to the next. Same two instructions, three cells — because the address moved instead of the instruction changing.

This is the heart of how every Spectrum screen gets drawn: a pointer walking through memory, laying down bytes as it goes.

Assemble and run

pasmonext --sna a-finger-on-the-boxes.asm primer.sna

Three red cells, drawn by one moving finger.

Try this: point at the pixels instead

Change the start to ld hl, $4000 and the written value to ld (hl), %11111111. Now the finger walks the pixel street, not the colour one — three solid blocks of pixels along the top. Same pointer, different stretch of memory.

Try this: a longer reach

Add another inc hl / ld (hl), $17 pair, and another, to colour four cells, then five. It works — but you can feel the repetition coming back. Writing the same two lines over and over is exactly the itch the next unit's loop scratches: tell the machine "do this thirty-two times" and let it walk the finger.

When it's wrong, see why

• Only one cell is coloured. An inc hl is missing, so every write lands on the same box. Each write needs a step after it.
• The cells are scattered or wrong. Check you start with ld hl, $5800 (the colour map). Starting elsewhere points the finger somewhere else entirely.
• pasmonext errors on ld (hl), $17. That exact form — write an immediate value through the pointer — is right; check the brackets around hl and the comma.

What you've learnt

HL is a movable pointer: (hl) is the box it currently points at, and inc hl steps it to the next — so one pair of instructions can write all the way along memory.

What's next

You've stepped the finger by hand, three times. Next — Counting Toward Zero — we hand the repetition to the machine: load a count into B, and DJNZ runs the write-and-step until the count hits zero. One loop fills a whole row.