@zakkster/lite-scratch-fx 1.0.0 → 1.2.0

package/src/PixelScan.js

@@ -0,0 +1,74 @@
+/**
+ * Pixel scanner -- finds the still-covered pixels of a scratch layer as normalized
+ * 0..1 spawn points. Allocated ONCE per scanner and reused across every scan: the
+ * offscreen canvas, its context, and the spot arrays are built lazily and grown only
+ * when the source canvas is resized, so a scan allocates nothing per pixel (only
+ * getImageData's single buffer, which the 2D canvas API mandates).
+ *
+ * Shared by ScratchController and ScratchStage.
+ *
+ * Copyright (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+ * MIT License.
+ */
+
+/**
+ * @param {HTMLCanvasElement} sourceCanvas  The scratch layer to scan.
+ * @returns {{ scan(precision:number): { spotX: Float32Array, spotY: Float32Array, count: number },
+ *             destroy(): void }}
+ */
+export function createPixelScanner(sourceCanvas) {
+    let scanCanvas = null;
+    let scanCtx = null;
+    let scanW = 0, scanH = 0;
+    let spotX = new Float32Array(0);
+    let spotY = new Float32Array(0);
+    const result = { spotX, spotY, count: 0 };   // reused -- no per-scan allocation
+
+    function ensure(precision) {
+        const srcW = sourceCanvas.width || sourceCanvas.offsetWidth || 1;
+        const srcH = sourceCanvas.height || sourceCanvas.offsetHeight || 1;
+        const h = Math.max(1, Math.floor(srcH * (precision / srcW)));
+        if (scanCanvas && scanW === precision && scanH === h) return;
+        scanW = precision;
+        scanH = h;
+        if (!scanCanvas) {
+            scanCanvas = document.createElement('canvas');
+            scanCtx = scanCanvas.getContext('2d', { willReadFrequently: true });
+        }
+        scanCanvas.width = scanW;
+        scanCanvas.height = scanH;
+        const cap = scanW * scanH;
+        if (spotX.length < cap) {
+            spotX = new Float32Array(cap);
+            spotY = new Float32Array(cap);
+        }
+    }
+
+    return {
+        scan(precision) {
+            ensure(precision);
+            scanCtx.clearRect(0, 0, scanW, scanH);
+            scanCtx.drawImage(sourceCanvas, 0, 0, scanW, scanH);
+            const data = scanCtx.getImageData(0, 0, scanW, scanH).data;
+            let n = 0;
+            for (let i = 3; i < data.length; i += 4) {
+                if (data[i] > 128) {
+                    const p = (i - 3) / 4;
+                    spotX[n] = (p % scanW) / scanW;
+                    spotY[n] = ((p / scanW) | 0) / scanH;
+                    n++;
+                }
+            }
+            result.spotX = spotX;
+            result.spotY = spotY;
+            result.count = n;
+            return result;
+        },
+        destroy() {
+            scanCanvas = null;
+            scanCtx = null;
+        },
+    };
+}
+
+export default createPixelScanner;

package/src/ScratchController.js

@@ -3,7 +3,20 @@
  *
  * Mounts a reveal recipe, scans the remaining visible pixels of the scratch layer for
  * spawn points, delegates physics + rendering to the recipe, and auto-cleans up on
