reze-engine 0.42.3 → 0.50.0

package/src/shaders/passes/composite.ts

@@ -1,3 +1,12 @@
+import { RZ_LIGHT_STRUCT_WGSL } from "../lights"
+import { anchorAliasWgsl } from "../anchor-table"
+import { CAST_API } from "../cast-api"
+import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api"
+import { EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES } from "../cast-layout"
+import { audioApi } from "../audio-api"
+import { lyricsApi, lyricsTextApi } from "../lyrics-api"
+import { midiApi } from "../midi-api"
+import { gridReadApi } from "./grid"
 // Composite: HDR scene + bloom pyramid → Filmic tone map → gamma → swapchain.
 // Bloom tint/intensity applied at combine (EEVEE treats them as combine-stage params, not prefilter).
 //
@@ -71,22 +80,11 @@ export function parseEffectAnchors(wgsl: string, max: number): { bone: string; t
     .slice(0, max)
 }
 
-/**
- * The caps the cast buffer is built to, shared by the shader below and by the
- * engine that fills it. Interpolated into the WGSL rather than written twice:
- * the layout arithmetic on both sides has to agree exactly, and two literals
- * that must match are two literals that eventually will not.
- *
- * All three are MINIMUMS. Raising one breaks nothing, because effects read
- * through accessors and loop to the count functions; lowering one does.
- */
-export const EFFECT_SUBJECTS = 4
-export const EFFECT_ANCHORS = 8
-export const EFFECT_TRAIL_SAMPLES = 128
-/** vec4 slot where the trails begin — after the subjects and the anchors. */
-export const EFFECT_TRAIL_BASE = EFFECT_SUBJECTS * 3 + EFFECT_ANCHORS * EFFECT_SUBJECTS * 3
+// The cast's caps live in cast-layout.ts — re-exported here because half the
+// engine imports them from this file and the constants did not move in meaning.
+export { EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES } from "../cast-layout"
 
