@woosh/meep-engine 3.18.0 → 3.20.0

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"}

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

@@ -0,0 +1,51 @@
+/** Per-pixel temporal moments of linear Rec.709 luminance. No spatial pooling before variance. */
+export function measure_variance(samples, mask, width, height) {
+    if (samples.length < 2) { throw new Error('At least two samples are required'); }
+    const pixels = width * height;
+    if (mask.length !== pixels * 4 || samples.some(s => s.length !== pixels * 4)) {
+        throw new Error('Capture dimensions do not match');
+    }
+    const mean = new Float64Array(pixels), m2 = new Float64Array(pixels);
+    const minimum = new Float64Array(pixels).fill(Infinity), maximum = new Float64Array(pixels).fill(-Infinity);
+    for (let n = 0; n < samples.length; n++) {
+        const sample = samples[n];
+        for (let p = 0; p < pixels; p++) {
+            const i = p * 4;
+            if (![sample[i], sample[i + 1], sample[i + 2], sample[i + 3]].every(Number.isFinite)) {
+                throw new Error(`Non-finite capture at sample ${n}, pixel ${p}`);
+            }
+            const y = sample[i] * 0.2126 + sample[i + 1] * 0.7152 + sample[i + 2] * 0.0722;
+            const delta = y - mean[p];
+            mean[p] += delta / (n + 1);
+            m2[p] += delta * (y - mean[p]);
+            minimum[p] = Math.min(minimum[p], y); maximum[p] = Math.max(maximum[p], y);
+        }
+    }
+    const variance = Float32Array.from(m2, v => v / samples.length);
+    const summarize = predicate => {
+        const sigmas = [];
+        let variance_sum = 0, mean_sum = 0, range_sum = 0, max_range = 0;
+        for (let p = 0; p < pixels; p++) {
+            if (!predicate(p)) { continue; }
+            sigmas.push(Math.sqrt(variance[p])); variance_sum += variance[p]; mean_sum += mean[p];
+            const range = maximum[p] - minimum[p]; range_sum += range; max_range = Math.max(max_range, range);
+        }
+        sigmas.sort((a, b) => a - b);
+        const count = sigmas.length;
+        if (!count) { throw new Error('Empty measurement region'); }
+        return { pixels: count, mean_luminance: mean_sum / count,
+            mean_population_variance: variance_sum / count,
+            mean_sample_variance: variance_sum / count * samples.length / (samples.length - 1),
+            rms_temporal_sigma: Math.sqrt(variance_sum / count),
+            p95_temporal_sigma: sigmas[Math.ceil(count * 0.95) - 1],
+            mean_peak_to_peak: range_sum / count, max_peak_to_peak: max_range };
+    };
+    // Fixed screen rectangle shared by every stage/control, intersected with ground normals.
+    const roi = { x: Math.floor(width * 0.25), y: Math.floor(height * 0.50),
+        width: Math.floor(width * 0.5), height: Math.floor(height * 0.42) };
+    const ground = p => mask[p * 4] > 0.5;
+    return { mean: Float32Array.from(mean), variance, roi,
+        summary: { all: summarize(() => true), ground: summarize(ground),
+            reflection: summarize(p => ground(p) && p % width >= roi.x && p % width < roi.x + roi.width
+                && Math.floor(p / width) >= roi.y && Math.floor(p / width) < roi.y + roi.height) } };
+}