- * completion. The particle engine owns its own requestAnimationFrame loop.
+ * completion.
+ *
+ * Driving model (three ways, all keep dt correct -- the double-drive that corrupts dt is
+ * never possible):
+ *   - DEFAULT: the controller owns a SoaParticleEngine and lets it self-drive via its own
+ *     requestAnimationFrame loop (start() on reveal, stop() on completion).
+ *   - HOST-DRIVEN (`{ driven: true }`): the controller never calls start(); the host runs
+ *     one clock (e.g. @zakkster/lite-ticker / lite-raf) and calls `controller.tick(dt)`
+ *     every frame with dt in SECONDS. One page loop drives N controllers.
+ *   - SHARED ENGINE (`{ engine }`): N controllers share one caller-supplied engine, so one
+ *     lane pool serves the whole page instead of one per controller. The engine has a
+ *     single render slot and one particle pool, so ONE reveal per shared engine at a time
+ *     -- a reveal attempted while another is active on the same engine is ignored. Pair
+ *     with `{ driven: true }` and drive the page from one clock.
  *
  * Recipe interface:
  *   {
@@ -29,84 +42,45 @@
 
 import { SoaParticleEngine } from '@zakkster/lite-soa-particle-engine';
 import { Random }            from '@zakkster/lite-random';
+import { createPixelScanner } from './PixelScan.js';
+
+// Shared engines currently driving a reveal. A shared engine has one render slot and one
+// particle pool, so only one controller may reveal on it at a time; a second reveal is
+// ignored rather than clobbering the first. Owned engines never enter this set.
+const busySharedEngines = new WeakSet();
 
 /**
  * @param {HTMLCanvasElement} sourceCanvas  The scratch layer being revealed
  * @param {HTMLCanvasElement} effectCanvas  Overlay canvas for VFX
  * @param {Object} [options]
+ * @param {number} [options.maxParticles=2000]  Pool capacity (ignored when `engine` is given)
+ * @param {number} [options.seed=Date.now()]     Deterministic RNG seed
+ * @param {number} [options.scanPrecision=32]     Horizontal resolution of the pixel scan
+ * @param {boolean} [options.driven=false]        Host-driven: skip start(), call tick(dt)
+ * @param {SoaParticleEngine} [options.engine]    Share a caller-supplied engine + lane pool
  */
 export function createScratchController(sourceCanvas, effectCanvas, {
     maxParticles = 2000,
     seed = Date.now(),
     scanPrecision = 32,
+    driven = false,
+    engine: externalEngine = null,
 } = {}) {
     const ctx = effectCanvas.getContext('2d');
-    const engine = new SoaParticleEngine(maxParticles);
+    const ownEngine = !externalEngine;
+    const engine = externalEngine || new SoaParticleEngine(maxParticles);
     const rng = new Random(seed);
-    // The SoA engine owns its own requestAnimationFrame loop: start() schedules it, stop()
-    // cancels it, and it computes dt internally. The controller must NOT also drive
-    // engine._loop from an external ticker -- that double-drives the loop and corrupts its
-    // dt, which breaks both particle life decay and completion detection. (An earlier
-    // version accepted a `sharedTicker` and did exactly that; it is removed.)
 
     let activeRecipe = null;
     let destroyed = false;
     let elapsed = 0;
     let onComplete = null;
 
-    // ── Reveal-scan scratch, all allocated ONCE (zero-GC on the reveal-start frame) ──
-    // The offscreen scan canvas, its context, and the spawn-point arrays are built here
-    // and reused across every reveal. Only getImageData() -- a single small typed array
-    // per reveal, mandated by the 2D canvas API -- is not reusable; the per-pixel object
-    // churn of the previous design (one `{x, y}` literal per surviving pixel) is gone.
-    let scanCanvas = null;
-    let scanCtx = null;
-    let scanW = 0, scanH = 0;
-    let spotX = new Float32Array(0);   // grown lazily if the source canvas is ever resized
-    let spotY = new Float32Array(0);
-    let spotCount = 0;
+    // The pixel scanner owns the offscreen scan canvas + spot arrays, all allocated once
+    // and reused across reveals -- zero per-pixel allocation on the reveal-start frame.
+    const scanner = createPixelScanner(sourceCanvas);
     const spot = { x: 0.5, y: 0.5 };   // the single shared, reused spawn point
 
-    function ensureScanBuffers(precision) {
-        const srcW = sourceCanvas.width || sourceCanvas.offsetWidth || 1;
-        const srcH = sourceCanvas.height || sourceCanvas.offsetHeight || 1;
-        const h = Math.max(1, Math.floor(srcH * (precision / srcW)));
-        if (scanCanvas && scanW === precision && scanH === h) return;
-        // Dims changed (or first run): (re)build. Off the hot path -- once per resize.
-        scanW = precision;
-        scanH = h;
-        if (!scanCanvas) {
-            scanCanvas = document.createElement('canvas');
-            scanCtx = scanCanvas.getContext('2d', { willReadFrequently: true });
-        }
-        scanCanvas.width = scanW;
-        scanCanvas.height = scanH;
-        const cap = scanW * scanH;
-        if (spotX.length < cap) {
-            spotX = new Float32Array(cap);
-            spotY = new Float32Array(cap);
-        }
-    }
-
-    // ── Scan remaining visible pixels from the scratch canvas into spotX/spotY ──
-    // Fills the preallocated arrays and sets spotCount. Allocates nothing per pixel.
-    function scanPixels(precision = scanPrecision) {
-        ensureScanBuffers(precision);
-        scanCtx.clearRect(0, 0, scanW, scanH);
-        scanCtx.drawImage(sourceCanvas, 0, 0, scanW, scanH);
-        const data = scanCtx.getImageData(0, 0, scanW, scanH).data;
-        let n = 0;
-        for (let i = 3; i < data.length; i += 4) {
-            if (data[i] > 128) {
-                const p = (i - 3) / 4;
-                spotX[n] = (p % scanW) / scanW;
-                spotY[n] = ((p / scanW) | 0) / scanH;
-                n++;
-            }
-        }
-        spotCount = n;
-    }
-
     // The particle-view object handed to recipe.tick every frame. Built ONCE and
     // reused: the engine's SoA arrays are stable references for the life of the engine,
     // so a fresh `{ x, y, ... }` literal per frame would be a pure zero-GC violation on
@@ -114,7 +88,7 @@ export function createScratchController(sourceCanvas, effectCanvas, {
     let pView = null;
 
     // ── Render callback (the engine calls this every frame with raw SoA arrays) ──
-    engine.onTick((dt, x, y, vx, vy, life, invLife, data, max) => {
+    function renderTick(dt, x, y, vx, vy, life, invLife, data, max) {
         if (destroyed || !activeRecipe) return;
         elapsed += dt;
         const w = effectCanvas.width;
@@ -134,7 +108,8 @@ export function createScratchController(sourceCanvas, effectCanvas, {
         );
 
         if (isFinished) {
-            engine.stop();
+            if (!driven) engine.stop();
+            releaseEngine();
             if (activeRecipe.destroy) activeRecipe.destroy();
             activeRecipe = null;
             ctx.clearRect(0, 0, w, h);
@@ -142,28 +117,48 @@ export function createScratchController(sourceCanvas, effectCanvas, {
             onComplete = null;
             if (done) done();
         }
-    });
+    }
+
+    // Release our hold on a shared engine's single render slot so the next controller can
+    // reveal on it. A no-op for an owned engine, which stays bound for its whole life.
+    function releaseEngine() {
+        if (ownEngine) return;
+        engine.onTick(null);
+        busySharedEngines.delete(engine);
+    }
+
+    // An owned engine is bound once for its whole life; the renderTick early-returns when no
+    // reveal is active. A shared engine is bound per-reveal (in reveal) and released on
+    // completion so it can serve other controllers.
+    if (ownEngine) engine.onTick(renderTick);
 
     return {
         /**
-         * Execute a reveal recipe.
+         * Execute a reveal recipe. Ignored if this controller is already revealing, is
+         * destroyed, or shares an engine that another controller is revealing on.
          * @param {Object} recipe
          * @param {Function} [onDone]  Called when the effect completes
          */
         reveal(recipe, onDone) {
             if (destroyed || activeRecipe) return;
+            if (!ownEngine && busySharedEngines.has(engine)) return;
 
             activeRecipe = recipe;
             onComplete = onDone || null;
             elapsed = 0;
+
+            if (!ownEngine) {
+                engine.onTick(renderTick);
+                busySharedEngines.add(engine);
+            }
             engine.clear();
 
             // Size the effect canvas to match the scratch layer
             const w = effectCanvas.width = sourceCanvas.offsetWidth || sourceCanvas.width;
             const h = effectCanvas.height = sourceCanvas.offsetHeight || sourceCanvas.height;
 
-            // Scan spawn points from visible pixels (fills spotX/spotY, sets spotCount).
-            scanPixels();
+            // Scan spawn points from visible pixels.
+            const spots = scanner.scan(scanPrecision);
 
             // Init recipe
             recipe.init(ctx, maxParticles, w, h);
@@ -175,10 +170,10 @@ export function createScratchController(sourceCanvas, effectCanvas, {
             const count = Math.min(requested, maxParticles);
             for (let i = 0; i < count; i++) {
                 const idx = engine._head;
-                if (spotCount > 0) {
-                    const k = rng.int(0, spotCount - 1);
-                    spot.x = spotX[k];
-                    spot.y = spotY[k];
+                if (spots.count > 0) {
+                    const k = rng.int(0, spots.count - 1);
+                    spot.x = spots.spotX[k];
+                    spot.y = spots.spotY[k];
                 } else {
                     spot.x = 0.5;
                     spot.y = 0.5;
@@ -187,8 +182,21 @@ export function createScratchController(sourceCanvas, effectCanvas, {
                 engine.emit(state.x, state.y, state.vx, state.vy, state.life, idx);
             }
 
-            // The engine owns its RAF loop; start() schedules it and drives onTick.
-            engine.start();
+            // Self-driven: the engine's RAF loop drives renderTick. Host-driven: the host
+            // calls controller.tick(dt) instead; we schedule nothing.
+            if (!driven) engine.start();
+        },
+
+        /**
+         * Advance one frame in host-driven mode. `dt` is in SECONDS. A no-op unless the
+         * controller was created with `{ driven: true }` AND a reveal is active -- so a host
+         * can safely call tick() on every controller each frame; only the revealing one (and,
+         * for a shared engine, only the single active controller) does work.
+         * @param {number} dt  Seconds since the previous frame.
+         */
+        tick(dt) {
+            if (destroyed || !driven || activeRecipe === null) return;
+            engine.tick(dt);
         },
 
         /** Re-seed the RNG. */
@@ -197,13 +205,14 @@ export function createScratchController(sourceCanvas, effectCanvas, {
         destroy() {
             if (destroyed) return;
             destroyed = true;
-            engine.stop();
+            if (!driven) engine.stop();
+            releaseEngine();
             if (activeRecipe && activeRecipe.destroy) activeRecipe.destroy();
             activeRecipe = null;
             onComplete = null;
-            scanCanvas = null;
-            scanCtx = null;
-            engine.destroy();
+            scanner.destroy();
+            // Only tear down an engine we created. A caller-supplied engine is theirs.
+            if (ownEngine) engine.destroy();
         },
     };
 }