-export type CompositeEffectSource = {
+type CompositeEffectSource = {
   /** The user's WGSL verbatim: helpers plus whichever entry points it defines. */
   wgsl: string
   /** Codegen'd `struct EffectParams {...}` + binding decl; empty when no params. */
@@ -95,6 +93,20 @@ export type CompositeEffectSource = {
   hasBackground: boolean
   /** Defines `fn foreground(...)` — mount over the finished frame. */
   hasForeground: boolean
+  /** Grid resolution when the effect declared `// @grid`, else 0. */
+  gridSize: number
+  /** Whether the scene pass carries the id attachment, so the field module can
+   *  bind it. False emits accessors that answer 0 rather than nothing at all. */
+  ids?: boolean
+  /** How many of this effect's anchors asked for a trail — RZ_TRAIL_SLOTS,
+   *  which a hosted particle or trail loop reads even in this module. REQUIRED,
+   *  and deliberately not defaulted: a silent 0 is a ribbon loop that iterates
+   *  nothing, which looks exactly like an effect that drew nothing. */
+  trailCount: number
+  /** This effect's local anchor slot → scene slot, from the shared table.
+   *  Omitted or identity when it owns the table. The particle and trail modules
+   *  have always taken this; the field module not taking it was the bug. */
+  alias?: number[]
 }
 
 const COMPOSITE_HEAD = /* wgsl */ `
@@ -162,13 +174,39 @@ override APPLY_GAMMA: bool = true;
 // vec4 slots: [0 .. 11] four subjects, three each (root+valid, hip, bounds);
 // then MAX_ANCHORS × four subjects, three each (pos+valid, vel, fwd).
 @group(0) @binding(11) var<storage, read> _rzCast: array<vec4f>;
-
+// The FIELD LAYER: the user's background/foreground mounts, rendered at half
+// resolution in their own pass (see buildFieldShader) and sampled here. Field
+// effects are glows, fog, shafts, gradients — low-frequency by nature — and
+// running them per quarter-pixel was the single largest per-frame cost an
+// effect could add. Bilinear upsampling is invisible at that frequency.
+// The field layer, ONE PAIR PER RESOLUTION. 15/16 are full res, 20/21 half.
+// An effect draws into the pair it declared, so a starfield that upsamples
+// perfectly no longer pays full-resolution pixels because a neighbour needed
+// crisp edges. Both pairs are read every frame and combined full-over-half
+// below; a pair NO effect draws into is bound to a 1x1 transparent texture
+// instead of a target, so nothing has to clear a full-res pair to hand this
+// shader the transparent black it would then read.
+@group(0) @binding(15) var fieldBgTex: texture_2d<f32>;
+@group(0) @binding(16) var fieldFgTex: texture_2d<f32>;
+@group(0) @binding(20) var fieldBgHalfTex: texture_2d<f32>;
+@group(0) @binding(21) var fieldFgHalfTex: texture_2d<f32>;
+
+/** Two field layers into one, premultiplied OVER, top in front. A resolution
+ *  boundary is a layer boundary: within a pair, effects blend in document
+ *  order; across pairs, full res wins. (No backticks in here — this string is
+ *  a TS template literal and one ends it mid-shader.) */
+fn rzFieldMerge(top: vec4f, bot: vec4f) -> vec4f {
+  return vec4f(top.rgb + bot.rgb * (1.0 - top.a), top.a + bot.a * (1.0 - top.a));
+}
 // Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).
 const FILMIC_LUT_W: f32 = 256.0;
 
 fn linearDepth(coord: vec2<i32>) -> f32 {
   let z = textureLoad(depthTex, coord, 0);
-  // projA > 1 for every valid z in [0,1], so the divisor never crosses zero.
+  // projA and projB are m[10] and m[14] of whatever projection the camera built,
+  // so this one line inverts both conventions. Non-reversed puts projA just above
+  // 1; reversed puts it slightly below 0. Either way (z - projA) keeps its sign
+  // across the whole of z in [0,1], so the divisor never crosses zero.
   return clamp(dofU[2].y / (z - dofU[2].x), 0.05, 100000.0);
 }
 
@@ -256,7 +294,22 @@ fn viewTransform(c: vec3f) -> vec3f {
   if (mode > 0.5) { return vec3f(srgb_encode(c.r), srgb_encode(c.g), srgb_encode(c.b)); }
   return vec3f(filmic(c.r), filmic(c.g), filmic(c.b));
 }
+`
 
+/**
+ * The scene half of the effect API — camera, projection, cast, trails.
+ *
+ * Split out of COMPOSITE_HEAD so the SIM pass can have it too. One effect file
+ * is spliced into every module it has a mount in, so a file with both a grid and
+ * a foreground compiles its foreground inside the grid shader, where every
+ * rzCameraPos() in it has to resolve. Sharing the block is better than stubbing
+ * it twice, and it means a kernel can legitimately ask where a bone is — which
+ * is exactly what a wake wants.
+ *
+ * Depends on `viewU` and `_rzCast` being declared by the including module, and
+ * on nothing else: no textures, no samplers.
+ */
+export const EFFECT_SCENE_API = /* wgsl */ `
 // ── The effect API ────────────────────────────────────────────────────────────
 //
 // Named rz*, for the engine. The prefix earns its place twice: user code is
@@ -302,104 +355,22 @@ fn rzProject(p: vec3f) -> vec3f {
   return vec3f(ndc * 0.5 + 0.5, z);
 }
 
-/** A character, as much of one as a shader needs. */
-struct RzSubject {
-  /** On the FLOOR, under the body — where a ring or a magic circle belongs. */
-  root: vec3f,
-  /** At the hips, the middle of the body — where an aura belongs. */
-  center: vec3f,
-  /** Bounding sphere: xyz centre, w radius. Deliberately generous — cull with it. */
-  bounds: vec4f,
-  /** False past the end of the cast, and every field is then zero. */
-  valid: bool,
-}
+fn rzCamPos() -> vec3f { return rzCameraPos(); }
+fn rzCameraRight() -> vec3f { return viewU[3].xyz; }
+fn rzCameraUp() -> vec3f { return viewU[4].xyz; }
+fn rzCameraForward() -> vec3f { return viewU[5].xyz; }
 
-/** One bone an effect asked for, by name, at the top of its own source. */
-struct RzAnchor {
-  pos: vec3f,
-  /** World units per second, from the previous frame. Direction for a trail,
-   *  magnitude for anything that should react to how hard someone is moving. */
-  vel: vec3f,
-  /** The bone's forward axis — which way a foot points, where a head looks. */
-  fwd: vec3f,
-  /** False when this rig has no such bone. Check it: the alternative is drawing
-   *  a hand effect at the world origin on every model that spells it differently. */
-  valid: bool,
-}
+// The cast — subjects, anchors, trails — is CAST_API, shared verbatim with the
+// particle and trail modules. It used to be written out here, a second time, and
+// the two copies had drifted: this one had rzAnchor and that one did not.
+${CAST_API}
 
-const RZ_MAX_ANCHORS: i32 = ${EFFECT_ANCHORS};
+// The hashes, the noise and rzFalloff — EFFECT_MATH_API, the same text the
+// particle and trail modules get. The field module used to be missing most of
+// it, so a helper an author wrote for one mount failed to compile in another
+// for no reason visible in the file.
+${EFFECT_MATH_API}${PARTICLE_STRUCT_WGSL}
 
-/**
- * Character i. Loop to rzSubjectCount(), never to a constant — the caps here are
- * MINIMUMS and are free to grow, which is only true while nobody hardcodes them.
- */
-fn rzSubject(i: i32) -> RzSubject {
-  var s: RzSubject;
-  s.valid = i >= 0 && i < rzSubjectCount();
-  if (!s.valid) { return s; }
-  let b = i * 3;
-  s.root = _rzCast[b].xyz;
-  s.center = _rzCast[b + 1].xyz;
-  s.bounds = _rzCast[b + 2];
-  return s;
-}
-
-/**
- * The slot-th bone this effect declared, on character subject.
- *
- * Slots are the order of the declarations at the top of your source:
- *
- *     // @anchor 左手首
- *     // @anchor 頭
- *
- * gives you slot 0 and slot 1. Any bone name the model has works; valid is
- * false when it does not have it, which is the normal case across rigs that
- * spell things differently.
- */
-fn rzAnchor(subject: i32, slot: i32) -> RzAnchor {
-  var a: RzAnchor;
-  a.valid = false;
-  if (subject < 0 || subject >= rzSubjectCount() || slot < 0 || slot >= RZ_MAX_ANCHORS) { return a; }
-  let b = ${EFFECT_SUBJECTS * 3} + (slot * ${EFFECT_SUBJECTS} + subject) * 3;
-  a.valid = _rzCast[b].w > 0.5;
-  a.pos = _rzCast[b].xyz;
-  a.vel = _rzCast[b + 1].xyz;
-  a.fwd = _rzCast[b + 2].xyz;
-  return a;
-}
-
-const RZ_TRAIL_SAMPLES: i32 = ${EFFECT_TRAIL_SAMPLES};
-
-/**
- * How many path samples this anchor has. Zero unless it was declared with
- * trail, and it climbs from zero as the trail fills after the effect loads.
- *
- * Loop to THIS, never to RZ_TRAIL_SAMPLES: the cap is a minimum and is free to
- * grow, which stays true only while nobody hardcodes it.
- */
-fn rzTrailCount(subject: i32, slot: i32) -> i32 {
-  if (subject < 0 || subject >= rzSubjectCount() || slot < 0 || slot >= RZ_MAX_ANCHORS) { return 0; }
-  return i32(_rzCast[${EFFECT_SUBJECTS * 3} + (slot * ${EFFECT_SUBJECTS} + subject) * 3 + 2].w);
-}
-
-/**
- * Sample i of an anchor's path: xyz where it was, w how many seconds ago.
- *
- * i = 0 is NOW and they run backwards in time, so a ribbon is drawn by walking i
- * upward and fading on .w. Sampled at a fixed rate on the SCENE clock, not the
- * display's — so the path is identical in the editor, in an export, and in a
- * re-export, and its spacing does not change with framerate.
- *
- * This is what a hand trail wants instead of position and velocity. One position
- * and one velocity is a straight segment that jitters, because a velocity is a
- * difference between two frames; a path is what actually happened.
- */
-fn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {
-  let n = rzTrailCount(subject, slot);
-  if (i < 0 || i >= n) { return vec4f(0.0); }
-  let base = ${EFFECT_TRAIL_BASE} + (slot * ${EFFECT_SUBJECTS} + subject) * RZ_TRAIL_SAMPLES;
-  return _rzCast[base + i];
-}
 
 fn bgResolution() -> vec2f { return rzResolution(); }
 fn bgCameraPos() -> vec3f { return rzCameraPos(); }
@@ -446,6 +417,7 @@ fn rzWorldPos(ray: vec3f, depth: f32) -> vec3f {
 }
 
 fn bgWorldPos(ray: vec3f, depth: f32) -> vec3f { return rzWorldPos(ray, depth); }
+${RZ_LIGHT_STRUCT_WGSL}
 
 /** Color grading, applied to the tonemapped SCENE (not the background — see the
  *  call site). The core is ASC CDL, the film-industry interchange standard:
@@ -570,6 +542,19 @@ const COMPOSITE_BODY = /* wgsl */ `
       let su = 0.5 + atan2(dir.x, dir.z) * 0.15915494309;  // 1/(2π)
       let sv = 0.5 - asin(clamp(dir.y, -1.0, 1.0)) * 0.31830988618;  // 1/π
       bgPm = textureSampleLevel(bgEquirect, bloomSamp, vec2f(su, sv), 0.0).rgb;
+      if (bg.w > 2.5) {
+        // Mode 3: the texels are scene-linear RADIANCE, not display wallpaper.
+        // Same exposure, same view transform, same user gamma as the scene —
+        // one film for everything in frame, which is what makes a sun roll off
+        // like a sun instead of clipping at texture white. bg.x carries the
+        // world STRENGTH (the colour slot is dead in equirect modes). The
+        // scene's grade stays scene-only, the documented rule above.
+        var sky = max(viewTransform(bgPm * bg.x * viewU[0].x), vec3f(0.0));
+        if (APPLY_GAMMA) {
+          sky = pow(sky, vec3f(viewU[0].y));
+        }
+        bgPm = sky;
+      }
     }
     BACKGROUND_CALL
   }
