@woosh/meep-engine 3.18.0 → 3.19.0

package/src/shade/playground/particle_ecs/moonlit_environment.js

@@ -0,0 +1,144 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
+import { sampler2d_to_f16 } from "../../../engine/graphics/texture/sampler/sampler2d_to_f16.js";
+import { octahedral_uv_to_direction } from "../../renderer/light/environment/octahedral_uv_to_direction.js";
+import { ColorSpace } from "../../renderer/texture/ColorSpace.js";
+import { ShadeImage } from "../../renderer/texture/source/ShadeImage.js";
+import { ShadeTexture } from "../../renderer/texture/ShadeTexture.js";
+
+/**
+ * A moonlit night sky, generated: what the bonfire is lit by when it is not lighting itself.
+ *
+ * Built rather than loaded for the same reason the sprites are — `test_assets/` is gitignored, so a
+ * fresh checkout has no environment map, and a page that needs one to look right would look wrong
+ * for everybody who has not fetched the asset repository. This is small, it is in linear radiance,
+ * and it is the same octahedral projection `scene.lights.environment` samples.
+ *
+ * **The sky is the reason the fire reads as a fire.** Shade assumes global illumination, so a scene
+ * with no environment renders unlit; give it a bright day and the flame washes out to a pale smear,
+ * because the fire's own light is then a small fraction of what is already there. A night sky about
+ * three orders of magnitude below daylight is what leaves the fire room to be the brightest thing
+ * in the frame, and what makes the smoke read as blue where the firelight has stopped reaching it.
+ */
+
+/**
+ * Resolution per octahedral face grid.
+ *
+ * Small on purpose: this is an ambient source, convolved into irradiance and a handful of roughness
+ * mips before anything samples it. What it has to be is smooth and correctly oriented.
+ *
+ * @type {number}
+ */
+const RESOLUTION = 128;
+
+/**
+ * Where the moon is. Unit, +Y up — the direction light arrives *from*, so the shadows fall the
+ * other way.
+ *
+ * @type {Vector3}
+ */
+export const MOON_DIRECTION = new Vector3(-0.42, 0.62, -0.66).normalize();
+
+/**
+ * Angular radius of the moon's disc, in radians. Far larger than the real one (about 0.0045): the
+ * map is 128 texels across a hemisphere, so a true disc would be a fraction of a texel and would
+ * disappear into the first mip. This is a moon to look at, not an ephemeris.
+ *
+ * @type {number}
+ */
+const MOON_RADIUS = 0.075;
+
+/**
+ * @type {Vector3}
+ */
+const SCRATCH_DIRECTION = new Vector3();
+
+/**
+ * Radiance arriving from a direction, in linear space.
+ *
+ * @param {number[]} out rgb
+ * @param {number} x
+ * @param {number} y +Y is up
+ * @param {number} z
+ */
+function moonlit_radiance(out, x, y, z) {
+    // How close this direction is to the moon, as the cosine of the angle between them.
+    const alignment = x * MOON_DIRECTION.x + y * MOON_DIRECTION.y + z * MOON_DIRECTION.z;
+    const angle = Math.acos(Math.min(1, Math.max(-1, alignment)));
+
+    if (y >= 0) {
+        // Night sky: deepest at the zenith, lifting toward the horizon where the atmosphere is
+        // thicker and there is more of it to scatter what little light there is.
+        const horizon = Math.pow(1 - y, 4);
+
+        out[0] = 0.0035 + horizon * 0.011;
+        out[1] = 0.0052 + horizon * 0.014;
+        out[2] = 0.0115 + horizon * 0.020;
+    } else {
+        // Below the horizon: ground bounce, dimmer and less blue than the sky. This is what lights
+        // the underside of the smoke, so it is not zero however dark the night is.
+        const t = Math.pow(1 + y, 2);
+
+        out[0] = 0.0016 + t * 0.0042;
+        out[1] = 0.0017 + t * 0.0044;
+        out[2] = 0.0022 + t * 0.0055;
+    }
+
+    // A broad halo, then the disc itself. The halo is what makes the sky around the moon read as
+    // sky with a moon in it rather than as a sticker on a gradient.
+    const halo = Math.exp(-angle * 5.5) * 0.05;
+
+    out[0] += halo * 0.75;
+    out[1] += halo * 0.82;
+    out[2] += halo;
+
+    if (angle < MOON_RADIUS) {
+        // Soft-edged, so the disc survives the convolution into the roughness mips with a shape
+        // rather than as ringing.
+        const disc = 1 - Math.pow(angle / MOON_RADIUS, 3);
+
+        out[0] += disc * 5.2;
+        out[1] += disc * 5.6;
+        out[2] += disc * 6.4;
+    }
+}
+
+/**
+ * The environment map. Assign it to `scene.lights.environment`.
+ *
+ * @returns {ShadeTexture}
+ */
+export function moonlit_environment() {
+    const sampler = Sampler2D.float32(4, RESOLUTION, RESOLUTION);
+
+    const data = sampler.data;
+    const rgb = [0, 0, 0];
+
+    for (let v = 0; v < RESOLUTION; v++) {
+        for (let u = 0; u < RESOLUTION; u++) {
+            // texel centres, so the mapping is symmetric across the octahedron's folds
+            octahedral_uv_to_direction(
+                SCRATCH_DIRECTION,
+                (u + 0.5) / RESOLUTION,
+                (v + 0.5) / RESOLUTION
+            );
+
+            moonlit_radiance(rgb, SCRATCH_DIRECTION.x, SCRATCH_DIRECTION.y, SCRATCH_DIRECTION.z);
+
+            const offset = (v * RESOLUTION + u) * 4;
+
+            data[offset] = rgb[0];
+            data[offset + 1] = rgb[1];
+            data[offset + 2] = rgb[2];
+            data[offset + 3] = 1;
+        }
+    }
+
+    const image = ShadeImage.fromSampler2D(sampler2d_to_f16(sampler));
+
+    // radiance, not colour: the values above are light arriving, and treating them as sRGB would
+    // put a transfer curve through numbers that never had one
+    image.color_space = ColorSpace.LinearSRGB;
+
+    return ShadeTexture.from(image);
+}

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

