@aardworx/wombat.rendering 0.19.11 → 0.19.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aardworx/wombat.rendering",
-  "version": "0.19.11",
+  "version": "0.19.12",
   "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/core/renderObject.ts

@@ -102,4 +102,13 @@ export interface RenderObject {
     readonly depthWrite?:     import("../runtime/derivedModes/rule.js").DerivedModeRule<"depthWrite">;
     readonly alphaToCoverage?: import("../runtime/derivedModes/rule.js").DerivedModeRule<"alphaToCoverage">;
   };
+  /**
+   * GPU transform propagation: this RO's `Model` as an ancestor trafo CHAIN
+   * (root→leaf order, constant runs folded) instead of a single composed
+   * `ModelTrafo` aval. The scene-graph emits this so a shared root trafo over
+   * N objects never fans out to N composed CPU avals — the heap composes each
+   * RO's Model on the GPU. Heap-path only (the legacy path composes on CPU).
+   * See docs/gpu-transform-propagation.md.
+   */
+  readonly modelChain?: readonly aval<import("@aardworx/wombat.base").Trafo3d>[];
 }

package/src/runtime/derivedUniforms/codegen.ts

@@ -23,6 +23,18 @@ export interface UberKernel {
   readonly strideU32: number;
 }
 
+/**
+ * Reserved rule id for the built-in variable-length trafo-chain arm (GPU
+ * transform propagation). A chain record is laid out as
+ *   [ CHAIN_RULE_ID, out_slot, count, link0, link1, … ]
+ * where each `linkK` is a Constituent handle. The arm folds the df32 product
+ * `link0 · link1 · … · link(count-1)` and writes it (collapsed) to `out_slot`.
+ * One arm handles every chain length, so distinct SG ancestor paths don't each
+ * spawn a kernel arm / recompile. Kept far above the registry's monotonic ids
+ * (which start at 0) so it can never collide. See docs/gpu-transform-propagation.md.
+ */
+export const CHAIN_RULE_ID = 0x7fffffff;
+
 // ─── Rule-shape classification ────────────────────────────────────────
 
 type Shape =