@@ -577,6 +562,11 @@ const COMPOSITE_BODY = /* wgsl */ `
   // expression, because the foreground mount composites onto it.
   var outRgb = disp * sceneAlpha + bgPm * (1.0 - sceneAlpha);
   var outA = sceneAlpha + bgA * (1.0 - sceneAlpha);
+  // Ribbons are NOT read here any more: they draw inside the scene pass, so
+  // they are already in disp — tone mapped, and bloomed, which they never
+  // were while this line existed. Sampling them here as well would draw them
+  // twice, and the layer nothing clears would go stale the moment an effect
+  // was removed.
   FOREGROUND_CALL
   return vec4f(outRgb, outA);
 }
@@ -587,9 +577,16 @@ const COMPOSITE_BODY = /* wgsl */ `
 // OVER onto the base layer. No `if` around it: the pipeline is rebuilt per
 // effect, so this text only exists in variants whose WGSL defines background().
 const BACKGROUND_CALL = /* wgsl */ `
-    let bgUv = vec2f(fragCoord.x / fullSz.x, 1.0 - fragCoord.y / fullSz.y);
-    let bgFx = clamp(background(dir, bgUv, viewU[6].x), vec4f(0.0), vec4f(1.0));
-    bgPm = bgFx.rgb * bgFx.a + bgPm * (1.0 - bgFx.a);
+    // The field layer is PREMULTIPLIED: N effects blend into it in document
+    // order, and premultiplied is the only form in which repeated OVER composes
+    // associatively — straight alpha would need the divide back out on every
+    // draw. So rgb is already scaled by its own alpha and must not be again.
+    // With one effect drawing over a cleared target this is identical to the
+    // straight form it replaced.
+    let bgFx = rzFieldMerge(
+      clamp(textureSampleLevel(fieldBgTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)),
+      clamp(textureSampleLevel(fieldBgHalfTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)));
+    bgPm = bgFx.rgb + bgPm * (1.0 - bgFx.a);
     bgA = bgFx.a + bgA * (1.0 - bgFx.a);
 `
 
