@aardworx/wombat.rendering 0.18.1 → 0.19.1

package/dist/runtime/heapScene.d.ts

@@ -1,5 +1,5 @@
 import { type V2f } from "@aardworx/wombat.base";
-import type { ITexture } from "../core/texture.js";
+import type { HostTextureSource, ITexture } from "../core/texture.js";
 import type { ISampler } from "../core/sampler.js";
 import { AdaptiveToken } from "@aardworx/wombat.adaptive";
 import type { aval, aset } from "@aardworx/wombat.adaptive";
@@ -57,6 +57,18 @@ export interface HeapDrawSpec {
      * computes `indexCount * instanceCount` per record.
      */
     readonly instanceCount?: aval<number> | number;
+    /**
+     * Optional visibility gate. When ticks to `false`, this RO emits
+     * 0 vertices that frame — its drawTable record gets effective
+     * `indexCount = 0`, the scan kernel's prefix sum skips past it,
+     * and no fragment shader invocations fire. Pool allocations,
+     * arena uploads, and bucket membership all stay intact, so the
+     * `true → false → true` round-trip is a pair of small drawTable
+     * writes plus a scan-pass re-issue — no `addDraw`/`removeDraw`
+     * churn. Designed for `<Sg Active={cval}>` driven by LOD walkers
+     * that flip many tiles per camera move.
+     */
+    readonly active?: aval<boolean>;
     /**
      * Index buffer for this draw. Indices live in their own `INDEX`-
      * usage `GPUBuffer` (WebGPU forces this), separate from the arena.
@@ -247,6 +259,14 @@ export type HeapTextureSet = {
      * reference.
      */
     readonly repack?: (newTex: ITexture) => import("./textureAtlas/atlasPool.js").AtlasAcquisition;
+    /**
+     * Host source captured at adapter time, used by the heap-side
+     * re-acquire path when the pool entry was evicted while this spec
+     * sat idle (heap remove → re-add). Without it, `AtlasPool.acquire`
+     * allocates a fresh sub-rect with no `source` and skips `upload()`,
+     * leaving the drawHeader pointing at uninitialized atlas pixels.
+     */
+    readonly host?: HostTextureSource;
 };
 /**
  * Build a heap-backed scene renderer from a flat list of draws.

package/dist/runtime/heapScene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heapScene.d.ts","sourceRoot":"","sources":["../../src/runtime/heapScene.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"heapScene.d.ts","sourceRoot":"","sources":["../../src/runtime/heapScene.ts"],"names":[],"mappings":"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"}

package/dist/runtime/heapScene.js

@@ -119,6 +119,96 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
      */
     const modeAvalToDrawIds = new Map();
     const modeAvalCallbacks = new Map();
