@8bitscript/c64 0.1.0

package/src/bitmap.8bs

@@ -0,0 +1,175 @@
+// @8bitscript/c64/bitmap — the VIC-II's bitmap modes: 320x200 pixels, or
+// 160x200 in four colours.
+//
+// Named by "8bitscript".exports["./bitmap"] in this package's package.json:
+//
+//     import { bitmap } from "@8bitscript/c64/bitmap";
+//
+//     bitmap.enter(false);            // hi-res: 320x200, two colours a cell
+//     bitmap.clear();
+//     bitmap.fillColors(1, 0);        // white on black, every cell
+//     for (let x: usmallint = 0; x < 320; x++) {
+//         bitmap.plot(x, x >> 1);     // a line
+//     }
+//     ...
+//     bitmap.leave();                 // text mode again
+//
+// Hardware-level, C64-only surface, the layer a portable canvas
+// capability (docs/systems.md's bitmap rung) will sit on. The bitmap is
+// 8000 bytes at $E000, laid out the VIC's way: 8 bytes a cell (one a
+// pixel row), 40 cells a row, 25 rows — so pixel (x, y) is bit `7 - x % 8`
+// of byte `(y / 8) * 320 + (x / 8) * 8 + y % 8`, which `offset` computes
+// with a row table and masks, no multiply. Where the picture is, and
+// why the colour matrix is under the I/O area, is ./geometry.8bs's story
+// (the `Bitmap` namespace).
+//
+// ---- colours ----------------------------------------------------------------
+//
+// Hi-res: a set bit shows the cell's high nybble, a clear bit its low
+// nybble, both from the colour matrix — sixteen colours, two per 8x8
+// cell. Multicolour: pixels are pairs of bits, twice as wide (x 0-159),
+// %00 the background register ($D021, screen.setBackground), %01 the
+// matrix's high nybble, %10 its low nybble, %11 the cell's colour RAM
+// nybble — four colours a cell, three of them per cell.
+//
+// The colour matrix is RAM under the I/O area, so a matrix write is a
+// window with I/O banked out (writeUnderIo in ./index.8bs): `setCellColors`
+// is one such window, `fillColors` is one window for all thousand cells —
+// about 15000 cycles, most of a frame — and with the raster interrupt on,
+// that frame's entries wait for it. Colour RAM is I/O and written freely.
+//
+// ---- sprites over a bitmap --------------------------------------------------
+//
+// The sprite pointers move with the screen matrix, to $DFF8 under the I/O
+// area; sprites.setShape() knows (it reads `videoMode`). The shape blocks
+// at $E400 are the bitmap now, so a sprite over a bitmap draws from blocks
+// 96-111 at $D800 (Bitmap.SHAPE_BLOCK_FIRST/SHAPE_COUNT), written with
+// sprites.setShapeByte(), which writes under the I/O area for those.
+//
+// ---- text and bitmap ----------------------------------------------------------
+//
+// One or the other. `enter` switches the VIC to the bitmap over the same
+// $E000 RAM the text screen used, and `leave` switches back — the text is
+// gone, the bitmap is what the screen matrix now holds (screen.blank()
+// clears it). @8bitscript/text writes screen codes into the bitmap while
+// this mode is on; nothing stops it, and it draws noise.
+import {
+    control1, control2, memoryPointer, setupVideo, videoMode, VideoMode,
+    bankIoOut, bankIoIn, writeUnderIo,
+} from "./index.8bs";
+import { Video, Bitmap, bitmapRam, colorRam } from "./geometry.8bs";
+
+// Byte offset of each cell row's first byte: row * 320.
+const ROW_OFFSET: array<usmallint, 25> = [
+    0, 320, 640, 960, 1280, 1600, 1920, 2240, 2560, 2880, 3200, 3520, 3840,
+    4160, 4480, 4800, 5120, 5440, 5760, 6080, 6400, 6720, 7040, 7360, 7680,
+];
+// Hi-res: the bit of pixel x % 8, left to right.
+const BIT: array<utinyint, 8> = [128, 64, 32, 16, 8, 4, 2, 1];
+const NOT_BIT: array<utinyint, 8> = [127, 191, 223, 239, 247, 251, 253, 254];
+// Multicolour: the two bits of pixel x % 4, and a colour 0-3 shifted into them
+// (index (x % 4) * 4 + colour).
+const PAIR_MASK: array<utinyint, 4> = [0x3F, 0xCF, 0xF3, 0xFC];
+const PAIR_BITS: array<utinyint, 16> = [
+    0x00, 0x40, 0x80, 0xC0,
+    0x00, 0x10, 0x20, 0x30,
+    0x00, 0x04, 0x08, 0x0C,
+    0x00, 0x01, 0x02, 0x03,
+];
+const PAIR_SHIFT: array<utinyint, 4> = [6, 4, 2, 0];
+
+export namespace bitmap {
+    const WIDTH: usmallint = 320; // hi-res pixels across
+    const HEIGHT: utinyint = 200;
+    const MULTICOLOR_WIDTH: utinyint = 160; // multicolour pixels across
+    const BYTES: usmallint = 8000;
+
+    // Bitmap mode on, hi-res or multicolour, over whatever the RAM holds.
+    function enter(multicolor: bool): void {
+        setupVideo();
+        videoMode = VideoMode.BITMAP;
+        // Bits 0-4 (YSCROLL, RSEL, DEN) kept, ECM off, BMM on, and bit 7 —
+        // the raster compare's ninth bit on a write — clear.
+        control1 = (control1 & 0x1F) | 0x20;
+        if (multicolor) {
+            control2 = control2 | 0x10;
+        } else {
+            control2 = control2 & 0xEF;
+        }
+        memoryPointer = Bitmap.MEMORY_POINTER;
+    }
+
+    // Text mode again: the screen matrix at $E000 over the upper-case set.
+    function leave(): void {
+        control1 = control1 & 0x1F;
+        control2 = control2 & 0xEF;
+        memoryPointer = Video.MEMORY_POINTER_UPPERCASE;
+        videoMode = VideoMode.TEXT;
+    }
+
+    // Every pixel clear (`bits` 0) or set (255), or any pattern byte.
+    function clear(bits: utinyint = 0): void {
+        for (let i: usmallint = 0; i < Bitmap.BYTES; i++) {
+            bitmapRam[i] = bits;
+        }
+    }
+
+    // The byte holding hi-res pixel (x, y): see the header.
+    function offset(x: usmallint, y: utinyint): usmallint {
+        return ROW_OFFSET[y >> 3] + (x & 0x1F8) + (y & 7);
+    }
+
+    function plot(x: usmallint, y: utinyint): void {
+        let at: usmallint = bitmap.offset(x, y);
+        bitmapRam[at] = bitmapRam[at] | BIT[x & 7];
+    }
+
+    function unplot(x: usmallint, y: utinyint): void {
+        let at: usmallint = bitmap.offset(x, y);
+        bitmapRam[at] = bitmapRam[at] & NOT_BIT[x & 7];
+    }
+
+    function point(x: usmallint, y: utinyint): bool {
+        return (bitmapRam[bitmap.offset(x, y)] & BIT[x & 7]) != 0;
+    }
+
+    // Multicolour pixel (x 0-159, y) set to `color` 0-3 (see the header).
+    function plotColor(x: utinyint, y: utinyint, color: utinyint): void {
+        let at: usmallint = ROW_OFFSET[y >> 3] + ((x & 0xFC) << 1) + (y & 7);
+        let pair: utinyint = x & 3;
+        bitmapRam[at] = (bitmapRam[at] & PAIR_MASK[pair]) | PAIR_BITS[pair * 4 + (color & 3)];
+    }
+
+    // The colour 0-3 of multicolour pixel (x, y).
+    function pointColor(x: utinyint, y: utinyint): utinyint {
+        let at: usmallint = ROW_OFFSET[y >> 3] + ((x & 0xFC) << 1) + (y & 7);
+        return (bitmapRam[at] >> PAIR_SHIFT[x & 3]) & 3;
+    }
+
+    // Cell `cell` (row * 40 + column): the colour of set bits and of clear
+    // bits (hi-res), or of %01 and %10 pixels (multicolour).
+    function setCellColors(cell: usmallint, foreground: utinyint, background: utinyint): void {
+        writeUnderIo(Bitmap.MATRIX + cell, (foreground << 4) | (background & 15));
+    }
+
+    // The same pair for every cell, in one window.
+    function fillColors(foreground: utinyint, background: utinyint): void {
+        let pair: utinyint = (foreground << 4) | (background & 15);
+        bankIoOut();
+        for (let cell: usmallint = 0; cell < Video.CELL_COUNT; cell++) {
+            memory.write(Bitmap.MATRIX + cell, pair);
+        }
+        bankIoIn();
+    }
+
+    // Multicolour's third colour per cell (%11), from colour RAM.
+    function setCellColor3(cell: usmallint, color: utinyint): void {
+        colorRam[cell] = color & 15;
+    }
+
+    function fillColor3(color: utinyint): void {
+        for (let cell: usmallint = 0; cell < Video.CELL_COUNT; cell++) {
+            colorRam[cell] = color & 15;
+        }
+    }
+}

