@8bitscript/c64 0.1.0

package/src/raster.8bs

@@ -0,0 +1,190 @@
+// @8bitscript/c64/raster — a list of register writes, each at a raster line.
+//
+// Named by "8bitscript".exports["./raster"] in this package's package.json:
+//
+//     import { raster, Register } from "@8bitscript/c64/raster";
+//
+//     raster.clear();
+//     raster.at(49, Register.BORDER, 0);         // black border over the picture
+//     raster.at(49, Register.BACKGROUND, 6);     // blue playfield
+//     raster.at(210, Register.BACKGROUND, 0);    // a black status area from line 210
+//     raster.at(210, Register.CONTROL_2, 0x08);  // ... that does not scroll
+//     raster.at(250, Register.BORDER, 2);        // red border below the picture
+//     raster.enable();
+//
+// The VIC-II can interrupt the CPU when the raster reaches a line, and a
+// program that changes a register there — border, background, the
+// character set, the scroll position, a sprite's coordinates — shows two
+// things on one screen: a playfield over a status bar, a fixed strip of
+// score under a scrolling world, sixteen objects from eight sprites. This
+// module is that, as a list: an entry says which line, which address,
+// which value, and the handler this package ships in assembly
+// (native/6502/raster.s) applies each at its line, every frame, with no
+// program code running in the interrupt at all. What it is not: a handler
+// of the program's own. 8bitscript has no function values, so nothing a
+// program writes can be named as the code to run at a line; a write list
+// covers colour splits, split scrolling, character-set and screen switches
+// (any $D018 value), and sprite multiplexing (rewriting a sprite's Y, X,
+// pointer and colour at a line, as entries), and a computed effect —
+// a sine border, a per-line colour cycle — is a list a program rebuilds
+// each frame, up to the 63 entries the list holds.
+//
+// ---- rules ----------------------------------------------------------------
+//
+// - Lines run 0-255 and entries are added in ascending order; `at` refuses
+//   a line below the last one, and a list full at 63 entries. Entries on
+//   the same line are applied together. The visible picture is lines
+//   50-249 (the first text row starts at 51 with the default YSCROLL);
+//   0-49 and 250-255 are border. On PAL the frame has 312 lines, on NTSC
+//   263: lines past 255 cannot be named, and are border on both.
+// - The write lands a few cycles into the line — the handler's entry
+//   (about 30 cycles) plus the instruction the interrupt interrupted (up
+//   to 7), plus, on a bad line (every eighth, from 51 with the default
+//   scroll: the VIC takes 40 of the line's 63 cycles), that. So a colour
+//   change at a line inside the picture shows a step partway across the
+//   line; put it on the line BEFORE the one that should look different,
+//   or in the border, or on a line the VIC is not fetching (not 51, 59,
+//   67, ...). Border and background writes at line 49 and 250 are clean.
+// - Rebuild the list between frames: right after waitFrame(), which is
+//   line 0 or so, before the first entry's line. The handler reads the
+//   list live; `at` writes an entry's four bytes before it counts it, so
+//   a frame never sees a half-written entry, but a list rebuilt while the
+//   raster is inside it applies part of the old list and part of the new,
+//   for that frame.
+// - `enable()` banks the KERNAL out (setupVideo() does; the CPU's vectors
+//   are then RAM, and this package's start-up code has already pointed
+//   them at a bare rti), silences both CIAs, acknowledges everything the
+//   VIC has pending, points the IRQ vector at the handler and runs `cli`.
+//   From then on, `interruptsOn` in @8bitscript/c64 is true, and every
+//   window the package opens with the I/O area banked out (a write under
+//   it: the character set, the bitmap's colour matrix) is an interrupt-
+//   free window — the handler cannot acknowledge $D019 through RAM. A
+//   long window (bitmap.fillColors, charset.restore) delays that frame's
+//   entries by its length; do those before `enable()`, or between frames
+//   and accept the frame.
+// - The handler touches A, X and the list's three state bytes at
+//   $0300-$0302, and nothing else: no zero page, no register but $D012 and
+//   $D019 besides the entries' own. It costs about 30 cycles plus 25 per
+//   entry, out of a frame's 17000-19000.
+import {
+    control1, raster as rasterCompare, interruptStatus, interruptMask,
+    cia1InterruptControl, cia2InterruptControl, setupVideo, interruptsOn,
+} from "./index.8bs";
+
+// The list, where native/6502/raster.s reads it. Four bytes an entry:
+// line, address low, address high, value; then the three state bytes.
+const LIST_ADDRESS: usmallint = 0x0200;
+const END_ADDRESS: usmallint = 0x0300;
+const INDEX_ADDRESS: usmallint = 0x0301;
+
+@address(LIST_ADDRESS)
+let rasterList: array<u8, 252>;
+@address(END_ADDRESS)
+let rasterEnd: volatile<u8>; // entries * 4
+@address(INDEX_ADDRESS)
+let rasterIndex: volatile<u8>; // the handler's next entry * 4
+
+let lastLine: utinyint = 0;
+
+// Addresses for `at`: the registers a split usually writes. `spriteX(n)`
+// and friends below build the per-sprite ones.
+export namespace Register {
+    const BORDER: usmallint = 0xD020;
+    const BACKGROUND: usmallint = 0xD021;
+    const BACKGROUND_1: usmallint = 0xD022;
+    const BACKGROUND_2: usmallint = 0xD023;
+    const BACKGROUND_3: usmallint = 0xD024;
+    const CONTROL_1: usmallint = 0xD011; // YSCROLL bits 0-2, RSEL 3, DEN 4, BMM 5, ECM 6; keep bit 7 clear
+    const CONTROL_2: usmallint = 0xD016; // XSCROLL bits 0-2, CSEL 3, MCM 4
+    const MEMORY_POINTER: usmallint = 0xD018; // screen and character set (or bitmap) in the bank
+    const SPRITE_POSITIONS: usmallint = 0xD000; // + 2n for sprite n's X, + 2n + 1 for its Y
+    const SPRITE_X_HIGH: usmallint = 0xD010;
+    const SPRITE_ENABLE: usmallint = 0xD015;
+    const SPRITE_EXPAND_Y: usmallint = 0xD017;
+    const SPRITE_PRIORITY: usmallint = 0xD01B;
+    const SPRITE_MULTICOLOR: usmallint = 0xD01C;
+    const SPRITE_EXPAND_X: usmallint = 0xD01D;
+    const SPRITE_SHARED_0: usmallint = 0xD025;
+    const SPRITE_SHARED_1: usmallint = 0xD026;
+    const SPRITE_COLORS: usmallint = 0xD027; // + n
+    const SPRITE_POINTERS: usmallint = 0xE3F8; // + n, in text mode (Video.SPRITE_POINTERS); in bitmap mode they are under the I/O area, out of the list's reach
+    const SID_VOLUME: usmallint = 0xD418;
+}
+
+export namespace raster {
+    const MAX: utinyint = 63; // entries
+
+    // Sprite n's registers, for `at`.
+    function spriteX(sprite: utinyint): usmallint {
+        return Register.SPRITE_POSITIONS + sprite * 2;
+    }
+    function spriteY(sprite: utinyint): usmallint {
+        return Register.SPRITE_POSITIONS + sprite * 2 + 1;
+    }
+    function spriteColor(sprite: utinyint): usmallint {
+        return Register.SPRITE_COLORS + sprite;
+    }
+    function spritePointer(sprite: utinyint): usmallint {
+        return Register.SPRITE_POINTERS + sprite;
+    }
+
+    // Empty the list. The handler, if enabled, then fires at the stale
+    // first line and applies nothing until entries are added again.
+    function clear(): void {
+        rasterEnd = 0;
+        rasterIndex = 0;
+        lastLine = 0;
+    }
+
+    // Append: at `line`, write `value` to `address`. False, and nothing
+    // added, if the list is full or `line` is below the last entry's.
+    function at(line: utinyint, address: usmallint, value: utinyint): bool {
+        let offset: utinyint = rasterEnd;
+        if (offset >= 252 || line < lastLine) {
+            return false;
+        }
+        rasterList[offset] = line;
+        rasterList[offset + 1] = address & 0xFF;
+        rasterList[offset + 2] = address >> 8;
+        rasterList[offset + 3] = value;
+        lastLine = line;
+        rasterEnd = offset + 4;
+        return true;
+    }
+
+    // How many entries the list holds.
+    function count(): utinyint {
+        return rasterEnd >> 2;
+    }
+
+    // Own the IRQ: the list is applied from the next frame on.
+    function enable(): void {
+        setupVideo(); // KERNAL out: the vectors are RAM
+        rasterIndex = 0;
+        control1 = control1 & 0x7F; // raster compare bit 8 = 0: lines 0-255
+        rasterCompare = rasterList[0];
+        cia1InterruptControl = 0x7F; // no CIA interrupt reaches the handler: the KERNAL's timer A is one
+        cia2InterruptControl = 0x7F;
+        let pending: utinyint = cia1InterruptControl; // reading acknowledges what was latched
+        pending = cia2InterruptControl;
+        interruptStatus = 0x0F; // and whatever the VIC had
+        interruptMask = 0x01; // the raster compare only
+        asm6502 {
+            jsr __8bs_c64_raster_install
+        }
+        interruptsOn = true;
+        asm6502 {
+            cli
+        }
+    }
+
+    // Interrupts off again; the list is kept.
+    function disable(): void {
+        asm6502 {
+            sei
+        }
+        interruptMask = 0;
+        interruptStatus = 0x0F;
+        interruptsOn = false;
+    }
+}