@@ -78,10 +78,11 @@ edits it at both altitudes.
 - Two of them are **ramps**, edited as a picture. An **RGBA Gradient** (and an RGB one) is a strip of
   the colour it produces with its stops underneath: drag a stop, click the lane to add one — in the
   colour the gradient already is there, so adding never changes anything — and middle-click to remove.
-  A **Curve** is the unit square with its keys in it, and the picker under it decides the selected
-  key's tangents. Neither is sampled from a table at runtime: both are written out into the program as
-  arithmetic, which is what the **Code** tab shows. `Curve Table`, which *is* the table, is the other
-  node — it takes a row handle rather than a curve.
+  A **Curve** plots normalized time against unrestricted values, with a Y axis that fits the whole
+  curve, including peaks between keys. Its fields edit the selected key's time, value and tangents.
+  The scale stays fixed during a drag and refits on release. Neither ramp is sampled from a table
+  at runtime: both are written out into the program as arithmetic, which is what the **Code** tab
+  shows. `Curve Table`, which *is* the table, is the other node — it takes a row handle rather than a curve.
 - The strip along the bottom lists every problem with the effect, from **both** phases, loudest
   first. Click one to jump to the phase it is in and select the node; the node is outlined in the
   graph too.

package/src/shade/playground/profile_hotkey.d.ts

