@woosh/meep-engine 3.47.0 → 3.49.0

package/src/shade/playground/contact_shadows/README.md

@@ -0,0 +1,126 @@
+# Contact shadows
+
+`npm run dev`, then `/src/shade/playground/contact_shadows/`.
+
+Screen-space contact shadows for the sun, one scene per way they are known to fail, each judged
+against a ray-traced reference. The pass under test is Bend Studio's wavefront method, ported in
+`src/shade/renderer/shadow/contact/`; what was found is in `FINDINGS.md` beside it.
+
+**Nothing in the default renderer changes.** The page adds two render extensions:
+
+- after lighting, it runs the contact pass, re-evaluates the sun's direct term from the G-buffer with the
+  deferred pass's own chunks, and takes back the share the contact term removes — the image deferred
+  shading would have made reading the mask beside the CSM/VSM lookup. `verify()` checks that this is
+  exact;
+- before tonemapping, it draws the chosen debug view.
+
+## Scenes
+
+| Scene | Failure mode it isolates | Camera path |
+|---|---|---|
+| Thickness | the depth buffer is a heightfield: 1–5 cm poles and a 2 cm plank (too thin for the window), a 2.5 m deep block (too thick) | ±40° orbit |
+| Grazing receivers | a sun 8° above the ground; low-poly sphere and hexagonal column (faceted depth, smooth normals), a ramp, a normal-mapped slab | low dolly |
+| View dependence | a table, a sphere, a cube hidden by a post from part of the orbit | full orbit, radius and height varying |
+| Fine detail, moving | a 2 cm grating, pickets, 300 grass blades; TAA on | lateral pan |
+| Movers, disocclusion | a box circling low, a sliding plank, a rolling ball, pillars the pan reveals ground behind; TAA on | lateral pan |
+| Screen edges | posts whose shadows fall into view while the pan takes them off the left edge, a beam above the top | pan |
+| Distance | the same cube and pole at 2, 5, 10, 20, 50, 100, 200 m | dolly 18 m |
+| Foliage | crossed alpha-tested leaf cards, a hedge, grass cards; TAA on | ±50° orbit |
+| Against the shadow map | a box, a sphere and a column whose bases sit in the cascades' bias gap, a slab 8 cm off the ground | orbit, dolly |
+| Sun in view | posts and cubes round the camera, a 15° sun | the camera turns on the spot, through the sun and away |
+
+## Controls
+
+- **Method**:
+  - off: the shadow map alone;
+  - the wavefront pass (Bend);
+  - the engine's old per-pixel march (`deferred/chunk_ss_trace_contact_shadow_soft.js`'s
+    `ss_trace_pixel_occlusion`), given the wavefront pass's 60-sample budget and thickness window;
+  - the linear trace: `renderer/shadow/contact/shader_contact_shadow_linear.js` on the generic
+    `shader/chunk/screen_space/chunk_screen_space_linear_ray.js`, one ray per pixel toward the sun.
+- **Linear: steps / reach / thickness / jitter** set the linear trace:
+  - steps, capped at 64 and at one per pixel;
+  - reach, in texels of the shadow map serving the near field (cascade 0 as last fitted, or VSM's first
+    level), shown in centimetres beside it; 5 is the cascades' 5×5 filter;
+  - thickness, as a multiple of reach ÷ steps; at 1 it is the least that lets a march behind surfaces see
+    every surface;
+  - jitter, which moves each pixel's first step by interleaved gradient noise every frame, for TAA.
+- **Combined with the shadow map by**: multiply or min.
+- **Surface thickness / edge threshold / shadow contrast** and the three flags are Bend's own tuning
+  (`DispatchParameters`); the sliders step by factors of two from Bend's starting values, as Bend's notes
+  advise.
+- **Wavefront debug** writes Bend's debug outputs into the contact term: the edge mask, or the thread and
+  wave layout (show "Contact term" to see them).
+- **Shadow map**: cascades or the virtual shadow map. **TAA** on or off.
+- **Show**: the final image; the combined, contact, shadow-map or reference visibility; or each pixel against
+  the reference — green, a gap the contact term closed; blue, shadowed in the reference and lit in the frame;
+  red, a false shadow the contact term added; amber, a false shadow the shadow map already had.
+- **Follow the scene's path** drives the camera along the scene's path at the chosen speed; **Pause time**
+  stops the path and the movers; **Step frame** advances one 1/60 s frame.
+- **Live counters** traces the reference every tenth frame and lists the counters below.
+
+`T` records a GPU profile (`.sgpt`).
+
+## Counters
+
+Every measured frame is classified pixel by pixel before TAA, with "shadowed" meaning a visibility under
+½. The reference is one ray from the pixel's G-buffer position to the sun's centre through the scene's
+BVH, alpha-tested occluders resolved from their materials.
+
+- **map missed (gaps)**: the reference shadows the pixel, the shadow map does not. **Closed by contact**: the
+  share of those the combined term shadows.
+- **Added by contact**: the reference and the shadow map both light the pixel, the combined term shadows it.
+- **Spurious flips**: pixels whose combined term crossed ½ since the last frame while the reference's did
+  not; the shadow map's own figure is beside it.
+- **Darker than both**: the combined term more than 0.1 below both terms — double darkening.
+- Per depth band of 0–2 m, 2–4 m, … doubling: the reference's shadowed pixels, the gaps, those closed, and
+  false shadow added.
+
+A shadow edge the shadow map filters and the reference does not differs by a pixel or two at every edge;
+those pixels count as gaps in every arm alike.
+
+## Console
+
+- `contact_lab.configure({ id: value, … })` sets controls by element id (`scene`, `method`, `combine`,
+  `thickness`, `technique`, `taa`, `show`, `path`, …); a scene change is in place when it resolves.
+- `await contact_lab.measure_scene({ scene, frames, warmup, moving, arms })` runs each arm over the same
+  camera path from the same start and returns the counters per frame. `arms` maps a name to control
+  settings; the default is off / wavefront / march.
+- `await contact_lab.measure_cost({ frames, block })`: GPU time of every pass, the three methods swapped
+  every `block` frames in ABC CBA order in one capture, each block's first frame dropped.
+- `await verify()`:
+  1. taking the whole sun term back out equals a frame with the sun switched off, to within the float16
+     rounding of the lit frame, with each shadow technique;
+  2. where the cascades shadow the "against the shadow map" scene, the reference does too;
+  3. the wavefront pass closes some of the cascades' gaps there (a smoke check).
+
+  It returns `{ pass, checks }`.
+
+## Measured
+
+Per scene and per arm, with cascades and with VSM, the cost, and the forks:
+`src/shade/renderer/shadow/contact/FINDINGS.md`.
+
+## Scripted session (one sitting, about ten minutes)
+
+Open the page in Chrome on the 4090, maximised. After each step, note what you see; paste the console
+output at the end.
+
+1. `await verify()` — expect `pass: true`.
+2. **Against the shadow map**, Show "Error against the reference", Method off, then Wavefront. Green should
+   cover most of the blue at the box, sphere and column bases and under the slab; red stays a pixel thin.
+   Then Shadow map "Virtual shadow map", Method off and Wavefront: the gaps are a fraction of the cascades'.
+3. **Thickness**, Show "Error", Wavefront: thickness slider to −2 and to +2. Red at the poles and plank
+   grows with the window; blue at the deep block's far side shrinks.
+4. **Grazing receivers**, Show "Contact term", Wavefront: the slab's normal map casts nothing (the depth
+   buffer is flat); look for striation on the ramp and the low-poly sphere; tick "Ignore edge pixels".
+5. **Fine detail, moving** with Follow path on, TAA on: watch the grating's shadows while the camera moves;
+   then Method "Per-pixel march".
+6. **Screen edges** with Follow path: watch the posts' contact shadows as the posts leave the left edge.
+7. **Sun in view** with Follow path; Wavefront debug "Wave index" with Show "Contact term" shows the
+   wavefronts converging on the sun's point, then leaving the point opposite.
+8. **Fine detail, moving**, then **Against the shadow map**, Show "Error against the reference": Method
+   "Linear trace" against "Wavefront" with Ignore edge pixels on. The linear trace adds less red on the
+   grating and leaves more blue at the box and sphere bases.
+9. Paste: `JSON.stringify(await contact_lab.measure_cost())` (all four methods; the linear trace at the
+   panel's settings).

package/src/shade/playground/contact_shadows/index.html

@@ -0,0 +1,191 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Meep — contact shadows</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            font: 13px/1.45 system-ui, sans-serif;
+            --panel: rgba(20, 25, 33, 0.92);
+            --line: #34404f;
+            --text: #e2e8f0;
+            --muted: #9aa8ba;
+            --pass: #8fd6a8;
+            --fail: #ff9a9a;
+        }
+
+        * { box-sizing: border-box; }
+
+        html, body { margin: 0; height: 100%; background: #0b0e13; color: var(--text); overflow: hidden; }
+
+        #view { position: fixed; inset: 0; width: 100vw; height: 100vh; display: block; }
+
+        #panel {
+            position: fixed; top: 12px; right: 12px; bottom: 12px; width: 310px;
+            overflow-y: auto; padding: 14px 16px;
+            background: var(--panel); border: 1px solid var(--line); border-radius: 8px;
+        }
+
+        h1 { font-size: 16px; margin: 0 0 4px; font-weight: 600; }
+        h2 { font-size: 12px; margin: 14px 0 6px; color: var(--muted); font-weight: 600; text-transform: uppercase; letter-spacing: .05em; }
+        p.lead { margin: 0 0 8px; color: var(--muted); }
+
+        label { display: block; margin: 6px 0; }
+        label > span { display: flex; justify-content: space-between; color: var(--muted); font-size: 12px; margin-bottom: 2px; }
+        label.check { display: flex; gap: 8px; align-items: center; }
+
+        select, button { width: 100%; background: #232c39; border: 1px solid #45556a; color: inherit; border-radius: 4px; padding: 5px 6px; font: inherit; }
+        button { cursor: pointer; }
+        button:hover { background: #2f3b4d; }
+        input[type=range] { width: 100%; accent-color: #6fc3ff; }
+
+        .row { display: grid; grid-template-columns: repeat(2, 1fr); gap: 6px; }
+
+        #failure { color: var(--muted); font-size: 12px; margin: 4px 0 0; }
+        #stats { font: 11px/1.5 ui-monospace, Consolas, monospace; white-space: pre-wrap; color: var(--text); margin: 6px 0 0; }
+        #status { font: 11px/1.5 ui-monospace, Consolas, monospace; white-space: pre-wrap; color: var(--pass); margin: 8px 0 0; }
+        #status.fail { color: var(--fail); }
+
+        .legend { font-size: 11px; color: var(--muted); }
+        .swatch { display: inline-block; width: 9px; height: 9px; border-radius: 2px; margin-right: 3px; vertical-align: -1px; }
+    </style>
+</head>
+<body tabindex="0">
+<canvas id="view" tabindex="0" aria-label="Contact shadow scene"></canvas>
+<div id="panel">
+    <h1>Contact shadows</h1>
+    <p class="lead">Screen-space contact shadows for the sun, one scene per way they fail, against a ray-traced reference.</p>
+
+    <h2>Scene</h2>
+    <label><span>Failure mode</span>
+        <select id="scene">
+            <option value="thickness" selected>Thickness</option>
+            <option value="grazing">Grazing receivers</option>
+            <option value="view">View dependence</option>
+            <option value="noise">Fine detail, moving</option>
+            <option value="disocclusion">Movers, disocclusion</option>
+            <option value="screen_edge">Screen edges</option>
+            <option value="distance">Distance</option>
+            <option value="foliage">Foliage</option>
+            <option value="combine">Against the shadow map</option>
+            <option value="sun_in_view">Sun in view</option>
+        </select>
+    </label>
+    <p id="failure"></p>
+
+    <h2>Contact term</h2>
+    <label><span>Method</span>
+        <select id="method">
+            <option value="0">Off (shadow map only)</option>
+            <option value="1" selected>Wavefront (Bend)</option>
+            <option value="2">Per-pixel march (old engine chunk)</option>
+            <option value="3">Linear trace (per pixel)</option>
+        </select>
+    </label>
+    <label><span>Linear: steps</span>
+        <select id="linear-steps">
+            <option value="16">16</option>
+            <option value="32">32</option>
+            <option value="64" selected>64 (measured best)</option>
+        </select>
+    </label>
+    <label><span>Linear: reach, in shadow-map texels <output id="linear-reach-value"></output></span>
+        <select id="linear-reach">
+            <option value="2.5">2.5 (half the PCF kernel)</option>
+            <option value="5">5 (the PCF kernel)</option>
+            <option value="10" selected>10 (measured best)</option>
+        </select>
+    </label>
+    <label><span>Linear: thickness, × reach / steps</span>
+        <select id="linear-thickness">
+            <option value="1">1 (the least that sees every surface)</option>
+            <option value="4" selected>4 (measured best)</option>
+            <option value="16">16</option>
+        </select>
+    </label>
+    <label class="check"><input id="linear-jitter" type="checkbox"> Linear: jitter the first step</label>
+    <label><span>Combined with the shadow map by</span>
+        <select id="combine">
+            <option value="0" selected>Multiply</option>
+            <option value="1">Min</option>
+        </select>
+    </label>
+    <label><span>Surface thickness <output id="thickness-value"></output></span>
+        <input id="thickness" type="range" min="-3" max="3" step="1" value="0">
+    </label>
+    <label><span>Edge threshold <output id="threshold-value"></output></span>
+        <input id="threshold" type="range" min="-3" max="3" step="1" value="0">
+    </label>
+    <label><span>Shadow contrast <output id="contrast-value"></output></span>
+        <input id="contrast" type="range" min="1" max="8" step="1" value="4">
+    </label>
+    <label class="check"><input id="ignore-edges" type="checkbox"> Ignore edge pixels</label>
+    <label class="check"><input id="offset-mode" type="checkbox"> Bilinear offset mode</label>
+    <label class="check"><input id="precision-offset" type="checkbox"> Precision offset</label>
+    <label><span>Wavefront debug</span>
+        <select id="debug">
+            <option value="0" selected>None</option>
+            <option value="1">Edge mask</option>
+            <option value="2">Thread index</option>
+            <option value="3">Wave index</option>
+        </select>
+    </label>
+
+    <h2>Frame</h2>
+    <label><span>Shadow map</span>
+        <select id="technique">
+            <option value="csm" selected>Cascades</option>
+            <option value="vsm">Virtual shadow map</option>
+        </select>
+    </label>
+    <label class="check"><input id="taa" type="checkbox"> TAA</label>
+    <label><span>Show</span>
+        <select id="show">
+            <option value="0" selected>Final image</option>
+            <option value="1">Sun visibility, combined</option>
+            <option value="2">Contact term</option>
+            <option value="3">Shadow map term</option>
+            <option value="4">Ray-traced reference</option>
+            <option value="5">Error against the reference</option>
+        </select>
+    </label>
+    <div class="legend">
+        Error: <span class="swatch" style="background:#1ae633"></span>gap closed
+        <span class="swatch" style="background:#1a59ff"></span>missed
+        <span class="swatch" style="background:#ff1414"></span>false (contact)
+        <span class="swatch" style="background:#ff990d"></span>false (map)
+    </div>
+    <label class="check"><input id="reference" type="checkbox"> Trace the reference every frame</label>
+    <label class="check"><input id="live" type="checkbox"> Live counters (traces the reference)</label>
+
+    <h2>Camera</h2>
+    <label class="check"><input id="path" type="checkbox"> Follow the scene's path</label>
+    <label><span>Path speed <output id="speed-value"></output></span>
+        <input id="speed" type="range" min="0.25" max="4" step="0.25" value="1">
+    </label>
+    <label class="check"><input id="pause" type="checkbox"> Pause time</label>
+    <div class="row">
+        <button id="preset">Preset</button>
+        <button id="step">Step frame</button>
+    </div>
+
+    <h2>State</h2>
+    <div id="stats"></div>
+    <div id="status">Loading…</div>
+</div>
+<script type="module">
+    import { start } from './main.js';
+
+    start().catch(error => {
+        const status = document.getElementById('status');
+
+        status.textContent = String(error?.stack ?? error);
+        status.className = 'fail';
+
+        console.error(error);
+    });
+</script>
+</body>
+</html>

package/src/shade/playground/contact_shadows/main.d.ts

@@ -0,0 +1,2 @@
+export function start(): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/contact_shadows/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/contact_shadows/main.js"],"names":[],"mappings":"AA8JA,uCAytBC"}