@aardworx/wombat.rendering 0.21.11 → 0.21.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aardworx/wombat.rendering",
-  "version": "0.21.11",
+  "version": "0.21.13",
   "description": "WebGPU rendering layer for the Wombat TypeScript stack — RenderObject/RenderTask/runtime + window glue, port of Aardvark.Rendering's lower layers on top of WebGPU and wombat.shader.",
   "license": "MIT",
   "author": "krauthaufen",

package/src/runtime/heapAdapter.ts

@@ -621,11 +621,22 @@ export function renderObjectToHeapSpec(
     pipelineState: ro.pipelineState,
     inputs,
     ...(instanceAttributes !== undefined ? { instanceAttributes } : {}),
-    // ≠ 1 (not > 1): instanceCount 0 must flow through — the scan
-    // kernel emits indexCount × 0 = nothing, matching what the legacy
-    // path draws for zero instances. Omitting it would default to 1
-    // and pack a garbage instance from empty per-instance arrays.
-    ...(dc.instanceCount !== 1 ? { instanceCount: dc.instanceCount } : {}),
+    // Count binding, in preference order:
+    //   1. The scene layer's shape-invariant drawCall marker carries
+    //      the LIVE count aval (`__sgHeapSafeDraw.count`) — bind it so
+    //      count ticks flow to the drawTable in place (epoch morphing,
+    //      point add/remove) with no per-RO wrapper aval.
+    //   2. Snapshot ≠ 1 (not > 1): instanceCount 0 must flow through —
+    //      the scan kernel emits indexCount × 0 = nothing, matching
+    //      what the legacy path draws for zero instances. Omitting it
+    //      would default to 1 and pack a garbage instance.
+    ...((): { instanceCount?: aval<number> | number } => {
+      const marker = (ro.drawCall as {
+        __sgHeapSafeDraw?: { kind: string; count?: aval<number> };
+      }).__sgHeapSafeDraw;
+      if (marker?.count !== undefined) return { instanceCount: marker.count };
+      return dc.instanceCount !== 1 ? { instanceCount: dc.instanceCount } : {};
+    })(),
     ...geom,
     ...(textures !== undefined ? { textures } : {}),
     ...(ro.injectedStorage !== undefined && ro.injectedStorage.count > 0

package/src/runtime/heapScene/pools.ts

@@ -67,16 +67,42 @@ export const SEM_NORMALS   = 2;
  * in which chunk's bind group is active at draw time (shaders
  * never decode it).
  */
+/** Fresh placement for a changed value — everything `repack` needs to
+ *  decide whether the allocation still fits and how to re-encode. */
+export interface PoolPlacement {
+  readonly dataBytes: number;
+  readonly typeId: number;
+  readonly length: number;
+  readonly pack: (val: unknown, dst: Float32Array, off: number) => void;
+}
+
 interface PoolEntry {
   readonly chunkIdx: number;
   /** Byte offset within the chunk's GPUBuffer. Mutated by
    *  `UniformPool.remapRefs` when a waste-triggered arena compaction
-   *  relocates the allocation. */
+   *  relocates the allocation, and by the sized-repack realloc path. */
   ref: number;
-  readonly dataBytes: number;
-  readonly typeId: number;
-  readonly pack: (val: unknown, dst: Float32Array, off: number) => void;
+  /** Raw data bytes of the CURRENT allocation. Mutated by the
+   *  sized-repack realloc path. */
+  dataBytes: number;
+  typeId: number;
+  pack: (val: unknown, dst: Float32Array, off: number) => void;
   refcount: number;
+  /** Present for size-variable payloads (attribute buffers): re-derive
+   *  the placement from the CURRENT value so `repack` can realloc when
+   *  the payload grew or shrank (geometry morphing — epoch switches,
+   *  point add/remove). Absent = fixed-size (plain uniforms). */
+  replan?: (val: unknown) => PoolPlacement;
+}
+
+/** A pool allocation that moved during a sized repack — every
+ *  drawHeader field referencing (aval, chunkIdx, oldRef) must be
+ *  rewritten to newRef by the caller. */
+export interface MovedRef {
+  readonly av: aval<unknown>;
+  readonly chunkIdx: number;
+  readonly oldRef: number;
+  readonly newRef: number;
 }
 
 /**
@@ -200,10 +226,12 @@ export class UniformPool {
     typeId: number,
     length: number,
     pack: (val: unknown, dst: Float32Array, off: number) => void,
+    replan?: (val: unknown) => PoolPlacement,
   ): number {
     const existing = this.getEntry(av, chunkIdx);
     if (existing !== undefined) {
       existing.refcount++;
+      if (replan !== undefined && existing.replan === undefined) existing.replan = replan;
       return existing.ref;
     }
     const r = arena.alloc(dataBytes, chunkIdx);
@@ -237,6 +265,7 @@ export class UniformPool {
     void device;
     this.setEntry(av, {
       chunkIdx: finalChunk, ref: r.off, dataBytes, typeId, pack, refcount: 1,
+      ...(replan !== undefined ? { replan } : {}),
     });
     return r.off;
   }
@@ -282,9 +311,44 @@ export class UniformPool {
     arena: ChunkedAttributeArena,
     av: aval<unknown>,
     val: unknown,
-  ): void {
+  ): MovedRef[] | undefined {
     let dst: Float32Array | undefined;
+    let moved: MovedRef[] | undefined;
     for (const e of this.entriesOf(av)) {
+      if (e.replan !== undefined) {
+        // Size-variable payload: re-derive the placement from the new
+        // value. Same size → refresh the encoder and fall through to
+        // the in-place write; different size → realloc within the
+        // same chunk, rewrite header + data, and report the move so
+        // the caller re-seats every drawHeader field.
+        const p = e.replan(val);
+        if (p.dataBytes !== e.dataBytes) {
+          arena.release(e.chunkIdx, e.ref, e.dataBytes);
+          const r = arena.alloc(p.dataBytes, e.chunkIdx);
+          if (r.chunkIdx !== e.chunkIdx) {
+            throw new Error(
+              `UniformPool.repack: realloc spilled from chunk ${e.chunkIdx} to ${r.chunkIdx} ` +
+              `(${p.dataBytes} bytes) — the referencing bucket is bound to chunk ${e.chunkIdx}.`,
+            );
+          }
+          const allocBytes = ALIGN16(ALLOC_HEADER_PAD_TO + p.dataBytes);
+          const buf = new ArrayBuffer(allocBytes);
+          const u32 = new Uint32Array(buf);
+          const f32 = new Float32Array(buf);
+          u32[0] = p.typeId;
+          u32[1] = p.length;
+          u32[2] = p.length > 0 ? Math.floor(p.dataBytes / p.length) : 0;
+          p.pack(val, f32, ALLOC_HEADER_PAD_TO / 4);
+          arena.write(e.chunkIdx, r.off, new Uint8Array(buf));
+          (moved ??= []).push({ av, chunkIdx: e.chunkIdx, oldRef: e.ref, newRef: r.off });
+          e.ref = r.off;
+          e.dataBytes = p.dataBytes;
+          e.typeId = p.typeId;
+          e.pack = p.pack;
+          continue;
+        }
+        e.pack = p.pack;
+      }
       if (dst === undefined || dst.length !== e.dataBytes / 4) {
         dst = new Float32Array(e.dataBytes / 4);
       }
@@ -296,6 +360,7 @@ export class UniformPool {
       );
     }
     void device;
+    return moved;
   }
   /** Total bytes touched by `repack` for this aval — sum across
    *  chunks. Used by the dirty-bytes diagnostics. */

package/src/runtime/heapScene.ts

@@ -91,6 +91,7 @@ import {
   ENC_V3F_TIGHT, ENC_OCT32, ENC_C4B, SEM_POSITIONS, SEM_NORMALS,
   COMPACTION_WASTE_FLOOR_BYTES,
   type ArenaState,
+  type PoolPlacement,
 } from "./heapScene/pools.js";
 import { encodeModeKey, type PipelineStateDescriptor } from "./pipelineCache/index.js";
 import { snapshotDescriptor, ModeKeyTracker } from "./derivedModes/modeKeyCpu.js";
@@ -385,6 +386,12 @@ interface Bucket {
    * keyed by aval identity.
    */
   readonly localPerDrawAvals: (aval<unknown>[] | undefined)[];
+  /** drawHeader field index per pooled aval — PARALLEL to
+   *  `localPerDrawAvals[slot]`. Lets the sized-repack drain rewrite
+   *  exactly the fields whose aval's allocation moved (matching by
+   *  aval identity, never by numeric offset — a released offset can
+   *  be re-issued to a different aval within the same drain). */
+  readonly localPerDrawAvalFieldIdx: (number[] | undefined)[];
   /** Field indices (into `layout.drawHeaderFields`) whose drawHeader
    *  cells hold RAW arena refs (§7 output slots, no pool entry). */
   readonly localPerDrawRawFieldIdx: (number[] | undefined)[];
@@ -1150,6 +1157,79 @@ export function buildHeapScene(
     }
   }
 
+  // ─── HeapDrawSpec.instanceCount as an aval ────────────────────────
+  // The geometry-morphing / collection-count path (epoch switches,
+  // point add/remove): a count tick is ONE drawTable write (record
+  // word 4) + emit re-estimate + re-scan — no add/remove churn, no
+  // arena activity. Instance ATTRIBUTE payloads ride the sized-repack
+  // path independently; per-instance UNIFORM arrays (packed per
+  // count) are rejected with an adaptive count at addDraw.
+  const drawIdToCountAval = new Map<number, aval<number>>();
+  const drawIdToCountCallback = new Map<number, IDisposable>();
+  const countDirty = new Set<number>();
+
+  function subscribeCount(av: aval<number>, drawId: number): void {
+    drawIdToCountAval.set(drawId, av);
+    drawIdToCountCallback.set(
+      drawId,
+      addMarkingCallback(av, () => { countDirty.add(drawId); }),
+    );
+  }
+
+  function unsubscribeCount(drawId: number): void {
+    const cb = drawIdToCountCallback.get(drawId);
+    if (cb === undefined) return;
+    cb.dispose();
+    drawIdToCountCallback.delete(drawId);
+    drawIdToCountAval.delete(drawId);
+    countDirty.delete(drawId);
+  }
+
+  /** Update the drawTable record's instanceCount in place — the
+   *  word-4 sibling of `setEffectiveIndexCount`. */
+  function setEffectiveInstanceCount(drawId: number, newCount: number): void {
+    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 indexCount = partition.masterShadow[recIdx * ru32 + 3]!;
+      const oldCount = partition.masterShadow[recIdx * ru32 + 4]!;
+      partition.masterShadow[recIdx * ru32 + 4] = newCount >>> 0;
+      const delta = indexCount * (newCount - oldCount);
+      bucket.partitionDirty = true;
+      for (const sl of bucket.slots) {
+        sl.totalEmitEstimate = Math.max(0, sl.totalEmitEstimate + delta);
+        sl.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 indexCount = shadow[recIdx * RECORD_U32 + 3]!;
+      const oldCount = shadow[recIdx * RECORD_U32 + 4]!;
+      shadow[recIdx * RECORD_U32 + 4] = newCount >>> 0;
+      const byteOff = recIdx * RECORD_BYTES + 4 * 4;
+      if (byteOff < slot.drawTableDirtyMin) slot.drawTableDirtyMin = byteOff;
+      if (byteOff + 4 > slot.drawTableDirtyMax) slot.drawTableDirtyMax = byteOff + 4;
+      const delta = indexCount * (newCount - oldCount);
+      slot.totalEmitEstimate = Math.max(0, slot.totalEmitEstimate + delta);
+      slot.scanDirty = true;
+    }
+    const localSlot = drawIdToLocalSlot[drawId];
+    if (localSlot !== undefined) {
+      const e = bucket.localEntries[localSlot];
+      if (e !== undefined) e.instanceCount = newCount;
+    }
+  }
+
   function subscribeModeLeaf(av: aval<unknown>, drawId: number): void {
     let set = modeAvalToDrawIds.get(av);
     if (set === undefined) {
@@ -1732,7 +1812,18 @@ export function buildHeapScene(
     // `colorTargets` here silently dropped blends/write-masks from every
     // heap pipeline: transparent heap leaves painted opaque, and the OIT
     // pick passes' write-mask-0 "Colors" leaked color onto the composite.
+    // Locations the family's fragment shader actually writes — a
+    // signature target the shader has NO output for must set
+    // writeMask 0 (WebGPU: non-zero writeMask without a fragment
+    // output is a validation error; e.g. a non-picking leaf in a
+    // Colors+pickId pass writes only Colors).
+    const writtenLocations = new Set<number>();
+    for (const e of fam.schema.effects) {
+      const sc = fam.schema.perEffectSchema.get(e)!;
+      for (const fo of sc.fragmentOutputs) writtenLocations.add(fo.location);
+    }
     const targets: GPUColorTargetState[] = colorTargets.map((t, i) => {
+      if (!writtenLocations.has(i)) return { format: t.format, writeMask: 0 };
       const a = desc.attachments[i];
       if (a === undefined) return { format: t.format };
       return {
@@ -3091,7 +3182,7 @@ export function buildHeapScene(
       headerDirtyMin: Infinity, headerDirtyMax: 0,
       localPosRefs: [], localNorRefs: [],
       localEntries: [], localToDrawId: [],
-      localPerDrawAvals: [], localPerDrawRawFieldIdx: [], localPerDrawRefs: [], localLayoutIds: [],
+      localPerDrawAvals: [], localPerDrawAvalFieldIdx: [], localPerDrawRawFieldIdx: [], localPerDrawRefs: [], localLayoutIds: [],
       fieldIdx,
       posFieldIdx: fieldIdx.get("Positions") ?? -1,
       norFieldIdx: fieldIdx.get("Normals") ?? -1,
@@ -3365,8 +3456,24 @@ export function buildHeapScene(
     const hasIndices = spec.indices !== undefined;
     const indicesAval = hasIndices ? (asAval(spec.indices!) as aval<Uint32Array>) : undefined;
     const indexArr = hasIndices ? (readPlain(spec.indices!) as Uint32Array) : undefined;
+    const icAval =
+      spec.instanceCount !== undefined && typeof spec.instanceCount === "object"
+      && typeof (spec.instanceCount as { getValue?: unknown }).getValue === "function"
+        ? (spec.instanceCount as aval<number>)
+        : undefined;
     const instanceCount = spec.instanceCount !== undefined
       ? (readPlain(spec.instanceCount) as number) : 1;
+    if (icAval !== undefined && perInstanceUniforms.size > 0) {
+      // Per-instance UNIFORM arrays are packed `instanceCount` deep at
+      // addDraw — a changing count would need a repack protocol those
+      // packers don't have. Attribute-backed instancing (BufferViews /
+      // raw arrays) is unaffected: the payload rides the sized-repack
+      // path and the count merely selects a prefix.
+      throw new Error(
+        "heapScene: adaptive instanceCount is not supported together with per-instance UNIFORM values " +
+        `(fields: ${[...perInstanceUniforms].join(", ")}) — use instance attributes instead`,
+      );
+    }
 
     let estBytes = indexArr !== undefined ? ALIGN16(ALLOC_HEADER_PAD_TO + indexArr.byteLength) : 0;
     for (const f of layout.drawHeaderFields) {
@@ -3489,6 +3596,7 @@ export function buildHeapScene(
     // packs as a single value. Both go through the same pool — sharing
     // emerges from aval identity either way.
     const perDrawAvals: aval<unknown>[] = [];
+    const perDrawAvalFieldIdx: number[] = [];
     let perDrawRawFieldIdx: number[] | undefined;
     const perDrawRefs = new Int32Array(bucket.layout.drawHeaderFields.length).fill(-1);
     const setRef = (name: string, ref: number): void => {
@@ -3583,9 +3691,13 @@ export function buildHeapScene(
         let value: unknown;
         let placement: ReturnType<typeof poolPlacementFor>;
         let releasable: { _v: unknown } | undefined;
+        let replanFn: ((v: unknown) => PoolPlacement) | undefined;
         if (f.kind === "attribute-ref" && !isPerInstanceUniformField && isBufferView(provided)) {
           const bv = provided;
           placement = bufferViewPlacement(f, bv);
+          // Size-variable payload: geometry morphing re-derives the
+          // placement from the view's CURRENT buffer value.
+          replanFn = () => bufferViewPlacement(f, bv);
           av = bv.buffer as aval<unknown>;
           value = bv.buffer.getValue(tok);
         } else if (
@@ -3619,14 +3731,19 @@ export function buildHeapScene(
           placement = isPerInstanceUniformField
             ? perInstancePlacementFor(f, value, instanceCount)
             : poolPlacementFor(f, value);
+          if (f.kind === "attribute-ref" && !isPerInstanceUniformField) {
+            replanFn = (v) => poolPlacementFor(f, v);
+          }
         }
         const ref = pool.acquire(
           device, arena.attrs, av, bucket.chunkIdx, value,
           placement.dataBytes, placement.typeId, placement.length, placement.pack,
+          replanFn,
         );
         if (releasable !== undefined) releasable._v = null;   // staged — drop the CPU copy
         setRef(f.name, ref);
         perDrawAvals.push(av);
+        perDrawAvalFieldIdx.push(bucket.fieldIdx.get(f.name)!);
       }
     }
 
@@ -3638,6 +3755,7 @@ export function buildHeapScene(
     bucket.localToDrawId[localSlot] = drawId;
     bucket.drawSlots.add(localSlot);
     bucket.localPerDrawAvals[localSlot] = perDrawAvals;
+    bucket.localPerDrawAvalFieldIdx[localSlot] = perDrawAvalFieldIdx;
     bucket.localPerDrawRawFieldIdx[localSlot] = perDrawRawFieldIdx;
     bucket.localPerDrawRefs[localSlot]  = perDrawRefs;
     const layoutId = fam.schema.layoutIdOf.get(spec.effect)!;
@@ -3839,6 +3957,9 @@ export function buildHeapScene(
         setEffectiveIndexCount(drawId, 0);
       }
     }
+    if (icAval !== undefined) {
+      subscribeCount(icAval, drawId);
+    }
 
     // ─── Reactive rebucket: track PS-modeKey changes ────────────────
     // When any mode-axis aval marks (e.g. cullCval.value = 'front'),
@@ -3955,6 +4076,7 @@ export function buildHeapScene(
     // Tear down `active` subscription (if any) so its callback won't
     // fire after the underlying drawTable record is gone.
     unsubscribeActive(drawId);
+    unsubscribeCount(drawId);
     // §7: deregister this RO's derivation records and release slots.
     if (derivedScene !== undefined) {
       const reg = derivedByDrawId.get(drawId);
@@ -4089,6 +4211,7 @@ export function buildHeapScene(
     bucket.localAtlasArrIdx[localSlot] = undefined;
 
     bucket.localPerDrawAvals[localSlot] = undefined;
+    bucket.localPerDrawAvalFieldIdx[localSlot] = undefined;
     bucket.localPerDrawRefs[localSlot]  = undefined;
     bucket.localLayoutIds[localSlot]    = undefined;
     bucket.localPosRefs[localSlot]  = undefined;
@@ -4479,11 +4602,63 @@ export function buildHeapScene(
       //    One writeBuffer per dirty aval, regardless of how many draws
       //    reference it — sharing pays off here.
       if (allocDirty.size > 0) {
+        // aval → (chunkIdx → newRef) for allocations the sized repack
+        // moved (payload grew/shrank → realloc'd within the chunk).
+        let movedByAval: Map<aval<unknown>, Map<number, number>> | undefined;
         for (const av of allocDirty) {
-          pool.repack(device, arena.attrs, av, av.getValue(tok));
+          const moved = pool.repack(device, arena.attrs, av, av.getValue(tok));
           totalDirtyBytes += pool.totalDataBytes(av);
+          if (moved !== undefined) {
+            for (const m of moved) {
+              let byChunk = (movedByAval ??= new Map()).get(m.av);
+              if (byChunk === undefined) { byChunk = new Map(); movedByAval.set(m.av, byChunk); }
+              byChunk.set(m.chunkIdx, m.newRef);
+            }
+          }
         }
         allocDirty.clear();
+        if (movedByAval !== undefined) {
+          // Re-seat every drawHeader field whose aval's allocation
+          // moved. Matched by AVAL IDENTITY via the parallel
+          // `localPerDrawAvalFieldIdx` — never by numeric offset (a
+          // released offset can be re-issued to a DIFFERENT aval in
+          // this same drain). Mirrors the compaction remap loop.
+          for (const bucket of buckets) {
+            for (const localSlot of bucket.drawSlots) {
+              const avals = bucket.localPerDrawAvals[localSlot];
+              const fidx = bucket.localPerDrawAvalFieldIdx[localSlot];
+              const refs = bucket.localPerDrawRefs[localSlot];
+              if (avals === undefined || fidx === undefined || refs === undefined) continue;
+              let changed = false;
+              for (let i = 0; i < avals.length; i++) {
+                const byChunk = movedByAval.get(avals[i]!);
+                if (byChunk === undefined) continue;
+                const nn = byChunk.get(bucket.chunkIdx);
+                if (nn === undefined) continue;
+                if (bucket.gpuRouted) {
+                  throw new Error(
+                    "heapScene: payload realloc under a GPU-routed (derived-modes) bucket is not supported yet",
+                  );
+                }
+                if (refs[fidx[i]!]! !== nn) { refs[fidx[i]!] = nn; changed = true; }
+              }
+              if (!changed) continue;
+              const pr = bucket.posFieldIdx >= 0 ? refs[bucket.posFieldIdx]! : -1;
+              const nr = bucket.norFieldIdx >= 0 ? refs[bucket.norFieldIdx]! : -1;
+              bucket.localPosRefs[localSlot] = pr < 0 ? undefined : pr;
+              bucket.localNorRefs[localSlot] = nr < 0 ? undefined : nr;
+              packBucketHeader(bucket, localSlot, refs, bucket.localLayoutIds[localSlot] ?? 0);
+              if (bucket.isAtlasBucket) {
+                const ts = bucket.localAtlasTextures[localSlot];
+                if (ts !== undefined) packAtlasTextureFields(bucket, localSlot, ts);
+              }
+              const byteOff = localSlot * bucket.layout.drawHeaderBytes;
+              if (byteOff < bucket.headerDirtyMin) bucket.headerDirtyMin = byteOff;
+              const end = byteOff + bucket.layout.drawHeaderBytes;
+              if (end > bucket.headerDirtyMax) bucket.headerDirtyMax = end;
+            }
+          }
+        }
       }
 
       // 1c. HeapDrawSpec.active drain — flip drawTable.indexCount
@@ -4502,6 +4677,18 @@ export function buildHeapScene(
         activeDirty.clear();
       }
 
+      // 1d. HeapDrawSpec.instanceCount aval drain — write the new
+      //     count into drawTable word 4 (emit = indexCount × count;
+      //     0 draws nothing). One record write + re-scan per tick.
+      if (countDirty.size > 0) {
+        for (const did of countDirty) {
+          const av = drawIdToCountAval.get(did);
+          if (av === undefined) continue;
+          setEffectiveInstanceCount(did, Math.max(0, av.getValue(tok) | 0));
+        }
+        countDirty.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)