package/src/reu.8bs

@@ -0,0 +1,210 @@
+// @8bitscript/c64/reu — a RAM Expansion Unit: is one plugged in, how big,
+// and moving memory to and from it.
+//
+// Named by "8bitscript".exports["./reu"] in this package's package.json:
+//
+//     import { reu } from "@8bitscript/c64/reu";
+//
+//     let banked: usmallint = reu.detect();   // KiB found, 0 for none
+//     if (banked != 0) {
+//         reu.stash(0xE000, 0, 0x0000, 1000);  // the screen into bank 0
+//         ...
+//         reu.fetch(0xE000, 0, 0x0000, 1000);  // and back
+//     }
+//
+// ---- transfers ------------------------------------------------------------
+//
+// The REU is a DMA controller with its own RAM in 64 KiB banks: given a
+// C64 address, a REU address (bank, then 16 bits within it) and a length,
+// it copies in either direction, swaps, or compares, with the CPU halted
+// for about a cycle a byte — a thousand bytes in a millisecond, which no
+// loop on the 6510 approaches. `stash` copies C64 → REU, `fetch` REU →
+// C64, `swap` exchanges, `verify` compares and says whether they matched;
+// `fillReu` writes one byte across a REU range. A length of 0 means 65536.
+// The C64 side goes through the CPU's memory map as $01 has it (./index.8bs):
+// $E000-$FFFF is the screen's RAM (KERNAL out), $D000-$DFFF the I/O area,
+// so a transfer touching the character set or a bitmap's colour matrix
+// needs the I/O area banked out around it (bankIoOut/bankIoIn) — and
+// nothing here does that for a caller. Every transfer sets every register,
+// so the REU's own address stepping after a transfer never matters. The
+// REU's contents survive a RESET but not power off; VICE's `-reu` keeps
+// nothing between runs unless told to.
+//
+// The first run-time hardware probe. A build fitted with a REU
+// (`--hardware ram=reu512`, or a profile) says so at compile time —
+// `Memory.BANKED` from @8bitscript/system is true, `Memory.BANKED_KIB` is
+// what the build was fitted with — and that means "this build may use
+// one", not "one is there": the same binary runs on a C64 with no REU, a
+// 1700, or a 16 MiB modern one, and `detect()` is how it finds out which.
+// A program that never imports this file carries none of it: only what a
+// program imports is compiled, so an app with no use for a REU pays
+// nothing for one, and the same goes for every probe to come. See
+// docs/systems.md, "Facts", the third rule.
+//
+// C64-only, hardware-level, like ./sid.8bs: the layer a portable banked-
+// memory capability will sit on. Two questions, answered in order:
+//
+// 1. Is there a REU at all? A register round trip. `$DF02` (C64 base
+//    address, low byte) stores what is written and reads it back on every
+//    REU; on a C64 without one, `$DF00`–`$DFFF` is open bus and reads
+//    whatever byte last crossed it, which is not two different values in
+//    a row. Writing $55 then $AA and reading each back is the test.
+// 2. How much RAM? Sixty-four-KiB banks, found by writing a marker to the
+//    first byte of each bank in turn and looking for it to land somewhere
+//    it should not. One-byte DMA transfers do the writing and reading:
+//    `stash` copies a byte from C64 RAM into the REU, `fetch` the other
+//    way. Bank 0 is marked first; then for each higher bank, its marker
+//    is stashed and two things are checked — did bank 0's marker change
+//    (the address wrapped: this bank *is* bank 0 again), and does the
+//    bank read its own marker back (a bank that does not exist reads
+//    nothing back). Either ends the count. The units with 3-bit bank
+//    registers (1700, 1764, 1750: 128, 256, 512 KiB) wrap at 8 banks or
+//    alias below it; the larger units have all 8 bits, up to 256 banks.
+//    Run under VICE at 128 KiB, 256, 512, 1 MiB and 16 MiB, and with no
+//    REU (see AGENTS.md); verified against VICE's reu.c: the bank register's
+//    unused bits are forced high on those units, addresses wrap at the
+//    unit's size, every register reads back what was written, and
+//    autoload restores the bank register too.
+//
+// The byte the DMA reads and writes is `probe`, one location in the
+// cassette buffer ($033C–$03FB), which nothing else in an 8bitscript
+// program uses (interrupts are off; there is no tape). The registers are
+// set once: with bit 5 of the command (autoload) the REU reloads every
+// address and the length from what was written after each transfer, and
+// with bit 4 the transfer runs immediately, without the $FF00 trigger the
+// original REU firmware wants. So a transfer is two writes — the bank and
+// the command. Measured: a program that calls `detect()` is about 180
+// bytes bigger than the same program without it (the size loop is most
+// of that; `present()` alone is a couple of dozen), and a program that
+// does not import this file is not one byte bigger.
+//
+// `detect()` is safe to call on a C64 without a REU (question 1 stops it),
+// costs a few hundred DMA cycles at most, and is meant to run once at
+// start-up; keep the answer in a variable rather than asking again.
+import {
+    reuStatus, reuCommand, reuC64AddressLow, reuC64AddressHigh, reuAddressLow, reuAddressHigh,
+    reuBank, reuLengthLow, reuLengthHigh, reuAddressControl,
+} from "./index.8bs";
+
+// The one C64 byte the transfers touch. Its address goes into $DF02/$DF03.
+@address(0x033C) let probe: volatile<u8>;
+
+namespace Reu {
+    const PROBE_LOW: utinyint = 0x3C;    // low byte of `probe`'s address
+    const PROBE_HIGH: utinyint = 0x03;   // high byte
+    const STASH: utinyint = 0xB0;        // execute now, autoload, C64 → REU
+    const FETCH: utinyint = 0xB1;        // execute now, autoload, REU → C64
+    const EXECUTE: utinyint = 0x90;      // execute now, no autoload; OR the direction in
+    const TO_REU: utinyint = 0;          // command bits 0-1
+    const FROM_REU: utinyint = 1;
+    const EXCHANGE: utinyint = 2;
+    const COMPARE: utinyint = 3;
+    const FIX_C64: utinyint = 0x80;      // address control: the C64 address does not advance
+    const FAULT: utinyint = 0x20;        // status: a verify found a difference
+}
+
+// One transfer: every register, then the command. `control` is the
+// address-control register (0, or Reu.FIX_C64).
+function transfer(direction: utinyint, control: utinyint, c64Address: usmallint, bank: utinyint, address: usmallint, length: usmallint): void {
+    reuC64AddressLow = c64Address & 0xFF;
+    reuC64AddressHigh = c64Address >> 8;
+    reuAddressLow = address & 0xFF;
+    reuAddressHigh = address >> 8;
+    reuBank = bank;
+    reuLengthLow = length & 0xFF;
+    reuLengthHigh = length >> 8;
+    reuAddressControl = control;
+    reuCommand = Reu.EXECUTE | direction;
+}
+
+export namespace reu {
+    // Question 1: is a REU present? A register that stores what it is
+    // given, twice, with different values.
+    function present(): bool {
+        reuC64AddressLow = 0x55;
+        if (reuC64AddressLow != 0x55) {
+            return false;
+        }
+        reuC64AddressLow = 0xAA;
+        return reuC64AddressLow == 0xAA;
+    }
+
+    // Question 2, given a REU: how many 64 KiB banks it has, 1..255, or 0
+    // meaning all 256 (16 MiB — the count does not fit the byte). Every
+    // transfer is one byte between `probe` and the first byte of a bank.
+    function banks(): utinyint {
+        reuC64AddressLow = Reu.PROBE_LOW;
+        reuC64AddressHigh = Reu.PROBE_HIGH;
+        reuAddressLow = 0;
+        reuAddressHigh = 0;
+        reuLengthLow = 1;
+        reuLengthHigh = 0;
+        reuAddressControl = 0;
+        probe = 0;
+        reuBank = 0;
+        reuCommand = Reu.STASH;
+        let bank: utinyint = 1;
+        while (bank != 0) {
+            probe = bank;
+            reuBank = bank;
+            reuCommand = Reu.STASH;
+            probe = 0xFF;
+            reuBank = 0;
+            reuCommand = Reu.FETCH;
+            if (probe == bank) {
+                return bank;        // wrapped: this bank is bank 0 again
+            }
+            probe = 0xFF;
+            reuBank = bank;
+            reuCommand = Reu.FETCH;
+            if (probe != bank) {
+                return bank;        // nothing there
+            }
+            bank = bank + 1;
+        }
+        return 0;
+    }
+
+    // KiB of REU RAM plugged in: 0 for none, 128 for a 1700, 512 for a
+    // 1750, up to 16384. One call at start-up; keep the answer.
+    function detect(): usmallint {
+        if (!reu.present()) {
+            return 0;
+        }
+        let found: utinyint = reu.banks();
+        if (found == 0) {
+            return 16384;
+        }
+        let kib: usmallint = found;
+        return kib * 64;
+    }
+
+    // `length` bytes from C64 `c64Address` into the REU at `bank`:`address`.
+    function stash(c64Address: usmallint, bank: utinyint, address: usmallint, length: usmallint): void {
+        transfer(Reu.TO_REU, 0, c64Address, bank, address, length);
+    }
+
+    // `length` bytes from the REU at `bank`:`address` into C64 `c64Address`.
+    function fetch(c64Address: usmallint, bank: utinyint, address: usmallint, length: usmallint): void {
+        transfer(Reu.FROM_REU, 0, c64Address, bank, address, length);
+    }
+
+    // The two ranges exchanged.
+    function swap(c64Address: usmallint, bank: utinyint, address: usmallint, length: usmallint): void {
+        transfer(Reu.EXCHANGE, 0, c64Address, bank, address, length);
+    }
+
+    // True if the two ranges hold the same bytes.
+    function verify(c64Address: usmallint, bank: utinyint, address: usmallint, length: usmallint): bool {
+        let cleared: utinyint = reuStatus; // reading clears the fault bit from before
+        transfer(Reu.COMPARE, 0, c64Address, bank, address, length);
+        return (reuStatus & Reu.FAULT) == 0;
+    }
+
+    // `length` bytes of the REU at `bank`:`address` all set to `value`: a
+    // stash from one C64 byte that does not advance.
+    function fillReu(bank: utinyint, address: usmallint, length: usmallint, value: utinyint): void {
+        probe = value;
+        transfer(Reu.TO_REU, Reu.FIX_C64, 0x033C, bank, address, length);
+    }
+}

