@woosh/meep-engine 3.14.6 → 3.15.0

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

@@ -0,0 +1,117 @@
+# avboit
+
+AVBOIT against MBOIT on the deck's own test case: a stack of near-opaque cards at a chosen depth
+separation, a tinted glass pane, an opaque surface pushed through the transparency pipeline, an
+opaque backdrop. `npm run dev`, then `/src/shade/playground/avboit/`.
+
+The pipeline itself is documented in
+[`AVBOIT_PLAN_2026_09_03.md`](../../renderer/rasterize/native/avboit/AVBOIT_PLAN_2026_09_03.md); this
+page is its device tier — the real compile, the look, and the timings.
+
+## What to look for
+
+- **Depth-complexity invariance.** Four cards at alpha 0.85 and spacing 1.5. Under MBOIT the cards
+  behind the front one show through more than their alpha allows and the black bar behind the stack
+  is visible through all four (deck slides 35–38). Under AVBOIT the front card hides what is behind
+  it by its alpha and no more. Seen on 2026-09-03 (ledger entry 12).
+- **The slice floor.** Drop the spacing under AVBOIT. When the cards land in one slice the stack
+  degrades to weighted blending — the deck's fail case (slides 86–92). With 4096 virtual slices the
+  floor at this camera is about 1.6 cm, and the two-slice bias means cards need more than 3.2 cm to
+  occlude each other cleanly; 0.05 should still resolve, 0.02 should not.
+- **RGB transmittance.** With **tint transmitted light by base colour** on
+  (`renderer.avboit.transmission_tint_from_base_color`, off by default), the glass pane filters the
+  backdrop by its base colour under AVBOIT — glTF's transmission semantics — and never under MBOIT
+  or the tracer, which have no per-channel transmission. Off, all three modes render the pane as
+  the same clear glass. Switch the tint to `none` for a control.
+- **An opaque surface through the transparency pipeline.** The small pale quad one unit behind the
+  last card is alpha 1 on a `Transparent` material — the deck's "0 % transmittance card" (slides
+  35–38). Both pipelines clamp its coverage at 0.997, so it should read as solid with a hard edge
+  against the backdrop and the dark bar. Under MBOIT the moment reconstruction cannot hold a step
+  that steep: the quad leaks what is behind it, and where its depth jumps against the background the
+  reconstruction tears along the edge. Under AVBOIT the quad occupies a slice of its own and the
+  edge is only as soft as the 1/8-resolution volume's trilinear filter.
+- **Slopes.** Orbit until a card or the pane is at a grazing angle. A splat fragment carries the
+  depth of its 1/8-resolution pixel centre, which on a slope can differ from the full-resolution
+  fragment's depth by more than the two-slice bias; self-occlusion along the slope would show as the
+  surface darkening or striping toward the grazing edge. Copy the camera when you find one.
+- **Brick4.** The indirect-lighting select runs the Brick4 draw variant. The scene has no probes, so
+  the indirect term is black either way; what it proves is that the variant compiles and draws.
+- **Nothing else changes.** TAA, shadows and exposure are pinned across the switch; auto exposure
+  is off by default because it keeps drifting for seconds after any change.
+
+## The reference
+
+The third mode, **path traced (reference)**, hands the frame to `renderer.path_tracer`, the
+accumulating path tracer. It rolls every transparent hit against the surface's alpha
+(`chunk_render_trace_path.js`, the opacity roll) and continues the ray, so over many samples it
+converges to the exact order-independent composite of the card stack — what both OIT modes are
+approximating. The report shows the sample count of the slowest tile; judge nothing under a few
+hundred. TAA is forced off while tracing (two temporal filters over one image), the running-mean
+floor is lowered from the tracer's default so the image keeps settling, and any camera move or
+**Reset accumulation** starts over.
+
+Two things the reference does *not* settle:
+
+- **The glass tint.** The tracer's thin-walled transmission carries the `(1 - F)` Fresnel split and
+  no per-channel colour (`chunk_render_trace_path.js`, the substrate slot), so for the pane it is a
+  reference for the Fresnel coverage only. Compare the pane with the tint switch off.
+- **Shadow rays through transparency.** The tracer's occlusion query treats geometry as opaque
+  (its own `TODO`), so cards cast full shadows in the reference where the rasterized modes cast
+  none. Look at the stack, not at its shadow on the floor.
+
+## Camera
+
+Drag to orbit, wheel to zoom, right-drag to pan, W/A/S/D to move (the `OrbitalCameraController`, on
+`document.body`, so dragging across the panel moves the camera too and the keys need the page
+focused — click it once). The camera and its controls are wired before the device is requested, so
+they work even where the renderer cannot start; a control whose handler fails says so in the report
+panel rather than only in the console. **Copy camera** puts
+`{"position":[…],"target":[…],"fov_degrees":…}` on the clipboard and in the box; **Apply camera**
+reads the box back. From the console: `camera_state()`, `apply_camera(state)`, or
+`configure({ camera: state })` alongside the other controls.
+
+## Timings
+
+**Profile** starts a `GPUProfileSession` at `WORKLOAD` level (pass spans, the frame graph, dispatch
+and draw counts); pressing it again drains the in-flight frames, stops, and downloads
+`avboit-<mode>-<timestamp>.sgpt`. Record a few seconds in one mode, switch, record again with the
+same settings, and open both in the inspector:
+
+```bash
+npm run dev --workspace @woosh/gpu-inspector-tool
+```
+
+The passes to compare are under the `transparencies` scope: `AVBOIT/occupancy`, `AVBOIT/build warp`,
+`AVBOIT/splat`, `AVBOIT / integrate`, `AVBOIT/draw`, `AVBOIT / resolve` against `MBOIT/generate
+moments`, `MBOIT/resolve moments`, `OIT Blend`. Without `timestamp-query` the capture has the
+structure and no durations; the report says so when it starts. `start_profile()` / `stop_profile()`
+from the console do the same.
+
+## One scripted session
+
+The in-app browser pane has no WebGPU adapter in this environment, so the device-tier checks are
+run by hand. One session, in order, results pasted back into the ledger:
+
+1. Open the page. The report should say `mode AVBOIT, IBL indirect, 4 cards, …` and the scene should render.
+2. Press **Compile check**. Expect `10/10 AVBOIT modules compiled`. Anything else: paste the block.
+3. Switch **indirect lighting** to Brick4. The frame should still render (black indirect is expected).
+4. Compare the stack: AVBOIT vs MBOIT at the defaults. Does the black bar show through under AVBOIT?
+5. `configure({ spacing: 0.05 })` then `configure({ spacing: 0.02 })` under AVBOIT: the first should
+   still occlude, the second should blend.
+6. `configure({ spacing: 1.5, tint_from_base_color: true, tint: 'none' })` then `tint: 'red'`: the
+   backdrop behind the pane should go red under AVBOIT only. With the switch off the pane is the
+   same clear glass in every mode.
+7. `configure({ mode: 'REFERENCE', tint: 'none' })`, wait for the report to pass ~300 samples, and
+   compare the stack against AVBOIT at the same settings: which of the two OIT modes is closer to
+   it, and where do they differ (the bar behind the stack is the sharpest test).
+8. With the opaque quad on, zoom on its edges against the backdrop and against the dark bar under
+   MBOIT, AVBOIT and the reference: is the edge a clean step, and does anything behind the quad show
+   through its interior?
+9. Orbit to a grazing view of a card or the pane; if the surface darkens or stripes toward the
+   grazing edge under AVBOIT and not under MBOIT, **Copy camera** and paste the state with the note.
+10. **Profile** a few seconds in AVBOIT, then in MBOIT at the same settings; open both captures in
+    the inspector and read the `transparencies` scope.
+
+Everything the page does is reachable from the console: `renderer`, `scene`, `camera`, `controller`,
+`configure({...})`, `camera_state()`, `apply_camera(state)`, `compile_check()` (its last result is
+on `globalThis.__last_compile`), `start_profile()`, `stop_profile()`.

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