package/src/shade/renderer/geometry/Geometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Geometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/Geometry.js"],"names":[],"mappings":"4BA2BU,MAAM;;;;AAQhB;;GAEG;AACH;IAQI;;;;OAIG;IACH,iBAEC;IAED;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,YAFU,SAAS,EAAE,CAEL;IAEhB;;;OAGG;IACH,OAFU,SAAS,GAAC,IAAI,CAEX;IAEb;;;OAGG;IACH,cAFU,YAAY,CAEa;IACnC;;;OAGG;IACH,iBAFU,YAAY,CAEgB;IAEtC;;;OAGG;IACH,OAFU,MAAM,CAEM;IAOtB;;;;;;;;;;OAUG;IACH,sBAEC;IAED;;OAEG;IACH,8BAIC;IAGD;;;;OAIG;IACH,cAHW,MAAM,GAAC,aAAa,GAClB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,aAAa,GAClB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,aAAa,SACpB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,aAAa,GAClB,OAAO,CAInB;IAED;;;;OAIG;IACH,cAHW,QAAQ,GACN,OAAO,CAYnB;IAED,eAQC;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACL,SAAS,GAAC,SAAS,CAkB9B;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;OAGG;IACH,wBAFW,SAAS,QAQnB;IAED;;;OAGG;IACH,wBAFW,SAAS,QASnB;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACL,SAAS,GAAC,SAAS,CAiB9B;IAED;;;OAGG;IACH,kBAFY,MAAM,CAWjB;IAED;;;OAGG;IACH,iBAFY,MAAM,CAYjB;IAED;;;;OAIG;IACH,qBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAIC;IAED;;OAEG;IACH,mBASC;IAED,qBAIC;IAED;;OAEG;IACH,qCAoBC;IAED,8BAaC;IAED,8BAKC;IAED,2BAeC;IAED,sBAOC;IAED,uBA4BC;IAoFD,uBAOC;IAED,wBAWC;IAED;;;OAGG;IACH,YAFW,QAAQ,QAmBlB;IAED;;;OAGG;IACH,SAFY,QAAQ,CAQnB;IAED,eAEC;IAED;;;OAGG;IACH,iCAYC;IAGL;;;OAGG;IACH,qBAFU,OAAO,CAEY;;CAN5B;0BAvkByB,gBAAgB"}
+{"version":3,"file":"Geometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/Geometry.js"],"names":[],"mappings":"4BA4BU,MAAM;;;;AAQhB;;GAEG;AACH;IAQI;;;;OAIG;IACH,iBAEC;IAED;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,YAFU,SAAS,EAAE,CAEL;IAEhB;;;OAGG;IACH,OAFU,SAAS,GAAC,IAAI,CAEX;IAEb;;;OAGG;IACH,cAFU,YAAY,CAEa;IACnC;;;OAGG;IACH,iBAFU,YAAY,CAEgB;IAEtC;;;OAGG;IACH,OAFU,MAAM,CAEM;IAOtB;;;;;;;;;;OAUG;IACH,sBAEC;IAED;;OAEG;IACH,8BAIC;IAGD;;;;OAIG;IACH,cAHW,MAAM,GAAC,aAAa,GAClB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,aAAa,GAClB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,aAAa,SACpB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,aAAa,GAClB,OAAO,CAInB;IAED;;;;OAIG;IACH,cAHW,QAAQ,GACN,OAAO,CAYnB;IAED,eAQC;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACL,SAAS,GAAC,SAAS,CAkB9B;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;OAGG;IACH,wBAFW,SAAS,QAQnB;IAED;;;OAGG;IACH,wBAFW,SAAS,QASnB;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACL,SAAS,GAAC,SAAS,CAiB9B;IAED;;;OAGG;IACH,kBAFY,MAAM,CAWjB;IAED;;;OAGG;IACH,iBAFY,MAAM,CAYjB;IAED;;;;OAIG;IACH,qBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAIC;IAED;;OAEG;IACH,mBASC;IAED,qBAIC;IAED;;OAEG;IACH,qCAoBC;IAED,8BAaC;IAED,8BAKC;IAED,2BAeC;IAED,sBAOC;IAED,uBA4BC;IAoFD,uBAOC;IAED,wBAWC;IAED;;;OAGG;IACH,YAFW,QAAQ,QAelB;IAED;;;OAGG;IACH,SAFY,QAAQ,CAQnB;IAED,eAEC;IAED;;;OAGG;IACH,iCAYC;IAGL;;;OAGG;IACH,qBAFU,OAAO,CAEY;;CAN5B;0BAnkByB,gBAAgB"}

