reze-engine 0.55.0 → 0.55.1

package/src/engine.ts

@@ -2395,6 +2395,33 @@ export class Engine {
     }
   }
 
+  /** Sensor grain: how much, and whether it moves. */
+  private grain = { amount: 0, animated: true }
+
+  /**
+   * Film grain over the rendered scene, 0–1.
+   *
+   * A property of a SENSOR, so it belongs to the camera rather than to any one
+   * subject, and it lands on what the engine drew and on nothing else — never on
+   * a background image or a backdrop video, which arrived with grain of their
+   * own and would be graded rather than matched by a second helping.
+   *
+   * `animated` false freezes it. A still photograph's grain does not move, and
+   * noise crawling over a frozen picture makes the rendering look more alive
+   * than the thing it is standing in.
+   *
+   * Costs one hash per pixel in a pass that already runs, and nothing at all at
+   * zero — the branch is on a uniform.
+   */
+  setFilmGrain(amount: number, animated = true): void {
+    this.grain.amount = Math.min(Math.max(amount, 0), 1)
+    this.grain.animated = animated
+    if (this.device && this.compositeUniformBuffer) this.writeCompositeViewUniforms()
+  }
+  getFilmGrain(): Readonly<{ amount: number; animated: boolean }> {
+    return this.grain
+  }
+
   setViewTransformOptions(patch: Partial<ViewTransformOptions>): void {
     const v = this.viewTransform
     if (patch.exposure !== undefined) v.exposure = patch.exposure
@@ -2436,8 +2463,11 @@ export class Engine {
     // compiler doesn't fold `pow(x, 1/g)` into identity when g=1, so also emit
     // a uniform branch that skips the pow entirely in the common case.
     u[1] = 1.0 / Math.max(v.gamma, 1e-4)
-    u[2] = 0.0
-    u[3] = 0.0
+    u[2] = this.grain.amount
+    // The seed. Zero means STILL: a plate that is one photograph has grain that
+    // does not move, and CG noise crawling over a frozen picture makes the CG
+    // look more alive than the footage — the opposite of the point.
+    u[3] = this.grain.animated ? Math.floor(this.sceneClock * 24) % 1024 : 0
     u[4] = b.color.x
     u[5] = b.color.y
     u[6] = b.color.z
@@ -7580,19 +7610,73 @@ export class Engine {
   // A dedicated camera VMD (target / rotation / distance / fov animated). Motion VMDs loaded
   // via model.loadVmd never touch the camera — the camera shot is opt-in through here.
 
+  /** Whether a loaded camera track is allowed to drive (setCameraVmdEnabled).
+   *  Held separately from `camera.vmdDriven` because that flag now answers to
+   *  two sources, and a track switched off must stay off when the other one
+   *  releases the camera. */
+  private cameraVmdEnabled = true
+  /** A pose pushed in from outside — see setCameraPose. Reapplied every frame,
+   *  so it outranks the orbit AND a loaded track for as long as it is set. */
+  private cameraPoseOverride: CameraPose | null = null
+
+  /** The one place that decides who is holding the camera. An external pose
+   *  wins; a track drives when it is loaded and enabled; otherwise orbit. */
+  private refreshCameraDrive(): void {
+    this.camera.setVmdDriven(
+      this.cameraPoseOverride !== null || (this.cameraVmdEnabled && this.cameraAnimation !== null),
+    )
+  }
+
+  /**
+   * Aim the camera from outside — a solved match-move, a saved shot, a rig
+   * driving the view from the host's own clock.
+   *
+   * The exact partner of `getCameraPose`, and the same five channels: the shot
+   * as MMD states it, roll included. Orbit cannot express roll, so this is the
+   * only way a tilted camera reaches the engine.
+   *
+   * Reapplied every frame while set, which makes it authoritative rather than
+   * advisory — nothing the transport or a loaded track does moves it. Pass null
+   * to release, and whatever was driving before takes the camera back.
+   */
+  setCameraPose(pose: CameraPose | null): void {
+    if (pose) {
+      // Copied, not held: a host reusing one object per frame is the normal
+      // shape of a track, and storing the reference would make the value we
+      // reapply depend on when the caller next touched theirs.
+      this.cameraPoseOverride = {
+        target: new Vec3(pose.target.x, pose.target.y, pose.target.z),
+        rotation: new Vec3(pose.rotation.x, pose.rotation.y, pose.rotation.z),
+        distance: pose.distance,
+        fov: pose.fov,
+      }
+    } else {
+      this.cameraPoseOverride = null
+    }
+    this.refreshCameraDrive()
+    if (this.cameraPoseOverride) this.camera.setVmdPose(this.cameraPoseOverride)
+  }
+
+  /** The pose currently forced from outside, or null when nothing is. */
+  getCameraPoseOverride(): CameraPose | null {
+    return this.cameraPoseOverride
+  }
+
   /** Load a camera VMD (dedicated camera file, or any VMD's camera block) and drive the shot
    *  from it. Default-on once a non-empty track loads; toggle with setCameraVmdEnabled. */
   async loadCameraVmd(url: string): Promise<void> {
     const frames = await VMDLoader.loadCamera(url)
     this.cameraAnimation = frames.length ? new CameraAnimation(frames) : null
-    this.camera.setVmdDriven(this.cameraAnimation !== null)
+    this.cameraVmdEnabled = true
+    this.refreshCameraDrive()
   }
 
   /** Load a camera VMD from an already-fetched buffer (e.g. a File the user dropped). */
   loadCameraVmdFromBuffer(buffer: ArrayBuffer): void {
     const frames = VMDLoader.loadCameraFromBuffer(buffer)
     this.cameraAnimation = frames.length ? new CameraAnimation(frames) : null
-    this.camera.setVmdDriven(this.cameraAnimation !== null)
+    this.cameraVmdEnabled = true
+    this.refreshCameraDrive()
   }
 
   /**
@@ -7610,7 +7694,8 @@ export class Engine {
    */
   loadCameraClip(frames: CameraKeyframe[]): void {
     this.cameraAnimation = frames.length ? new CameraAnimation([...frames]) : null
-    this.camera.setVmdDriven(this.cameraAnimation !== null)
+    this.cameraVmdEnabled = true
+    this.refreshCameraDrive()
   }
 
   /** The loaded camera track as editable keyframes, or [] with none loaded.
@@ -7630,7 +7715,8 @@ export class Engine {
 
   /** Turn the loaded camera VMD on/off (falls back to orbit when off). No-op if none loaded. */
   setCameraVmdEnabled(enabled: boolean): void {
-    this.camera.setVmdDriven(enabled && this.cameraAnimation !== null)
+    this.cameraVmdEnabled = enabled
+    this.refreshCameraDrive()
     if (!enabled && this.cameraTargetModel) {
       // Follow resumes with a clean snap to bone + configured offset — one
       // predictable cut to the scene's framing, no easing from the shot.
@@ -7891,7 +7977,7 @@ export class Engine {
   /** Drop the loaded camera VMD and return to orbit control. */
   clearCameraVmd(): void {
     this.cameraAnimation = null
-    this.camera.setVmdDriven(false)
+    this.refreshCameraDrive()
   }
 
   /**
@@ -7934,6 +8020,29 @@ export class Engine {
     return this.camera.getPosition()
   }
 
+  /**
+   * The live orbit, read in ONE call.
+   *
+   * A host that stores the shot has to be able to ask where the camera actually
+   * IS, because a drag on the canvas moves this and nothing else — and a
+   * document that never asks will happily write back the angle it last set,
+   * discarding whatever the person just did with the mouse. Reading the four
+   * separately invites a torn set across a frame boundary; this cannot tear.
+   *
+   * `target` is the orbit's own centre. While the engine is following a bone
+   * that point rides the bone, so a caller storing a FOLLOW offset must keep its
+   * own and take only the angles from here.
+   */
+  getCameraOrbit(): { alpha: number; beta: number; distance: number; target: Vec3 } {
+    const c = this.camera
+    return {
+      alpha: c.alpha,
+      beta: c.beta,
+      distance: c.radius,
+      target: new Vec3(c.target.x, c.target.y, c.target.z),
+    }
+  }
+
   getCameraDistance(): number {
     return this.camera.radius
   }
@@ -7952,6 +8061,21 @@ export class Engine {
   setCameraBeta(b: number): void {
     this.camera.beta = b
   }
+  /**
+   * Roll the orbiting shot, radians — the lean alpha and beta cannot state.
+   *
+   * Tips the up vector about the eye→target line, so the camera stays exactly
+   * where it was and keeps looking at exactly what it looked at. Everything the
+   * orbit does still works underneath it: following a bone, dragging, zooming.
+   *
+   * A camera VMD carries its own roll and ignores this while it drives.
+   */
+  setCameraRoll(r: number): void {
+    this.camera.roll = r
+  }
+  getCameraRoll(): number {
+    return this.camera.roll
+  }
   /** Vertical field of view in radians (default π/4). While a camera VMD
    *  drives the view it animates fov itself; the orbit value set here is
    *  restored when the VMD releases the camera. */
@@ -8081,6 +8205,16 @@ export class Engine {
     /** Mirror softness, 0–1: 0 a polished mirror, 1 the softest blur level,
      *  scaled by how far the reflected geometry sits behind the surface. */
     mirrorBlur?: number
+    /** How soft the received shadow's edge is, 0–1. 0 (default) is the sharp
+     *  kernel this has always used, to the bit; 1 spreads the taps fourteen
+     *  times as wide, which is the edge an overcast sky throws.
+     *
+     *  A property of the LIGHT, applied where the light is received: the sun
+     *  in a scene is either a point source with a hard edge or a sky with
+     *  none, and a floor that always answers "hard" can only match one of
+     *  them. Above 0 the taps go from nine to sixteen, so leave it at 0 for
+     *  scenes that want the sharp edge and pay nothing. */
+    shadowSoftness?: number
   }): void {
     // NOT YET, OR NEVER AGAIN — same race setAudioData documents. This call is
     // deferred a frame by useSceneSync's own rAF batching, and a hot reload
@@ -8104,6 +8238,7 @@ export class Engine {
       opacity: 1.0,
       mirror: false,
       mirrorBlur: 0,
+      shadowSoftness: 0,
       ...options,
     }
     this.createGroundGeometry(opts.width, opts.height)
@@ -10520,6 +10655,7 @@ export class Engine {
     opacity: number
     mirror: boolean
     mirrorBlur: number
+    shadowSoftness: number
   }) {
     const {
       diffuseColor,
@@ -10534,6 +10670,7 @@ export class Engine {
       opacity,
       mirror,
       mirrorBlur,
+      shadowSoftness,
     } = opts
     // Shadow map is already created in setupPipelines()
     // 20 floats: 16 for the original block, then (mirrorBlur, pad, pad, pad)
@@ -10559,6 +10696,9 @@ export class Engine {
     this.groundMirror = gb[15]
     gb[16] = Math.min(Math.max(mirrorBlur, 0), 1)
     this.groundMirrorBlur = gb[16]
+    // gb[18] — shadow edge softness. Was padding; the shader reads it as the
+    // Vogel disk's radius, and 0 takes the sharp nine-tap path unchanged.
+    gb[18] = Math.min(Math.max(shadowSoftness, 0), 1)
     // gb[17] — does the FAR cascade hold anything?
     //
     // It holds something only when a stage is loaded; that is what it exists for
@@ -11850,13 +11990,62 @@ export class Engine {
   }
 
   // World-space ray from camera through a canvas pixel. Uses WebGPU's NDC z ∈ [0,1].
+  /**
+   * Where a point on the canvas lands on a horizontal plane.
+   *
+   * `px,py` are canvas-relative pixels, top-left origin — what a pointer event
+   * gives you after subtracting the element's rect. Returns null when the ray
+   * cannot reach the plane: parallel to it, or pointing the other way, which is
+   * what a click on the sky above the horizon is.
+   *
+   * The one primitive a placement UI needs. Dragging a thing across the floor is
+   * otherwise three sliders in world units, which asks someone to guess numbers
+   * that have no visible relation to the picture they are looking at — and it
+   * throws away the property that makes pointing work at all: under perspective,
+   * moving something further away makes it smaller by exactly the right amount,
+   * so position and size stop being two controls to tune against each other.
+   */
+  groundPointAt(px: number, py: number, planeY = 0): Vec3 | null {
+    const ray = this.buildMouseRay(px, py)
+    if (!ray) return null
+    // Parallel to the plane: no intersection, and a huge one is not an answer.
+    if (Math.abs(ray.dir.y) < 1e-6) return null
+    const t = (planeY - ray.origin.y) / ray.dir.y
+    // Behind the camera — the plane is there, but not in this shot.
+    if (!(t > 0) || !isFinite(t)) return null
+    return new Vec3(ray.origin.x + ray.dir.x * t, planeY, ray.origin.z + ray.dir.z * t)
+  }
+
+  /** Hand the pointer to something else — a placement drag, a gizmo, a host's own
+   *  overlay — so the orbit does not also act on it. */
+  setCameraInputLocked(locked: boolean): void {
+    this.camera?.setInputLocked(locked)
+  }
+
   private buildMouseRay(px: number, py: number): { origin: Vec3; dir: Vec3 } | null {
     if (!this.camera) return null
     const width = this.canvas.clientWidth
     const height = this.canvas.clientHeight
-    if (width <= 0 || height <= 0) return null
-    const ndcX = (px / width) * 2 - 1
-    const ndcY = -((py / height) * 2 - 1)
+    if (width <= 0 || height <= 0 || this.canvas.width <= 0 || this.canvas.height <= 0) return null
+    // THE PICTURE, NOT THE ELEMENT.
+    //
+    // The projection's aspect comes from the DRAWING BUFFER, while a pointer
+    // arrives in the CSS box — and the two do not have to agree. The canvas is
+    // laid out `object-contain`, so whenever they differ the rendered image sits
+    // letterboxed inside the element with bars either side of it, and dividing
+    // by the element's own size lands the ray somewhere the picture is not.
+    // They disagree on every resize until the observer catches up, and
+    // permanently wherever a host frames the canvas to a shape of its own.
+    //
+    // So: work out where the image actually sits, and take the ray from that.
+    const bufAspect = this.canvas.width / this.canvas.height
+    const boxAspect = width / height
+    const imgW = bufAspect > boxAspect ? width : height * bufAspect
+    const imgH = bufAspect > boxAspect ? width / bufAspect : height
+    const ox = (width - imgW) / 2
+    const oy = (height - imgH) / 2
+    const ndcX = ((px - ox) / imgW) * 2 - 1
+    const ndcY = -(((py - oy) / imgH) * 2 - 1)
     const view = this.camera.getViewMatrix()
     const proj = this.camera.getProjectionMatrix()
     const invVP = proj.multiply(view).inverse()
@@ -12333,8 +12522,13 @@ export class Engine {
       }
     }
 
-    // Drive the shot from the camera VMD (synced to the animated model's clock).
-    if (this.camera.vmdDriven && this.cameraAnimation) {
+    // Who holds the shot this frame. An external pose is a statement about
+    // where the camera IS, so it is reapplied rather than sampled — and it
+    // outranks a loaded track, which is scene data.
+    if (this.cameraPoseOverride) {
+      this.camera.setVmdPose(this.cameraPoseOverride)
+    } else if (this.camera.vmdDriven && this.cameraAnimation) {
+      // Drive the shot from the camera VMD (synced to the animated model's clock).
       const pose = this.cameraAnimation.sample(this.transportTime())
       if (pose) this.camera.setVmdPose(pose)
     }
@@ -13635,6 +13829,12 @@ export class Engine {
       // clock is already per effect, which is the one that actually breaks
       // things (rzGridFrame()==0 is a grid's only chance to seed).
       u[24] = this.sceneClock - (this.effects[0]?.epochScene ?? 0)
+      // The grain's seed rides the same per-frame refresh, because it is the
+      // only thing that makes it move — a seed written once by its setter is a
+      // still pattern welded to the picture. On the SCENE clock like everything
+      // else here, so an export reproduces the editor exactly rather than
+      // scattering differently at whatever rate the encoder ran.
+      u[3] = this.grain.animated ? Math.floor((this.sceneClock * 24) % 1024) : 0
       u[26] = this.canvas.width
       u[27] = this.canvas.height
       // Camera world position (viewU[10]) — the other half of bgWorldPos. It

package/src/shaders/passes/composite.ts

@@ -138,7 +138,7 @@ override APPLY_GAMMA: bool = true;
 // monotone-cubic (Fritsch–Carlson) fit through the same 14 anchors — same values, C1
 // continuity kills the banding — sampled with hardware linear filtering.
 @group(0) @binding(5) var filmicLut: texture_2d<f32>;
-// viewU[0] = (exposure, invGamma, _, _);  viewU[1] = (tint.rgb, intensity)
+// viewU[0] = (exposure, invGamma, grain amount, grain seed);  viewU[1] = (tint.rgb, intensity)
 // viewU[2] = (background.rgb, mode) — display-space sRGB, composited UNDER the
 //            scene post-tonemap. BASE-layer mode: 0 transparent (DOM shows),
 //            1 solid color, 2 = 360 equirect skybox sampled by view ray. A user
@@ -526,6 +526,23 @@ const COMPOSITE_BODY = /* wgsl */ `
   if (APPLY_GAMMA) {
     disp = pow(disp, vec3f(viewU[0].y));
   }
+  // ── Film grain, on the SCENE ONLY ─────────────────────────────────────────
+  //
+  // Applied here, before the background is composited under, so it rides on what
+  // the engine drew and nothing else. That placement is the whole point when the
+  // background is footage: the plate came off a real sensor and already carries
+  // its own grain, and a second helping over the top would grade the photograph
+  // rather than match it. A clean CG figure on a grainy plate is one of the
+  // loudest tells there is — the noise gives it away long before the geometry.
+  //
+  // Multiplicative and weighted toward the mid-tones, which is how film behaves:
+  // little grain in the blacks, and the highlights clip it off.
+  if (viewU[0].z > 0.0) {
+    let gp = fragCoord.xy + vec2f(viewU[0].w, viewU[0].w * 1.7);
+    let gn = fract(sin(dot(gp, vec2f(12.9898, 78.233))) * 43758.5453) - 0.5;
+    let glum = dot(disp, vec3f(0.2126, 0.7152, 0.0722));
+    disp = max(disp * (1.0 + gn * viewU[0].z * 4.0 * glum * (1.0 - glum)), vec3f(0.0));
+  }
   // Composite over the background in display space (premultiplied out). The
   // background is TWO layers: a base (transparent / solid color / 360 equirect)
   // and an optional user WGSL effect over-composited onto it.

package/src/shaders/passes/ground.ts

@@ -10,6 +10,61 @@ import { WORLD_AMBIENT_WGSL } from "../lights"
 // the struct this returns depends on what the probe at init found, and a string
 // baked at import time cannot know that. Called once, when the module is built.
 
+// How far the softest setting spreads the taps, in units of the sharp kernel's
+// own step, and how many taps carry that spread. Sixteen is what keeps a wide
+// disk reading as a penumbra instead of sixteen shadows.
+const SOFT_TAPS = 16
+const SOFT_MAX_SPREAD = 14
+
+/**
+ * PCF taps for one cascade, emitted per shadow map.
+ *
+ * At softness 0 this is the 3x3 box the ground has always used — same offsets,
+ * same weights, same result to the bit. Above it the taps spread over a Vogel
+ * disk whose radius IS the penumbra: an overcast sky throws no edge, and a
+ * razor-edged shadow under one is the loudest thing wrong in a composite.
+ *
+ * The branch is on a uniform, so a scene at softness 0 genuinely takes the
+ * nine-tap side rather than masking the wide one — the same reasoning the
+ * shadowStrength branch above it already documents.
+ *
+ * A string rather than a WGSL function because a texture is the one handle type
+ * this shader has never passed as a parameter, and the file is already a
+ * template that interpolates its constants.
+ *
+ * `acc` must already be declared and zeroed; the caller reads it back
+ * normalised, so there is no `/ 9.0` left at the call site.
+ */
+function pcfWgsl(map: string, uv: string, texel: string, z: string, acc: string, pad: string): string {
+  const golden = 2.39996323
+  return [
+    `if (material.shadowSoftness <= 0.0) {`,
+    `  let st = ${texel} * 2.0;`,
+    `  for (var y = -1; y <= 1; y++) {`,
+    `    for (var x = -1; x <= 1; x++) {`,
+    // ...Level, not the implicit-derivative form: identical on a single-mip
+    // shadow map, and legal inside a branch.
+    `      ${acc} += textureSampleCompareLevel(${map}, shadowSampler, ${uv} + vec2f(f32(x), f32(y)) * st, ${z});`,
+    `    }`,
+    `  }`,
+    `  ${acc} *= ${1 / 9};`,
+    `} else {`,
+    `  let radius = ${texel} * 2.0 * (1.0 + material.shadowSoftness * ${SOFT_MAX_SPREAD}.0);`,
+    `  for (var s = 0; s < ${SOFT_TAPS}; s++) {`,
+    `    let fs = f32(s);`,
+    // sqrt of the index spaces the ring radii evenly by AREA; the golden angle
+    // keeps successive taps from lining up into spokes.
+    `    let r = sqrt((fs + 0.5) * ${1 / SOFT_TAPS});`,
+    `    let a = fs * ${golden} + rot;`,
+    `    ${acc} += textureSampleCompareLevel(${map}, shadowSampler, ${uv} + vec2f(cos(a), sin(a)) * (r * radius), ${z});`,
+    `  }`,
+    `  ${acc} *= ${1 / SOFT_TAPS};`,
+    `}`,
+  ]
+    .map((l) => pad + l)
+    .join("\n")
+}
+
 export function groundShaderWgsl(): string {
   return /* wgsl */ `
 struct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _p: f32, };
@@ -22,7 +77,7 @@ struct GroundShadowMat {
   gridLineColor: vec3f, mirror: f32,
   // farCascade: 1 while a stage is loaded, 0 otherwise. See the branch below —
   // with no stage the far map is never drawn into, so its taps are known.
-  mirrorBlur: f32, farCascade: f32, _mb1: f32, _mb2: f32,
+  mirrorBlur: f32, farCascade: f32, shadowSoftness: f32, _mb2: f32,
   // Every shadow caster in one sphere, refreshed per frame. w = radius; 0 means
   // nothing casts, negative means "do not use this" (a rigid caster has no
   // sphere, so a scene with a stage keeps the taps). See rzShadowPossible.
@@ -152,6 +207,11 @@ ${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
   // The same reasoning the noise tint below already got, applied to the term
   // that costs a hundred times more.
   if (material.shadowStrength > 0.0 && shadowPossible) {
+  // Per-pixel rotation for the soft disk, so its rings break up into fine noise
+  // rather than banding. Interleaved gradient noise: a function of the pixel
+  // alone, so a still camera gives a still shadow — the sharp path ignores it.
+  let ign = fract(52.9829189 * fract(dot(i.position.xy, vec2f(0.06711056, 0.00583715))));
+  let rot = ign * 6.28318530718;
   // The far cascade's taps, skipped entirely when nothing ever drew into it.
   //
   // This branch is the expensive one on a wide floor: it runs wherever the NEAR
@@ -165,32 +225,20 @@ ${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
   if (material.farCascade > 0.0 && frustum < 1.0 && frustum1 > 0.0) {
     let suv1 = vec2f(ndc1.x * 0.5 + 0.5, 0.5 - ndc1.y * 0.5);
     let suv1_c = clamp(suv1, vec2f(0.02), vec2f(0.98));
-    let st1 = ${1 / SHADOW_CASCADES[SHADOW_CASCADES.length - 1].mapSize} * 2.0;
     let compareZ1 = ndc1.z - 0.0035;
     var acc1 = 0.0;
-    for (var y = -1; y <= 1; y++) {
-      for (var x = -1; x <= 1; x++) {
-        acc1 += textureSampleCompareLevel(shadowMapFar, shadowSampler, suv1_c + vec2f(f32(x), f32(y)) * st1, compareZ1);
-      }
-    }
-    vis = mix(1.0, acc1 * (1.0 / 9.0), frustum1);
+${pcfWgsl("shadowMapFar", "suv1_c", `${1 / SHADOW_CASCADES[SHADOW_CASCADES.length - 1].mapSize}`, "compareZ1", "acc1", "    ")}
+    vis = mix(1.0, acc1, frustum1);
   }
   if (frustum > 0.0) {
     let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
     let suv_c = clamp(suv, vec2f(0.02), vec2f(0.98));
-    let st = material.pcfTexel * 2.0;
     let compareZ = ndc.z - 0.0035;
     var acc = 0.0;
-    for (var y = -1; y <= 1; y++) {
-      for (var x = -1; x <= 1; x++) {
-        // ...Level, not the implicit-derivative form: identical on a single-mip
-        // shadow map, and legal inside this branch.
-        acc += textureSampleCompareLevel(shadowMap, shadowSampler, suv_c + vec2f(f32(x), f32(y)) * st, compareZ);
-      }
-    }
+${pcfWgsl("shadowMap", "suv_c", "material.pcfTexel", "compareZ", "acc", "    ")}
     // The base is whatever the far cascade decided, so the near border blends
     // cascade to cascade rather than snapping to lit mid-floor.
-    vis = mix(vis, acc * (1.0 / 9.0), frustum);
+    vis = mix(vis, acc, frustum);
   }
   }