@aardworx/wombat.rendering 0.1.0

package/src/runtime/renderTo.ts

@@ -0,0 +1,154 @@
+// renderTo — Aardvark `RenderTask.renderTo` ported.
+//
+// Usage:
+//   const result = renderTo(ctx, scene, { size, signature, clear });
+//   const colorAval: aval<ITexture> = result.color("color");
+//   // bind colorAval as a texture on a downstream RenderObject
+//
+// `result.framebuffer` is an `AdaptiveResource<IFramebuffer>` that:
+//   - Allocates the FBO on first acquire.
+//   - On `compute(token)`: reads `size`, encodes a clear pass +
+//     scene render into the active `RenderContext.encoder`, returns
+//     the FBO. Encoding only runs when an outer encoder is active;
+//     when read outside a frame the FBO is returned untouched.
+//   - On last release: disposes the inner cache and frees the FBO.
+//
+// Each `result.color(name)` is a derived `aval<ITexture>` whose
+// lifetime forwards to `framebuffer`, so consuming any attachment
+// keeps the whole pipeline alive.
+
+import {
+  AdaptiveResource,
+  ITexture,
+  RenderContext,
+  type ClearValues,
+  type FramebufferSignature,
+  type IFramebuffer,
+  type RenderTree,
+} from "../core/index.js";
+import {
+  allocateFramebuffer,
+  type FramebufferSize,
+} from "../resources/index.js";
+import { beginPassDescriptor } from "../commands/index.js";
+import { HashMap, type AdaptiveToken, type aval } from "@aardworx/wombat.adaptive";
+import { ScenePass } from "./scenePass.js";
+import type { RuntimeContext } from "./renderTask.js";
+
+export interface RenderToOptions {
+  readonly size: aval<FramebufferSize>;
+  readonly signature: FramebufferSignature;
+  /** What to clear the FBO with each frame. Omit to skip the clear pass. */
+  readonly clear?: ClearValues;
+  readonly label?: string;
+  /**
+   * Extra GPU texture usage flags for every color attachment.
+   * `RENDER_ATTACHMENT | TEXTURE_BINDING` are always set; pass
+   * `COPY_SRC` here to enable readback, `STORAGE_BINDING` for
+   * compute writes, etc.
+   */
+  readonly extraUsage?: GPUTextureUsageFlags;
+}
+
+export interface RenderToResult {
+  /** The full framebuffer resource. Acquire/release for explicit lifetime control. */
+  readonly framebuffer: AdaptiveResource<IFramebuffer>;
+  /**
+   * Returns an `aval<ITexture>` for the named color attachment.
+   * The aval is itself an AdaptiveResource — acquiring it
+   * activates the render-to pipeline.
+   */
+  color(name: string): AdaptiveResource<ITexture>;
+  /**
+   * Convenience for multi-target render passes: returns a
+   * `HashMap<string, aval<ITexture>>` covering every color
+   * attachment in the signature. Each entry shares the underlying
+   * lifetime — acquiring any (or the whole map's entries) activates
+   * the render-to pipeline.
+   */
+  colors(): HashMap<string, AdaptiveResource<ITexture>>;
+  /** Returns the depth-stencil attachment as an `ITexture` (if the signature has one). */
+  depthStencil(): AdaptiveResource<ITexture>;
+}
+
+class RenderToFramebuffer extends AdaptiveResource<IFramebuffer> {
+  private scenePass: ScenePass | undefined;
+
+  constructor(
+    private readonly ctx: RuntimeContext,
+    private readonly fbo: AdaptiveResource<IFramebuffer>,
+    private readonly scene: RenderTree,
+    private readonly clearValues: ClearValues | undefined,
+    private readonly signature: FramebufferSignature,
+  ) { super(); }
+
+  protected override create(): void {
+    this.fbo.acquire();
+    this.scenePass = new ScenePass(
+      this.ctx.device, this.signature, this.scene, this.ctx.compileEffect,
+    );
+  }
+
+  protected override destroy(): void {
+    this.scenePass?.dispose();
+    this.scenePass = undefined;
+    this.fbo.release();
+  }
+
+  override compute(token: AdaptiveToken): IFramebuffer {
+    const fb = this.fbo.getValue(token);
+    const enc = RenderContext.encoder;
+    if (enc !== null && this.scenePass !== undefined) {
+      const leaves = this.scenePass.resolve(token);
+      if (leaves.length > 0 || this.clearValues !== undefined) {
+        const pass = enc.beginRenderPass(beginPassDescriptor(fb, this.clearValues));
+        for (const leaf of leaves) leaf.record(pass, token);
+        pass.end();
+      }
+    }
+    return fb;
+  }
+}
+
+export function renderTo(
+  ctx: RuntimeContext,
+  scene: RenderTree,
+  opts: RenderToOptions,
+): RenderToResult {
+  const fbo = allocateFramebuffer(ctx.device, opts.signature, opts.size, {
+    ...(opts.label !== undefined ? { labelPrefix: opts.label } : {}),
+    ...(opts.extraUsage !== undefined ? { extraUsage: opts.extraUsage } : {}),
+  });
+  const renderToFbo = new RenderToFramebuffer(
+    ctx, fbo, scene,
+    opts.clear,
+    opts.signature,
+  );
+  return {
+    framebuffer: renderToFbo,
+    color(name) {
+      return renderToFbo.derive<ITexture>(fb => {
+        const tex = fb.colorTextures?.tryFind(name);
+        if (tex === undefined) {
+          throw new Error(`renderTo.color: framebuffer has no color attachment "${name}"`);
+        }
+        return ITexture.fromGPU(tex);
+      });
+    },
+    colors() {
+      let out = HashMap.empty<string, AdaptiveResource<ITexture>>();
+      for (const [name] of opts.signature.colors) {
+        out = out.add(name, this.color(name));
+      }
+      return out;
+    },
+    depthStencil() {
+      return renderToFbo.derive<ITexture>(fb => {
+        if (fb.depthStencilTexture === undefined) {
+          throw new Error("renderTo.depthStencil: framebuffer has no depth-stencil attachment");
+        }
+        return ITexture.fromGPU(fb.depthStencilTexture);
+      });
+    },
+  };
+}