package/src/shade/renderer/geometry/Geometry.js

@@ -14,8 +14,9 @@ import {
 import {
     geometry_compute_vertex_normals_unindexed
 } from "../../../engine/graphics/geometry/buffered/geometry_compute_vertex_normals_unindexed.js";
-import { optional_equality } from "../../descriptor/util/optional_equality.js";
-import { optional_hash } from "../../descriptor/util/optional_hash.js";
+import { optional_clone } from "../../../core/model/object/optional_clone.js";
+import { optional_equality } from "../../../core/model/object/optional_equality.js";
+import { optional_hash } from "../../../core/model/object/optional_hash.js";
 import { Attribute } from "./Attribute.js";
 import { build_tangent_from_normal } from "./normals/build_tangent_from_normal.js";
 import { geometry_build_tangents } from "./normals/geometry_build_tangents.js";
@@ -551,11 +552,7 @@ export class Geometry {
 
         this.name = other.name;
 
-        if (other.index !== null) {
-            this.index = other.index.clone();
-        } else {
-            this.index = null;
-        }
+        this.index = optional_clone(other.index);
 
         this.attributes = other.attributes.map(a => a.clone());
 

package/src/shade/renderer/loader/gltf/tiny-gltf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tiny-gltf.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/loader/gltf/tiny-gltf.js"],"names":[],"mappings":"AA4UA;IAoEI;;;;;;;;;;;;;OAaG;IACH,+CAFU,aAAa,CAEgC;IA3BvD;;;;OAIG;IACH,qFAFW,qBAAqB,EAQ/B;IAjED,oBAA2B;IAE3B;;;;;;;;OAQG;IACH,iDAAmD;IAEnD;;;;;;;;;OASG;IACH,SAFU,IAAI,MAAM,EAAE,IAAI,GAAC,IAAI,GAAC,WAAW,CAAC,GAAC,SAAS,CAElC;IAqKpB;;;OAGG;IACH,iBAHW,MAAM,GACJ,QAAQ,QAAQ,CAAC,CAgB7B;IAED;;;;;;OAMG;IACH,4BAJW,WAAW,WACX,MAAM,GACL,QAAQ;QAAC,KAAK,CAAA;KAAC,MAAE,CAAC,CAM7B;IAED;;;;;;OAMG;IACH;;;mBALwC,EAAE;eAAO,EAAE;mBAAW,EAAE;iBAAS,EAAE;mBAAW,EAAE;kBAAW,EAAE;gBAAS,EAAE;gBAAQ,EAAE;gBAC/G,MAAM,gBACN,UAAU,GACT,QAAQ;QAAC,KAAK,CAAA;KAAC,MAAE,CAAC,CAiR7B;;CAGJ;8BAtyB6B,qDAAqD"}
+{"version":3,"file":"tiny-gltf.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/loader/gltf/tiny-gltf.js"],"names":[],"mappings":"AA4UA;IAoEI;;;;;;;;;;;;;OAaG;IACH,+CAFU,aAAa,CAEgC;IA3BvD;;;;OAIG;IACH,qFAFW,qBAAqB,EAQ/B;IAjED,oBAA2B;IAE3B;;;;;;;;OAQG;IACH,iDAAmD;IAEnD;;;;;;;;;OASG;IACH,SAFU,IAAI,MAAM,EAAE,IAAI,GAAC,IAAI,GAAC,WAAW,CAAC,GAAC,SAAS,CAElC;IAqKpB;;;OAGG;IACH,iBAHW,MAAM,GACJ,QAAQ,QAAQ,CAAC,CAgB7B;IAED;;;;;;OAMG;IACH,4BAJW,WAAW,WACX,MAAM,GACL,QAAQ;QAAC,KAAK,CAAA;KAAC,MAAE,CAAC,CAM7B;IAED;;;;;;OAMG;IACH;;;mBALwC,EAAE;eAAO,EAAE;mBAAW,EAAE;iBAAS,EAAE;mBAAW,EAAE;kBAAW,EAAE;gBAAS,EAAE;gBAAQ,EAAE;gBAC/G,MAAM,gBACN,UAAU,GACT,QAAQ;QAAC,KAAK,CAAA;KAAC,MAAE,CAAC,CAuR7B;;CAGJ;8BA5yB6B,qDAAqD"}

package/src/shade/renderer/loader/gltf/tiny-gltf.js

@@ -498,7 +498,7 @@ export class TinyGltf {
      * Read a KTX2 image into texels, transcoding it where its payload is Basis.
      *
      * @param {ArrayBuffer|Uint8Array} bytes the whole file
-     * @returns {ShadeTexelData}
+     * @returns {Promise<ShadeTexelData>}
      * @param {TextureRole} [role] what the image is for, which orders the candidate targets
      * @throws {Error} naming the feature, for a container this reader does not read
      */
@@ -811,7 +811,13 @@ export class TinyGltf {
         place_nodes(json);
 
         // Replace the resolved resources in the JSON structure.
-        const buffers = await Promise.all(pendingBuffers);
+        // Observe image failures while buffers are still loading. Native decompression can reject
+        // during another resource's I/O; deferring its handler until all buffers finish would leave
+        // that rejection unhandled (and could leave the load waiting indefinitely).
+        const [buffers, images] = await Promise.all([
+            Promise.all(pendingBuffers),
+            Promise.all(pendingImages),
+        ]);
 
         /*
          Views that some extension produces the bytes for become ordinary ones here, over decoded
@@ -827,7 +833,7 @@ export class TinyGltf {
         );
 
         json.buffers = buffers;
-        json.images = await Promise.all(pendingImages);
+        json.images = images;
 
         return json;
     }

package/src/shade/renderer/loader/usd/usd_decode_image.d.ts

@@ -13,17 +13,17 @@ export function decode_data_url(url: string): {
  *
  * Accepts anything `PNGReader` accepts; see the module comment for what that covers and how
  * other layouts are brought to RGBA8. Errors from the reader (bad signature, truncated stream,
- * corrupt deflate payload) propagate as thrown.
+ * corrupt deflate payload) reject the returned promise.
  *
  * @param {Uint8Array|ArrayBuffer} png_bytes
- * @returns {{ width: number, height: number, channels: number, pixels: Uint8Array }}
+ * @returns {Promise<{ width: number, height: number, channels: number, pixels: Uint8Array }>}
  */
-export function decode_png(png_bytes: Uint8Array | ArrayBuffer): {
+export function decode_png(png_bytes: Uint8Array | ArrayBuffer): Promise<{
     width: number;
     height: number;
     channels: number;
     pixels: Uint8Array;
-};
+}>;
 /**
  * Create a ShadeTexture from decoded image data.
  *

package/src/shade/renderer/loader/usd/usd_decode_image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usd_decode_image.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/loader/usd/usd_decode_image.js"],"names":[],"mappings":"AA4BA;;;;;GAKG;AACH,qCAHW,MAAM;cACQ,MAAM;UAAQ,UAAU;EAgChD;AAGD;;;;;;;;;GASG;AACH,sCAHW,UAAU,GAAC,WAAW;WACX,MAAM;YAAU,MAAM;cAAY,MAAM;YAAU,UAAU;EA0DjF;AAGD;;;;;GAKG;AACH,2DAHW;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACrE,YAAY,CAexB;6BAnI4B,+BAA+B"}
+{"version":3,"file":"usd_decode_image.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/loader/usd/usd_decode_image.js"],"names":[],"mappings":"AA4BA;;;;;GAKG;AACH,qCAHW,MAAM;cACQ,MAAM;UAAQ,UAAU;EAgChD;AAGD;;;;;;;;;GASG;AACH,sCAHW,UAAU,GAAC,WAAW;WACH,MAAM;YAAU,MAAM;cAAY,MAAM;YAAU,UAAU;GA0DzF;AAGD;;;;;GAKG;AACH,2DAHW;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACrE,YAAY,CAexB;6BAnI4B,+BAA+B"}