@@ -0,0 +1,58 @@
+/**
+ * One key that records a GPU profile capture and downloads it.
+ *
+ * `T` starts a recording, `T` again stops it and saves an `.sgpt` next to the browser's other
+ * downloads. That is the whole interaction, and it is what every playground page wants: a capture is
+ * something you take *while looking at* the thing you are suspicious of, so reaching for a panel is
+ * already too slow.
+ *
+ * **The engine never constructs a `GPUProfileSession`.** `Renderer.profile_session` is a nullable
+ * field and the null checks around it are the entire integration, which is what keeps the profiler
+ * out of a bundle that does not ask for it. Importing this module is the opt-in.
+ *
+ * `volumetrics_froxel/main.js` has its own copy of this, written first; it is the page this was
+ * lifted from and it can adopt this when somebody has the assets to verify it against.
+ */
+/**
+ * @typedef {object} ProfileHotkeyHandle
+ * @property {function(): boolean} is_recording
+ * @property {function(): Promise<void>} toggle start a recording, or stop and save the one running
+ * @property {function(): void} dispose remove the key listener
+ */
+/**
+ * Wire the key up.
+ *
+ * @param {object} params
+ * @param {import("../renderer/Renderer.js").Renderer} params.renderer initialized — this reads its
+ *        device for the capture's metadata
+ * @param {string} params.name goes in the filename and in the capture's note
+ * @param {HTMLElement|null} [params.status] written with what the recording is doing; the element
+ *        gets the class `recording` while one is running, and nothing otherwise
+ * @param {function(): string[]} [params.settings] what the page was set to when the capture was
+ *        taken. A pass timing says nothing until you know that
+ * @param {number} [params.level] see {@link GPUProfileLevel}; `WORKLOAD` is the most detailed
+ * @param {string} [params.key] the letter to bind, lowercase
+ * @param {EventTarget} [params.target] where the listener goes
+ * @returns {ProfileHotkeyHandle}
+ */
+export function install_profile_hotkey({ renderer, name, status, settings, level, key, target, }: {
+    renderer: import("../renderer/Renderer.js").Renderer;
+    name: string;
+    status?: HTMLElement | null;
+    settings?: () => string[];
+    level?: number;
+    key?: string;
+    target?: EventTarget;
+}): ProfileHotkeyHandle;
+export type ProfileHotkeyHandle = {
+    is_recording: () => boolean;
+    /**
+     * start a recording, or stop and save the one running
+     */
+    toggle: () => Promise<void>;
+    /**
+     * remove the key listener
+     */
+    dispose: () => void;
+};
+//# sourceMappingURL=profile_hotkey.d.ts.map

package/src/shade/playground/profile_hotkey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile_hotkey.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/profile_hotkey.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;;;;;GAeG;AACH;IAZ8D,QAAQ,EAA3D,OAAO,yBAAyB,EAAE,QAAQ;IAE3B,IAAI,EAAnB,MAAM;IACoB,MAAM,GAAhC,WAAW,GAAC,IAAI;IAEc,QAAQ,SAA1B,MAAM,EAAE;IAEJ,KAAK,GAArB,MAAM;IACU,GAAG,GAAnB,MAAM;IACe,MAAM,GAA3B,WAAW;IACT,mBAAmB,CAwO/B;;wBA3PyB,OAAO;;;;kBACP,QAAQ,IAAI,CAAC;;;;mBACb,IAAI"}

package/src/shade/playground/profile_hotkey.js

