c64-kb 0.17.0

package/docs/recipes/oscar64/print-number.md

@@ -0,0 +1,367 @@
+---
+recipe: print-number
+toolchain: oscar64
+output_format: PRG
+region: both
+techniques: [decimal_print]
+file_formats: [PRG]
+uses_registers: [DC04, DC05, DC0E, D011, D012]
+uses_kernal: []
+---
+
+<!-- doc-type: recipe -->
+
+# Oscar64 Print Number: binary to decimal and hex in screen RAM
+
+## Synopsis
+
+Turns a 16-bit binary value into five screen codes, right-aligned with
+leading zeros shown as spaces, and an 8-bit value into `$xx`, and writes
+them straight into screen RAM with no KERNAL call. Two decimal routes are
+given: subtract-powers (`fmt_dec_sub`, the one to use from C) and a plain
+C double-dabble (`fmt_dec_dab`, for comparison). Both are run over all
+65,536 values and the hex route over all 256, each field folded into a
+16-bit checksum shown with `PASS` or `FAIL` against the value Python
+computed. A CIA1 timer A harness then prints the cycle cost of each
+route, so the screenshot proves the digits and the figures. Use it for a
+HUD score, timer, coordinate readout or a debugging display. It
+implements `decimal_print` (`techniques/text.md`); the design-level notes
+are in `game-design/game-design-patterns.md` under "Printing numbers".
+
+## Source
+
+```c
+// print-number.c
+// Binary to decimal and hexadecimal for a text HUD, written straight into
+// screen RAM as screen codes with no KERNAL call. Two 16-bit decimal
+// routes (subtract-powers and double-dabble) are run over all 65,536
+// values and the 8-bit hex route over all 256, each folded into a 16-bit
+// checksum shown with PASS or FAIL against the value Python computed.
+// A CIA1 timer A harness then prints the cycle cost of each route.
+#include <c64/vic.h>
+#include <c64/cia.h>
+
+#define SCREEN ((char *)0x0400)      // default text screen
+
+// Expected checksums, computed by the same fold in Python (page text).
+#define EXPECT_DEC 0x0EB2            // fold over str(n).rjust(5), n = 0..65535
+#define EXPECT_HEX 0x263C            // fold over the 4-char hex field, n = 0..255
+
+// Screen codes: digits are $30-$39 as in PETSCII; 'A'-'F' are $01-$06.
+static const char hex_glyph[16] = {
+    0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
+    0x38, 0x39, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06
+};
+
+// --- the routines under test ------------------------------------------------
+
+// Subtract-powers. Writes five screen codes to dst: the value right-aligned,
+// leading zeros as spaces, so 0 becomes "    0" and 65535 fills the field.
+__noinline void fmt_dec_sub(unsigned v, char *dst)
+{
+    static const unsigned pow10[4] = { 10000, 1000, 100, 10 };
+    char lead = 1;
+    for (char i = 0; i < 4; i++)
+    {
+        unsigned p = pow10[i];
+        char d = 0x30;
+        while (v >= p) { v -= p; d++; }
+        if (d != 0x30 || !lead) { dst[i] = d; lead = 0; }
+        else dst[i] = 0x20;
+    }
+    dst[4] = 0x30 + v;               // v is 0..9 here
+}
+
+// Double-dabble in plain C. Shifts the 16 bits into three packed BCD bytes,
+// adding 3 to any nibble that is 5 or more before each shift, then unpacks
+// with the same zero suppression as fmt_dec_sub. Same output bytes.
+__noinline void fmt_dec_dab(unsigned v, char *dst)
+{
+    char b0 = 0, b1 = 0, b2 = 0;     // b2 ten-thousands, b1 thousands|hundreds, b0 tens|units
+    for (char i = 0; i < 16; i++)
+    {
+        if ((b0 & 0x0f) >= 0x05) b0 += 0x03;
+        if ((b0 & 0xf0) >= 0x50) b0 += 0x30;
+        if ((b1 & 0x0f) >= 0x05) b1 += 0x03;
+        if ((b1 & 0xf0) >= 0x50) b1 += 0x30;
+        if (b2 >= 0x05) b2 += 0x03;
+        b2 = (b2 << 1) | (b1 >> 7);
+        b1 = (b1 << 1) | (b0 >> 7);
+        b0 = (b0 << 1) | (char)(v >> 15);
+        v <<= 1;
+    }
+    char n[5];
+    n[0] = b2 & 0x0f; n[1] = b1 >> 4; n[2] = b1 & 0x0f; n[3] = b0 >> 4; n[4] = b0 & 0x0f;
+    char lead = 1;
+    for (char i = 0; i < 4; i++)
+    {
+        if (n[i] != 0 || !lead) { dst[i] = 0x30 + n[i]; lead = 0; }
+        else dst[i] = 0x20;
+    }
+    dst[4] = 0x30 + n[4];
+}
+
+// Hex byte for debugging: "$" and two digits, right-aligned in four cells.
+__noinline void fmt_hex8(char v, char *dst)
+{
+    dst[0] = 0x20;
+    dst[1] = 0x24;                   // '$'
+    dst[2] = hex_glyph[v >> 4];
+    dst[3] = hex_glyph[v & 0x0f];
+}
+
+__noinline void fmt_null(unsigned v, char *dst)
+{
+    // timing control: same call shape, empty body
+}
+
+// --- helpers ---------------------------------------------------------------
+
+static void put_text(char row, char col, const char *s)
+{
+    char *p = SCREEN + 40 * row + col;
+    while (*s)
+    {
+        char c = *s++;
+        if (c >= 'A' && c <= 'Z') c -= 64;   // ASCII upper case to screen code
+        else if (c == '[') c = 0x1b;          // brackets: screen codes $1B, $1D
+        else if (c == ']') c = 0x1d;
+        *p++ = c;
+    }
+}
+
+static void put_hex16(char row, char col, unsigned v)
+{
+    char *p = SCREEN + 40 * row + col;
+    p[0] = hex_glyph[(v >> 12) & 15]; p[1] = hex_glyph[(v >> 8) & 15];
+    p[2] = hex_glyph[(v >> 4) & 15];  p[3] = hex_glyph[v & 15];
+}
+
+static unsigned fold(unsigned chk, char value)
+{
+    return (chk ^ value) * 5 + 1;
+}
+
+// --- timing harness: CIA1 timer A, force-loaded from $FFFF, phi2 ----------
+
+static char tbuf[8];
+static volatile unsigned tval = 65535;   // volatile: the call cannot be folded
+static volatile unsigned tval2 = 59999;  // worst case for subtract-powers (5+9+9+9 steps)
+
+static void t_start(void)
+{
+    cia1.cra = 0x00;                     // stop timer A
+    cia1.ta = 0xffff;                    // latch $FFFF
+    cia1.cra = 0x11;                     // force load, start, count phi2
+}
+
+static unsigned t_stop(void)
+{
+    cia1.cra = 0x00;                     // stop before reading, so the two
+    return 0xffff - cia1.ta;             // byte reads cannot straddle a borrow
+}
+
+static unsigned time_sub(void)  { unsigned v = tval; t_start(); fmt_dec_sub(v, tbuf);       return t_stop(); }
+static unsigned time_sub2(void) { unsigned v = tval2; t_start(); fmt_dec_sub(v, tbuf);      return t_stop(); }
+static unsigned time_dab(void)  { unsigned v = tval; t_start(); fmt_dec_dab(v, tbuf);       return t_stop(); }
+static unsigned time_hex(void)  { unsigned v = tval; t_start(); fmt_hex8((char)v, tbuf);    return t_stop(); }
+static unsigned time_null(void) { unsigned v = tval; t_start(); fmt_null(v, tbuf);          return t_stop(); }
+
+static void show_cycles(char row, const char *label, unsigned raw, unsigned base)
+{
+    put_text(row, 0, label);
+    fmt_dec_sub(raw - base, SCREEN + 40 * row + 12);
+}
+
+int main(void)
+{
+    __asm { sei }                            // no KERNAL IRQ during the checks
+    for (unsigned i = 0; i < 1000; i++) SCREEN[i] = 0x20;
+
+    put_text(0, 0, "PRINT NUMBER");
+
+    // The four demonstration fields, each shown inside brackets.
+    put_text(2, 0, "DEC 0      [     ]");
+    fmt_dec_sub(0, SCREEN + 2 * 40 + 12);
+    put_text(3, 0, "DEC 7      [     ]");
+    fmt_dec_sub(7, SCREEN + 3 * 40 + 12);
+    put_text(4, 0, "DEC 65535  [     ]");
+    fmt_dec_sub(65535, SCREEN + 4 * 40 + 12);
+    put_text(5, 0, "HEX $A5    [    ]");
+    fmt_hex8(0xa5, SCREEN + 5 * 40 + 12);
+
+    // Cycle costs for the value 65535, body only: the empty call is subtracted.
+    // Display off while timing so no badline stalls the CPU. The VIC-II
+    // samples DEN once per frame, on line $30 (VIC-II documentation, not
+    // measured here), so wait for the next frame to start before timing;
+    // what was measured is that without this wait the NTSC run read 9% higher.
+    vic.ctrl1 &= ~0x10;
+    while (vic.raster != 0x80) ;
+    while (vic.raster != 0x00) ;
+    unsigned base = time_null();
+    unsigned c_sub = time_sub();
+    unsigned c_sub2 = time_sub2();
+    unsigned c_dab = time_dab();
+    unsigned c_hex = time_hex();
+    vic.ctrl1 |= 0x10;
+
+    put_text(11, 0, "CYCLES, BODY ONLY (CIA1 TIMER A)");
+    show_cycles(12, "SUB16 65535", c_sub, base);
+    show_cycles(13, "SUB16 59999", c_sub2, base);
+    show_cycles(14, "DAB16 65535", c_dab, base);
+    show_cycles(15, "HEX8  $FF  ", c_hex, base);
+    show_cycles(16, "NULL CALL  ", base, 0);
+
+
+    // Exhaustive checks: every value through both decimal routes, all 256
+    // bytes through the hex route, each field folded into a checksum.
+    unsigned chk_sub = 0, chk_dab = 0, chk_hex = 0;
+    char buf[5];
+    unsigned n = 0;
+    do
+    {
+        fmt_dec_sub(n, buf);
+        for (char i = 0; i < 5; i++) chk_sub = fold(chk_sub, buf[i]);
+        fmt_dec_dab(n, buf);
+        for (char i = 0; i < 5; i++) chk_dab = fold(chk_dab, buf[i]);
+    } while (++n != 0);
+    for (unsigned h = 0; h < 256; h++)
+    {
+        fmt_hex8((char)h, buf);
+        for (char i = 0; i < 4; i++) chk_hex = fold(chk_hex, buf[i]);
+    }
+
+    put_text(7, 0, "SUB 0-65535 CHK      EXP      ");
+    put_hex16(7, 16, chk_sub); put_hex16(7, 25, EXPECT_DEC);
+    put_text(7, 30, chk_sub == EXPECT_DEC ? "PASS" : "FAIL");
+    put_text(8, 0, "DAB 0-65535 CHK      EXP      ");
+    put_hex16(8, 16, chk_dab); put_hex16(8, 25, EXPECT_DEC);
+    put_text(8, 30, chk_dab == EXPECT_DEC ? "PASS" : "FAIL");
+    put_text(9, 0, "HEX 0-255   CHK      EXP      ");
+    put_hex16(9, 16, chk_hex); put_hex16(9, 25, EXPECT_HEX);
+    put_text(9, 30, chk_hex == EXPECT_HEX ? "PASS" : "FAIL");
+
+    for (;;) ;
+    return 0;
+}
+```
+
+## Build
+
+```bash
+oscar64 -tm=c64 -O2 -o=print-number.prg print-number.c
+```
+
+Then run headless (PAL; add `-model ntsc` for NTSC):
+
+```bash
+GSETTINGS_SCHEMA_DIR=/opt/homebrew/share/glib-2.0/schemas timeout 120 x64sc -default -warp +sound +autostart-delay-random -autostartprgmode 1 -limitcycles 400000000 -exitscreenshot print-number.png -autostart print-number.prg
+```
+
+The cycle limit is 400,000,000 because the exhaustive loop runs both
+decimal routes 65,536 times, about 4,000 cycles a pass with the checksum
+folds (rung 3, from the measured routine costs); at 300,000,000 a first
+version, which blanked the display for the whole check, exited with the
+screen still blank.
+
+## Expected output
+
+`screenshots/print-number.png` (PAL) and `screenshots/print-number-ntsc.png`
+(NTSC), both read cell by cell against the character ROM. Light blue
+text on the default blue screen:
+
+```
+PRINT NUMBER
+
+DEC 0      [    0]
+DEC 7      [    7]
+DEC 65535  [65535]
+HEX $A5    [ $A5]
+
+SUB 0-65535 CHK 0EB2 EXP 0EB2 PASS
+DAB 0-65535 CHK 0EB2 EXP 0EB2 PASS
+HEX 0-255   CHK 263C EXP 263C PASS
+
+CYCLES, BODY ONLY (CIA1 TIMER A)
+SUB16 65535   957
+SUB16 59999  1361
+DAB16 65535  2537
+HEX8  $FF      74
+NULL CALL      17
+```
+
+The three checksums are the fold `chk = ((chk ^ byte) * 5 + 1) & 0xFFFF`
+over every byte of every field, in order. In Python:
+
+```python
+def fold(chk, v): return ((chk ^ v) * 5 + 1) & 0xffff
+chk = 0
+for n in range(65536):
+    for b in str(n).rjust(5).encode('ascii'):
+        chk = fold(chk, b)
+print(hex(chk))            # 0xeb2
+hexg = [0x30 + i for i in range(10)] + [1, 2, 3, 4, 5, 6]
+chk = 0
+for n in range(256):
+    for b in [0x20, 0x24, hexg[n >> 4], hexg[n & 15]]:
+        chk = fold(chk, b)
+print(hex(chk))            # 0x263c
+```
+
+The decimal fold works on the ASCII bytes of `str(n).rjust(5)` because
+screen codes for `0`-`9` and space are `$30`-`$39` and `$20`, the same
+as ASCII. The hex fold has to spell the screen codes out, because `A`-`F`
+are `$01`-`$06` on screen and not their ASCII values. Both decimal routes
+reach the same checksum, which is the point of running two: they agree on
+all 327,680 output bytes.
+
+The cycle figures are the value of CIA1 timer A after each call, less
+the 17 cycles of the same sequence around an empty function, so they are
+the body of the routine without its `JSR` and `RTS`. The PAL and NTSC
+runs give identical figures (rung 1, VICE x64sc 3.10). 59999 is the
+worst case for subtract-powers (digit sum 5 + 9 + 9 + 9, thirty-two
+subtractions); the double-dabble's cost does not depend on the value.
+A build with different code placement read 953 and 2,533 for the first
+and third lines, so treat the last few cycles as layout, not routine.
+
+## Why this works
+
+`fmt_dec_sub` walks the powers 10000, 1000, 100, 10 and counts how many
+times each can be taken from the value; the count plus `$30` is the
+digit's screen code, and what is left after the last power is the units
+digit. `lead` stays set until the first non-zero digit, and while it is
+set a zero writes `$20` instead of `$30`, which gives zero suppression and
+right alignment in one move because the field width is fixed. The last
+digit is written unconditionally so that 0 prints as `0`. For an
+arcade-style score with leading zeros, drop the `lead` test.
+
+`fmt_dec_dab` is the textbook double-dabble: shift the bits in from the
+top, and before each shift add 3 to any BCD nibble that is 5 or more so
+that the shift carries a 10 out of it. On the 6502 the same algorithm is
+much cheaper in assembly with `SED`, where `adc` of a byte to itself
+doubles a packed BCD pair and adjusts it for free; C cannot set decimal
+mode, so the nibble version pays for every test and lands at 2.6 times
+the cost of subtract-powers. Use `fmt_dec_sub` from C, and if a fixed
+cost matters more than the average, call an assembly double-dabble
+through `__asm` (the KickAssembler `dab_u16` listing under "Printing
+numbers" in `game-design/game-design-patterns.md` measured 875 cycles for
+any value).
+
+The timing harness stops timer A, writes `$FFFF` to the latch, and
+restarts it with a force load (`cra = $11`), so the count starts from a
+known value; it stops the timer again before reading the two bytes so
+the read cannot straddle a borrow from low to high. The display is
+blanked during the timing, and the program then waits for the next frame
+before starting, because the VIC-II samples the DEN bit once per frame,
+on line `$30` (VIC-II documentation, not measured here; what was measured
+is that the wait closes the 9 per cent NTSC gap): a first version that
+blanked and timed at once read 9 per cent higher on NTSC, where the run
+happened to start mid-frame and the badlines of that frame were still
+stealing cycles. With the wait, PAL and NTSC agree to the cycle.
+
+Everything is written as screen codes at `$0400` with no KERNAL call:
+`put_text` folds ASCII upper case to screen codes by subtracting 64 and
+maps `[` and `]` to `$1B` and `$1D`; digits and `$` need no translation.
+The KERNAL IRQ is switched off with `sei` so the jiffy handler does not
+run inside the timed region or reprogram the timer (the KERNAL uses CIA1
+timer A for its 60 Hz tick).

