@woosh/meep-engine 3.18.0 → 3.19.0

package/src/shade/playground/ssr_variance/capture.js

@@ -0,0 +1,96 @@
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+import { FramePhase } from "../../renderer/extension/FramePhase.js";
+import { SceneColor } from "../../renderer/extension/SceneColor.js";
+import { ImageShader } from "../../renderer/shader/ImageShader.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { chunk_decode_g_buffer_normal } from "../../renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js";
+import { graph_image_pass } from "../../renderer/shader/graph/graph_image_pass.js";
+import { graph_import_texture } from "../../renderer/shader/graph/graph_import_texture.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../renderer/shader/ShaderDescriptor.js";
+import { GPUTextureContext } from "../../renderer/texture/GPUTextureContext.js";
+import { download_texture_data } from "../../renderer/texture/download_texture_data.js";
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup().addTexture('tSource', 'unfilterable-float').addTexture('tNormal', 'uint');
+const shader = new ImageShader({
+    descriptor: ShaderDescriptor.from({ label: 'SSR variance / capture', resources,
+        body: CodeChunk.from(/* language=WGSL */ `
+struct Capture { @location(0) radiance: vec4f, @location(1) mask: vec4f }
+@fragment fn main(@builtin(position) coord: vec4f) -> Capture {
+    let p = vec2i(coord.xy);
+    var output: Capture;
+    output.radiance = textureLoad(tSource, p, 0);
+    output.mask = vec4f(select(0.0, 1.0, decode_g_buffer_normal(textureLoad(tNormal, p, 0).xy).y > 0.99));
+    return output;
+}`, [chunk_decode_g_buffer_normal]) }),
+    targets: [{ format: 'rgba32float' }, { format: 'rgba32float' }],
+});
+
+/** TAA-off currently leaves raster jitter active. Freeze only this lab's view before rasterization. */
+export class FixedProjection extends RenderExtension {
+    name = 'SSR variance / fixed projection';
+    phase = FramePhase.FrameStart;
+    record(frame) {
+        frame.view.setJitter(0, 0);
+        frame.view.camera.setViewportOffset(0, 0);
+        frame.view.camera.update();
+        frame.view.update_uniforms();
+    }
+}
+
+/** Exact textureLoad copies of production SSR stages, only on requested frames. */
+export class CaptureSSR extends RenderExtension {
+    name = 'SSR variance / capture';
+    phase = FramePhase.BeforePresent;
+    enabled = false;
+    textures = new Map();
+    constructor(device) { super(); this.device = device; }
+    record(frame) {
+        if (!this.enabled) { return; }
+        this.jitter = Array.from(frame.view.jitter);
+        const passes = frame.graph.__pass_nodes;
+        const resolve = passes.find(p => p.name === 'SSR resolve / IBL');
+        const spatial1 = passes.find(p => p.name === 'SSR / spatial denoise with metadata');
+        const temporal = passes.find(p => p.name === 'SSR Reproject');
+        const spatial = passes.filter(p => p.name === 'SSR / spatial denoise');
+        const taa = passes.find(p => p.name === 'TAA');
+        if (!resolve || !temporal) { throw new Error('SSR stages missing from the frame graph'); }
+        const resolved = resolve.data['@output'][0];
+        const reprojected = temporal.data['@output'][0];
+        const stages = {
+            resolve: resolved,
+            spatial1: spatial1?.data['@output'][0] ?? resolved,
+            temporal: reprojected,
+            spatial2: spatial[0]?.data['@output'][0] ?? reprojected,
+            spatial4: spatial[1]?.data['@output'][0] ?? reprojected,
+            'pre-taa': taa?.data.ColourTexture ?? frame.get(SceneColor).color,
+            scene: frame.get(SceneColor).color,
+        };
+        const [width, height] = frame.resolution;
+        const texture = name => {
+            let t = this.textures.get(name);
+            if (!t || t.width !== width || t.height !== height) {
+                t?.destroy();
+                t = GPUTextureContext.fromTexture(this.device.createTexture({
+                    label: `SSR variance / ${name}`, size: [width, height, 1], format: 'rgba32float',
+                    usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
+                }), this.device);
+                this.textures.set(name, t);
+            }
+            return graph_import_texture(frame.graph, t, `SSR variance / ${name}`);
+        };
+        let mask = texture('mask');
+        for (const [name, handle] of Object.entries(stages)) {
+            [, mask] = graph_image_pass({ graph: frame.graph, shader,
+                inputs: { tSource: handle, tNormal: resolve.data.tNormal }, output: [texture(name), mask] });
+        }
+    }
+    async read() {
+        const result = {};
+        for (const [name, texture] of this.textures) {
+            result[name] = await download_texture_data({ device: this.device, source: texture.gpu_texture });
+        }
+        return result;
+    }
+}

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

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SSR variance lab</title><style>
+body{margin:24px;background:#14161a;color:#e7e9ee;font:14px system-ui}h1{font-size:24px;margin-bottom:8px}p{color:#acb5c5;max-width:900px}button,select,a{font:inherit}button,select{padding:8px;background:#29313e;color:inherit;border:1px solid #4b586d;border-radius:4px}button:disabled{opacity:.45}a{color:#9ac9ff}#view{display:block;width:800px;max-width:100%;height:auto;background:#08090a;margin:18px 0}#status{white-space:pre-wrap}table{border-collapse:collapse;font-variant-numeric:tabular-nums}td,th{padding:8px 14px;border-bottom:1px solid #394150;text-align:right}td:first-child,th:first-child{text-align:left}.frames{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:12px;max-width:1200px}.frames img{width:100%}figure{margin:0}figcaption{padding:5px}#heatmap{width:800px;max-width:100%}.error{color:#ff9a9a}
+</style></head><body>
+<h1>SSR variance lab</h1>
+<p>One ground plane · roughness 0.30 · metallic 1 · textured emissive card · fixed camera and exposure. Starts at frame zero. Rendering advances only when requested.</p>
+<label>Spatial <select id="spatial"><option value="on">On</option><option value="off">Off</option></select></label>
+<label>Temporal <select id="temporal"><option value="on">On</option><option value="off">Off</option></select></label>
+<label>Raster jitter <select id="jitter"><option value="off">Off</option><option value="on">On</option></select></label>
+<label>Main TAA <select id="taa"><option value="off">Off</option><option value="on">On</option></select></label>
+<button id="step" disabled>Step one frame</button> <button id="run" disabled>Capture frames 100–115</button>
+<button id="restart">Restart at frame zero</button>
+<button id="converge" disabled>Measure convergence</button>
+<canvas id="view" width="800" height="500"></canvas><div id="status">Initializing…</div>
+<div id="results" hidden>
+<p>Per-pixel temporal luminance variance, measured in linear HDR across 16 samples. Table: fixed reflection rectangle intersected with upward-facing ground pixels. Population variance uses ÷16; the JSON also includes sample variance (÷15), whole-ground and full-image measurements.</p>
+<table><thead><tr><th>Stage</th><th>Mean variance</th><th>RMS σ</th><th>95th percentile σ</th><th>Mean peak-to-peak</th></tr></thead><tbody id="metrics"></tbody></table>
+<p><a id="download">Download measurements JSON</a></p>
+<p>Final scene temporal standard deviation. Fixed scale: black = 0, yellow = 0.10 linear luminance. Red outline = measurement rectangle.</p><canvas id="heatmap" width="800" height="500"></canvas>
+<p>Recorded canvas output. Select a frame to download its full-resolution PNG.</p><div id="frames" class="frames"></div>
+</div><div id="convergence-results" hidden><p>SSR error against a separate float32 average of 1,024 later pre-temporal samples (frames 513–1536). The reference is never fed into the rendered image. This measures convergence to the prefilter's mean, not physical ground truth.</p><table><thead><tr><th>Frame</th><th>Input RMSE</th><th>Temporal RMSE</th><th>After spatial RMSE</th><th>Temporal bias</th></tr></thead><tbody id="convergence-metrics"></tbody></table><p><a id="convergence-download">Download convergence JSON</a></p></div><script type="module" src="./main.js"></script></body></html>

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

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

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

package/src/shade/playground/ssr_variance/main.js

@@ -0,0 +1,246 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { ShadeIndirectLightingMode } from "../../renderer/ShadeIndirectLightingMode.js";
+import { CaptureSSR, FixedProjection } from "./capture.js";
+import { create_scene } from "./scene.js";
+import { measure_variance } from "./statistics.js";
+import { ReflectionReference, reflection_error } from "./reference.js";
+
+const element = id => document.getElementById(id);
+const params = new URLSearchParams(location.search);
+const report = text => { element('status').textContent = text; };
+function png(canvas) {
+    const url = canvas.toDataURL('image/png');
+    return { url, bytes: Uint8Array.from(atob(url.split(',')[1]), c => c.charCodeAt(0)) };
+}
+function json_download(id, name, value, files) {
+    const json = JSON.stringify(value, null, 2);
+    files.set(name, new TextEncoder().encode(json));
+    element(id).href = `data:application/json;charset=utf-8,${encodeURIComponent(json)}`;
+    element(id).download = name;
+}
+function restart(mode) {
+    const query = new URLSearchParams(Object.fromEntries(['spatial', 'temporal', 'jitter', 'taa'].map(name => [name, element(name).value])));
+    if (mode) { query.set(mode, ''); }
+    location.search = query.toString();
+}
+element('restart').onclick = () => restart();
+for (const name of ['spatial', 'temporal', 'jitter', 'taa']) {
+    element(name).value = name === 'jitter' || name === 'taa' ? (params.get(name) === 'on' ? 'on' : 'off') : (params.get(name) === 'off' ? 'off' : 'on');
+    element(name).onchange = () => restart();
+}
+
+async function start() {
+    const canvas = element('view');
+    const renderer = new Renderer();
+    await renderer.initialize({ context: canvas.getContext('webgpu'), pixelRatio: 1 });
+    renderer.feature_ssr_enabled = true;
+    renderer.indirect_lighting_mode = ShadeIndirectLightingMode.IBL;
+    for (const name of ['taa', 'ssao', 'bloom', 'sharpening', 'motion_blur', 'automatic_exposure']) {
+        renderer[`feature_${name}_enabled`] = false;
+    }
+    renderer.exposure_compensation = 1;
+    renderer.feature_taa_enabled = element('taa').value === 'on';
+    renderer.internal_resolution_scale = 1;
+    renderer.ssr.spatial_denoising_enabled = element('spatial').value === 'on';
+    renderer.ssr.reprojection_mode = element('temporal').value === 'off' ? 2 : 0;
+    const world = await create_scene();
+    const camera = new PerspectiveCamera();
+    camera.near = 0.1; camera.far = 50; camera.fov = 50 * Math.PI / 180;
+    camera.aspect = canvas.width / canvas.height;
+    camera.transform.setTranslation(0, 3.2, 7);
+    camera.transform.lookAt(new Vector3(0, 0.2, -2));
+    camera.transform.updateMatrix();
+    renderer.resize(canvas.width, canvas.height);
+    const device = renderer.graphics.device;
+    let failure, busy = false, frame_count = 0;
+    const fail = error => {
+        failure = error; report(error.message ?? String(error));
+        element('status').classList.add('error'); console.error(error);
+        element('step').disabled = element('run').disabled = element('converge').disabled = true;
+    };
+    device.addEventListener('uncapturederror', event => fail(event.error));
+    device.lost.then(info => fail(new Error(`GPU device lost: ${info.message}`)));
+    const capture = new CaptureSSR(device);
+    const reference = new ReflectionReference(device);
+    renderer.add_extension(reference);
+    if (element('jitter').value === 'off') { renderer.add_extension(new FixedProjection()); }
+    renderer.add_extension(capture);
+    const frames = [], files = new Map();
+    // A run owns hundreds of MB of HDR captures. Release them when navigating
+    // between controls, including when the browser keeps a page in its back cache.
+    addEventListener('pagehide', () => {
+        frames.length = 0; files.clear();
+        renderer.destroy(); device.destroy();
+    });
+    addEventListener('pageshow', event => { if (event.persisted) { location.reload(); } });
+    async function render_frame(record = false) {
+        if (failure) { throw failure; }
+        capture.enabled = record;
+        const rendered = renderer.render(camera, world.scene, 1 / 60);
+        if (rendered === false) { throw new Error('Renderer did not submit the requested frame'); }
+        frame_count++;
+        if (renderer.frame_count !== frame_count) { throw new Error('Renderer frame count diverged from the experiment'); }
+        // Snapshot before yielding: the browser may discard the presented canvas after compositing.
+        let display;
+        if (record) {
+            display = document.createElement('canvas'); display.width = canvas.width; display.height = canvas.height;
+            display.getContext('2d').drawImage(canvas, 0, 0);
+        }
+        await device.queue.onSubmittedWorkDone();
+        if (failure) { throw failure; }
+        if (record) {
+            const stages = await capture.read();
+            const output = png(display);
+            const frame = { frame: frame_count, ssr_frame_index: renderer.ssr.frame_index, jitter: capture.jitter, stages, png: output.bytes, png_url: output.url };
+            frames.push(frame);
+            files.set(`frame-${frame_count}.png`, output.bytes);
+            for (const [name, data] of Object.entries(stages)) {
+                // Keep one CPU copy. Hundreds of HDR blobs can exhaust the browser's
+                // disk-backed Blob quota before a batch exporter gets to read them.
+                files.set(`frame-${frame_count}-${name}.f32`, data);
+            }
+        }
+        capture.enabled = false;
+        report(`Frame ${frame_count} · ${frames.length} captures · idle between steps`);
+        return frame_count;
+    }
+    async function exclusive(action) {
+        if (busy) { throw new Error('A render operation is already running'); }
+        busy = true;
+        for (const id of ['step', 'run', 'spatial', 'temporal', 'jitter', 'taa', 'restart', 'converge']) { element(id).disabled = true; }
+        try { return await action(); }
+        catch (error) { fail(error); throw error; }
+        finally {
+            busy = false;
+            for (const id of ['step', 'run', 'spatial', 'temporal', 'jitter', 'taa', 'restart', 'converge']) { element(id).disabled = false; }
+            if (failure) { element('step').disabled = element('run').disabled = element('converge').disabled = true; }
+        }
+    }
+    const step = (n = 1, record = false) => exclusive(async () => {
+        if (!Number.isSafeInteger(n) || n < 1) { throw new Error('Step count must be a positive integer'); }
+        for (let i = 0; i < n; i++) { await render_frame(record); }
+        return frame_count;
+    });
+    async function run() {
+        if (frame_count !== 0) { throw new Error('Restart at frame zero before a measurement run'); }
+        return exclusive(async () => {
+            // No initial render, animation loop, or readback-only render is hidden in these counts.
+            for (let i = 1; i <= 115; i++) { await render_frame(i >= 100); }
+            const summary = {
+                width: canvas.width, height: canvas.height, frames: frames.map(f => f.frame),
+                ssr_frame_indices: frames.map(f => f.ssr_frame_index), dt: 1 / 60,
+                raster_jitter: frames.map(f => f.jitter),
+                automatic_exposure: false, exposure_compensation: 1,
+                roughness: 0.3, metallic: 1, spatial: renderer.ssr.spatial_denoising_enabled,
+                temporal: renderer.ssr.reprojection_mode !== 2, taa: renderer.feature_taa_enabled,
+                camera: { position: [0, 3.2, 7], target: [0, 0.2, -2], fov_degrees: 50 },
+                raw_format: 'Little-endian float32 RGBA, row-major, top-left origin. SSR radiance alpha is internal variance; scene alpha is opacity; mask is ground=1 elsewhere=0.',
+                variance_definition: 'Per-pixel Rec.709 linear luminance population variance across frames 100–115 (divide by 16). Spatial mean of those variances in each region.',
+                stages: {},
+            };
+            let scene_measurement;
+            for (const name of Object.keys(frames[0].stages).filter(n => n !== 'mask')) {
+                const measurement = measure_variance(frames.map(f => f.stages[name]), frames[0].stages.mask, canvas.width, canvas.height);
+                summary.roi = measurement.roi;
+                summary.stages[name] = measurement.summary;
+                files.set(`${name}-mean-luminance.f32`, measurement.mean);
+                files.set(`${name}-variance.f32`, measurement.variance);
+                if (name === 'scene') { scene_measurement = measurement; }
+                const r = measurement.summary.reflection;
+                const row = document.createElement('tr');
+                for (const value of [name, r.mean_population_variance.toExponential(5), r.rms_temporal_sigma.toFixed(6), r.p95_temporal_sigma.toFixed(6), r.mean_peak_to_peak.toFixed(6)]) {
+                    const cell = document.createElement('td'); cell.textContent = value; row.append(cell);
+                }
+                element('metrics').append(row);
+            }
+            const heatmap = element('heatmap'), ctx = heatmap.getContext('2d');
+            const image = ctx.createImageData(canvas.width, canvas.height);
+            for (let p = 0; p < scene_measurement.variance.length; p++) {
+                const v = Math.min(1, Math.sqrt(scene_measurement.variance[p]) / 0.1);
+                image.data[p * 4] = 255 * Math.min(1, v * 2);
+                image.data[p * 4 + 1] = 255 * v;
+                image.data[p * 4 + 2] = 40 * v; image.data[p * 4 + 3] = 255;
+            }
+            ctx.putImageData(image, 0, 0);
+            const roi = summary.roi;
+            ctx.strokeStyle = '#ff4444'; ctx.strokeRect(roi.x, roi.y, roi.width, roi.height);
+            files.set('scene-temporal-sigma.png', png(heatmap).bytes);
+            json_download('download', 'measurements.json', summary, files);
+            for (const frame of frames) {
+                const figure = document.createElement('figure'), link = document.createElement('a'), img = document.createElement('img'), caption = document.createElement('figcaption');
+                img.src = link.href = frame.png_url; img.alt = `Frame ${frame.frame}`;
+                link.download = `frame-${frame.frame}.png`; link.append(img); caption.textContent = `Frame ${frame.frame}`;
+                figure.append(link, caption); element('frames').append(figure);
+            }
+            element('results').hidden = false;
+            lab.summary = summary;
+            report(`Complete · exactly 115 submitted frames · 16 captures (100–115) · renderer stopped`);
+            return summary;
+        });
+    }
+    async function convergence() {
+        if (frame_count !== 0) { throw new Error('Restart at frame zero before measuring convergence'); }
+        if (element('jitter').value !== 'off') {
+            const message = 'Convergence requires raster jitter off so checkpoints and reference use the same pixel grid.';
+            report(message);
+            throw new Error(message);
+        }
+        return exclusive(async () => {
+            const checkpoints = [4, 8, 16, 32, 64, 100, 128, 256, 512];
+            try {
+                for (let i = 1; i <= 1536; i++) {
+                    reference.enabled = i > 512;
+                    await render_frame(checkpoints.includes(i));
+                    report(i <= 512 ? `Convergence · frame ${i}/512` : `Building separate reference · ${i - 512}/1024 samples`);
+                }
+            } finally { reference.enabled = false; }
+            const target = await reference.read();
+            const mask = frames.at(-1).stages.mask;
+            const summary = { width: canvas.width, height: canvas.height, checkpoints,
+                ssr_frame_indices: frames.map(f => f.ssr_frame_index), dt: 1 / 60,
+                reference_frames: [513, 1536], reference_sample_count: reference.count,
+                automatic_exposure: false, exposure_compensation: 1,
+                roughness: 0.3, metallic: 1, spatial: renderer.ssr.spatial_denoising_enabled,
+                temporal: renderer.ssr.reprojection_mode !== 2,
+                taa: renderer.feature_taa_enabled, raster_jitter: element('jitter').value,
+                camera: { position: [0, 3.2, 7], target: [0, 0.2, -2], fov_degrees: 50 },
+                definition: 'Per-pixel linear-luminance error in the reflection ROI against the unrectified float32 mean of pre-temporal samples from later frames. The reference is never fed into SSR.',
+                samples: frames.map(frame => ({ frame: frame.frame,
+                    input: reflection_error(frame.stages.spatial1, target, mask, canvas.width, canvas.height),
+                    temporal: reflection_error(frame.stages.temporal, target, mask, canvas.width, canvas.height),
+                    spatial: reflection_error(frame.stages.spatial4, target, mask, canvas.width, canvas.height) })),
+            };
+            files.set('reference.f32', target);
+            json_download('convergence-download', 'convergence.json', summary, files);
+            for (const sample of summary.samples) {
+                const row = document.createElement('tr');
+                for (const value of [sample.frame, sample.input.rmse.toFixed(6), sample.temporal.rmse.toFixed(6), sample.spatial.rmse.toFixed(6), sample.temporal.bias.toFixed(6)]) {
+                    const cell = document.createElement('td'); cell.textContent = String(value); row.append(cell);
+                }
+                element('convergence-metrics').append(row);
+            }
+            element('convergence-results').hidden = false;
+            lab.summary = summary;
+            report('Convergence complete · 9 checkpoints · 1,024 later reference samples · frame 1536 · renderer stopped');
+            return summary;
+        });
+    }
+    const lab = globalThis.ssr_variance_lab = {
+        renderer, camera, world, step, run, convergence, frames, files, get frame_count() { return frame_count; },
+    };
+    element('step').disabled = element('run').disabled = false;
+    element('converge').disabled = false;
+    element('converge').onclick = () => frame_count === 0 ? convergence().catch(() => {}) : restart('convergence');
+    element('step').onclick = () => step().catch(() => {});
+    element('run').onclick = () => frame_count === 0 ? run().catch(() => {}) : restart('run');
+    report('Ready · frame 0 · no frames submitted');
+    if (params.has('convergence')) { await convergence(); }
+    else if (params.has('run')) { await run(); }
+    return lab;
+}
+globalThis.ssr_variance_ready = start().catch(error => {
+    report(error.message ?? String(error)); element('status').classList.add('error'); console.error(error);
+    throw error;
+});

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

@@ -0,0 +1,18 @@
+export function reflection_error(sample: any, reference: any, mask: any, width: any, height: any): {
+    pixels: number;
+    mse: number;
+    rmse: number;
+    bias: number;
+};
+/** Unclipped float32 average of later pre-temporal samples, never fed into rendering. */
+export class ReflectionReference extends RenderExtension {
+    constructor(device: any);
+    enabled: boolean;
+    count: number;
+    textures: any[];
+    device: any;
+    record(frame: any): void;
+    read(): Promise<TypedArray>;
+}
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+//# sourceMappingURL=reference.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_variance/reference.js"],"names":[],"mappings":"AA8DA;;;;;EAeC;AAjDD,yFAAyF;AACzF;IAKI,yBAAsD;IAHtD,iBAAgB;IAChB,cAAU;IACV,gBAAc;IACiB,YAAoB;IACnD,yBAmBC;IACD,4BAIC;CACJ;gCA5D+B,6CAA6C"}

package/src/shade/playground/ssr_variance/reference.js

@@ -0,0 +1,78 @@
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+import { ImageShader } from "../../renderer/shader/ImageShader.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { ShaderDescriptor } from "../../renderer/shader/ShaderDescriptor.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
+import { f32 } from "../../renderer/shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { graph_image_pass } from "../../renderer/shader/graph/graph_image_pass.js";
+import { graph_import_texture } from "../../renderer/shader/graph/graph_import_texture.js";
+import { GPUTextureContext } from "../../renderer/texture/GPUTextureContext.js";
+import { download_texture_data } from "../../renderer/texture/download_texture_data.js";
+
+const settings = WebGPUStruct.from({ count: f32 });
+const resources = new ShaderResourceSetDescriptor();
+resources.setImmediate('settings', settings);
+resources.createGroup().addTexture('tInput', 'unfilterable-float').addTexture('tPrevious', 'unfilterable-float');
+const shader = new ImageShader({ descriptor: ShaderDescriptor.from({
+    label: 'SSR lab / later-sample reference', resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@fragment fn main(@builtin(position) coord: vec4f) -> @location(0) vec4f {
+    let p = vec2i(coord.xy);
+    let sample = textureLoad(tInput, p, 0);
+    if (settings.count <= 1.0) { return sample; }
+    let previous = textureLoad(tPrevious, p, 0);
+    return previous + (sample - previous) / settings.count;
+}`, [settings.declaration_chunk]),
+}), targets: [{ format: 'rgba32float' }] });
+
+/** Unclipped float32 average of later pre-temporal samples, never fed into rendering. */
+export class ReflectionReference extends RenderExtension {
+    name = 'SSR lab / later-sample reference';
+    enabled = false;
+    count = 0;
+    textures = [];
+    constructor(device) { super(); this.device = device; }
+    record(frame) {
+        if (!this.enabled) { return; }
+        const temporal = frame.graph.__pass_nodes.find(p => p.name === 'SSR Reproject');
+        if (!temporal) { throw new Error('SSR is required for a reflection reference'); }
+        if (!this.textures.length) {
+            for (let i = 0; i < 2; i++) {
+                this.textures.push(GPUTextureContext.fromTexture(this.device.createTexture({
+                    size: [frame.resolution[0], frame.resolution[1], 1], format: 'rgba32float',
+                    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
+                }), this.device));
+            }
+        }
+        const index = this.count % 2;
+        const previous = graph_import_texture(frame.graph, this.textures[1 - index], 'SSR reference previous');
+        const output = graph_import_texture(frame.graph, this.textures[index], 'SSR reference output');
+        graph_image_pass({ graph: frame.graph, shader,
+            inputs: { tInput: temporal.data.tInput, tPrevious: previous, settings: { count: this.count + 1 } },
+            output: [output] });
+        this.count++;
+    }
+    async read() {
+        if (!this.count) { throw new Error('Reference has no samples'); }
+        return download_texture_data({ device: this.device,
+            source: this.textures[(this.count - 1) % 2].gpu_texture });
+    }
+}
+
+export function reflection_error(sample, reference, mask, width, height) {
+    let count = 0, squared_error = 0, bias = 0;
+    for (let y = Math.floor(height * 0.5); y < Math.floor(height * 0.92); y++) {
+        for (let x = Math.floor(width * 0.25); x < Math.floor(width * 0.75); x++) {
+            const p = (y * width + x) * 4;
+            if (mask[p] <= 0.5) { continue; }
+            const error = (sample[p] - reference[p]) * 0.2126
+                + (sample[p + 1] - reference[p + 1]) * 0.7152
+                + (sample[p + 2] - reference[p + 2]) * 0.0722;
+            if (!Number.isFinite(error)) { throw new Error('Non-finite convergence sample'); }
+            squared_error += error * error; bias += error; count++;
+        }
+    }
+    if (!count) { throw new Error('No reflection pixels in convergence sample'); }
+    return { pixels: count, mse: squared_error / count, rmse: Math.sqrt(squared_error / count), bias: bias / count };
+}

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

@@ -0,0 +1,11 @@
+/** Two quads. The cross is a texture, with no extra geometry or surface-normal edges. */
+export function create_scene(): Promise<{
+    scene: Scene;
+    ground: Mesh;
+    card: Mesh;
+    ground_material: StandardShadeMaterial;
+}>;
+import { Scene } from "../../renderer/scene/Scene.js";
+import { Mesh } from "../../renderer/scene/Mesh.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+//# sourceMappingURL=scene.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_variance/scene.js"],"names":[],"mappings":"AAeA,yFAAyF;AACzF;;;;;GA4CC;sBAnDqB,+BAA+B;qBADhC,8BAA8B;sCADb,kDAAkD"}

package/src/shade/playground/ssr_variance/scene.js

@@ -0,0 +1,61 @@
+import { Color } from "../../../core/color/Color.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { MeshoptClusterizer } from "../../renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js";
+import { make_plane_geometry } from "../../renderer/geometry/primitives/make_plane_geometry.js";
+import { MeshletGeometry } from "../../renderer/geometry/MeshletGeometry.js";
+import { meshlet_geometry_build_from_geometry } from "../../renderer/geometry/meshlet_geometry_build_from_geometry.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import { Mesh } from "../../renderer/scene/Mesh.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { ColorSpace } from "../../renderer/texture/ColorSpace.js";
+import { ShadeTexture } from "../../renderer/texture/ShadeTexture.js";
+import { ShadeImage } from "../../renderer/texture/source/ShadeImage.js";
+import { make_flat_environment } from "../skinned_blas_refit/flat_environment.js";
+
+/** Two quads. The cross is a texture, with no extra geometry or surface-normal edges. */
+export async function create_scene() {
+    await MeshoptClusterizer.ready;
+    const scene = new Scene();
+    const quad = (name, width, height, material) => {
+        const geometry = new MeshletGeometry();
+        meshlet_geometry_build_from_geometry(make_plane_geometry(width, height), geometry);
+        const mesh = Mesh.from(geometry, material);
+        mesh.name = name;
+        scene.add(mesh);
+        return mesh;
+    };
+    const ground_material = new StandardShadeMaterial();
+    ground_material.diffuse_color.copy(new Color(0.85, 0.85, 0.85));
+    ground_material.roughness_factor = 0.3;
+    ground_material.metallic_factor = 1;
+    const ground = quad('Ground / roughness 0.30', 18, 18, ground_material);
+    const rotation = Quaternion.fromAxisAngle(Vector3.right, -Math.PI / 2);
+    ground.transform_local.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
+    ground.transform_local.setTranslation(0, 0, -2);
+    ground.updateMatrices();
+
+    const canvas = document.createElement('canvas');
+    canvas.width = canvas.height = 512;
+    const ctx = canvas.getContext('2d');
+    ctx.fillStyle = '#181818'; ctx.fillRect(0, 0, 512, 512);
+    ctx.fillStyle = '#f4f4f4';
+    ctx.fillRect(216, 64, 80, 384); ctx.fillRect(64, 216, 384, 80);
+    // Small inset bars expose detail loss at a second scale.
+    ctx.fillStyle = '#ff8822'; ctx.fillRect(56, 56, 96, 24);
+    ctx.fillStyle = '#33bbff'; ctx.fillRect(360, 408, 96, 48);
+    const image = ShadeImage.fromImageBitmap(await createImageBitmap(canvas, { premultiplyAlpha: 'none' }));
+    image.color_space = ColorSpace.SRGB;
+    const pattern = ShadeTexture.from(image);
+    pattern.label = 'SSR variance / cross';
+    const card_material = new StandardShadeMaterial();
+    card_material.diffuse_color.copy(new Color(0, 0, 0));
+    card_material.texture_emissive = pattern;
+    card_material.emissive_factor.copy(new Color(1, 1, 1));
+    card_material.roughness_factor = 1;
+    const card = quad('Pattern card', 3, 3, card_material);
+    card.transform_local.setTranslation(0, 2, -2);
+    card.updateMatrices();
+    scene.lights.environment = make_flat_environment([0.025, 0.025, 0.025]);
+    return { scene, ground, card, ground_material };
+}

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

@@ -0,0 +1,44 @@
+/** Per-pixel temporal moments of linear Rec.709 luminance. No spatial pooling before variance. */
+export function measure_variance(samples: any, mask: any, width: any, height: any): {
+    mean: Float32Array;
+    variance: Float32Array;
+    roi: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    summary: {
+        all: {
+            pixels: number;
+            mean_luminance: number;
+            mean_population_variance: number;
+            mean_sample_variance: number;
+            rms_temporal_sigma: number;
+            p95_temporal_sigma: number;
+            mean_peak_to_peak: number;
+            max_peak_to_peak: number;
+        };
+        ground: {
+            pixels: number;
+            mean_luminance: number;
+            mean_population_variance: number;
+            mean_sample_variance: number;
+            rms_temporal_sigma: number;
+            p95_temporal_sigma: number;
+            mean_peak_to_peak: number;
+            max_peak_to_peak: number;
+        };
+        reflection: {
+            pixels: number;
+            mean_luminance: number;
+            mean_population_variance: number;
+            mean_sample_variance: number;
+            rms_temporal_sigma: number;
+            p95_temporal_sigma: number;
+            mean_peak_to_peak: number;
+            max_peak_to_peak: number;
+        };
+    };
+};
+//# sourceMappingURL=statistics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"statistics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_variance/statistics.js"],"names":[],"mappings":"AAAA,kGAAkG;AAClG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDC"}