@@ -0,0 +1,325 @@
+import package_json from "../../../package.json";
+import { GPUProfileLevel } from "../device/timing/profile/GPUProfileLevel.js";
+import { GPUProfileSession } from "../device/timing/profile/GPUProfileSession.js";
+
+/**
+ * One key that records a GPU profile capture and downloads it.
+ *
+ * `T` starts a recording, `T` again stops it and saves an `.sgpt` next to the browser's other
+ * downloads. That is the whole interaction, and it is what every playground page wants: a capture is
+ * something you take *while looking at* the thing you are suspicious of, so reaching for a panel is
+ * already too slow.
+ *
+ * **The engine never constructs a `GPUProfileSession`.** `Renderer.profile_session` is a nullable
+ * field and the null checks around it are the entire integration, which is what keeps the profiler
+ * out of a bundle that does not ask for it. Importing this module is the opt-in.
+ *
+ * `volumetrics_froxel/main.js` has its own copy of this, written first; it is the page this was
+ * lifted from and it can adopt this when somebody has the assets to verify it against.
+ */
+
+/**
+ * @typedef {object} ProfileHotkeyHandle
+ * @property {function(): boolean} is_recording
+ * @property {function(): Promise<void>} toggle start a recording, or stop and save the one running
+ * @property {function(): void} dispose remove the key listener
+ */
+
+/**
+ * Wire the key up.
+ *
+ * @param {object} params
+ * @param {import("../renderer/Renderer.js").Renderer} params.renderer initialized — this reads its
+ *        device for the capture's metadata
+ * @param {string} params.name goes in the filename and in the capture's note
+ * @param {HTMLElement|null} [params.status] written with what the recording is doing; the element
+ *        gets the class `recording` while one is running, and nothing otherwise
+ * @param {function(): string[]} [params.settings] what the page was set to when the capture was
+ *        taken. A pass timing says nothing until you know that
+ * @param {number} [params.level] see {@link GPUProfileLevel}; `WORKLOAD` is the most detailed
+ * @param {string} [params.key] the letter to bind, lowercase
+ * @param {EventTarget} [params.target] where the listener goes
+ * @returns {ProfileHotkeyHandle}
+ */
+export function install_profile_hotkey({
+    renderer,
+    name,
+    status = null,
+    settings = () => [],
+    level = GPUProfileLevel.WORKLOAD,
+    key = "t",
+    target = window,
+}) {
+    /**
+     * The recording in progress, or null.
+     * @type {GPUProfileSession|null}
+     */
+    let session = null;
+
+    /** Guards against the key being leaned on while a stop is still draining. */
+    let busy = false;
+
+    /**
+     * @param {string} text
+     * @param {boolean} [recording]
+     */
+    function set_status(text, recording = false) {
+        if (status === null) {
+            return;
+        }
+
+        status.textContent = text;
+        status.className = recording ? "recording" : "";
+    }
+
+    function start() {
+        const device = renderer.device;
+
+        const recording = new GPUProfileSession({
+            level,
+            note: `${name} — ${[...settings(), `${renderer.pixel_ratio.toFixed(2)}x`].join(" · ")}`,
+        });
+
+        /*
+         Populated before start(): the meta record is written into the stream there and not read
+         again. Without it the capture is unreadable in the sense that matters — a pass taking 0.4 ms
+         says nothing until you know which GPU and at what resolution.
+        */
+        const meta = recording.meta;
+
+        // `GPUDevice.adapterInfo` is recent enough that a browser running this page may not have it,
+        // and several browsers withhold the fields even when they do. Empty is what the format
+        // expects in that case.
+        const info = device.adapterInfo;
+
+        if (info !== undefined && info !== null) {
+            meta.adapter_vendor = info.vendor ?? "";
+            meta.adapter_architecture = info.architecture ?? "";
+            meta.adapter_device = info.device ?? "";
+            meta.adapter_description = info.description ?? "";
+        }
+
+        meta.features = [...device.features];
+        meta.engine_version = package_json.version;
+
+        recording.onBytesWritten.add(bytes => {
+            /*
+             Only while this is still the live recording. Frames keep landing all through the drain
+             in `stop`, which is the whole point of draining — and without this check each one would
+             overwrite "stopping…" with "● recording · T to stop", so a capture that is on its way to
+             disk reads as one that is still running.
+            */
+            if (session !== recording) {
+                return;
+            }
+
+            set_status(
+                `● recording — ${recording.frames_recorded} frames, ${format_bytes(bytes)}`
+                + `  ·  ${key.toUpperCase()} to stop`,
+                true
+            );
+        });
+
+        renderer.profile_session = recording;
+        recording.start();
+
+        session = recording;
+
+        // The timers go quiet without this rather than failing, so the capture still carries the
+        // frame graph and the workload — it just has no durations in it. Worth knowing before you
+        // record for a minute and then look.
+        const timed = device.features.has("timestamp-query");
+
+        set_status(
+            timed
+                ? `● recording — 0 frames  ·  ${key.toUpperCase()} to stop`
+                : "● recording without timestamp-query — structure only, no durations"
+                + `  ·  ${key.toUpperCase()} to stop`,
+            true
+        );
+    }
+
+    /**
+     * Wait for frames already submitted to finish landing in the session.
+     *
+     * A frame is committed when its timestamp readback resolves — a `mapAsync` a frame or two behind
+     * submit, see `ShadeGPUCommandContext.profiling_absorbed` — and `record_frame` silently ignores
+     * anything arriving after `stop()`. Stopping the instant the key goes down therefore discards
+     * the last few frames, which are the ones you were most likely looking at.
+     *
+     * Drains the queue, then waits for the frame count to stop moving. Capped, because a recording
+     * taken while the page is paused never moves at all.
+     *
+     * @param {GPUProfileSession} recording
+     * @returns {Promise<void>}
+     */
+    async function drain(recording) {
+        const DEADLINE_MS = 1000;
+        const QUIET_MS = 60;
+
+        await renderer.device.queue.onSubmittedWorkDone();
+
+        const deadline = performance.now() + DEADLINE_MS;
+
+        let previous = recording.frames_recorded;
+
+        while (performance.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, QUIET_MS));
+
+            if (recording.frames_recorded === previous) {
+                return;
+            }
+
+            previous = recording.frames_recorded;
+        }
+    }
+
+    async function stop() {
+        const recording = session;
+
+        session = null;
+
+        // Detached first, so nothing encoded during the drain below joins the recording. Frames
+        // already encoded are unaffected: Renderer captures the session into a local before it
+        // subscribes to the readback.
+        renderer.profile_session = null;
+
+        set_status("stopping — draining in-flight frames…");
+
+        await drain(recording);
+
+        const bytes = recording.stop();
+        const filename = `${name}-${file_timestamp()}.sgpt`;
+
+        download_bytes(bytes, filename);
+
+        const topologies = `${recording.topology_count} topolog${recording.topology_count === 1 ? "y" : "ies"}`;
+
+        // Also to the console, because the status line is the only other place the name appears and
+        // a browser that declines the save says nothing about which capture it declined.
+        console.log(
+            `profile: ${recording.frames_recorded} frames, ${format_bytes(bytes.byteLength)}, `
+            + `${topologies} -> ${filename}`
+        );
+
+        set_status(
+            `${recording.frames_recorded} frames, ${format_bytes(bytes.byteLength)}, ${topologies}`
+            + `  ·  ${filename}`
+        );
+    }
+
+    /**
+     * @returns {Promise<void>}
+     */
+    function toggle() {
+        if (busy) {
+            return Promise.resolve();
+        }
+
+        busy = true;
+
+        const done = session === null ? Promise.resolve(start()) : stop();
+
+        return done.catch(error => {
+            set_status(`profiling failed: ${error?.message ?? error}`);
+            console.error(error);
+
+            session = null;
+            renderer.profile_session = null;
+        }).finally(() => {
+            busy = false;
+        });
+    }
+
+    /**
+     * @param {KeyboardEvent} event
+     */
+    function on_keydown(event) {
+        if (event.ctrlKey || event.metaKey || event.altKey || event.repeat) {
+            return;
+        }
+
+        /*
+         `key` first, because it is the letter actually printed on the key the user pressed — `code`
+         is physical position, so on AZERTY it names the key where T sits on QWERTY. `code` is the
+         fallback for layouts whose `key` is not Latin at all (Cyrillic gives "е" here).
+        */
+        if (event.key.toLowerCase() !== key && event.code !== `Key${key.toUpperCase()}`) {
+            return;
+        }
+
+        // a panel's fields and buttons are focusable; do not steal a key from one
+        const focused = event.target;
+
+        if (
+            focused instanceof HTMLInputElement
+            || focused instanceof HTMLTextAreaElement
+            || focused instanceof HTMLSelectElement
+        ) {
+            return;
+        }
+
+        event.preventDefault();
+
+        toggle();
+    }
+
+    target.addEventListener("keydown", on_keydown);
+
+    return {
+        is_recording: () => session !== null,
+        toggle,
+        dispose: () => target.removeEventListener("keydown", on_keydown),
+    };
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @param {string} filename
+ */
+function download_bytes(bytes, filename) {
+    const url = URL.createObjectURL(new Blob([bytes], { type: "application/octet-stream" }));
+
+    const anchor = document.createElement("a");
+
+    anchor.href = url;
+    anchor.download = filename;
+
+    document.body.appendChild(anchor);
+    anchor.click();
+    anchor.remove();
+
+    // Revoking in the same task cancels the download in some browsers — the click only schedules it.
+    setTimeout(() => URL.revokeObjectURL(url), 60000);
+}
+
+/**
+ * `YYYYMMDD-HHMMSS` in local time, matching the naming the other `.sgpt` captures already use — same
+ * sort order, and it reads as the clock you took it by rather than as UTC.
+ *
+ * @returns {string}
+ */
+function file_timestamp() {
+    const now = new Date();
+
+    const pad = value => String(value).padStart(2, "0");
+
+    return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`
+        + `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+function format_bytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    }
+
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}

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