package/src/runtime/runtime.ts

@@ -0,0 +1,113 @@
+// Runtime — the user-facing entry point. Holds the device +
+// effect-compilation hook, exposes `compile(commands)` and
+// (eventually) `renderTo(...)`.
+
+import type { Command, CompiledEffect, Effect, IRenderTask, RenderTree } from "../core/index.js";
+import type { alist } from "@aardworx/wombat.adaptive";
+import { compileRenderTask, type RuntimeContext } from "./renderTask.js";
+import { renderTo, type RenderToOptions, type RenderToResult } from "./renderTo.js";
+
+export interface RuntimeOptions {
+  readonly device: GPUDevice;
+  /**
+   * Optional override for `Effect → CompiledEffect`. Defaults to
+   * `effect.compile({ target: "wgsl" })`. Override when tests want
+   * a hand-built CompiledEffect or when the caller needs custom
+   * `CompileOptions` (`skipMatrixReversal`, source-file labelling,
+   * …).
+   */
+  readonly compileEffect?: (effect: Effect) => CompiledEffect;
+}
+
+export class Runtime {
+  private readonly ctx: RuntimeContext;
+  private readonly _tasks = new Set<IRenderTask>();
+  private _disposed = false;
+  private _deviceLost = false;
+  /**
+   * Resolves to the lost-info when the device is reported lost.
+   * Stays pending while the device is alive.
+   */
+  readonly deviceLost: Promise<GPUDeviceLostInfo>;
+
+  constructor(opts: RuntimeOptions) {
+    this.ctx = {
+      device: opts.device,
+      compileEffect: opts.compileEffect ?? ((e: Effect) => e.compile({ target: "wgsl" })),
+    };
+    // `device.lost` is a real-WebGPU promise; mock devices may not
+    // expose it. Treat as "never lost" in that case.
+    const lost = (opts.device as { lost?: Promise<GPUDeviceLostInfo> }).lost;
+    this.deviceLost = lost !== undefined
+      ? lost.then((info) => {
+          this._deviceLost = true;
+          // Best-effort: dispose all outstanding tasks so user code
+          // that still holds them stops trying to encode against a
+          // dead device.
+          this.disposeAll();
+          return info;
+        })
+      : new Promise(() => { /* never resolves on mock */ });
+  }
+
+  get device(): GPUDevice { return this.ctx.device; }
+  get isDeviceLost(): boolean { return this._deviceLost; }
+
+  // Recovery story (after `device.lost`):
+  //
+  // 1. The `lost`-handler above fires `disposeAll()`, releasing all
+  //    `IRenderTask`s and the `PreparedRenderObject`s they hold.
+  //    User-level avals (`cval`, `clist`, `cset`) survive — they're
+  //    device-agnostic.
+  // 2. Caller re-requests an adapter + device, constructs a new
+  //    `Runtime` from it, and re-`compile()`s their original
+  //    `alist<Command>`. The new Runtime builds fresh
+  //    PreparedRenderObjects + a fresh ScenePass tree from the same
+  //    user data; the per-device caches inside compile-pipeline /
+  //    sampler / mip-gen are keyed on `WeakMap<GPUDevice, ...>` so
+  //    they re-populate naturally for the new device.
+  //
+  // We don't expose a single-call `replaceDevice()` because every
+  // prepared object's GPU handles are baked in at construction; the
+  // cleanest path is to discard the old Runtime and construct a new
+  // one from the same source `alist<Command>`.
+
+  /** Compile an `alist<Command>` into a runnable `IRenderTask`. */
+  compile(commands: alist<Command>): IRenderTask {
+    if (this._disposed) throw new Error("Runtime: compile after disposeAll");
+    const task = compileRenderTask(this.ctx, commands);
+    this._tasks.add(task);
+    const origDispose = task.dispose.bind(task);
+    task.dispose = () => { origDispose(); this._tasks.delete(task); };
+    return task;
+  }
+
+  /**
+   * Render `scene` into a freshly-allocated framebuffer, returning
+   * lazy `aval<ITexture>` handles for each color/depth attachment.
+   * The framebuffer + inner render task come live when any
+   * returned aval is acquired (transitively, e.g. by binding it
+   * to a downstream RenderObject), and shut down on last release.
+   */
+  renderTo(scene: RenderTree, opts: RenderToOptions): RenderToResult {
+    if (this._disposed) throw new Error("Runtime: renderTo after disposeAll");
+    return renderTo(this.ctx, scene, opts);
+  }
+
+  /**
+   * Tear down every IRenderTask compiled through this Runtime.
+   * After calling this, `compile()` and `renderTo()` throw.
+   * Idempotent. Intended for page-unload + fatal error paths.
+   *
+   * Note: doesn't destroy the GPUDevice itself — the user still
+   * owns its lifecycle.
+   */
+  disposeAll(): void {
+    if (this._disposed) return;
+    this._disposed = true;
+    for (const t of [...this._tasks]) {
+      try { t.dispose(); } catch (e) { console.error("Runtime.disposeAll: task.dispose threw", e); }
+    }
+    this._tasks.clear();
+  }
+}