@@ -0,0 +1,215 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — AVBOIT / MBOIT transparency A/B</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --bg: #14161a;
+            --panel: #1c1f25;
+            --line: #2b3038;
+            --text: #d6dae0;
+            --muted: #8b939f;
+            --pass: #55c46a;
+            --fail: #ff6b6b;
+            --warn: #e5b54a;
+        }
+
+        * { box-sizing: border-box; }
+
+        body {
+            margin: 0;
+            padding: 16px;
+            background: var(--bg);
+            color: var(--text);
+            font: 13px/1.5 system-ui, -apple-system, Segoe UI, sans-serif;
+        }
+
+        body:focus { outline: none; }
+
+        h1 { font-size: 16px; font-weight: 600; margin: 0 0 4px; }
+
+        p.lede { margin: 0 0 14px; color: var(--muted); max-width: 90ch; }
+
+        .stage { display: flex; gap: 16px; align-items: flex-start; flex-wrap: wrap; }
+
+        canvas {
+            display: block;
+            border: 1px solid var(--line);
+            border-radius: 4px;
+            background: #000;
+        }
+
+        aside {
+            width: 340px;
+            background: var(--panel);
+            border: 1px solid var(--line);
+            border-radius: 8px;
+            padding: 12px 14px;
+        }
+
+        aside h2 {
+            font-size: 11px;
+            text-transform: uppercase;
+            letter-spacing: 0.06em;
+            color: var(--muted);
+            margin: 0 0 8px;
+        }
+
+        label { display: flex; gap: 8px; align-items: center; padding: 3px 0; }
+
+        label span { flex: 1; }
+
+        select, input[type="number"], textarea {
+            font: inherit;
+            background: #14161a;
+            color: var(--text);
+            border: 1px solid var(--line);
+            border-radius: 4px;
+            padding: 3px 6px;
+            width: 120px;
+        }
+
+        textarea {
+            width: 100%;
+            height: 3.4em;
+            font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
+            font-size: 11px;
+            resize: vertical;
+        }
+
+        button {
+            font: inherit;
+            padding: 6px 12px;
+            border-radius: 6px;
+            border: 1px solid var(--line);
+            background: #22303f;
+            color: var(--text);
+            cursor: pointer;
+            margin-top: 10px;
+            width: 100%;
+        }
+
+        button:disabled { opacity: 0.45; cursor: default; }
+
+        button.recording { border-color: var(--fail); color: var(--fail); }
+
+        .hint { color: var(--muted); font-size: 12px; margin: 6px 0 0; }
+
+        .pair { display: flex; gap: 8px; }
+
+        pre {
+            background: #14161a;
+            border: 1px solid var(--line);
+            border-radius: 6px;
+            padding: 8px 10px;
+            font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
+            font-size: 11.5px;
+            white-space: pre-wrap;
+            margin: 10px 0 0;
+            max-height: 40vh;
+            overflow: auto;
+        }
+
+        pre.pass { border-color: var(--pass); }
+        pre.fail { border-color: var(--fail); }
+
+        hr { border: 0; border-top: 1px solid var(--line); margin: 12px 0; }
+    </style>
+</head>
+<body tabindex="0">
+
+<h1>AVBOIT / MBOIT transparency A/B</h1>
+<p class="lede">
+    The deck’s test harness in miniature: a stack of camera-facing transparent cards at a chosen depth
+    separation, a tinted glass pane, an opaque surface pushed through the transparency pipeline, and an
+    opaque backdrop. “Mode” flips <code>renderer.transparency_mode</code> between the voxel-based and the
+    moment-based pipelines with everything else held still, or to the path tracer for a reference that
+    accumulates while the camera is still. Drag to orbit, wheel to zoom, right-drag to pan; the camera state
+    copies as JSON so a view can be handed over exactly. “Profile” records GPU timings into an
+    <code>.sgpt</code> capture for the gpu-inspector-tool.
+</p>
+
+<div class="stage">
+    <div>
+        <canvas id="view"></canvas>
+        <p class="hint">drag to orbit · wheel to zoom · right-drag to pan · W/A/S/D to move (click the page first, the keys listen on the body)</p>
+    </div>
+
+    <aside>
+        <h2>transparency</h2>
+
+        <label><span>mode</span>
+            <select id="mode">
+                <option value="AVBOIT" selected>AVBOIT (voxels)</option>
+                <option value="MBOIT">MBOIT (moments)</option>
+                <option value="REFERENCE">path traced (reference)</option>
+            </select>
+        </label>
+
+        <label><span>indirect lighting</span>
+            <select id="indirect">
+                <option value="IBL" selected>IBL</option>
+                <option value="Brick4">Brick4</option>
+            </select>
+        </label>
+
+        <label><span>card alpha</span><input type="number" id="alpha" value="0.85" min="0.05" max="0.997" step="0.05"></label>
+        <label><span>card spacing</span><input type="number" id="spacing" value="1.5" min="0.001" max="10" step="0.1"></label>
+        <label><span>card count</span><input type="number" id="count" value="4" min="1" max="12" step="1"></label>
+        <label><span>glass pane</span><input type="checkbox" id="glass" checked></label>
+        <label><span>tint transmitted light by base colour (AVBOIT)</span><input type="checkbox" id="tint_from_base_color"></label>
+        <label><span>glass tint</span>
+            <select id="tint">
+                <option value="red" selected>red</option>
+                <option value="green">green</option>
+                <option value="blue">blue</option>
+                <option value="none">none (clear)</option>
+            </select>
+        </label>
+        <label><span>opaque quad, transparent material</span><input type="checkbox" id="opaque_quad" checked></label>
+
+        <hr>
+
+        <h2>renderer</h2>
+
+        <label><span>TAA</span><input type="checkbox" id="taa" checked></label>
+        <label><span>shadows</span><input type="checkbox" id="shadows" checked></label>
+        <label><span>auto exposure</span><input type="checkbox" id="exposure"></label>
+        <label><span>exposure (stops)</span><input type="number" id="exposure_compensation" value="1.5" step="0.5"></label>
+        <label><span>width</span><input type="number" id="width" value="1280" step="2"></label>
+        <label><span>height</span><input type="number" id="height" value="720" step="2"></label>
+
+        <button id="apply">Apply</button>
+        <button id="reset">Reset accumulation (reference)</button>
+
+        <hr>
+
+        <h2>camera</h2>
+
+        <textarea id="camera_state" placeholder='{"position":[x,y,z],"target":[x,y,z],"fov_degrees":45}'></textarea>
+        <div class="pair">
+            <button id="copy_camera">Copy camera</button>
+            <button id="apply_camera">Apply camera</button>
+        </div>
+
+        <hr>
+
+        <h2>measure</h2>
+
+        <button id="profile">Profile (record GPU timings)</button>
+        <button id="compile">Compile check (AVBOIT modules)</button>
+
+        <pre id="report">ready</pre>
+    </aside>
+</div>
+
+<script type="module">
+    import { start } from './main.js';
+
+    start();
+</script>
+
+</body>
+</html>

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

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

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

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