@woosh/meep-engine 3.47.0 → 3.49.0

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

@@ -0,0 +1,888 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { GPUProfileLevel } from "../../device/timing/profile/GPUProfileLevel.js";
+import { GPUProfileSession } from "../../device/timing/profile/GPUProfileSession.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { ShadeIndirectLightingMode } from "../../renderer/ShadeIndirectLightingMode.js";
+import { ContactShadowFlags } from "../../renderer/shadow/contact/shader_contact_shadow_wavefront.js";
+import { FrameRateMeter } from "../frame_rate_meter.js";
+import { install_profile_hotkey } from "../profile_hotkey.js";
+import { ContactMethod, ContactShadowLab } from "./ContactShadowLab.js";
+import { create_contact_scene } from "./scenes.js";
+import { ContactCombine } from "./shader_contact_lab_composite.js";
+import {
+    CONTACT_STAT_BAND_BASE,
+    CONTACT_STAT_BAND_COUNT,
+    CONTACT_STAT_BAND_STRIDE,
+    CONTACT_STAT_COUNT,
+    ContactStat
+} from "./shader_contact_lab_stats.js";
+
+const element = id => document.getElementById(id);
+
+const RUNNING = 'Running. Drag to orbit, right-drag to pan, wheel to zoom. T records a GPU profile.';
+
+/** Seconds of scene time per frame when a measurement drives the frames. */
+const FIXED_DT = 1 / 60;
+
+/**
+ * @param {string} text
+ * @param {boolean} [error]
+ */
+function report(text, error = false) {
+    const status = element('status');
+
+    status.textContent = text;
+    status.className = error ? 'fail' : '';
+}
+
+/**
+ * The counters of one or more frames as readable rates.
+ *
+ * @param {Float64Array|Uint32Array} s summed counters
+ * @param {number} frames how many frames they sum
+ */
+function summarise(s, frames) {
+    const per_frame = v => v / frames;
+    const percent = (a, b) => b > 0 ? 100 * a / b : 0;
+
+    return {
+        frames,
+        pixels: per_frame(s[ContactStat.Pixels]),
+        reference_shadowed: per_frame(s[ContactStat.ReferenceShadowed]),
+        shadow_map_missed: per_frame(s[ContactStat.ShadowMapMissed]),
+        gap_closed_percent: percent(s[ContactStat.Fixed], s[ContactStat.ShadowMapMissed]),
+        missed: per_frame(s[ContactStat.Missed]),
+        shadow_map_false: per_frame(s[ContactStat.ShadowMapFalse]),
+        false_shadow: per_frame(s[ContactStat.False]),
+        added_false: per_frame(s[ContactStat.AddedFalse]),
+        contact_shadowed: per_frame(s[ContactStat.ContactShadowed]),
+        darker_than_both: per_frame(s[ContactStat.DarkerThanBoth]),
+        mean_error_combined: s[ContactStat.CombinedError] / 255 / Math.max(1, s[ContactStat.Pixels]),
+        mean_error_shadow_map: s[ContactStat.ShadowMapError] / 255 / Math.max(1, s[ContactStat.Pixels]),
+        spurious_flips: per_frame(s[ContactStat.SpuriousFlips]),
+        shadow_map_spurious_flips: per_frame(s[ContactStat.ShadowMapSpuriousFlips]),
+        reference_flips: per_frame(s[ContactStat.ReferenceFlips]),
+        change: per_frame(s[ContactStat.CombinedChange]) / 255,
+        shadow_map_change: per_frame(s[ContactStat.ShadowMapChange]) / 255,
+        bands: summarise_bands(s, frames),
+    };
+}
+
+/**
+ * The depth-band counters: per band of view depth ([0, 2) m, [2, 4) m, … doubling), per frame.
+ *
+ * @param {Float64Array|Uint32Array} s
+ * @param {number} frames
+ */
+function summarise_bands(s, frames) {
+    const bands = [];
+
+    for (let band = 0; band < CONTACT_STAT_BAND_COUNT; band++) {
+        const base = CONTACT_STAT_BAND_BASE + band * CONTACT_STAT_BAND_STRIDE;
+        const reference_shadowed = s[base] / frames;
+
+        if (reference_shadowed === 0 && s[base + 3] === 0) {
+            continue;
+        }
+
+        bands.push({
+            metres: band === 0 ? '0-2' : `${2 ** band}-${band === CONTACT_STAT_BAND_COUNT - 1 ? 'inf' : 2 ** (band + 1)}`,
+            reference_shadowed,
+            shadow_map_missed: s[base + 1] / frames,
+            fixed: s[base + 2] / frames,
+            added_false: s[base + 3] / frames,
+        });
+    }
+
+    return bands;
+}
+
+/**
+ * @param {ReturnType<typeof summarise>} r
+ * @returns {string[]}
+ */
+function describe_summary(r) {
+    return [
+        `reference shadowed   ${r.reference_shadowed.toFixed(0)} px`,
+        `map missed (gaps)    ${r.shadow_map_missed.toFixed(0)} px`,
+        `  closed by contact  ${r.gap_closed_percent.toFixed(1)} %`,
+        `still missed         ${r.missed.toFixed(0)} px`,
+        `false, total         ${r.false_shadow.toFixed(0)} px`,
+        `  added by contact   ${r.added_false.toFixed(0)} px`,
+        `darker than both     ${r.darker_than_both.toFixed(0)} px`,
+        `mean |error|         ${r.mean_error_combined.toFixed(4)} (map ${r.mean_error_shadow_map.toFixed(4)})`,
+    ];
+}
+
+/**
+ * A profile session that also keeps every span's duration by frame, for an in-page A/B.
+ */
+class SpanCollector extends GPUProfileSession {
+    /** @type {Map<number, Map<string, number>>} frame index → label → nanoseconds */
+    spans = new Map();
+
+    /** @type {Map<number, number>} frame index → whole frame's GPU span, nanoseconds */
+    frames = new Map();
+
+    record_frame(frame) {
+        const by_label = new Map();
+
+        let begin = Infinity;
+        let end = -Infinity;
+
+        for (const span of frame.spans) {
+            by_label.set(span.label, (by_label.get(span.label) ?? 0) + span.duration_ns);
+
+            begin = Math.min(begin, span.t_begin_ns);
+            end = Math.max(end, span.t_begin_ns + span.duration_ns);
+        }
+
+        this.spans.set(frame.frame_index, by_label);
+        this.frames.set(frame.frame_index, end - begin);
+
+        super.record_frame(frame);
+    }
+}
+
+/**
+ * @param {number[]} values
+ */
+function median(values) {
+    const sorted = values.slice().sort((a, b) => a - b);
+
+    return sorted.length === 0 ? NaN : sorted[sorted.length >> 1];
+}
+
+export async function start() {
+    const canvas = element('view');
+
+    const camera = new PerspectiveCamera();
+
+    camera.near = 0.1;
+    camera.far = 400;
+    camera.fov = 55 * Math.PI / 180;
+
+    const controller = new OrbitalCameraController(camera, canvas);
+
+    const renderer = new Renderer();
+
+    report('Acquiring GPU…');
+
+    await renderer.initialize({ context: canvas.getContext('webgpu'), pixelRatio: 1 });
+
+    renderer.indirect_lighting_mode = ShadeIndirectLightingMode.IBL;
+    renderer.feature_shadows_enabled = true;
+    renderer.feature_automatic_exposure_enabled = false;
+    renderer.exposure_compensation = 0.5;
+    // AO darkens the same contacts and would hide what the sun's term does; it is not under test
+    renderer.feature_ssao_enabled = false;
+    renderer.feature_bloom_enabled = false;
+
+    const lab = new ContactShadowLab(renderer);
+
+    renderer.add_extension(lab.lighting);
+    renderer.add_extension(lab.overlay);
+
+    /** @type {Map<string, import("./scenes.js").ContactScene>} */
+    const worlds = new Map();
+
+    /** @type {import("./scenes.js").ContactScene} */
+    let world;
+
+    /** Seconds along the camera path and the movers' clock. */
+    let time = 0;
+
+    /** Measurements driving the frames (they nest); the frame loop stands aside while any does. */
+    let driving = 0;
+
+    let stopped = false;
+
+    const meter = new FrameRateMeter();
+
+    const path_from = [0, 0, 0];
+    const path_to = [0, 0, 0];
+    const look_from = new Vector3();
+    const look_to = new Vector3();
+
+    /**
+     * @param {number[]} from
+     * @param {number[]} to
+     */
+    function look(from, to) {
+        look_from.set(from[0], from[1], from[2]);
+        look_to.set(to[0], to[1], to[2]);
+
+        controller.look(look_from, look_to);
+    }
+
+    function frame_preset(name = 'default') {
+        const presets = world.presets;
+        const preset = presets[name] ?? presets[Object.keys(presets)[0]];
+
+        look(preset[0], preset[1]);
+    }
+
+    async function select_world() {
+        const name = element('scene').value;
+
+        if (!worlds.has(name)) {
+            report(`Building ${name}…`);
+
+            worlds.set(name, await create_contact_scene(renderer, name));
+        }
+
+        world = worlds.get(name);
+
+        lab.to_light = world.to_light;
+        lab.reset_history();
+
+        if (world.defaults.taa !== undefined) {
+            element('taa').checked = world.defaults.taa;
+        }
+
+        element('failure').textContent = world.failure;
+
+        time = 0;
+
+        frame_preset();
+        apply_settings();
+
+        renderer.indicate_view_change();
+
+        report(RUNNING);
+    }
+
+    function apply_settings() {
+        const thickness = 0.005 * 2 ** Number(element('thickness').value);
+        const threshold = 0.02 * 2 ** Number(element('threshold').value);
+        const contrast = Number(element('contrast').value);
+
+        lab.method = Number(element('method').value);
+        lab.combine = Number(element('combine').value);
+        lab.view = Number(element('show').value);
+        lab.reference = element('reference').checked || lab.view >= 4;
+
+        lab.settings.surface_thickness = thickness;
+        lab.settings.bilinear_threshold = threshold;
+        lab.settings.shadow_contrast = contrast;
+        lab.settings.debug_mode = Number(element('debug').value);
+        lab.settings.flags = (element('ignore-edges').checked ? ContactShadowFlags.IgnoreEdgePixels : 0)
+            | (element('offset-mode').checked ? ContactShadowFlags.BilinearOffsetMode : 0)
+            | (element('precision-offset').checked ? ContactShadowFlags.PrecisionOffset : 0);
+
+        renderer.feature_virtual_shadow_maps = element('technique').value === 'vsm';
+        renderer.feature_taa_enabled = element('taa').checked;
+
+        lab.linear_settings.steps = Number(element('linear-steps').value);
+        lab.linear_jitter = element('linear-jitter').checked;
+
+        element('thickness-value').textContent = thickness.toFixed(5);
+        element('threshold-value').textContent = threshold.toFixed(4);
+        element('contrast-value').textContent = String(contrast);
+        element('speed-value').textContent = Number(element('speed').value).toFixed(2);
+    }
+
+    for (const id of ['method', 'combine', 'show', 'reference', 'thickness', 'threshold', 'contrast', 'debug',
+        'ignore-edges', 'offset-mode', 'precision-offset', 'technique', 'taa', 'speed',
+        'linear-steps', 'linear-reach', 'linear-thickness', 'linear-jitter']) {
+        element(id).addEventListener('input', apply_settings);
+    }
+
+    element('scene').addEventListener('change', () => select_world().catch(error => report(String(error), true)));
+    element('preset').addEventListener('click', () => frame_preset());
+    element('step').addEventListener('click', () => {
+        element('pause').checked = true;
+        advance(FIXED_DT);
+        render_frame(FIXED_DT);
+    });
+
+    function resize() {
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+
+        camera.aspect = width / height;
+        renderer.resize(width, height);
+    }
+
+    /**
+     * Move the scene's clock, its movers and, on the path, the camera.
+     *
+     * @param {number} dt seconds
+     */
+    function advance(dt) {
+        time += dt * Number(element('speed').value);
+
+        world.update(time);
+    }
+
+    /**
+     * The world size of a texel of the shadow map serving the camera's near field: the cascades' first
+     * cascade as last fitted, or VSM's first level.
+     */
+    function shadow_texel() {
+        const map = renderer.scenes.obtain(world.scene).lights.shadow_context.get_map(world.sun);
+
+        if (map === undefined) {
+            return renderer.shadow_virtual_first_texel_size;
+        }
+
+        if (map.isVirtualShadowMap === true) {
+            return renderer.shadow_virtual_first_texel_size;
+        }
+
+        const camera = map.views[0]?.camera;
+        const slot = map.layout[0];
+
+        if (camera === undefined || slot === undefined) {
+            return renderer.shadow_virtual_first_texel_size;
+        }
+
+        return Math.max((camera.right - camera.left) / slot.width, (camera.top - camera.bottom) / slot.height);
+    }
+
+    /**
+     * The linear trace's reach and thickness, from the shadow map it complements: a reach of so many of its
+     * texels (the 5×5 filter blurs 5), and a thickness of reach / steps times a factor — at 1, the least that
+     * lets a march behind surfaces still see every surface.
+     */
+    function derive_linear_settings() {
+        const settings = lab.linear_settings;
+
+        settings.length = shadow_texel() * Number(element('linear-reach').value);
+        settings.thickness = settings.length / settings.steps * Number(element('linear-thickness').value);
+
+        element('linear-reach-value').textContent = `${(settings.length * 100).toFixed(1)} cm`;
+    }
+
+    /**
+     * @param {number} dt seconds, for the renderer's own clocks
+     */
+    function render_frame(dt) {
+        if (element('path').checked) {
+            world.path(time, path_from, path_to);
+            look(path_from, path_to);
+        }
+
+        resize();
+        controller.update();
+
+        derive_linear_settings();
+
+        renderer.render(camera, world.scene, dt);
+    }
+
+    /** Counters for the panel, read every few frames. */
+    let live_reading = false;
+    let live_counter = 0;
+    let live_lines = [];
+
+    async function read_live() {
+        live_reading = true;
+
+        try {
+            const s = await lab.read_stats();
+
+            live_lines = describe_summary(summarise(s, 1));
+        } finally {
+            live_reading = false;
+        }
+    }
+
+    function frame(dt, raf_dt) {
+        if (stopped || driving > 0 || world === undefined) {
+            return;
+        }
+
+        meter.add(raf_dt);
+
+        if (!element('pause').checked) {
+            advance(dt);
+        }
+
+        const live = element('live').checked && !live_reading && ++live_counter % 10 === 0;
+
+        if (live) {
+            // one frame on its own, so flips mean nothing here
+            lab.reset_history();
+            lab.clear_stats();
+            lab.measuring = true;
+        }
+
+        render_frame(dt);
+
+        lab.measuring = false;
+
+        if (live) {
+            read_live().catch(error => console.error(error));
+        }
+
+        update_readouts();
+    }
+
+    let last_readout = 0;
+
+    function update_readouts() {
+        const now = performance.now();
+
+        if (now - last_readout < 250) {
+            return;
+        }
+
+        last_readout = now;
+
+        const lines = [
+            `${meter.fps.toFixed(1)} fps, ${meter.mean_ms.toFixed(2)} ms mean`,
+            `${world.title}`,
+            `t = ${time.toFixed(2)} s`,
+        ];
+
+        if (element('live').checked) {
+            lines.push('', ...live_lines);
+        }
+
+        element('stats').textContent = lines.join('\n');
+    }
+
+    apply_settings();
+
+    await select_world();
+
+    let stop_loop = create_frame_loop((dt, raf_dt) => {
+        try {
+            frame(Math.min(dt, 0.1), raf_dt);
+        } catch (error) {
+            stopped = true;
+            stop_loop?.();
+            report(String(error?.stack ?? error), true);
+            console.error(error);
+        }
+    });
+
+    window.addEventListener('pagehide', () => {
+        stopped = true;
+        stop_loop?.();
+        lab.destroy();
+        renderer.destroy();
+    });
+
+    window.addEventListener('pageshow', event => {
+        if (event.persisted) {
+            location.reload();
+        }
+    });
+
+    install_profile_hotkey({
+        renderer,
+        name: 'contact_shadows',
+        status: element('status'),
+        settings: () => [
+            `scene=${element('scene').value}`,
+            `method=${element('method').value}`,
+            `combine=${element('combine').value}`,
+            `technique=${element('technique').value}`,
+            `taa=${element('taa').checked}`,
+        ],
+    });
+
+    /**
+     * Set controls by element id, as a person would.
+     *
+     * @param {Object<string, *>} settings
+     */
+    async function configure(settings) {
+        for (const [id, value] of Object.entries(settings)) {
+            const control = element(id);
+
+            if (control === null) {
+                throw new Error(`no control '${id}'`);
+            }
+
+            if (control.type === 'checkbox') {
+                control.checked = Boolean(value);
+            } else {
+                control.value = String(value);
+            }
+        }
+
+        if ('scene' in settings) {
+            await select_world();
+        }
+
+        apply_settings();
+    }
+
+    /**
+     * Take the frames from the loop for the length of `body`, and give them back.
+     *
+     * @template T
+     * @param {function(): Promise<T>} body
+     * @returns {Promise<T>}
+     */
+    async function drive(body) {
+        driving++;
+
+        const pause = element('pause').checked;
+
+        try {
+            return await body();
+        } finally {
+            lab.measuring = false;
+            lab.capture = false;
+            element('pause').checked = pause;
+            driving--;
+        }
+    }
+
+    /**
+     * Render frames at a fixed step and wait for each to finish on the GPU.
+     *
+     * @param {number} count
+     * @param {boolean} move whether scene time (path and movers) advances
+     */
+    async function run_frames(count, move) {
+        for (let i = 0; i < count; i++) {
+            if (move) {
+                advance(FIXED_DT);
+            }
+
+            render_frame(FIXED_DT);
+
+            await renderer.device.queue.onSubmittedWorkDone();
+        }
+    }
+
+    /**
+     * Count one scene's failure against the reference for each arm, along the scene's own camera path:
+     * every arm runs the same path from the same start, with the same movers.
+     *
+     * @param {Object} [options]
+     * @param {string} [options.scene] defaults to the one on screen
+     * @param {number} [options.frames] measured per arm
+     * @param {number} [options.warmup] frames before counting, for the shadow map (and VSM pages) to settle
+     * @param {boolean} [options.moving] follow the path; still otherwise
+     * @param {Object<string, Object>} [options.arms] name → control settings for {@link configure}
+     */
+    async function measure_scene({
+        scene = element('scene').value,
+        frames = 240,
+        warmup = 30,
+        moving = true,
+        arms = {
+            off: { method: ContactMethod.Off },
+            wavefront: { method: ContactMethod.Wavefront },
+            march: { method: ContactMethod.March },
+        },
+    } = {}) {
+        return drive(async () => {
+            const path = element('path').checked;
+
+            await configure({ scene, path: moving });
+
+            const results = {};
+
+            for (const [name, arm] of Object.entries(arms)) {
+                await configure(arm);
+
+                time = 0;
+                world.update(0);
+
+                await run_frames(warmup, false);
+
+                lab.reset_history();
+
+                const sum = new Float64Array(CONTACT_STAT_COUNT);
+
+                /** per frame: the fraction of the shadow map's gaps closed, and false shadow added */
+                const closed = [];
+                const added = [];
+
+                for (let i = 0; i < frames; i++) {
+                    if (moving) {
+                        advance(FIXED_DT);
+                    }
+
+                    lab.clear_stats();
+                    lab.measuring = true;
+
+                    render_frame(FIXED_DT);
+
+                    lab.measuring = false;
+
+                    const s = await lab.read_stats();
+
+                    for (let k = 0; k < s.length; k++) {
+                        sum[k] += s[k];
+                    }
+
+                    closed.push(s[ContactStat.ShadowMapMissed] > 0 ? s[ContactStat.Fixed] / s[ContactStat.ShadowMapMissed] : NaN);
+                    added.push(s[ContactStat.AddedFalse]);
+                }
+
+                const finite = closed.filter(Number.isFinite);
+
+                results[name] = {
+                    ...summarise(sum, frames),
+                    per_frame: {
+                        gap_closed_min_percent: 100 * Math.min(...finite),
+                        gap_closed_max_percent: 100 * Math.max(...finite),
+                        added_false_max: Math.max(...added),
+                        gap_closed: closed.map(v => Math.round(v * 1000) / 10),
+                        added_false: added,
+                    },
+                };
+            }
+
+            element('path').checked = path;
+
+            return { scene, moving, frames, results };
+        });
+    }
+
+    /**
+     * GPU time of the contact pass, A/B in one process: the arms swap every `block` frames in ABCD DCBA
+     * order, each block's first frame dropped, with the camera and scene still.
+     *
+     * @param {Object} [options]
+     * @param {number} [options.frames]
+     * @param {number} [options.block]
+     */
+    async function measure_cost({ frames = 360, block = 4 } = {}) {
+        return drive(async () => {
+            const arms = [ContactMethod.Off, ContactMethod.Wavefront, ContactMethod.March, ContactMethod.Linear];
+            const order = [0, 1, 2, 3, 3, 2, 1, 0];
+
+            await run_frames(20, false);
+
+            const session = new SpanCollector({ level: GPUProfileLevel.TIMING });
+
+            /** @type {Map<number, number>} frame index → arm */
+            const arm_of = new Map();
+
+            renderer.profile_session = session;
+
+            session.start();
+
+            for (let i = 0; i < frames; i++) {
+                const b = Math.floor(i / block);
+                const arm = arms[order[b % order.length]];
+
+                lab.method = arm;
+
+                if (i % block !== 0) {
+                    arm_of.set(renderer.frame_count, arm);
+                }
+
+                render_frame(FIXED_DT);
+
+                await renderer.device.queue.onSubmittedWorkDone();
+            }
+
+            await session.stop();
+
+            renderer.profile_session = null;
+
+            apply_settings();
+
+            /** label → arm → durations, µs */
+            const by_label = new Map();
+            const frame_us = arms.map(() => []);
+
+            for (const [index, arm] of arm_of) {
+                const spans = session.spans.get(index);
+
+                if (spans === undefined) {
+                    continue;
+                }
+
+                frame_us[arm].push(session.frames.get(index) / 1000);
+
+                for (const [label, ns] of spans) {
+                    if (!by_label.has(label)) {
+                        by_label.set(label, arms.map(() => []));
+                    }
+
+                    by_label.get(label)[arm].push(ns / 1000);
+                }
+            }
+
+            const names = ['off', 'wavefront', 'march', 'linear'];
+            const passes = {};
+
+            for (const [label, per_arm] of by_label) {
+                passes[label] = Object.fromEntries(per_arm.map((values, arm) => [names[arm], {
+                    n: values.length,
+                    median_us: median(values),
+                    mean_us: values.reduce((a, b) => a + b, 0) / Math.max(1, values.length),
+                }]));
+            }
+
+            return {
+                resolution: [canvas.width, canvas.height],
+                frame_median_us: Object.fromEntries(frame_us.map((values, arm) => [names[arm], median(values)])),
+                passes,
+            };
+        });
+    }
+
+    /**
+     * The checks that make the counters mean something:
+     *
+     * 1. the composite reproduces deferred shading's sun term: taking it all back out equals a frame lit
+     *    with the sun at zero intensity, to within the float16 rounding of the lit frame, with the cascades
+     *    and with the virtual shadow map;
+     * 2. where the shadow map shadows the combine scene, the ray-traced reference does too (the reverse
+     *    is what the scene is built to break);
+     * 3. the wavefront pass closes some of the shadow map's gaps there: a smoke check, not a quality bar.
+     */
+    async function verify() {
+        return drive(async () => {
+            const checks = [];
+
+            const taa = element('taa').checked;
+
+            // 1. the sun term, taken back out, against the sun switched off, with each shadow technique:
+            // the composite must be built for the one the deferred pass links
+            for (const technique of ['csm', 'vsm']) {
+                await configure({ scene: 'combine', path: false, taa: false, technique, method: ContactMethod.Off, combine: ContactCombine.Multiply, show: 0 });
+
+                frame_preset();
+
+                await run_frames(20, false);
+
+                const sun = world.sun;
+                const intensity = sun.intensity;
+
+                lab.combine = ContactCombine.RemoveSun;
+                lab.capture = true;
+
+                await run_frames(12, false);
+
+                const removed = await lab.read_capture();
+
+                lab.combine = ContactCombine.Multiply;
+                sun.intensity = 0;
+                world.scene.lights.needsUpdate = true;
+
+                await run_frames(12, false);
+
+                const dark = await lab.read_capture();
+
+                sun.intensity = intensity;
+                world.scene.lights.needsUpdate = true;
+
+                await run_frames(12, false);
+
+                const lit = await lab.read_capture();
+
+                lab.capture = false;
+
+                /*
+                 The composite subtracts from the lit frame as the renderer stored it, in rgba16float. Four
+                 float16 writes stand between an exact composite and the dark frame: the deferred pass's and
+                 the indirect resolve's additive blend into the lit frame, the composite's own output, and
+                 the resolve's blend into the dark frame (whose deferred write is exactly 0: the sun is its
+                 one direct light). Each is off by less than a step of the lit value. The 4090 truncates
+                 (1 + 0.75 step is written as 1), which puts the difference in (-3, 1) steps; round to
+                 nearest would keep it within 2. Measured 2026-10-16: 1.5 at worst in cascades, 2 in VSM,
+                 a mean of -0.43 (the composite's extra truncation); 4 in cascades when the composite left
+                 out the direct multiscatter compensation, 34,201 in VSM when it sampled the cascades.
+                */
+                let worst_steps = 0;
+                let worst_absolute = 0;
+                let signed_steps = 0;
+
+                for (let i = 0; i < removed.rgb.length; i++) {
+                    const magnitude = Math.max(Math.abs(lit.rgb[i]), Math.abs(dark.rgb[i]), 2 ** -14);
+                    const step = 2 ** (Math.floor(Math.log2(magnitude)) - 10);
+                    const difference = removed.rgb[i] - dark.rgb[i];
+
+                    worst_steps = Math.max(worst_steps, Math.abs(difference) / step);
+                    worst_absolute = Math.max(worst_absolute, Math.abs(difference));
+                    signed_steps += difference / step;
+                }
+
+                checks.push({
+                    name: `taking the whole sun term back out equals the frame with the sun off (${technique})`,
+                    pass: worst_steps < 3,
+                    worst_float16_steps_of_the_lit_value: worst_steps,
+                    mean_signed_float16_steps: signed_steps / removed.rgb.length,
+                    worst_absolute_difference: worst_absolute,
+                });
+            }
+
+            // 2 and 3. the reference, and the wavefront against it, with the cascades
+            await configure({ technique: 'csm' });
+
+            await run_frames(20, false);
+
+            const result = await measure_scene({
+                scene: 'combine',
+                frames: 8,
+                warmup: 4,
+                moving: false,
+                arms: { off: { method: ContactMethod.Off }, wavefront: { method: ContactMethod.Wavefront } },
+            });
+
+            const off = result.results.off;
+            const wavefront = result.results.wavefront;
+
+            /*
+             Where the cascades shadow, the reference must too: only their filtered edges may disagree.
+             (The other way round is the point of the scene — the cascades leave gaps at caster bases.)
+            */
+            const map_shadowed = off.reference_shadowed - off.shadow_map_missed + off.shadow_map_false;
+
+            checks.push({
+                name: 'where the shadow map shadows, the reference does too',
+                pass: map_shadowed > 1000 && off.shadow_map_false < 0.01 * map_shadowed,
+                shadow_map_shadowed: map_shadowed,
+                shadow_map_false: off.shadow_map_false,
+                reference_shadowed: off.reference_shadowed,
+                shadow_map_missed: off.shadow_map_missed,
+            });
+
+            checks.push({
+                name: 'the wavefront pass closes shadow-map gaps',
+                pass: wavefront.gap_closed_percent > 10,
+                gap_closed_percent: wavefront.gap_closed_percent,
+            });
+
+            element('taa').checked = taa;
+            apply_settings();
+
+            return { pass: checks.every(c => c.pass), checks };
+        });
+    }
+
+    globalThis.contact_lab = {
+        renderer,
+        camera,
+        controller,
+        lab,
+        get world() {
+            return world;
+        },
+        configure,
+        frame_preset,
+        /**
+         * Put the camera where the scene's path has it at time `t`, and the movers with it.
+         * @param {number} t seconds along the path
+         */
+        path_at(t) {
+            time = t;
+            world.update(t);
+            world.path(t, path_from, path_to);
+            look(path_from, path_to);
+        },
+        measure_scene,
+        measure_cost,
+        verify,
+    };
+
+    globalThis.verify = verify;
+
+    report(RUNNING);
+}