@woosh/meep-engine 3.11.0 → 3.11.2

package/src/shade/renderer/volumetrics/NOTES.md

@@ -1,9 +1,691 @@
-* https://shaderbits.com/blog/creating-volumetric-ray-marcher
-* "Physically Based and Unified Volumetric Rendering in Frostbite" SIGGRAPH 2015
-* "Creating the Atmospheric World of Red Dead Redemption 2: A Complete and Integrated Solution" SIGGRAPH 2019
-* "Volumetric Fog in Enshrouded" GPC 2024 (https://www.youtube.com/watch?v=OR8HbFnQdlk)
-
-
-
-Check out "A Novel Sampling Algorithm for Fast and Stable Real-Time Volume Rendering" SIGGRAPH 2015
- * https://github.com/huwb/volsample/blob/master/src/shadertoy/clouds.shader
+* https://shaderbits.com/blog/creating-volumetric-ray-marcher
+* "Physically Based and Unified Volumetric Rendering in Frostbite" SIGGRAPH 2015
+* "Creating the Atmospheric World of Red Dead Redemption 2: A Complete and Integrated Solution" SIGGRAPH 2019
+* "Volumetric Fog in Enshrouded" GPC 2024 (https://www.youtube.com/watch?v=OR8HbFnQdlk)
+
+
+
+Check out "A Novel Sampling Algorithm for Fast and Stable Real-Time Volume Rendering" SIGGRAPH 2015
+ * https://github.com/huwb/volsample/blob/master/src/shadertoy/clouds.shader
+## Blue noise for the froxel column jitter — measured, 2026-08-29
+
+Considered as a fix for C-05 (adjacent columns carry independent jitter, so a trilinear XY fetch
+mixes slabs at different depths) and as groundwork for cutting `SAMPLE_COUNT`. Measured against the
+shipped `stbn_vec*.bin` volumes rather than argued. Three findings, one of which kills the original
+rationale.
+
+**Reusing `stbn_vec3` is not an option — it biases, and the bias does not converge away.**
+The aerial pass already reads `stbn_sample_vec3(vec3(voxel_coord.xy, view.frame_index))` and
+consumes all three channels (`.xy` for the tile UV, `.z` for the slice dither). A column jitter
+indexed the same way is *the same number* — correlation 1.0000, not merely "the same set". Two
+nuisance variables locked together stop exploring the unit square and only ever visit its diagonal,
+so the estimator converges to the wrong integral:
+
+| integrand over (j, d) | truth | naive `stbn_vec3.x` converges to | error |
+|---|---|---|---|
+| `j*d`          | 0.250 | 0.334 | +34% |
+| `exp(-3(j+d))` | 0.100 | 0.167 | +67% |
+| `step(j > d)`  | 0.500 | 0.000 | −100% |
+
+RMSE is flat from N=32 to N=128 in every case. That is bias, not noise — no TAA window fixes it.
+
+**An independent source is fine, and converges faster than the hash.** `stbn_vec1` is a separate
+scalar 128×128×64 volume, already loaded by `STATIC_GRAPHICS_ENGINE_ASSETS`, uniform to 0.75%, and
+decorrelated from all three `stbn_vec3` channels (|r| ≤ 0.0018). RMSE on `j*d`: 0.0478 vs the
+murmur hash's 0.0632 at N=8, 0.0149 vs 0.0219 at N=64 — roughly 1.3–1.5× better across the window
+the 0.95 TAA blend actually spans (~39 effective samples). Bias ≤ 0.0025.
+
+Caveat: STBN stops improving past N=64, the volume's temporal depth, while white noise keeps going —
+at N=128 the hash wins. The TAA never reaches that regime, but anything accumulating longer would.
+
+**It does not fix C-05, it makes it slightly worse.** Blue noise is built to make neighbours
+*maximally different*; C-05 wants them *similar*. Measured adjacent-column jitter difference:
+hash 0.3331 (neighbour r = 0.0005, i.e. independent), `stbn_vec1` 0.3656 (neighbour r = −0.112,
+anti-correlated). So it widens the cross-column depth mixing by ~10%.
+
+Conclusion: C-05 stays closed as a documented non-issue — it is zero-mean, the TAA integrates it
+away, and the obvious fix aggravates the stated mechanism. Genuinely removing it means dropping the
+XY jitter (the TAA's 3×3×3 Blackman–Harris resample already does spatial reconstruction), not
+changing the noise source. Adopt `stbn_vec1` when cutting `SAMPLE_COUNT` (P-01), where better
+per-pixel temporal distribution is the actual goal — and never `stbn_vec3`, for the reason above.
+
+## Shadowing the clustered lights — measured, 2026-08-29
+
+Q-01. The point and spot loops in `shader_volumetrics_build_lighting` never applied a shadow map, so
+geometry did not occlude a local light in the volume at all; only the medium's own optical depth
+did. The directional loop always had. Fixed by `chunk_volumetrics_local_light_shadow`, one nearest
+atlas tap per light.
+
+Two things about it were expected to be problems and measured not to be. The numbers below came from
+a `local_light_shadow_mode` word on the metadata that switched between off, that tap, and the
+deferred path's filter kernels; it and the two playground checkboxes over it have since been removed,
+which is why nothing in the tree reproduces these rows any more. Restoring the comparison means
+re-adding that switch.
+
+**The cost is nearly nothing, even at 130 shadow-casting lights.** Whole-frame median over 18
+interleaved rounds in the playground scene at 3840x2160 (the froxel grid is 4x the 1080p one, so
+this magnifies any per-froxel cost by 4x):
+
+| sampling | frame (ms) | vs. off |
+|---|---|---|
+| off | 10.29 | — |
+| one atlas tap (what ships) | 10.42 | +0.13 (+1.2%) |
+| deferred kernels (8 cone taps / 9-gather PCF) | 10.71 | +0.42 (+4.0%) |
+
+Scaled back to 1080p that is +0.03 ms and +0.10 ms, both far below the run-to-run spread. Which
+means the thing P-02 exists to make affordable was already affordable — do not reach for a
+pre-filtered ESM/VSM target on Q-01's behalf. It also means the "skip the shadow test for lights
+whose contribution is negligible" idea has nothing left to buy and would only add a popping risk.
+
+**The cheap tap is not a quality compromise here — it is indistinguishable, and marginally
+quieter.** Under the measurement protocol in the playground README (auto exposure off, 45 frames of
+re-convergence, 32-frame average, noise floor from an identical no-op toggle):
+
+| comparison | signed mean | mean abs |
+|---|---|---|
+| noise floor (mode 1 vs itself) | -0.053 | 1.110 |
+| mode 1 vs off | **-0.852** | 1.826 |
+| mode 2 vs off | **-0.853** | 2.010 |
+| mode 1 vs mode 2 | +0.0004 | 1.439 |
+
+The two paths remove the same light to four decimal places — 0.0004 against a floor of 0.05 — and
+their per-pixel difference sits at the floor. Residual noise after the TAA (mean abs of two settled
+captures of the same setting) is 1.100 off, 1.343 for one tap, 1.381 for the kernels: the 8-tap cone
+is *noisier*, because its taps are drawn stochastically per frame. Repeated with a shadow-casting
+spot light added to the scene: mode 1 vs mode 2 signed mean -0.061, mean abs 1.092, against that
+run's floor of +0.016 / 1.124 — below the floor on both statistics.
+
+So the PCF kernel really was filtering something about to be filtered three more times, and the
+deferred path keeps it for surfaces, where it belongs.
+
+One caveat came out of this, recorded because it bit the spec, and since fixed — though not the way
+it first looked. `shadowmap_sample_point` rounds its taps stochastically from
+`uv * face_size - 0.5`, and an axis-aligned light-to-sample direction encodes to an octahedral uv of
+exactly 0 or 1, so some taps land at texel -1 or `face_size`, one texel outside the rect the record
+publishes. Latent in the deferred path (mode 2), not introduced here; mode 1 clamps and never had it.
+Not an exotic input either: the xy axes are the four edge midpoints of the square and the -Z pole is
+its corner, so a lamp above the floor beneath it overshoots on roughly half its taps.
+
+**That overshoot is provided for, and the first read of this was wrong.** `shadow_point` publishes
+the INNER octahedral surface — `make_octahedral_point_shadow_record` subtracts
+`SHADOWMAP_ATLAS_BORDER` (4) from every side of the slot — and the cube → octahedral remap fills the
+ring around it with `inner[texture_octahedral_wrap_texel_coordinates(local)]`, folding each border
+fragment through the wrap before decoding a direction from it. One texel of overshoot therefore
+reads this light's own wrapped data, four texels inside its slot. Nothing was ever reading a
+neighbouring light, and the `face_size` overshoot was never a defect at all.
+
+What *was* wrong is narrower: the sampler reached the skirt through
+`vec2<u32>(rounded_local_texel) + vec2<u32>(atlas_aabb.xy)`, and `vec2<u32>` of `-1.0` is a
+negative-to-`u32` conversion WGSL leaves indeterminate. Land on `0xFFFFFFFF` and the wrapping add
+gets to `inner - 1`, which is right; land on `0`, equally legal, and the tap silently reads the
+opposite edge of the inner surface. Fixed by doing the add in `i32` — exact for an integral `f32` in
+`[-1, size]`, and the inner origin is at least `SHADOWMAP_ATLAS_BORDER`, so the `u32` at the end is
+defined.
+
+`shadow/map/shader/shadowmap_sample_point_seam.spec.js` builds a synthetic atlas with the skirt the
+remap would have written, and drives the shader under *both* legal readings of that conversion,
+requiring the same answer. That is the assertion that failed before; a checkerboard inner surface
+makes the two readings disagree on every affected tap, because the skirt texel at local `(x, -1)`
+holds `inner[size - 1 - x, 0]`, of opposite parity to `inner[x, 0]`.
+
+Worth knowing if the border is ever revisited: `chunk_shadow2d_pcf_multiple_tap_pcf_contact_hardened`,
+the DPCF disk kernel `SHADOWMAP_ATLAS_BORDER`'s doc names as its reason to exist, is imported by no
+shader — `chunk_shadowmap_sample_point2` replaced it with cone sampling. So the skirt's only current
+reader is that one-texel overshoot, and 8 texels per slot (half of a 16-slot) are otherwise idle.
+Cutting the border is therefore possible but not free: the overshoot needs at least one texel of it.
+
+## Amortizing the sun's optical depth into a light-aligned volume — measured, 2026-08-29
+
+> **Superseded in two places by the last section of this file.** What kept this switched off is not
+> the frustum-clipped medium; the field-of-view measurement that argued it was is confounded, because
+> widening the lens also coarsens the box. And the structure is cascaded now, not a single volume.
+
+Q-04. `integrate_optical_depth` marches 16 steps from every froxel toward every light. For two
+froxels on the same light ray the answers differ by one increment, and the pass recomputes the whole
+integral for each: a prefix sum evaluated as N independent sums.
+`shader_volumetrics_build_sun_shadow_volume` computes it once instead, into a voxel grid whose third
+axis is the sun, and `chunk_volumetrics_sun_optical_depth` reads it back in a single fetch.
+`__VOL_SUN_SHADOW` switches between them. **Off by default**, for the one reason recorded at the end.
+
+### What the literature actually does, including a correction
+
+The report this came from credited both RDR2 and Enshrouded with amortizing the per-froxel march
+into a volumetric shadow representation. Read against the released material, one of those is right
+and the other is not.
+
+**Enshrouded (GPC 2024) is doing exactly this, cascaded.** From the talk: "for rendering shadows …
+we are using 3D volumes in a cascaded fashion and align their z-axis to the direction of the primary
+light source, so in a first pass we would just initialize them with participating media properties
+and in a second pass integrate from the light source down … and that gives us information about how
+much shadowing there is from the fog for any position inside those cascades." And on the shipping
+version: "we're initializing that one in one 3D dispatch and then do a 2D dispatch for each cascade
+in the direction of the light … each cascade as an initial shadow value reads the upper cascade, so
+in the end we can just sample the one cascade and with one sample we get the full shadow volume, and
+the outer cascade is initialized with approximate volumetric shadows for clouds." Same structure,
+same build shape — a 2D dispatch walking columns along the light — with cascades on top and the
+outermost seeded from a cloud approximation. Their fog lives in a world-space voxel grid at 1 m per
+voxel, which is why they do not have the caveat below.
+
+**RDR2 (SIGGRAPH 2019) is not.** It does have a *Shadow Volume* — R16F, one of three volumes in a
+160x88x64 frustum grid, temporally filtered — but the slide and its speaker notes say what it holds:
+"the directional light shadow term sampled from the shadow map cascade as well as cloud and terrain
+shadow map". That is the **shadow map** lookup amortized, not the medium's own optical depth. The
+medium's self-shadowing there is a short secondary sample on cloud material ("we also sample
+extinction towards the sun or moon to generate high frequency shadowing") plus the cloud shadow map,
+which is a light-space ESM built by ray-marching the cloudscape from the light — a genuine
+light-space transmittance structure, but for clouds only. The talk's own Future Outlook slide lists
+**"Volumetric shadows"** as work not done. The review document is corrected accordingly.
+
+Costs from that talk, for calibration, on PS4: cloud ESM 0.156 ms, shadow volume 0.204 ms, material
+volume 0.33 ms, scattering volume 0.34 ms, far-field raymarch 1.31 ms.
+
+**Fourier Opacity Mapping is the famous answer and the wrong one here.** FOM (Jansen & Bavoil, I3D
+2010) projects log-transmittance along each light-space texel onto a truncated Fourier basis. It
+exists because the medium usually arrives as *unordered rasterized particles*, where the only thing
+available is a fixed-size, order-independent, additively blendable summary — and it pays for that
+with ringing at sharp density transitions, which is why Adaptive Volumetric Shadow Maps (Salvi et
+al., EGSR 2010) answer the same problem with a variable-error compressed curve instead. This engine's
+medium is already a 3D texture with a defined order along any axis, so the scan is available, exact
+for the piecewise-constant field a voxel grid *is*, and has nothing to ring. In the shadow-map
+taxonomy what is implemented here is an Opacity Shadow Map (Kim & Neumann 2001) with enough slices
+and hardware trilinear reconstruction that the slice artefacts it is remembered for do not appear.
+
+### The structure, and why it does not swim
+
+A cube in sun space, sized from the camera frustum's **bounding sphere** and snapped to whole voxels.
+Both halves matter and neither is decoration:
+
+- The sphere's radius is a function of `fov`, `aspect`, `near` and `far` only, so the extent does not
+  change when the camera turns. A tight fit of the frustum corners in sun space — which is what this
+  engine's CSM deliberately does, for reasons its own comment gives — would breathe under rotation,
+  moving every voxel centre continuously. The CSM can afford that because it is two orders of
+  magnitude denser and its consumer is a filtered depth comparison; this is neither.
+- With a fixed extent, snapping the origin makes the world-space voxel lattice *the same set of
+  points* every frame. Only the indexing changes. `build_volumetrics_sun_shadow_transform.spec.js`
+  asserts that directly: voxel centres generated for one camera pose land on voxel centres of the
+  grid generated for another, under translation, rotation and both together.
+
+Confirmed on the device, with the volumetric TAA off so nothing could hide a discontinuity. Creeping
+the camera across three voxels of translation, and separately across 20 degrees of yaw, the volume
+path's mean absolute second difference of frame luminance is *lower* than the march's — 0.0140 vs
+0.0165 translating, 0.0051 vs 0.0253 rotating. It does not snap.
+
+Six scripted motions (yaw, pitch, forward, backward, strafe, combined), 90 frames each, at two
+viewpoints, comparing the volume against the march on flicker while moving, on flicker and drift
+while settling, and on the converged image after the motion against the converged image from a
+standing start at the same pose. Every pair agrees to within a few percent; the largest gap in
+"flown vs still" is 0.06 mean luminance against a floor of 0.05. The structure adds no temporal
+instability of its own. `playground/volumetrics_froxel/measure.js` is that harness.
+
+### Cost, from the profiler rather than from frame time
+
+Per pass, `WORKLOAD` capture decoded in the page, 50 frames, two runs each:
+
+| pass | 1920x1080, march -> volume | 3840x2160, march -> volume |
+|---|---|---|
+| build sun shadow volume | 0.003 -> **0.048** | 0.003 -> **0.053** |
+| build lighting | 0.675 -> **0.499** | 1.857 -> **1.274** |
+| net | **-0.13 ms** | **-0.53 ms** |
+
+The whole-frame delta at 2160p is -0.55 ms with disjoint spreads over seven interleaved rounds,
+matching the per-pass sum. At 1080p whole-frame timing could not resolve it at all: the run-to-run
+spread is about +-0.5 ms and three interleaved runs read +0.11, +0.31 and +0.37 — the *wrong sign*.
+The README's advice to attribute cost to passes rather than infer it from frame time earned itself
+here.
+
+The shape is the point. The build is fixed at ~0.05 ms, and the same at 64^3 as at 128^3 — it is not
+where the time goes — while what it removes scales with the froxel count. Double the resolution and
+the saving doubles while the cost does not move.
+
+### Why it is off by default
+
+At seven of the nine playground viewpoints the two paths agree to within about four times the noise
+floor (|signed mean| <= 0.20 against a floor of 0.01-0.09). "Under the island" reads -0.73. **"Inside
+the fog" reads +1.92**, and carries a single **+3.8 pop** around 8 degrees into a yaw, which the
+0.95-blend TAA passes straight through rather than absorbing.
+
+That is not resolution, and the measurement that settles it is the field of view. At that same
+viewpoint, widening to 110 degrees brings the disagreement to -0.05 against a floor of -0.06 — gone —
+while *raising* the volume's resolution does not converge at all (32^3 through 192^3 oscillates
+between +7.0 and -1.9). The pop moves when `__VOL_FROXEL_FAR` moves and does not move with the box's
+snapping: the transform is bit-identical either side of it.
+
+> **Read the next section before trusting the paragraph below.** It calls the march "the converged
+> one", on the strength of `STEP_COUNT = 256` moving it by only -0.24 at *that* viewpoint. That is
+> true there and false in general — sixteen steps step clean over a thin fog slab, and there are
+> viewpoints in this same scene where the march is 58 luminance from its own converged answer while
+> the volume is 29 from it. Which of the two is nearer the truth is a property of the geometry, not
+> of the method.
+
+All of which points at the medium rather than the structure. `tParticipatingMedia1` is hard clipped
+to the camera frustum (Q-05), so the field being scanned has an artificial discontinuity in it. The
+march resolves that edge at its own step size, which is anchored at the froxel and shrinks to nothing
+exactly where the exit is near; a world-space lattice resolves it at a fixed 2.3 units. Where the sun
+ray leaves the frustum within a voxel or two of the froxel — inside dense fog, looking toward a low
+sun — that edge *is* the integral, and the two disagree. Widening the FOV pushes it away and they
+agree again. For a reference: the march at `STEP_COUNT = 256` differs from the shipping 16 by only
+-0.24 mean luminance, so the march is the converged one and the volume is the one in error there.
+
+So the fix is not more voxels and not a smarter fit. It is to stop sampling a frustum-shaped medium —
+build the volume from the scene's participating-media volumes directly, which removes the
+discontinuity, closes Q-05, and is the arrangement Enshrouded has. That is one shader's worth of work
+now that the structure and the measurements exist, and flipping the default is a line.
+
+Cascades are the other half of what Enshrouded ships, and this is shaped to take them: an inner
+cascade's scan starts from the outer cascade's value at its entry face instead of from zero. Worth it
+when the near field needs resolution the uniform grid cannot give — which, on this evidence, is not
+the binding constraint yet.
+
+## The sun volume strobed, and the march was not the reference — measured, 2026-08-29
+
+> **Read the last section of this file for what closed this.** The strobe diagnosis here is right
+> and the fix for it stands. The paragraph at the end proposing temporal accumulation is answered
+> there, and the answer is no; so is the claim that the box is thin in two axes.
+
+Reported from the playground: at a camera parked beside one of the small fog boxes, with the sun
+ahead, `__VOL_SUN_SHADOW = true` made the light pulse. Two poses, both reproducible, both with the
+camera *stationary* — which rules out everything the section above establishes about the box moving,
+since a still camera means a bit-identical transform every frame.
+
+Frame-to-frame mean luminance, 24 frames, camera static:
+
+| | march (16 steps) | volume, 1 sample per voxel |
+|---|---|---|
+| mean | 120.19 | 91.59 |
+| mean absolute frame-to-frame step | 0.0023 | 0.131 |
+| largest single-frame step | 0.004 | **0.623** |
+
+At the second pose the largest step was **1.81**. That is a visible pulse, and the temporal filter
+passes it through rather than absorbing it.
+
+### The march was not the reference, and the earlier note leant on it as if it were
+
+Raising `STEP_COUNT` to 512 to get a converged answer at these poses:
+
+| | pose 1 | pose 2 |
+|---|---|---|
+| march, 16 steps (shipping) | 120.18 | 149.47 |
+| **march, 512 steps** | **62.19** | **79.03** |
+| volume, 128^3, 1 sample per voxel | 91.59 | 119.23 |
+| volume, 256^3 | 63.20 | — |
+
+So at these poses the shipping march is 58 luminance from its own converged answer and the volume is
+29 from it: the amortized path is the *more* accurate of the two, and the resolution sweep that
+looked like divergence — 64^3 giving 120.3, 128^3 giving 91.8, 256^3 giving 63.2 — was convergence
+all along, toward a reference the earlier work never computed at this geometry. It read as
+divergence only because the shipping march was being used as ground truth, and here it is nowhere
+near it.
+
+Worth saying plainly, because it inverts the last paragraph of the section above: **the march at 16
+steps is converged when the medium is thick and spread out, and badly wrong when it is thin.** Its
+step is the distance to the frustum exit over sixteen, which at these poses is about 8 units, and
+the fog box it is meant to find is 3 units thick. It steps over it. A stable wrong answer does not
+strobe, which is the only reason the march looks better on the flicker column.
+
+### Why it strobed, and the fix
+
+The fog box here is 10x3x20 and the camera sits about a third of a unit outside its face. The sun
+travels roughly along -X, so what the ray toward the sun has to cross is the 3-unit dimension — and
+the 128^3 volume's voxel is 2.28 units. Walking the column that passes through the camera and asking
+which lattice points fall inside any scene volume: **two of them.** The entire shadow rested on two
+samples, and the froxel grid's per-frame column jitter moves the medium under both.
+
+The fix is to stop conflating the sampling rate with the storage resolution. A voxel has to hold the
+medium's *integral across its slab*, and one point sample at its centre is not that. The build pass
+now takes four sub-steps per voxel along the sun axis and stores the running integral at the voxel
+centre as before — 0.57-unit sample spacing behind a 2.28-unit voxel, one loop rather than 64x the
+memory:
+
+| | 1 sample/voxel | 4 sub-steps/voxel |
+|---|---|---|
+| pose 1, largest frame step | 0.623 | **0.083** |
+| pose 2, largest frame step | 1.81 | **0.151** |
+| pose 1, mean abs step | 0.131 | 0.020 |
+| pose 2, mean abs step | 0.468 | 0.037 |
+
+Six to thirteen times quieter, and it improves the static disagreement at *Inside the fog* as well,
++1.92 -> +1.30. The cost, per pass at `WORKLOAD`:
+
+| | 1920x1080 | 3840x2160 |
+|---|---|---|
+| build sun shadow volume | 0.008 -> 0.115 | 0.003 -> 0.133 |
+| build lighting | 0.427 -> 0.318 | 1.772 -> 1.068 |
+| net | **~0.00 ms** | **-0.57 ms** |
+
+So the strobe fix spends the 1080p win — it is now a wash there — and keeps the 2160p one. The build
+grew 2.7x rather than 4x, the rest being fixed overhead.
+
+### The switch is gone, and what that costs
+
+Q-04 is approved, so the cascades are the sun's only path and the A/B that measured them has been
+removed: the `__VOL_SUN_SHADOW` global, the playground checkbox over it, and the `sun_shadow_mode`
+word in the metadata, along with the branch in `shader_volumetrics_build_lighting` that read it.
+Same treatment Q-01 got, and it has the same consequence — **nothing in the tree reproduces the
+tables above any more.** Restoring the comparison means re-adding that word and its branch.
+
+Restoring the rest of it means more than that, and it is worth writing down while it is fresh:
+
+* the converged reference needs `STEP_COUNT` in `chunk_integrate_optical_depth` raised to 512;
+* the single-box rows need `VOLUMETRICS_SUN_SHADOW_CASCADE_RATIO` set to 1, which makes the three
+  cascades coincide and the structure exactly one box, built by the same code;
+* the resolution ladder needs `VOLUMETRICS_SUN_SHADOW_RESOLUTION` edited. There was a
+  `__VOL_SUN_SHADOW_RESOLUTION` override for it; it went with the rest, because a global that only
+  exists to A/B a constant is the same thing as the switch and it was inconsistent to keep one
+  without the other — the ratio never had one.
+
+What replaces the mode word is one field rather than two. `sun_shadow_light_index` already said
+which directional light the cascades were built for, so that a second sun degrades to the march
+instead of being shadowed by the first one's boxes; it now also carries
+`VOLUMETRICS_SUN_SHADOW_LIGHT_NONE` for the two cases that can place no box at all — a scene with no
+directional light, and a camera with no field of view to derive a bounding sphere from. The sentinel
+matches no index, so those degrade every directional light the same way. "Not built this frame" is a
+property of the light, not a mode to select, and saying it that way removes the failure mode a mode
+word has: left at zero it selects the march, silently, everywhere.
+
+The build passes still run in those cases, collapsed to one voxel per cascade. Not for measurement
+symmetry any more — that argument went with the A/B — but because the lighting pass binds their
+outputs unconditionally and WebGPU has no optional bindings.
+
+### What is left, and it is not more sub-steps
+
+Sub-stepping fixed the *temporal* aliasing and left most of the *magnitude* gap: pose 1 went 91.59 ->
+92.97 against a reference of 62.19. That is because sub-stepping refines one axis and the fog box is
+thin in two of them — perpendicular to the sun its cross-section is the 3x20 face, so the 3-unit
+dimension is under-sampled laterally as well, and only 256^3, which refines all three, converges.
+Lateral sub-sampling would blur the shadow rather than sharpen it, so that is not the answer either.
+
+The answer is *not* what the first draft of this section said, which was to build the volume from
+the scene's media volumes and integrate each box analytically, "since the chord a sun ray cuts
+through a box has a closed form". That assumes the medium inside a box is uniform, and it is not.
+
+`compute_volume_fade_factor` ramps the density near every face:
+`smoothstep(0, fade_distance, d.x) * smoothstep(0, fade_distance, d.y) * smoothstep(0, fade_distance, d.z)`
+over the world-space distance to each face. So a box's interior is a separable cubic-Hermite ramp,
+and `chord_length * sigma` is wrong by whatever the fade profile does along that chord. The volumes
+overlap too, though that half is harmless on its own — optical depth is additive, so
+`tau = integral of sum(sigma_i) = sum of integral of sigma_i`, and each volume could in principle be
+integrated separately. It is the non-uniformity inside each one that kills it.
+
+And there is a worse problem underneath, which is that **the participating-media pass does not
+discretise a field — it evaluates an estimator**. `compute_volume_fade_factor` takes the *froxel's
+frustum*, intersects it with the box, and samples the fade at the midpoint of that intersection
+segment; `frustum_unit_box_coverage` multisamples the froxel/box overlap to get a coverage fraction.
+Both answers depend on the shape of the froxel, not only on where it is. There is therefore no
+`sigma(x)` that the PM grid is sampling and that something else could integrate exactly: an analytic
+sun-volume build would be computing a different quantity from the one the froxel grid holds, and the
+two would disagree by construction, everywhere, for a reason no measurement would attribute
+correctly.
+
+`ParticipatingMediaVolume` also carries `noise_scale`, `noise_amplitude` and `noise_evolution_speed`.
+They are not in `PARTICIPATING_MEDIA_VOLUME_STRUCT`, so nothing reaches the GPU and no noise is
+applied today — but the data model plainly intends it, and an analytic scheme would die the day it is
+wired.
+
+So: sample the medium, do not try to solve it. What makes that affordable is the one property this
+structure already has and the froxel grid does not — **the world-space voxel lattice does not move**,
+which the transform spec asserts and the device measurements confirm. A lattice that does not move
+can be accumulated in place: one *jittered* sample per voxel per frame, a ping-pong pair of volumes,
+and a blend. No reprojection, because there is nothing to reproject; the effective sample count grows
+with the frame count instead of with the per-frame cost, and it converges on the true cell average of
+whatever the medium turns out to be, fade profiles and noise included. The sub-steps this commit adds
+would then drop back toward one.
+
+It is not free of conditions, and they are the usual ones for anything temporal:
+
+* the lattice is invariant to *camera* motion, not to the sun turning (the basis changes) nor to
+  `fov`/`near`/`far` changing (the extent changes) — both need a reset, and both are rare;
+* a volume that moves or animates needs the accumulation invalidated, which `SceneVolumetrics` can
+  now signal since it gained `invalidate`;
+* it buys accuracy with lag, which is the trade the froxel TAA already makes one pass downstream.
+
+What none of this fixes is the *spatial* resolution of the stored shadow: a three-unit box behind a
+2.3-unit voxel gives a blurry shadow no matter how well each voxel's content is estimated. That is
+what cascades are for, and it is a separate axis from this.
+
+## The sun volume needed cascades, and nothing else would do — measured, 2026-08-29
+
+Q-04, third pass. The section above ends by proposing temporal accumulation, and blames the
+frustum-clipped medium (Q-05) for the disagreement that kept the structure switched off. Both are
+wrong, and the measurements that show it also show what the structure actually needed. It now ships
+**on by default**, as three cascades.
+
+Everything below is against a converged reference: `chunk_integrate_optical_depth` with `STEP_COUNT`
+raised to 512, rendered by the same code path as the shipping march so the two differ in nothing but
+the step count. 1280x720, auto exposure off, 45 frames of re-convergence and a 32-frame average,
+noise floor from a repeat of the reference inside the same run — the protocol in the playground
+README. Numbers are signed mean luminance against that reference.
+
+### Where the three paths stand
+
+| viewpoint | reference | march, 16 steps | one box, 128^3 | **cascades, 3 x 96^3** |
+|---|---|---|---|---|
+| beside the fog bank, pose 1 | 62.39 | **+58.2** | +30.5 | **-1.13** |
+| beside the fog bank, pose 2 | 79.05 | **+70.5** | +37.6 | **-0.53** |
+| Inside the fog | 114.68 | +0.29 | +1.51 | +0.04 |
+| Fog bank, wide | 110.22 | +0.01 | 0.00 | -0.02 |
+| Under the island | 92.02 | +0.62 | -0.19 | -0.20 |
+| Dead overview | 100.88 | +0.12 | -0.16 | -0.08 |
+
+Floors 0.01 to 0.16. The amortized path is not a cheaper approximation of the march any more. It is
+the accurate one, by a factor of fifty at the two viewpoints where the two disagree at all, and it
+is also the cheaper one.
+
+### The error was resolution, on one axis, and the axis is not the sun's
+
+Isolating axes at pose 1, one box, four sub-steps throughout so the quadrature is held fixed. The
+sun travels along -X at 12 degrees of elevation; the volume's basis puts `u` horizontal and `v`
+within 12 degrees of vertical, and the fog bank is a slab three units thick in world Y.
+
+| grid | lateral voxel (u, v) | sun voxel | signed |
+|---|---|---|---|
+| `[128,128,128]` | 2.28, 2.28 | 2.28 | +30.5 |
+| `[128,128,256]` — sun axis x2 | 2.28, 2.28 | 1.14 | +30.3 |
+| `[256,128,128]` — u x2 | 1.14, 2.28 | 2.28 | +30.9 |
+| **`[128,256,128]` — v x2** | 2.28, **1.14** | 2.28 | **+6.1** |
+| `[128,512,128]` — v x4 | 2.28, 0.57 | 2.28 | +4.8 |
+| `[256,256,128]` | 1.14, 1.14 | 2.28 | +3.5 |
+
+Doubling the sun axis buys nothing. Doubling the *one* lateral axis that runs across the slab's
+three-unit dimension removes 80% of the error. That is a Nyquist threshold and it sits where one
+would predict: 1.52 units (a `[192,192,*]` grid) still reads +21.9, and 1.14 units reads +6.1.
+
+So the previous section's account — "it refines one axis and the box is thin in two of them", and
+"only 256^3, which refines all three, converges" — is wrong on both counts. As the sun sees it the
+box is thin in *one* axis, and `[256,256,32]` converges at exactly the memory `[128,128,128]` was
+already spending.
+
+### Prefiltering cannot fix it, and neither can temporal accumulation
+
+This is the measurement that closes the proposal the section above ends on. Replace the single
+lateral sample per sub-step with a 4x4 stratified average over the voxel's lateral footprint —
+sixteen taps, deterministic, and therefore the *converged limit* of any scheme that reaches the same
+cell average stochastically over time. Quadrature held at a constant 0.6 unit spacing.
+
+| | 1 lateral sample | 4x4 lateral |
+|---|---|---|
+| `[128,128,128]`, pose 1 | +30.5 | **+25.1** |
+| `[128,128,128]`, pose 2 | +37.5 | **+29.7** |
+| `[256,256,32]`, pose 1 | +0.35 | +4.09 |
+| `[256,256,32]`, pose 2 | +7.59 | +10.05 |
+
+Sixteen times the sampling recovers 18% of the error, and at a resolution that already resolves the
+medium it makes matters *worse*, because there it blurs a shadow that was resolved. That is what a
+prefilter is for and all it is for: it removes aliasing, not the resolution that was aliased away. A
+box filter preserves the integral of `tau` and lowers its peak, and the froxels that carry the image
+sit at the peak.
+
+**One jittered sample per voxel per frame, accumulated in place, converges on that same 4x4 column.**
+The world-space lattice really does not move — that half of the proposal is sound and its spec still
+asserts it — but what it does not move *toward* is the reference. Temporal accumulation would spend
+a settling window, a reset on every sun rotation and projection change, and an invalidation on every
+moving volume, to arrive at +25.1 instead of +30.5. It is the wrong instrument for this defect. It
+stays the right instrument for the residual per-frame noise, which is a different and much smaller
+problem — the stability table below puts that noise at 0.03 to 0.05.
+
+The literature says the same thing from the other end. Optical depth is *linear* in `sigma`, which is
+why every light-space structure in this family stores it: Fourier Opacity Mapping (Jansen & Bavoil,
+I3D 2010) projects absorption along the ray onto a Fourier basis and exponentiates on read, and its
+own framing is that it is for media whose spatial opacity variations are smooth. Deep Shadow Maps
+(Lokovic & Veach, SIGGRAPH 2000) prefilter in *transmittance* instead, because their medium is hair
+and the sub-texel variation is binary. And averaging the extinction of a heterogeneous medium to
+downsample it is known to be wrong in a specific direction — Zhao et al., "Downsampling Scattering
+Parameters for Rendering Anisotropic Media" (SIGGRAPH Asia 2016), put it as linear downsampling
+weakening the object's intrinsic shadowing structures, which is precisely the +25.1 above.
+
+### And the frustum clip is not what kept it switched off
+
+The section above attributes the *Inside the fog* disagreement to Q-05, on the strength of widening
+the field of view to 110 degrees making it vanish while raising the resolution did not. That
+inference does not hold, because **widening the field of view changes the resolution**: the box is
+sized from the frustum's bounding sphere, whose radius runs 93 units at 40 degrees, 141 at 60, 245
+at 90 and 350 at 110. Opening the lens by a factor of 2.5 coarsens every voxel by the same factor.
+The disagreement went away at 110 degrees because the box happened to land on a size that suited
+that geometry, which the next table makes plain.
+
+### Why no single box could ever have been right
+
+Pose 2, against a converged reference computed at each field of view. The cascade ratio is forced to
+1 so the three cascades coincide and the structure is exactly a single box, built by the same code
+with the same sub-steps — the only variable is the shape.
+
+| field of view | reference | one box 96^3 | one box 128^3 | one box `[256,256,32]` | 3 x 64^3 | **3 x 96^3** | 3 x 128^3 |
+|---|---|---|---|---|---|---|---|
+| 40 deg | 84.96 | **+49.97** | +6.43 | +28.09 | -0.61 | **-1.35** | -1.77 |
+| 60 deg | 79.05 | +5.87 | **+37.68** | +2.47 | +1.01 | **-0.53** | -1.14 |
+| 90 deg | 76.21 | +5.13 | +1.43 | **+38.96** | +1.29 | **+0.32** | -0.41 |
+| 110 deg | 74.94 | **+39.46** | +2.07 | **+39.46** | +5.86 | **+1.77** | +0.13 |
+
+Floor ±0.12 throughout. **Every single-box configuration measured has a field of view at which it is
+28 to 50 luminance from the truth, and which one that is moves with the resolution.** That is not
+tuning, it is arithmetic: the box has to contain the frustum under any rotation, so its side is
+proportional to `far` and to `tan(fov/2)`, while a three-unit fog slab is three units whatever the
+camera is doing. The ratio between what the structure can resolve and what it has to resolve is a
+free parameter of the *camera*, and no constant pins it.
+
+Buying the near field uniformly is not an option either. A 0.28 unit voxel over a 283 unit box is
+1024 per axis: 268 MB.
+
+### Cascades, which is what both shipped references do
+
+Three boxes, each sized from the bounding sphere of the sub-frustum out to `far / 3^(2-i)` — 13.3,
+40 and 120 units at the playground's projection, so 0.34, 1.02 and 3.07 unit voxels at 96 per axis.
+7.1 MB each, 21.2 MB in total, against the 16.8 MB the single 128^3 box was already spending.
+
+Every property the single box had transfers, because each cascade is placed by the same call with a
+different `far`: the extent is a function of the projection alone, so it cannot breathe under
+rotation, and the snapped origin makes each cascade's world-space voxel lattice the same set of
+points from frame to frame. `build_volumetrics_sun_shadow_transform.spec.js` now asserts that per
+cascade, along with the containment the seeding depends on.
+
+Enshrouded (GPC 2024) ships exactly this: "each cascade as an initial shadow value reads the upper
+cascade, so in the end we can just sample the one cascade and with one sample we get the full shadow
+volume". So does Frostbite (SIGGRAPH 2015) one level down the stack — its extinction volume is a
+three-level clip-map and its volumetric shadow maps are 32^3 3D textures storing *transmittance*,
+built at 0.04 ms for a spot light and 0.14 ms for a point light on PS4. Both cascade, and neither
+has this engine's problem of a medium that exists only inside the camera frustum.
+
+Three things about the construction are decisions rather than transcription:
+
+- **The seed is one fetch of the outer cascade at the world position where this column enters this
+  box**, not at the box centre and not a re-march of the approach. Everything between the sun and
+  that plane has already been integrated out there. It is what makes an inner cascade a *refinement*
+  of the outer rather than a truncation of the medium — without it every near-field froxel would be
+  lit as if the fog behind it did not exist, and the volume would still come out perfectly smooth,
+  with the correct slope, and wrong.
+- **A texture per cascade, not one texture with the cascades stacked along w.** Stacking puts a
+  pass's own output and its input in the same texture, which WebGPU rejects: a subresource cannot be
+  bound as writable storage and as a sampled texture at once, and a 3D texture has no subresource
+  finer than the whole thing to split it on.
+- **Selection is on view depth, with a blend band over the last 10% of each cascade's range.** The
+  two cascades do not agree where they meet — one is more accurate, which is the reason there are
+  two — so a hard switch is a ring at a fixed view depth, and the 0.95-blend froxel TAA smears such
+  an edge rather than removing it. Depth also makes the branch uniform: the lighting pass dispatches
+  one froxel slice per workgroup in z, and a slice is a surface of constant depth.
+
+The boxes are **cubic**, and that too is measured rather than assumed. `[256,256,32]` is tempting —
+at 60 degrees it beats `[128,128,128]` by an order of magnitude at identical memory, for the good
+reason that this scene's medium is eight times finer across the sun than along it. The table above
+is what that costs at other fields of view. Two axes, two Nyquist limits, and which one is starved
+is a property of the fog and the sun's elevation rather than of the method.
+
+The sub-step count is per cascade — 4, 2, 2 from the outermost inward — so that the *world-space
+sample spacing* is held constant across cascades rather than the count per voxel. It has to be even:
+the build stores its running integral at sub-step `count / 2`, which is the voxel's centre only when
+the halves are equal, and a count of one stores it at the near face, half a slab of missing shadow
+on whichever cascade drew the short straw.
+
+### Cost
+
+Per pass, `WORKLOAD` capture decoded in the page — `measure.js` grew a `profile` for it, so this no
+longer needs a downloaded `.sgpt` — medians over interleaved rounds at pose 1.
+
+| 1920x1080 | build | build lighting | total |
+|---|---|---|---|
+| march, 16 steps | 0.010 | 0.521 | **0.531** |
+| cascades 3 x 64^3 | 0.120 | 0.282 | **0.422** |
+| cascades 3 x 96^3 | 0.187 | 0.190 | **0.370** |
+
+| 3840x2160 | build | build lighting | total |
+|---|---|---|---|
+| march, 16 steps | 0.011 | 1.503 | **1.515** |
+| cascades 3 x 64^3 | 0.131 | 0.866 | **0.997** |
+| cascades 3 x 96^3 | 0.188 | 0.617 | **0.805** |
+
+The single box with four sub-steps was break-even at 1080p; three cascades are 0.16 ms *ahead* of
+the march there and 0.71 ahead at 2160p. Not a paradox: the build is bound by the length of its
+serial dependency chain rather than by its sample count, so splitting one 128-slice column into
+three 96-slice ones with three times as many columns is a better shape for the machine even at 1.7x
+the samples. Measured directly on the single box, `[128,128,128]` and `[256,256,32]` carry the same
+8.4M samples and cost 0.094 ms and 0.032 ms.
+
+One caveat in those tables. The lighting pass does the same work for 64^3 and 96^3 — one fetch
+either way — and reads 0.282 against 0.190. Every round put 64^3 immediately after the march, so
+read that gap as ordering within the round rather than as a property of the change.
+
+### Temporal stability
+
+Static camera, 24 frames, largest single-frame step in mean luminance:
+
+| | pose 1 | pose 2 | Inside the fog |
+|---|---|---|---|
+| march (512 steps) | 0.012 | 0.011 | 0.004 |
+| cascades 3 x 96^3 | 0.051 | 0.033 | 0.003 |
+| cascades 3 x 64^3 | 0.023 | 0.049 | 0.004 |
+| *one box, one sample per voxel — the reported strobe* | *0.595* | *0.636* | — |
+
+An order of magnitude below the pulse that was reported as visible, and three to four times the
+march's own floor.
+
+Six scripted motions — yaw, pitch, forward, backward, strafe, and all three together — 90 frames of
+motion plus 40 of hold, at two viewpoints, comparing the cascades against the march on flicker while
+moving, on flicker and drift while settling, and on the converged image after the motion against the
+converged image from a standing start at the same pose. At pose 1:
+
+| motion | settling flicker, cascades / march | flown vs still, cascades / march |
+|---|---|---|
+| yaw | 0.011 / 0.008 | +0.056 / +0.004 |
+| pitch | 0.005 / 0.003 | -0.007 / +0.013 |
+| forward | 0.043 / 0.042 | +0.037 / +0.013 |
+| backward | 0.007 / 0.008 | -0.047 / -0.043 |
+| strafe | 0.022 / 0.022 | +0.024 / +0.016 |
+| combined | 0.012 / 0.013 | +0.009 / -0.016 |
+
+At *Inside the fog* the two agree to within 0.01 on every motion and every statistic. The forward
+and backward runs are the ones to look at: they sweep the cascade boundaries eight units through the
+fog, which is the one instability this change could have introduced, and they read identically to
+the march. The **+3.8 pop** the section above reports around 8 degrees into a yaw at that viewpoint
+is gone — the largest single-frame step across that motion is 0.233 for the cascades against 0.235
+for the march.
+
+### What is left
+
+- **Q-05 still stands, and is now the largest defect here.** The medium exists only inside the camera
+  frustum, so fog outside it casts no shadow. Both paths have that, so it appears nowhere in the
+  tables above: every one of them compares two readings of the same clipped medium.
+- A systematic **-1.2 luminance** at the higher resolutions, converging rather than shrinking — 64^3
+  reads -0.32 at pose 1, 96^3 -1.13, 112^3 -1.23. Small, and part of it is the reference's own bias
+  (the march's first sample carries 0.9 of a step's weight), but it is not noise.
+- The cascade count is capped at 4 because the per-cascade scalars are packed into a `vec4f`. Past
+  that the metadata wants a real array, whose uniform-space stride is 16 bytes per `f32`.
+- The build is latency-bound, not bandwidth-bound. If it ever has to be cheaper, the lever is the
+  serial chain — fewer slices per cascade, or a cooperative scan — and not fewer samples.