reze-engine 0.57.6 → 0.58.1

package/src/shaders/lights.ts

@@ -38,6 +38,7 @@ import { midiApi } from "./midi-api"
 import { lyricsApi } from "./lyrics-api"
 import { clockApi, trailSlotsApi, viewportApi } from "./passes/hosted-api"
 import { idApi } from "./id-api"
+import { sceneLightApi, worldAmbientWgsl } from "./scene-light-api"
 
 /** Floats before the first record. One is the count; the rest keep the records
  *  vec4-aligned, which is what lets a future pass read them as vec4s. */
@@ -84,29 +85,8 @@ struct RzLight {
 }
 `
 
-/**
- * The world's light at a surface facing n — the flat colour, or the installed
- * HDRI's irradiance (sh[0].w = 1), evaluated from folded SH coefficients (see
- * ibl.ts for the folding; the shader is a plain polynomial in the normal).
- *
- * One string included by every module that declares LightUniforms with the sh
- * block — the hosted-api lesson: a helper defined in some modules and not
- * others is a compile error waiting for the first file that crosses them.
- */
-export const WORLD_AMBIENT_WGSL = /* wgsl */ `
-fn rzWorldAmbient(n: vec3f) -> vec3f {
-  if (light.sh[0].w < 0.5) { return light.ambientColor.xyz; }
-  let x = n.x;
-  let y = n.y;
-  let z = n.z;
-  let c = light.sh[0].xyz
-    + light.sh[1].xyz * y + light.sh[2].xyz * z + light.sh[3].xyz * x
-    + light.sh[4].xyz * (x * y) + light.sh[5].xyz * (y * z)
-    + light.sh[6].xyz * (3.0 * z * z - 1.0) + light.sh[7].xyz * (x * z)
-    + light.sh[8].xyz * (x * x - y * y);
-  return max(c, vec3f(0.0));
-}
-`
+/** rzWorldAmbient against the materials' and the ground's `light` uniform. */
+export const WORLD_AMBIENT_WGSL = worldAmbientWgsl("light")
 
 /** Does this source define the emit mount? */
 export function hasLightEmit(wgsl: string): boolean {
@@ -184,7 +164,7 @@ ${viewportApi("viewU[6].w")}
 ${trailSlotsApi(cast.trailCount)}
 // The id accessors, stubbed: this module cannot read an attachment the
 // scene pass writes. See id-api.ts — the author's whole file compiles here.
-${idApi(false, 0, 0) + castDistanceStub()}
+${idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0)}
 // The dials the author declared, if any. A lamp is exactly the thing someone
 // retunes — its colour and its reach — so an emitter reads params like every
 // other mount rather than being the one place a #param resolves to nothing.

package/src/shaders/materials/common.ts

@@ -1,6 +1,7 @@
 import { sceneFsOutWgsl } from "../passes/scene-contract"
 import { lightsApi } from "../lights"
 import { SHADOW_CASCADES } from "../../shadow-cascades"
+import { pcf9 } from "../scene-light-api"
 import { WORLD_AMBIENT_WGSL } from "../lights"
 
 // Shared WGSL blocks concatenated by every material shader.
@@ -175,8 +176,8 @@ fn safe_normal(nIn: vec3f) -> vec3f {
 `;
 
 // ─── Shadow sampler (3×3 PCF, cascade-selected) ─────────────────────
-// Normal-bias 0.08, depth-bias 0.001 NDC. Unrolled — Safari's Metal backend
-// doesn't unroll nested shadow loops reliably. Texel sizes are interpolated
+// Normal-bias 0.08, depth-bias 0.001 NDC; the kernel is pcf9 in scene-light-api.ts,
+// shared with effects. Texel sizes are interpolated
 // from SHADOW_CASCADES so they cannot go stale the way the hardcoded 1/2048
 // once did (PCF taps landed TWO texels apart after the map grew to 4096,
 // quantizing self-shadow edges into crawling gray squares).
