@aardworx/wombat.rendering 0.9.15 → 0.9.17

package/dist/runtime/heapScene.js

@@ -55,6 +55,7 @@ import { GrowBuffer, MIN_BUFFER_BYTES, POW2, ALIGN16, } from "./heapScene/growBu
 import { UniformPool, IndexPool, DrawHeap, AttributeArena, IndexAllocator, insertSortedFreeBlock, buildArenaState, arenaBytes, writeAttribute, asAval, isBufferView, asFloat32, ALLOC_HEADER_BYTES, ALLOC_HEADER_PAD_TO, ENC_V3F_TIGHT, SEM_POSITIONS, SEM_NORMALS, } from "./heapScene/pools.js";
 import { encodeModeKey } from "./pipelineCache/index.js";
 import { snapshotDescriptor, ModeKeyTracker } from "./derivedModes/modeKeyCpu.js";
+import { addMarkingCallback } from "@aardworx/wombat.adaptive";
 export function buildHeapScene(device, sig, initialDraws, opts = {}) {
     const atlasPool = opts.atlasPool;
     const colorAttachmentName = sig.colorNames[0];
@@ -94,11 +95,48 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
      * references.
      */
     const drawIdToSpec = [];
-    /** Per-draw ModeKeyTracker — subscribes to PS aval marks, recomputes
-     *  the modeKey, schedules a rebucket if it changed. */
+    /** Per-draw ModeKeyTracker — recomputes the modeKey on demand. Does
+     *  NOT install per-instance marking callbacks; subscriptions are
+     *  scene-level (deduped by aval identity below). */
     const drawIdToModeTracker = [];
     /** drawIds whose PS marked since last update; drained by `update`. */
     const dirtyModeKeyDrawIds = new Set();
+    /**
+     * Scene-level mode-aval subscription dedupe. One IDisposable per
+     * unique leaf aval, plus a Set of dependent drawIds. When the aval
+     * marks, all drawIds in the set become dirty in O(1) per RO instead
+     * of installing N separate addMarkingCallbacks. The big win for the
+     * shared-cullCval case (20k ROs subscribing to one cval → 1 callback
+     * instead of 20k).
+     */
+    const modeAvalToDrawIds = new Map();
+    const modeAvalCallbacks = new Map();
+    function subscribeModeLeaf(av, drawId) {
+        let set = modeAvalToDrawIds.get(av);
+        if (set === undefined) {
+            set = new Set();
+            modeAvalToDrawIds.set(av, set);
+            modeAvalCallbacks.set(av, addMarkingCallback(av, () => {
+                for (const id of set)
+                    dirtyModeKeyDrawIds.add(id);
+            }));
+        }
+        set.add(drawId);
+    }
+    function unsubscribeModeLeaf(av, drawId) {
+        const set = modeAvalToDrawIds.get(av);
+        if (set === undefined)
+            return;
+        set.delete(drawId);
+        if (set.size === 0) {
+            modeAvalToDrawIds.delete(av);
+            const cb = modeAvalCallbacks.get(av);
+            if (cb !== undefined) {
+                cb.dispose();
+                modeAvalCallbacks.delete(av);
+            }
+        }
+    }
     let nextDrawId = 0;
     /**
      * Unwrap an aval to its inner value, or pass through a plain value.
@@ -853,7 +891,14 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
     // right per-effect helper at draw time. Atlas-binding shape follows
     // from `family.drawHeaderUnion.atlasTextureBindings.size > 0`.
     void texIdOf; // retained for future per-bucket diagnostics
-    function findOrCreateBucket(effect, _textures, pipelineState) {
+    function findOrCreateBucket(effect, _textures, pipelineState, 
+    /**
+     * Optional precomputed descriptor. addDrawImpl passes this when
+     * the spec carries `modeRules` so the bucket key reflects the
+     * rule-evaluated value (not the raw PS aval values). When omitted
+     * the descriptor is snapshotted from PS as before.
+     */
+    precomputedDescriptor) {
         if (!familyBuilt) {
             throw new Error("heapScene: findOrCreateBucket called before family build");
         }
@@ -866,13 +911,25 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         // (the actual value-set in the descriptor), so identical-value
         // cvals collapse to ONE bucket. See docs/derived-modes.md and
         // tests/heap-multi-pipeline-bucket.test.ts.
-        const psDescriptor = snapshotDescriptor(pipelineState, sig);
+        const psDescriptor = precomputedDescriptor ?? snapshotDescriptor(pipelineState, sig);
         const psModeKey = encodeModeKey(psDescriptor);
         const bk = `family#${fam.schema.id}|mk#${psModeKey.toString(16)}`;
         const existing = bucketByKey.get(bk);
         if (existing !== undefined)
             return existing;
-        const ps = resolvePipelineState(pipelineState);
+        // If a precomputed descriptor is supplied (rule-evaluated path),
+        // use its post-rule axis values so the pipeline reflects what the
+        // RO actually wants. Otherwise fall through to PS-aval forcing.
+        const ps = precomputedDescriptor !== undefined
+            ? {
+                topology: precomputedDescriptor.topology,
+                cullMode: precomputedDescriptor.cullMode,
+                frontFace: precomputedDescriptor.frontFace,
+                ...(precomputedDescriptor.depth !== undefined
+                    ? { depth: { write: precomputedDescriptor.depth.write, compare: precomputedDescriptor.depth.compare } }
+                    : {}),
+            }
+            : resolvePipelineState(pipelineState);
         const layout = fam.schema.drawHeaderUnion;
         const isAtlasBucket = layout.atlasTextureBindings.size > 0;
         const vsModule = fam.vsModule;
@@ -1147,7 +1204,23 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         const perInstanceAttributes = spec.instanceAttributes !== undefined
             ? new Set(Object.keys(spec.instanceAttributes))
             : new Set();
-        const bucket = findOrCreateBucket(spec.effect, spec.textures, spec.pipelineState);
+        // If the spec has modeRules, pre-snapshot the rule-evaluated
+        // descriptor so the bucket key + pipeline reflect post-rule
+        // values. Without this, two ROs with identical PS but different
+        // rule outputs would collide on the same bucket.
+        let precomputedDescriptor;
+        if (spec.modeRules !== undefined) {
+            const uAvals = new Map();
+            for (const [name, val] of Object.entries(spec.inputs)) {
+                uAvals.set(name, asAval(val));
+            }
+            precomputedDescriptor = snapshotDescriptor(spec.pipelineState, sig, {
+                modeRules: spec.modeRules,
+                uniformAvals: uAvals,
+                token: outerTok,
+            });
+        }
+        const bucket = findOrCreateBucket(spec.effect, spec.textures, spec.pipelineState, precomputedDescriptor);
         const fam = familyFor(spec.effect);
         const effectFields = fam.fieldsForEffect.get(spec.effect.id);
         // Indices live in their own INDEX-usage buffer (WebGPU constraint).
@@ -1316,10 +1389,27 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         // value must move the RO to a different bucket. Without this
         // tracker the cval flip would be silently ignored.
         drawIdToSpec[drawId] = spec;
-        const tracker = new ModeKeyTracker(spec.pipelineState, sig, () => {
-            dirtyModeKeyDrawIds.add(drawId);
+        // skipSubscribe: this tracker doesn't install its own callbacks.
+        // The scene-level `modeAvalToDrawIds` does it once per unique aval
+        // (the 20k-ROs-share-one-cullCval optimization).
+        // If the spec has modeRules, pre-build a uniforms-aval map the
+        // rule closures will read against; the tracker auto-discovers
+        // which avals each rule reads and surfaces them via forEachLeaf.
+        let uniformAvals;
+        if (spec.modeRules !== undefined) {
+            const m = new Map();
+            for (const [name, val] of Object.entries(spec.inputs)) {
+                m.set(name, asAval(val));
+            }
+            uniformAvals = m;
+        }
+        const tracker = new ModeKeyTracker(spec.pipelineState, sig, () => { dirtyModeKeyDrawIds.add(drawId); }, {
+            skipSubscribe: true,
+            ...(spec.modeRules !== undefined ? { modeRules: spec.modeRules } : {}),
+            ...(uniformAvals !== undefined ? { uniformAvals } : {}),
         });
         drawIdToModeTracker[drawId] = tracker;
+        tracker.forEachLeaf((av) => subscribeModeLeaf(av, drawId));
         // ─── §7 derived-uniforms registration ────────────────────────────
         // A uniform binding on this RO is either a value (aval/constant) or a rule —
         // collect the rules (explicit `derivedUniform(...)` values + standard trafo
@@ -1482,8 +1572,10 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
         drawIdToIndexAval[drawId] = undefined;
         drawIdToSpec[drawId] = undefined;
         const oldTracker = drawIdToModeTracker[drawId];
-        if (oldTracker !== undefined)
+        if (oldTracker !== undefined) {
+            oldTracker.forEachLeaf((av) => unsubscribeModeLeaf(av, drawId));
             oldTracker.dispose();
+        }
         drawIdToModeTracker[drawId] = undefined;
         dirtyModeKeyDrawIds.delete(drawId);
         stats.totalDraws--;
@@ -1592,24 +1684,100 @@ export function buildHeapScene(device, sig, initialDraws, opts = {}) {
             if (dirtyModeKeyDrawIds.size > 0) {
                 const dirty = [...dirtyModeKeyDrawIds];
                 dirtyModeKeyDrawIds.clear();
+                // Bucket-level fast path: group dirty drawIds by bucket. If
+                // ALL of a bucket's ROs are dirty (typical SG case where one
+                // shared aval drives every leaf — e.g. <Sg CullMode={cullC}>
+                // wrapping 20k leaves), the whole bucket transitions together.
+                // Rebuild the bucket's pipeline + rename in bucketByKey,
+                // O(1) work instead of N remove+add cycles.
+                const byBucket = new Map();
                 for (const drawId of dirty) {
-                    const tracker = drawIdToModeTracker[drawId];
-                    if (tracker === undefined)
+                    const b = drawIdToBucket[drawId];
+                    if (b === undefined)
                         continue; // RO removed since mark
-                    const oldKey = tracker.modeKey;
-                    if (!tracker.recompute())
-                        continue; // value unchanged
-                    if (tracker.modeKey === oldKey)
-                        continue; // belt + braces
-                    const spec = drawIdToSpec[drawId];
-                    if (spec === undefined)
+                    let arr = byBucket.get(b);
+                    if (arr === undefined) {
+                        arr = [];
+                        byBucket.set(b, arr);
+                    }
+                    arr.push(drawId);
+                }
+                for (const [bucket, ids] of byBucket) {
+                    // First recompute every dirty tracker so .modeKey is fresh.
+                    // Filter out ones whose value didn't actually change.
+                    const changed = [];
+                    for (const drawId of ids) {
+                        const tracker = drawIdToModeTracker[drawId];
+                        if (tracker === undefined)
+                            continue;
+                        const oldKey = tracker.modeKey;
+                        if (!tracker.recompute())
+                            continue;
+                        if (tracker.modeKey === oldKey)
+                            continue;
+                        changed.push(drawId);
+                    }
+                    if (changed.length === 0)
                         continue;
-                    removeDraw(drawId);
-                    const newId = addDrawImpl(spec, tok);
-                    // The drawId returned by addDraw is a fresh slot; we don't
-                    // attempt to preserve the caller's id mapping in v1. v2
-                    // could thread the original id through if needed.
-                    void newId;
+                    // Try the all-together fast path.
+                    const wholeBucket = changed.length === bucket.drawSlots.size;
+                    if (wholeBucket) {
+                        const repId = changed[0];
+                        const repTracker = drawIdToModeTracker[repId];
+                        const newKey = repTracker.modeKey;
+                        // Compute the new bucketByKey string; we need the family.
+                        const sample = drawIdToSpec[repId];
+                        const fam = familyFor(sample.effect);
+                        const newBk = `family#${fam.schema.id}|mk#${newKey.toString(16)}`;
+                        const existing = bucketByKey.get(newBk);
+                        if (existing === undefined) {
+                            // No conflict — rename + rebuild pipeline in place.
+                            // Find this bucket's current key by linear scan
+                            // (buckets ≤ ~100 typically, so this is cheap).
+                            let oldBk;
+                            for (const [k, v] of bucketByKey) {
+                                if (v === bucket) {
+                                    oldBk = k;
+                                    break;
+                                }
+                            }
+                            if (oldBk !== undefined)
+                                bucketByKey.delete(oldBk);
+                            bucketByKey.set(newBk, bucket);
+                            // Build the new pipeline with the snapshotted PS.
+                            const desc = repTracker.descriptor;
+                            const { pipelineLayout } = getBgl(bucket.layout, bucket.isAtlasBucket);
+                            const newPipeline = device.createRenderPipeline({
+                                label: `heapScene/${newBk}/pipeline`,
+                                layout: pipelineLayout,
+                                vertex: { module: familyFor(sample.effect).vsModule, entryPoint: familyFor(sample.effect).vsEntryName, buffers: [] },
+                                fragment: { module: familyFor(sample.effect).fsModule, entryPoint: familyFor(sample.effect).fsEntryName, targets: colorTargets },
+                                primitive: { topology: desc.topology, cullMode: desc.cullMode, frontFace: desc.frontFace },
+                                ...(depthFormat !== undefined && desc.depth !== undefined
+                                    ? { depthStencil: { format: depthFormat, depthWriteEnabled: desc.depth.write, depthCompare: desc.depth.compare } }
+                                    : depthFormat !== undefined
+                                        ? { depthStencil: { format: depthFormat, depthWriteEnabled: false, depthCompare: "always" } }
+                                        : {}),
+                            });
+                            // Swap pipeline reference on the bucket's single slot.
+                            // (Multi-slot Phase 5c would update one slot at a time.)
+                            bucket.slots[0].pipeline = newPipeline;
+                            continue; // done with this bucket
+                        }
+                        // Conflict: another bucket already owns newBk. Fall through
+                        // to per-RO rebucket below, which will merge into `existing`.
+                    }
+                    // Slow path — per-RO rebucket (used when partial transition
+                    // OR when a merge with an existing destination bucket is
+                    // required).
+                    for (const drawId of changed) {
+                        const spec = drawIdToSpec[drawId];
+                        if (spec === undefined)
+                            continue;
+                        removeDraw(drawId);
+                        const newId = addDrawImpl(spec, tok);
+                        void newId;
+                    }
                 }
             }
             // 1. Pool: re-pack any aval whose value changed since last frame.