@@ -136,6 +148,12 @@ fn load_entry_mat4(h: u32, r: u32, c: u32) -> vec2<f32> {
 fn write_mat4_entry(out_byte: u32, r: u32, c: u32, v: f32) {
   MainHeap[(out_byte >> 2u) + r * 4u + c] = v;
 }
+// Write one df32 mat4 entry (r,c) into a constituent slot — keeps both hi+lo
+// so a downstream §7 pass reads it at full df32 precision. Used by the chain
+// pass, whose output IS a per-RO Model constituent (not a collapsed uniform).
+fn write_constituent_entry(slot: u32, r: u32, c: u32, e: vec2<f32>) {
+  Constituents[slot * 16u + r * 4u + c] = e;
+}
 fn write_mat3_entry(out_byte: u32, r: u32, c: u32, v: f32) {
   // std140 mat3<f32>: 3 rows × 4-float stride; the 4th column per row is left untouched.
   MainHeap[(out_byte >> 2u) + r * 4u + c] = v;
@@ -144,7 +162,7 @@ fn write_mat3_entry(out_byte: u32, r: u32, c: u32, v: f32) {
 
 function bindings(strideU32: number): string {
   return /* wgsl */ `
-@group(0) @binding(0) var<storage, read>       Constituents: array<vec2<f32>>;
+@group(0) @binding(0) var<storage, read_write> Constituents: array<vec2<f32>>;
 @group(0) @binding(1) var<storage, read_write> MainHeap:     array<f32>;
 @group(0) @binding(2) var<storage, read>       RecordData:   array<u32>;
 struct CountUniform { count: u32 }
@@ -214,6 +232,43 @@ function emitMatMulChainArm(id: number, n: number): string {
   return `\nfn arm_${id}(${params}, out_byte: u32) {\n${body}}\n`;
 }
 
+/** Built-in `CHAIN` arm (GPU transform propagation): variable-length df32
+ *  matmul chain read straight from the record. `RecordData[base+2]` = count;
+ *  `RecordData[base+3+k]` = link k (Constituent handle). Folds
+ *  P = L0·L1·…·L(count-1) in df32 and writes it — keeping BOTH hi+lo — into the
+ *  output CONSTITUENT slot (`out_slot` = the out handle's payload), so a later
+ *  §7 pass reads it at full df32 precision. The inverse half is produced by a
+ *  second chain record over the links' inv slots in reverse order (same arm).
+ *  P starts at identity so count==0 yields identity. */
+const CHAIN_ARM = /* wgsl */ `
+fn arm_chain(base: u32, out_slot: u32) {
+  let count = RecordData[base + 2u];
+  var P: array<vec2<f32>, 16>;
+  for (var i: u32 = 0u; i < 16u; i = i + 1u) { P[i] = vec2<f32>(0.0, 0.0); }
+  P[0] = vec2<f32>(1.0, 0.0); P[5] = vec2<f32>(1.0, 0.0);
+  P[10] = vec2<f32>(1.0, 0.0); P[15] = vec2<f32>(1.0, 0.0);
+  for (var k: u32 = 0u; k < count; k = k + 1u) {
+    let h = RecordData[base + 3u + k];
+    var Q: array<vec2<f32>, 16>;
+    for (var r: u32 = 0u; r < 4u; r = r + 1u) {
+      for (var c: u32 = 0u; c < 4u; c = c + 1u) {
+        var acc = vec2<f32>(0.0, 0.0);
+        for (var t: u32 = 0u; t < 4u; t = t + 1u) {
+          acc = df_add(acc, df_mul(P[r * 4u + t], load_entry_mat4(h, t, c)));
+        }
+        Q[r * 4u + c] = acc;
+      }
+    }
+    P = Q;
+  }
+  for (var r: u32 = 0u; r < 4u; r = r + 1u) {
+    for (var c: u32 = 0u; c < 4u; c = c + 1u) {
+      write_constituent_entry(out_slot, r, c, P[r * 4u + c]);
+    }
+  }
+}
+`;
+
 // ─── Generic path: arbitrary IR lowered via the wgsl printer (f32) ────
 //
 // The rule's IR is rewritten so each input leaf — `ReadInput("Uniform", x)` or
@@ -454,13 +509,16 @@ export function buildUberKernel(registry: DerivedUniformRegistry, strideU32: num
 
   const arms = entries.map((e, i) => emitArm(e, shapes[i]!)).join("");
   const cases = entries.map((e, i) => emitCase(e, shapes[i]!)).join("\n");
-  const needsDf32 = shapes.some((s) => s.kind === "matmulChain");
+  // The CHAIN arm is always present (GPU transform propagation) and always
+  // needs the df32 library.
+  const needsDf32 = true;
 
   const wgsl = `${bindings(strideU32)}
 ${needsDf32 ? DF32_LIB : ""}
 ${HANDLE_HELPERS}
 ${loadersStorers}
 ${arms}
+${CHAIN_ARM}
 @compute @workgroup_size(64)
 fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
   if (gid.x >= Count.count) { return; }
@@ -468,6 +526,7 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
   let rule_id = RecordData[base];
   let out_byte = RecordData[base + 1u] & SLOT_PAYLOAD_MASK;
   switch rule_id {
+    case ${CHAIN_RULE_ID >>> 0}u: { arm_chain(base, out_byte); }
 ${cases}
     default: { return; }
   }

package/src/runtime/derivedUniforms/dispatch.ts

@@ -43,7 +43,9 @@ export interface DerivedUniformsResources {
 
 function bglEntries(): GPUBindGroupLayoutEntry[] {
   return [
-    { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+    // Constituents: read_write — the chain pass writes per-RO Model constituents
+    // here (a separate, earlier dispatch); §7 reads them. read_write permits both.
+    { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "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" } },
@@ -119,9 +121,12 @@ class RecordsGpu {
 class UberPipeline {
   private readonly device: GPUDevice;
   readonly bgl: GPUBindGroupLayout;
-  private pipe: GPUComputePipeline | undefined;
+  // Cache one pipeline per record stride (the kernel bakes RECORD_STRIDE). The
+  // chain pass and the §7 pass usually have different strides, and both are
+  // dispatched every frame, so a single-slot cache would thrash → recompile
+  // per frame. Cleared on a registry-version bump (new rule shape).
+  private readonly pipes = new Map<number, GPUComputePipeline>();
   private builtVersion = -1;
-  private builtStride = -1;
 
   constructor(device: GPUDevice) {
     this.device = device;
@@ -129,20 +134,25 @@ class UberPipeline {
   }
 
   pipeline(registry: DerivedUniformRegistry, strideU32: number): GPUComputePipeline | undefined {
-    if (registry.size === 0) return undefined;
-    if (this.pipe !== undefined && this.builtVersion === registry.version && this.builtStride === strideU32) {
-      return this.pipe;
+    // Always buildable: the kernel carries the built-in CHAIN arm even with an
+    // empty registry, so a scene using only transform-propagation chains (no
+    // §7 rules) still gets a pipeline. encodeChunk's recordCount===0 guard is
+    // what skips the dispatch when there's genuinely nothing to do.
+    if (registry.version !== this.builtVersion) {
+      this.pipes.clear();
+      this.builtVersion = registry.version;
     }
+    const cached = this.pipes.get(strideU32);
+    if (cached !== undefined) return cached;
     const { wgsl } = buildUberKernel(registry, strideU32);
     const module = this.device.createShaderModule({ code: wgsl, label: "derivedUniforms.uber" });
-    this.pipe = this.device.createComputePipeline({
+    const pipe = this.device.createComputePipeline({
       label: "derivedUniforms.uber",
       layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.bgl] }),
       compute: { module, entryPoint: "main" },
     });
-    this.builtVersion = registry.version;
-    this.builtStride = strideU32;
-    return this.pipe;
+    this.pipes.set(strideU32, pipe);
+    return pipe;
   }
 }
 

package/src/runtime/derivedUniforms/sceneIntegration.ts

@@ -25,6 +25,7 @@ import {
 } from "./slots.js";
 import { DerivedUniformRegistry } from "./registry.js";
 import { RecordsBuffer, SlotTag, makeHandle } from "./records.js";
+import { CHAIN_RULE_ID } from "./codegen.js";
 import { DerivedUniformsDispatcher, uploadConstituentsRange } from "./dispatch.js";
 import { flatten, type RuleInput } from "./flatten.js";
 import { ruleFromIR, type DerivedRule } from "./rule.js";
@@ -41,6 +42,11 @@ export class DerivedUniformsScene {
    *  scene-wide; records partition by chunk so each dispatch binds
    *  the right chunk's main heap. */
   private readonly recordsByChunk = new Map<number, RecordsBuffer>();
+  /** Scene-wide CHAIN records (GPU transform propagation). Dispatched BEFORE
+   *  the §7 per-chunk passes — they write per-RO Model constituents that §7
+   *  then reads. Scene-wide (not per-chunk) because they target the shared
+   *  constituents buffer, not any chunk's main heap. */
+  readonly chainRecords = new RecordsBuffer();
   readonly dispatcher: DerivedUniformsDispatcher;
   /** Constituents storage GPU buffer (`array<vec2<f32>>` — df32 mat4 halves). */
   constituentsBuf: GPUBuffer;
@@ -57,7 +63,7 @@ export class DerivedUniformsScene {
     this.constituentsBuf = device.createBuffer({
       label: "derivedUniforms.constituents",
       size: initial * DF32_MAT4_BYTES,
-      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
     });
     this.dispatcher = new DerivedUniformsDispatcher(device, {
       constituentsBuf: () => this.constituentsBuf,
@@ -71,6 +77,13 @@ export class DerivedUniformsScene {
     this.mainHeapByChunk.set(chunkIdx, getter);
   }
 
+  /** Any registered main-heap getter (the chain pass needs a MainHeap binding
+   *  even though its arm never touches it). */
+  private firstHeapGetter(): (() => GPUBuffer) | undefined {
+    for (const g of this.mainHeapByChunk.values()) return g;
+    return undefined;
+  }
+
   /** Get-or-create the records buffer for `chunkIdx`. */
   recordsFor(chunkIdx: number): RecordsBuffer {
     let r = this.recordsByChunk.get(chunkIdx);
@@ -97,7 +110,7 @@ export class DerivedUniformsScene {
     this.constituentsBuf = this.device.createBuffer({
       label: "derivedUniforms.constituents",
       size: cap,
-      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
     });
     this.bufferEpoch++;
     // Fresh buffer is zero-initialised; re-upload everything packed so far.
@@ -134,6 +147,17 @@ export class DerivedUniformsScene {
    *  main heap buffer. */
   encode(enc: GPUCommandEncoder): boolean {
     let any = false;
+    // Phase 1: chain pass — writes per-RO Model constituents (fwd+inv) into the
+    // shared constituents buffer. Must run BEFORE the §7 passes that read them.
+    // The MainHeap binding is unused by the chain arm; bind any registered heap.
+    if (this.chainRecords.recordCount > 0) {
+      const anyHeap = this.firstHeapGetter();
+      if (anyHeap === undefined) {
+        throw new Error("derivedUniforms.encode: chain records present but no chunk main-heap registered to bind.");
+      }
+      if (this.dispatcher.encodeChunk(enc, this.registry, this.chainRecords, anyHeap)) any = true;
+    }
+    // Phase 2: §7 per-chunk (reads constituents incl. the chain-written Model).
     for (const [chunkIdx, records] of this.recordsByChunk) {
       if (records.recordCount === 0) continue;
       const heapGetter = this.mainHeapByChunk.get(chunkIdx);
@@ -159,6 +183,18 @@ export class DerivedUniformsScene {
 export interface RoDerivedRequest {
   /** Derived rules to install, keyed by the uniform name each produces. */
   readonly rules: ReadonlyMap<string, DerivedRule>;
+  /**
+   * GPU transform propagation: the SG ancestor trafo chain for THIS RO's
+   * `Model` (root→leaf order, constant runs folded), as `aval<Trafo3d>` links.
+   * Links are constituents shared by aval identity, so a root trafo shared by
+   * N ROs is ONE slot referenced N times (no CPU fan-out). When present, the
+   * chain pass computes a per-RO `Model` constituent (fwd from the links, inv
+   * from the reversed inverse links) and the §7 rules' `Model` leaf resolves to
+   * it — so ModelTrafo / ModelView / ModelViewInv / NormalMatrix / custom rules
+   * all derive from the GPU-composed Model, unchanged. See
+   * docs/gpu-transform-propagation.md.
+   */
+  readonly modelChain?: readonly aval<Trafo3d>[];
   /** Trafo avals available on this RO, keyed by the uniform name a rule leaf may reference (e.g. "ModelTrafo"). */
   readonly trafoAvals: ReadonlyMap<string, aval<Trafo3d>>;
   /** drawHeader byte offset (relative to `drawHeaderBaseByte`) of a host-supplied uniform on this RO; undefined if not present. */
@@ -180,6 +216,9 @@ export interface RoRegistration {
   readonly ruleHashes: readonly string[];
   /** Chunk this registration was placed into — used by deregister. */
   readonly chunkIdx: number;
+  /** Per-RO Model output constituent pair (transform propagation); freed on
+   *  deregister. Present iff the request carried a `modelChain`. */
+  readonly modelPair?: PairedSlots;
 }
 
 export function registerRoDerivations(
@@ -187,7 +226,9 @@ export function registerRoDerivations(
   owner: object,
   req: RoDerivedRequest,
 ): RoRegistration {
-  if (req.rules.size === 0) return { owner, constituentAvals: [], ruleHashes: [], chunkIdx: req.chunkIdx };
+  if (req.rules.size === 0 && req.modelChain === undefined) {
+    return { owner, constituentAvals: [], ruleHashes: [], chunkIdx: req.chunkIdx };
+  }
   const records = scene.recordsFor(req.chunkIdx);
 
   const acquiredAvals: aval<Trafo3d>[] = [];
@@ -207,8 +248,9 @@ export function registerRoDerivations(
   };
   const resolve = (inp: RuleInput): number => {
     // A matrix-typed leaf bound as an aval is a `Trafo3d` ⇒ a df32 constituent slot
-    // (its `Inverse` reads the stored backward half — free).
-    if (inp.type.kind === "Matrix" && req.trafoAvals.has(inp.name)) {
+    // (its `Inverse` reads the stored backward half — free). `Model` may instead
+    // be a GPU-composed chain output already in `pairByName` (modelChain case).
+    if (inp.type.kind === "Matrix" && (req.trafoAvals.has(inp.name) || pairByName.has(inp.name))) {
       const p = acquireTrafo(inp.name);
       return makeHandle(SlotTag.Constituent, inp.inverse ? p.inv : p.fwd);
     }
@@ -225,6 +267,27 @@ export function registerRoDerivations(
     );
   };
 
+  // GPU transform propagation: compute this RO's `Model` as a per-RO constituent
+  // from its ancestor chain, and point §7's `Model` leaf at it. The chain pass
+  // (a separate, earlier dispatch) writes the fwd half from the links and the
+  // inv half from the reversed inverse links.
+  let modelPair: PairedSlots | undefined;
+  if (req.modelChain !== undefined) {
+    modelPair = scene.constituents.allocOutputPair();
+    pairByName.set("Model", modelPair);
+    const linkPairs = req.modelChain.map((av) => {
+      acquiredAvals.push(av);
+      return scene.constituents.acquire(av);
+    });
+    const n = linkPairs.length;
+    // Model.fwd = link0·link1·…·link(n-1)  (forward order, fwd slots).
+    scene.chainRecords.add(owner, CHAIN_RULE_ID, makeHandle(SlotTag.Constituent, modelPair.fwd),
+      [n, ...linkPairs.map((p) => makeHandle(SlotTag.Constituent, p.fwd))]);
+    // Model.inv = link(n-1)⁻¹·…·link0⁻¹  (reversed order, inv slots).
+    scene.chainRecords.add(owner, CHAIN_RULE_ID, makeHandle(SlotTag.Constituent, modelPair.inv),
+      [n, ...linkPairs.slice().reverse().map((p) => makeHandle(SlotTag.Constituent, p.inv))]);
+  }
+
   for (const [outName, rule] of req.rules) {
     // `flatten` returns the same Expr object when nothing was substituted (the common case —
     // the standard recipes reference no derived names), so we can reuse `rule` (it already
@@ -241,12 +304,18 @@ export function registerRoDerivations(
     }
     records.add(owner, id, makeHandle(SlotTag.HostHeap, req.drawHeaderBaseByte + outOff), inSlots);
   }
+
   scene.ensureConstituentsCapacity(scene.constituents.slotCount * DF32_MAT4_BYTES);
-  return { owner, constituentAvals: acquiredAvals, ruleHashes, chunkIdx: req.chunkIdx };
+  return {
+    owner, constituentAvals: acquiredAvals, ruleHashes, chunkIdx: req.chunkIdx,
+    ...(modelPair !== undefined ? { modelPair } : {}),
+  };
 }
 
 export function deregisterRoDerivations(scene: DerivedUniformsScene, reg: RoRegistration): void {
   scene.recordsFor(reg.chunkIdx).removeAllForOwner(reg.owner);
+  scene.chainRecords.removeAllForOwner(reg.owner);
   for (const h of reg.ruleHashes) scene.registry.release(h);
   for (const av of reg.constituentAvals) scene.constituents.release(av);
+  if (reg.modelPair !== undefined) scene.constituents.freeOutputPair(reg.modelPair);
 }

package/src/runtime/derivedUniforms/slots.ts

@@ -87,6 +87,21 @@ export class ConstituentSlots {
     this.mirror = new Float32Array(initialCapacity * 32);
   }
 
+  /** Allocate a fwd+inv slot pair for a GPU-WRITTEN output (not keyed by any
+   *  aval, never dirty-tracked or CPU-uploaded). Used for a per-RO `Model`
+   *  produced by the transform-propagation chain pass and then consumed by §7
+   *  as a constituent. Free with `freeOutputPair`. */
+  allocOutputPair(): PairedSlots {
+    const fwd = this.pool.alloc() as SlotIndex;
+    const inv = this.pool.alloc() as SlotIndex;
+    this.ensureCapacity(this.pool.highWaterMark);
+    return { fwd, inv };
+  }
+  freeOutputPair(p: PairedSlots): void {
+    this.pool.release(p.fwd);
+    this.pool.release(p.inv);
+  }
+
   acquire(av: aval<Trafo3d>): PairedSlots {
     let entry = this.byAval.get(av);
     if (entry === undefined) {

package/src/runtime/heapAdapter.ts

@@ -464,6 +464,7 @@ export function renderObjectToHeapSpec(
     ...geom,
     ...(textures !== undefined ? { textures } : {}),
     ...(ro.modeRules !== undefined ? { modeRules: ro.modeRules } : {}),
+    ...(ro.modelChain !== undefined ? { modelChain: ro.modelChain } : {}),
     // Pass `active` through unforced so the heap path can subscribe
     // and react to flips without re-running the spec adapter.
     ...(ro.active !== undefined ? { active: ro.active } : {}),

package/src/runtime/heapScene.ts

@@ -530,6 +530,16 @@ export interface HeapDrawSpec {
     readonly depthWrite?:     import("./derivedModes/rule.js").DerivedModeRule<"depthWrite">;
     readonly alphaToCoverage?: import("./derivedModes/rule.js").DerivedModeRule<"alphaToCoverage">;
   };
+  /**
+   * GPU transform propagation: this RO's `Model` ancestor trafo chain (root→
+   * leaf, constant runs folded) as `aval<Trafo3d>` links. When present, the §7
+   * compute pass composes a per-RO Model constituent from these on the GPU
+   * (instead of the RO supplying a single composed `ModelTrafo` aval), and the
+   * standard recipes / custom rules derive ModelView / inverses / NormalMatrix
+   * from it. Eliminates the CPU fan-out of a shared root trafo over many ROs.
+   * See docs/gpu-transform-propagation.md.
+   */
+  readonly modelChain?: readonly aval<Trafo3d>[];
 }
 
 export interface HeapSceneStats {
@@ -1193,6 +1203,10 @@ export function buildHeapScene(
     // just means "this RO doesn't supply the base trafos", so the field falls back to its
     // packed `spec.inputs` value (or errors later if there is none — same as without §7).
     for (const inp of inputsOf(rule.ir)) {
+      // `Model` may be supplied by the GPU transform-propagation chain rather
+      // than a ModelTrafo aval — treat it as bound when a modelChain is present
+      // (registerRoDerivations points the §7 Model leaf at the chain output).
+      if (inp.name === "Model" && spec.modelChain !== undefined) continue;
       const specName = STANDARD_TRAFO_LEAVES.get(inp.name) ?? inp.name;
       const lv = spec.inputs[specName];
       if (lv === undefined || isDerivedRule(lv)) {
@@ -3415,6 +3429,7 @@ export function buildHeapScene(
         const reg = registerRoDerivations(derivedScene, {}, {
           rules: ruleSubset,
           trafoAvals,
+          ...(spec.modelChain !== undefined ? { modelChain: spec.modelChain } : {}),
           hostUniformOffset: (n) => {
             const r = perDrawRefs.get(n);
             return r === undefined ? undefined : r + ALLOC_HEADER_PAD_TO;