package/src/charset.8bs

@@ -0,0 +1,142 @@
+// @8bitscript/c64/charset — the character set is RAM: redefine it.
+//
+// Named by "8bitscript".exports["./charset"] in this package's package.json:
+//
+//     import { charset } from "@8bitscript/c64/charset";
+//
+//     // Screen code 1 ('A' as text prints it) becomes a solid block with a hole.
+//     charset.define(1, 0xFF, 0x81, 0x81, 0x81, 0x81, 0x81, 0x81, 0xFF);
+//     charset.copy(2, 1);             // and code 2 the same
+//     charset.restore();              // the ROM's glyphs again
+//
+// The set the VIC draws text from is this package's copy of the character
+// ROM in the RAM under the I/O area ($D000, ./geometry.8bs), and a copy is
+// writable: a program's own tiles, a font, a map's terrain are glyphs
+// written over the ROM's, each 8 bytes — one byte a pixel row, bit 7 the
+// left pixel — at `Video.CHARSET + 8 * code`. The upper-case set (256
+// glyphs at $D000-$D7FF) is the one @8bitscript/text selects on every
+// print, so it is the one to define into: codes 1-26 are what text prints
+// for 'A'-'Z', 32-63 the digits and punctuation, 64-127 the graphics, and
+// 128-255 the same in reverse video. A program that never prints text is
+// free to use all 256.
+//
+// Every write here is a window with the I/O area banked out (./index.8bs,
+// writeUnderIo): `define` is one window for a glyph's 8 bytes, `copy`
+// one for 8 reads and 8 writes. With the raster interrupt on, each window
+// is a few dozen cycles that frame's entries wait for; `restore` is a
+// second ROM copy (about four frames of window) — do it before
+// raster.enable(), or accept the frame.
+//
+// Multicolour text ($D016 bit 4, `charset.setMulticolor`): in a cell whose
+// colour RAM nybble has bit 3 set, pixels are pairs — %00 the background,
+// %01 $D022, %10 $D023, %11 the low three bits of the cell's colour — and
+// a cell without bit 3 is drawn hi-res in that colour, so one screen mixes
+// both. `useLowercase` selects the ROM's other set at $D800 for a program
+// that wants it; @8bitscript/text's next print selects upper-case again.
+import {
+    control2, memoryPointer, backgroundColor1, backgroundColor2,
+    setupVideo, copyCharacterRom, videoMode, VideoMode, bankIoOut, bankIoIn, readUnderIo,
+} from "./index.8bs";
+import { Video } from "./geometry.8bs";
+
+export namespace charset {
+    const COUNT: usmallint = 256;
+    const BYTES: utinyint = 8; // a glyph: one byte a row
+
+    // Where glyph `code`'s 8 bytes start, in the upper-case set.
+    function offset(code: utinyint): usmallint {
+        return Video.CHARSET + code * 8;
+    }
+
+    // Glyph `code` becomes the eight rows given, top to bottom.
+    function define(code: utinyint, row0: utinyint, row1: utinyint, row2: utinyint, row3: utinyint, row4: utinyint, row5: utinyint, row6: utinyint, row7: utinyint): void {
+        setupVideo();
+        let at: usmallint = charset.offset(code);
+        bankIoOut();
+        memory.write(at, row0);
+        memory.write(at + 1, row1);
+        memory.write(at + 2, row2);
+        memory.write(at + 3, row3);
+        memory.write(at + 4, row4);
+        memory.write(at + 5, row5);
+        memory.write(at + 6, row6);
+        memory.write(at + 7, row7);
+        bankIoIn();
+    }
+
+    // One row of glyph `code`.
+    function setRow(code: utinyint, row: utinyint, bits: utinyint): void {
+        setupVideo();
+        bankIoOut();
+        memory.write(charset.offset(code) + (row & 7), bits);
+        bankIoIn();
+    }
+
+    // Read one row back.
+    function readRow(code: utinyint, row: utinyint): utinyint {
+        setupVideo();
+        return readUnderIo(charset.offset(code) + (row & 7));
+    }
+
+    // Glyph `target` becomes a copy of glyph `source`.
+    function copy(target: utinyint, source: utinyint): void {
+        setupVideo();
+        let sourceAt: usmallint = charset.offset(source);
+        let targetAt: usmallint = charset.offset(target);
+        bankIoOut();
+        for (let i: utinyint = 0; i < 8; i++) {
+            memory.write(targetAt + i, memory.read(sourceAt + i));
+        }
+        bankIoIn();
+    }
+
+    // Every row of glyph `code` the same byte: 0 blank, 255 solid.
+    function fill(code: utinyint, bits: utinyint): void {
+        setupVideo();
+        let at: usmallint = charset.offset(code);
+        bankIoOut();
+        for (let i: utinyint = 0; i < 8; i++) {
+            memory.write(at + i, bits);
+        }
+        bankIoIn();
+    }
+
+    // The ROM's glyphs again, both sets — all 4K under the I/O area, so
+    // in bitmap mode this also overwrites the colour matrix and the shape
+    // blocks that live there: leave bitmap mode first.
+    function restore(): void {
+        setupVideo();
+        copyCharacterRom();
+    }
+
+    // Multicolour text mode on or off (see the header).
+    function setMulticolor(on: bool): void {
+        if (on) {
+            control2 = control2 | 0x10;
+        } else {
+            control2 = control2 & 0xEF;
+        }
+    }
+
+    // The two shared multicolour text colours ($D022, $D023).
+    function setSharedColors(color1: utinyint, color2: utinyint): void {
+        backgroundColor1 = color1 & 15;
+        backgroundColor2 = color2 & 15;
+    }
+
+    // The ROM's lower-case set (text mode only; the next text print
+    // selects upper-case again).
+    function useLowercase(): void {
+        setupVideo();
+        if (videoMode == VideoMode.TEXT) {
+            memoryPointer = Video.MEMORY_POINTER_LOWERCASE;
+        }
+    }
+
+    function useUppercase(): void {
+        setupVideo();
+        if (videoMode == VideoMode.TEXT) {
+            memoryPointer = Video.MEMORY_POINTER_UPPERCASE;
+        }
+    }
+}