@@ -188,21 +189,6 @@ fn safe_normal(nIn: vec3f) -> vec3f {
 // far plane the comparison failed against every stored depth, silently
 // shadowing any stage deeper than the box.
 
-const pcf9 = (map: string, ts: string) => /* wgsl */ `
-  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
-  let cmpZ = ndc.z - 0.001;
-  let ts = ${ts};
-  let s00 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(-ts, -ts), cmpZ);
-  let s10 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(0.0, -ts), cmpZ);
-  let s20 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f( ts, -ts), cmpZ);
-  let s01 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(-ts, 0.0), cmpZ);
-  let s11 = textureSampleCompareLevel(${map}, shadowSampler, suv, cmpZ);
-  let s21 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f( ts, 0.0), cmpZ);
-  let s02 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(-ts,  ts), cmpZ);
-  let s12 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(0.0,  ts), cmpZ);
-  let s22 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f( ts,  ts), cmpZ);
-  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);
-`
 
 const SAMPLE_SHADOW_WGSL = /* wgsl */ `
 

package/src/shaders/passes/composite.ts

@@ -6,6 +6,7 @@ import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewpor
 import { EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES } from "../cast-layout"
 import { audioApi } from "../audio-api"
 import { idApi } from "../id-api"
+import { sceneLightApi } from "../scene-light-api"
 import { castDistanceApi, CAST_FIELD_DIV } from "./cast-distance"
 import { lyricsApi, lyricsTextApi } from "../lyrics-api"
 import { midiApi } from "../midi-api"
@@ -722,6 +723,7 @@ export function buildFieldShader(effect: CompositeEffectSource): string {
     viewportApi("viewU[6].w") +
     trailSlotsApi(effect.trailCount) +
     idApi(effect.ids === true, 0, 23) +
+    sceneLightApi(false, 0, 0) +
     // Distance to the cast, in SCREEN pixels: the field is half-res, so a field
     // texel is CAST_FIELD_DIV of them and the accessor scales on the way out.
     // An author writes the width they mean and never learns how it is built.

package/src/shaders/passes/grid.ts

@@ -8,6 +8,7 @@ import { SCENE_TAP_STUB } from "../scene-tap"
 import { type CastLayout } from "./particles"
 import { clockApi, trailSlotsApi, viewportApi } from "./hosted-api"
 import { idApi } from "../id-api"
+import { sceneLightApi } from "../scene-light-api"
 
 // A persistent grid an effect can step and read: the one thing an effect could
 // not have before, which is MEMORY.
@@ -168,6 +169,7 @@ fn rzGrid(uv: vec2f) -> vec4f { return rzGridPrev(uv); }
     // Stubbed: this module cannot read an attachment the scene pass writes — see
     // id-api.ts. The author's whole file compiles here, so the names must exist.
     idApi(false, 0, 0) +
+    sceneLightApi(false, 0, 0) +
     // Inlined rather than imported from cast-distance, and NOT for tidiness.
     //
     // This module and composite.ts import each other — grid takes

package/src/shaders/passes/particles.ts

@@ -1,4 +1,5 @@
 import { castDistanceStub } from "./cast-distance"
+import { gridReadApi } from "./grid"
 import { RZ_LIGHT_STRUCT_WGSL } from "../lights"
 import { audioApi } from "../audio-api"
 import { lyricsApi } from "../lyrics-api"
@@ -9,6 +10,7 @@ import { EFFECT_SUBJECT_VEC4S } from "../cast-layout"
 import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api"
 import { sceneIdFieldWgsl, sceneIdPadWgsl } from "./scene-contract"
 import { idApi } from "../id-api"
+import { sceneLightApi } from "../scene-light-api"
 // GPU particles for user effects: a compute step and an instanced quad draw.
 //
 // Its own shader MODULE rather than more source spliced into composite.ts, for
@@ -75,7 +77,9 @@ fn _rzCastLive() -> i32 {
 }
 
 /** How the author's quads combine with the scene. */
-type ParticleBlend = "alpha" | "additive"
+/** `cutout` shades exactly like `alpha`; the difference is entirely in the
+ *  pipeline — depth write on, alpha-to-coverage on. See directives.ts. */
+type ParticleBlend = "alpha" | "additive" | "cutout"
 
 type ParticleSource = {
   /** The author's WGSL verbatim. */
@@ -89,8 +93,23 @@ type ParticleSource = {
    *  rule reads the same dial the shading does, and rain's fall speed is used
    *  in the compute half. */
   paramsDecl: string
+  /** The effect defines `particleCover(p, uv) -> f32`: the shape alone, cheap.
+   *  A cutout then draws TWICE — coverage to depth first, then the shading at
+   *  depthCompare equal — so the lighting runs only for the visible layer. A
+   *  discard forbids the hardware's own early rejection on a tile-based GPU,
+   *  where every stacked fragment is otherwise shaded in full; the prepass is
+   *  the shape of that rejection, done by hand and cheaply. */
+  cover: boolean
+  /** The side of this effect's grid, or 0 when it declared none. Particles READ
+   *  the grid; the kernel that steps it lives in the grid pass. A blade of grass
+   *  bending where a foot pressed is the whole case: the bend has to persist and
+   *  recover, which is memory, and memory is what the grid is for. */
+  gridSize: number
 }
 
+/** Where the shading stage's five scene-light bindings start — see scene-light-api.ts. */
+export const PARTICLE_LIGHT_BINDING = 10
+
 /** Bytes per particle. Explicitly padded — see the struct below. */
 export const PARTICLE_STRIDE = 48
 
@@ -148,12 +167,14 @@ fn rzProject(p: vec3f) -> vec3f {
 fn rzCamPos() -> vec3f { return cam.camPos; }
 `
 
-/** Does the source define the particle contract? All three are required together. */
-export function particleEntryPoints(wgsl: string): { init: boolean; step: boolean; shade: boolean } {
+/** Does the source define the particle contract? All three are required
+ *  together; `cover` is optional and only means anything to a cutout. */
+export function particleEntryPoints(wgsl: string): { init: boolean; step: boolean; shade: boolean; cover: boolean } {
   return {
     init: /\bfn\s+particleInit\s*\(/.test(wgsl),
     step: /\bfn\s+particleStep\s*\(/.test(wgsl),
     shade: /\bfn\s+particleShade\s*\(/.test(wgsl),
+    cover: /\bfn\s+particleCover\s*\(/.test(wgsl),
   }
 }
 
@@ -182,10 +203,15 @@ ${src.paramsDecl}
     audioApi(0, 4) +
     midiApi(0, 5) +
     lyricsApi(0, 6) +
+    // Always, even with no grid — then it samples a 1x1 of zeroes. Same reason
+    // composite compiles it unconditionally, plus one this module owns: an
+    // effect's whole file is spliced here, so a `gridStep` written for the grid
+    // pass has to RESOLVE here too, and the stubs that let it are in here.
+    gridReadApi(0, 8, 9, src.gridSize) +
     PRELUDE +
     // Stubbed: this module cannot read an attachment the scene pass writes — see
     // id-api.ts. The author's whole file compiles here, so the names must exist.
-    idApi(false, 0, 0) + castDistanceStub() +
+    idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) +
     "\n// ── user effect ──\n" +
     src.wgsl +
     /* wgsl */ `
@@ -230,7 +256,13 @@ fn main(@builtin(global_invocation_id) gid: vec3u) {
 export function buildParticleRenderShader(src: ParticleSource, cast: CastLayout): string {
   return (
     `override BLOOM: bool = ${src.bloom ? "true" : "false"};
-override ADDITIVE: bool = ${src.blend === "additive" ? "true" : "false"};\n` +
+override ADDITIVE: bool = ${src.blend === "additive" ? "true" : "false"};
+override CUTOUT: bool = ${src.blend === "cutout" ? "true" : "false"};
+// A cutout with a prepass: the depth is already written and this pass draws at
+// depthCompare equal, so it neither discards nor masks — the depth test IS the
+// coverage, per sample, and a shader with no discard keeps the hardware's
+// early rejection.
+override PREPASSED: bool = ${src.blend === "cutout" && src.cover ? "true" : "false"};\n` +
     PARTICLE_STRUCT_WGSL +
     CAMERA_STRUCT +
     PARTICLE_UNIFORMS +
@@ -245,10 +277,18 @@ ${src.paramsDecl}
     audioApi(0, 4) +
     midiApi(0, 5) +
     lyricsApi(0, 6) +
+    // Always, even with no grid — then it samples a 1x1 of zeroes. Same reason
+    // composite compiles it unconditionally, plus one this module owns: an
+    // effect's whole file is spliced here, so a `gridStep` written for the grid
+    // pass has to RESOLVE here too, and the stubs that let it are in here.
+    gridReadApi(0, 8, 9, src.gridSize) +
     PRELUDE +
     // Stubbed: this module cannot read an attachment the scene pass writes — see
     // id-api.ts. The author's whole file compiles here, so the names must exist.
     idApi(false, 0, 0) + castDistanceStub() +
+    // The sun's shadow and the world's ambient, for real: the shadow pass has
+    // run by the time this draws, inside the scene pass. See scene-light-api.ts.
+    sceneLightApi(true, 0, PARTICLE_LIGHT_BINDING) +
     "\n// ── user effect ──\n" +
     src.wgsl +
     /* wgsl */ `
@@ -301,6 +341,12 @@ fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut
 
 struct FSOut {
   @location(0) color: vec4f,
+  // Which of the pixel's MSAA samples this fragment covers. Alpha-to-coverage
+  // by hand: the hardware kind reads alpha off the first colour target, and
+  // the HDR target is rg11b10, which has no alpha to read. Every particle
+  // writes it; a blended one writes all four, which is what not declaring it
+  // would have meant.
+  @builtin(sample_mask) samples: u32,
   // The scene's aux target: (bloom mask, coverage). Materials write it, so a
   // particle that skipped it would punch a hole in the mask of whatever it drew
   // over.
@@ -328,8 +374,25 @@ fn fs(in: VSOut) -> FSOut {
   c.a *= pu.weight;
   // Weight 0 therefore discards every fragment, so an effect faded out costs
   // nothing past the vertex stage even on the frame the draw is still issued.
-  if (c.a <= 0.0) { discard; }
+  // Not after a prepass: that pass already decided coverage into depth, and
+  // a discard here would cost this pass the early rejection it exists for.
+  if (!PREPASSED && c.a <= 0.0) { discard; }
   var out: FSOut;
+  out.samples = 0xFu;
+  if (PREPASSED) {
+    c.a = 1.0;
+  } else if (CUTOUT) {
+    // Alpha becomes coverage: 0..4 of the pixel's samples, and the fragment is
+    // then opaque wherever it lands. The pattern is turned by pixel position
+    // so a half-covered edge is not the same two samples on every pixel along
+    // it, which is what makes a2c edges look dithered rather than stepped.
+    let n = u32(clamp(c.a, 0.0, 1.0) * 4.0 + 0.5);
+    if (n == 0u) { discard; }
+    let low = (1u << n) - 1u;
+    let turn = (u32(in.clip.x) + u32(in.clip.y)) & 3u;
+    out.samples = ((low << turn) | (low >> (4u - turn))) & 0xFu;
+    c.a = 1.0;
+  }
   // PREMULTIPLIED: the scene's colour target blends with srcFactor \"one\", so a
   // straight-alpha fragment would come out over-bright wherever it is
   // translucent — which is most of a soft particle.
@@ -350,6 +413,30 @@ fn fs(in: VSOut) -> FSOut {
   out.mask = vec4f(mg.x, mg.y, 0.0, c.a);
 ${sceneIdPadWgsl("out")}  return out;
 }
+` +
+    (src.blend === "cutout" && src.cover
+      ? /* wgsl */ `
+/**
+ * The prepass: the shape to depth, nothing to colour. Every output is still
+ * declared — the pipeline takes the colour targets at writeMask 0 — and the
+ * sample mask is exactly what the single-pass cutout would have written, so
+ * the shading pass's equal test lands on the same samples.
+ */
+@fragment
+fn fsDepth(in: VSOut) -> FSOut {
+  let p = particles[in.id];
+  let a = particleCover(p, in.uv) * pu.weight;
+  let n = u32(clamp(a, 0.0, 1.0) * 4.0 + 0.5);
+  if (n == 0u) { discard; }
+  let low = (1u << n) - 1u;
+  let turn = (u32(in.clip.x) + u32(in.clip.y)) & 3u;
+  var out: FSOut;
+  out.samples = ((low << turn) | (low >> (4u - turn))) & 0xFu;
+  out.color = vec4f(0.0);
+  out.mask = vec4f(0.0);
+${sceneIdPadWgsl("out")}  return out;
+}
 `
+      : "")
   )
 }

package/src/shaders/passes/trails.ts

@@ -1,4 +1,5 @@
 import { castDistanceStub } from "./cast-distance"
+import { gridReadApi } from "./grid"
 import { RZ_LIGHT_STRUCT_WGSL } from "../lights"
 import { audioApi } from "../audio-api"
 import { lyricsApi } from "../lyrics-api"
@@ -9,6 +10,7 @@ import { EFFECT_SUBJECT_VEC4S } from "../cast-layout"
 import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api"
 import { sceneIdFieldWgsl, sceneIdPadWgsl } from "./scene-contract"
 import { idApi } from "../id-api"
+import { sceneLightApi } from "../scene-light-api"
 // Ribbons along a bone's recorded path, drawn as geometry.
 //
 // This is the effect the whole geometry path was built for. As a fullscreen
@@ -39,6 +41,9 @@ type TrailSource = {
   /** Additive, like most glowing ribbons, or straight alpha. */
   blend: "alpha" | "additive"
   bloom: boolean
+  /** The side of this effect's grid, or 0 when it declared none. See the note
+   *  on the same field in particles.ts: a ribbon reads the grid, never steps it. */
+  gridSize: number
 }
 
 /**
@@ -291,9 +296,13 @@ fn rzTurnRadius(a: vec3f, b: vec3f, c: vec3f) -> f32 {
     audioApi(0, 4) +
     midiApi(0, 5) +
     lyricsApi(0, 6) +
+    // Always, with or without a grid — and required either way, because an
+    // effect's whole file is spliced here and a `gridStep` written for the grid
+    // pass has to resolve in this module too.
+    gridReadApi(0, 8, 9, src.gridSize) +
     // Stubbed: this module cannot read an attachment the scene pass writes — see
     // id-api.ts. The author's whole file compiles here, so the names must exist.
-    idApi(false, 0, 0) + castDistanceStub() +
+    idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) +
     "\n// ── user effect ──\n" +
     src.wgsl +
     /* wgsl */ `

package/src/shaders/scene-light-api.ts

@@ -0,0 +1,148 @@
+import { SHADOW_CASCADES } from "../shadow-cascades"
+// The scene's own light, as an effect author sees it: the sun's shadow and the
+// world's ambient.
+//
+// A lawn standing in a character's shadow has to darken where the floor under
+// it does, or the figure floats: the ground catcher draws her shadow, and the
+// blades drawn over it hide it. And the shade has to be the SCENE'S shade — her
+// shaded side takes the world's colour, and a lawn shaded by its own guess
+// reads as a patch of different flowers beside her. Both are already computed
+// for the materials every frame; this hands the same lookups to effects.
+//
+// Bound for real in the particle SHADING stage only. That is where geometry an
+// effect draws inside the scene pass is shaded, and the shadow pass has already
+// run by then. Every other module that compiles the author's file gets stubs:
+// rzShadow answers 1, lit, which is what a point with no occlusion information
+// is — the same answer sampleShadow gives outside every cascade — and
+// rzWorldAmbient answers black, no light.
+
+/**
+ * The world's light at a surface facing n — the flat colour, or the installed
+ * HDRI's irradiance (sh[0].w = 1), evaluated from folded SH coefficients (see
+ * ibl.ts for the folding; the shader is a plain polynomial in the normal).
+ *
+ * Written against whichever name the module gives the light uniform, so the
+ * materials, the ground and an effect all evaluate one polynomial.
+ */
+export const worldAmbientWgsl = (u: string) => /* wgsl */ `
+fn rzWorldAmbient(n: vec3f) -> vec3f {
+  if (${u}.sh[0].w < 0.5) { return ${u}.ambientColor.xyz; }
+  let x = n.x;
+  let y = n.y;
+  let z = n.z;
+  let c = ${u}.sh[0].xyz
+    + ${u}.sh[1].xyz * y + ${u}.sh[2].xyz * z + ${u}.sh[3].xyz * x
+    + ${u}.sh[4].xyz * (x * y) + ${u}.sh[5].xyz * (y * z)
+    + ${u}.sh[6].xyz * (3.0 * z * z - 1.0) + ${u}.sh[7].xyz * (x * z)
+    + ${u}.sh[8].xyz * (x * x - y * y);
+  return max(c, vec3f(0.0));
+}
+`
+
+/**
+ * 3×3 PCF over one cascade's map, for a point already in that cascade's NDC.
+ *
+ * Shared with the materials, so an effect's shadow and her own shadow soften
+ * alike. The sampler is linear-filtered, which makes each tap a 2×2 bilinear
+ * compare. Unrolled — Safari's Metal backend doesn't unroll nested shadow
+ * loops reliably. The body expects `ndc` in scope and returns.
+ */
+export const pcf9 = (map: string, ts: string, sampler = "shadowSampler") => /* wgsl */ `
+  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
+  let cmpZ = ndc.z - 0.001;
+  let ts = ${ts};
+  let s00 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(-ts, -ts), cmpZ);
+  let s10 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(0.0, -ts), cmpZ);
+  let s20 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f( ts, -ts), cmpZ);
+  let s01 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(-ts, 0.0), cmpZ);
+  let s11 = textureSampleCompareLevel(${map}, ${sampler}, suv, cmpZ);
+  let s21 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f( ts, 0.0), cmpZ);
+  let s02 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(-ts,  ts), cmpZ);
+  let s12 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f(0.0,  ts), cmpZ);
+  let s22 = textureSampleCompareLevel(${map}, ${sampler}, suv + vec2f( ts,  ts), cmpZ);
+  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);
+`
+
+/** Bindings the real accessors take, from `binding` upward. */
+export const SCENE_LIGHT_API_BINDINGS = 5
+
+/**
+ * `rzShadow(p)`: how much of the sun reaches world point `p` — 1 lit, 0 in a
+ * caster's shadow, soft in between.
+ *
+ * `rzWorldAmbient(n)`: the world's light arriving at a surface facing `n` —
+ * the materials' own ambient, so an effect's shade can match hers.
+ *
+ * With `on`, declares five bindings from `binding`:
+ *   +0 the light uniform (ambient, the sun — direction, and in .w the shadow
+ *      switch — and the HDRI's irradiance)
+ *   +1 the cascade view-projections, then the caster sphere
+ *   +2 the near cascade's map   +3 the far cascade's map
+ *   +4 the comparison sampler
+ *
+ * It takes a POINT and no normal. The materials' sampleShadow also rejects a
+ * surface facing away from the sun, which is right for skin and wrong for a
+ * blade of grass or a petal: those are thin, lit through, and shaded by their
+ * own N·L. The point is nudged toward the sun instead, which lifts a blade's
+ * root off a stage floor that casts into the same map.
+ */
+export function sceneLightApi(on: boolean, group: number, binding: number): string {
+  if (!on) {
+    return /* wgsl */ `
+fn rzShadow(p: vec3f) -> f32 { return 1.0; }
+fn rzWorldAmbient(n: vec3f) -> vec3f { return vec3f(0.0); }
+`
+  }
+  const n = SHADOW_CASCADES.length
+  return /* wgsl */ `
+// The light uniform, as the materials lay it out; lights[0] is the sun.
+struct _RzSceneLight { direction: vec4f, color: vec4f, }
+struct _RzSceneLightU { ambientColor: vec4f, lights: array<_RzSceneLight, 4>, sh: array<vec4f, 9>, }
+// The cascades' matrices, inner to outer, then every caster in one sphere
+// (x, y, z, radius): radius 0 = nothing casts, negative = do not test.
+struct _RzShadowBlock { viewProj: array<mat4x4f, ${n}>, casters: vec4f, }
+@group(${group}) @binding(${binding}) var<uniform> _rzLight: _RzSceneLightU;
+@group(${group}) @binding(${binding + 1}) var<uniform> _rzShadowVP: _RzShadowBlock;
+@group(${group}) @binding(${binding + 2}) var _rzShadowNear: texture_depth_2d;
+@group(${group}) @binding(${binding + 3}) var _rzShadowFar: texture_depth_2d;
+@group(${group}) @binding(${binding + 4}) var _rzShadowCmp: sampler_comparison;
+
+fn _rzShadowNearTaps(ndc: vec3f) -> f32 {
+${pcf9("_rzShadowNear", `1.0 / ${SHADOW_CASCADES[0].mapSize}.0`, "_rzShadowCmp")}
+}
+
+fn _rzShadowFarTaps(ndc: vec3f) -> f32 {
+${pcf9("_rzShadowFar", `1.0 / ${SHADOW_CASCADES[n - 1].mapSize}.0`, "_rzShadowCmp")}
+}
+
+fn rzShadow(p: vec3f) -> f32 {
+  // The scene's one shadow switch, on the sun — see sampleShadow.
+  let castAmt = _rzLight.lights[0].direction.w;
+  if (castAmt <= 0.0) { return 1.0; }
+  let toSun = normalize(-_rzLight.lights[0].direction.xyz);
+  // Can anything cast onto this point at all? The ground's test, for the same
+  // two reasons: most of a lawn is nowhere near her, and a scene with no
+  // models never renders the map, whose untouched zeroes compare as shadowed.
+  let cs = _rzShadowVP.casters;
+  if (cs.w == 0.0) { return 1.0; }
+  if (cs.w > 0.0) {
+    let toCaster = cs.xyz - p;
+    let along = dot(toCaster, toSun);
+    let perp = length(toCaster - toSun * along);
+    if (along <= -cs.w || perp > cs.w) { return 1.0; }
+  }
+  let q = p + toSun * 0.08;
+  let c0 = _rzShadowVP.viewProj[0] * vec4f(q, 1.0);
+  let n0 = c0.xyz / max(c0.w, 1e-6);
+  if (all(abs(n0.xy) < vec2f(0.98)) && n0.z > 0.0 && n0.z < 1.0) {
+    return mix(1.0, _rzShadowNearTaps(n0), castAmt);
+  }
+  let c1 = _rzShadowVP.viewProj[${n - 1}] * vec4f(q, 1.0);
+  let n1 = c1.xyz / max(c1.w, 1e-6);
+  if (all(abs(n1.xy) < vec2f(0.98)) && n1.z > 0.0 && n1.z < 1.0) {
+    return mix(1.0, _rzShadowFarTaps(n1), castAmt);
+  }
+  return 1.0;
+}
+${worldAmbientWgsl("_rzLight")}`
+}