@aardworx/wombat.rendering 0.9.16 → 0.9.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aardworx/wombat.rendering",
-  "version": "0.9.16",
+  "version": "0.9.17",
   "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/derivedModes/modeKeyCpu.ts

@@ -20,7 +20,7 @@ import type {
 } from "../../core/pipelineState.js";
 import type { FramebufferSignature } from "../../core/framebufferSignature.js";
 import type { aval, IDisposable } from "@aardworx/wombat.adaptive";
-import { addMarkingCallback } from "@aardworx/wombat.adaptive";
+import { addMarkingCallback, AdaptiveToken } from "@aardworx/wombat.adaptive";
 
 import {
   encodeModeKey,
@@ -31,6 +31,42 @@ import {
   type BlendComponent,
   type DepthSlice,
 } from "../pipelineCache/index.js";
+import type { DerivedModeRule } from "./rule.js";
+
+/**
+ * Per-axis derived-mode rules for one RO. Same shape as
+ * `HeapDrawSpec.modeRules`.
+ */
+export interface RoModeRules {
+  readonly cull?:            DerivedModeRule<"cull">;
+  readonly frontFace?:       DerivedModeRule<"frontFace">;
+  readonly topology?:        DerivedModeRule<"topology">;
+  readonly depthCompare?:    DerivedModeRule<"depthCompare">;
+  readonly depthWrite?:      DerivedModeRule<"depthWrite">;
+  readonly alphaToCoverage?: DerivedModeRule<"alphaToCoverage">;
+}
+
+/**
+ * Uniforms accessor exposed to a derived-mode rule's `(u, declared)`
+ * closure. Reads each `u.<Name>` from the supplied aval map at
+ * evaluation time and tracks which avals were accessed so the
+ * `ModeKeyTracker` can subscribe to them.
+ */
+function uniformsProxy(
+  uniformAvals: ReadonlyMap<string, aval<unknown>>,
+  tok: AdaptiveToken,
+  recordDep: ((av: aval<unknown>) => void) | undefined,
+): Record<string, unknown> {
+  return new Proxy({}, {
+    get(_target, prop): unknown {
+      if (typeof prop !== "string") return undefined;
+      const av = uniformAvals.get(prop);
+      if (av === undefined) return undefined;
+      if (recordDep !== undefined) recordDep(av);
+      return av.getValue(tok);
+    },
+  }) as Record<string, unknown>;
+}
 
 /**
  * One-shot snapshot of the current values of every leaf aval in a
@@ -42,9 +78,15 @@ import {
 export function snapshotDescriptor(
   ps: PipelineState | undefined,
   signature: FramebufferSignature,
+  options: {
+    readonly modeRules?: RoModeRules;
+    readonly uniformAvals?: ReadonlyMap<string, aval<unknown>>;
+    readonly token?: AdaptiveToken;
+    readonly recordDep?: (av: aval<unknown>) => void;
+  } = {},
 ): PipelineStateDescriptor {
   if (ps === undefined) {
-    return buildAttachmentsFor(DEFAULT_DESCRIPTOR, signature);
+    return applyRules(buildAttachmentsFor(DEFAULT_DESCRIPTOR, signature), options);
   }
   const r = ps.rasterizer;
   const depth = ps.depth !== undefined ? snapshotDepth(ps.depth, signature) : undefined;
@@ -63,6 +105,52 @@ export function snapshotDescriptor(
     attachments,
     alphaToCoverage: atc,
   };
+  return applyRules(out, options);
+}
+
+function applyRules(
+  d: PipelineStateDescriptor,
+  options: {
+    readonly modeRules?: RoModeRules;
+    readonly uniformAvals?: ReadonlyMap<string, aval<unknown>>;
+    readonly token?: AdaptiveToken;
+    readonly recordDep?: (av: aval<unknown>) => void;
+  },
+): PipelineStateDescriptor {
+  const rules = options.modeRules;
+  if (rules === undefined) return d;
+  const uniforms = options.uniformAvals ?? new Map();
+  const tok = options.token ?? AdaptiveToken.top;
+  const proxy = uniformsProxy(uniforms, tok, options.recordDep);
+  let out = d;
+  if (rules.cull !== undefined) {
+    const v = rules.cull.evaluate(proxy, out.cullMode);
+    if (v !== out.cullMode) out = { ...out, cullMode: v };
+  }
+  if (rules.frontFace !== undefined) {
+    const v = rules.frontFace.evaluate(proxy, out.frontFace);
+    if (v !== out.frontFace) out = { ...out, frontFace: v };
+  }
+  if (rules.topology !== undefined) {
+    const v = rules.topology.evaluate(proxy, out.topology);
+    if (v !== out.topology) out = { ...out, topology: v, stripIndexFormat: stripFormatFor(v) };
+  }
+  if (rules.alphaToCoverage !== undefined) {
+    const v = rules.alphaToCoverage.evaluate(proxy, out.alphaToCoverage);
+    if (v !== out.alphaToCoverage) out = { ...out, alphaToCoverage: v };
+  }
+  if (out.depth !== undefined && (rules.depthCompare !== undefined || rules.depthWrite !== undefined)) {
+    let depthOut = out.depth;
+    if (rules.depthCompare !== undefined) {
+      const v = rules.depthCompare.evaluate(proxy, depthOut.compare);
+      if (v !== depthOut.compare) depthOut = { ...depthOut, compare: v };
+    }
+    if (rules.depthWrite !== undefined) {
+      const v = rules.depthWrite.evaluate(proxy, depthOut.write);
+      if (v !== depthOut.write) depthOut = { ...depthOut, write: v };
+    }
+    if (depthOut !== out.depth) out = { ...out, depth: depthOut };
+  }
   return out;
 }
 
@@ -131,6 +219,11 @@ export class ModeKeyTracker implements IDisposable {
   private readonly subs: IDisposable[] = [];
   private cachedDescriptor: PipelineStateDescriptor;
   private cachedModeKey: bigint;
+  private readonly modeRules: RoModeRules | undefined;
+  private readonly uniformAvals: ReadonlyMap<string, aval<unknown>> | undefined;
+  /** Avals discovered while evaluating rules; merged into the leaf
+   *  set returned by `forEachLeaf` so the heap scene subscribes once. */
+  private readonly ruleDeps = new Set<aval<unknown>>();
 
   constructor(
     ps: PipelineState | undefined,
@@ -144,43 +237,63 @@ export class ModeKeyTracker implements IDisposable {
      * cullCval case) — saves N subscriptions and N callback dispatches
      * per mark.
      */
-    options: { skipSubscribe?: boolean } = {},
+    options: {
+      skipSubscribe?: boolean;
+      modeRules?: RoModeRules;
+      uniformAvals?: ReadonlyMap<string, aval<unknown>>;
+    } = {},
   ) {
     this.ps        = ps;
     this.signature = signature;
     this.onDirty   = onDirty;
-    this.cachedDescriptor = snapshotDescriptor(ps, signature);
+    if (options.modeRules    !== undefined) this.modeRules    = options.modeRules;
+    if (options.uniformAvals !== undefined) this.uniformAvals = options.uniformAvals;
+    this.cachedDescriptor = this.snapshot();
     this.cachedModeKey    = encodeModeKey(this.cachedDescriptor);
     if (options.skipSubscribe !== true) this.subscribeAll();
   }
 
+  private snapshot(): PipelineStateDescriptor {
+    return snapshotDescriptor(this.ps, this.signature, {
+      ...(this.modeRules    !== undefined ? { modeRules:    this.modeRules    } : {}),
+      ...(this.uniformAvals !== undefined ? { uniformAvals: this.uniformAvals } : {}),
+      recordDep: (av) => { this.ruleDeps.add(av); },
+    });
+  }
+
   /**
    * Walk every leaf aval in this tracker's PipelineState and invoke
    * `visit(aval)`. Used by the heap scene to register ONE
    * addMarkingCallback per unique aval across many trackers.
    */
   forEachLeaf(visit: (a: aval<unknown>) => void): void {
-    if (this.ps === undefined) return;
     const ps = this.ps;
-    visit(ps.rasterizer.topology);
-    visit(ps.rasterizer.cullMode);
-    visit(ps.rasterizer.frontFace);
-    if (ps.rasterizer.depthBias !== undefined) visit(ps.rasterizer.depthBias);
-    if (ps.depth !== undefined) {
-      visit(ps.depth.write);
-      visit(ps.depth.compare);
-      if (ps.depth.clamp !== undefined) visit(ps.depth.clamp);
-    }
-    if (ps.blends !== undefined) {
-      visit(ps.blends);
-      const map = ps.blends.force(/* allow-force */);
-      for (const [, bs] of map) {
-        visit(bs.color.srcFactor); visit(bs.color.dstFactor); visit(bs.color.operation);
-        visit(bs.alpha.srcFactor); visit(bs.alpha.dstFactor); visit(bs.alpha.operation);
-        visit(bs.writeMask);
+    if (ps !== undefined) {
+      visit(ps.rasterizer.topology);
+      visit(ps.rasterizer.cullMode);
+      visit(ps.rasterizer.frontFace);
+      if (ps.rasterizer.depthBias !== undefined) visit(ps.rasterizer.depthBias);
+      if (ps.depth !== undefined) {
+        visit(ps.depth.write);
+        visit(ps.depth.compare);
+        if (ps.depth.clamp !== undefined) visit(ps.depth.clamp);
+      }
+      if (ps.blends !== undefined) {
+        visit(ps.blends);
+        const map = ps.blends.force(/* allow-force */);
+        for (const [, bs] of map) {
+          visit(bs.color.srcFactor); visit(bs.color.dstFactor); visit(bs.color.operation);
+          visit(bs.alpha.srcFactor); visit(bs.alpha.dstFactor); visit(bs.alpha.operation);
+          visit(bs.writeMask);
+        }
       }
+      if (ps.alphaToCoverage !== undefined) visit(ps.alphaToCoverage);
     }
-    if (ps.alphaToCoverage !== undefined) visit(ps.alphaToCoverage);
+    // Rule-input deps discovered on the last evaluation. The set is
+    // refreshed each `recompute()`; callers re-subscribe accordingly.
+    // Surfaced regardless of `ps` because a rule can fire without
+    // any underlying PipelineState aval (e.g. ps === undefined).
+    for (const av of this.ruleDeps) visit(av);
   }
 
   get descriptor(): PipelineStateDescriptor { return this.cachedDescriptor; }
@@ -190,9 +303,15 @@ export class ModeKeyTracker implements IDisposable {
    * Snapshot current aval values and rebuild descriptor + modeKey.
    * Returns true iff the modeKey changed (so the bucket only needs to
    * upload + repartition when something actually moved).
+   *
+   * Also rediscovers rule-input dependencies on every call — a
+   * conditional rule body may read different uniforms in different
+   * branches. New deps surface in `forEachLeaf` so the heap scene's
+   * subscription-dedupe layer picks them up.
    */
   recompute(): boolean {
-    const next = snapshotDescriptor(this.ps, this.signature);
+    this.ruleDeps.clear();
+    const next = this.snapshot();
     const nextKey = encodeModeKey(next);
     if (nextKey === this.cachedModeKey) return false;
     this.cachedDescriptor = next;

package/src/runtime/derivedModes/rule.ts

@@ -0,0 +1,110 @@
+// `derivedMode(axis, (u, declared) => modeValue)` — author-facing
+// marker for per-RO pipeline-state values that are functions of the
+// RO's uniforms.
+//
+// v1 is CPU-evaluated: the user's closure runs in JS each time the
+// rule's inputs mark. That's a good fit for the typical authoring
+// shapes (a uniform-driven enum flip, a determinant-sign cull flip,
+// etc.) and pairs naturally with the bucket-level rebuild fast path
+// shipped in 0.9.16 — only ROs whose inputs actually changed get
+// re-evaluated, and same-key buckets re-bind their pipeline once
+// rather than per-RO.
+//
+// v2 (deferred) lowers rules to a GPU compute kernel via §7's IR
+// machinery — needed only when bulk-animated per-RO inputs become a
+// CPU-side bottleneck. See docs/derived-mode-rules-plan.md.
+//
+// What can be derived (the small-enum axes — cull/blend/depth-compare/
+// topology/etc.) and what stays static (depth bias, blend constant,
+// stencil ref) is covered in docs/derived-modes.md.
+
+import type { CullMode, FrontFace, Topology } from "../pipelineCache/index.js";
+
+/** Discrete pipeline-state axes a `derivedMode` rule can target. v1
+ *  supports cull / frontFace / topology / depthCompare / depthWrite /
+ *  blendEnabled. Stencil + per-attachment blend factor/operation are
+ *  deferred — same carve-outs as `derived-modes.md`. */
+export type ModeAxis =
+  | "cull" | "frontFace" | "topology"
+  | "depthCompare" | "depthWrite"
+  | "alphaToCoverage";
+
+/** Output value type per axis. */
+export type ModeValue<A extends ModeAxis> =
+  A extends "cull"           ? CullMode :
+  A extends "frontFace"      ? FrontFace :
+  A extends "topology"       ? Topology :
+  A extends "depthCompare"   ? GPUCompareFunction :
+  A extends "depthWrite"     ? boolean :
+  A extends "alphaToCoverage" ? boolean :
+  never;
+
+/**
+ * The closure signature a `derivedMode` rule body takes:
+ *   - `u`: a proxy whose properties resolve to the RO's uniform values
+ *     at evaluation time. The proxy is type-erased in v1 — declare the
+ *     uniforms you'll read via `UniformScope` augmentation on the
+ *     wombat.shader side for compile-time safety, or annotate locally.
+ *   - `declared`: the SG-declared value for this axis at this leaf.
+ *     Identity rules `(u, d) => d` are valid and useful for axes that
+ *     want to pass declared through unchanged.
+ */
+export type DerivedModeBuilder<A extends ModeAxis> = (
+  u: Record<string, unknown>,
+  declared: ModeValue<A>,
+) => ModeValue<A>;
+
+export interface DerivedModeRule<A extends ModeAxis = ModeAxis> {
+  readonly __derivedModeRule: true;
+  readonly axis:    A;
+  readonly evaluate: DerivedModeBuilder<A>;
+  /**
+   * Conservative over-approximation of the rule's output set. Used by
+   * the build-time pre-warm in v2 to enumerate the pipelines a scene
+   * could realize. v1 doesn't use it at runtime, but recording it
+   * here keeps the API forward-compatible.
+   */
+  readonly domain?: ReadonlyArray<ModeValue<A>>;
+}
+
+/**
+ * Author a derived mode rule.
+ *
+ *     derivedMode("cull", (u, declared) =>
+ *       u.WindingFlipped ? flipCull(declared) : declared);
+ *
+ *     derivedMode("blend", (u) => u.Premultiplied ? "premul" : "straight");
+ *
+ *     // Determinant-flip-cull (the motivating case):
+ *     derivedMode("cull", (u, declared) => {
+ *       const m = u.ModelTrafo as M44d;
+ *       const det =
+ *         m.M00 * (m.M11 * m.M22 - m.M12 * m.M21) -
+ *         m.M01 * (m.M10 * m.M22 - m.M12 * m.M20) +
+ *         m.M02 * (m.M10 * m.M21 - m.M11 * m.M20);
+ *       return det < 0 ? flipCull(declared) : declared;
+ *     });
+ */
+export function derivedMode<A extends ModeAxis>(
+  axis: A,
+  evaluate: DerivedModeBuilder<A>,
+  options: { readonly domain?: ReadonlyArray<ModeValue<A>> } = {},
+): DerivedModeRule<A> {
+  const out: DerivedModeRule<A> = options.domain !== undefined
+    ? { __derivedModeRule: true, axis, evaluate, domain: options.domain }
+    : { __derivedModeRule: true, axis, evaluate };
+  return out;
+}
+
+/** Brand check — distinguishes a DerivedModeRule from an aval/raw value
+ *  at runtime so PipelineState consumers can route accordingly. */
+export function isDerivedModeRule(x: unknown): x is DerivedModeRule {
+  return typeof x === "object" && x !== null
+      && (x as { __derivedModeRule?: unknown }).__derivedModeRule === true;
+}
+
+/** Convenience: flip 'back' ↔ 'front' (and pass through 'none').
+ *  Useful in `(u, declared) => mirrored ? flipCull(declared) : declared`. */
+export function flipCull(c: CullMode): CullMode {
+  return c === "back" ? "front" : c === "front" ? "back" : "none";
+}

package/src/runtime/heapScene.ts

@@ -92,7 +92,7 @@ import {
   ENC_V3F_TIGHT, SEM_POSITIONS, SEM_NORMALS,
   type ArenaState,
 } from "./heapScene/pools.js";
-import { encodeModeKey } from "./pipelineCache/index.js";
+import { encodeModeKey, type PipelineStateDescriptor } from "./pipelineCache/index.js";
 import { snapshotDescriptor, ModeKeyTracker } from "./derivedModes/modeKeyCpu.js";
 import { addMarkingCallback } from "@aardworx/wombat.adaptive";
 
@@ -341,6 +341,38 @@ export interface HeapDrawSpec {
    * with depth write enabled. Matches the demo's existing visuals.
    */
   readonly pipelineState?: PipelineState;
+  /**
+   * Per-RO derived pipeline-mode rules: per-axis closures
+   * `(u, declared) => modeValue` that compute the effective mode
+   * value as a function of this RO's uniforms (see
+   * `derivedMode(...)` in `runtime/derivedModes/rule.ts`).
+   *
+   * A rule overrides the corresponding `pipelineState.rasterizer.*`
+   * (or `pipelineState.depth.*`) aval value at descriptor-snapshot
+   * time. The rule's closure runs CPU-side with a proxy that
+   * resolves `u.<Name>` against this spec's `inputs[<Name>]`. The
+   * heap renderer auto-discovers the closure's input dependencies on
+   * first run and subscribes the per-RO ModeKeyTracker to each of
+   * them — so a rule that reads `u.ModelTrafo` reactively rebuckets
+   * when ModelTrafo marks.
+   *
+   * Common use cases:
+   *   - cull: flip-by-determinant-sign for mirrored geometry
+   *   - blend: pick a preset based on a boolean uniform
+   *   - depthCompare: lighter passes for transparent overlays
+   *
+   * v1 evaluates rules CPU-side. v2 (deferred) lowers them to a GPU
+   * compute kernel for the bulk-animated-input case. See
+   * `docs/derived-modes.md`.
+   */
+  readonly modeRules?: {
+    readonly cull?:           import("./derivedModes/rule.js").DerivedModeRule<"cull">;
+    readonly frontFace?:      import("./derivedModes/rule.js").DerivedModeRule<"frontFace">;
+    readonly topology?:       import("./derivedModes/rule.js").DerivedModeRule<"topology">;
+    readonly depthCompare?:   import("./derivedModes/rule.js").DerivedModeRule<"depthCompare">;
+    readonly depthWrite?:     import("./derivedModes/rule.js").DerivedModeRule<"depthWrite">;
+    readonly alphaToCoverage?: import("./derivedModes/rule.js").DerivedModeRule<"alphaToCoverage">;
+  };
 }
 
 export interface HeapSceneStats {
@@ -1473,6 +1505,13 @@ export function buildHeapScene(
     effect: Effect,
     _textures: HeapTextureSet | undefined,
     pipelineState: PipelineState | undefined,
+    /**
+     * Optional precomputed descriptor. addDrawImpl passes this when
+     * the spec carries `modeRules` so the bucket key reflects the
+     * rule-evaluated value (not the raw PS aval values). When omitted
+     * the descriptor is snapshotted from PS as before.
+     */
+    precomputedDescriptor?: PipelineStateDescriptor,
   ): Bucket {
     if (!familyBuilt) {
       throw new Error("heapScene: findOrCreateBucket called before family build");
@@ -1486,12 +1525,24 @@ export function buildHeapScene(
     // (the actual value-set in the descriptor), so identical-value
     // cvals collapse to ONE bucket. See docs/derived-modes.md and
     // tests/heap-multi-pipeline-bucket.test.ts.
-    const psDescriptor = snapshotDescriptor(pipelineState, sig);
+    const psDescriptor = precomputedDescriptor ?? snapshotDescriptor(pipelineState, sig);
     const psModeKey    = encodeModeKey(psDescriptor);
     const bk = `family#${fam.schema.id}|mk#${psModeKey.toString(16)}`;
     const existing = bucketByKey.get(bk);
     if (existing !== undefined) return existing;
-    const ps = resolvePipelineState(pipelineState);
+    // If a precomputed descriptor is supplied (rule-evaluated path),
+    // use its post-rule axis values so the pipeline reflects what the
+    // RO actually wants. Otherwise fall through to PS-aval forcing.
+    const ps: ResolvedPipelineState = precomputedDescriptor !== undefined
+      ? {
+          topology:  precomputedDescriptor.topology,
+          cullMode:  precomputedDescriptor.cullMode,
+          frontFace: precomputedDescriptor.frontFace,
+          ...(precomputedDescriptor.depth !== undefined
+            ? { depth: { write: precomputedDescriptor.depth.write, compare: precomputedDescriptor.depth.compare } }
+            : {}),
+        }
+      : resolvePipelineState(pipelineState);
 
     const layout: BucketLayout = fam.schema.drawHeaderUnion;
     const isAtlasBucket = layout.atlasTextureBindings.size > 0;
@@ -1800,7 +1851,24 @@ export function buildHeapScene(
     const perInstanceAttributes = spec.instanceAttributes !== undefined
       ? new Set(Object.keys(spec.instanceAttributes))
       : new Set<string>();
-    const bucket = findOrCreateBucket(spec.effect, spec.textures, spec.pipelineState);
+
+    // If the spec has modeRules, pre-snapshot the rule-evaluated
+    // descriptor so the bucket key + pipeline reflect post-rule
+    // values. Without this, two ROs with identical PS but different
+    // rule outputs would collide on the same bucket.
+    let precomputedDescriptor: PipelineStateDescriptor | undefined;
+    if (spec.modeRules !== undefined) {
+      const uAvals = new Map<string, aval<unknown>>();
+      for (const [name, val] of Object.entries(spec.inputs)) {
+        uAvals.set(name, asAval(val as aval<unknown> | unknown));
+      }
+      precomputedDescriptor = snapshotDescriptor(spec.pipelineState, sig, {
+        modeRules:    spec.modeRules,
+        uniformAvals: uAvals,
+        token:        outerTok,
+      });
+    }
+    const bucket = findOrCreateBucket(spec.effect, spec.textures, spec.pipelineState, precomputedDescriptor);
     const fam = familyFor(spec.effect);
     const effectFields = fam.fieldsForEffect.get(spec.effect.id)!;
 
@@ -1985,10 +2053,25 @@ export function buildHeapScene(
     // skipSubscribe: this tracker doesn't install its own callbacks.
     // The scene-level `modeAvalToDrawIds` does it once per unique aval
     // (the 20k-ROs-share-one-cullCval optimization).
+    // If the spec has modeRules, pre-build a uniforms-aval map the
+    // rule closures will read against; the tracker auto-discovers
+    // which avals each rule reads and surfaces them via forEachLeaf.
+    let uniformAvals: ReadonlyMap<string, aval<unknown>> | undefined;
+    if (spec.modeRules !== undefined) {
+      const m = new Map<string, aval<unknown>>();
+      for (const [name, val] of Object.entries(spec.inputs)) {
+        m.set(name, asAval(val as aval<unknown> | unknown));
+      }
+      uniformAvals = m;
+    }
     const tracker = new ModeKeyTracker(
       spec.pipelineState, sig,
       () => { dirtyModeKeyDrawIds.add(drawId); },
-      { skipSubscribe: true },
+      {
+        skipSubscribe: true,
+        ...(spec.modeRules  !== undefined ? { modeRules: spec.modeRules } : {}),
+        ...(uniformAvals    !== undefined ? { uniformAvals } : {}),
+      },
     );
     drawIdToModeTracker[drawId] = tracker;
     tracker.forEachLeaf((av) => subscribeModeLeaf(av, drawId));

package/src/runtime/index.ts

@@ -126,3 +126,13 @@ export {
   type PartitionInput,
   type PartitionResult,
 } from "./derivedModes/partition.js";
+
+export {
+  derivedMode,
+  isDerivedModeRule,
+  flipCull,
+  type DerivedModeRule,
+  type DerivedModeBuilder,
+  type ModeAxis,
+  type ModeValue,
+} from "./derivedModes/rule.js";