package/src/screen.8bs

@@ -0,0 +1,120 @@
+// @8bitscript/c64/screen — the C64's implementation of @8bitscript/screen.
+//
+// Named by "8bitscript".exports["./screen"] in this package's package.json,
+// and what
+//
+//     import { screen, BorderColor, BackgroundColor } from "@8bitscript/screen";
+//
+// resolves to when the build is for the C64: @8bitscript/screen's entry is
+// keyed by machine and delegates here. Built on the registers @8bitscript/c64
+// itself exports, one layer up from them. Every machine's screen.8bs exports
+// this same surface, which is what lets a program import it from
+// @8bitscript/screen and never name the hardware.
+//
+// Where the screen is — VIC bank 3, above the program, with the ROM
+// character set copied under the I/O area — is ./geometry.8bs's story, and
+// `setupVideo()` (in ./index.8bs) is what puts it there, once, before the
+// first cell is written.
+import { borderColor, backgroundColor, setupVideo } from "./index.8bs";
+import { Video, screenRam } from "./geometry.8bs";
+
+// ---- the screen: border and background --------------------------------------
+//
+// The VIC-II gives border and background their own registers, sixteen
+// colours each; the masks make the wrap around the palette explicit.
+export namespace screen {
+    function setColors(border: u8, background: u8): void {
+        borderColor = border & 15;
+        backgroundColor = background & 15;
+    }
+
+    // `blank(border, background)`: every cell blank and both colours set —
+    // black when left off, or `BorderColor.KEEP` / `BackgroundColor.KEEP`
+    // to leave one as it is. `setBorder` and `setBackground` are one
+    // colour each, `setColors` the pair; `text.setColor` owns what the
+    // next print looks like.
+    function blank(border: utinyint = BorderColor.BLACK, background: utinyint = BackgroundColor.BLACK): void {
+        setupVideo();
+        if (border != BorderColor.KEEP) {
+            screen.setBorder(border);
+        }
+        if (background != BackgroundColor.KEEP) {
+            screen.setBackground(background);
+        }
+        // Four quarters at once, indexed by one byte. Written as a single
+        // `cell < CELL_COUNT` loop this is a sixteen-bit counter and a
+        // sixteen-bit pointer walked a byte at a time with its own carry —
+        // what LLVM-MOS has to emit when an index does not fit a register.
+        // Four constant offsets off one 8-bit index is the shape a 6502
+        // wants: `sta $0400,x` and friends, a quarter of the iterations.
+        for (let i: utinyint = 0; i < 250; i++) {
+            screenRam[i] = 32; // 32: the space screen code
+            screenRam[i + 250] = 32;
+            screenRam[i + 500] = 32;
+            screenRam[i + 750] = 32;
+        }
+    }
+
+    function setBackground(background: u8): void {
+        backgroundColor = background & 15;
+    }
+
+    function setBorder(border: u8): void {
+        borderColor = border & 15;
+    }
+}
+
+// ---- colour names ----------------------------------------------------------
+//
+// The same eight names every machine's screen.8bs exports — Black, White,
+// Red, Cyan, Purple, Green, Blue, Yellow — so a program can write
+// `screen.setColors(BorderColor.BLUE, BackgroundColor.BLACK)` through
+// @8bitscript/screen and get blue on every target; the values are this
+// machine's own. The VIC-II has sixteen colours in both registers, so both
+// namespaces carry all sixteen, in the VIC-II's own numbering — the
+// numbering the VIC-20 shares for its first eight, and that @8bitscript/web
+// and @8bitscript/cx16 borrow.
+
+export namespace BorderColor {
+    const BLACK: utinyint = 0;
+    const WHITE: utinyint = 1;
+    const RED: utinyint = 2;
+    const CYAN: utinyint = 3;
+    const PURPLE: utinyint = 4;
+    const GREEN: utinyint = 5;
+    const BLUE: utinyint = 6;
+    const YELLOW: utinyint = 7;
+    const ORANGE: utinyint = 8;
+    const BROWN: utinyint = 9;
+    const LIGHT_RED: utinyint = 10;
+    const DARK_GREY: utinyint = 11;
+    const GREY: utinyint = 12;
+    const LIGHT_GREEN: utinyint = 13;
+    const LIGHT_BLUE: utinyint = 14;
+    const LIGHT_GREY: utinyint = 15;
+    // Not a colour: `blank(KEEP, ...)` leaves this one as it is. 255 is
+    // a value no register here takes.
+    const KEEP: utinyint = 255;
+}
+
+export namespace BackgroundColor {
+    const BLACK: utinyint = 0;
+    const WHITE: utinyint = 1;
+    const RED: utinyint = 2;
+    const CYAN: utinyint = 3;
+    const PURPLE: utinyint = 4;
+    const GREEN: utinyint = 5;
+    const BLUE: utinyint = 6;
+    const YELLOW: utinyint = 7;
+    const ORANGE: utinyint = 8;
+    const BROWN: utinyint = 9;
+    const LIGHT_RED: utinyint = 10;
+    const DARK_GREY: utinyint = 11;
+    const GREY: utinyint = 12;
+    const LIGHT_GREEN: utinyint = 13;
+    const LIGHT_BLUE: utinyint = 14;
+    const LIGHT_GREY: utinyint = 15;
+    // Not a colour: `blank(KEEP, ...)` leaves this one as it is. 255 is
+    // a value no register here takes.
+    const KEEP: utinyint = 255;
+}

