@aardworx/wombat.rendering 0.8.1 → 0.9.1

package/src/core/renderTask.ts

@@ -1,16 +1,69 @@
 // RenderTask — the compiled, runnable form of an alist<Command>.
 // The runtime returns one of these from `compile`; the user calls
-// `run(token)` to encode + submit a frame.
+// `run(framebuffer, token)` to encode + submit a frame against the
+// supplied framebuffer instance. The framebuffer's signature must
+// match the one the task was compiled against.
 
 import type { AdaptiveToken } from "@aardworx/wombat.adaptive";
+import type { FramebufferSignature } from "./framebufferSignature.js";
+import type { IFramebuffer } from "./framebuffer.js";
 
 export interface IRenderTask {
+  /**
+   * The signature this task was compiled against. All pipelines
+   * baked in were specialised against this signature; framebuffers
+   * passed to `run`/`encode` must match.
+   */
+  readonly signature: FramebufferSignature;
+
   /**
    * Encode all commands into the GPU queue using the current
    * adaptive state read via `token`. Returns once submission has
    * been queued (does not wait for GPU completion).
    */
-  run(token: AdaptiveToken): void;
+  run(framebuffer: IFramebuffer, token: AdaptiveToken): void;
+
+  /**
+   * Total GPU buckets the heap path emits across this task's
+   * compiled scenes. With §6 family-merge in v1 this collapses to
+   * one per pipelineState per Render command. Useful for status
+   * text / dev overlays.
+   */
+  heapBucketCount(): number;
+
+  /** Per-frame breakdown of §7 derived-uniforms work (CPU, last frame). */
+  heapDerivedTimings(): {
+    pullMs: number; uploadMs: number; encodeMs: number; records: number;
+  };
+
+  /** Diagnostic: walks heap drawHeaders, drawTables, prefix sums,
+   *  attribute alloc headers; checks refs/indices/instance counts and
+   *  data finiteness. Useful for hunting OOB-corruption bugs. */
+  validateHeap(): Promise<{
+    arenaBytes: number; issues: string[];
+    okRefs: number; badRefs: number;
+    drawTableRows: number; drawTableErrs: number; prefixSumErrs: number;
+    attrAllocsChecked: number; attrAllocsBad: number;
+    tilesChecked: number; tilesBad: number;
+    vidChecks: number; vidBad: number;
+    indicesHash: string;
+  }>;
+  /** CPU draw simulator. Walks N sampled emits, runs the binary-search
+   *  + index/instance recovery, and verifies every storage read lands
+   *  inside the bound buffer. */
+  simulateDraws(samples?: number): Promise<{
+    emitsChecked: number; oob: number; issues: string[];
+  }>;
+  /** GPU-side binary-search probe — runs the same search the render VS
+   *  does and compares its result with the CPU's. */
+  probeBinarySearch(samples?: number): Promise<{
+    emitsChecked: number; gpuMismatches: number; issues: string[];
+  }>;
+  /** Triangle-level coherence — verifies each triangle's 3 emits land
+   *  in the same slot (no cross-RO triangles). */
+  checkTriangleCoherence(samples?: number): Promise<{
+    trianglesChecked: number; crossSlot: number; issues: string[];
+  }>;
 
   /** Tear down resources owned by the task. Idempotent. */
   dispose(): void;

package/src/resources/preparedRenderObject.ts

@@ -548,9 +548,9 @@ export function prepareRenderObject(
     // tight one-element buffer and asks every vertex/instance to read
     // it. WebGPU reads the same element when arrayStride is 0
     // (regardless of stepMode), so override the default tight stride
-    // here. Without this the second vertex would read past the end of
-    // the 16-byte buffer and pick up zeros — colorAval would tint
-    // only the first vertex of a draw.
+    // here. Without this the second vertex would read past the end
+    // of the 16-byte buffer and pick up zeros — colorAval would tint
+    // only the first vertex of each draw.
     const isBroadcast = view.singleValue !== undefined;
     const stride = isBroadcast ? 0 : BufferView.strideOf(view);
     const offset = BufferView.offsetOf(view);

package/src/resources/uniformBuffer.ts

@@ -135,6 +135,16 @@ export function writeField(
     view.f32.set(value, offset >> 2);
     return;
   }
+  if (value instanceof Float64Array) {
+    // Downcast to f32 in-place. Aardvark's V/M types in the F#-on-JS
+    // path use Float64Array internally (V4d / M44d / Trafo3d) but
+    // GPU uniforms are always f32 — converting here saves every
+    // F# user from sprinkling V4f / V3f conversions across their
+    // Sg.Uniform values.
+    const dst = view.f32.subarray(offset >> 2, (offset >> 2) + value.length);
+    for (let i = 0; i < value.length; i++) dst[i] = value[i]!;
+    return;
+  }
   if (value instanceof Int32Array) {
     view.i32.set(value, offset >> 2);
     return;
@@ -146,6 +156,11 @@ export function writeField(
   if (value !== null && typeof value === "object" && "_data" in (value as object)) {
     const data = (value as { _data: unknown })._data;
     if (data instanceof Float32Array) { view.f32.set(data, offset >> 2); return; }
+    if (data instanceof Float64Array) {
+      const dst = view.f32.subarray(offset >> 2, (offset >> 2) + data.length);
+      for (let i = 0; i < data.length; i++) dst[i] = data[i]!;
+      return;
+    }
     if (data instanceof Int32Array)   { view.i32.set(data, offset >> 2); return; }
     if (data instanceof Uint32Array)  { view.u32.set(data, offset >> 2); return; }
   }

package/src/runtime/derivedUniforms/dispatch.ts

@@ -0,0 +1,407 @@
+// §7 single-dispatch leaf dispatcher.
+//
+// Each bucket holds a static-ish records buffer (only edited on RO
+// add/remove). Per frame the caller:
+//   1. Drains dirty constituent avals and uploads the changed byte
+//      range to the shared constituents buffer.
+//   2. Builds a dirty bitmask (one bit per constituent slot) and
+//      uploads it to the shared dirty buffer.
+//   3. For each bucket, calls `dispatcher.encode(enc)` — one
+//      compute pass with one dispatch per bucket. The kernel
+//      early-returns on records whose inputs are all clean.
+//
+// No worklist building, no atomicAdd compaction, no per-frame record
+// encoding. The records buffer changes only when ROs come and go.
+
+import {
+  ConstituentSlots, DF32_MAT4_BYTES,
+  type DerivationRecord, type SlotIndex,
+} from "./slots.js";
+import {
+  RECORD_STRIDE_BYTES, RECORD_STRIDE_U32, RECORD_FIELD,
+  DERIVED_UBER_KERNEL_WGSL,
+} from "./uberKernel.wgsl.js";
+
+/** Live getters for the GPU resources the dispatcher needs. The scene
+ *  may replace these buffers in-place when capacity grows; the
+ *  dispatcher rebinds each frame. */
+export interface DerivedUniformsResources {
+  readonly constituentsBuf: () => GPUBuffer;
+  readonly mainHeapBuf:     () => GPUBuffer;
+}
+
+/** Per-bucket records buffer. Records are added/removed when ROs
+ *  enter/leave the bucket. Uses swap-remove to keep the buffer dense.
+ *  CPU mirror is kept up-to-date; the dirty range is uploaded once
+ *  per `flush()`. */
+export class RecordsBuffer {
+  private readonly device: GPUDevice;
+  private cpu: Uint32Array;
+  private cap = 0;             // record slots (capacity, in records)
+  private count = 0;           // live records
+  private nextId = 0;
+  private readonly slotById = new Map<number, number>();
+  private readonly idBySlot: number[] = [];
+
+  /** Dirty CPU-mirror byte range that must be uploaded next flush. */
+  private dirtyMinByte = Infinity;
+  private dirtyMaxByte = -1;
+
+  private gpu: GPUBuffer | undefined;
+  private gpuCap = 0;          // record slots in `gpu`
+
+  constructor(device: GPUDevice, initialCapacity = 64) {
+    this.device = device;
+    this.cap = initialCapacity;
+    this.cpu = new Uint32Array(this.cap * RECORD_STRIDE_U32);
+  }
+
+  /** Add a record. Returns a stable handle for later removal. */
+  add(rec: DerivationRecord): number {
+    if (this.count === this.cap) this.growCpu();
+    const slot = this.count++;
+    const id = this.nextId++;
+    this.slotById.set(id, slot);
+    this.idBySlot[slot] = id;
+    this.writeAt(slot, rec);
+    return id;
+  }
+
+  /** Swap-remove. The last record moves into the freed slot. */
+  remove(id: number): void {
+    const slot = this.slotById.get(id);
+    if (slot === undefined) {
+      throw new Error("RecordsBuffer.remove: unknown id");
+    }
+    const last = this.count - 1;
+    if (slot !== last) {
+      // Move last → slot.
+      const srcOff = last * RECORD_STRIDE_U32;
+      const dstOff = slot * RECORD_STRIDE_U32;
+      for (let i = 0; i < RECORD_STRIDE_U32; i++) {
+        this.cpu[dstOff + i] = this.cpu[srcOff + i]!;
+      }
+      const movedId = this.idBySlot[last]!;
+      this.slotById.set(movedId, slot);
+      this.idBySlot[slot] = movedId;
+      this.markDirty(slot, slot + 1);
+    }
+    this.slotById.delete(id);
+    this.idBySlot.length = last;
+    this.count = last;
+  }
+
+  /** Live record count. */
+  get recordCount(): number { return this.count; }
+
+  /** Ensure GPU buffer matches cap and upload dirty CPU range. Call
+   *  before `encode`. */
+  flush(): void {
+    if (this.gpu === undefined || this.gpuCap < this.cap) {
+      if (this.gpu !== undefined) this.gpu.destroy();
+      this.gpu = this.device.createBuffer({
+        label: "derivedUniforms.records",
+        size:  this.cap * RECORD_STRIDE_BYTES,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+      });
+      this.gpuCap = this.cap;
+      // Whole CPU mirror needs re-upload.
+      this.dirtyMinByte = 0;
+      this.dirtyMaxByte = this.count * RECORD_STRIDE_BYTES;
+    }
+    if (this.dirtyMaxByte > this.dirtyMinByte) {
+      const start = this.dirtyMinByte;
+      const end   = Math.min(this.dirtyMaxByte, this.count * RECORD_STRIDE_BYTES);
+      if (end > start) {
+        this.device.queue.writeBuffer(
+          this.gpu!, start,
+          this.cpu.buffer,
+          this.cpu.byteOffset + start,
+          end - start,
+        );
+      }
+      this.dirtyMinByte = Infinity;
+      this.dirtyMaxByte = -1;
+    }
+  }
+
+  buffer(): GPUBuffer {
+    if (this.gpu === undefined) {
+      // Empty bucket — make a tiny stub so binding always has something.
+      this.gpu = this.device.createBuffer({
+        label: "derivedUniforms.records.stub",
+        size:  RECORD_STRIDE_BYTES,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+      });
+      this.gpuCap = 1;
+    }
+    return this.gpu;
+  }
+
+  dispose(): void {
+    if (this.gpu !== undefined) {
+      this.gpu.destroy();
+      this.gpu = undefined;
+    }
+  }
+
+  // ── Internals ─────────────────────────────────────────────────────
+
+  private writeAt(slot: number, rec: DerivationRecord): void {
+    const off = slot * RECORD_STRIDE_U32;
+    this.cpu[off + RECORD_FIELD.recipe_id] = rec.recipe;
+    this.cpu[off + RECORD_FIELD.in0]       = rec.in0;
+    this.cpu[off + RECORD_FIELD.in1]       = rec.in1;
+    this.cpu[off + RECORD_FIELD.in2]       = rec.in2;
+    this.cpu[off + RECORD_FIELD.out_byte]  = rec.outByte;
+    this.markDirty(slot, slot + 1);
+  }
+
+  private markDirty(startSlot: number, endSlot: number): void {
+    const startByte = startSlot * RECORD_STRIDE_BYTES;
+    const endByte   = endSlot   * RECORD_STRIDE_BYTES;
+    if (startByte < this.dirtyMinByte) this.dirtyMinByte = startByte;
+    if (endByte   > this.dirtyMaxByte) this.dirtyMaxByte = endByte;
+  }
+
+  private growCpu(): void {
+    const newCap = this.cap * 2;
+    const grown = new Uint32Array(newCap * RECORD_STRIDE_U32);
+    grown.set(this.cpu);
+    this.cpu = grown;
+    this.cap = newCap;
+  }
+}
+
+/** One compute pipeline shared across buckets — created once per scene. */
+export class DerivedUniformsPipeline {
+  readonly pipeline: GPUComputePipeline;
+  readonly bgl:      GPUBindGroupLayout;
+
+  constructor(device: GPUDevice) {
+    const module = device.createShaderModule({ code: DERIVED_UBER_KERNEL_WGSL });
+    this.bgl = device.createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+        { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+        { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+        { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+      ],
+    });
+    this.pipeline = device.createComputePipeline({
+      layout: device.createPipelineLayout({ bindGroupLayouts: [this.bgl] }),
+      compute: { module, entryPoint: "main" },
+    });
+  }
+}
+
+/** Per-bucket dispatcher. One bind group cached, rebuilt only when a
+ *  bound buffer reference changes (constituents or main heap grew, or
+ *  records buffer was re-created). */
+export class DerivedUniformsDispatcher {
+  private readonly device: GPUDevice;
+  private readonly pipe:   DerivedUniformsPipeline;
+  private readonly resources: DerivedUniformsResources;
+  readonly records: RecordsBuffer;
+
+  private cachedBg: GPUBindGroup | undefined;
+  private bgKeyConsts: GPUBuffer | undefined;
+  private bgKeyHeap:   GPUBuffer | undefined;
+  private bgKeyRecs:   GPUBuffer | undefined;
+
+  /** Tiny uniform holding the live record count — gates threads past
+   *  the live range from reading stale swap-removed records. */
+  private readonly countBuf: GPUBuffer;
+  private readonly countCpu = new Uint32Array(1);
+  private lastCountUploaded = -1;
+
+  constructor(
+    device: GPUDevice,
+    pipe:   DerivedUniformsPipeline,
+    resources: DerivedUniformsResources,
+    initialRecordCapacity = 64,
+  ) {
+    this.device    = device;
+    this.pipe      = pipe;
+    this.resources = resources;
+    this.records   = new RecordsBuffer(device, initialRecordCapacity);
+    this.countBuf = device.createBuffer({
+      label: "derivedUniforms.recordCount",
+      size:  16,                             // uniform min size
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+  }
+
+  /** Dispatch into an open compute pass. Caller is responsible for
+   *  beginning/ending the pass and setting the pipeline once across
+   *  all dispatchers (the pipeline is shared). */
+  dispatchInto(pass: GPUComputePassEncoder): boolean {
+    const count = this.records.recordCount;
+    if (count === 0) return false;
+    this.records.flush();
+    if (count !== this.lastCountUploaded) {
+      this.countCpu[0] = count;
+      this.device.queue.writeBuffer(
+        this.countBuf, 0, this.countCpu.buffer, this.countCpu.byteOffset, 4,
+      );
+      this.lastCountUploaded = count;
+    }
+    pass.setBindGroup(0, this.bindGroup());
+    pass.dispatchWorkgroups(Math.ceil(count / 64));
+    return true;
+  }
+
+  /** Convenience: open/close a pass and dispatch. Use only when this
+   *  is the sole dispatcher in the pass; otherwise use `dispatchInto`
+   *  inside a caller-managed pass. */
+  encode(enc: GPUCommandEncoder): boolean {
+    if (this.records.recordCount === 0) return false;
+    const pass = enc.beginComputePass({ label: "derivedUniforms.uber" });
+    pass.setPipeline(this.pipe.pipeline);
+    const ran = this.dispatchInto(pass);
+    pass.end();
+    return ran;
+  }
+
+  dispose(): void {
+    this.records.dispose();
+    this.countBuf.destroy();
+  }
+
+  private bindGroup(): GPUBindGroup {
+    const consts = this.resources.constituentsBuf();
+    const heap   = this.resources.mainHeapBuf();
+    const recs   = this.records.buffer();
+    if (
+      this.cachedBg !== undefined &&
+      this.bgKeyConsts === consts && this.bgKeyHeap === heap &&
+      this.bgKeyRecs === recs
+    ) {
+      return this.cachedBg;
+    }
+    this.cachedBg = this.device.createBindGroup({
+      layout: this.pipe.bgl,
+      entries: [
+        { binding: 0, resource: { buffer: consts } },
+        { binding: 1, resource: { buffer: heap } },
+        { binding: 2, resource: { buffer: recs } },
+        { binding: 3, resource: { buffer: this.countBuf } },
+      ],
+    });
+    this.bgKeyConsts = consts; this.bgKeyHeap = heap;
+    this.bgKeyRecs = recs;
+    return this.cachedBg;
+  }
+}
+
+/** Scene-side helper: O(changed) maintenance of a GPU dirty bitmask.
+ *
+ *  Steady state (clean frame): zero work. The CPU mirror reflects the
+ *  GPU buffer, so we only ever touch bits that actually flip.
+ *
+ *  Each `upload(dirty)` call:
+ *    1. Clears the bits set last frame (O(prev_dirty)).
+ *    2. Sets the bits dirty this frame (O(dirty)).
+ *    3. Writes only the affected u32 range to the GPU (one writeBuffer).
+ *  If both sets are empty, returns immediately. */
+export class DirtyMaskUploader {
+  private readonly device: GPUDevice;
+  private cpu: Uint32Array;
+  private gpu: GPUBuffer | undefined;
+  private gpuCapU32 = 0;
+  /** Bits set on the previous upload — must be cleared next time. */
+  private prevDirty: SlotIndex[] = [];
+
+  constructor(device: GPUDevice, initialU32 = 8) {
+    this.device = device;
+    this.cpu = new Uint32Array(Math.max(1, initialU32));
+  }
+
+  /** Resize CPU + GPU mirrors so they cover `slotCount` bits. */
+  ensureCapacity(slotCount: number): void {
+    const need = Math.max(1, Math.ceil(slotCount / 32));
+    if (need > this.cpu.length) {
+      let cap = Math.max(this.cpu.length, 1);
+      while (cap < need) cap *= 2;
+      const grown = new Uint32Array(cap);
+      grown.set(this.cpu);
+      this.cpu = grown;
+    }
+    if (this.gpu === undefined || this.gpuCapU32 < need) {
+      if (this.gpu !== undefined) this.gpu.destroy();
+      const cap = this.cpu.length;
+      this.gpu = this.device.createBuffer({
+        label: "derivedUniforms.dirtyMask",
+        size:  cap * 4,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+      });
+      this.gpuCapU32 = cap;
+      // GPU buffer is fresh-zero; CPU mirror should match. Wipe any
+      // prevDirty (those bits live in the destroyed buffer).
+      this.prevDirty.length = 0;
+    }
+  }
+
+  /** Apply the new dirty set. O(prev_dirty + dirty), no O(slotCount). */
+  upload(dirty: ReadonlySet<SlotIndex>): void {
+    let minU32 =  Infinity;
+    let maxU32 = -Infinity;
+    for (const s of this.prevDirty) {
+      const i = s >>> 5; const b = s & 31;
+      this.cpu[i] = (this.cpu[i]! & ~(1 << b)) >>> 0;
+      if (i < minU32) minU32 = i;
+      if (i > maxU32) maxU32 = i;
+    }
+    this.prevDirty.length = 0;
+    for (const s of dirty) {
+      const i = s >>> 5; const b = s & 31;
+      this.cpu[i] = (this.cpu[i]! | (1 << b)) >>> 0;
+      if (i < minU32) minU32 = i;
+      if (i > maxU32) maxU32 = i;
+      this.prevDirty.push(s);
+    }
+    if (maxU32 < 0 || maxU32 === -Infinity) return;
+    const startByte = minU32 * 4;
+    const endByte   = (maxU32 + 1) * 4;
+    this.device.queue.writeBuffer(
+      this.gpu!, startByte,
+      this.cpu.buffer, this.cpu.byteOffset + startByte,
+      endByte - startByte,
+    );
+  }
+
+  buffer(): GPUBuffer {
+    if (this.gpu === undefined) this.ensureCapacity(1);
+    return this.gpu!;
+  }
+
+  dispose(): void {
+    if (this.gpu !== undefined) {
+      this.gpu.destroy();
+      this.gpu = undefined;
+    }
+  }
+}
+
+/** Upload the dirty constituent value range to the constituents GPU
+ *  buffer. Helper used by the scene each frame after draining. */
+export function uploadConstituentsRange(
+  device: GPUDevice,
+  buf:    GPUBuffer,
+  mirror: Float32Array,
+  dirty:  ReadonlySet<SlotIndex>,
+): void {
+  let minSlot = Infinity, maxSlot = -1;
+  for (const s of dirty) {
+    if (s < minSlot) minSlot = s;
+    if (s > maxSlot) maxSlot = s;
+  }
+  if (maxSlot < 0) return;
+  const startByte = minSlot * DF32_MAT4_BYTES;
+  const endByte   = (maxSlot + 1) * DF32_MAT4_BYTES;
+  device.queue.writeBuffer(
+    buf, startByte,
+    mirror.buffer, mirror.byteOffset + startByte,
+    endByte - startByte,
+  );
+}

package/src/runtime/derivedUniforms/index.ts

@@ -0,0 +1,52 @@
+// §7 derived-uniforms module — public surface.
+//
+// Caller responsibilities (typically heapScene.ts):
+//
+//   1. Construct one DerivedUniformsScene per heap scene, one
+//      DerivedUniformsBucket per render bucket. The scene owns the
+//      shared constituents storage buffer + dirty bitmask + pipeline.
+//   2. In the parent scene-object's `inputChanged(t, o)` router, call
+//      `scene.routeInputChanged(o)`. Returns true iff o matched.
+//   3. In each RO's add path: `registerRoDerivations(scene, bucket, req)`
+//      allocates constituent slots and pushes records into the bucket's
+//      records buffer. In remove path: `deregisterRoDerivations(...)`.
+//   4. In the per-frame compute prep, inside the parent sceneObj's
+//      `evaluateAlways(token, ...)` scope:
+//        const dirty = scene.constituents.pullDirty(token);
+//        scene.uploadDirty(dirty);
+//        for each bucket: bucket.dispatcher.encode(enc);
+//      All steps are O(changed); on clean frames they no-op.
+//
+// Identifying which uniform names are §7-owned: DERIVED_UNIFORM_NAMES.
+
+export {
+  RecipeId,
+  ALL_RECIPES, DERIVED_UNIFORM_NAMES,
+  recipeIdByName, recipeName, recipeInputs, recipeInputCount, recipeOutput,
+  type ConstituentRef, type RecipeOutput,
+} from "./recipes.js";
+
+export {
+  ConstituentSlots, DF32_MAT4_BYTES,
+  type SlotIndex, type PairedSlots, type DerivationRecord, type SubscribeFn,
+} from "./slots.js";
+
+export {
+  DerivedUniformsDispatcher, DerivedUniformsPipeline,
+  RecordsBuffer, uploadConstituentsRange,
+  type DerivedUniformsResources,
+} from "./dispatch.js";
+
+export {
+  DerivedUniformsScene,
+  registerRoDerivations,
+  deregisterRoDerivations,
+  isDerivedUniformName,
+  type RoTrafoInputs,
+  type RoDerivedRequest,
+  type RoRegistration,
+} from "./sceneIntegration.js";
+
+export {
+  DERIVED_UBER_KERNEL_WGSL,
+} from "./uberKernel.wgsl.js";