package/src/geometry.8bs

@@ -0,0 +1,116 @@
+// @8bitscript/c64 — where the picture lives: VIC bank 3, above the program.
+//
+// The VIC-II sees one 16K bank at a time, and everything it draws from —
+// the screen matrix, the character set, the sprite shapes, the eight
+// sprite pointers — has to be inside that one bank. The SDK links a
+// program into $0801-$CFFF (mos-platform/c64/lib/link.ld: `ram` is
+// ORIGIN $0801, LENGTH $C7FF, and the C stack grows down from $D000), and
+// it decides where every byte of code and data goes. Nothing the VIC
+// needs can be promised a place inside that region without a build-time
+// overlap check the toolchain does not have, so the picture lives in the
+// only RAM the linker never touches: $D000-$FFFF, the upper half of VIC
+// bank 3 ($C000-$FFFF). The VIC always reads RAM there — its two
+// character-ROM windows are in banks 0 and 2 ($1000 and $9000), not here —
+// and the CPU writes RAM there too: a store to $E000-$FFFF lands under the
+// KERNAL ROM whether the ROM is mapped or not.
+//
+//   $D000-$DFFF  the character ROM's 4K, copied into the RAM under the I/O
+//                area once at start-up (setupVideo() in ./index.8bs): the
+//                upper-case/graphics set at $D000, lower-case at $D800.
+//                The same offset ($1000) in the bank as the ROM window has
+//                in bank 0, so $D018's charset field is the ROM's own.
+//   $E000-$E3E7  the 40x25 screen matrix, one screen code per cell.
+//   $E3F8-$E3FF  the eight sprite pointers (screen + $3F8, a VIC rule).
+//   $E400-$FFBF  111 sprite shape blocks of 64 bytes, blocks 144-254 of
+//                the bank. Block 255 ($FFC0-$FFFF) is RAM too, but its
+//                last six bytes are the CPU's NMI/reset/IRQ vectors — RAM
+//                the CPU reads once the KERNAL is banked out, which
+//                native/6502/raster.s fills — so it is not a shape block.
+//
+// In bitmap mode (@8bitscript/c64/bitmap) the same bank holds, instead:
+//
+//   $E000-$FF3F  the 8000-byte bitmap (the second 8K of the bank: $D018
+//                bit 3 set), over the screen matrix and the shape blocks.
+//   $DC00-$DFE7  the colour matrix, one byte per cell — high nybble the
+//                colour of set bits, low nybble of clear bits (hi-res), or
+//                the %01 and %10 colours (multicolour) — in the RAM under
+//                the I/O area, where the CPU writes only with the area
+//                banked out (writeUnderIo in ./index.8bs). It is the second
+//                half of the lower-case set, which bitmap mode gives up;
+//                the upper-case set at $D000-$D7FF is untouched, so leaving
+//                bitmap mode is a register change, not a second ROM copy.
+//   $DFF8-$DFFF  the sprite pointers, matrix + $3F8 as always.
+//   $D800-$DBFF  16 shape blocks (96-111) for sprites over a bitmap, under
+//                the I/O area too (the first half of the lower-case set).
+//
+// The colour matrix could not go anywhere the CPU reaches freely: every
+// 1K slot of the bank is either the program's ($C000-$CFFF), the bitmap's
+// ($E000-$FFFF), or under the I/O area.
+//
+// Colour RAM does not move with the bank: it is the 1K of nybbles at $D800
+// in the I/O area, wherever the screen is. So a cell's colour is written
+// through I/O ($01 bit 2 set) while its character is written to RAM — the
+// normal state of the machine, and the state setupVideo() leaves it in.
+//
+// Screenshots of a program using this layout under x64sc (text from the
+// copied set, a sprite from block 144) are how these numbers were checked;
+// packages/c64/AGENTS.md has the table.
+
+// The addresses themselves, as this module's own consts: `@address` takes
+// a literal or a const declared beside it, so the arrays over the screen,
+// the colour RAM, the sprite pointers and the shape blocks are declared
+// here, where the numbers are, and `Video` names the same numbers for
+// everything else.
+const SCREEN_ADDRESS: usmallint = 0xE000;
+const COLOR_ADDRESS: usmallint = 0xD800;
+const SPRITE_POINTERS_ADDRESS: usmallint = 0xE3F8;
+const SHAPES_ADDRESS: usmallint = 0xE400;
+const BITMAP_ADDRESS: usmallint = 0xE000;
+
+// The screen matrix: 1000 screen codes, cell 0 top-left.
+@address(SCREEN_ADDRESS)
+export let screenRam: array<u8, 1000>;
+// Colour RAM: the low nybble of each byte is that cell's colour.
+@address(COLOR_ADDRESS)
+export let colorRam: array<u8, 1000>;
+// Sprite n's shape block: the VIC reads shape data from bank + 64 * pointer.
+@address(SPRITE_POINTERS_ADDRESS)
+export let spritePointers: array<u8, 8>;
+// The shape blocks, one array: block b's 63 bytes start at 64 * (b - 144).
+@address(SHAPES_ADDRESS)
+export let spriteShapes: array<u8, 7104>;
+// The bitmap, in bitmap mode: 8000 bytes, cell by cell (8 bytes a cell,
+// 40 cells a row — see @8bitscript/c64/bitmap's offset()). The same RAM
+// as the screen matrix and the shape blocks above.
+@address(BITMAP_ADDRESS)
+export let bitmapRam: array<u8, 8000>;
+
+export namespace Video {
+    const BANK: usmallint = 0xC000; // VIC bank 3, selected through CIA2 port A bits 0-1 (= %00)
+    const SCREEN: usmallint = SCREEN_ADDRESS; // screen matrix: one screen code per cell
+    const COLOR: usmallint = COLOR_ADDRESS; // colour RAM: one nybble per cell, same cell index, never moves
+    const CHARSET: usmallint = 0xD000; // the character ROM's copy in RAM: upper-case set here, lower-case at +$0800
+    const SPRITE_POINTERS: usmallint = SPRITE_POINTERS_ADDRESS; // eight bytes: shape block per sprite (address / 64 within the bank)
+    const SHAPES: usmallint = SHAPES_ADDRESS; // first sprite shape block
+    const SHAPE_BLOCK_FIRST: utinyint = 144; // (SHAPES - BANK) / 64
+    const SHAPE_COUNT: utinyint = 111; // blocks 144-254
+    const MEMORY_POINTER_UPPERCASE: utinyint = 0x84; // $D018: screen at bank+$2000 (bits 4-7 = 8), charset at bank+$1000 (bits 1-3 = 2)
+    const MEMORY_POINTER_LOWERCASE: utinyint = 0x86; // the same screen, the lower-case set at bank+$1800
+    const COLUMNS: utinyint = 40;
+    const ROWS: utinyint = 25;
+    const CELL_COUNT: usmallint = 1000; // COLUMNS * ROWS
+}
+
+// Bitmap mode's layout, in the same bank; see the header.
+export namespace Bitmap {
+    const ADDRESS: usmallint = BITMAP_ADDRESS; // 8000 bytes, bank + $2000
+    const BYTES: usmallint = 8000;
+    const WIDTH: usmallint = 320; // pixels, hi-res
+    const HEIGHT: utinyint = 200;
+    const MATRIX: usmallint = 0xDC00; // the colour matrix, under the I/O area: bank + $1C00
+    const SPRITE_POINTERS: usmallint = 0xDFF8; // MATRIX + $3F8
+    const SHAPES: usmallint = 0xD800; // 16 shape blocks under the I/O area
+    const SHAPE_BLOCK_FIRST: utinyint = 96; // (SHAPES - BANK) / 64
+    const SHAPE_COUNT: utinyint = 16; // blocks 96-111
+    const MEMORY_POINTER: utinyint = 0x78; // $D018: matrix at bank+$1C00 (bits 4-7 = 7), bitmap at bank+$2000 (bit 3)
+}