@aardworx/wombat.rendering 0.5.4 → 0.7.0

package/src/resources/preparedRenderObject.ts

@@ -14,6 +14,8 @@
 
 import {
   AdaptiveResource,
+  BufferView,
+  ElementType,
   type CompiledEffect,
   type FramebufferSignature,
   type ProgramInterface,
@@ -25,7 +27,6 @@ import {
   HashMap,
   cval,
 } from "@aardworx/wombat.adaptive";
-import type { BufferView } from "../core/bufferView.js";
 import type { Type } from "@aardworx/wombat.shader/ir";
 import { prepareAdaptiveBuffer } from "./adaptiveBuffer.js";
 import { prepareAdaptiveTexture } from "./adaptiveTexture.js";
@@ -34,32 +35,6 @@ import { prepareUniformBuffer } from "./uniformBuffer.js";
 import { compileRenderPipeline, type CompileRenderPipelineDescription } from "./renderPipeline.js";
 import { BufferUsage, ShaderStage } from "./webgpuFlags.js";
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function isIndexFormat(fmt: string): boolean {
-  return fmt === "uint16" || fmt === "uint32";
-}
-
-function vertexFormatStride(fmt: GPUVertexFormat): number {
-  switch (fmt) {
-    case "float32": return 4;
-    case "float32x2": return 8;
-    case "float32x3": return 12;
-    case "float32x4": return 16;
-    case "uint32": case "sint32": return 4;
-    case "uint32x2": case "sint32x2": return 8;
-    case "uint32x3": case "sint32x3": return 12;
-    case "uint32x4": case "sint32x4": return 16;
-    case "uint16x2": case "sint16x2": case "float16x2": return 4;
-    case "uint16x4": case "sint16x4": case "float16x4": return 8;
-    case "uint8x2": case "sint8x2": case "unorm8x2": case "snorm8x2": return 2;
-    case "uint8x4": case "sint8x4": case "unorm8x4": case "snorm8x4": return 4;
-    default: throw new Error(`vertexFormatStride: unsupported format ${fmt}`);
-  }
-}
-
 interface VertexBindingInfo {
   readonly name: string;
   readonly slot: number;
@@ -371,10 +346,10 @@ export class PreparedRenderObject {
     private readonly device: GPUDevice,
     private readonly vertexBindings: readonly VertexBindingInfo[],
     private readonly vertexBuffers: ReadonlyMap<string, AdaptiveResource<GPUBuffer>>,
-    private readonly vertexViews: ReadonlyMap<string, aval<import("../core/index.js").BufferView>>,
+    private readonly vertexViews: ReadonlyMap<string, BufferView>,
     private readonly indexBuffer: AdaptiveResource<GPUBuffer> | undefined,
     private readonly indexFormat: GPUIndexFormat | undefined,
-    private readonly indices: aval<import("../core/index.js").BufferView> | undefined,
+    private readonly indices: BufferView | undefined,
     groups: readonly GroupDesc[],
     private readonly drawCall: aval<import("../core/index.js").DrawCall>,
     pipelineCtx: PipelineBuildContext,
@@ -479,15 +454,12 @@ export class PreparedRenderObject {
     for (const vb of this.vertexBindings) {
       const res = this.vertexBuffers.get(vb.name);
       if (res === undefined) throw new Error(`PreparedRenderObject.record: missing vertex buffer for "${vb.name}"`);
-      const viewAval = this.vertexViews.get(vb.name);
-      const view = viewAval !== undefined ? viewAval.getValue(token) : undefined;
+      const view = this.vertexViews.get(vb.name);
       const buf = res.getValue(token);
-      if (view !== undefined && view.offset > 0) {
-        // size omitted → WebGPU uses (buffer.size − offset). The
-        // BufferView's count·stride span doesn't include the offset,
-        // so passing it here would request bytes past the end of the
-        // buffer for any non-zero offset; let WebGPU default.
-        pass.setVertexBuffer(vb.slot, buf, view.offset);
+      const offset = view !== undefined ? BufferView.offsetOf(view) : 0;
+      if (offset > 0) {
+        // size omitted → WebGPU uses (buffer.size − offset).
+        pass.setVertexBuffer(vb.slot, buf, offset);
       } else {
         pass.setVertexBuffer(vb.slot, buf);
       }
@@ -495,8 +467,8 @@ export class PreparedRenderObject {
 
     if (this.indexBuffer !== undefined && this.indices !== undefined && this.indexFormat !== undefined) {
       const buf = this.indexBuffer.getValue(token);
-      const view = this.indices.getValue(token);
-      pass.setIndexBuffer(buf, this.indexFormat, view.offset, view.count * (this.indexFormat === "uint16" ? 2 : 4));
+      // size omitted → WebGPU uses (buffer.size − offset).
+      pass.setIndexBuffer(buf, this.indexFormat, BufferView.offsetOf(this.indices));
     }
 
     const dc = this.drawCall.getValue(token);
@@ -531,7 +503,7 @@ export function prepareRenderObject(
   opts: PrepareRenderObjectOptions = {},
 ): PreparedRenderObject {
   const iface = effect.interface;
-  const vertexBindings = vertexBindingsFor(iface);
+  let vertexBindings = vertexBindingsFor(iface);
 
   // The set of attribute names is fixed structurally; only the
   // per-attribute BufferView avals are reactive. We resolve names →
@@ -539,9 +511,28 @@ export function prepareRenderObject(
   const vertexMap = obj.vertexAttributes;
   const instanceMap = obj.instanceAttributes ?? emptyAttrMap();
 
-  const vertexBuffers = new Map<string, AdaptiveResource<GPUBuffer>>();
-  const vertexViews = new Map<string, aval<import("../core/index.js").BufferView>>();
-  const vertexLayouts: GPUVertexBufferLayout[] = [];
+  // Per-attribute resolution + grouping. Multiple attributes can
+  // share one underlying GPUBuffer slot when they all point at the
+  // same `aval<IBuffer>` (by reference identity) with the same
+  // stride + stepMode (the auto-instancing rewrite emits 4 vec4
+  // column attributes per M44 instance trafo — without packing
+  // we'd hit `maxVertexBuffers` (8) for any moderately rich
+  // instancing scope). Each attribute's `view.offset` becomes its
+  // shader-location offset within the shared layout.
+  //
+  // BufferView is now structural-eager (elementType/offset/stride),
+  // so no `force()` is needed to discover layout — the attribute
+  // grouping reads the plain fields directly.
+  interface ResolvedBinding {
+    readonly name: string;
+    readonly shaderLocation: number;
+    readonly stepMode: GPUVertexStepMode;
+    readonly stride: number;
+    readonly offset: number;
+    readonly format: GPUVertexFormat;
+    readonly view: BufferView;
+  }
+  const resolved: ResolvedBinding[] = [];
   for (const vb of vertexBindings) {
     const fromVertex = vertexMap.tryFind(vb.name);
     const fromInstance = instanceMap.tryFind(vb.name);
@@ -551,61 +542,106 @@ export function prepareRenderObject(
     const isInstance = fromVertex === undefined && fromInstance !== undefined;
     const stepMode: GPUVertexStepMode = isInstance ? "instance" : "vertex";
 
-    const viewAval = (fromVertex ?? fromInstance)!;
-    // BufferView's stride drives `arrayStride` so callers can pack
-    // multiple attributes into one interleaved buffer (each attribute
-    // names the same IBuffer with a different `offset`, all sharing
-    // a `stride` ≥ sum of attribute sizes). The renderer honors
-    // `view.offset` at draw time via `setVertexBuffer(slot, buf,
-    // offset)`, so each attribute reads its own slice. Sampled at
-    // build time — switching stride / offset dynamically would need
-    // a fresh pipeline.
-    const initialView = viewAval.force();
-    const explicitZeroStride = initialView.stride === 0;
-    // The buffer's own `format` (e.g. "float32x3" for a packed-Vec3
-    // position stream) is the source of truth — use it whenever
-    // present so the layout matches what's actually in memory.
-    // WebGPU auto-pads missing components when the shader declares a
-    // wider vector (vec4 input fed by Float32x3 → w=1).
-    const viewFormat = initialView.format as GPUVertexFormat | undefined;
-    const format = (viewFormat !== undefined && !isIndexFormat(viewFormat))
-      ? viewFormat
-      : vb.format;
-    const stride = explicitZeroStride
-      ? 0
-      : (initialView.stride > 0
-        ? initialView.stride
-        : vertexFormatStride(format));
-
-    const bufAval = viewAval.map(view => view.buffer);
-    const res = prepareAdaptiveBuffer(device, bufAval, {
-      usage: BufferUsage.VERTEX,
-      ...(opts.label !== undefined ? { label: `${opts.label}.${vb.name}` } : {}),
+    const view = (fromVertex ?? fromInstance)!;
+    const format = ElementType.toVertexFormat(view.elementType, view.normalized ?? false);
+    const stride = BufferView.strideOf(view);
+    const offset = BufferView.offsetOf(view);
+    resolved.push({
+      name: vb.name,
+      shaderLocation: vb.slot,
+      stepMode, stride, offset,
+      format, view,
     });
-    vertexBuffers.set(vb.name, res);
-    vertexViews.set(vb.name, viewAval);
-    vertexLayouts[vb.slot] = {
-      arrayStride: stride,
-      stepMode,
-      attributes: [{ shaderLocation: vb.slot, offset: 0, format }],
+  }
+
+  // Group resolved bindings by (IBuffer-aval identity, stride, stepMode).
+  // The aval reference is the natural identity now that BufferView
+  // owns its `aval<IBuffer>` directly.
+  type GroupKey = string;
+  interface BindingGroup {
+    readonly key: GroupKey;
+    readonly slot: number;             // GPU vertex-buffer slot index
+    readonly stride: number;
+    readonly stepMode: GPUVertexStepMode;
+    readonly view: BufferView;
+    readonly bufferRes: AdaptiveResource<GPUBuffer>;
+    readonly members: ResolvedBinding[];
+  }
+  const bufferIds = new WeakMap<object, number>();
+  let nextBufId = 0;
+  const idOf = (b: object): number => {
+    let n = bufferIds.get(b);
+    if (n === undefined) { n = nextBufId++; bufferIds.set(b, n); }
+    return n;
+  };
+  const vbGroups = new Map<GroupKey, BindingGroup>();
+  let nextSlot = 0;
+  const vertexBuffers = new Map<string, AdaptiveResource<GPUBuffer>>();
+  const vertexViews = new Map<string, BufferView>();
+  for (const r of resolved) {
+    const bufId = idOf(r.view.buffer as unknown as object);
+    const key = `${bufId}|${r.stride}|${r.stepMode}`;
+    let group = vbGroups.get(key);
+    if (!group) {
+      const bufferRes = prepareAdaptiveBuffer(device, r.view.buffer, {
+        usage: BufferUsage.VERTEX,
+        ...(opts.label !== undefined ? { label: `${opts.label}.${r.name}` } : {}),
+      });
+      group = {
+        key, slot: nextSlot++, stride: r.stride, stepMode: r.stepMode,
+        view: r.view, bufferRes, members: [],
+      };
+      vbGroups.set(key, group);
+    }
+    group.members.push(r);
+    vertexBuffers.set(r.name, group.bufferRes);
+    vertexViews.set(r.name, r.view);
+  }
+  const vertexLayouts: GPUVertexBufferLayout[] = [];
+  for (const g of vbGroups.values()) {
+    vertexLayouts[g.slot] = {
+      arrayStride: g.stride,
+      stepMode: g.stepMode,
+      attributes: g.members.map((m) => ({
+        shaderLocation: m.shaderLocation,
+        offset: m.offset,
+        format: m.format,
+      })),
     };
   }
+  // The IR-side `vertexBindings.slot` was the per-attribute shader
+  // location. The runtime needs the GPU buffer-slot index. Build a
+  // parallel array keyed by binding name so the per-frame
+  // `setVertexBuffer` loop calls the right slot once per group.
+  const groupSlotByBindingName = new Map<string, number>();
+  for (const g of vbGroups.values()) {
+    for (const m of g.members) groupSlotByBindingName.set(m.name, g.slot);
+  }
+  // Build the unique-per-slot binding list the prepared object uses
+  // at draw time. Pick the first member of each group to represent
+  // the buffer; per-attribute view offsets live in the layout.
+  const drawTimeBindings: VertexBindingInfo[] = [];
+  for (const g of vbGroups.values()) {
+    const head = g.members[0]!;
+    drawTimeBindings.push({
+      name: head.name,
+      slot: g.slot,
+      format: head.format,
+      byteSize: 0,
+    });
+  }
+  vertexBindings = drawTimeBindings;
 
-  // Index buffer — `indexFormat` from BufferView wins; defaults to uint32.
+  // Index buffer — `elementType` (u16 / u32) determines `GPUIndexFormat`.
+  // Structural fields are eager on BufferView, so no force needed.
   let indexBuffer: AdaptiveResource<GPUBuffer> | undefined;
   let indexFormat: GPUIndexFormat | undefined;
   if (obj.indices !== undefined) {
-    const bufAval = obj.indices.map(v => v.buffer);
-    indexBuffer = prepareAdaptiveBuffer(device, bufAval, {
+    indexBuffer = prepareAdaptiveBuffer(device, obj.indices.buffer, {
       usage: BufferUsage.INDEX,
       ...(opts.label !== undefined ? { label: `${opts.label}.indices` } : {}),
     });
-    // Construction-time read to discover the index format. The
-    // BufferView aval is expected to settle on a stable format —
-    // changing index format would require a fresh PreparedRO.
-    const initial = obj.indices.force();
-    indexFormat = initial.indexFormat
-      ?? (initial.format === "uint16" ? "uint16" : "uint32");
+    indexFormat = ElementType.toIndexFormat(obj.indices.elementType);
   }
 
   const slotOf = (e: { group: number; slot: number }) => e.slot;
@@ -695,8 +731,8 @@ export function prepareRenderObject(
   );
 }
 
-function emptyAttrMap(): HashMap<string, aval<BufferView>> {
-  return HashMap.empty<string, aval<BufferView>>();
+function emptyAttrMap(): HashMap<string, BufferView> {
+  return HashMap.empty<string, BufferView>();
 }
 
 /**

package/src/window/loop.ts

@@ -1,20 +1,44 @@
-// runFrame — requestAnimationFrame-driven loop integrated with
-// wombat.adaptive transactions. Each tick:
-//   1. Bumps the canvas attachment's frame counter so its
-//      framebuffer aval invalidates and the next read returns the
-//      current swap-chain texture.
-//   2. Calls the user's `frame(token)` callback. The user runs
-//      their `IRenderTask` here.
+// runFrame — adaptivity-driven render loop. Mirrors Aardvark.Rendering's
+// approach: an AVal wraps the user's frame callback, the frame's
+// dependency set comes from whatever the callback reads via the
+// adaptive `token`, and a marking callback on the wrapper schedules
+// the next `requestAnimationFrame`. Idle scenes (no avals fired
+// since last render) consume zero CPU per rAF.
 //
-// Returns a `stop()` to cancel the loop.
+// The standard time-ticking pattern (which the wombat.dom
+// `<RenderControl>` follows) is:
+//   1. The user's frame callback calls `task.run(token)` which
+//      reads its inputs (uniforms, alists, …) via the token.
+//      Those reads register as inputs to the wrapping AVal.
+//   2. After `task.run`, the callback ticks a global `time` cval
+//      inside a `transact(...)`.
+//   3. If anything in the scene (e.g. an `OrbitController`'s
+//      damping aval, a custom animation aval) reads `time`, the
+//      mark cascades into the wrapper → marking callback fires →
+//      next rAF scheduled. If *nothing* depends on time, the mark
+//      dies in midair and the loop sleeps.
+//   4. Canvas resize / explicit cval edits / scene-graph deltas
+//      mark their respective avals → cascade → wake-up.
+//
+// Returns a `stop()` to cancel the loop and clear the subscription.
 
-import type { AdaptiveToken } from "@aardworx/wombat.adaptive";
-import { AdaptiveToken as Tok } from "@aardworx/wombat.adaptive";
+import type { aval, AdaptiveToken, IDisposable } from "@aardworx/wombat.adaptive";
+import { AVal, transact } from "@aardworx/wombat.adaptive";
 import type { CanvasAttachment } from "./canvas.js";
 
 export interface RunFrameOptions {
   /** Stop after N frames. Useful for tests + finite animations. */
   readonly maxFrames?: number;
+  /**
+   * Hook called after each frame's eval completes — typically used
+   * to tick a `time` cval (so any aval that depends on time gets
+   * marked AFTER the frame, waking the next rAF). Fired in a fresh
+   * transaction. Returning without ticking (`onAfterFrame: () => {}`,
+   * or omitting) means the loop won't advance unless something else
+   * marks an aval that the frame reads. That's the correct idle
+   * behavior.
+   */
+  readonly onAfterFrame?: () => void;
 }
 
 export type FrameCallback = (token: AdaptiveToken, info: FrameInfo) => void;
@@ -34,29 +58,68 @@ export function runFrame(
   let frameNo = 0;
   let lastTime = performance.now();
   let rafId = 0;
+  let pending = false;
 
-  const tick = (now: number) => {
-    if (stopped) return;
+  // Wrap the frame callback in an AVal so the adaptive system tracks
+  // its dependency set. Each `force()` re-reads the inputs and runs
+  // the frame; subsequent input marks fire the marking callback.
+  const renderAval: aval<number> = AVal.custom((token) => {
+    const now = performance.now();
     const delta = now - lastTime;
     lastTime = now;
     attachment.markFrame();
     try {
-      frame(Tok.top, { frame: frameNo, timestampMs: now, deltaMs: delta });
+      frame(token, { frame: frameNo, timestampMs: now, deltaMs: delta });
     } catch (e) {
       stopped = true;
       console.error("runFrame: error in frame callback", e);
       throw e;
     }
     frameNo++;
-    if (opts.maxFrames !== undefined && frameNo >= opts.maxFrames) return;
-    rafId = requestAnimationFrame(tick);
+    return frameNo;
+  });
+
+  const tick = (): void => {
+    if (stopped) return;
+    pending = false;
+    // The single force-on-render-path. Pulls `renderAval`, which
+    // re-evaluates the user's frame callback (making it up-to-date
+    // for the next mark). Adaptivity-driven equivalent of "run one
+    // frame on this rAF."
+    renderAval.force(/* allow-force */);
+    // Post-frame hook in a fresh transaction. Marks fired here
+    // propagate AFTER the eval, so they actually reach
+    // `renderAval`'s marking callback and wake the next rAF.
+    // Inside the eval the same mark would race the
+    // `outOfDate=false` reset and animation would stall after one
+    // frame.
+    if (opts.onAfterFrame !== undefined) {
+      transact(opts.onAfterFrame);
+    }
+    if (opts.maxFrames !== undefined && frameNo >= opts.maxFrames) {
+      stopped = true;
+      sub.dispose();
+    }
   };
 
+  const sub: IDisposable = (renderAval as unknown as {
+    addMarkingCallback(cb: () => void): IDisposable;
+  }).addMarkingCallback(() => {
+    if (pending || stopped) return;
+    pending = true;
+    rafId = requestAnimationFrame(tick);
+  });
+
+  // Initial render. Schedules subsequent frames only when adaptive
+  // marks reach `renderAval` (via the marking callback above).
+  pending = true;
   rafId = requestAnimationFrame(tick);
+
   return {
     stop() {
       stopped = true;
       cancelAnimationFrame(rafId);
+      sub.dispose();
     },
   };
 }