@woosh/meep-engine 3.47.0 → 3.50.0

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

@@ -1,246 +1,247 @@
-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(renderer);
-    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;
-});
+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";
+import { submit_frame } from "../submit_frame.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(renderer);
+    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;
+        // Counted once submitted: the first calls are refused while the renderer's prepared pipelines compile.
+        await submit_frame(renderer, camera, world.scene, 1 / 60);
+        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/submit_frame.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Draw one frame, and resolve once the renderer has submitted it — not once the GPU has finished it.
+ * What a page does when it counts frames exactly, or reads the canvas back before yielding.
+ *
+ * **A call is not a frame.** `Renderer.render` encodes nothing and answers `false` while the
+ * pipelines prepared ahead of use are still compiling — the ones `initialize` asked for, a few
+ * seconds on a cold profile. A page that treats `false` as a failure stops on its first frame; one
+ * that ignores it counts a frame that flushed no rows, ran no pass and captured nothing.
+ *
+ * A refused frame is tried again on the next task, which is when a compile's promise can land. A
+ * refusal with nothing compiling is a renderer that cannot draw at all — its device lost, or the
+ * renderer destroyed — and throws rather than waiting for ever.
+ *
+ * The frame that is finally submitted is drawn by a `render` call that returned `true` in the same
+ * task this resolves in, so a caller continuing straight from the `await` still sees that frame's
+ * canvas: no task, and so no compositing, comes between them.
+ *
+ * @param {Renderer} renderer
+ * @param {PerspectiveCamera} camera
+ * @param {Scene} scene
+ * @param {number} [dt] simulation seconds the frame advances by
+ * @returns {Promise<void>}
+ */
+export function submit_frame(renderer: Renderer, camera: PerspectiveCamera, scene: Scene, dt?: number): Promise<void>;
+//# sourceMappingURL=submit_frame.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"submit_frame.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/submit_frame.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,+FAHW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAczB"}

package/src/shade/playground/submit_frame.js

@@ -0,0 +1,36 @@
+/**
+ * Draw one frame, and resolve once the renderer has submitted it — not once the GPU has finished it.
+ * What a page does when it counts frames exactly, or reads the canvas back before yielding.
+ *
+ * **A call is not a frame.** `Renderer.render` encodes nothing and answers `false` while the
+ * pipelines prepared ahead of use are still compiling — the ones `initialize` asked for, a few
+ * seconds on a cold profile. A page that treats `false` as a failure stops on its first frame; one
+ * that ignores it counts a frame that flushed no rows, ran no pass and captured nothing.
+ *
+ * A refused frame is tried again on the next task, which is when a compile's promise can land. A
+ * refusal with nothing compiling is a renderer that cannot draw at all — its device lost, or the
+ * renderer destroyed — and throws rather than waiting for ever.
+ *
+ * The frame that is finally submitted is drawn by a `render` call that returned `true` in the same
+ * task this resolves in, so a caller continuing straight from the `await` still sees that frame's
+ * canvas: no task, and so no compositing, comes between them.
+ *
+ * @param {Renderer} renderer
+ * @param {PerspectiveCamera} camera
+ * @param {Scene} scene
+ * @param {number} [dt] simulation seconds the frame advances by
+ * @returns {Promise<void>}
+ */
+export async function submit_frame(renderer, camera, scene, dt = 1 / 60) {
+    const graphics = renderer.graphics;
+
+    while (!renderer.render(camera, scene, dt)) {
+        if (graphics.render_pipelines.pending_count === 0 && graphics.compute_pipelines.pending_count === 0) {
+            throw new Error(
+                `the renderer refused a frame with no pipeline compiling — its device is lost, or it was destroyed`
+            );
+        }
+
+        await new Promise(resolve => setTimeout(resolve, 0));
+    }
+}