jsbeeb 1.19.3 → 1.20.1

package/src/soundchip.js

@@ -12,6 +12,10 @@ export const SoundBufferSamples = 512;
 // mean level, which a zero-mean output would silence (see issue #863).
 const DcRestoreCornerHz = 1 / (2 * Math.PI * 10e3 * 4.7e-6);
 
+// A chip with an event sink reports progress this often, so its events can
+// stream through a long execute() rather than all arriving at its end.
+const EventProgressCycles = 4000;
+
 const volumeTable = new Float32Array(16);
 (() => {
     let f = 1.0;
@@ -35,9 +39,15 @@ export class SoundChip {
      * @param {function(Float32Array): void} onBuffer called with each full
      *     SoundBufferSamples-sized buffer of output. Receives the same buffer
      *     every call, overwritten afterwards: copy the contents if they are kept.
+     * @param {object} [options]
+     * @param {function(object): void} [options.onEvent] called with each
+     *     change to the chip's state, stamped with the cycle it takes effect at.
+     *     A chip with an event sink does not render; something else renders
+     *     from the events (see audio-renderer.js).
      */
-    constructor(onBuffer) {
+    constructor(onBuffer, { onEvent = null } = {}) {
         this._onBuffer = onBuffer;
+        this._onEvent = onEvent;
         // 4MHz input signal. Internal divide-by-8
         this.soundchipFreq = 4000000.0 / 8;
         const sampleRate = this.soundchipFreq;
@@ -91,15 +101,38 @@ export class SoundChip {
             mute: () => {
                 this.catchUp();
                 this.sineOn = false;
+                this._emit({ sine: 0 });
             },
             tone: (freq) => {
                 this.catchUp();
                 this.sineOn = true;
                 this.sineStep = (freq / sampleRate) * this.sineTable.length;
+                this._emit({ sine: freq });
             },
         };
     }
 
+    _emit(event) {
+        if (this._onEvent) this._onEvent({ cycle: this.scheduler.epoch, ...event });
+    }
+
+    /** Applies an event from another chip's onEvent, at the cycle this chip is rendering. */
+    applyEvent(event) {
+        if (event.poke !== undefined) this.poke(event.poke);
+        else if (event.sine !== undefined) {
+            if (event.sine) this.toneGenerator.tone(event.sine);
+            else this.toneGenerator.mute();
+        } else if (event.enabled !== undefined) this.enabled = event.enabled;
+        else if (event.state !== undefined) this.restoreState(event.state);
+        else if (event.reset !== undefined) this.reset(event.reset);
+    }
+
+    /** Renders `length` samples of output from `cycle`, for a chip that is driven by events. */
+    renderAt(cycle, out, offset, length) {
+        this.scheduler.epoch = this.lastRunEpoch = cycle;
+        this.generate(out, offset, length);
+    }
+
     sineChannel(channel, out, offset, length) {
         if (!this.sineOn) return;
 
@@ -181,6 +214,7 @@ export class SoundChip {
         this.volume[2] = volumeTable[v2];
         this.volume[3] = volumeTable[v3];
         this.noisePoked();
+        this._emit({ state: this.snapshotState() });
     }
 
     generate(out, offset, length) {
@@ -219,6 +253,13 @@ export class SoundChip {
         this.activeTask = this.scheduler.newTask(() => {
             if (this.active) this.poke(this.slowDataBus);
         });
+        if (this._onEvent) {
+            this.progressTask = this.scheduler.newTask(() => {
+                this._emit({ progress: true });
+                this.progressTask.schedule(EventProgressCycles);
+            });
+            this.progressTask.schedule(EventProgressCycles);
+        }
     }
 
     render(out, offset, length) {
@@ -239,6 +280,7 @@ export class SoundChip {
     }
 
     advance(cycles) {
+        if (this._onEvent) return;
         const num = cycles * this.samplesPerCycle + this.residual;
         let rounded = num | 0;
         this.residual = num - rounded;
@@ -270,6 +312,7 @@ export class SoundChip {
 
     poke(value) {
         this.catchUp();
+        this._emit({ poke: value });
 
         let command;
         if (value & 0x80) {
@@ -350,10 +393,13 @@ export class SoundChip {
         // Older snapshots predate the DC blocker
         this.dcPrevIn = state.dcPrevIn ?? 0;
         this.dcPrevOut = state.dcPrevOut ?? 0;
+        this.progressTask?.ensureScheduled(true, EventProgressCycles);
+        this._emit({ state: this.snapshotState() });
     }
 
     reset(hard) {
         if (!hard) return;
+        this._emit({ reset: true });
         for (let i = 0; i < 4; ++i) {
             this.counter[i] = 0;
             this.registers[i] = 0;
@@ -366,14 +412,15 @@ export class SoundChip {
 
     enable(e) {
         this.enabled = e;
+        this._emit({ enabled: e });
     }
 
     mute() {
-        this.enabled = false;
+        this.enable(false);
     }
 
     unmute() {
-        this.enabled = true;
+        this.enable(true);
     }
 }
 
@@ -383,8 +430,8 @@ export class SoundChip {
  * channel with DC-blocking filter.
  */
 export class AtomSoundChip extends SoundChip {
-    constructor(onBuffer, { cpuSpeed = 1000000 } = {}) {
-        super(onBuffer);
+    constructor(onBuffer, { cpuSpeed = 1000000, onEvent = null } = {}) {
+        super(onBuffer, { onEvent });
         this.samplesPerCycle = this.soundchipFreq / cpuSpeed;
         this.secondsPerCycle = 1 / cpuSpeed;
 
@@ -423,7 +470,19 @@ export class AtomSoundChip extends SoundChip {
         this._speakerCycleOffset = 0;
     }
 
+    applyEvent(event) {
+        if (event.bit !== undefined) this.bitChange.push({ bit: event.bit, cycles: event.cycle });
+        else if (event.speakerReset !== undefined) this.speakerReset();
+        else super.applyEvent(event);
+    }
+
+    renderAt(cycle, out, offset, length) {
+        this._speakerCycleOffset = 0;
+        super.renderAt(cycle, out, offset, length);
+    }
+
     speakerReset() {
+        this._emit({ speakerReset: true });
         this.bitChange = [];
         this.currentSpeakerBit = 0.0;
         this._speakerPrevIn = 0;
@@ -461,7 +520,9 @@ export class AtomSoundChip extends SoundChip {
 
     updateSpeaker(value, microCycle, seconds) {
         const cycles = microCycle + seconds / this.secondsPerCycle;
-        this.bitChange.push({ bit: value ? 1.0 : 0.0, cycles });
+        const bit = value ? 1.0 : 0.0;
+        if (this._onEvent) this._onEvent({ cycle: cycles, bit });
+        else this.bitChange.push({ bit, cycles });
     }
 }
 

package/src/tapes.js

@@ -315,6 +315,5 @@ export async function loadTapeFromData(name, data, model) {
         console.log("Detected a UEF tape");
         return new UefTape(stream, model);
     }
-    console.log("Unknown tape format");
-    return null;
+    throw new Error(`${name} is not a UEF or tapefile tape image`);
 }

package/src/video-filters/pal-composite.js

@@ -4,7 +4,7 @@
 //
 // Simulates PAL composite video artifacts by encoding the framebuffer to a
 // composite signal and decoding it back to RGB, mimicking the behavior of
-// connecting a BBC Micro to a PAL television via composite cable.
+// a BBC Micro's UHF-modulated picture on a PAL television.
 //
 // REFERENCES:
 // - John Watkinson's "Engineer's Guide to Decoding & Encoding" (Section 3.4)
@@ -40,7 +40,7 @@ export class PALCompositeFilter {
             uFramebuffer: gl.getUniformLocation(this.program, "uFramebuffer"),
             uResolution: gl.getUniformLocation(this.program, "uResolution"),
             uTexelSize: gl.getUniformLocation(this.program, "uTexelSize"),
-            uFrameCount: gl.getUniformLocation(this.program, "uFrameCount"),
+            uLineBase: gl.getUniformLocation(this.program, "uLineBase"),
         };
     }
 
@@ -55,6 +55,6 @@ export class PALCompositeFilter {
         gl.uniform1i(this.locations.uFramebuffer, 0); // Texture unit 0
         gl.uniform2f(this.locations.uResolution, params.width, params.height);
         gl.uniform2f(this.locations.uTexelSize, 1.0 / params.width, 1.0 / params.height);
-        gl.uniform1f(this.locations.uFrameCount, params.frameCount % 8); // 8-field temporal phase sequence
+        gl.uniform2f(this.locations.uLineBase, params.lineBaseEven, params.lineBaseOdd);
     }
 }

package/src/video-filters/shaders/pal-composite.frag.glsl

@@ -5,23 +5,21 @@ varying vec2 vTexCoord;
 uniform sampler2D uFramebuffer;
 uniform vec2 uResolution;
 uniform vec2 uTexelSize;
-uniform float uFrameCount;
+// Line numbers of texture rows 0 (x) and 1 (y)
+uniform vec2 uLineBase;
 
 const float PI = 3.14159265359;
 
 // IMPLEMENTATION (Baseband Blending Method):
 // 1. Encode RGB to PAL composite: Y + U*sin(ωt) + V*cos(ωt)*v_switch
 // 2. Demodulate current line (with correct phase) → U_curr, V_curr
-// 3. Demodulate previous line (2H for interlaced, same field) → U_prev, V_prev
+// 3. Demodulate the previous scanline (two texture rows up) → U_prev, V_prev
 // 4. Blend at baseband: U_final = mix(U_curr, U_prev), V_final = mix(V_curr, V_prev)
-// 5. Remodulate blended chroma back to composite frequency
-// 6. Extract luma via complementary subtraction: Y = composite - remodulated_chroma
-// 7. Combine luma and chroma, convert back to RGB
+// 5. Luma: composite through the set's low-pass and subcarrier trap
+// 6. Combine luma and chroma, convert back to RGB
 //
-// NOTE: Uses 2H delay (line-2) not 1H (line-1) because jsbeeb simulates interlacing by
-// rendering only odd or even lines per frame. A real PAL TV's 1H delay line would contain
-// the previous scanline from the SAME field, which is 2 texture lines apart. Proper
-// support for non-interlaced modes needs to be added.
+// NOTE: Texture rows are half-lines, so the previous scanline of the same field is two rows
+// up, and the subcarrier phase and V-switch come from uLineBase, not from the row.
 
 // Chroma demodulation gain: compensates for sin²(x) = 0.5 - 0.5·cos(2x) amplitude loss
 const float FIR_GAIN = 2.0;
@@ -35,13 +33,9 @@ const float PAL_FRAME_RATE = 25.0;           // Frames per second
 const float PAL_SUBCARRIER_MHZ = 4.43361875; // PAL color subcarrier frequency (exact)
 
 // Derived PAL parameters
-const float PAL_LINES_PER_FIELD = PAL_TOTAL_LINES / 2.0;
 const float PAL_CYCLES_PER_LINE = PAL_SUBCARRIER_MHZ * 1e6 / (PAL_TOTAL_LINES * PAL_FRAME_RATE);
-const float PAL_LINE_PHASE_OFFSET = fract(PAL_CYCLES_PER_LINE);
-const float PAL_FIELD_PHASE_OFFSET = PAL_LINE_PHASE_OFFSET * PAL_LINES_PER_FIELD;
-
-// jsbeeb texture parameters
-const float TEXTURE_WIDTH = 1024.0;          // Framebuffer width (896 visible + 128 blanking)
+// fract(PAL_CYCLES_PER_LINE), spelt out: float keeps more of it alone than inside 283.7516
+const float PAL_LINE_PHASE_OFFSET = 0.7516;
 
 // RGB → YUV conversion with proper PAL signal levels baked in
 // Derived from ITU-R BT.470-6: white at 0.7V, peak at 0.931V
@@ -63,45 +57,58 @@ vec3 yuv_to_rgb(vec3 yuv) {
     );
 }
 
-// Demodulate composite signal at given position
-vec2 demodulate_uv(vec2 xy, float pixel_x, float offset_pixels, float v_switch, float cycles_per_pixel, float phase_offset) {
-    float t = ((pixel_x + offset_pixels) * cycles_per_pixel + phase_offset) * 2.0 * PI;
+// Subcarrier phase (radians) at offset_pixels from pixel_x
+float carrier_phase(float pixel_x, float offset_pixels, float cycles_per_pixel, float phase_offset) {
+    return ((pixel_x + offset_pixels) * cycles_per_pixel + phase_offset) * 2.0 * PI;
+}
 
+// Encode the texel at offset_pixels from xy to composite: Y + U*sin(ωt) + V*cos(ωt)*v_switch
+float encode_composite(vec2 xy, float offset_pixels, float t, float v_switch) {
     vec2 sample_uv = xy + vec2(offset_pixels * uTexelSize.x, 0.0);
     vec3 rgb = texture2D(uFramebuffer, sample_uv).rgb;
     vec3 yuv = rgb_to_yuv(rgb);
+    return yuv.x + yuv.y * sin(t) + yuv.z * cos(t) * v_switch;
+}
 
-    // Encode to composite: Y + U*sin(ωt) + V*cos(ωt)*v_switch
-    float composite = yuv.x + yuv.y * sin(t) + yuv.z * cos(t) * v_switch;
+// Demodulate composite signal at given position
+vec2 demodulate_uv(vec2 xy, float pixel_x, float offset_pixels, float v_switch, float cycles_per_pixel, float phase_offset) {
+    float t = carrier_phase(pixel_x, offset_pixels, cycles_per_pixel, phase_offset);
+    float composite = encode_composite(xy, offset_pixels, t, v_switch);
 
     // Demodulate: multiply by carrier to shift chroma to baseband
     return vec2(composite * sin(t), composite * cos(t) * v_switch);
 }
 
 void main() {
-    // Use gl_FragCoord for pixel coordinates - it's hardware-provided and avoids interpolation artifacts
-    vec2 pixelCoord = vec2(gl_FragCoord.x, uResolution.y - gl_FragCoord.y);
+    // Texel column and row, whatever size the drawing buffer is.
+    vec2 pixelCoord = floor(vTexCoord * uResolution);
 
     // BEGIN_FIR_COEFFICIENTS
     // This section is replaced by the Vite build to include FIR filter coefficients.
     // Change Cutoff (in comment below) or FIRTAPS value to configure.
-    // Cutoff: 1.108 MHz (quarter subcarrier)
+    // Cutoff: 1.108 MHz (quarter subcarrier; the -6 dB design point, -3 dB at about 0.83 MHz)
     const int FIRTAPS = 21;
     float FIR[FIRTAPS];
     // END_FIR_COEFFICIENTS
 
-    float line = floor(pixelCoord.y);
+    // BEGIN_LUMA_COEFFICIENTS
+    // This section is replaced by the Vite build with the set's luma path, low-pass and
+    // subcarrier trap in one symmetric FIR, as designed in tools/luma-fir-generator.js.
+    const int LUMA_TAPS = 31;
+    float LUMA_FIR[LUMA_TAPS];
+    // END_LUMA_COEFFICIENTS
+
+    float row = pixelCoord.y;
+    float line = (mod(row, 2.0) < 1.0 ? uLineBase.x : uLineBase.y) + floor(row / 2.0);
 
     // PAL phase alternates each scanline (V component inverts)
     float v_switch = mod(line, 2.0) < 1.0 ? 1.0 : -1.0;
 
-    // Map PAL subcarrier across texture width
-    float cycles_per_pixel = PAL_CYCLES_PER_LINE / TEXTURE_WIDTH;
+    // Map PAL subcarrier across the full line, blanking included
+    float cycles_per_pixel = PAL_CYCLES_PER_LINE / uResolution.x;
 
-    // PAL temporal phase (8-field sequence creates animated dot crawl)
-    float line_phase_offset = line * PAL_LINE_PHASE_OFFSET;
-    float frame_phase_offset = uFrameCount * PAL_FIELD_PHASE_OFFSET;
-    float phase_offset = line_phase_offset + frame_phase_offset;
+    // Subcarrier phase at the start of this line, carried across frames by the line count
+    float phase_offset = fract(line * PAL_LINE_PHASE_OFFSET);
 
     // Step 1: Demodulate current line with FIR filter
     vec2 filtered_uv_curr = vec2(0.0);
@@ -111,14 +118,11 @@ void main() {
         filtered_uv_curr += FIR_GAIN * uv * FIR[i];
     }
 
-    // Step 2: Demodulate previous line (2H for interlaced, same field) with FIR filter
-    // In interlaced mode, only odd OR even lines are rendered per frame.
-    // Using 2H (line-2) ensures we sample from the same field (both fresh data).
-    // This represents the TV's 1H delay within a single field.
+    // Step 2: Demodulate the previous scanline of the same field (two rows up, one line
+    // earlier) with FIR filter. This represents the TV's 1H delay line.
     vec2 prev_uv = vTexCoord - vec2(0.0, 2.0 * uTexelSize.y);
-    float prev_line = line - 2.0;
-    float prev_v_switch = v_switch * -1.0;
-    float prev_phase_offset = prev_line * PAL_LINE_PHASE_OFFSET + frame_phase_offset;
+    float prev_v_switch = -v_switch;
+    float prev_phase_offset = fract((line - 1.0) * PAL_LINE_PHASE_OFFSET);
 
     vec2 filtered_uv_prev = vec2(0.0);
     for (int i = 0; i < FIRTAPS; i++) {
@@ -130,17 +134,13 @@ void main() {
     // Step 3: Blend chroma at baseband
     vec2 filtered_uv = mix(filtered_uv_curr, filtered_uv_prev, CHROMA_BLEND_WEIGHT);
 
-    // Step 4: Get luma via complementary subtraction
-    float t_curr = (pixelCoord.x * cycles_per_pixel + phase_offset) * 2.0 * PI;
-    vec3 rgb_curr = texture2D(uFramebuffer, vTexCoord).rgb;
-    vec3 yuv_curr = rgb_to_yuv(rgb_curr);
-    float composite_curr = yuv_curr.x + yuv_curr.y * sin(t_curr) + yuv_curr.z * cos(t_curr) * v_switch;
-
-    // Remodulate blended chroma back to composite frequency
-    float remodulated_chroma = filtered_uv.x * sin(t_curr) + filtered_uv.y * cos(t_curr) * v_switch;
-
-    // Complementary subtraction: luma = composite - chroma
-    float y_out = composite_curr - remodulated_chroma;
+    // Step 4: Luma is the composite through the set's low-pass and subcarrier trap
+    float y_out = 0.0;
+    for (int i = 0; i < LUMA_TAPS; i++) {
+        float offset = float(i - (LUMA_TAPS - 1) / 2);
+        float t = carrier_phase(pixelCoord.x, offset, cycles_per_pixel, phase_offset);
+        y_out += encode_composite(vTexCoord, offset, t, v_switch) * LUMA_FIR[i];
+    }
 
     vec3 rgb_out = yuv_to_rgb(vec3(y_out, filtered_uv.x, filtered_uv.y));
     gl_FragColor = vec4(clamp(rgb_out, 0.0, 1.0), 1.0);

package/src/video.js

@@ -19,6 +19,10 @@ export const OPAQUE_WHITE = 0xffffffff;
 
 export const MinPaintedFrameRows = 64;
 
+// The PAL subcarrier advances 283.7516 cycles per line (4433618.75 Hz / 15625 Hz), and
+// 0.7516 = 1879 / 2500, so its phase against the line is periodic in 2500 lines.
+export const PalPhasePeriodLines = 2500;
+
 ////////////////////
 // VideoNULA - programmable 12-bit RGB palette extension (RobC hardware mod).
 // Reference: b-em src/video.c (stardot/b-em).
@@ -348,6 +352,11 @@ export class Video {
         this.bitmapY = 0;
         this.oddClock = false;
         this.frameCount = 0;
+        this.hsyncCount = 0;
+        // The hsyncCount in effect while framebuffer rows 0 and 1 were drawn: row r was drawn
+        // during line lineBase[r & 1] + (r >> 1), which sets its PAL subcarrier phase.
+        this.lineBaseEven = 0;
+        this.lineBaseOdd = 0;
         this.doEvenFrameLogic = false;
         this.isEvenRender = true;
         this.lastRenderWasEven = false;
@@ -460,6 +469,9 @@ export class Video {
             bitmapY: this.bitmapY,
             oddClock: this.oddClock,
             frameCount: this.frameCount,
+            hsyncCount: this.hsyncCount,
+            lineBaseEven: this.lineBaseEven,
+            lineBaseOdd: this.lineBaseOdd,
             doEvenFrameLogic: this.doEvenFrameLogic,
             isEvenRender: this.isEvenRender,
             lastRenderWasEven: this.lastRenderWasEven,
@@ -512,6 +524,9 @@ export class Video {
         this.bitmapY = state.bitmapY;
         this.oddClock = state.oddClock;
         this.frameCount = state.frameCount;
+        this.hsyncCount = state.hsyncCount ?? 0;
+        this.lineBaseEven = state.lineBaseEven ?? 0;
+        this.lineBaseOdd = state.lineBaseOdd ?? 0;
         this.doEvenFrameLogic = state.doEvenFrameLogic;
         this.isEvenRender = state.isEvenRender;
         this.lastRenderWasEven = state.lastRenderWasEven;
@@ -606,13 +621,26 @@ export class Video {
         this.dispEnabled |= enable;
         this.cursorInvertedOffset = -1;
 
-        this.bitmapY = 0;
         // Interlace even frame fires vsync midway through a scanline.
-        if (!!(this.regs[8] & 1) && !!(this.frameCount & 1)) {
-            this.bitmapY = -1;
+        const oddField = !!(this.regs[8] & 1) && !!(this.frameCount & 1);
+        this.bitmapY = oddField ? -1 : 0;
+
+        // The even field draws the rest of the vsync line on row 0; the odd field's first row
+        // is the first hsync after it.
+        const firstRowLine = (this.hsyncCount + (oddField ? 1 : 0)) % PalPhasePeriodLines;
+        if (this.doublesLines()) {
+            this.lineBaseEven = this.lineBaseOdd = firstRowLine;
+        } else if (oddField) {
+            this.lineBaseOdd = firstRowLine;
+        } else {
+            this.lineBaseEven = firstRowLine;
         }
     }
 
+    doublesLines() {
+        return (this.doubledScanlines && !this.interlacedSyncAndVideo) || this.isEvenRender === this.lastRenderWasEven;
+    }
+
     debugOffset(x, y) {
         if (x < 0 || x >= 1024) return -1;
         if (y < 0 || y >= 768) return -1;
@@ -715,9 +743,7 @@ export class Video {
         if (!this.halfClock || !this.oddClock) return;
         if ((this.dispEnabled & EVERYTHINGENABLED) !== EVERYTHINGENABLED) return;
         if (this.bitmapX < 0 || this.bitmapX >= 1024 || this.bitmapY < 0 || this.bitmapY >= 625) return;
-        // The same line doubling decision as the render loop, which inlines it for speed.
-        const doubledLines =
-            (this.doubledScanlines && !this.interlacedSyncAndVideo) || this.isEvenRender === this.lastRenderWasEven;
+        const doubledLines = this.doublesLines();
         const bitmapRow = doubledLines ? this.bitmapY & ~1 : this.bitmapY;
         const offset = bitmapRow * 1024 + this.bitmapX;
         const halfCell = this.pixelsPerChar >>> 1;
@@ -903,6 +929,7 @@ export class Video {
             // The CRT vertical beam speed is constant, so this is actually
             // an approximation that works if hsyncs are spaced evenly.
             this.bitmapY += 2;
+            this.hsyncCount = (this.hsyncCount + 1) % PalPhasePeriodLines;
 
             // Arbitrary moment when TV will give up and start flyback in the absence of an explicit VSync signal
             return this.bitmapY >= 768;
@@ -1064,7 +1091,8 @@ export class Video {
                     // There's a painting subtlety here: if we're in an
                     // interlace mode but R6>R4 then we'll get stuck
                     // painting just an odd or even frame, so we double up
-                    // scanlines to avoid a ghost half frame.
+                    // scanlines to avoid a ghost half frame. This is
+                    // doublesLines(), inlined for speed.
                     if (
                         (this.doubledScanlines && !this.interlacedSyncAndVideo) ||
                         this.isEvenRender === this.lastRenderWasEven