@@ -597,21 +594,14 @@ const BACKGROUND_CALL = /* wgsl */ `
 // base. Ungated by design: a foreground runs at every pixel, including the ones
 // the model covers, because covering them is the point.
 const FOREGROUND_CALL = /* wgsl */ `
-  let fgUv = vec2f(fragCoord.x / fullSz.x, 1.0 - fragCoord.y / fullSz.y);
-  // The scene's own depth, so the effect can tell what is in front of it: a
-  // petal compares its distance against this and lets the model take the pixel,
-  // and fog's alpha is nothing but a function of it. Pixels the scene never drew
-  // read the far plane, so distance fog closes over the backdrop too.
-  let fgFx = clamp(foreground(dir, fgUv, viewU[6].x, linearDepth(coord)), vec4f(0.0), vec4f(1.0));
-  outRgb = fgFx.rgb * fgFx.a + outRgb * (1.0 - fgFx.a);
+  // Premultiplied, as the background layer above — same reason.
+  let fgFx = rzFieldMerge(
+    clamp(textureSampleLevel(fieldFgTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)),
+    clamp(textureSampleLevel(fieldFgHalfTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)));
+  outRgb = fgFx.rgb + outRgb * (1.0 - fgFx.a);
   outA = fgFx.a + outA * (1.0 - fgFx.a);
 `
 
-// Derivative builtins are illegal in non-uniform control flow (WGSL uniformity
-// analysis rejects the pipeline), so the coverage gate below can only wrap
-// effect code that doesn't use them. Checked textually at build time.
-const USES_DERIVATIVES = /\b(?:fwidth|dpdx|dpdy)(?:Fine|Coarse)?\s*\(/
-
 /** The condition on the background block (equirect sample + background effect).
  *
  *  Two jobs. It skips the block behind pixels the model fully covers — the
@@ -620,33 +610,151 @@ const USES_DERIVATIVES = /\b(?:fwidth|dpdx|dpdy)(?:Fine|Coarse)?\s*\(/
  *  most). And with no background effect compiled in, it also skips the block
  *  entirely unless the equirect needs it.
  *
- *  The equirect uses explicit-LOD sampling, which is always legal in non-uniform
- *  flow; only derivative-using effects must keep uniform control flow and forgo
- *  the coverage half. The test is textual over the whole file, so a foreground
- *  that uses fwidth costs the background its gate — conservative, and only ever
- *  in the direction of correctness. (The foreground mount itself sits in uniform
- *  flow, so derivatives are always legal there.) */
+ *  Everything the gate wraps is an explicit-LOD sample or a texture read, both
+ *  always legal in non-uniform flow. It used to also wrap the user's code, which
+ *  meant an effect using a derivative builtin had to forfeit the gate; that
+ *  carve-out went with the field pass, and the last of it is below. */
 function backgroundCondition(effect?: CompositeEffectSource | null): string {
   // sceneAlpha, not alpha: the bokeh gather spreads coverage, so a pixel the
   // sharp scene fully covered can end up needing background behind its blur.
+  // (The old derivative carve-out is gone with the inline user code: the field
+  // pass runs the whole quad, which is uniform control flow by construction.)
   const coverage = "sceneAlpha < 0.999"
   if (!effect?.hasBackground) return `bg.w > 1.5 && ${coverage}`
-  return USES_DERIVATIVES.test(effect.wgsl) ? "true" : coverage
+  return coverage
 }
 
 export function buildCompositeShader(effect?: CompositeEffectSource | null): string {
   const body = COMPOSITE_BODY.replace("BACKGROUND_COND", backgroundCondition(effect))
     .replace("BACKGROUND_CALL", effect?.hasBackground ? BACKGROUND_CALL.trim() : "")
     .replace("FOREGROUND_CALL", effect?.hasForeground ? FOREGROUND_CALL.trim() : "")
-  if (!effect) return COMPOSITE_HEAD + body
+  // The composite is STATIC either way now: the user's code compiles in the
+  // field module alone, and the composite only decides whether to sample it.
+  return COMPOSITE_HEAD +
+    EFFECT_SCENE_API + anchorAliasWgsl(effect?.alias ?? []) + audioApi(0, 13) + midiApi(0, 19) + lyricsApi(0, 24) + body
+}
+
+/**
+ * The field pass: the user's background/foreground mounts at half resolution,
+ * into two rgba16f targets the composite bilinearly upsamples.
+ *
+ * The fragment reconstructs the FULL-resolution pixel it stands in for and runs
+ * the original derivation verbatim — same ndc, same ray, same uv, same depth
+ * read — so an effect cannot tell it moved; it is simply asked half as often
+ * in each direction.
+ */
+/**
+ * Reading the scene's id attachment from a field effect — the consumer the MRT
+ * work exists for.
+ *
+ * A field effect covers the whole screen and has no idea what it is drawing
+ * over. These make it addressable: mask a glow to one character, dissolve one
+ * material, outline the thing someone selected. Without them the id buffer is
+ * written every frame and read by nobody.
+ *
+ * MULTISAMPLED AND UNRESOLVED, so it is read the way it is written —
+ * textureLoad of sample 0, the same rule linearDepth already follows. An
+ * averaged id belongs to nothing.
+ *
+ * When ids are OFF the buffer does not exist, so the accessors are still
+ * DECLARED and answer 0 — the reserved nothing. An effect that masks by id then
+ * masks nothing at all, which is a scene that renders rather than a shader that
+ * will not compile.
+ */
+function idApi(on: boolean, group: number, binding: number): string {
+  if (!on) {
+    return /* wgsl */ `
+fn rzObjectAt(uv: vec2f) -> u32 { return 0u; }
+fn rzMaterialAt(uv: vec2f) -> u32 { return 0u; }
+`
+  }
+  return /* wgsl */ `
+@group(${group}) @binding(${binding}) var _rzIdTex: texture_multisampled_2d<u32>;
+
+/** Which OBJECT drew this pixel — compare against rzSubjectId(i). 0 = nothing. */
+fn rzObjectAt(uv: vec2f) -> u32 {
+  let sz = vec2f(textureDimensions(_rzIdTex));
+  let p = vec2<i32>(clamp(uv, vec2f(0.0), vec2f(1.0)) * sz);
+  return textureLoad(_rzIdTex, clamp(p, vec2<i32>(0), vec2<i32>(sz) - vec2<i32>(1)), 0).y;
+}
+
+/** Which MATERIAL drew it, within that object. 0 = nothing. */
+fn rzMaterialAt(uv: vec2f) -> u32 {
+  let sz = vec2f(textureDimensions(_rzIdTex));
+  let p = vec2<i32>(clamp(uv, vec2f(0.0), vec2f(1.0)) * sz);
+  return textureLoad(_rzIdTex, clamp(p, vec2<i32>(0), vec2<i32>(sz) - vec2<i32>(1)), 0).x;
+}
+`
+}
+
+export function buildFieldShader(effect: CompositeEffectSource): string {
+  const bgLine = effect.hasBackground
+    ? "out.bg = clamp(background(dir, uv, _rzFieldClock.x), vec4f(0.0), vec4f(1.0));"
+    : ""
+  const fgLine = effect.hasForeground
+    ? "out.fg = clamp(foreground(dir, uv, _rzFieldClock.x, linearDepth(vec2<i32>(min(fx, fullSz - 1.0)))), vec4f(0.0), vec4f(1.0));"
+    : ""
   return (
     COMPOSITE_HEAD +
+    EFFECT_SCENE_API +
+    anchorAliasWgsl(effect.alias ?? []) +
+    audioApi(0, 13) +
+    midiApi(0, 19) +
+    lyricsApi(0, 24) +
+    // The words themselves — the atlas rides the grid's sampler, which is
+    // declared just below and resolves module-wide.
+    lyricsTextApi(0, 25, "_rzGridSamp") +
+    // The persistent grid, always bound — a 1×1 of zeroes when the effect has
+    // none, so rzGrid() is a function that always exists rather than one an
+    // author has to know whether they are allowed to call.
+    gridReadApi(0, 17, 18, effect.gridSize) +
+    clockApi("_rzFieldClock.x", "0.0") +
+    viewportApi("viewU[6].w") +
+    trailSlotsApi(effect.trailCount) +
+    idApi(effect.ids === true, 0, 23) +
     "\n// ── user effect (setEffect) ──\n" +
     effect.paramsDecl +
     "\n" +
     effect.wgsl +
     "\n" +
-    body
+    /* wgsl */ `
+@group(0) @binding(14) var<uniform> fieldU: vec4f;
+/**
+ * THIS EFFECT'S OWN clock, seconds since it was installed.
+ *
+ * Per effect, and that is the whole point of it existing. The time argument
+ * used to come from viewU[6].x, which is measured from the FIRST installed
+ * effect's epoch — so every later effect started mid-stream, and an effect
+ * whose lightEmit read its own epoch disagreed with its own background()
+ * about what time it was. One buffer per effect, one answer.
+ */
+@group(0) @binding(22) var<uniform> _rzFieldClock: vec4f;
+
+@vertex fn fieldVs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
+  let x = f32((vi & 1u) << 2u) - 1.0;
+  let y = f32((vi & 2u) << 1u) - 1.0;
+  return vec4f(x, y, 0.0, 1.0);
+}
+
+struct FieldOut {
+  @location(0) bg: vec4f,
+  @location(1) fg: vec4f,
+}
+
+@fragment fn fieldFs(@builtin(position) fragCoord: vec4f) -> FieldOut {
+  let fullSz = fieldU.zw;
+  let fx = fragCoord.xy * (fullSz / max(fieldU.xy, vec2f(1.0)));
+  let ndc = vec2f(fx.x / fullSz.x * 2.0 - 1.0, 1.0 - fx.y / fullSz.y * 2.0);
+  let dir = normalize(viewU[5].xyz + ndc.x * viewU[3].w * viewU[3].xyz + ndc.y * viewU[4].w * viewU[4].xyz);
+  let uv = vec2f(fx.x / fullSz.x, 1.0 - fx.y / fullSz.y);
+  var out: FieldOut;
+  out.bg = vec4f(0.0);
+  out.fg = vec4f(0.0);
+  ${bgLine}
+  ${fgLine}
+  return out;
+}
+`
   )
 }
 

package/src/shaders/passes/cull.ts

@@ -0,0 +1,139 @@
+// GPU frustum cull writing indirect draw arguments.
+//
+// One dispatch covers every material draw in the scene and writes THREE
+// argument buffers — the camera pass, the shadow pass and the mirror pass —
+// because they differ only in which frustum they test against, and splitting
+// them into separate dispatches would read the same metadata each time. See
+// docs/frame-graph.md.
+//
+// The MIRROR frustum is the camera frustum reflected about the floor plane: an
+// object is visible in the mirror exactly when its reflection is visible to
+// the camera, i.e. when the object itself lies in the reflected frustum. The
+// camera args would be WRONG for it — a close-up of the floor shows a dancer's
+// reflection while the dancer herself is out of frame. When no reflection is
+// active the CPU writes the camera planes into the mirror slots, so the args
+// stay sane for bundles that never execute.
+//
+// The compute writes ONLY `instanceCount` (word 1 of each 5-word record). The
+// other four words — indexCount, firstIndex, baseVertex, firstInstance — are
+// seeded by the CPU when the draw list changes, which is the same moment the
+// metadata buffer is uploaded. Nothing about them varies per frame, so shipping
+// them through the compute would be a per-frame write in exchange for nothing.
+//
+// Two bound kinds, because a skinned mesh has no usable model-space bounds:
+//   RIGID   — every bone of the model shares one skin matrix (a stage, or a
+//             character still in its bind pose), so each material's load-time
+//             model-space AABB is valid and gets transformed by that matrix.
+//             This is what makes a 200-material stage worth culling at all.
+//   SKINNED — animation invalidates per-material bounds, so the whole model is
+//             one world-space sphere derived from its posed bone positions.
+//
+// Planes are NORMALIZED on the CPU. The AABB test would tolerate unnormalized
+// planes (distance and extent scale together), the sphere test would not.
+
+export const CULL_COMPUTE_WGSL = /* wgsl */ `
+struct DrawMeta {
+  lo: vec3f,      // model-space AABB min — read only for RIGID models
+  model: u32,     // index into models[]
+  hi: vec3f,      // model-space AABB max
+  flags: u32,     // bit0 = casts shadow
+};
+
+struct ModelRec {
+  xform: mat4x4f, // model space -> world; meaningful only when RIGID
+  sphere: vec4f,  // world-space centre.xyz + radius.w; meaningful when SKINNED
+  flags: u32,     // bit0 = visible, bit1 = rigid
+  pad0: u32,
+  pad1: u32,
+  pad2: u32,
+};
+
+// Camera planes at 0..5, light planes at 6..11, mirror planes at 12..17.
+// counts.x = draw count, counts.y = 0 to pass everything (setCullEnabled).
+struct Frusta {
+  planes: array<vec4f, 18>,
+  counts: vec4u,
+};
+
+@group(0) @binding(0) var<storage, read> metas: array<DrawMeta>;
+@group(0) @binding(1) var<storage, read> models: array<ModelRec>;
+@group(0) @binding(2) var<uniform> frusta: Frusta;
+@group(0) @binding(3) var<storage, read_write> cameraArgs: array<u32>;
+@group(0) @binding(4) var<storage, read_write> shadowArgs: array<u32>;
+// 1 = the user hid this material, or a material morph drove its alpha to zero.
+// Here rather than in the encode loop because a render bundle bakes its draw
+// list: a face VMD rewrites the morph-hidden set every frame, so a bundle that
+// invalidated on it would re-record every frame and cost more than it saves.
+@group(0) @binding(5) var<storage, read> hidden: array<u32>;
+@group(0) @binding(6) var<storage, read_write> mirrorArgs: array<u32>;
+
+const DRAW_CASTS_SHADOW: u32 = 1u;
+const MODEL_VISIBLE: u32 = 1u;
+const MODEL_RIGID: u32 = 2u;
+
+// Signed distance of the AABB's most-positive corner: the centre distance plus
+// the extent projected onto |n|. Negative means every corner is behind the
+// plane, which is the only case that can reject.
+fn aabbVisible(base: u32, c: vec3f, e: vec3f) -> bool {
+  for (var i = 0u; i < 6u; i = i + 1u) {
+    let p = frusta.planes[base + i];
+    if (dot(p.xyz, c) + p.w + dot(e, abs(p.xyz)) < 0.0) { return false; }
+  }
+  return true;
+}
+
+fn sphereVisible(base: u32, s: vec4f) -> bool {
+  for (var i = 0u; i < 6u; i = i + 1u) {
+    let p = frusta.planes[base + i];
+    if (dot(p.xyz, s.xyz) + p.w + s.w < 0.0) { return false; }
+  }
+  return true;
+}
+
+@compute @workgroup_size(64)
+fn cs(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let i = gid.x;
+  if (i >= frusta.counts.x) { return; }
+
+  // Named dm, not meta: "meta" is a WGSL reserved word (reserved for future use,
+  // so it parses nowhere). No backticks anywhere in this string either — it is a
+  // template literal, and one would end the shader mid-comment.
+  let dm = metas[i];
+  let m = models[dm.model];
+  let visible = (m.flags & MODEL_VISIBLE) != 0u;
+
+  var inCamera = false;
+  var inLight = false;
+  var inMirror = false;
+  if (visible) {
+    if ((m.flags & MODEL_RIGID) != 0u) {
+      let c = (dm.lo + dm.hi) * 0.5;
+      let e = (dm.hi - dm.lo) * 0.5;
+      let wc = (m.xform * vec4f(c, 1.0)).xyz;
+      // Extent of the transformed box: the abs of the linear part applied to the
+      // half-extent. Exact for the axis-aligned case, conservative for a rotation.
+      let a = mat3x3f(abs(m.xform[0].xyz), abs(m.xform[1].xyz), abs(m.xform[2].xyz));
+      let we = a * e;
+      inCamera = aabbVisible(0u, wc, we);
+      inLight = aabbVisible(6u, wc, we);
+      inMirror = aabbVisible(12u, wc, we);
+    } else {
+      inCamera = sphereVisible(0u, m.sphere);
+      inLight = sphereVisible(6u, m.sphere);
+      inMirror = sphereVisible(12u, m.sphere);
+    }
+  }
+
+  // Culling off (setCullEnabled) passes everything, so a scene can be A/B'd
+  // against its own unculled self without rebuilding anything. The pass still
+  // runs, so the diagnostics keep reporting. It bypasses the FRUSTUM only —
+  // a hidden material is not culled, it is switched off, and answering "is this
+  // gone because of culling?" requires the two to stay separable.
+  let off = frusta.counts.y == 0u;
+  let shown = hidden[i] == 0u;
+  let castsShadow = (dm.flags & DRAW_CASTS_SHADOW) != 0u;
+  cameraArgs[i * 5u + 1u] = select(0u, 1u, (inCamera || off) && shown);
+  shadowArgs[i * 5u + 1u] = select(0u, 1u, ((inLight && castsShadow) || off) && shown);
+  mirrorArgs[i * 5u + 1u] = select(0u, 1u, (inMirror || off) && shown);
+}
+`