package/src/scroll.8bs

@@ -0,0 +1,130 @@
+// @8bitscript/c64/scroll — the VIC-II's fine scroll, and coarse shifts of
+// the text screen.
+//
+// Named by "8bitscript".exports["./scroll"] in this package's package.json:
+//
+//     import { scroll } from "@8bitscript/c64/scroll";
+//
+//     scroll.setNarrow(true);              // 38 columns: the edges are border
+//     let fine: u8 = 7;
+//     ...
+//     // each frame, a world moving left:
+//     if (fine == 0) {
+//         fine = 7;
+//         scroll.shiftLeft(32, 1);         // a column of spaces in, white
+//         ... draw the new column at 39 ...
+//     } else {
+//         fine = fine - 1;
+//     }
+//     scroll.setX(fine);
+//
+// Hardware-level, C64-only surface. The VIC-II shifts the whole picture
+// by 0-7 pixels horizontally ($D016 bits 0-2, XSCROLL) and vertically
+// ($D011 bits 0-2, YSCROLL; 3 is the boot value that puts the first row
+// at line 51), and hides the edge a scroll exposes by drawing 38 columns
+// instead of 40 ($D016 bit 3, CSEL, clear) or 24 rows instead of 25
+// ($D011 bit 3, RSEL, clear) — the border grows over the outer half-cells.
+// Smooth scrolling is the two together: fine scroll one pixel a frame,
+// and every eighth frame shift the screen a cell and reset the fine scroll,
+// as the sketch above does. The shifts move screen codes and colour RAM
+// together and fill the column or row that opens with one code and colour;
+// each is a thousand-cell copy, some 20000 cycles — a frame's worth of
+// CPU on the frame it happens.
+//
+// YSCROLL moves the bad lines: the VIC fetches a row of screen codes on
+// every line whose low three bits equal YSCROLL, so a raster list's timing
+// (@8bitscript/c64/raster) shifts with it. Reads of the screen work
+// because the KERNAL is banked out (./index.8bs, setupVideo).
+import { control1, control2, setupVideo } from "./index.8bs";
+import { Video, screenRam, colorRam } from "./geometry.8bs";
+
+export namespace scroll {
+    // Horizontal fine scroll, 0-7 pixels right.
+    function setX(pixels: utinyint): void {
+        control2 = (control2 & 0xF8) | (pixels & 7);
+    }
+
+    // Vertical fine scroll, 0-7 pixels down; 3 is the default position.
+    // Bit 7 — the raster compare's ninth bit on a write — is kept clear.
+    function setY(pixels: utinyint): void {
+        control1 = (control1 & 0x78) | (pixels & 7);
+    }
+
+    // 38 columns (true) or 40: the border covers half a cell at each side.
+    function setNarrow(on: bool): void {
+        if (on) {
+            control2 = control2 & 0xF7;
+        } else {
+            control2 = control2 | 0x08;
+        }
+    }
+
+    // 24 rows (true) or 25: the border covers half a cell top and bottom.
+    function setShort(on: bool): void {
+        if (on) {
+            control1 = control1 & 0x77;
+        } else {
+            control1 = (control1 & 0x7F) | 0x08;
+        }
+    }
+
+    // Every cell moves one column left; column 39 becomes `code` in `color`.
+    function shiftLeft(code: utinyint, color: utinyint): void {
+        setupVideo();
+        let cell: usmallint = 0;
+        for (let row: utinyint = 0; row < Video.ROWS; row++) {
+            for (let column: utinyint = 0; column < 39; column++) {
+                screenRam[cell] = screenRam[cell + 1];
+                colorRam[cell] = colorRam[cell + 1];
+                cell = cell + 1;
+            }
+            screenRam[cell] = code;
+            colorRam[cell] = color;
+            cell = cell + 1;
+        }
+    }
+
+    // Every cell moves one column right; column 0 becomes `code` in `color`.
+    function shiftRight(code: utinyint, color: utinyint): void {
+        setupVideo();
+        let cell: usmallint = Video.CELL_COUNT - 1;
+        for (let row: utinyint = 0; row < Video.ROWS; row++) {
+            for (let column: utinyint = 0; column < 39; column++) {
+                screenRam[cell] = screenRam[cell - 1];
+                colorRam[cell] = colorRam[cell - 1];
+                cell = cell - 1;
+            }
+            screenRam[cell] = code;
+            colorRam[cell] = color;
+            cell = cell - 1;
+        }
+    }
+
+    // Every row moves up one; row 24 becomes `code` in `color`.
+    function shiftUp(code: utinyint, color: utinyint): void {
+        setupVideo();
+        for (let cell: usmallint = 0; cell < 960; cell++) {
+            screenRam[cell] = screenRam[cell + 40];
+            colorRam[cell] = colorRam[cell + 40];
+        }
+        for (let cell: usmallint = 960; cell < Video.CELL_COUNT; cell++) {
+            screenRam[cell] = code;
+            colorRam[cell] = color;
+        }
+    }
+
+    // Every row moves down one; row 0 becomes `code` in `color`.
+    function shiftDown(code: utinyint, color: utinyint): void {
+        setupVideo();
+        let cell: usmallint = Video.CELL_COUNT - 1;
+        while (cell >= 40) {
+            screenRam[cell] = screenRam[cell - 40];
+            colorRam[cell] = colorRam[cell - 40];
+            cell = cell - 1;
+        }
+        for (let first: utinyint = 0; first < 40; first++) {
+            screenRam[first] = code;
+            colorRam[first] = color;
+        }
+    }
+}