@@ -0,0 +1,105 @@
+# SSR variance playground
+
+Run `npm run dev` from the workspace, then open
+<http://localhost:5173/src/shade/playground/ssr_variance/>.
+
+The scene contains exactly two quads: a metallic ground plane at y=0 with roughness
+0.30, and a vertical card facing the camera. The card carries an emissive cross
+texture with two coloured details. The pattern does not add geometry or normal
+edges. A constant dim environment supplies the SSR fallback.
+
+The camera, scene, exposure (compensation 1), and 800×500 resolution are fixed.
+Automatic exposure, SSAO, bloom, sharpening, and motion blur are disabled.
+Main TAA defaults off and can be enabled independently.
+Raster jitter defaults off separately: the production renderer still applies its
+jitter sequence with TAA off, so a playground-only `FrameStart` extension freezes
+the view's projection and jitter uniforms before rasterization. The jitter control
+can restore production behaviour. SSR's stochastic frame index still advances.
+
+## Exact capture
+
+The page starts at frame **0** without submitting a frame or scheduling an animation
+loop. **Capture frames 100–115** submits exactly 115 frames, each with dt=1/60, and
+records frame 100 and every subsequent frame through 115. GPU completion and readback
+are awaited between captures. Readback does not render extra frames. The renderer's
+own count is checked against the experiment count; its zero-based SSR indices are
+99–114 for these captures.
+
+From the console:
+
+```js
+const lab = await ssr_variance_ready;
+const measurements = await lab.run(); // requires frame zero; finishes at frame 115
+lab.frame_count;                      // 115, stays there indefinitely
+lab.frames;                           // 16 PNG byte arrays and linear float32 stage arrays
+lab.files;                            // Map<filename, Uint8Array | Float32Array>
+```
+
+For manual control on a fresh page:
+
+```js
+await ssr_variance_ready;
+await ssr_variance_lab.step(99);
+await ssr_variance_lab.step(1, true);  // submit frame 100 and capture it
+await ssr_variance_lab.step(15, true); // capture every frame from 101 through 115
+```
+
+`step(n, true)` records each of its n frames. The standard `run()` additionally
+calculates statistics and fills the page's results. Operations are serialized;
+overlapping calls are rejected. Restarting or changing a control reloads the page,
+giving every comparison a fresh renderer and the same frame-index sequence.
+Appending `?run` runs the standard capture automatically. `spatial=off`,
+`temporal=off`, `jitter=on`, and `taa=on` select controls in the query string.
+Use `?run&jitter=on&taa=on` to measure the full production jitter/TAA path.
+
+## Convergence
+
+**Measure convergence**, `?convergence`, or `await lab.convergence()` on a fresh page
+records frames 4, 8, 16, 32, 64, 100, 128, 256, and 512. It then averages the
+pre-temporal input from frames 513–1536 into a separate float32 GPU texture. This
+reference is never fed into the renderer. The table compares each checkpoint's
+temporal and post-spatial output with that 1,024-sample mean, using linear luminance
+RMSE and signed bias over the same reflection rectangle.
+
+This catches a darkened or frozen output that scores well on temporal variance.
+The reference estimates the prefilter's expected output; it is not ray-traced
+ground truth and does not validate SSR visibility, ray reuse, or the prefilter's
+own bias. Finite reference noise also sets an error floor. This pixel-aligned
+comparison requires raster jitter off; the playground rejects it otherwise before
+submitting any frames. Production history is bounded at 128 frames to
+retain responsiveness, so convergence approaches a noise floor rather than an
+unbounded average. `convergence.json`, `reference.f32`, checkpoint PNGs, and stage
+arrays are available in `lab.files` after the run stops at frame 1536.
+
+## Outputs and measurement
+
+The playground copies resolve, spatial step 1, temporal reprojection, spatial step 2,
+spatial step 4, pre-TAA scene colour, and final linear scene colour after TAA using
+integer `textureLoad` calls before presentation.
+Copies run only on recorded frames. Disabling spatial filtering makes those stage
+captures refer to their bypass inputs. Resolve still performs its own ray reuse
+and roughness-dependent source mip sampling.
+
+Each displayed image is the actual canvas output copied immediately after render,
+before the browser can discard it. Select a thumbnail to download its PNG. The JSON
+download includes frame indices, controls, camera settings, and statistics. Full raw
+captures and per-pixel mean/variance maps are available as typed arrays in `lab.files`.
+An external driver can write each array directly, for example as a `fetch` request
+body. Captures stay in CPU memory without duplicating HDR arrays into Blob storage.
+RGBA captures are little-endian float32, row-major, top-left origin. SSR radiance
+alpha carries the shader's internal variance estimate; scene alpha is opacity.
+The mask uses 1 for upward-facing ground pixels and 0 elsewhere.
+
+Temporal variance is computed **per pixel** over all 16 linear Rec.709 luminance
+samples (0.2126 R + 0.7152 G + 0.0722 B), then averaged spatially. Population variance
+divides by 16; sample variance divides by 15. RMS temporal sigma is the square root
+of mean population variance. This is distinct from image contrast or the shader's
+alpha-channel estimate. Non-finite readback values fail the measurement.
+
+The JSON reports full-image, whole-ground, and reflection-region statistics. The
+reflection region is the fixed rectangle x=200…599, y=250…459 intersected with the
+frame-100 ground mask. It covers the main visible reflection, not its full rough
+tail. The heatmap uses a fixed 0…0.10 linear-luminance sigma scale. With raster jitter
+enabled, silhouette coverage can vary; the fixed-projection default avoids that
+confound. A lower variance alone does not prove better image quality: blurring can
+reduce variance while destroying reflected detail.

package/src/shade/playground/ssr_variance/capture.d.ts

@@ -0,0 +1,16 @@
+/** TAA-off currently leaves raster jitter active. Freeze only this lab's view before rasterization. */
+export class FixedProjection extends RenderExtension {
+    record(frame: any): void;
+}
+/** Exact textureLoad copies of production SSR stages, only on requested frames. */
+export class CaptureSSR extends RenderExtension {
+    constructor(device: any);
+    enabled: boolean;
+    textures: Map<any, any>;
+    device: any;
+    record(frame: any): void;
+    jitter: any[];
+    read(): Promise<{}>;
+}
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+//# sourceMappingURL=capture.d.ts.map

package/src/shade/playground/ssr_variance/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_variance/capture.js"],"names":[],"mappings":"AA6BA,uGAAuG;AACvG;IAGI,yBAKC;CACJ;AAED,mFAAmF;AACnF;IAKI,yBAAsD;IAFtD,iBAAgB;IAChB,wBAAqB;IACU,YAAoB;IACnD,yBAuCC;IArCG,cAA2C;IAsC/C,oBAMC;CACJ;gCA/F+B,6CAA6C"}