@woosh/meep-engine 3.10.0 → 3.11.1

package/src/shade/device/timing/profile/sgpt_write_record.js

@@ -0,0 +1,62 @@
+import { assert } from "../../../../core/assert.js";
+import { crc32 } from "../../../../core/binary/hash/crc32.js";
+import { SGPT_RECORD_HEADER_SIZE } from "./SGPT_RECORD_HEADER_SIZE.js";
+import { SGPT_RECORD_SYNC } from "./SGPT_RECORD_SYNC.js";
+
+/**
+ * Append one framed record, encoding its payload through `write_payload`.
+ *
+ * The payload is written first, into the same buffer, and the framing is filled in behind it once
+ * its length and checksum are known. That ordering is what keeps a record a single pass: the
+ * alternative — encode to a scratch buffer, measure, copy — costs an allocation and a copy per
+ * frame, every frame, for nothing.
+ *
+ * A record is complete or it is absent. If `write_payload` throws, `position` is restored to where
+ * the record would have begun, so a failed encode leaves no half-record for a reader to trip over.
+ *
+ * @template T
+ * @param {BinaryBuffer} buffer positioned where the record should start
+ * @param {number} type one of {@link SGPT_RECORD_TYPE}
+ * @param {T} data handed to `write_payload`
+ * @param {function(BinaryBuffer, T): void} write_payload
+ * @returns {number} bytes written, framing included
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function sgpt_write_record(buffer, type, data, write_payload) {
+    assert.defined(buffer, 'buffer');
+    assert.isInteger(type, 'type');
+    assert.isFunction(write_payload, 'write_payload');
+
+    const record_start = buffer.position;
+    const payload_start = record_start + SGPT_RECORD_HEADER_SIZE;
+
+    buffer.position = payload_start;
+
+    try {
+        write_payload(buffer, data);
+    } catch (e) {
+        buffer.position = record_start;
+
+        throw e;
+    }
+
+    const payload_end = buffer.position;
+    const payload_byte_length = payload_end - payload_start;
+
+    const checksum = crc32(buffer.raw_bytes, payload_start, payload_byte_length);
+
+    buffer.position = record_start;
+
+    buffer.writeUint32(SGPT_RECORD_SYNC);
+    buffer.writeUint32(type);
+    buffer.writeUint32(payload_byte_length);
+    buffer.writeUint32(checksum);
+
+    assert.equal(buffer.position, payload_start, 'record framing size mismatch');
+
+    buffer.position = payload_end;
+
+    return payload_end - record_start;
+}

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

@@ -0,0 +1,88 @@
+# volumetrics_froxel
+
+Real participating media, a movable sun and a wide-FOV camera in front of the froxel volumetrics
+pass.
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+then open <http://localhost:5173/src/shade/playground/volumetrics_froxel/index.html>.
+
+## Why it exists
+
+`shader_volumetrics_build_lighting` and the passes around it were reviewed against current practice.
+Five correctness findings came out of it; four were fixed and one was closed as a documented
+non-issue. All five were geometric, and geometry is the class of defect a unit test can prove but
+not show — an emulator can assert that a sample lands at the wrong depth and still not tell you
+whether that reads as a smear, a seam, or nothing at all. This page was where that got decided.
+
+| finding | what it was | where the fix lives |
+|---|---|---|
+| C-01a | Planar view depth walked as a distance along a unit ray, so the froxel sample fell short by cos θ | `chunk_camera_ray_planar_depth_scale`, from the lighting pass |
+| C-01b | The aerial pass integrated Beer's law over a planar depth difference rather than arc length | same chunk, from the aerial pass — this was the visible half |
+| C-02 | Cell-averaged grids read with the boundary-sampled convention, a ~0.53-froxel bias | `chunk_volumetrics_froxel_content_offset` |
+| C-03 | Shadow ray clipped against a frustum with no far plane, so a sun anywhere in the view cone got zero optical depth | `chunk_integrate_optical_depth` takes the metadata frustum |
+| C-04 | The shadow march addressed the froxel grid with the aerial LUT's depth curve | `volumetrics_position_world_to_froxel_uvw` |
+| C-05 | Adjacent columns carry independent jitter, so an XY fetch mixes depths | closed — zero-mean and TAA-absorbable; `volumetrics/NOTES.md` has the measurements and why the obvious fix makes it worse |
+
+Those fixes are in the permanent path now and there is nothing left to A/B. What the page is for is
+the *next* change here — the performance findings especially, since every one of them trades image
+quality for time and none can be judged from a screenshot.
+
+## Measuring, rather than eyeballing
+
+This pass is stochastic and temporally filtered, so most changes to it move the image by less than
+the frame-to-frame noise. A screenshot pair is not evidence. Four traps, each of which produced a
+confident wrong answer during the work above:
+
+- **Auto exposure.** It keeps adapting for seconds after any change, so two captures of the
+  *identical* setting differed in mean luminance by more than the change being judged. Off by
+  default here; `renderer.exposure_compensation` sets the fixed value.
+- **Per-frame jitter.** The column jitter and the sample RNG both key on `view.frame_index`, so
+  consecutive frames genuinely differ. Average 18+ frames per capture.
+- **No noise floor, no result.** Capture the *same* setting twice and difference those first. If the
+  change's delta is not clearly above that, nothing has been shown.
+- **The noise floor has to pay the same costs the signal does.** Anything that calls
+  `indicate_view_change()` resets temporal accumulation, so a capture taken right after one carries
+  a re-convergence transient that a back-to-back capture does not. Measuring the floor without that
+  in the middle inflates every result — it made C-04 fail a test it should have passed. Capture as
+  *change → settle ~45 frames → average*, and take the floor by making an identical no-op change so
+  both paths cost the same.
+
+Prefer the **signed mean** when the change has a direction; it discriminates far better than the
+mean-absolute, which is dominated by noise. C-01b read −0.148 at 60° FOV against a floor of ±0.05,
+and −1.071 at 110°: same fix, and that 7× is the `1/cos θ` scaling it predicts.
+
+Also: mutating `light.intensity` does not mark the light buffer dirty, so a sweep of it renders
+identically. Remove and re-add the light instead.
+
+## Scene
+
+`flying_world_-_battle_of_the_trash_god/v2`, six participating-media volumes, a low sun, and the
+Venice sunset environment. Both the volumes and most of the camera placements are carried over from
+the sibling repo's playground, where they were found by hand against this exact model — keeping the
+numbers means a before/after pair is taken from the same place to the pixel.
+
+Assets live under `test_assets/`, which is gitignored; `test_assets/README.md` has how they get
+there. This page needs:
+
+```bash
+mkdir -p "test_assets/flying_world_-_battle_of_the_trash_god/v2"
+cp "H:/git/meep-renderer-deferred-algo/public/flying_world_-_battle_of_the_trash_god/v2/scene.gltf" "H:/git/meep-renderer-deferred-algo/public/flying_world_-_battle_of_the_trash_god/v2/scene.bin" "test_assets/flying_world_-_battle_of_the_trash_god/v2/"
+cp "H:/git/meep-renderer-deferred-algo/public/environments/octahedral/venice_sunset_2k.hdr" test_assets/environments/octahedral/
+```
+
+Only `scene.gltf` and `scene.bin` are needed from that directory — about 26 MB. glTF rather than the
+`.shade` sitting beside it: that export's header reads format version 1 and `deserialize_scene`
+accepts version 2 only, deliberately and with no backward compatibility.
+
+## Notes
+
+Two viewpoints from the sibling repo (`v_volumetrics_light_extinction_0` and `_1`) sit inside
+geometry here and were replaced with placements verified against this build. *Log camera* writes the
+current placement to the console in the form the `VIEWS` table takes, which is how to add more.
+
+Frame time settles around 28 ms at 1920×1080 on a 4070-class part. That is the whole frame, not the
+volumetrics pass — separating it out needs a timestamp query. It is the baseline the performance
+findings (P-01 … P-06) would move.

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

@@ -0,0 +1,251 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — froxel volumetrics</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --panel: rgba(20, 22, 26, 0.88);
+            --line: #2b3038;
+            --text: #d6dae0;
+            --muted: #8b939f;
+            --pass: #55c46a;
+            --fail: #ff6b6b;
+            --warn: #e5b54a;
+            --tag: #c98b3f;
+        }
+
+        * { box-sizing: border-box; }
+
+        html, body { margin: 0; height: 100%; overflow: hidden; background: #0d0f12; }
+
+        /* body carries tabindex so the camera controller's keyboard device has something focusable
+           to listen on; the focus ring around the whole viewport is not wanted */
+        body:focus { outline: none; }
+
+        #view { display: block; width: 100vw; height: 100vh; }
+
+        #panel {
+            position: fixed;
+            top: 12px;
+            left: 12px;
+            width: 330px;
+            max-height: calc(100vh - 24px);
+            overflow-y: auto;
+            padding: 12px 14px;
+            background: var(--panel);
+            border: 1px solid var(--line);
+            border-radius: 8px;
+            backdrop-filter: blur(6px);
+            color: var(--text);
+            font: 13px/1.5 system-ui, -apple-system, Segoe UI, sans-serif;
+        }
+
+        #panel h1 { font-size: 13px; font-weight: 600; margin: 0 0 8px; }
+
+        h2 {
+            font-size: 11px;
+            font-weight: 600;
+            text-transform: uppercase;
+            letter-spacing: 0.06em;
+            color: var(--muted);
+            margin: 0 0 6px;
+        }
+
+        label { display: flex; align-items: center; gap: 8px; padding: 3px 0; cursor: pointer; }
+        label input[type="checkbox"] { margin: 0; }
+        label .hint { color: var(--muted); font-size: 11.5px; }
+
+        hr { border: 0; border-top: 1px solid var(--line); margin: 10px 0; }
+
+        button {
+            font: inherit;
+            padding: 5px 11px;
+            border-radius: 6px;
+            border: 1px solid var(--line);
+            background: #1c1f25;
+            color: var(--text);
+            cursor: pointer;
+        }
+
+        button:hover { border-color: #3d4552; }
+        button:focus-visible { outline: 2px solid var(--tag); outline-offset: 2px; }
+
+        #views { display: flex; flex-direction: column; gap: 4px; }
+
+        button.view {
+            text-align: left;
+            display: flex;
+            align-items: baseline;
+            gap: 8px;
+            padding: 4px 9px;
+            font-size: 12.5px;
+        }
+
+        .tag {
+            font: 10px ui-monospace, SFMono-Regular, Consolas, monospace;
+            color: var(--tag);
+            border: 1px solid currentColor;
+            border-radius: 3px;
+            padding: 0 4px;
+            flex: 0 0 auto;
+        }
+
+        .slider {
+            display: grid;
+            grid-template-columns: 1fr auto;
+            align-items: center;
+            gap: 2px 8px;
+            padding: 4px 0;
+        }
+
+        .slider .name { font-size: 12px; }
+        .slider .value {
+            font: 12px ui-monospace, SFMono-Regular, Consolas, monospace;
+            color: var(--muted);
+            text-align: right;
+            min-width: 44px;
+        }
+        .slider input[type="range"] { grid-column: 1 / -1; width: 100%; margin: 0; }
+
+        .row { display: flex; gap: 6px; align-items: center; }
+        .row button { flex: 1 1 auto; }
+
+        #status { font-size: 12px; color: var(--muted); word-break: break-word; margin-top: 6px; }
+        #status.pass { color: var(--pass); }
+        #status.fail { color: var(--fail); }
+        #status.warn { color: var(--warn); }
+
+        #stats {
+            margin-top: 4px;
+            font: 12px ui-monospace, SFMono-Regular, Consolas, monospace;
+            color: var(--text);
+        }
+
+        p.note { margin: 6px 0 0; font-size: 11.5px; color: var(--muted); }
+    </style>
+</head>
+<body tabindex="0">
+
+<canvas id="view"></canvas>
+
+<div id="panel">
+    <h1>Froxel volumetrics</h1>
+
+    <h2>Viewpoints</h2>
+    <div id="views"></div>
+
+    <hr>
+
+    <h2>Sun</h2>
+
+    <div class="row">
+        <button id="sun_into_view">Sun into view</button>
+        <button id="sun_behind">Sun behind</button>
+    </div>
+    <p class="note">
+        Places the sun on the camera's forward axis, or directly opposite it. Media self-shadowing
+        depends on the shadow ray's path through the grid, so swinging the sun through the frustum
+        is the quickest way to exercise it.
+    </p>
+
+    <div class="slider">
+        <span class="name">Azimuth</span>
+        <span class="value" id="sun_azimuth_value">200°</span>
+        <input type="range" id="sun_azimuth" min="0" max="359" step="1" value="200">
+    </div>
+
+    <div class="slider">
+        <span class="name">Elevation</span>
+        <span class="value" id="sun_elevation_value">12°</span>
+        <input type="range" id="sun_elevation" min="1" max="80" step="1" value="12">
+    </div>
+
+    <hr>
+
+    <h2>Camera</h2>
+
+    <div class="slider">
+        <span class="name">Field of view</span>
+        <span class="value" id="fov_value">60°</span>
+        <input type="range" id="fov" min="30" max="110" step="1" value="60">
+    </div>
+    <p class="note">
+        Froxel geometry is angle-dependent — the planar depth curve and the ray it is walked along
+        diverge as cos&nbsp;θ. A wide FOV is where anything that confuses the two shows up, so open
+        this to 110° when judging a change to the grid.
+    </p>
+
+    <hr>
+
+    <h2>Volumetrics</h2>
+
+    <label>
+        <input type="checkbox" id="vol_taa" checked>
+        <span>Volumetric TAA <span class="hint">— off exposes the raw per-frame noise</span></span>
+    </label>
+
+    <label>
+        <input type="checkbox" id="taa" checked>
+        <span>Renderer TAA</span>
+    </label>
+
+    <label>
+        <input type="checkbox" id="auto_exposure">
+        <span>Auto exposure <span class="hint">— off: A/B is meaningless with it on</span></span>
+    </label>
+    <p class="note">
+        Eye adaptation drifts for seconds after any change, so two captures of the same setting can
+        differ by more than the change being judged. It starts off here for that reason; turn it on
+        only to see how something reads in a normally-exposed frame.
+    </p>
+
+    <div class="slider">
+        <span class="name">Froxel far</span>
+        <span class="value" id="froxel_far_value">off</span>
+        <input type="range" id="froxel_far" min="20" max="120" step="5" value="120">
+    </div>
+    <p class="note">
+        Packs the froxel grid into a shorter range than <code>camera.far</code>, so the near field
+        gets more slices and the aerial pass ray-marches the volumes beyond it. At <em>off</em> the
+        grid spans the whole range and the two depth curves coincide.
+    </p>
+
+    <div class="slider">
+        <span class="name">Multiscatter octaves</span>
+        <span class="value" id="ms_octaves_value">6</span>
+        <input type="range" id="ms_octaves" min="1" max="8" step="1" value="6">
+    </div>
+
+    <hr>
+
+    <div class="row">
+        <button id="pause">Pause</button>
+        <button id="log_camera">Log camera</button>
+    </div>
+
+    <div id="status"></div>
+    <div id="stats"></div>
+
+    <p class="note">
+        Drag to orbit, wheel to zoom, WASD to move. <em>Log camera</em> writes the current placement
+        to the console in the form the <code>VIEWS</code> table takes.
+    </p>
+</div>
+
+<script type="module">
+    import { start } from './main.js';
+
+    start().catch(error => {
+        const status = document.getElementById('status');
+
+        status.className = 'fail';
+        status.textContent = String(error?.message ?? error);
+
+        console.error(error);
+    });
+</script>
+
+</body>
+</html>

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

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

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

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