package/src/runtime/scenePass.ts

@@ -0,0 +1,273 @@
+// ScenePass — delta-driven walker for one `Render` command's
+// `RenderTree`. Built once at task-compile time; subscribes to the
+// dynamic subtrees (`Adaptive` / `OrderedFromList` /
+// `UnorderedFromSet`); incrementally maintains its set of
+// PreparedRenderObjects.
+//
+// Per-frame cost = O(deltas) + O(leaves) for emission. The static
+// recursion through Empty / Leaf / Ordered / Unordered nodes that
+// the previous walker did each frame is gone — those are folded
+// into a stable NodeWalker tree at construction.
+//
+// Lifted from Aardvark.Rendering's CommandTask delta handling.
+// We keep the *adaptive bookkeeping* pattern (per-RO AdaptiveObject,
+// reader-driven splice) and drop the native command-stream linked-
+// list — that was a .NET↔native amortisation in the F# build with
+// no analogue in WebGPU/JS.
+
+import {
+  type AdaptiveToken,
+  type IIndexListReader,
+  type IHashSetReader,
+  MapExt,
+  type Index,
+  type aval,
+  type alist,
+  type aset,
+} from "@aardworx/wombat.adaptive";
+import {
+  type CompiledEffect,
+  type Effect,
+  type FramebufferSignature,
+  type RenderObject,
+  type RenderTree,
+} from "../core/index.js";
+import {
+  prepareRenderObject,
+  type PreparedRenderObject,
+} from "../resources/index.js";
+
+interface BuildContext {
+  readonly device: GPUDevice;
+  readonly compileEffect: (e: Effect) => CompiledEffect;
+  readonly signature: FramebufferSignature;
+  readonly stats: WalkerStats;
+}
+
+/**
+ * Counters surfaced for tests. `prepareCount` only goes up when
+ * `prepareRenderObject` is called for a fresh RenderObject; it
+ * does not increment per frame on an unchanged scene.
+ */
+export interface WalkerStats {
+  prepareCount: number;
+}
+
+abstract class NodeWalker {
+  /** Pull deltas from any subscribed readers and propagate to children. */
+  abstract update(token: AdaptiveToken): void;
+  /** Push this subtree's current leaves into `out`, in render order. */
+  abstract emit(out: PreparedRenderObject[]): void;
+  /** Release every PreparedRenderObject this walker owns. */
+  abstract dispose(): void;
+}
+
+class EmptyWalker extends NodeWalker {
+  update(): void {}
+  emit(): void {}
+  dispose(): void {}
+}
+
+class LeafWalker extends NodeWalker {
+  private readonly prepared: PreparedRenderObject;
+  constructor(ctx: BuildContext, obj: RenderObject) {
+    super();
+    const eff = ctx.compileEffect(obj.effect);
+    this.prepared = prepareRenderObject(ctx.device, obj, eff, ctx.signature, {
+      effectId: obj.effect.id,
+    });
+    this.prepared.acquire();
+    ctx.stats.prepareCount++;
+  }
+  update(): void {}
+  emit(out: PreparedRenderObject[]): void { out.push(this.prepared); }
+  dispose(): void { this.prepared.release(); }
+}
+
+class OrderedWalker extends NodeWalker {
+  constructor(private readonly children: readonly NodeWalker[]) { super(); }
+  update(token: AdaptiveToken): void { for (const c of this.children) c.update(token); }
+  emit(out: PreparedRenderObject[]): void { for (const c of this.children) c.emit(out); }
+  dispose(): void { for (const c of this.children) c.dispose(); }
+}
+
+// Same identity-rank counter used by the previous walker. Sorting
+// Unordered subtrees by pipeline-then-group0-layout to minimise
+// state changes inside the render pass.
+const sortRanks = new WeakMap<object, number>();
+let nextSortRank = 1;
+function rankOf(o: object): number {
+  let r = sortRanks.get(o);
+  if (r === undefined) { r = nextSortRank++; sortRanks.set(o, r); }
+  return r;
+}
+function compareLeaves(a: PreparedRenderObject, b: PreparedRenderObject): number {
+  const pa = rankOf(a.pipeline);
+  const pb = rankOf(b.pipeline);
+  if (pa !== pb) return pa - pb;
+  const la = a.groups[0]?.layout;
+  const lb = b.groups[0]?.layout;
+  if (la !== undefined && lb !== undefined && la !== lb) return rankOf(la) - rankOf(lb);
+  return 0;
+}
+
+class UnorderedWalker extends NodeWalker {
+  constructor(private readonly children: readonly NodeWalker[]) { super(); }
+  update(token: AdaptiveToken): void { for (const c of this.children) c.update(token); }
+  emit(out: PreparedRenderObject[]): void {
+    const start = out.length;
+    for (const c of this.children) c.emit(out);
+    // Sort just our slice in-place.
+    const slice = out.splice(start);
+    slice.sort(compareLeaves);
+    for (const p of slice) out.push(p);
+  }
+  dispose(): void { for (const c of this.children) c.dispose(); }
+}
+
+class AdaptiveWalker extends NodeWalker {
+  private current: NodeWalker | undefined;
+  private currentTree: RenderTree | undefined;
+  constructor(private readonly source: aval<RenderTree>, private readonly ctx: BuildContext) {
+    super();
+  }
+  update(token: AdaptiveToken): void {
+    const t = this.source.getValue(token);
+    if (t !== this.currentTree) {
+      this.current?.dispose();
+      this.current = build(t, this.ctx);
+      this.currentTree = t;
+    }
+    this.current!.update(token);
+  }
+  emit(out: PreparedRenderObject[]): void { this.current?.emit(out); }
+  dispose(): void { this.current?.dispose(); this.current = undefined; }
+}
+
+class OrderedFromListWalker extends NodeWalker {
+  private readonly reader: IIndexListReader<RenderTree>;
+  // Sorted-by-Index map. Reassigned (immutable persistent) on every delta.
+  private map: MapExt<Index, NodeWalker> = MapExt.empty(indexCompare);
+  constructor(source: alist<RenderTree>, private readonly ctx: BuildContext) {
+    super();
+    this.reader = source.getReader();
+  }
+  update(token: AdaptiveToken): void {
+    const deltas = this.reader.getChanges(token);
+    for (const [idx, op] of deltas) {
+      if (op.tag === "Set") {
+        const old = this.map.tryFind(idx);
+        if (old !== undefined) old.dispose();
+        const w = build(op.value, this.ctx);
+        // Update the new child immediately so its initial state
+        // is consistent before the next emit.
+        w.update(token);
+        this.map = this.map.add(idx, w);
+      } else {
+        const old = this.map.tryFind(idx);
+        if (old !== undefined) {
+          old.dispose();
+          this.map = this.map.remove(idx);
+        }
+      }
+    }
+    // Existing children may have dirty sub-readers — update them too.
+    for (const [, w] of this.map) w.update(token);
+  }
+  emit(out: PreparedRenderObject[]): void {
+    for (const [, w] of this.map) w.emit(out);
+  }
+  dispose(): void {
+    for (const [, w] of this.map) w.dispose();
+    this.map = MapExt.empty(indexCompare);
+  }
+}
+
+class UnorderedFromSetWalker extends NodeWalker {
+  private readonly reader: IHashSetReader<RenderTree>;
+  private readonly map = new Map<RenderTree, NodeWalker>();
+  constructor(source: aset<RenderTree>, private readonly ctx: BuildContext) {
+    super();
+    this.reader = source.getReader();
+  }
+  update(token: AdaptiveToken): void {
+    const deltas = this.reader.getChanges(token);
+    for (const op of deltas) {
+      if (op.count > 0) {
+        if (!this.map.has(op.value)) {
+          const w = build(op.value, this.ctx);
+          w.update(token);
+          this.map.set(op.value, w);
+        }
+      } else if (op.count < 0) {
+        const old = this.map.get(op.value);
+        if (old !== undefined) {
+          old.dispose();
+          this.map.delete(op.value);
+        }
+      }
+    }
+    for (const w of this.map.values()) w.update(token);
+  }
+  emit(out: PreparedRenderObject[]): void {
+    const start = out.length;
+    for (const w of this.map.values()) w.emit(out);
+    const slice = out.splice(start);
+    slice.sort(compareLeaves);
+    for (const p of slice) out.push(p);
+  }
+  dispose(): void {
+    for (const w of this.map.values()) w.dispose();
+    this.map.clear();
+  }
+}
+
+function indexCompare(a: Index, b: Index): number { return a.compareTo(b); }
+
+function build(tree: RenderTree, ctx: BuildContext): NodeWalker {
+  switch (tree.kind) {
+    case "Empty": return new EmptyWalker();
+    case "Leaf": return new LeafWalker(ctx, tree.object);
+    case "Ordered": return new OrderedWalker(tree.children.map(c => build(c, ctx)));
+    case "Unordered": return new UnorderedWalker(tree.children.map(c => build(c, ctx)));
+    case "Adaptive": return new AdaptiveWalker(tree.tree, ctx);
+    case "OrderedFromList": return new OrderedFromListWalker(tree.children, ctx);
+    case "UnorderedFromSet": return new UnorderedFromSetWalker(tree.children, ctx);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ScenePass — public entry
+// ---------------------------------------------------------------------------
+
+export class ScenePass {
+  private readonly root: NodeWalker;
+  /** Bumped on `prepareRenderObject`. Tests use this to confirm O(deltas) prep cost. */
+  readonly stats: WalkerStats = { prepareCount: 0 };
+
+  constructor(
+    device: GPUDevice,
+    signature: FramebufferSignature,
+    tree: RenderTree,
+    compileEffect: (e: Effect) => CompiledEffect,
+  ) {
+    const ctx: BuildContext = { device, signature, compileEffect, stats: this.stats };
+    this.root = build(tree, ctx);
+  }
+
+  /**
+   * Pull deltas from every dynamic subtree, splice the affected
+   * walkers, and produce the current ordered list of leaves.
+   * Idempotent on a clean adaptive graph (no readers fire).
+   */
+  resolve(token: AdaptiveToken): PreparedRenderObject[] {
+    this.root.update(token);
+    const out: PreparedRenderObject[] = [];
+    this.root.emit(out);
+    return out;
+  }
+
+  dispose(): void {
+    this.root.dispose();
+  }
+}