c64-kb 0.17.0

package/docs/recipes/oscar64/sprite-multiplex-8.md

@@ -0,0 +1,314 @@
+---
+recipe: sprite-multiplex-8
+toolchain: oscar64
+output_format: PRG
+region: both
+techniques: [sprite_multiplex_8]
+file_formats: [PRG]
+uses_registers: [D015, D000, D001, D010, D027, D012, D019, D01A, D020, D021]
+uses_kernal: []
+---
+
+<!-- doc-type: recipe -->
+
+# Oscar64 8-Sprite Multiplexer (12 Logical Sprites)
+
+## Synopsis
+
+Displays 12 independently moving logical sprites using only the VIC-II's 8
+hardware sprite slots, via `sprites.h` virtual sprite (`vspr_*`) functions.
+The `vspr_*` layer sorts logical sprites by Y position each frame and uses
+`rasterirq.h` slots to reposition hardware sprites mid-screen. Each logical
+sprite beyond the eighth gets its own raster IRQ slot that re-arms one
+hardware sprite as soon as that sprite's first draw has finished, so with 12
+logical sprites four of the eight hardware sprites are reused once and the
+other four are not (an earlier version of this page described "two vertical
+passes" with every hardware sprite reused; the library does not work that
+way). This is the `sprite_multiplex_8` technique from
+`docs/techniques/sprite.md`.
+
+## Source
+
+```c
+// sprite-multiplex-8.c
+//
+// 12 logical sprites on 8 hardware sprites using vspr_* multiplexer.
+// Sprites move in circular paths computed from a precomputed sine table.
+//
+// Memory layout: sprite data is placed at a fixed page-aligned address
+// ($2000) so that block numbers are predictable (block = addr / 64).
+//
+#include <c64/vic.h>
+#include <c64/sprites.h>
+#include <c64/rasterirq.h>
+#include <math.h>
+
+// Screen RAM at the default C64 address.
+#define Screen ((char *)0x0400)
+
+// Keep code and writable data below $2000 so sprite data fits at $2000.
+#pragma region( lower, 0x0a00, 0x2000, , , {code, data} )
+
+// Reserve $2000-$2800 for the sprite set (32 sprites × 64 bytes each = 2048).
+#pragma section( spriteset, 0 )
+#pragma region( spriteset, 0x2000, 0x2800, , , {spriteset} )
+
+// Remaining code, data, bss, heap, and stack go above $2800.
+#pragma region( main, 0x2800, 0xa000, , , {code, data, bss, heap, stack} )
+
+// --- Sprite bitmap data ---
+// Twelve distinct 24x21 bitmaps, each 63 bytes (padded to 64-byte alignment).
+// For this demo each sprite is a simple filled diamond shape generated by the
+// initializer. In a real program, use: #embed spd_sprites "sprites.spd"
+// or #embed "../resources/sprites.bin" to load SpritePad data.
+#pragma data(spriteset)
+
+static char spriteset[2048];   // 32 × 64-byte blocks; first 12 used
+
+#pragma data(data)
+
+// --- Sine tables for circular motion ---
+// 128 entries covering one full cycle, pre-scaled to the orbit radius so the
+// frame loop is a table lookup. An earlier version kept one -90..+90 table
+// and scaled it in the loop with a 16-bit multiply and divide per axis; that
+// loop measured 23,213-26,694 cycles per frame in VICE, more than a 19,656-
+// cycle PAL frame, so rirq_wait() returned at arbitrary raster lines and
+// vspr_update() rewrote the hardware sprites mid-frame, losing up to half the
+// sprites. The table-only loop below measured 6,292-9,162 cycles.
+static int sinx[128];   // -RADIUS_X..+RADIUS_X
+static int siny[128];   // -RADIUS_Y..+RADIUS_Y
+
+// Number of logical sprites to display.
+#define NUM_SPRITES  12
+
+// Radius of each sprite's circular orbit in screen pixels.
+#define RADIUS_X  80
+#define RADIUS_Y  60
+
+// Center of the display area (sprite Y origin on PAL is approximately 50
+// for the top of the visible area; sprites are Y=50..250).
+#define CENTER_X  160
+#define CENTER_Y  150
+
+int main(void)
+{
+    // --- Initialize sine tables (floating point once, at start-up) ---
+    for (int i = 0; i < 128; i++) {
+        sinx[i] = (int)(RADIUS_X * sin(i * 3.14159265 / 64.0));
+        siny[i] = (int)(RADIUS_Y * sin(i * 3.14159265 / 64.0));
+    }
+
+    // --- Initialize sprite bitmaps in place ---
+    // Paint each block with a distinct simple pattern so sprites are
+    // visually distinguishable. A filled diamond is 9 bytes per sprite row.
+    for (char s = 0; s < NUM_SPRITES; s++) {
+        char *blk = spriteset + (int)s * 64;
+        // Row 10 (middle row) of the diamond: all three bytes filled.
+        for (char row = 0; row < 21; row++) {
+            // Diamond shape: row 0 and 20 have 1 pixel, row 10 is full.
+            char w = (row <= 10) ? row : (20 - row);
+            // Shift a centered mask to the right by (10 - w) bits.
+            // Each row is 3 bytes = 24 bits of sprite data.
+            unsigned long mask = ((1UL << (2 * w + 1)) - 1) << (10 - w);
+            blk[row * 3 + 0] = (byte)(mask >> 16);
+            blk[row * 3 + 1] = (byte)(mask >>  8);
+            blk[row * 3 + 2] = (byte)(mask      );
+        }
+        blk[63] = 0;  // padding byte
+    }
+
+    // --- Initialize raster IRQ system ---
+    // rirq_init must be called by the program: vspr_init does NOT call it.
+    // Without it the raster IRQ lands in the KERNAL handler, is never
+    // acknowledged, and the main loop hangs in rirq_wait() with only the
+    // first eight sprites on screen (measured in VICE; an earlier version of
+    // this listing omitted the call). true = hook the KERNAL $0314 vector.
+    rirq_init(true);
+    // vspr_init occupies rirq slots 0 through VSPRITES_MAX-8 : one reuse
+    // slot per virtual sprite beyond the eighth, plus a sync slot at line 250.
+    vspr_init(Screen);
+
+    // --- Configure 12 logical sprites ---
+    // vspr_set(index, x, y, image_block, color)
+    // image_block = address / 64. With spriteset at $2000, block 0 = sprite 0.
+    char base_block = (unsigned)spriteset / 64;
+
+    for (char i = 0; i < NUM_SPRITES; i++) {
+        // Stagger starting phase so sprites spread around the circle.
+        char phase = (i * 128) / NUM_SPRITES;
+        int  sx    = CENTER_X + sinx[phase & 127];
+        int  sy    = CENTER_Y + siny[(phase + 32) & 127];
+
+        // Color cycles through the 8 non-black palette entries.
+        byte col = (byte)(8 + (i & 7));
+
+        vspr_set(i, sx, sy, base_block + i, col);
+    }
+
+    // --- Initial sort and update ---
+    // vspr_sort orders the logical sprites by ascending Y before the
+    // first frame. vspr_update programs the 8 hardware sprites with the
+    // top 8 by Y, and arms one reuse IRQ slot per remaining sprite.
+    vspr_sort();
+    vspr_update();
+    rirq_sort();
+
+    // --- Start the raster IRQ engine ---
+    rirq_start();
+
+    // Set a dark background so sprites are visible.
+    vic.color_back   = VCOL_BLACK;
+    vic.color_border = VCOL_BLACK;
+
+    // --- Animation loop ---
+    unsigned frame = 0;
+
+    for (;;) {
+        // Advance animation counter.
+        frame++;
+
+        // Compute new positions for each logical sprite. Keep this cheap:
+        // everything between one rirq_wait() and the next must fit in a
+        // frame, or the hardware sprites get rewritten mid-screen.
+        for (char i = 0; i < NUM_SPRITES; i++) {
+            // Each sprite orbits the center with a unique phase offset.
+            // The tables have 128 entries; the frame counter drives the angle.
+            char phase = (char)frame + (char)((i * 128) / NUM_SPRITES);
+            int  nx    = CENTER_X + sinx[phase & 127];
+            int  ny    = CENTER_Y + siny[(phase + 32) & 127];
+            vspr_move(i, nx, ny);
+        }
+
+        // Sort by Y: the multiplexer requires ascending Y order to assign
+        // hardware sprites to the correct vertical bands.
+        vspr_sort();
+
+        // Wait for the last raster IRQ of the current frame to complete.
+        // This ensures vspr_update is never called while the IRQ engine is
+        // still consuming the sprite slot table from the previous frame.
+        rirq_wait();
+
+        // Reprogram hardware sprite registers and raster IRQ reuse slots
+        // based on the freshly sorted logical sprite list.
+        vspr_update();
+
+        // Re-sort IRQ slots because vspr_update may have moved reuse slots.
+        rirq_sort();
+    }
+
+    return 0;
+}
+```
+
+## Build
+
+```bash
+oscar64 -O2 -o=sprite-multiplex-8.prg -tf=prg sprite-multiplex-8.c
+```
+
+`-O2` enables auto-inlining of small functions and 8-bit narrowing of the loop
+index arithmetic, both of which matter for the per-frame sprite update loop.
+
+Outputs: `sprite-multiplex-8.prg`, `.map`, `.asm`, `.lbl`.
+
+## Expected output
+
+Twelve filled 21×21 diamonds orbit a common center on an 80×60-pixel ellipse
+over the untouched power-on text screen (the listing never clears it, so the
+BASIC banner and `READY.`/`RUN` stay on the top rows). Colours are 8–15 with
+8–11 used twice, so the twelve are not all distinct. All 12 are visible
+simultaneously: the eight topmost by Y sit on the hardware sprites, and each
+of the other four is put on screen by its own reuse IRQ, which fires 23 lines
+below the Y of one of the four topmost sprites and re-arms that hardware
+sprite. The main loop is paced by `rirq_wait()`, one iteration per frame.
+
+Measured in VICE 3.10 (PAL) with the positions held at frame 200: twelve
+221-pixel diamonds at raster lines 92–230, at exactly the Y values the
+arithmetic gives (the first drawn row is at raster line Y+1). On the orbit
+used here the ninth-lowest sprite is always at least ~60 lines below the
+lowest, well past the 23-line reuse point, so no reused slot is asked to
+draw before its first sprite has finished (arithmetic, not a flicker sweep).
+
+An earlier version of this page said eight sprites sat "in the top half" and
+one IRQ "at the midpoint" moved them to the bottom half; there is no single
+midpoint IRQ, and the listing as then published never called `rirq_init()`,
+which left it frozen with eight sprites at their starting positions.
+
+## Why this works
+
+### The core multiplexer contract
+
+The VIC-II compares each hardware sprite's Y register against the raster counter
+at the start of every scanline. Once a sprite is latched as active (its top line
+passed), it renders for 21 lines even if the Y register changes. This gives the
+CPU a 21-line safe window per sprite to reprogram Y and the image pointer before
+the chip needs those values for the next activation.
+
+The multiplexer exploits this window. After sorting the logical sprites by Y,
+the top 8 are written to hardware at frame start. For each sorted sprite `8+n`
+a raster IRQ slot `n` is moved to `Y(sorted sprite n) + 23`, the line after
+hardware sprite `n & 7` has finished its first 21-row draw; that handler writes
+the new Y, X, colour, image pointer and MSB-X mask for that one hardware sprite
+(read from `sprites.c`: `rirq_move(ti, spriteYPos[ti + 1] + 23)`). An earlier
+version of this page said one IRQ fired "just before logical sprites 9-12";
+there is one per reused sprite, keyed to the finished sprite, not the next one.
+
+### `vspr_init` and the rirq slot reservation
+
+`vspr_init(Screen)` does **not** call `rirq_init()`; the program must, before
+`vspr_init`, as Oscar64's own `samples/sprites/multiplexer.c` does. It sets
+`$D015 = $FF`, clears both expand registers, and reserves `VSPRITES_MAX - 8`
+rirq slots for reuse IRQs plus one empty sync slot at line 250 — slots 0–8
+with the default `VSPRITES_MAX = 16` (read from `sprites.c`; the header
+comment says the same). With 12 logical sprites, `vspr_update` arms slots 0–3
+and clears 4–7 every frame. An earlier version of this page said `vspr_init`
+called `rirq_init(true)` and reserved `VSPRITES_MAX / 8 - 1` slots ("one
+slot"); both were wrong, and the missing `rirq_init` call left the listing
+frozen. To display more than 16 logical sprites, rebuild with
+`-dVSPRITES_MAX=24` (or higher) **and** raise `-dNUM_IRQS=` so that
+`VSPRITES_MAX - 7` slots fit (the default `NUM_IRQS` is 16; Oscar64's
+`sprmux32` sample builds with `-dVSPRITES_MAX=32 -dNUM_IRQS=28`). Each
+additional logical sprite, not each group of eight, costs one rirq slot, and
+its Y must be at least 23 lines plus a few lines of IRQ latency below the
+sprite whose hardware slot it reuses.
+
+### `vspr_sort`, `vspr_update`, `rirq_sort` — the per-frame triple
+
+These three calls form the per-frame multiplexer ritual:
+
+1. **`vspr_sort()`** — insertion sort on the logical sprite array by ascending Y.
+   It always walks all `VSPRITES_MAX` entries (the four unused ones sit at
+   Y = $FF). Measured with a CIA 2 timer around the call in this program on
+   VICE 3.10, over 200 frames: 457 cycles minimum, 2,018 maximum (the maximum
+   includes interrupts landing inside the call). An earlier version of this
+   page said "approximately 20-40 cycles", which is too small by an order of
+   magnitude.
+
+2. **`rirq_wait()`** — returns once `rirq_count` has changed since the last
+   `rirq_wait()`/`rirq_sort()`; the ISR increments it after the last slot of
+   the frame (the sync slot at line 250). Must precede `vspr_update()` to
+   prevent writing into the slot table while the IRQ engine is reading it.
+   **It only paces the loop if the loop is faster than a frame.** If the work
+   since the last `rirq_sort()` already took longer than a frame, the count
+   has already changed and `rirq_wait()` returns at once, wherever the beam
+   is. Measured here with the earlier multiply-and-divide position loop: the
+   raster line on return ranged over 1–311, and the screenshot showed six of
+   the twelve sprites. That is why the listing uses pre-scaled tables.
+
+3. **`vspr_update()`** — writes the sorted list to hardware: Y positions, image
+   pointers in the sprite pointer block (`Screen + $3F8`), colors (`$D027-$D02E`),
+   and the combined MSB-X byte (`$D010`). Also moves each active reuse slot
+   `n` to `Y(sorted sprite n) + 23` and stores the reused sprite's registers
+   in that slot's code with `rirq_data`. Measured as above: 554–1,853 cycles.
+
+4. **`rirq_sort()`** — re-sorts the rirq slot table after `vspr_update` has
+   moved any reuse slots to new Y positions. Measured as above: 441–1,430
+   cycles.
+
+The sprite pointer block at `Screen + $3F8` (address `$07F8` for the default
+$0400 screen) holds one byte per hardware sprite indicating which 64-byte block
+of sprite data it reads. `vspr_update` writes this block to change which logical
+sprite image each hardware slot displays on the next activation. `$D010` (MSIGX)
+packs the MSB of the X coordinate for all eight sprites into a single byte;
+`vspr_update` recomputes the full combined mask each frame so sprites whose X
+position exceeds 255 display at the correct horizontal position.

package/docs/recipes/oscar64/stable-raster-irq.md

@@ -0,0 +1,236 @@
+---
+recipe: stable-raster-irq
+toolchain: oscar64
+output_format: PRG
+region: both
+techniques: [stable_raster_irq]
+file_formats: [PRG]
+uses_registers: [D011, D012, D019, D01A, D020]
+uses_kernal: []
+---
+
+<!-- doc-type: recipe -->
+
+# Oscar64 Stable Raster IRQ
+
+## Synopsis
+
+Demonstrates the canonical Oscar64 idiom for raster-synchronized interrupts using
+`rasterirq.h`. The program fires a single raster IRQ at line 100, changes the border
+color to white on entry, and holds it white for the rest of the frame. This is the
+foundational pattern that all other raster effects in this KB build on.
+
+## Source
+
+```c
+// stable-raster-irq.c
+#include <c64/vic.h>
+#include <c64/rasterirq.h>
+
+// RIRQCode is a 32-byte struct (a size byte plus 31 bytes of generated
+// code) that encodes up to five writes. Declare it at file scope so it
+// lives in static storage.
+RIRQCode rirq;
+RIRQCode restore;
+
+int main(void)
+{
+    // rirq_init(true) installs the raster IRQ system and routes it through
+    // the KERNAL IRQ vector at $0314/$0315; it also sets $D01A bit 0 and
+    // clears $D011 bit 7. It does NOT disable the CIA1 timer: the KERNAL's
+    // jiffy IRQ keeps running and is handed on to $EA31. Pass false to
+    // install directly at the hardware vector $FFFE/$FFFF (faster, but
+    // requires KERNAL off). true is safe for cartridge-free PRG programs
+    // that load over BASIC.
+    rirq_init(true);
+
+    // rirq_build initializes the RIRQCode struct for one write slot.
+    // The second argument is the number of writes (1-5). Each write slot
+    // is one store to <address> in the IRQ handler at the programmed
+    // raster line. No heap allocation; you supply the struct.
+    rirq_build(&rirq, 1);
+
+    // rirq_write sets write slot 0 to store VCOL_WHITE into vic.color_border
+    // ($D020). When the raster IRQ fires, the generated code executes:
+    //   LDY #VCOL_WHITE          ; loaded before the wait loop
+    //   CMP $D012 / BCS -5       ; spin until the target line
+    //   STY $D020
+    // (slot 0 uses Y, slot 1 uses X, slots 2-4 use LDA/STA after the loop).
+    // Hand-optimized bytes generated by rirq_build; no C function overhead.
+    rirq_write(&rirq, 0, &vic.color_border, VCOL_WHITE);
+
+    // rirq_set installs the RIRQCode into slot 0, scheduled to fire one
+    // raster line below line 100 (i.e., at the start of raster line 101).
+    // Slots are numbered 0-15 (up to NUM_IRQS, default 16).
+    rirq_set(0, 100, &rirq);
+
+    // A second slot puts the border back to light blue at line 201. Without
+    // it the first interrupt leaves the whole border white for good and
+    // there is nothing to see: a register write persists until something
+    // writes the register again.
+    rirq_build(&restore, 1);
+    rirq_write(&restore, 0, &vic.color_border, VCOL_LT_BLUE);
+    rirq_set(1, 200, &restore);
+
+    // rirq_sort orders all installed slots by ascending raster line.
+    // Always call this after any rirq_set or rirq_move before rirq_start,
+    // and once per frame after moving slots mid-loop.
+    rirq_sort();
+
+    // rirq_start clears D011 bit 7, writes the constant 100 to D012 (not
+    // the first slot's line: it happens to coincide here), acknowledges
+    // D019 and unmasks the CPU IRQ. D01A was already set by rirq_init.
+    // From the first interrupt on, the dispatcher re-arms D012 itself
+    // and the handler fires automatically each frame.
+    rirq_start();
+
+    // Spin forever. The raster IRQ changes the border color on every frame
+    // without any CPU involvement in the main loop.
+    for (;;) { }
+
+    return 0;
+}
+```
+
+## Build
+
+```bash
+oscar64 -o=stable-raster-irq.prg -tf=prg stable-raster-irq.c
+```
+
+Expected outputs: `stable-raster-irq.prg`, `stable-raster-irq.map`,
+`stable-raster-irq.asm`, `stable-raster-irq.lbl`.
+
+Load with `LOAD"STABLE-RASTER-IRQ",8,1` followed by `RUN`, or pass
+`-autostart stable-raster-irq.prg` to VICE.
+
+## Expected output
+
+A white band in the border from raster line 101 to line 200; light blue above
+and below. Both edges are straight across the frame: the dispatcher's polling
+loop (below) puts the write in the horizontal blank.
+
+On both PAL (50 Hz, 312 lines) and NTSC (60 Hz, 263 lines) the effect is
+identical in appearance.
+
+Verified with Oscar64 (build 2026-05-19) and VICE 3.10 x64sc, measured
+2026-09-22 on both models: the left and right border columns are white on
+raster lines 101-200 inclusive and light blue on 100 and 201, and the
+transition rows are one colour from the first border pixel to the last (PAL
+C64C, VIC-II 8565, and NTSC 6567R8 both; an earlier version said PAL 6569,
+but `x64sc -default` is the C64C). No baseline PNG was committed for this recipe
+before this audit. The earlier version
+of this recipe had only the first slot and described a split at line 101;
+what it produced was an all-white border, because nothing ever wrote light
+blue back.
+
+## Why this works
+
+### What `rirq_init` actually does
+
+`rirq_init(true)` (which is `rirq_init_kernal()` in `rasterirq.c`) does three
+things. First, it installs the `rasterirq` dispatcher at `$0314`/`$0315` (the
+KERNAL software IRQ vector), so the KERNAL's IRQ entry at `$FF48` jumps into
+the dispatcher after doing its standard register save. Second, it sets `$D01A`
+bit 0 to enable VIC-II raster interrupts. Third, it clears `$D011` bit 7 and
+writes 255 to `$D012`, a line that never matches until `rirq_start` re-arms
+it.
+
+It does **not** disable the CIA1 timer A interrupt. The earlier text of this
+recipe said it wrote `$DC0D` to switch the jiffy timer off; the source does no
+such write, and a run of this listing on 2026-09-22 with the main loop
+watching `$A1`/`$A2` showed the KERNAL jiffy clock still counting after
+`rirq_start`. What the dispatcher does instead is test `$D019` bit 7 on entry:
+a VIC interrupt is serviced and exits through the KERNAL's bare `$EA81`; any
+other IRQ reads `$DC0D` to acknowledge the CIA and jumps to `$EA31`, the full
+KERNAL service, so the clock, keyboard scan and STOP key all keep working
+(about 190 cycles per jiffy tick idle). Both sources therefore share the IRQ
+line by design; the dispatcher tells them apart rather than silencing one.
+If you need the CIA quiet, write `$DC0D = 0x7F` yourself before `rirq_start`.
+
+### What "stable" means here, and what it does not
+
+Raw VIC-II raster IRQs carry 0-6 cycles of jitter because the CPU finishes
+its current instruction before entering the handler, and on top of that the
+KERNAL dispatcher adds 29 fixed cycles, so the handler starts on cycle 37-43
+of the line. A colour write from there lands two-thirds of the way across the
+visible line.
+
+What `rasterirq.c` does about it can be read in `rirq_build`: every
+`RIRQCode` begins with `LDY #d0 / LDX #d1 / CMP $D012 / BCS -5`: the first
+two data bytes are preloaded, then a 7-cycle loop spins until the raster
+counter passes the programmed row (A holds the row; the branch falls through
+once `$D012` exceeds it). In the KERNAL-vector mode used here the dispatcher
+arms `$D012` *two* lines before the target (the hardware-vector mode arms it
+one line before; the earlier text said "the row before" for both), so the
+KERNAL's 37-43-cycle entry and the dispatcher's own table walk are paid on
+the lines above and the loop is already spinning when the target line
+begins. Its `CMP` reads `$D012` on cycles 1-7 of that line, the branch falls
+through in 2 and the `STY` (slot 0 is a `STY`, not a `STA`; slot 1 is `STX`)
+writes 4 later, so the first write lands by about cycle 13 — arithmetic from
+the loop's 7-cycle period, not a cycle-level measurement — inside the
+horizontal blank. That is why the band edges are straight: the write is
+early, not exact. The residual jitter is the loop's granularity, up to six
+cycles, which is invisible for a border colour and would not be for a
+$D016 side-border write or an FLI $D018 write. The genuinely cycle-exact
+entry — the double-IRQ method — is in
+`docs/recipes/kickassembler/stable-raster-irq.md`; `rasterirq.h` does not
+implement it, and the earlier text of this recipe, which said the offset
+was "fixed" and "jitter-free", overstated the library.
+
+### `rirq_build`, `rirq_write`, `rirq_set`
+
+`rirq_build(&rirq, n)` initializes an `RIRQCode` struct for `n` writes (1-5).
+The struct is 32 bytes — a size byte and `RIRQ_SIZE` = 31 bytes of code (the
+earlier text said 31; `sizeof(RIRQCode)` is 32, checked with a compile-time
+assertion against the 2026-05-19 headers); larger variants `RIRQCode10` and
+`RIRQCode20` (62 and 107 bytes) hold 10
+and 20 writes respectively. The writes are stored as immediate operands and
+absolute addresses of real 6502 instructions inside the struct — no heap, no
+indirection at fire time; the dispatcher `JSR`s into the struct.
+
+`rirq_write(&rirq, slot, addr, data)` patches slot `slot` of the struct with the
+target address and data byte. At IRQ fire time the code runs `LDY #d0 / LDX
+#d1`, the wait loop, then `STY a0 / STX a1`, then `LDA #d / STA a` for slots
+2-4 in sequence (the earlier text said `LDA #data / STA addr` for every slot;
+the first two are preloaded so they can land 4 cycles apart right after the
+loop). Up to five writes fire within the cycle
+budget of a single raster line on both PAL (63 cycles/line) and NTSC
+(65 cycles/line). For more writes per line, use `RIRQCode10` or `RIRQCode20`.
+
+`rirq_set(n, row, &rirq)` installs the code into IRQ slot `n` and programs it to
+fire one line below `row`. The "one below" offset is a documented convention in
+`rasterirq.h`: `rirq_set(0, 100, ...)` fires at the start of line 101, not
+line 100. This gives the CPU the entirety of line 101 to execute the writes
+before the raster beam reaches the point where writes need to be visible.
+
+### `rirq_sort` and `rirq_start`
+
+`rirq_sort()` orders the slot table by ascending raster line. The dispatcher
+walks this sorted table on every frame, firing each slot as the beam reaches its
+line. If slots are installed out of order or moved mid-frame (via `rirq_move`),
+`rirq_sort()` must be called again before the next frame begins. The idiomatic
+call site is at the bottom of the main loop, after `rirq_wait()`.
+
+`rirq_start()` clears `$D011` bit 7, writes the constant 100 to `$D012`,
+acknowledges `$D019` and executes `CLI`. It does not read the slot table: the
+earlier text said it programmed `$D012` to the first slot's line, and in this
+recipe the two coincide only because the first slot *is* line 100. The first
+interrupt therefore fires at line 100 whatever the first slot says; the
+dispatcher then runs slot 0's code (which spins until the raster passes its
+own row) and from then on re-arms `$D012` for each following slot itself. A
+first slot far above line 100 pays that difference once, on the first frame.
+After this call the handler runs autonomously — the main loop never needs to
+touch IRQ machinery again unless slots are being moved.
+
+### Oscar64 vs cc65 IRQ style
+
+The cc65 equivalent of this recipe requires writing `$DC0D = 0x7F` to disable
+CIA interrupts, storing a function pointer at `$0314`/`$0315`, writing `$D01A =
+0x01`, and writing `$D012 = 100` manually. The handler stub must acknowledge
+`$D019`, re-arm `$D012` for the next frame, and return via RTI with A/X/Y/SR
+restored. None of that appears in this recipe because `rasterirq.h` encapsulates
+it — with one difference worth knowing: the library never disables the CIA, it
+forwards CIA interrupts to `$EA31` and keeps the KERNAL clock alive (see "What
+`rirq_init` actually does"). The Oscar64 idiom is three function calls to set up and one `for (;;)`
+to hold: the handler is data, not code, and the dispatcher is a reusable library.