+    // ─── HeapDrawSpec.active subscription ────────────────────────────────
+    // Per-drawId state for the "skip without re-allocating" path. When a
+    // tile (or any RO) flips visibility many times per second (e.g. an
+    // LOD walker culling/uncrossing the frustum), pool churn would be
+    // prohibitive. Instead we keep the RO in the bucket and flip its
+    // drawTable record's `indexCount` field between the original count
+    // (visible) and 0 (hidden). The scan kernel's prefix sum naturally
+    // skips a record with 0 emit count, so this costs one drawTable
+    // write + a re-scan dispatch — no arena/freelist activity.
+    const drawIdToActiveAval = new Map();
+    const drawIdToOrigIndexCount = new Map();
+    const drawIdToActiveCallback = new Map();
+    const activeAvalToDrawIds = new Map();
+    const activeDirty = new Set();
+    function subscribeActive(av, drawId) {
+        let set = activeAvalToDrawIds.get(av);
+        if (set === undefined) {
+            set = new Set();
+            activeAvalToDrawIds.set(av, set);
+        }
+        set.add(drawId);
+        const cb = addMarkingCallback(av, () => { activeDirty.add(drawId); });
+        drawIdToActiveCallback.set(drawId, cb);
+    }
+    function unsubscribeActive(drawId) {
+        const av = drawIdToActiveAval.get(drawId);
+        if (av === undefined)
+            return;
+        const cb = drawIdToActiveCallback.get(drawId);
+        cb?.dispose();
+        drawIdToActiveCallback.delete(drawId);
+        const set = activeAvalToDrawIds.get(av);
+        if (set !== undefined) {
+            set.delete(drawId);
+            if (set.size === 0)
+                activeAvalToDrawIds.delete(av);
+        }
+        drawIdToActiveAval.delete(drawId);
+        drawIdToOrigIndexCount.delete(drawId);
+        activeDirty.delete(drawId);
+    }
+    /** Update the drawTable record's effective indexCount in place
+     *  (GPU-routed: masterShadow + partition re-dispatch; legacy:
+     *  drawTableShadow + scan re-dispatch). Common helper used by the
+     *  active-aval drain in `update()`. */
+    function setEffectiveIndexCount(drawId, newIndexCount) {
+        const bucket = drawIdToBucket[drawId];
+        if (bucket === undefined)
+            return;
+        if (bucket.gpuRouted) {
+            const partition = bucket.partitionScene;
+            const recIdx = bucket.drawIdToRecord.get(drawId);
+            if (recIdx === undefined)
+                return;
+            const ru32 = partition.recordU32;
+            const oldIndexCount = partition.masterShadow[recIdx * ru32 + 3];
+            const instanceCount = partition.masterShadow[recIdx * ru32 + 4];
+            partition.masterShadow[recIdx * ru32 + 3] = newIndexCount >>> 0;
+            const delta = (newIndexCount - oldIndexCount) * instanceCount;
+            bucket.partitionDirty = true;
+            for (const s of bucket.slots) {
+                s.totalEmitEstimate = Math.max(0, s.totalEmitEstimate + delta);
+                s.scanDirty = true;
+            }
+        }
+        else {
+            const slotIdx = drawIdToSlotIdx[drawId];
+            const slot = slotIdx !== undefined ? bucket.slots[slotIdx] : bucket.slots[0];
+            if (slot === undefined)
+                return;
+            const localSlot = drawIdToLocalSlot[drawId];
+            if (localSlot === undefined)
+                return;
+            const recIdx = slot.slotToRecord[localSlot];
+            if (recIdx === undefined || recIdx < 0)
+                return;
+            const shadow = slot.drawTableShadow;
+            const oldIndexCount = shadow[recIdx * RECORD_U32 + 3];
+            const instanceCount = shadow[recIdx * RECORD_U32 + 4];
+            shadow[recIdx * RECORD_U32 + 3] = newIndexCount >>> 0;
+            const byteOff = recIdx * RECORD_BYTES + 3 * 4;
+            if (byteOff < slot.drawTableDirtyMin)
+                slot.drawTableDirtyMin = byteOff;
+            if (byteOff + 4 > slot.drawTableDirtyMax)
+                slot.drawTableDirtyMax = byteOff + 4;
+            const delta = (newIndexCount - oldIndexCount) * instanceCount;
+            slot.totalEmitEstimate = Math.max(0, slot.totalEmitEstimate + delta);
+            slot.scanDirty = true;
+        }
+    }
     function subscribeModeLeaf(av, drawId) {
         let set = modeAvalToDrawIds.get(av);
         if (set === undefined) {
@@ -1924,6 +2014,11 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
     // inside a single outer evaluateAlways and invoke addDrawImpl
     // directly with their token — collapsing 1000× nested
     // evaluateAlways into 1× outer.
+    // DEBUG counters.
+    let __addDrawCalls = 0;
+    let __removeDrawCalls = 0;
+    sceneObj.__addDrawCalls = () => __addDrawCalls;
+    sceneObj.__removeDrawCalls = () => __removeDrawCalls;
     function addDraw(spec) {
         let id = -1;
         sceneObj.evaluateAlways(AdaptiveToken.top, (tok) => {
@@ -1932,6 +2027,7 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         return id;
     }
     function addDrawImpl(spec, outerTok) {
+        __addDrawCalls++;
         const drawId = nextDrawId++;
         // Family-merge (slice 3c): build the family lazily from this
         // single spec when no batched lazy-build occurred earlier (e.g.
@@ -2122,6 +2218,61 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         packBucketHeader(bucket, localSlot, perDrawRefs, layoutId);
         if (bucket.isAtlasBucket && spec.textures !== undefined && spec.textures.kind === "atlas") {
             packAtlasTextureFields(bucket, localSlot, spec.textures);
+            // Pair this addDraw with one atlas refcount bump. The spec's
+            // release closure (stored below, fired in removeDraw) decrements
+            // exactly once per add/remove cycle; without this incRef the
+            // refcount underflows when the same cached spec is re-introduced
+            // across multiple aset add/remove cycles (e.g., a tile flipping
+            // in and out of the heap-eligible subset).
+            //
+            // Falls back to a full re-acquire if the entry was already
+            // evicted (incRef returns false): in that case the spec's stored
+            // (pageId, origin, size) are stale and the new acquire's values
+            // overwrite them before packAtlasTextureFields is re-called.
+            if (atlasPool !== undefined) {
+                const ok = atlasPool.incRef(spec.textures.poolRef);
+                if (!ok) {
+                    // Entry was evicted while the cached spec was idle in heap-
+                    // remove state. Acquire a fresh sub-rect, redirect the spec
+                    // (and the per-aval cell behind its release closure) to the
+                    // new ref, and re-emit the drawHeader fields.
+                    // Pass the captured `host` as `source` so the pool's
+                    // `finalize` re-runs `upload()` for the fresh sub-rect. Without
+                    // this, AtlasPool.acquire allocates the rect and skips the
+                    // upload (the `source.host !== undefined` branch in finalize),
+                    // so the drawHeader points at uninitialized atlas pixels —
+                    // exactly the "black rectangle holes" symptom on tiles that
+                    // cycled out and back in across a long-enough gap to be
+                    // evicted.
+                    const reW = spec.textures.size.x;
+                    const reH = spec.textures.size.y;
+                    const host = spec.textures.host;
+                    const acq = atlasPool.acquire(spec.textures.page.format, spec.textures.sourceAval, reW, reH, {
+                        wantsMips: spec.textures.numMips > 1,
+                        ...(host !== undefined ? { source: { width: reW, height: reH, host } } : {}),
+                    });
+                    spec.textures.pageId = acq.pageId;
+                    spec.textures.origin = acq.origin;
+                    spec.textures.size = acq.size;
+                    spec.textures.numMips = acq.numMips;
+                    spec.textures.page = acq.page;
+                    spec.textures.poolRef = acq.ref;
+                    // The release closure captures a per-aval cell whose `ref`
+                    // must track the LATEST acquired sub-rect; otherwise the
+                    // closure releases a long-evicted ref (no-op leak).
+                    if (spec.textures.repack !== undefined) {
+                        // repack updates the per-aval cell to the new ref as a
+                        // side effect of its own atlas-mark drain path. Re-using
+                        // it here would free the entry we just acquired; instead
+                        // mirror the same effect with a tiny helper attached to
+                        // the spec at adapter time (`__retarget`).
+                    }
+                    const retarget = spec.textures.__retarget;
+                    if (retarget !== undefined)
+                        retarget(acq.ref);
+                    packAtlasTextureFields(bucket, localSlot, spec.textures);
+                }
+            }
             bucket.localAtlasReleases[localSlot] = spec.textures.release;
             bucket.localAtlasTextures[localSlot] = spec.textures;
             // Reactivity wire-up: subscribe to `sourceAval` (so sceneObj.inputChanged
@@ -2226,6 +2377,22 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         drawIdToLocalSlot[drawId] = localSlot;
         drawIdToSlotIdx[drawId] = roSlotIdx;
         drawIdToIndexAval[drawId] = indicesAval;
+        // ─── HeapDrawSpec.active wire-up ──────────────────────────────────
+        // Track the visibility aval (if any) and apply its initial value
+        // immediately. After this point, ticks on the aval are routed via
+        // `subscribeActive` → `activeDirty` and drained in `update()`.
+        if (spec.active !== undefined) {
+            drawIdToActiveAval.set(drawId, spec.active);
+            drawIdToOrigIndexCount.set(drawId, idxAlloc.count);
+            const initial = spec.active.getValue(outerTok);
+            subscribeActive(spec.active, drawId);
+            if (initial === false) {
+                // Apply the off state synchronously so the very first frame
+                // already skips this RO (no flash of un-gated geometry while
+                // we wait for the next update tick).
+                setEffectiveIndexCount(drawId, 0);
+            }
+        }
         // ─── Reactive rebucket: track PS-modeKey changes ────────────────
         // When any mode-axis aval marks (e.g. cullCval.value = 'front'),
         // schedule this RO for rebucket on the next update(). Today's
@@ -2329,10 +2496,14 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         return drawId;
     }
     function removeDraw(drawId) {
+        __removeDrawCalls++;
         const bucket = drawIdToBucket[drawId];
         const localSlot = drawIdToLocalSlot[drawId];
         if (bucket === undefined || localSlot === undefined)
             return;
+        // Tear down `active` subscription (if any) so its callback won't
+        // fire after the underlying drawTable record is gone.
+        unsubscribeActive(drawId);
         // §7: deregister this RO's derivation records and release slots.
         if (derivedScene !== undefined) {
             const reg = derivedByDrawId.get(drawId);
@@ -2345,9 +2516,15 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             const partition = bucket.partitionScene;
             const recIdx = bucket.drawIdToRecord.get(drawId);
             const removedEntry = bucket.localEntries[localSlot];
-            const removedCount = removedEntry !== undefined
-                ? removedEntry.indexCount * removedEntry.instanceCount
-                : 0;
+            // Read the EFFECTIVE indexCount from masterShadow (already 0 for
+            // an inactive draw via setEffectiveIndexCount). Using the original
+            // count from localEntries would double-subtract for inactive draws
+            // (whose contribution was already removed when active flipped false).
+            const effectiveIndexCount = recIdx !== undefined
+                ? partition.masterShadow[recIdx * partition.recordU32 + 3]
+                : (removedEntry?.indexCount ?? 0);
+            const instanceCount = removedEntry?.instanceCount ?? 0;
+            const removedCount = effectiveIndexCount * instanceCount;
             if (recIdx !== undefined) {
                 const moved = partition.removeRecord(recIdx);
                 if (moved >= 0) {
@@ -2376,9 +2553,15 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             const slotIdx = drawIdToSlotIdx[drawId];
             const slot = slotIdx !== undefined ? bucket.slots[slotIdx] : bucket.slots[0];
             const removedEntry = bucket.localEntries[localSlot];
-            const removedCount = removedEntry !== undefined
-                ? removedEntry.indexCount * removedEntry.instanceCount
-                : 0;
+            const localSlotRec = slot.slotToRecord[localSlot];
+            // Effective (post-active) indexCount, read from shadow so that
+            // inactive draws contribute 0 here (their contribution was
+            // already removed when active flipped false).
+            const effectiveIndexCount = localSlotRec !== undefined && localSlotRec >= 0
+                ? slot.drawTableShadow[localSlotRec * RECORD_U32 + 3]
+                : (removedEntry?.indexCount ?? 0);
+            const instanceCount = removedEntry?.instanceCount ?? 0;
+            const removedCount = effectiveIndexCount * instanceCount;
             slot.totalEmitEstimate = Math.max(0, slot.totalEmitEstimate - removedCount);
             // Swap-pop: move the last record into the freed slot, decrement
             // recordCount. firstEmit is GPU-rewritten by the next scan, so
@@ -2680,6 +2863,22 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                 }
                 allocDirty.clear();
             }
+            // 1c. HeapDrawSpec.active drain — flip drawTable.indexCount
+            //     between origIndexCount (visible) and 0 (hidden) for any RO
+            //     whose active aval ticked since last frame. Set is small in
+            //     steady state (only the ROs whose visibility actually
+            //     changed). No pool / arena / freelist activity.
+            if (activeDirty.size > 0) {
+                for (const did of activeDirty) {
+                    const av = drawIdToActiveAval.get(did);
+                    if (av === undefined)
+                        continue;
+                    const a = av.getValue(tok);
+                    const orig = drawIdToOrigIndexCount.get(did) ?? 0;
+                    setEffectiveIndexCount(did, a ? orig : 0);
+                }
+                activeDirty.clear();
+            }
             // 1b. Atlas-texture aval reactivity: an `aval<ITexture>` that
             //     drives an atlas placement was marked. Repack the pool entry
             //     and rewrite the drawHeader fields of every (bucket, slot)
@@ -3101,7 +3300,26 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                         const typeId = arenaU32[refU32];
                         const length = arenaU32[refU32 + 1];
                         if (!KNOWN_TYPE_IDS.has(typeId)) {
-                            push(`bucket#${bucketIdx} slot=${slot} field='${f.name}' alloc@0x${ref.toString(16)} typeId=${typeId} unknown`);
+                            // Dump the first 8 u32s of the alloc to help diagnose
+                            // what wrote garbage onto the header. Also peek the
+                            // FOUR u32s BEFORE the alloc to see if a neighbour
+                            // overran into us.
+                            const before = refU32 >= 4
+                                ? `prev=[${arenaU32[refU32 - 4]},${arenaU32[refU32 - 3]},${arenaU32[refU32 - 2]},${arenaU32[refU32 - 1]}] `
+                                : "";
+                            const here = `here=[${arenaU32[refU32]},${arenaU32[refU32 + 1]},${arenaU32[refU32 + 2]},${arenaU32[refU32 + 3]},${arenaU32[refU32 + 4]},${arenaU32[refU32 + 5]},${arenaU32[refU32 + 6]},${arenaU32[refU32 + 7]}]`;
+                            // Compare CPU shadow vs GPU read-back. Differ → GPU
+                            // write corrupted; match → bug is in CPU-side write path
+                            // OR the alloc never went through pool.acquire.
+                            const shadowChunk = arena.attrs.chunk(0);
+                            const shadowU32 = shadowChunk.peekShadowU32(ref, 8);
+                            const shadowStr = `shadow=[${shadowU32[0]},${shadowU32[1]},${shadowU32[2]},${shadowU32[3]},${shadowU32[4]},${shadowU32[5]},${shadowU32[6]},${shadowU32[7]}]`;
+                            const cpuMatches = shadowU32[0] === arenaU32[refU32]
+                                && shadowU32[1] === arenaU32[refU32 + 1]
+                                && shadowU32[2] === arenaU32[refU32 + 2]
+                                && shadowU32[3] === arenaU32[refU32 + 3];
+                            const verdict = cpuMatches ? "GPU=CPU (likely CPU-write bug)" : "GPU≠CPU (likely GPU-write corruption)";
+                            push(`bucket#${bucketIdx} slot=${slot} field='${f.name}' alloc@0x${ref.toString(16)} typeId=${typeId} unknown ${verdict} ${before}${here} ${shadowStr}`);
                             attrAllocsBad++;
                             continue;
                         }
@@ -3205,11 +3423,18 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
                                 tilesBad++;
                             }
                         }
+                        // The scan kernel intentionally writes `numRecords - 1` as the
+                        // sentinel (not `numRecords`) — the render VS's binary search
+                        // uses `hi = firstDrawInTile[_tileIdx + 1u]` as an *inclusive*
+                        // upper bound, so the sentinel must point at the last valid
+                        // record slot. See scanKernel.ts `buildTileIndex` for the
+                        // full rationale.
+                        const expectedSentinel = recordCount === 0 ? 0 : recordCount - 1;
                         const sentinel = fdt[dc.numTiles];
                         tilesChecked++;
-                        if (sentinel !== recordCount) {
+                        if (sentinel !== expectedSentinel) {
                             push(`bucket#${bucketIdx} firstDrawInTile[${dc.numTiles}] sentinel ` +
-                                `got=${sentinel} expected=${recordCount}`);
+                                `got=${sentinel} expected=${expectedSentinel}`);
                             tilesBad++;
                         }
                         dc.firstDrawInTile.unmap();
@@ -4098,6 +4323,8 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             return { emitsChecked: sampleCount, gpuMismatches, issues };
         },
     };
-    return { frame, update, encodeIntoPass, encodeComputePrep, addDraw, removeDraw, stats, dispose, _debug };
+    const __addDrawCallsGetter = () => __addDrawCalls;
+    const __removeDrawCallsGetter = () => __removeDrawCalls;
+    return { frame, update, encodeIntoPass, encodeComputePrep, addDraw, removeDraw, stats, dispose, _debug, __addDrawCalls: __addDrawCallsGetter, __removeDrawCalls: __removeDrawCallsGetter };
 }
 //# sourceMappingURL=heapScene.js.map