@woosh/meep-engine 3.60.4 → 3.60.6

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

@@ -1,413 +0,0 @@
-# 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. 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. 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; 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) |
-| 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; 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/map/csm/NOTES.md

@@ -1,5 +0,0 @@
-Useful references:
-
-* https://github.com/roy-t/MiniRTS/blob/4e9d8b3999513ab11199f7666ae5976e18b192b8/src/MiniEngine.Graphics/Shadows/CascadedShadowMapSystem.cs#L94
-* https://github.com/roy-t/MiniRTS/blob/4e9d8b3999513ab11199f7666ae5976e18b192b8/src/MiniEngine.Graphics/Content/Effects/Includes/Shadows.hlsl#L92
-* https://github.com/SaschaWillems/Vulkan/blob/master/examples/shadowmappingcascade/shadowmappingcascade.cpp

package/src/shade/renderer/shadow/ray/NOTES.md

@@ -1,31 +0,0 @@
-Things to try:
-* Variable rate shading, shade a few pixels and see if it makes sense to shade more
-* First do temporal reprojection, and only then do raycasts using reprojection data
-  * If reprojection is a success and confidence is high - we can skip casting rays
-  * Otherwise, we cast a ray with probability proportional to confidence
-  * Eventually it should converge, but at a fraction of rays cast overall
-
-Occlusion queries should be single-sided, meaning we should not consider back of a triangle to be occluding.
-Considering back side of a triangle as an intersection will cause a lot of false-positives for shadows, TAA jitter will
-make those false-positives flicker creating a mess.
-So far there's no clear and robust solution to self-occlusion, this seems like the cleanest compromise
-
-# VRS
-
-1. Split image into 16x16 tiles (256 values)
-2. Classify tiles by shading rate (1, 4, 16, 64, 128, 256)
-3. Generate rays for each tile
-4. (optional) Sort rays
-5. Trace rays and write result into texture
-6. Fill gaps (flood fill)
-7. Apply denoising per-tile
-
-References:
-
-* Call of Duty paper [TBA]
-* [Raytraced Shadows in Call of Duty: Modern Warfare](https://www.youtube.com/watch?v=VXp-HEAw-l4)
-* Ray Tracing Gems chapter on shadows [TBA]
-* https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK/blob/main/docs/techniques/denoiser.md
-* [Denoising Raytraced Soft Shadows with FidelityFX (Presented by AMD)](https://www.youtube.com/watch?v=RTtVC-Zk5yI)
-* Calisto Protocol
-* [Ray-Traced Reflections in Battlefield V](https://www.youtube.com/watch?v=ncUNLDQZMzQ)

package/src/shade/renderer/shadow/sdf/NOTES.md

@@ -1,9 +0,0 @@
-References:
-
-* https://iquilezles.org/articles/distfunctions/
-* https://github.com/gkjohnson/three-mesh-bvh/blob/efce76d488a5875b5d8119c50b5d4c8e00f9d66c/example/utils/RayMarchSDFMaterial.js#L72
-* https://github.com/StarsX/SDFTracing/blob/11a1bb9911eae09cb68b4a66c2d25959fb51b460/SDFTracing/Content/Shaders/ConeTrace.hlsli#L24
-* https://kosmonautblog.wordpress.com/2017/05/01/signed-distance-field-rendering-journey-pt-1/
-* https://github.com/godotengine/godot/blob/a65954894670d3c1f23d7e09c13df9cd0cf534a8/servers/rendering/renderer_rd/shaders/environment/sdfgi_direct_light.glsl#L311
-* "Dynamic Occlusion with Signed Distance Fields" by Daniel Wright, Epic Games 2015
-* [Radiance Caching for Real-Time Global Illumination](https://www.youtube.com/watch?v=2GYXuM10riw)

package/src/shade/renderer/shadow/sdf/brixelizer/NOTES.md

@@ -1,5 +0,0 @@
-References:
-
-* https://gpuopen.com/manuals/fidelityfx_sdk/fidelityfx_sdk-page_techniques_brixelizer/
-* https://gpuopen.com/fidelityfx-brixelizer/
-* https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK/tree/main/sdk/include/FidelityFX/gpu/brixelizer

package/src/shade/renderer/shadow/sdf/cascade/NOTES.md

@@ -1,9 +0,0 @@
-see [Claybook_Simulation_Raytracing_GDC18](https://www.dropbox.com/scl/fi/5w6mwv24qis7pwco53oxn/Claybook_Simulation_Raytracing_GDC18.pptx?rlkey=11u09sotl5ahdhimmnc6o4rcv&e=1&dl=0)
-
-Raymarching to perfect intersection using geometric progression:
-
-```c
-step = d / (1 - (d - d_prev))
-```
-
-This should take us directly to the surface

package/src/shade/renderer/shadow/vsm/NOTES.md

@@ -1,12 +0,0 @@
-# Virtual Shadow Map
-
-## Requirements
-* we *don't* want to draw coarse-level tiles for virtual shadow map, unless it will actually be used.
-  * Drawing a coarse tile, will require us to rasterize larger amount of geometry, plus unused tile will be taking up a physical page
-
-## References
-
-* "Fitted Virtual Shadow Maps" by "Markus Giegl" and "Michael Wimmer"
-* "Queried Virtual Shadow Maps" by "Markus Giegl" and "Michael Wimmer"
-* How to split frustum : https://stackoverflow.com/questions/28155749/opengl-matrix-setup-for-tiled-rendering
-* https://ktstephano.github.io/rendering/stratusgfx/svsm