@woosh/meep-engine 3.47.0 → 3.49.0

package/src/shade/renderer/shadow/contact/FINDINGS.md

@@ -0,0 +1,413 @@
+# Contact shadows: what fails, and what a careful implementation fixes
+
+Status 2026-10-16: **prototype, not wired into the renderer.** The pass here is a WGSL port of Bend
+Studio's screen-space shadows; the playground `src/shade/playground/contact_shadows/` measures it, and the
+engine's older per-pixel march, against a ray-traced reference, one scene per failure mode. Nothing in the
+default frame changes until the forks at the end are answered.
+
+**In short.** Of the ten ways contact shadows are known to fail:
+
+- **Fixed**, measured:
+  - noise: the pass is deterministic;
+  - disocclusion trails: it keeps no history;
+  - self-shadowing where the sun grazes a receiver: 0.1% false;
+  - the far-field moiré where the view grazes the ground: 14,926 → 358 false px a frame with Bend's own
+    `IgnoreEdgePixels`.
+- **A trade, no fix:**
+  - the thickness window: no value serves both 2 cm poles and 40 cm boxes;
+  - foliage: thinnest of all;
+  - min against multiply: multiply is closer to the sun, min keeps the cascades' softness.
+- **Inherent to screen space:**
+  - view dependence: 11–50% of the gaps closed frame to frame round one orbit;
+  - off-screen casters, bounded by the 60-px reach;
+  - normal-map detail;
+  - shimmer of detail the cascades cannot resolve, under camera motion.
+
+With the cascades, the pass closes 77–79% of the gaps at caster bases for a handful of false pixels, at
+38 µs at 1.27 Mpx on a 4090. With VSM there is a twelfth to a twentieth as much to close, and it adds about
+as much false shadow as it removes.
+
+**Later the same day, Alex chose a per-pixel march, favouring accuracy, on a generic linear trace any
+screen-space feature can use (§6).** At 64 steps it matches the wavefront pass's accuracy against the sun
+summed over the ten scenes, with less false shadow on fine detail, at 3.4× its cost.
+
+## 0. What is here
+
+- `ContactShadowDispatchList.js`: Bend's `BuildDispatchList` (CPU). Up to 8 dispatches of 64-pixel
+  wavefronts converging on the light's point on screen.
+- `chunk_contact_shadow_wavefront_extents.js`, `shader_contact_shadow_wavefront.js`: Bend's
+  `ComputeWavefrontExtents` and `WriteScreenSpaceShadow`. A 64-thread workgroup is one 64-pixel run along a
+  single ray to the light; each thread does 2 reads of 2 depth taps into a 128-word workgroup array and
+  compares 60 of its neighbours' words. **Every thread's work is fixed: 4 texture reads, 60 shared-memory
+  compares,** whatever the scene.
+- `graph_contact_shadow_wavefront.js`: one graph pass, one dispatch per list entry, writing an `r32float`
+  visibility mask (1 lit). `r8unorm` storage needs `texture-formats-tier1`, which the engine takes when
+  offered but does not require.
+- `ContactShadowDispatchList.spec.js`: the real WGSL extents function, under the emulator, against the CPU
+  dispatch list: every pixel of a viewport gets a thread, for lights on screen, off each edge, in a corner,
+  nearly perpendicular to the view, and behind the camera.
+
+### Two holes in Bend's released layout, found by that spec and fixed
+
+1. **The light's own pixel is written by no thread.** Every ring stops one pixel short of the light, so
+   with the light on screen one pixel kept whatever the texture held. The innermost ring's threads now
+   also write it (lit: a ray of no length).
+2. **A light projecting millions of pixels away loses rows to f32 spacing.** Bend clamps w only once the
+   light is ~1M px out; at 9e6 px the spec saw rows unwritten. The CPU now pulls the light's point in to
+   2^20 px from the viewport's centre (f32 spacing 1/8 px there), turning the rays by under 0.1° at
+   1600 px. An overhead sun with a level camera (w = 0, Bend's clamp) projects to 3.5e6 px and was
+   already whole at 1600×900.
+
+## 1. The failure modes, and why they happen
+
+From the primary sources. Paths under `UE_5.4/Engine/` are Epic's installed source; Bend is
+`bend_sss_gpu.h` / `bend_sss_cpu.h` (Sony, Apache 2.0) and the SIGGRAPH 2023 talk's slide text.
+
+| # | Failure mode | Cause | What shipping code does about it |
+|---|---|---|---|
+| 1 | **Heightfield thickness**: thin casters smear, thick ones leak | The depth buffer holds each caster's front and nothing behind it, so every method assumes a slab thickness | Bend: 0.5% of the sample's depth to the far plane (here: in front of the ray by up to 1% of its view depth). UE desktop: ≈ L/2, set by ray length and 8 steps (`ScreenSpaceShadowRayCast.ush:26-32`, `DeferredLightingCommon.ush:63-64`). Filament ≈ 7.5 cm, three.js 1 cm, Bevy 10 cm, all world space. Nobody reconstructs back faces |
+| 2 | **Self-shadowing** where the sun or the view grazes a surface, and on normal-mapped surfaces | A ray leaving a surface at a grazing angle runs along it, so the surface's own neighbouring depths sit just in front of it; depth is quantised per pixel; the shading normal and the depth disagree | Bend: an edge-aware bilinear read across the ray's minor axis, pushing the casting depth back by the step across the pixel; a start bias "suppressed legitimate detail" (talk). UE: skip samples bit-equal to the start depth. Bevy: an open draft (#25355) bends the ray toward the normal. Normal maps are invisible to all of them; Days Gone wrote a ±8 cm material displacement into depth to get that detail |
+| 3 | **View dependence** | Only casters that are on screen and in front cast; the reach is counted in pixels (Bend, Godot, UE screen mode) or the screen reach shrinks with distance (world-space methods) | Bend: "they cannot replace shadow maps, only complement them" (talk). Nothing fixes it |
+| 4 | **Noise and TAA instability** | Jittered starts and few steps (UE 8 steps + IGN over 8 frames, Bevy, three.js, Filament) need TAA to converge; the jittered depth buffer changes what is in it | Bend is deterministic: 4 interleaved min-reductions averaged, 4 hard near samples, an 8-sample fade. Every other source leans on the scene's TAA |
+| 5 | **Disocclusion trails** | Temporal accumulation of a term that changes with the view | No source keeps contact-shadow history; trails are whatever TAA does |
+| 6 | **Screen edges** | Off-screen casters are not in the depth buffer | Bend reads off-screen as the far plane (clamp-to-border); UE treats an off-screen hit as a miss; Filament fades by the ray's end. A fade only hides the pop |
+| 7 | **Scale with distance** | A pixel reach means a world reach growing with depth; a world reach shrinks below a pixel | Bend 60 px fixed; UE screen mode L ∝ depth (`DeferredLightingCommon.ush:162-168`); world-space methods vanish far away |
+| 8 | **Alpha-tested foliage** | Cut-outs alias per texel, cards are millimetres thick, two-sided leaves are their own receivers | Bend's `IgnoreEdgePixels` "can also thin out otherwise valid shadows, especially on foliage edges". UE attenuates subsurface/foliage receivers by 1 − exp(−density·distance) (`DeferredLightingCommon.ush:197-211`) |
+| 9 | **Double darkening** against the shadow map | Multiplying two partial visibilities (a PCF penumbra and a partial contact) is darker than either | UE desktop multiplies (`DeferredLightingCommon.ush:213-216`); UE mobile and Godot take the min; Filament and Bevy multiply but skip pixels the map already shadows fully |
+| 10 | **The light's point on screen** | Rays converge on it, so near it every ray is a few pixels long; Bend widens its window there | Bend: `min(sample_distance + direction, 1/thickness)` in the window scale |
+
+## 2. Measured
+
+RTX 4090, headless Chrome, 1578×802, 2026-10-16. Every number is per frame, averaged over 150 frames at
+1/60 s along the scene's own camera path (the same path from the same start for every arm), classified
+before TAA against a ray traced from each pixel's G-buffer position to the sun's centre ("Counters" in the
+playground README). "Gaps" are pixels the reference shadows and the cascades leave lit; "closed" is the
+share of those the combined term shadows; "added" is false shadow the contact term put where the reference
+and the cascades are both lit. The runs are deterministic: a second campaign reproduced every count.
+
+Arms: **Bend** is the port with Bend's starting values (surface thickness 0.005, edge threshold 0.02,
+contrast 4) multiplied into the cascades' term; the next column turns on Bend's own `IgnoreEdgePixels`.
+**March** is the engine's unwired per-pixel march
+(`deferred/chunk_ss_trace_contact_shadow_soft.js`) given the same 60 samples and the same thickness window.
+
+| Scene | Reference shadowed | Cascade gaps | Bend: closed / added | Bend + `IgnoreEdgePixels`: closed / added | March: closed / added |
+|---|---|---|---|---|---|
+| thickness | 32,686 | 2,141 | 17.1% / 155 | 17.1% / 153 | 11.2% / 186 |
+| grazing | 22,286 | 7,941 | 31.9% / 23 | 28.2% / 6 | 2.8% / 1 |
+| view | 22,953 | 2,523 | 28.6% / 36 | 28.1% / 26 | 20.9% / 19 |
+| noise (fine detail) | 72,090 | 66,943 | 67.7% / 6,992 | 65.0% / 5,525 | 27.1% / 2,387 |
+| disocclusion | 19,305 | 5,013 | 76.6% / 21 | 75.3% / 11 | 4.5% / 1 |
+| screen_edge | 118,831 | 3,071 | 14.2% / 83 | 14.1% / 79 | 13.0% / 125 |
+| distance | 12,296 | 3,383 | 10.2% / 49 | 10.2% / 45 | 2.7% / 5 |
+| foliage | 57,767 | 26,659 | 42.6% / 3,323 | 40.8% / 3,012 | 18.6% / 1,272 |
+| combine | 22,767 | 6,039 | 81.5% / 45 | 79.1% / 22 | 10.1% / 3 |
+| sun_in_view | 19,868 | 2,991 | 36.2% / 14,926 | 35.3% / 358 | 33.8% / 433 |
+
+Taking the min with the cascades instead of multiplying is item 9.
+
+### Verdicts, failure by failure
+
+1. **Heightfield thickness — inherent; the window is a trade with no safe value.** In `thickness`, Bend's
+   window (in front of the ray by up to 1% of its depth) closes 17.1% and smears 155 px behind the thin
+   poles and plank; ¼ of it closes 14.3% and adds 1 px; 4× closes 20.1% and adds 1,193 px. But the same ½
+   window that cleans `foliage` (3,323 → 1,302 px added) drops the movers' closure in `disocclusion` from
+   76.6% to 21.6%: rays pass behind casters thicker than the window and read as lit. One depth layer cannot
+   tell a 2 cm pole from a 40 cm box. Bend's value is kept as the default; it is the trade every caller
+   would make differently.
+2. **Self-shadowing.**
+   - *The sun grazing a receiver* (8°, `grazing`) — **fixed by Bend's design**: 23 false px of 22,286
+     shadowed (0.1%), 6 with `IgnoreEdgePixels`. The edge-aware read across the ray's minor axis and the
+     window's one-sided offset (a sample at the ray's own depth stays lit) carry it; no start bias needed.
+   - *The view grazing a surface* (far ground at the horizon, sun ahead, `sun_in_view`) — **fixed by
+     `IgnoreEdgePixels`**: 14,926 → 358 false px a frame, all of it on ground 16–128 m away, and the
+     contact term's frame-to-frame change 16,957 → 5,552 (the cascades' own: 6,046), for one point of
+     closure. At 50 m one pixel row of ground spans ~1.7 m, past the 2% edge threshold, so the reads are
+     point-sampled and the row half a step nearer falls inside the window: a moiré band. Bend's notes
+     describe exactly this and offer the flag.
+   - *Normal maps* — **inherent**: depth does not carry normal-map detail, so the contact pass neither
+     shadows nor self-shadows from it (`grazing`'s normal-mapped slab). Days Gone wrote a ±8 cm material
+     displacement into depth to get it; that is a G-buffer change, not a shadow-pass one.
+3. **View dependence — inherent.** The share of `view`'s gaps closed swings from 12.7% to 42.1% frame to
+   frame along the orbit; casters hidden by the post cast nothing while hidden.
+4. **Noise and TAA instability — the noise is fixed; motion shimmer on sub-texel detail is inherent.**
+   Bend has no random term (a second campaign reproduced every count). TAA on or off changes nothing
+   before TAA (`noise`: 16,093 vs 15,616 flips), so the jitter is not the driver. But where the contact
+   term carries detail the cascades cannot resolve (`noise`: 2 cm slats, the cascades miss 93% of the
+   shadowed pixels), it changes frame to frame under camera motion far more than the cascades do: 15,616
+   pixels cross ½ a frame against the cascades' 856; summed change 18,568 against 10,788. That is the
+   depth buffer's own sampling of sub-pixel detail moving; only TAA can resolve it, and it costs nothing
+   there to try.
+5. **Disocclusion trails — fixed by construction.** The pass reads this frame's depth and nothing else;
+   it has no history to trail. Around the movers in `disocclusion` it closes 76.6% of the gaps with 21
+   false px. Any ghosting is TAA's, unchanged by the pass.
+6. **Screen edges — inherent.** See the coverage run below.
+7. **Scale with distance — mitigated.** The reach is 60 pixels, so its world length grows with depth, and
+   the thickness window does too. That matches both shadow maps' error, which also grows with depth (see
+   "The budget, derived" below). The far field's real failure was the grazing-view moiré, which
+   `IgnoreEdgePixels` removes (item 2).
+8. **Alpha-tested foliage — mitigated.** Contact shadows close 42.6% of the foliage gaps but add 3,323
+   false px (5.8% of the shadowed pixels): cards a few millimetres thick get the window's 1%-of-depth
+   thickness. `IgnoreEdgePixels` takes it to 3,012, a ½ window to 1,302 (closing 29.4%). It is item 1's
+   trade on the thinnest casters there are.
+9. **Double darkening — real, and against the sun it is the more accurate choice.** Multiplying leaves
+   pixels darker than both terms by over 0.1 (`combine` 978, `noise` 19,873, `foliage` 9,278, with
+   `IgnoreEdgePixels`); the min removes every one. But measured against the ray-traced sun, the multiply is
+   closer in all ten scenes (mean |error| lower or tied: `disocclusion` 0.0047 against 0.0051, `noise`
+   0.0376 against 0.0393, `combine` 0.0041 against 0.0043), and the min gives up closure for it
+   (`disocclusion` 75.3% → 55.5%, `screen_edge` 14.1% → 9.2%) while removing some false shadow (`combine`
+   22 → 14 px). The cascades' 5×5 PCF penumbra is wider than the sun's (0.37°, under a millimetre at a
+   contact), so darkening it toward the contact is mostly darkening toward the truth. The min only wins if
+   the shadow map's softness is the look to keep.
+10. **The light's point on screen.** The widened window near the sun's point did not show as a failure of
+    its own; the far-field moiré in `sun_in_view` (item 2) is what looking toward the sun exposed.
+
+### Against VSM
+
+The same scenes with the virtual shadow map (1 cm first texel), Bend + `IgnoreEdgePixels` + min:
+
+| Scene | Cascade gaps → closed / added | VSM gaps → closed / added |
+|---|---|---|
+| thickness | 2,141 → 15.8% / 142 | 197 → 7.2% / 149 |
+| grazing | 7,941 → 28.0% / 5 | 3,307 → 62.1% / 12 |
+| view | 2,523 → 24.0% / 8 | 336 → 1.6% / 8 |
+| noise | 66,943 → 59.0% / 4,156 | 19,417 → 54.2% / 2,935 |
+| disocclusion | 5,013 → 55.5% / 6 | 251 → 13.1% / 5 |
+| screen_edge | 3,071 → 9.2% / 62 | 357 → 7.3% / 60 |
+| distance | 3,383 → 8.7% / 27 | 166 → 4.7% / 28 |
+| foliage | 26,659 → 36.1% / 2,647 | 9,557 → 16.8% / 2,201 |
+| combine | 6,039 → 77.4% / 14 | 380 → 5.6% / 14 |
+| sun_in_view | 2,991 → 33.2% / 224 | 284 → 23.6% / 303 |
+
+VSM leaves a twelfth to a twentieth of the cascades' gaps at caster bases (`combine`, `disocclusion`,
+`view`, `distance`, `screen_edge`, `thickness`), and there the contact term adds about as much false shadow
+as it closes, or more. It still earns its place in three cases: a sun grazing the receiver (`grazing`: 62%
+of VSM's 3,307 gaps closed for 12 false px), detail finer than the first page (`noise`'s 2 cm slats: 54%),
+and foliage, though there it adds 2,201 false px to close 1,605. Bend's defaults without `IgnoreEdgePixels`
+put the far-field moiré back under VSM too (`sun_in_view`: 14,942 false px).
+
+### The coverage runs
+
+The 150-frame runs at 1/60 s cover only the first 2.5 s of each path. To traverse the pans, the orbit,
+the turn and the dolly, four scenes ran 300 frames at four times the speed:
+
+- **Screen edges — inherent, bounded by the reach.** Through the whole pan, the share of `screen_edge`'s
+  gaps closed swings between 9% and 20% from frame to frame, the same swing as the orbit's. A caster that
+  leaves the screen only takes the contact shadow within 60 px of the edge with it; off-screen reads
+  return the far plane (an explicit bounds check: WebGPU has no clamp-to-border), so nothing false comes
+  from beyond the edge.
+- **View dependence.** Round the full orbit of `view`, Bend closes 11–50% of the gaps by frame and its
+  false shadow spikes to 2,986 px on one frame; with `IgnoreEdgePixels` (and the ½ window) the spike is
+  12 px.
+- **Sun in view.** Facing the sun Bend adds 12,662–25,247 false px a frame, facing away 78–345; with
+  `IgnoreEdgePixels` (and the ½ window) at most 67 throughout.
+
+### The budget, derived
+
+Each thread's reach is its sample count in pixels. Bend's 60 is what their read formula fits in two reads
+of a 64-wide wave (it over-counts: the two reads hold 64 words past each thread). What has to be reached is
+the shadow map's own blur at a caster's base: the cascades filter 5×5 texels (`SHADOWMAP_FILTER_SIZE`), so
+2.5 texels either side of an edge. Measured in `combine`: cascade 0 covers the first 54 m at **4.7 cm a
+texel**, so 12 cm of blur; at 1578×802 and 55° a pixel spans 1.3 mm per metre of depth, so 60 pixels reach
+12 cm at **1.5 m** and more beyond it (7.8 cm × depth in metres, for a light parallel to the image). Nearer
+than 1.5 m the cascades' blur is wider than the reach; further away the reach outgrows it in step with the
+cascades, whose texels also grow with distance (17 cm to 167 m, 42 cm to 400 m). For VSM's 1 cm first
+texel the same 60 px covers its 2.5 cm from 0.3 m. Doubling the reach would take a third read per thread
+(READ_COUNT 3) and buy the 0.75–1.5 m band for cascades only. 60 is kept.
+
+### Defects found on the way, outside this pass
+
+- `shadow/ray/shader_ray_shadow_code.js`, the engine's ray-traced shadow prototype, binds five groups; a
+  device offers four, so it cannot be dispatched. The playground's reference is the same query in three
+  groups. Fixed the same day: it binds three, as the reference does.
+- It also starts its rays with `offset_ray`, which offsets in proportion to |position| (meant for a ray
+  hit's position). On a position rebuilt from depth that leaves the far ground shadowing itself: 180,140
+  shadowed pixels in `combine` against 25,166 with an offset of 3e-5 of the view distance, the onset of a
+  plateau measured from 1e-6 to 1e-3. Fixed the same day: its rays (and the staged generator's) start at
+  `offset_ray_from_depth` (`shader/chunk/geometry/ray/chunk_offset_ray_from_depth.js`), that offset.
+- `deferred/chunk_ss_trace_contact_shadow_soft.js`, the engine's unwired contact chunk, closes 2.7–27% of
+  the gaps where the wavefront pass closes 10–82%, with the same samples and window.
+
+## 3. Cost
+
+GPU time per pass, RTX 4090, 1578×802 (1.27 Mpx), the three methods swapped every 4 frames in ABC CBA
+order inside one profile capture, each block's first frame dropped, 90 frames per arm, camera still. Two
+runs per case; their medians agree to within one timer step (~1 µs). Deferred shading read 66.6–68.6 µs in
+every arm, so the clocks held.
+
+| | Sun off screen (`combine`) | Sun on screen (`sun_in_view`, facing it) |
+|---|---|---|
+| Wavefront pass (Bend) | **37.9 µs** | **32.8 µs** |
+| Per-pixel march (engine chunk) | 73.7 µs | 53.2 µs |
+| Playground composite (scaffolding) | 48.1 µs | 31.7 µs |
+
+About 30 µs per megapixel, so ~62 µs at 1080p and ~250 µs at 4K on this card; Bend report 0.19 ms at
+1440p on PS5. The composite is the price of applying the mask without touching deferred shading: it
+re-evaluates the sun's BRDF and cascade lookup and writes the debug record. Reading the mask inside the
+sun's shadow term instead is one texture load per pixel in a pass already running; it is not measured here
+because it needs the deferred shader changed (fork 3).
+
+## 4. Reuse map
+
+| Piece | Reuses | New |
+|---|---|---|
+| Depth, normals, camera | `ViewTextures`, `GBufferTextures` records; `CAMERA_UNIFORM_STRUCT`; the view's jittered `view_projection_matrix` for the light's screen point | — |
+| Wavefront pass | `ComputeShader`, `CodeChunk`, immediates (`setImmediate`), `graph_prepare_bindings`, the frame graph | the Bend port: dispatch list, extents chunk, kernel |
+| The mask in the sun's term (playground) | `chunk_read_gBuffer_material`, `chunk_shadowmap_get_light_visibility`, `chunk_get_directional_light_info_by_index`, `chunk_re_direct_physical`, the deferred pass's random seed — the deferred pass's own chunks | the subtractive composite (scaffolding) |
+| Reference | `chunk_ray_shaded_query_occluded` (path tracer), `RESOURCE_GROUP_RTX`, resident materials, `chunk_offset_ray` | three-group reference shader |
+| A/B arm | `chunk_ss_trace_pixel_occlusion` unchanged | an 8×8 dispatch of it |
+| Linear trace (§6) | `chunk_v3_matrix4_project`, `chunk_ndc_to_uv`, `chunk_uv_to_ndc`, `chunk_get_view_space_depth`, `chunk_get_bilinear_filter_texel`, `chunk_interpolate_bilinear_f32`, `chunk_interleaved_gradient_noise`, `chunk_project_position_from_depth`, `graph_compute_pass` | `chunk_screen_space_linear_ray` (generic, beside the Newton ray), the contact pass on it |
+| Measurement | `GPUProfileSession` (subclassed to keep spans by frame), the render-extension phases | counters shader |
+
+Nothing in the engine builds screen-space wavefronts toward a light, so the dispatch list and kernel are
+new. The unwired `deferred/chunk_ss_trace_contact_shadow_soft.js` is what the pass would supersede.
+
+## 5. Forks
+
+What the measurements recommend; each is Alex's call.
+
+1. **The sun only, or local lights too?** Sun only. Bend's layout takes a point or spot light as
+   `(position, 1)` with a screen rectangle, but every light is another full pass over its rectangle (about
+   30 µs per megapixel here), the local lights' shadow maps had their contact gap closed on 2026-10-04
+   (front faces, texel-scaled bias), and the ReSTIR DI path already traces their visibility. Not built or
+   measured here.
+2. **With the cascades, and with VSM.**
+   - Cascades: on. The pass closes 77–79% of their gaps at caster bases (`combine`, `disocclusion`) for
+     12–22 false px a frame, and 41–65% of what they cannot resolve at all (foliage cards, 2 cm slats) for
+     3,000–5,500 false px, at 38 µs at 1.27 Mpx.
+   - VSM: off. It leaves a twelfth to a twentieth of the cascades' gaps, and there the pass adds about as
+     much false shadow as it closes. The exceptions are a sun grazing the receiver, detail finer than the
+     first page, and foliage; whether those justify it is the question.
+   - Multiply (closer to the sun in all ten scenes) rather than min (keeps the cascades' softness, loses up
+     to 20 points of closure).
+3. **Where the mask is read.**
+   - (a) In the sun's shadow term (`chunk_shadowmap_sample_directional`, beside the CSM/VSM lookup): one
+     texture load per pixel. But that chunk is also linked by volumetrics, water optics and the forward
+     path, none of which has a screen pixel to read the mask at, so they need it without the read: a
+     per-pipeline choice, which waits on the shader-switches design started 2026-10-16.
+   - (b) A pass of its own after lighting, as the playground does: no change to deferred shading at all,
+     48 µs at 1.27 Mpx (it re-evaluates the sun's BRDF and cascade lookup), more than the contact pass
+     itself.
+   - Recommendation: (a) once shader switches exist.
+4. **Default on or off.** On with the cascades, with Bend's thickness, `IgnoreEdgePixels` on, bilinear
+   offset mode off (it closes more in `grazing`, 38.9% against 31.9%, but adds 150 false px against 23 and
+   does nothing for the far-field moiré), multiplied in. Off with VSM. The thickness is the one setting no
+   default serves (item 1): content with thin casters (foliage, grilles) wants it smaller, chunky casters
+   want Bend's.
+
+### Follow-ups, outside this prototype
+
+- `deferred/chunk_ss_trace_contact_shadow_soft.js` is unwired and measured worse than the wavefront pass
+  at twice its cost; wiring the pass should delete it.
+- `shadow/ray/shader_ray_shadow_code.js` could not be dispatched (five bind groups) and self-shadowed the
+  far ground (`offset_ray` on depth-rebuilt positions); both fixed 2026-10-16, along with its denoiser,
+  which did not load. It is still unwired.
+
+## 6. The linear trace, per pixel
+
+Alex's direction after reading §1–5: a per-pixel march, favouring accuracy, on a generic linear trace
+with a configurable step count that the rest of the engine can reuse.
+
+### What it is
+
+`shader/chunk/screen_space/chunk_screen_space_linear_ray.js`, beside the water's Newton ray. It is a port of
+Tomasz Stachowiak's `raymarch.hlsl` (MIT/Apache; the march Bevy uses for contact shadows, SSR and SSGI),
+built on the engine's own projection, depth and bilinear chunks:
+- **Clipped first.** The segment is clipped to the view frustum in NDC, so every step lands on screen.
+- **Exact depth along the ray.** It marches linearly in NDC, where device depth is affine along a projected
+  line.
+- **Bounded.** At most one step per pixel and at most 64 steps (`SCREEN_SPACE_LINEAR_RAY_STEP_LIMIT`), plus
+  up to 8 bisection steps.
+- **Two depth reads per step.** It takes the point-sampled and the bilinear depth from one 4-texel fetch,
+  and claims a hit only when the ray is behind both.
+- **World-unit thickness.** Depth is compared as view distance, so `depth_thickness` is in metres; with
+  `march_behind_surfaces` the ray carries on past a surface it went too deep behind.
+- **Hit refinement** by bisection and secant, for a trace that samples colour at the hit.
+
+`shadow/contact/shader_contact_shadow_linear.js` is the contact pass on it. Each pixel marches from its own
+NDC toward the sun:
+- a world-space reach, in a configurable number of steps;
+- a first step either fixed or jittered by interleaved gradient noise;
+- a hit's visibility faded over the back half of the thickness, as Bevy does.
+
+Pixels facing away from the sun are skipped.
+
+**Pinned on the CPU** (`chunk_screen_space_linear_ray.spec.js`, emulator against analytic depth buffers):
+- A ray climbing 3°, 10° or 30° off a flat ground, from near and far pixels in four headings, never finds
+  the ground in front of it. With point samples alone, the same rays do (the test that keeps the bilinear
+  read).
+- A ray toward a wall stops within a pixel of the analytic crossing.
+- Bisection takes a 4-step march from over 2 px off the crossing to under 1.
+- A 2 m deep wall is passed behind when marching behind surfaces, and stops the ray when not.
+- The sky is a miss over the whole length; the step count caps at 64 and at one per pixel.
+
+**Found on the device only:** `filter` is a WGSL reserved word, which the CPU validator does not check; the
+pipeline was invalid until it was renamed.
+
+### Settings, and where they come from
+
+- **Reach** is so many texels of the shadow map serving the near field (cascade 0 as last fitted, or VSM's
+  first level). That way the reach follows what the shadow map cannot resolve. Cascade 0 measured 4.7 cm a
+  texel in `combine`: 5 texels (the 5×5 filter) is 24 cm, 10 texels 48 cm.
+- **Thickness** is a multiple of reach ÷ steps. At 1 it is the least for which a march behind surfaces still
+  sees every surface (Tomasz's rule). Tying it to the step count makes more steps close less, because each
+  step's window narrows: at reach 5, 16 steps closed 58.8% in `combine`, 64 steps 39.5%.
+
+### Measured, against Bend with `IgnoreEdgePixels`
+
+Same scenes, paths and counters as §2 (150 frames per arm, cascades, multiply). Gaps closed / false px added /
+mean |error| against the ray-traced sun:
+
+| Scene | Bend + `IgnoreEdgePixels` | Linear, 32 steps, reach 5, thickness ×1 | Linear, 64 steps, reach 10, thickness ×4 |
+|---|---|---|---|
+| thickness | 17.1% / 153 / 0.0042 | 6.2% / 0 / 0.0043 | 15.1% / 21 / 0.0042 |
+| grazing | 28.2% / 6 / **0.0075** | 12.2% / 0 / 0.0086 | 11.1% / 0 / 0.0084 |
+| view | 28.1% / 26 / 0.0060 | 14.3% / 0 / 0.0064 | 29.0% / 1 / **0.0058** |
+| noise (fine detail) | 65.0% / 5,513 / 0.0376 | 29.7% / 175 / 0.0454 | 60.8% / 3,132 / **0.0351** |
+| disocclusion | 75.3% / 12 / **0.0047** | 45.2% / 1 / 0.0052 | 57.1% / 36 / 0.0050 |
+| screen_edge | 14.1% / 79 / 0.0346 | 5.3% / 1 / 0.0347 | 18.5% / 71 / **0.0342** |
+| distance | 10.2% / 45 / 0.0039 | 5.6% / 0 / 0.0041 | 10.3% / 1 / 0.0039 |
+| foliage | 40.8% / 3,004 / 0.0234 | 18.7% / 569 / 0.0256 | 41.0% / 1,725 / **0.0221** |
+| combine | 79.1% / 22 / **0.0041** | 53.8% / 0 / 0.0052 | 41.6% / 13 / 0.0056 |
+| sun_in_view | 35.3% / 358 / 0.0104 | 26.1% / 27 / 0.0110 | 48.7% / 542 / **0.0097** |
+| **Σ mean \|error\|** | 0.1364 | 0.1505 | **0.1340** |
+
+- **At the derived defaults** (reach 5, thickness ×1) the trace is the most conservative arm measured. It
+  adds almost no false shadow (0–1 px in seven scenes), but closes a third to three quarters of what Bend
+  closes, so it is the least accurate overall.
+- **At 64 steps, reach 10, thickness ×4** (≈48 cm reach, 3 cm thickness) it has the lowest summed error.
+  - Best in five scenes, tied in two.
+  - Bend stays better at the bases of solid casters (`combine`, `disocclusion`) and on a grazing sun.
+  - It adds less false shadow than Bend in most scenes (`noise` 3,132 against 5,513, `foliage` 1,725 against
+    3,004, `thickness` 21 against 153); `sun_in_view` is the exception (542 against 358).
+- **With VSM** (`combine`), 32 steps at reach 10 and thickness ×4 closes 5.1% of 380 gap px with none
+  false. There is as little to do as in §2.
+- **Jitter with TAA** changed nothing before TAA. It closed 53.0% against 53.8% in `combine` and doubled
+  the frame-to-frame change TAA is left to absorb (2,760 against 1,912). With at most one step per pixel
+  there is nothing for it to fill in. It stays off.
+
+### Cost
+
+RTX 4090, 1578×802, interleaved in one capture with Bend and the old march as in §3, two runs agreeing:
+
+| | Sun off screen | Sun on screen |
+|---|---|---|
+| Bend wavefront | 37.9 µs | 32.8 µs |
+| Linear, 32 steps | 80.9 µs | 47.1 µs |
+| Linear, 64 steps | 130.0 µs | 73.7 µs |
+| Old per-pixel march (60 steps) | 73.7 µs | 53.2 µs |
+
+Four depth reads a step, against Bend's four a pixel shared through workgroup memory. Fewer pixels march
+with the sun ahead, where more of the frame is sky and rays are shorter on screen.
+
+### What this changes in §5
+
+- **The method is the linear trace**, at 64 steps, reach 10 texels and thickness ×4. That setting is at
+  parity with Bend on accuracy against the sun and has less false shadow on fine detail, for 3.4× the cost:
+  ~130 µs at 1.27 Mpx, ~210 µs at 1080p on this card.
+- **Forks 1, 2 and 4 stand as written.** VSM still leaves too little to close.
+- **Fork 3 gets easier.** A per-pixel trace can run inline in the sun's shadow term, as Bevy does, with no
+  mask texture. It still needs the pixel's depth-buffer coordinate, which volumetrics and water do not
+  have, so it waits on shader switches all the same.
+- **Reuse.** SSR and ReSTIR DI march the HZB (`ffx_sssr_hierarchical_raymarch`), and the water uses its
+  Newton ray. Moving any of them onto this trace is a decision of its own, not made here; ReSTIR's chunk
+  records why it chose the HZB over a linear march.

package/src/shade/renderer/shadow/contact/chunk_contact_shadow_wavefront_extents.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where one thread of the contact shadow pass sits: the pixel it shadows, and the ray from it to the
+ * light's position on screen. Port of `ComputeWavefrontExtents` from Bend Studio's `bend_sss_gpu.h`
+ * (Sony Interactive Entertainment, Apache 2.0).
+ *
+ * A workgroup's `workgroup_id.yz` pick a square of {@link CONTACT_SHADOW_WAVE_SIZE} pixels in one of
+ * the rings around the light (`wave_offset` from {@link ContactShadowDispatchList} places the
+ * dispatch's quadrant), and `workgroup_id.x` a point along that ring's edge. That point and the light
+ * define a ray; the workgroup's threads sit on it, one pixel apart along its major axis, and the
+ * minor axis is wherever the ray crosses — fractional, which is why the depth reads interpolate
+ * across it.
+ *
+ * Thread order is reversed when the light is behind the camera (`light_coordinate.w < 0`), so that a
+ * thread's samples are always the threads after it.
+ *
+ * - `delta_xy`: the ray's displacement over the wave's {@link CONTACT_SHADOW_WAVE_SIZE} pixels, away
+ *   from the light; the reads step by it, times the march direction.
+ * - `pixel_xy`: this thread's pixel, fractional on the minor axis.
+ * - `pixel_distance`: this pixel's distance to the light along the major axis, in pixels.
+ * - `major_axis_x`: whether x is the ray's major axis.
+ * - `covers_light`: this thread also writes the pixel under the light's own coordinate. Bend's rings
+ *   stop one pixel short of the light, so with the light on screen that one pixel was written by no
+ *   thread at all and kept whatever the texture held; the threads of the innermost ring take it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_contact_shadow_wavefront_extents: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_contact_shadow_wavefront_extents.d.ts.map

package/src/shade/renderer/shadow/contact/chunk_contact_shadow_wavefront_extents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_contact_shadow_wavefront_extents.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/contact/chunk_contact_shadow_wavefront_extents.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qDAFU,SAAS,CA6EhB;0BAxGuB,oCAAoC"}

package/src/shade/renderer/shadow/contact/chunk_contact_shadow_wavefront_extents.js

@@ -0,0 +1,105 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { CONTACT_SHADOW_WAVE_SIZE } from "./CONTACT_SHADOW_WAVE_SIZE.js";
+
+/**
+ * Where one thread of the contact shadow pass sits: the pixel it shadows, and the ray from it to the
+ * light's position on screen. Port of `ComputeWavefrontExtents` from Bend Studio's `bend_sss_gpu.h`
+ * (Sony Interactive Entertainment, Apache 2.0).
+ *
+ * A workgroup's `workgroup_id.yz` pick a square of {@link CONTACT_SHADOW_WAVE_SIZE} pixels in one of
+ * the rings around the light (`wave_offset` from {@link ContactShadowDispatchList} places the
+ * dispatch's quadrant), and `workgroup_id.x` a point along that ring's edge. That point and the light
+ * define a ray; the workgroup's threads sit on it, one pixel apart along its major axis, and the
+ * minor axis is wherever the ray crosses — fractional, which is why the depth reads interpolate
+ * across it.
+ *
+ * Thread order is reversed when the light is behind the camera (`light_coordinate.w < 0`), so that a
+ * thread's samples are always the threads after it.
+ *
+ * - `delta_xy`: the ray's displacement over the wave's {@link CONTACT_SHADOW_WAVE_SIZE} pixels, away
+ *   from the light; the reads step by it, times the march direction.
+ * - `pixel_xy`: this thread's pixel, fractional on the minor axis.
+ * - `pixel_distance`: this pixel's distance to the light along the major axis, in pixels.
+ * - `major_axis_x`: whether x is the ray's major axis.
+ * - `covers_light`: this thread also writes the pixel under the light's own coordinate. Bend's rings
+ *   stop one pixel short of the light, so with the light on screen that one pixel was written by no
+ *   thread at all and kept whatever the texture held; the threads of the innermost ring take it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_contact_shadow_wavefront_extents = CodeChunk.from(
+    //language=WGSL
+    `
+struct ContactShadowWavefront {
+    delta_xy: vec2<f32>,
+    pixel_xy: vec2<f32>,
+    pixel_distance: f32,
+    major_axis_x: bool,
+    covers_light: bool,
+}
+
+fn contact_shadow_wavefront_extents(
+    light_coordinate: vec4<f32>,
+    wave_offset: vec2<i32>,
+    group_id: vec3<u32>,
+    thread_id: u32,
+) -> ContactShadowWavefront {
+    const WAVE_SIZE = ${CONTACT_SHADOW_WAVE_SIZE}i;
+
+    var xy = vec2<i32>(group_id.yz) * WAVE_SIZE + wave_offset;
+
+    // integer light position, and its fractional component
+    let light_xy = floor(light_coordinate.xy) + 0.5;
+    let light_xy_fraction = light_coordinate.xy - light_xy;
+    let reverse_direction = light_coordinate.w > 0.0;
+
+    let sign_xy = sign(xy);
+    let horizontal = abs(xy.x + sign_xy.y) < abs(xy.y - sign_xy.x);
+
+    let axis = vec2<i32>(
+        select(0, sign_xy.y, horizontal),
+        select(-sign_xy.x, 0, horizontal),
+    );
+
+    // step along the ring's edge
+    xy = axis * i32(group_id.x) + xy;
+    let xy_f = vec2<f32>(xy);
+
+    // only the larger axis matters for interpolating toward the light
+    let x_axis_major = abs(xy_f.x) > abs(xy_f.y);
+    let major_axis = select(xy_f.y, xy_f.x, x_axis_major);
+
+    let major_axis_start = abs(major_axis);
+    let major_axis_end = abs(major_axis) - f32(WAVE_SIZE);
+
+    var ma_light_frac = select(light_xy_fraction.y, light_xy_fraction.x, x_axis_major);
+    ma_light_frac = select(ma_light_frac, -ma_light_frac, major_axis > 0.0);
+
+    // back into screen space
+    let start_xy = xy_f + light_xy;
+
+    // the innermost ring ends on the light's exact coordinate, so rounding to a pixel skips none
+    let end_xy = mix(
+        light_coordinate.xy,
+        start_xy,
+        (major_axis_end + ma_light_frac) / (major_axis_start + ma_light_frac)
+    );
+
+    // a whole number of pixels on the major axis
+    let xy_delta = start_xy - end_xy;
+
+    let thread_step = f32(thread_id ^ select(u32(WAVE_SIZE - 1), 0u, reverse_direction));
+
+    var result: ContactShadowWavefront;
+
+    result.delta_xy = xy_delta;
+    result.pixel_xy = mix(start_xy, end_xy, thread_step / f32(WAVE_SIZE));
+    result.pixel_distance = major_axis_start - thread_step + ma_light_frac;
+    result.major_axis_x = x_axis_major;
+
+    // the innermost ring's last threads sit 1 ± ½ pixel from the light; no ring reaches distance 0
+    result.covers_light = result.pixel_distance < 2.5;
+
+    return result;
+}
+`);

package/src/shade/renderer/shadow/contact/graph_contact_shadow_linear.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Record one light's contact shadow by the linear trace into a new visibility texture: 1 lit, 0 shadowed,
+ * at the depth buffer's resolution.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.depth the depth buffer
+ * @param {number} options.normal the G-buffer normals
+ * @param {GPUBuffer} options.camera the view's camera uniforms, whose projection drew `depth`
+ * @param {ArrayLike<number>} options.resolution of `depth`
+ * @param {{to_light: ArrayLike<number>, length: number, steps: number, thickness: number, jitter_frame: number}} options.settings
+ *        see {@link CONTACT_SHADOW_LINEAR_SETTINGS_STRUCT}
+ * @returns {number} the visibility texture
+ */
+export function graph_contact_shadow_linear({ graph, depth, normal, camera, resolution, settings }: {
+    graph: FrameGraph;
+    depth: number;
+    normal: number;
+    camera: GPUBuffer;
+    resolution: ArrayLike<number>;
+    settings: {
+        to_light: ArrayLike<number>;
+        length: number;
+        steps: number;
+        thickness: number;
+        jitter_frame: number;
+    };
+}): number;
+//# sourceMappingURL=graph_contact_shadow_linear.d.ts.map

package/src/shade/renderer/shadow/contact/graph_contact_shadow_linear.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_contact_shadow_linear.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/contact/graph_contact_shadow_linear.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH;IAT+B,KAAK;IACT,KAAK,EAArB,MAAM;IACU,MAAM,EAAtB,MAAM;IACa,MAAM;IACE,UAAU,EAArC,UAAU,MAAM,CAAC;IAC8F,QAAQ,EAAvH;QAAC,QAAQ,EAAE,UAAU,MAAM,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAC;IAEnG,MAAM,CAsBlB"}

package/src/shade/renderer/shadow/contact/graph_contact_shadow_linear.js

@@ -0,0 +1,39 @@
+import { TextureResourceDescriptor } from "../../../device/graph/TextureResourceDescriptor.js";
+import { graph_compute_pass } from "../../shader/graph/compute/graph_compute_pass.js";
+import { shader_contact_shadow_linear } from "./shader_contact_shadow_linear.js";
+
+/**
+ * Record one light's contact shadow by the linear trace into a new visibility texture: 1 lit, 0 shadowed,
+ * at the depth buffer's resolution.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.depth the depth buffer
+ * @param {number} options.normal the G-buffer normals
+ * @param {GPUBuffer} options.camera the view's camera uniforms, whose projection drew `depth`
+ * @param {ArrayLike<number>} options.resolution of `depth`
+ * @param {{to_light: ArrayLike<number>, length: number, steps: number, thickness: number, jitter_frame: number}} options.settings
+ *        see {@link CONTACT_SHADOW_LINEAR_SETTINGS_STRUCT}
+ * @returns {number} the visibility texture
+ */
+export function graph_contact_shadow_linear({ graph, depth, normal, camera, resolution, settings }) {
+    const width = resolution[0];
+    const height = resolution[1];
+
+    return graph_compute_pass({
+        graph,
+        shader: shader_contact_shadow_linear,
+        group_count: [Math.ceil(width / 8), Math.ceil(height / 8), 1],
+        bindings: {
+            settings,
+            gBufferDepth: depth,
+            gBufferNormal: normal,
+            camera,
+            tContactShadow: TextureResourceDescriptor.from({
+                resolution: [width, height],
+                format: 'r32float',
+                usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING,
+            }),
+        },
+    }).tContactShadow;
+}