@woosh/meep-engine 3.60.3 → 3.60.5

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

@@ -1,1329 +0,0 @@
-* 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.
-
-## The lighting workgroup, and a premise that did not survive contact — measured, 2026-08-30
-
-S-01. The pass declared `@workgroup_size(16,16)`, dispatched one workgroup per froxel z slice. The
-study's argument for reshaping it: a froxel is `TILE_SIZE` = 8 pixels, so a 16x16 group covers
-128x128 pixels — sixteen separate 32-pixel light clusters — and every lane of a wave can be walking
-a different light list, which is the worst case for the divergent light-record reads in the point
-and spot loops and for shadow atlas tile locality. 4x4 in xy is exactly one cluster tile.
-
-Mean over the build lighting span:
-
-| shape | invocations | clusters spanned | mean |
-|---|---|---|---|
-| 16x16x1 | 256 | 16 in xy | **247 us** |
-| 8x8x1 | 64 | 4 in xy | 368 us |
-| 4x4x4 | 64 | 1 in xy, 4 in z | 386 us |
-
-**The premise was false.** The shape spanning the most clusters is the fastest by 50%, so
-cross-cluster divergence is not what governs this pass's time — cutting the group's cluster
-footprint from sixteen tiles to one made it *slower*, and the xy alignment the whole finding rested
-on bought nothing. Whatever dominates here, it is group size, not light-list coherence.
-
-**Spanning z is separately wrong, and that part holds.** At equal occupancy, 4x4x4 is slower than
-8x8x1. Lights are binned into 3D clusters and the largest distance between neighbouring clusters is
-along depth, so a group that spans z spans the most unrelated light lists — the axis the study
-picked to grow was the one axis to leave alone. The reshape is 2D for the same reason the pass was
-2D to begin with.
-
-Shipping **8x8x1**: 64 invocations, one wave64 or two warps, flat in z. That is 121 us of measured
-cost against the original, paid deliberately, and the reason is **portability**.
-
-Both numbers above were taken on an RTX 4090. Its register file is unusually large, and a 256-invocation
-group winning there says more about that part than about the shape: the wider the group, the more
-registers it needs live at once, and a 4090 has the headroom to keep 256 of them resident where a
-smaller part would drop occupancy instead. AMD hardware in particular does better with smaller
-groups. So 16x16x1's 247 us is a local result, not a general one, and shipping the shape that wins
-on one machine would be tuning the engine to this desk.
-
-Do not read the table as an instruction to put 16x16x1 back. That would need measurements from more
-than one vendor, and it is a different question from the one measured here.
-
-The shape is now `VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION`, read by both the `@workgroup_size` and
-the dispatch, following the sun shadow build. Dead `VOLUMETRICS_WORKGROUP_RESOLUTION` (`[8, 8, 4]`,
-zero importers, matching one pass's literal by coincidence) is deleted.
-
-### Regrouping cannot change the output, and did not
-
-Every invocation computes from `global_invocation_id` alone — no shared memory, no subgroup op, no
-cross-invocation state — so the question reduces to which ids get dispatched. Driven through the
-emulator over both id sets, `tLighting` compared equal byte for byte at grids with a partial group
-on one axis, on all three, and on none, with no voxel left unwritten; coverage at 1080p's 240x135x64
-is exactly once each. That harness was throwaway — it compares against shapes that no longer exist —
-and what stayed is a test pinning `@workgroup_size` to the constant the dispatch divides by.
-
-Two things worth keeping from building its negative controls:
-
-- Under-dispatching fails loudly: a stale divisor drops froxels and the volume comes back holed.
-- **Over-dispatching is invisible.** A `group_count_z` left at the slice count under a 4-deep group
-  still visits every voxel exactly once — `gz * 4 + lz` stays a bijection — so the volume is
-  bit-identical while four times the groups launch to bounds-check and return. Only an assertion
-  about the dispatch being tight catches it.
-
-## Hoisting the local-light shadow test above the march — measured and NOT shipped, 2026-08-30
-
-F-01 and F-03, together, because separately neither is worth doing. Both local-light loops in
-`shader_volumetrics_build_lighting` ran march -> multiscatter -> shadow:
-
-```
-let optical_depth = integrate_optical_depth(shadow_ray);   // up to 16 filtered 3D fetches
-let ms = calculate_multiscattering(...);                   // 6 octaves, pow + exp per octave
-let shadow_term = volumetrics_point_light_shadow(...);     // 1 textureLoad, returns 0 or 1
-inScatteringSum += shadow_term * ms * direct_light.color;
-```
-
-The shadow term is binary by construction — `chunk_volumetrics_local_light_shadow` takes one nearest
-texel with no filter kernel and ends in a `select` between 0.0 and 1.0 — so a zero throws away
-everything above it. Testing it first and `continue`ing on zero skips that work (F-01). And
-`volumetrics_point_light_shadow(database, index, position)` re-read the record
-`get_point_light_info_by_index` had just unmarshalled, *before* its `CASTS_SHADOW_BIT` early-out
-could fire, so the reorder alone would have added a storage read for every non-shadowing light;
-passing the struct instead removes the duplicate and makes the flag test free (F-03).
-
-**The reorder is exact, and that was verified rather than argued.** Both orderings were driven
-through the WGSL emulator over thirteen fixtures — every exit of both loops, plus a case with real
-per-froxel extinction where the old order computed a genuine optical depth and multiscatter and then
-multiplied the pair by zero — and `tLighting` compared **byte for byte**, on the raw bits so that
-`+0`/`-0` and any NaN payload would count as a difference. It is identical everywhere. NaN is the one
-input for which the two are not equivalent (`0 * NaN` propagates, a skipped term does not), so the
-spec fails on any non-finite value in its own right instead of folding it into the comparison.
-
-**It is not faster.** Median of the `Volumetrics / build lighting` span over 18 interleaved rounds at
-3840x2160, ABBA-ordered so neither arm systematically takes the warm half of a round, 48 recorded
-frames per capture after a 40-frame ramp:
-
-| arm | median (ms) |
-|---|---|
-| shadow test first (F-01/F-03) | 1.3573 |
-| march first (shipping) | 1.3471 |
-| **median paired difference** | **+0.0108** |
-
-and the same protocol run with the *same build on both arms*, which is what that number has to beat:
-
-| | median paired difference | median abs difference |
-|---|---|---|
-| A/B, 18 rounds | +0.0108 | 0.0998 |
-| **A/A floor, 10 rounds** | **+0.0092** | 0.0456 |
-
-The measured effect and the noise floor agree to 1.6 us. There is no signal, and the sign is the
-wrong one anyway.
-
-**Why there was nothing to win, which is the part worth keeping.** The local-light loops are not a
-measurable part of this pass in this scene at all. Removing all 130 shadow-casting point lights from
-the playground scene and re-measuring:
-
-| | median (ms) |
-|---|---|
-| 130 shadow-casting point lights | 1.2585 |
-| the same scene with all of them removed | 1.3343 |
-
-Deleting the entire workload the finding proposed to optimize does not make the pass faster — it
-reads a shade slower, which is to say the difference is noise. Whatever the 1.3 ms is spent on, it is
-the per-froxel work outside those loops: the STBN fetch, the two participating-media samples, the
-cluster lookup, and the directional loop's cascade fetch. That also retires the premise the finding
-rested on, the same way S-01's did: 130 shadow-casting lights in the scene does not mean 130 lights
-in the cluster any froxel actually reads.
-
-So this joins Q-01's "the cost is nearly nothing" as a cost claim the profiler refused. Not shipped;
-the tree keeps the march-first order.
-
-What would have to change before it is worth revisiting: a scene where the froxel volume genuinely
-overlaps many clustered lights, shown by that removal test moving the number. Reach for the removal
-test *first* next time — it is three captures and it would have settled this before any code was
-written.
-
-Two things did survive, both about the shipping code rather than the change:
-
-- `shader_volumetrics_build_lighting_local_shadow.spec.js` now covers the exits it did not: a light
-  over an atlas region that was never rendered (`stored == 0`, must not occlude), a froxel behind a
-  spot's apex (`clip_light.w <= 0`), that the optical-depth march still runs and still attenuates
-  when the shadow test passes, and that no NaN or infinity reaches `tLighting` in any fixture. The
-  apex case needs a deliberately inconsistent fixture and says so: in the shipping arrangement a
-  froxel behind the apex is also outside the cone, so the range cull `continue`s before the shadow
-  function is reached, and the branch has to be built rather than found.
-
-- The dev server no longer hot-reloads (`server.hmr: false`). A reload drops the WebGPU device and
-  resets the temporal accumulation, and an edit anywhere in the module graph — including one made by
-  someone else working in the tree at the same time, which is exactly what happened here — destroys
-  an interleaved A/B mid-run.
-
-Measurement conditions, because one of them is unusual: RTX 4090, canvas 1280x720 at pixel ratio 3.
-The pass was confirmed resolution-bound first (0.4618 ms at 1280x720 rising to 1.878 ms at 3840x2160)
-rather than presentation-throttled. Another session was building and running GPU work on the same
-machine throughout, which put occasional 2x outliers in both arms; medians absorb them, and the A/A
-floor was taken under the same conditions so it prices them in.
-
-## The participating-media coverage skip — counted and NOT shipped, 2026-08-30
-
-`shader_volumetrics_build_participating_media` carried a TODO: if a froxel is entirely inside a
-volume, coverage is 1.0 and `frustum_unit_box_coverage` need not run. The TODO proposed getting there
-by replacing `aabb3_intersects_frustum` with something that returns an intersection *degree*.
-
-### The degree answers the other question
-
-`aabb3_intersects_frustum(unit_bounds, local_frustum)` classifies the **volume box** against the
-**froxel's planes**, and `aabb3_intersects_frustum_degree` already returns 0/1/2 for exactly that.
-Its `2` means the box is inside the froxel — the arrangement where the froxel is *larger* than the
-volume, where coverage is a small fraction. Reading it as "coverage is 1.0" would flood the far field
-with fog, which `volumetrics_froxel_containment.spec.js` pins as a test.
-
-What coverage of 1.0 needs is the dual: **froxel ⊆ box**. Both bodies are convex, so it holds exactly
-when the froxel's 8 vertices are inside the box, and `frustum_to_corners` produces the same points
-`frustum_sample_point` reaches at `uvw ∈ {0,1}³` — the sign flips in `plane_convex_intersection`
-cancel, so a plane and its negation give the same corner. The test is exact, not conservative, and
-the same bound gives a second exact skip: if the froxel clears `fade_distance` from every face in
-world units, all three of `compute_volume_fade_factor`'s smoothsteps saturate and the fade is 1.0.
-
-### It is exact and it still loses
-
-Corners cost 8 `plane_convex_intersection` — 3 crosses, a dot and a divide each — which is what
-`frustum_unit_box_coverage` spends on its 4 rays. Deriving them per volume pays for precisely the
-work it skips, so the only arrangement that can win builds them once per froxel in world space and
-maps them into each volume with a matrix multiply.
-
-Hit rates over the playground's six volumes at 240x135x64 (every 4th column in X and Y, every slice
-in Z, froxel extents kept at the true 1/240 and 1/135):
-
-| pose | froxels touching a volume | survivors per froxel | contained | fade saturated |
-|---|---|---|---|---|
-| overview (default) | 100.0% | 1.223 | 7.0% | 3.3% |
-| fog bank, wide | 91.2% | 0.912 | 8.1% | 4.1% |
-| inside the fog | 97.6% | 1.565 | 33.2% | 27.2% |
-
-Per froxel, in three-plane intersections:
-
-| pose | paid | saved | |
-|---|---|---|---|
-| overview | 8.00 | 0.77 | **10.4x loss** |
-| fog bank | 8.00 | 0.67 | **12.0x loss** |
-| inside the fog | 8.00 | 5.00 | **1.6x loss** |
-
-Two refinements do not rescue it. Building the corners **lazily**, on the first volume that survives
-the plane test, saves nothing: the 400x20x400 cloud deck is a huge thin slab that defeats the
-conservative frustum/AABB test almost everywhere, so 91-100% of froxels touch a volume anyway.
-Gating on a **1-intersection necessary condition** — the froxel's own centre must be inside the box,
-or containment is impossible — is very tight (centre-inside is 8.7% against contained's 7.0%) and
-still loses: 2.7x, 2.5x and 1.3x on the three poses.
-
-So the geometry is right and the arithmetic is against it, at every pose measured, including the one
-where a third of froxels qualify. Not shipped. `volumetrics_froxel_containment.spec.js` keeps the
-proof — containment implies coverage of exactly 1.0, and the fade core implies a fade of exactly
-1.0 — alongside `chunk_aabb3_contains_aabb3` and `chunk_aabb3_from_transformed_corners`, so if the
-grid, the volume mix or the estimator's cost moves, restoring the early-out is a few lines rather
-than a rediscovery.
-
-This one was settled by counting rather than by the profiler, which is unusual here. The hit rate is
-a property of the scene's geometry and not of the device, and the cost ratio it implies is 2.5x to
-12x on the two poses that matter — far outside anything a capture would overturn. A GPU A/B is the
-confirmation, not the decision.
-
-### What did ship
-
-The line above the TODO was doing real redundant work. `frustum_transform_m4(froxel_frustum,
-volume.transform_inverse)` derives its plane matrix as `transpose(mat4_inverse(transform))`, so
-handing it `transform_inverse` made it compute `transpose(mat4_inverse(transform_inverse))` — which
-is `transpose(volume.transform)`, a matrix already resident in the struct. Every froxel/volume pair
-was running the 85-line generic cofactor `mat4_inverse` to recover a matrix it had been given: at
-1080p with six volumes, 12.4M of them per frame.
-
-`chunk_frustum_transform_plane_matrix` is that function with the plane matrix passed in, and
-`frustum_transform_m4` is now the wrapper that derives one. The shader calls the former with
-`transpose(volume.transform)`. Strictly less work, and marginally more accurate for dropping an
-inverse round-trip. It is a full 4x4, not a 3x3 normal basis: the last row carries the translation,
-which is what supplies each transformed plane's distance term, and
-`chunk_frustum_transform_plane_matrix.spec.js` asserts both that and the equality with the old route.
-
-`transpose` was missing from the WGSL emulator's language core, which is why `frustum_transform_m4`
-had never been exercised there; it is implemented now for the square matrix sizes, on the same
-footing as `determinant`.
-
-## Volumetric TAA review — 2026-09-02
-
-`taa/shader_volumetrics_taa.js`, reviewed for correctness. Each finding is its own commit, pinned
-by a spec that was red against the old code except where noted. The reprojection and the resolve
-were lifted into pure chunks first so the emulator could execute them.
-
-| item | finding | pin |
-|---|---|---|
-| history fetch | the 3x3x3 Blackman-Harris resample weighted the ±1 neighbours 8.4% each even at a zero offset, so every frame blurred the accumulation and the 0.95 feedback compounded it to ~1.8 froxels of sigma per axis, Z included. Now trilinear through the same sampler the lighting pass uses. | none, by request; validity gate |
-| reprojection | went through the previous camera's jittered VP while the reconstruction used the un-jittered CPU frustum, so a static camera missed its own texel by last frame's jitter. Now the projection diagonal on view-space xy. | a jittered previous camera must round-trip a static froxel exactly |
-| validity | a froxel behind the previous camera has negative w, the divide mirrors NDC back into frame, and the uv check passed. Now depth > 0 as well. | camera backing up past a near froxel |
-| box | the variance band excluded the centre sample whenever gamma < 1, breaking the clip's precondition; both failure paths output the raw sample. Now unioned with the centre. | 26 dark neighbours, a bright centre, the motion-end gamma |
-| resolve | damped the HISTORY to zero on clip, Karis's rule backwards: every clipped voxel output the raw 1-spp sample. Now a fixed 0.95 feedback with the incoming weight damped toward a quarter as the clamp distance reaches one. | impulse moves the resolve by ≤ W_CURRENT·Δ; clipped history kept; wall pull ≤ wide pull |
-| host | camera near/far changes rebuilt the froxel curve without a history reset. Now any change to the built curve resets. | software device, host-written `history_reset` across frames |
-
-Observed, not fixed:
-
-* The last slice (63) does not round-trip to its own texel centre. Its centre depth on the curve
-  exceeds the logical far, the reconstruction clamps it to far, and far maps back to slice 63.0
-  rather than 63.5, so trilinear reads a 50/50 of slices 62 and 63 even when static. The lighting
-  pass truncates that slab at far as well, so its stored content is not centred at 63.5 either.
-  The reprojection spec excludes the last slice from the exact round trip.
-* Box collapse. When all 27 neighbourhood samples miss a thin feature the spatial variance is
-  exactly zero, the box has zero width, and the clip erases everything the history accumulated;
-  it then climbs at 5% a frame and never reaches the mean — about a third of it at 10% coverage.
-  The damping does not touch this either way. It needs a box that knows temporal variance or a
-  width floor, and there is no drop-in for that with high confidence.
-
-## The fog runs only with volumes, and particle lighting left it — measured, 2026-10-09
-
-The whole chain used to run every frame, whatever the scene held. With no volume, it spent this
-integrating a medium that is zero everywhere (volumetrics playground with all six volumes removed,
-1378x746, RTX 4090, one 180-frame `WORKLOAD` capture):
-
-| pass | us |
-|---|---|
-| build sun shadow volume (outermost) | 259 |
-| build sun shadow volume (seeded, two cascades) | 91 |
-| build lighting | 36 |
-| sky transmittance + multi-scatter LUTs | 31 |
-| build scattering lut (aerial) | 29 |
-| build participating media | 23 |
-| volumetric TAA | 19 |
-| GI IBL | 4 |
-| **total** | **~490 of 2,415** |
-
-The sky LUT row was already gone by the time this landed: `3f28049c5` reads the scene sky's two LUTs
-instead of rebuilding them every frame.
-
-Two things held all of it in place, and the frame graph's culling would otherwise have dropped it:
-
-- **The volumetric TAA writes the imported history textures.** That makes it a side-effect pass,
-  which never culls, and it reads everything upstream.
-- **Particle lighting was a by-product of the fog's lighting pass.** The pass also wrote the froxel
-  irradiance volume lit particles read, with every light dimmed by `exp(-optical_depth)` through the
-  medium, so particle lighting needed the media, the sun cascades and the sky LUTs.
-
-So the irradiance has its own pass now (`shader_volumetrics_build_irradiance`): the froxel GI plus
-every light with its shadow, at the same jittered point the fog's lighting pass samples, and no
-medium. A lit particle is lit as the surfaces beside it are, which the deferred and forward paths never dimmed by the medium either, and
-the fog is composited over both. `GPUViewVolumetrics` records the fog only when the scene holds a
-volume; otherwise `resolved` is a 1x1x1 constant, `(0, 0, 0, 1)`, which is what the aerial pass
-integrates to through no medium, and the TAA history is marked stale for when a volume arrives. The
-frame graph culls the irradiance when nothing reads it.
-
-After, from the same kind of capture on the new build. Per-pass times swing by 3-5x between captures
-on this machine (the media build read 46 us and 232 us in two captures of the same scene), so the
-result is which passes run, not a frame-time delta:
-
-- volumetrics playground, volumes removed: **no volumetrics pass at all**;
-- bonfire playground (lit smoke, no volumes): 324 us of volumetrics passes before (16 us of them the
-  sky LUTs), **GI 4 us + irradiance 28 us** after;
-- volumetrics playground with its volumes: every fog pass still runs, and GI does not (nothing there
-  reads the irradiance). Screenshots agree with the old build to a mean |d| of 0.73/255; the same view
-  with and without its fog differs by 11.8.
-
-One behaviour change, deliberate: lit particles inside fog are no longer dimmed by the medium on the
-light's way in. Without fog, particle lighting is what it was: in the bonfire with one 3.5 m lit
-particle behind the fire and a point light 0.25 m in front of it, stepped by hand so both builds see
-the same frames, the new build matches the old to a max |d| of 0 per channel on the raw frame.
-
-**The point stays jittered.** Evaluating the lights at each froxel's centre instead
-(`volumetrics_froxel_centre_ws`, where the GI stage asks) was tried and is wrong: the texels then sit
-on a lattice that never moves, and that same giant particle showed it as a dark hole beside the light
-with a hard edge along a froxel row (mean |d| 2.1/255 against the old build, max 190). The jitter
-moves the lattice every frame so the main TAA can resolve it; `shader_volumetrics_build_irradiance`
-takes its point exactly as the fog's lighting pass does, and a spec pins that a froxel straddling a
-shadow edge is lit in some frames and shadowed in others.
-
-Observed in that same set-up, and not changed here: with the light 0.25 m from the particle, the
-jittered irradiance shows as blotchy 16-pixel blocks around the light even after 420 frames of the
-main TAA, identically on the old build. Nothing filters the irradiance volume in time, and a whole
-froxel flickering together is coherent over more pixels than the TAA's neighbourhood clamp looks at.
-
-## Noise on the volumes — built and measured, 2026-10-15
-
-`VOLUMETRIC_NOISE_PLAN_2026_10_15.md` is the design and the record of how it got there (Smolder,
-Enshrouded 2025 and AC4 read; three revisions; Alex's answers). What landed: a general 3-D tile
-atlas (`texture/atlas/GPUTileAtlas3D`), the volumetrics instance of it on `GPUSceneVolumetrics`
-(`r8unorm`, 128³ content + a one-texel skirt, growing by a layer along z), slot 0 baked on the
-device from three octaves of `psrdnoise3` the first time the scene updates, and a per-volume
-`[0, 1]` multiplier on density — two trilinear taps at most (base, and a warp tap that displaces the
-base lookup), read at a per-froxel STBN-jittered point at a third decorrelation offset `(53, 97)`,
-scrolled by phases the host folds and wraps in f64. The path tracer reads the same function.
-
-**The tile is on the device.** Read back off the atlas through `download_region` in the froxel
-playground (RTX 4090, Chrome, headless): a z slice through the middle of slot 0 spans 0–255 with a
-mean of 125.5 and texels in all eight histogram bins; every skirt texel checked equals the content
-texel it wraps; a row reads 127, 167, 200, 220, …, 253, …, 14 — a continuous field, not a block.
-
-**The picture changes by the noise and nothing else.** `measure.js`'s image `ab` from the "Inside
-the fog" viewpoint at 1080p, the fog bank with `noise_strength` 0 against 1 (16-frame averages after
-45 frames of settling, the floor from a repeat of each side):
-
-| | mean |d| luminance |
-|---|---|
-| floor, off vs off / on vs on | 0.44 / 0.24 |
-| signal, off vs on, twice | 17.0 / 16.7 |
-
-Signed mean +14.9: the fog thins where the tile is below its mean, so more of the lit scene shows.
-
-**What it costs: the taps are below the density pass's timestamp quantum unless the camera is in
-the noisy volume.** Per-pass GPU medians (`profile`, 60 recorded frames an arm, six rounds, the
-two arms interleaved and their order alternated each round, 3796×1852):
-
-| view | `build participating media`, uniform | with noise | frame |
-|---|---|---|---|
-| Dead overview, 2 noisy volumes covering few froxels | 0.2355 (6/6 identical) | 0.2355 (6/6) | 5.062 vs 5.068 |
-| Inside the graveyard fog | 0.2427–0.2437 | 0.2468 (6/6) | 4.619 vs 4.624 |
-| Inside the fog bank, 3 noisy volumes | 0.2642 (6/6) | 0.2703–0.2714 | 5.456 vs 5.466 |
-
-So +0.003 to +0.007 ms on the pass at 2160p with every froxel in front of the camera paying two
-taps, spreads disjoint; the frame totals sit inside their own round-to-round spread (±0.01 ms).
-Lighting, TAA and the LUT read identically in both arms. The whole-frame readings are the usual
-reminder that the pass capture is the number to believe (the README's Q-04 story).
-
-**The uniform path is untouched by construction**, not by measurement: `noise_strength > 0` is a
-per-volume uniform branch around the taps. A zero-volume scene was not re-timed.
-
-Not done on the device: the froxel-versus-tracer parity check for a noisy volume (both paths read
-one function and `chunk_participating_media_noise.spec.js` pins it on the emulator), and the
-giant-particle seam check with a noisy volume (the point is jittered on all three axes exactly as
-the lighting pass's is). Driver and probes: `probe/` in session 2fe0ac92's scratchpad, a one-off.
-
-## The flow map is linked only where the wind field has cascades — measured, 2026-10-16
-
-The noise's flow map (the GPU fluid's volumetrics, `e54461d36`) cost the froxel build 16.4 → 18.3 µs
-in uniform air, a scene with no fluid, where it never runs: a reach of exactly zero takes the one
-tap. The GPU fluid session's breakdown (RTX 4090, 1280×720, camera inside the fog) put it on the code
-being linked, not on running it: without the flow map and the wind sample the shader read 0.1–0.2 µs
-off the old one, and an exact-compare skip, dropping the two taps, or dropping the wind sample, each
-on its own, still cost about 1.8 µs.
-
-So the field's shape is a shader switch, `WIND_FIELD_UNIFORM` (a bool; `false`, the default, is the
-field as it is), decided in two places from one value: `chunk_wind_field_sample` (uniform: return
-`far_velocity`, which the cascaded read returns at every point of a field with no cascades) and
-`chunk_participating_media_noise` (uniform: the one tap at the scrolled lookup, the flow map's value
-at a zero departure). The froxel build picks its variant from the field it binds,
-`scene.wind.cascade_count === 0`, the frame it binds it; the other readers are left at the default.
-`ShaderSwitchSet.with` now remembers the sets it hands out, so deriving the build's set every frame
-allocates nothing (it built two arrays, a key and an assert message a call: 595 B).
-
-**On the device**, the three froxel builds interleaved by blocks of four frames in one capture: the
-pass as built (`new`, the variant it picked), the shader before the flow map (`old`, `ec5f0c093`), and
-master's (`head`, the flow map always linked). Means of ~175 frames an arm a round, µs, three rounds
-each:
-
-| scene | order | new | old | head |
-|---|---|---|---|---|
-| uniform air | new, old, head | 15.89 / 15.71 / 16.28 | 15.80 / 15.65 / 16.27 | 17.32 / 17.17 / 17.80 |
-| uniform air | head, old, new | 14.24 / 14.68 / 14.97 | 14.23 / 14.75 / 15.09 | 15.66 / 16.02 / 16.46 |
-| a domain, a wake, a vortex | head, old, new | 20.13 / 17.05 / 17.05 | 16.76 / 13.98 / 13.87 | 20.18 / 17.17 / 16.79 |
-
-Uniform air is the old cost to within 0.1 µs; disturbed air (the `new` arm on the full variant)
-is master's to within ±0.3 µs either way. TAA, which no arm touches, read alike in every row. The
-labels in the capture confirm which variant the pass picked in each scene.
-
-Every touched shader compiles through Tint on the device and builds a pipeline: both variants of the
-build, the water cull, the fluid query, the accumulating tracer, the Brick4 bake, the LPV trace, both
-lightmap viz bakes. Linked for the default, the seven readers of the wind alone (five particle
-passes, the water cull, the fluid query) are byte-identical to master's WGSL; the six readers of the
-noise differ only by the scroll-and-warp lookup now being one function both alternatives call.
-
-Specs: on the emulator, linked for a uniform field, the multiplier, the multiplier in a wind, the
-density and the wind read what the full variant reads in a field with no cascades, bit for bit (96
-random volumes, three far fields; red against a scrolled alternative that drops the warp and a
-uniform wind of zero). On the software device, the froxel build dispatches the uniform variant in a
-scene with no fluid and the full one when the field has a cascade, judged by the module it was
-handed (red against a pass that never and one that always picks it). Driver: `wfu_*` in session
-f2a32857's scratchpad, a one-off, adapted from the GPU fluid session's `s3g_*`.
-
-## The media build walks its workgroup's volumes, pre-culled by a bin — measured on the iGPU, 2026-10-17
-
-`shader_volumetrics_build_participating_media` walked every volume of the scene from every froxel.
-Each volume cost a plane transform and a six-plane box test even where it was nowhere near the
-froxel, and on a modest GPU that was the pass. On the box's AMD RDNA2 iGPU (2 CUs, headless
-Chrome, `--use-adapter-luid`) at 1898×982, small volumes placed beyond the far plane, where no
-froxel can reach them, cost the build **0.78 ms each**:
-
-| volumes beyond the far plane | 0 | 16 | 64 | 256 |
-|---|---|---|---|---|
-| build participating media (ms) | 7.78 | 20.18 | 57.53 | 207.05 |
-
-Lighting and TAA did not move in any arm (4.0–4.4 and 5.73–5.77 ms).
-
-**Now a bin runs first.** `shader_volumetrics_bin_participating_media` dispatches one 64-lane
-workgroup per workgroup of the build (16×16 froxels × 1 slice). Its lanes take the volumes in
-turn, test each against the group's slab with the build's own rejection
-(`volumetrics_volume_in_slab`), and set the volume's bit in that group's list. The build then walks
-its group's list in row order. There is a list a group, a bit a volume, in a FrameGraph transient
-sized from the scene's volume count and cleared by the graph. A lane of the bin tests ⌈volumes /
-64⌉ volumes, whatever the resolution and however large a volume is.
-
-**The output does not change.** A volume adds to a froxel only where its coverage is above zero,
-and coverage samples points inside the froxel. The group's slab holds every froxel of the group,
-widened a quarter froxel in xy and, in z, by the column jitter's half slice plus a quarter. So a
-volume that adds anything is in the list. The walk is in row order, so the sums add in the order
-they did. `shader_volumetrics_bin_participating_media.spec.js` runs both passes under the emulator
-and compares the build's bits through the bin's lists against lists holding every volume. It is red
-with the z widening cut to the jitter-free quarter slice (1,536 and 24 differing words), and green
-with it.
-
-**The walk has a budget**, `VOLUMETRICS_MEDIA_GROUP_VOLUME_BUDGET` = 32, chosen. Past it a froxel
-drops its group's highest-indexed volumes. Before the bin the loop had no budget at all.
-
-**After**, same driver, same scene, before/after/before/after in separate processes:
-
-| volumes beyond the far plane | 0 | 16 | 64 | 256 | 1,024 |
-|---|---|---|---|---|---|
-| build participating media (ms) | 4.48 | 4.48 | 4.58 | 4.95 | 6.99 |
-| bin participating media (ms) | 0.37 | 0.37 | 0.56 | 1.15 | 3.54 |
-| sum, against before | 4.85 / 7.78 | 4.85 / 20.18 | 5.14 / 57.53 | 6.10 / 207.05 | 10.53 / — |
-
-The two runs of each side agree to 0.01 ms. The scene's own six volumes, with nothing added, go
-from 7.78 to 4.85 ms. The old build was not run at 1,024; at 0.78 ms a volume it would be about
-0.8 s. At 1,024 the build's remaining growth is the list itself: 33 words a froxel to load.
-
-The picture, by the README's protocol (45 frames settled, 16 averaged, block means of 32×32
-pixels): before against after reads a mean |d| of 0.117–0.156 with signed means within ±0.004,
-inside the floor between two processes running the *same* build (0.121 and 0.151).
-
-**A defect this turned up, fixed below.** The build's Y flip negates as well as swapping
-(`planes[2] = -planes[3]; planes[3] = -t`), so its froxel's two Y planes face *out*. The corners
-`frustum_sample_point` builds are unchanged, being intersections, but `aabb3_intersects_frustum`
-on those planes keeps a box only when it spans the froxel's whole row. Measured on the emulator: a
-1×1×1 box at depth 10 covers rows 8.8–11.2 of a 20-row grid and fogs rows 9 and 10 only. The fog
-loses up to a row at every volume's top and bottom edge, and a volume thinner than a row is never
-drawn. The bin slices its slab with the planes facing in (`volumetrics_froxel_planes`: a swap, no
-negation). Inverted planes across a group's 16 rows rejected nearly every volume, and that is how
-it showed. The build keeps its arithmetic, so the output above stays byte-identical. Fixing it
-changes the fog.
-
-**Not covered:** the aerial pass's far field, `far_sample_volumes` in
-`shader_volumetrics_build_scattering_lut`, still walks every volume at every march sample past
-`froxel_far`. With `froxel_far` at its default, the camera's far, that is only each column's last
-step, whose dithered depth can land past it: about one far-field sample a column a frame. The
-playground's `froxel_far` slider below 120 hands the whole tail to the far field, many samples a
-column. Measured in the same runs, at the default, the pass reads 0.40–0.47 ms with the scene's own
-volumes and 2.27 ms with 256 added. In the 1,024 run it reads 9.56 ms.
-
-### The split ahead of the bin: a near field and a far field — measured on the iGPU, 2026-10-17
-
-`shader_volumetrics_split_participating_media` runs before the bin, with one thread per volume.
-It drops a volume outside any of the grid's four side planes or its near plane. Those are the bin's
-planes, widened the same quarter froxel. The plane at `froxel_far` then sorts the rest:
-
-- any part of a volume nearer than `froxel_far` puts it in the near field;
-- any part beyond it puts it in the far field;
-- a volume across it goes in both.
-
-Each field is a list, a count and rows in no particular order, which the split appends to from a
-count of zero. The bin now tests only the near field, and the aerial pass's far field walks the
-far field (see "The aerial pass's far field walks the far-field list" below).
-
-**The near field holds every volume the bin could keep, at the default `froxel_far`.** That
-default is the camera's far, where the bin's last groups end. The emulator spec runs split, bin
-and build together against lists holding every volume, byte for byte. It is red with the
-discriminator at half of `froxel_far`, and its own split cases are red with the far test's
-negation dropped. With `froxel_far` pulled nearer, the grid's last slice still reaches the camera's
-far, because its jittered slab clamps there. A volume wholly between the two now belongs to the
-far field alone and no longer reaches that slice. It had been counted by both until now.
-
-**After**, against master (bin only), master/split/master/split in separate processes, with a third
-master run. Same driver, scene and 1898×982 as the section above, figures in ms:
-
-| volumes beyond the far plane | 0 | 64 | 256 | 1,024 |
-|---|---|---|---|---|
-| split | 0.012–0.014 | 0.020–0.022 | 0.009–0.011 | 0.016–0.018 |
-| bin, master → split | 0.36–0.37 → 0.35 | 0.55–0.56 → 0.35 | 1.14–1.15 → 0.35 | 3.54 → 0.35 |
-| build, master → split | 4.48–4.50 → 4.17–4.18 | 4.57–4.61 → 4.29–4.31 | 4.94–4.98 → 4.69–4.71 | 7.03–7.11 → 6.87–6.95 |
-
-The bin no longer grows with volumes the camera cannot see. The build's code is unchanged, yet it
-reads 0.3 ms less at every count. Its lists are now built from the near field only, which fits
-the split dropping volumes that a group's plane-by-plane test let through. That account is not
-verified.
-
-The picture reads the same. Master against split gives a mean |d| of 0.057–0.164, with signed means
-within ±0.003. Two runs of the same build differ by 0.177 (master) and 0.284 (split). One master
-run read 1.54 against every other run, its own build's included, and is left out.
-
-## The media build's Y planes face in — measured on the emulator and the iGPU, 2026-10-17
-
-The build turned the metadata frustum's Y pair to the grid's rows by swapping and negating. That
-left both of a froxel's Y planes facing out (the defect above). It now takes the pair from
-`volumetrics_froxel_planes`, the same swap the bin slices its slabs with, and both planes face in.
-A plane and its negation meet the other planes at the same points, so the froxel's corners do not
-move. `frustum_sample_point`, the coverage estimate and the fade therefore read exactly what they
-did. Only the box test changes. It now rejects a volume only where the froxel lies wholly outside
-it. Before, it kept a volume only in the rows the volume spanned from top to bottom.
-
-**On the emulator** (`shader_volumetrics_build_participating_media.spec.js`, a 40×20×8 grid, the
-bin spec's camera). Take a box 1 tall and 1 deep, across the whole view at depth 10. It projects
-onto rows 8.73–11.27. With its fade off, a froxel's fog is its coverage alone: the box fogged rows 9
-and 10, and now fogs 8 to 11, the rows it reaches. A box half a row tall across the middle of row 9,
-with the volume's default fade, fogged nothing and now fogs row 9. Both tests were red against the
-old flip (`[9, 10]` and `[]`) and are green. The bin's spec stays green against the corrected
-build: through the bin's lists the build still writes, bit for bit, what it writes with every volume
-listed.
-
-**The fade hides half of what the box test dropped.** A froxel whose centre ray misses the box
-takes the fallback in `compute_volume_fade_factor`, the fade at the froxel's centre. Outside the
-box that is 0. So an edge froxel gets its fog back only when its centre ray reaches into the
-volume, which means only rows the volume covers past their middle. The 1×1×1 box at depth 10 with a
-fade of 0.25 still fogs rows 9 and 10 only: it covers rows 8 and 11 to about a quarter of their
-height, short of their middles. The fallback's comment calls this case "rare if coverage > 0", but
-at a volume's edges it is every froxel whose centre ray misses. Not changed here.
-
-**In the playground, on the iGPU** (headless Chrome, `--use-adapter-luid`, 1898×982, so 119×62
-froxels of 16 px). Both flips ran in one page behind a temporary switch, on the bin as committed at
-`7f09e80b4`, before the split above; the split's spec holds the build's output byte for byte at the
-default `froxel_far`. By the README's protocol at each of the 11 viewpoints: old, new, old, new, each
-after a view change, a 45-frame settle and a 16-frame average. Each floor compares a flip with its own repeat. Mean luminance in 8-bit codes, per
-pixel:
-
-| viewpoint | signed mean, old → new | floor, old / new | mean \|d\|, old → new | floor, old / new |
-|---|---|---|---|---|
-| Dead overview | +0.011, −0.013 | −0.000 / −0.025 | 0.162, 0.160 | 0.213 / 0.214 |
-| Fog bank, wide | +0.001, +0.000 | +0.001 / +0.000 | 0.303, 0.236 | 0.320 / 0.301 |
-| Inside the fog | +0.001, +0.002 | +0.002 / +0.003 | 0.138, 0.137 | 0.163 / 0.163 |
-| Island broadside | −0.007, −0.004 | +0.001 / +0.004 | 0.114, 0.124 | 0.153 / 0.168 |
-| Island from above | −0.008, −0.003 | −0.003 / +0.002 | 0.100, 0.093 | 0.134 / 0.124 |
-| Inside the cloud deck | −0.003, −0.002 | −0.003 / −0.002 | 0.081, 0.081 | 0.093 / 0.093 |
-| Volume edge | −0.007, −0.002 | −0.009 / −0.004 | 0.129, 0.141 | 0.185 / 0.199 |
-| Volume edge, above | −0.003, +0.001 | +0.006 / +0.010 | 0.130, 0.133 | 0.179 / 0.176 |
-| Beside the fog box | −0.003, −0.022 | +0.031 / +0.012 | 0.129, 0.131 | 0.159 / 0.158 |
-| Beside the fog box, deeper | +0.023, +0.023 | −0.013 / −0.013 | 0.126, 0.127 | 0.155 / 0.153 |
-| Under the island | +0.001, +0.002 | +0.011 / +0.013 | 0.129, 0.126 | 0.165 / 0.166 |
-
-On 32×32 block means one block, in *Fog bank, wide*, moved the same way in both pairs by more
-than the largest block move between repeats of one flip: +0.09 and +0.07 against 0.06. No other
-block at any viewpoint did. The one viewpoint whose signed means agree and clear their floors,
-*Beside the fog box, deeper*, moves by 0.023 of a code. **The change is inside the picture's noise
-at every viewpoint.** The six volumes are large on screen and fade over 0.5–7 m, so a row at their
-edge carries little of their density. What the defect hid was fog in volumes that are thin or small
-on screen: one under 16 px tall here never drew at all. The floors span two captures and the
-signals one, so a slow drift (the noise scrolling with the wind) counts double in a floor. That is
-why the signals' mean |d| sits below the floors'.
-
-**Cost: unchanged.** Old against new, alternating which goes first, two rounds a viewpoint: the
-media build reads 3.19–5.62 ms across the viewpoints, and new/old has a median of 0.998 (range
-0.982–1.026). More froxels at a volume's edge now run the coverage estimate, but too few to show.
-
-Driver: `bench/job_flip.js` and `summarize_flip.mjs` in session b5223342's scratchpad, run by the
-bin session's `drive.mjs`.
-
-## The aerial pass's far field walks the far-field list — measured on the iGPU, 2026-10-17
-
-`far_sample_volumes` in `shader_volumetrics_build_scattering_lut` used to walk every volume of the
-scene at each march sample past `froxel_far`. It now walks the split's far field. The list holds
-every volume with some part beyond `froxel_far` and inside the grid's widened side planes. A sample
-on a column's view ray past `froxel_far` lies inside both, so a volume left off the list cannot
-contain it.
-
-The list is in no particular order, so the sums round differently from frame to frame. Alex
-accepted that: the volumetric TAA and the final image's TAA absorb it.
-`shader_volumetrics_build_scattering_lut.far_field.spec.js` pins that the far field adds the
-volumes the list names and no others. It is red against the shader that walked every volume.
-
-Master (the split, the far field unread) against this, in separate processes, at 1898×982, ms:
-
-| aerial pass (`build scattering lut`) | 0 volumes added | 256 | 1,024 |
-|---|---|---|---|
-| `froxel_far` 40 m (camera far 120), master | 0.68–0.75 | 12.87–12.90 | 55.75–56.27 |
-| `froxel_far` 40 m, far-field list | 0.62–0.68 | 1.60–1.63 | 5.86–5.88 |
-| `froxel_far` at its default, master | 0.54 | 2.39 | 10.72 |
-| `froxel_far` at its default, far-field list | 0.63 | 0.69 | 1.13 |
-
-The added volumes are the ones the earlier sections place beyond the far plane in random
-directions. The far field keeps only those inside the view's side planes. At the default the far
-field is reached only by each column's dithered last step, and the pass grew a tenth as fast to
-begin with. One run each at the default: its 0.09 ms at no added volumes is inside the 0.54–0.75
-the pass reads across all runs, and is not shown to be a cost. The media build reads the same in
-every arm.
-
-The picture reads the same. At the default, master against list gives a mean |d| of 0.083 against
-floors of 0.075. At 40 m the pairs give 0.15 and 0.41, against 0.55 between the two runs of the
-list's own build. The first run of the batch read 1.58 against every other run, its own build's
-included, as one master run did in the section above. Both times it was the first run of a batch,
-so it is left out and taken as a property of the driver, not of either build.