package/docs/recipes/oscar64/raster-bars.md

@@ -0,0 +1,239 @@
+---
+recipe: raster-bars
+toolchain: oscar64
+output_format: PRG
+region: both
+techniques: [raster_bars, stable_raster_irq]
+file_formats: [PRG]
+uses_registers: [D012, D019, D020, D021]
+uses_kernal: []
+---
+
+<!-- doc-type: recipe -->
+
+# Oscar64 Raster Color Bars
+
+## Synopsis
+
+Fifteen color bars cycling down the screen, one per raster split, using
+`rasterirq.h`. Each bar changes both the border color (`$D020`) and the
+background color (`$D021`) for its band. The bars shift upward by one slot
+every two frames, producing a smooth rainbow animation. This recipe builds
+directly on `stable-raster-irq.md` and shows how multiple `RIRQCode` slots
+compose into a full multi-split raster effect.
+
+## Source
+
+```c
+// raster-bars.c
+#include <c64/vic.h>
+#include <c64/rasterirq.h>
+
+// 16 C64 palette entries in rainbow order. Names match Oscar64's c64/vic.h
+// enum exactly — note PURPLE (not VIOLET) and DARK_GREY (no plain GREY).
+// Index 16 duplicates index 0; the animation loop indexes with `& 15`, so
+// the sentinel is never read and is kept only for a plain-loop variant.
+static const byte rainbow[17] = {
+    VCOL_BLACK, VCOL_BROWN, VCOL_RED, VCOL_ORANGE,
+    VCOL_YELLOW, VCOL_LT_GREEN, VCOL_GREEN, VCOL_CYAN,
+    VCOL_LT_BLUE, VCOL_BLUE, VCOL_PURPLE, VCOL_LT_RED,
+    VCOL_DARK_GREY, VCOL_MED_GREY, VCOL_LT_GREY, VCOL_WHITE,
+    VCOL_BLACK   // sentinel wrap
+};
+
+// Number of visible bars. Each bar is one rirq slot that writes D020 + D021.
+// 15 bars plus the reset slot below = 16 slots, the library's NUM_IRQS.
+#define NUM_BARS  15
+
+// Bar height in raster lines: 15 bars * 13 lines = 195 of the 200 visible.
+#define BAR_HEIGHT  13
+
+// First raster line for the top bar (just below the top border on PAL).
+#define FIRST_LINE  51
+
+// One RIRQCode per bar. Each struct holds two writes (border + background).
+RIRQCode bars[NUM_BARS];
+
+// A final slot that resets both registers after the last bar, so the
+// area below the bars returns to black before the next frame begins.
+RIRQCode reset_slot;
+
+int main(void)
+{
+    // Standard rasterirq init: route through KERNAL vector, CIA disabled.
+    rirq_init(true);
+
+    // Build each bar slot with two writes: D020 (border) and D021 (background).
+    for (char i = 0; i < NUM_BARS; i++) {
+        rirq_build(&bars[i], 2);
+        rirq_write(&bars[i], 0, &vic.color_border, rainbow[i]);
+        rirq_write(&bars[i], 1, &vic.color_back,   rainbow[i]);
+        // Fire one line before the start of this bar's visible region.
+        rirq_set(i, FIRST_LINE + (char)(i * BAR_HEIGHT) - 1, &bars[i]);
+    }
+
+    // The reset slot fires after the last bar and sets both colors to black,
+    // so the area between the last bar and the frame bottom is clean. Same
+    // "one line early" rule as the bars: without the -1 the last bar is 14
+    // lines tall, which is what the earlier version of this recipe drew.
+    rirq_build(&reset_slot, 2);
+    rirq_write(&reset_slot, 0, &vic.color_border, VCOL_BLACK);
+    rirq_write(&reset_slot, 1, &vic.color_back,   VCOL_BLACK);
+    rirq_set(NUM_BARS, FIRST_LINE + NUM_BARS * BAR_HEIGHT - 1, &reset_slot);
+
+    rirq_sort();
+    rirq_start();
+
+    // Animation: shift the color palette index each frame so the bars appear
+    // to scroll upward. 'offset' cycles through 0..15.
+    char offset = 0;
+    char frame  = 0;
+
+    for (;;) {
+        // Wait until all raster IRQs for this frame have fired, then update
+        // the palette before rirq_sort re-arms for the next frame.
+        rirq_wait();
+
+        // Advance the color offset every two frames (25 Hz on PAL, 30 Hz NTSC).
+        frame++;
+        if (frame >= 2) {
+            frame = 0;
+            offset = (offset + 1) & 15;
+        }
+
+        // Repatch each bar's color data in-place using rirq_data.
+        // rirq_data only writes the data byte of an existing slot — it does
+        // not touch the target address or rebuild the slot. This is the
+        // fastest way to animate raster IRQ content.
+        for (char i = 0; i < NUM_BARS; i++) {
+            byte c = rainbow[(offset + i) & 15];
+            rirq_data(&bars[i], 0, c);  // border
+            rirq_data(&bars[i], 1, c);  // background
+        }
+
+        // Re-sort is not needed here because no slot has moved.
+        // rirq_sort() would be required if rirq_move() had been called.
+    }
+
+    return 0;
+}
+```
+
+## Build
+
+```bash
+oscar64 -o=raster-bars.prg -tf=prg raster-bars.c
+```
+
+Produces `raster-bars.prg` plus the usual `.map`, `.asm`, and `.lbl` side files.
+Load with `LOAD"RASTER-BARS",8,1 : RUN` or via VICE autostart.
+
+## Expected output
+
+Fifteen horizontal color bands fill the display area, each 13 raster lines
+tall, cycling through the C64 16-color palette. The entire stack of bars
+drifts upward smoothly at half the frame rate (one color step every two
+frames). Below the bar stack the border and background are black. The color
+boundaries are straight horizontal lines, with two exceptions: the bars that
+begin on lines 51 and 155 start on badlines, and on those two lines the
+background write (sometimes the border write too) lands after the display
+window has been drawn, so that one row keeps the previous bar's colour under
+an already-changed border. See "Badline interaction" below. The program does
+not clear the screen, so the BASIC start-up text stays visible in light blue
+on top of the bars.
+
+Verified with Oscar64 (build 2026-05-19) and VICE x64sc after the slot-count
+fix described below. Measured on the PAL render of 2026-09-22: fifteen bands
+on lines 51-245, each 13 lines (the earlier listing set the reset slot one
+line late and drew the last bar 14 lines tall, 233-246), black from line 246
+down, line 155 showing a cyan border over a still-green display row.
+
+On PAL (50 Hz) the palette completes one full cycle in 32 frames (0.64 seconds).
+On NTSC (60 Hz) the same 32-frame cycle completes in 0.53 seconds, running
+slightly faster.
+
+## Why this works
+
+### Foundation: stable raster IRQ
+
+This recipe is a direct extension of `stable-raster-irq.md`. Every slot in the
+`bars` array is entered on the line above its target and spins on `CMP $D012`
+until the target line begins. The loop exits within the first 1-7 cycles of
+the target line, the first write (`STY $D020`) completes by about cycle 12
+and the second (`STX $D021`) by about cycle 16, per the cycle comment above
+`rirq_build` in `rasterirq.c` and the opcodes it emits; both are before the display window opens, and
+the rendered edges are straight on every non-badline boundary. (This text
+used to say both writes complete by about cycle 12; that is only the first
+one.) See that recipe for what the library does and does not guarantee. The `rirq_init(true)` call disables CIA timer interrupts and
+installs the dispatcher through the KERNAL vector. Without the polling loop,
+each bar boundary would show a step two-thirds of the way across its first
+line.
+
+### Multiple slots: the rirq slot table
+
+`rasterirq.h` maintains a sorted table of `NUM_IRQS` IRQ slots, 16 by
+default. After `rirq_sort()`, the dispatcher walks this table on every frame,
+firing each slot when the raster beam reaches the programmed line. Oscar64's
+own `colorbars.c` sample uses exactly this pattern with 15 slots. This recipe
+uses 15 bars plus a reset slot: 16, the whole table.
+
+The earlier version of this recipe used 16 bars plus the reset slot.
+`rirq_set(16, ...)` wrote one entry past a 16-entry table, the program fell
+back to BASIC with no bars drawn, and nothing reported an error: there is no
+bounds check in `rirq_set`. A `#define NUM_IRQS 17` at the top of the main
+file does not fix it either, and that was tried: `rasterirq.c` is compiled
+as its own translation unit through the header's `#pragma compile`, so it
+sees the default 16 while the main file believes 17. To change the table
+size, pass `-dNUM_IRQS=17` on the command line so every unit agrees, or stay
+within 16.
+
+Each `RIRQCode` holds two write slots (border and background). Two writes per
+slot consume 8 cycles (`STY abs` then `STX abs`, 4 cycles each). With
+`BAR_HEIGHT = 13`, there are 13 raster lines between each consecutive pair of
+slots (this section said 12 while the listing said 13; 13 is what the code
+builds and what the render shows), giving the dispatcher ample time to exit
+one IRQ and enter the next. The minimum safe gap between two slots is
+approximately 4-5 raster lines on PAL, accounting for IRQ entry/exit
+overhead; that figure is an estimate and was not measured here.
+
+### `rirq_data` for animation without rebuilding
+
+`rirq_data(&bars[i], slot, byte)` patches only the data byte of write slot
+`slot` inside an existing `RIRQCode`. This is cheaper than calling `rirq_write`
+because it does not touch the target address. For animation where only the color
+value changes each frame — as in the cycling palette here — `rirq_data` is the
+correct tool. The address half of each slot (pointing at `$D020` and `$D021`)
+never changes; only the color index rotates.
+
+### D020 vs D021: border and background
+
+$D020 is the border color. It governs the colored region outside the active
+display window. $D021 is background color 0, which fills the background of
+each character cell in standard text mode (and all cells in blank/space
+characters). Writing both registers to the same color makes the entire visible
+area — border and display — appear as a solid horizontal band. Writing only
+$D020 would color the border stripe while leaving the display interior at its
+previous background color, useful for thinner decorative bars. Writing only
+$D021 would change the display area interior without touching the border.
+
+### Badline interaction
+
+Badlines occur every 8 raster lines on PAL (when the low 3 bits of the raster
+counter match YSCROLL, default 3). On a badline the VIC-II takes the bus for
+cycles 15-54 and pulls BA low on cycle 12, so the CPU loses 40-43 cycles;
+plan on 43 (this text said a flat 40; see `docs/pitfalls/raster-and-badline.md`).
+For this recipe the poll loop exits in cycles 1-7 of the target line and the
+6510 is halted at its first read after BA has been low for three cycles, so
+a write that has not completed by cycle 14 waits until cycle 55 or later —
+after the display window, and in the right border. The standard defense is
+to target splits at non-badline rows. With `FIRST_LINE = 51` and
+`BAR_HEIGHT = 13` that is not fully possible: 13 is coprime to 8, so the
+fifteen boundaries cover every residue and two of them are badlines whatever
+`FIRST_LINE` is chosen — with 51, the bars starting on lines 51 and 155
+(this text used to say
+`BAR_HEIGHT = 12` and "the visual result is clean"; the render shows the
+background write landing late on both lines, and on line 51 the border
+write too in one of two runs). A bar height that is a multiple of 8 keeps
+every boundary on one residue so a single `FIRST_LINE` clears them all. For
+pixel-perfect bar boundaries on any line, use the cycle-exact double-IRQ
+technique described in `docs/techniques/raster.md`.