@woosh/meep-engine 3.15.0 → 3.16.0

package/src/shade/playground/volumetrics_froxel/measure.js

@@ -1,559 +1,559 @@
-/**
- * The measurement protocol from this page's README, as code.
- *
- * Not imported by the page — it is loaded from the console when there is something to measure:
- *
- * ```js
- * const m = await (await import('./measure.js')).attach();
- * await m.ab(v => globalThis.__VOL_TAA_ENABLED = v, false, true);
- * ```
- *
- * It exists because every trap the README lists is a trap about *procedure*, and a procedure
- * written down in prose gets followed differently each time. Three of them are structural and are
- * dealt with here rather than left to the operator:
- *
- *  - **The canvas cannot be read back.** A canvas texture is configured by the presentation path,
- *    cannot carry `COPY_SRC`, and is rotated away the moment the frame is presented — a `drawImage`
- *    off it a task later returns an empty bitmap, and a comparison of two blanks reports perfect
- *    agreement. Everything here renders into a texture this module owns, via
- *    `Renderer.render_to_target`, which shares the view context (and therefore all the temporal
- *    history) with the canvas path.
- *
- *  - **Presentation throttling.** Whole-frame timing off the page's own loop is paced by the swap
- *    chain, which is why the README says two settings that plainly differ can report the same
- *    number. Driving the frames from here removes the swap chain from the measurement entirely.
- *
- *  - **The noise floor has to pay the same costs the signal does.** `ab` takes the floor by making
- *    an identical no-op change and settling exactly as the real change does, and it interleaves the
- *    two sides so drift lands on both.
- *
- * The camera-path helpers exist for a narrower reason: a structure that is fitted to the camera can
- * be perfectly correct standing still and swim under motion, and the froxel volume then goes
- * through a 0.95-blend temporal filter that turns swimming into either ghosting or flicker. Neither
- * is visible in a still. `fly` drives a pose sequence one frame at a time and records what the
- * image does while it happens.
- */
-
-/**
- * @param {object} [context] defaults to the globals the page publishes
- * @param {Renderer} [context.renderer]
- * @param {Scene} [context.scene]
- * @param {PerspectiveCamera} [context.camera]
- * @param {OrbitalCameraController} [context.controller]
- */
-export async function attach({
-                                 renderer = globalThis.renderer,
-                                 scene = globalThis.scene,
-                                 camera = globalThis.camera,
-                                 controller = globalThis.controller,
-                             } = {}) {
-
-    const { GPUTextureContext } = await import('../../renderer/texture/GPUTextureContext.js');
-
-    const device = renderer.device;
-
-    /** @type {object|null} */
-    let capture = null;
-
-    // The page's loop must stop, and not only so the frame count is ours: it also assigns
-    // `renderer.pixel_ratio = window.devicePixelRatio` on every tick, ahead of its own pause check,
-    // so a raised pixel ratio would be undone before the next frame.
-    const pause_button = document.getElementById('pause');
-
-    if (pause_button !== null && pause_button.textContent === 'Pause') {
-        pause_button.click();
-    }
-
-    // A/B is meaningless with eye adaptation running — it keeps drifting for seconds after any
-    // change, by more than most changes to this pass are worth.
-    renderer.feature_automatic_exposure_enabled = false;
-
-    function make_target() {
-        if (capture !== null) {
-            capture.destroy();
-        }
-
-        const resolution = renderer.output_resolution;
-
-        const width = resolution.x;
-        const height = resolution.y;
-
-        // the rule the renderer's own context configuration follows
-        const format = window.matchMedia('(dynamic-range: high)').matches
-            ? 'rgba16float'
-            : navigator.gpu.getPreferredCanvasFormat();
-
-        const texture = device.createTexture({
-            label: 'measure/capture',
-            size: [width, height, 1],
-            format,
-            usage: GPUTextureUsage.RENDER_ATTACHMENT
-                | GPUTextureUsage.COPY_SRC
-                | GPUTextureUsage.COPY_DST
-                | GPUTextureUsage.TEXTURE_BINDING,
-        });
-
-        const bytes_per_pixel = format === 'rgba16float' ? 8 : 4;
-
-        // copyTextureToBuffer wants rows on a 256-byte boundary
-        const bytes_per_row = Math.ceil(width * bytes_per_pixel / 256) * 256;
-
-        capture = {
-            texture,
-            target: GPUTextureContext.fromTexture(texture, device),
-            width,
-            height,
-            format,
-            bytes_per_row,
-            buffer: device.createBuffer({
-                label: 'measure/readback',
-                size: bytes_per_row * height,
-                usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
-            }),
-            destroy() {
-                this.texture.destroy();
-                this.buffer.destroy();
-            },
-        };
-
-        return capture;
-    }
-
-    function target() {
-        const resolution = renderer.output_resolution;
-
-        if (capture === null || capture.width !== resolution.x || capture.height !== resolution.y) {
-            make_target();
-        }
-
-        return capture;
-    }
-
-    function half_to_float(h) {
-        const sign = (h & 0x8000) !== 0 ? -1 : 1;
-        const exponent = (h & 0x7C00) >> 10;
-        const fraction = h & 0x03FF;
-
-        if (exponent === 0) {
-            return sign * Math.pow(2, -14) * (fraction / 1024);
-        }
-
-        if (exponent === 31) {
-            return fraction !== 0 ? NaN : sign * Infinity;
-        }
-
-        return sign * Math.pow(2, exponent - 15) * (1 + fraction / 1024);
-    }
-
-    /** One frame into the owned target. */
-    function frame(time_delta_s = 1 / 60) {
-        renderer.render_to_target(camera, scene, time_delta_s, target().target);
-    }
-
-    /** `n` frames, awaited, with nothing read back — for letting the temporal filter converge. */
-    async function settle(n) {
-        for (let i = 0; i < n; i++) {
-            frame();
-        }
-
-        await device.queue.onSubmittedWorkDone();
-    }
-
-    /**
-     * Per-pixel luminance of whatever is in the capture texture, added into `out`.
-     *
-     * @param {Float32Array} out length width*height
-     */
-    async function accumulate_luminance(out) {
-        const c = target();
-
-        const encoder = device.createCommandEncoder({ label: 'measure/readback' });
-
-        encoder.copyTextureToBuffer(
-            { texture: c.texture },
-            { buffer: c.buffer, bytesPerRow: c.bytes_per_row },
-            [c.width, c.height, 1]
-        );
-
-        device.queue.submit([encoder.finish()]);
-
-        await c.buffer.mapAsync(GPUMapMode.READ);
-
-        const raw = c.buffer.getMappedRange();
-
-        // The channel order is not cosmetic here: the preferred canvas format on Windows is
-        // bgra8unorm, and weighting it as if it were rgba silently swaps the 0.2126 and 0.0722
-        // coefficients — still a usable difference metric, but not the luminance it claims to be.
-        if (c.format === 'rgba16float') {
-            const source = new Uint16Array(raw);
-            const stride = c.bytes_per_row / 2;
-
-            for (let y = 0; y < c.height; y++) {
-                for (let x = 0; x < c.width; x++) {
-                    const i = y * stride + x * 4;
-
-                    out[y * c.width + x] += 0.2126 * half_to_float(source[i])
-                        + 0.7152 * half_to_float(source[i + 1])
-                        + 0.0722 * half_to_float(source[i + 2]);
-                }
-            }
-        } else {
-            const source = new Uint8Array(raw);
-            const bgra = c.format.startsWith('bgra');
-
-            for (let y = 0; y < c.height; y++) {
-                for (let x = 0; x < c.width; x++) {
-                    const i = y * c.bytes_per_row + x * 4;
-
-                    const r = bgra ? source[i + 2] : source[i];
-                    const b = bgra ? source[i] : source[i + 2];
-
-                    out[y * c.width + x] += 0.2126 * r + 0.7152 * source[i + 1] + 0.0722 * b;
-                }
-            }
-        }
-
-        c.buffer.unmap();
-    }
-
-    /**
-     * Settle, then average. The two numbers are the README's protocol: ~45 frames of
-     * re-convergence after any change that resets temporal accumulation, then a multi-frame average
-     * because the column jitter and the sample RNG both key on the frame index and consecutive
-     * frames genuinely differ.
-     *
-     * @returns {Promise<Float32Array>} mean luminance per pixel
-     */
-    async function capture_average({ settle: settle_frames = 45, average = 32 } = {}) {
-        await settle(settle_frames);
-
-        const c = target();
-        const accumulator = new Float32Array(c.width * c.height);
-
-        for (let i = 0; i < average; i++) {
-            frame();
-            await device.queue.onSubmittedWorkDone();
-            await accumulate_luminance(accumulator);
-        }
-
-        for (let i = 0; i < accumulator.length; i++) {
-            accumulator[i] /= average;
-        }
-
-        return accumulator;
-    }
-
-    function mean(values) {
-        let sum = 0;
-
-        for (let i = 0; i < values.length; i++) {
-            sum += values[i];
-        }
-
-        return sum / values.length;
-    }
-
-    /**
-     * Prefer the signed mean when the change has a direction — it discriminates far better than the
-     * mean absolute, which is dominated by noise.
-     */
-    function compare(a, b) {
-        let signed = 0;
-        let absolute = 0;
-        let largest = 0;
-
-        for (let i = 0; i < a.length; i++) {
-            const d = b[i] - a[i];
-
-            signed += d;
-            absolute += Math.abs(d);
-
-            if (Math.abs(d) > largest) {
-                largest = Math.abs(d);
-            }
-        }
-
-        return {
-            signed_mean: signed / a.length,
-            mean_abs: absolute / a.length,
-            max_abs: largest,
-            mean_a: mean(a),
-            mean_b: mean(b),
-        };
-    }
-
-    /**
-     * An interleaved A/B with its own noise floor.
-     *
-     * `apply` is called with `a` and with `b`; it must be the whole of the change, and cheap enough
-     * that the two sides pay the same fixed costs. Both sides then go through the identical
-     * settle-and-average, and the floor comes from the two captures of the *same* setting, which is
-     * what makes a small result readable — anything at or below the floor has not been shown.
-     */
-    async function ab(apply, a, b, options = {}) {
-        const run = async (value) => {
-            apply(value);
-            renderer.indicate_view_change();
-            return capture_average(options);
-        };
-
-        const a1 = await run(a);
-        const b1 = await run(b);
-        const a2 = await run(a);
-        const b2 = await run(b);
-
-        return {
-            floor: [compare(a1, a2), compare(b1, b2)],
-            signal: [compare(a1, b1), compare(a2, b2)],
-        };
-    }
-
-    // -----------------------------------------------------------------------------------------
-    // camera paths
-    // -----------------------------------------------------------------------------------------
-
-    function read_pose() {
-        const t = camera.transform;
-
-        return {
-            position: [t.position.x, t.position.y, t.position.z],
-            rotation: [t.rotation.x, t.rotation.y, t.rotation.z, t.rotation.w],
-        };
-    }
-
-    function write_pose(pose) {
-        camera.transform.position.set(pose.position[0], pose.position[1], pose.position[2]);
-        camera.transform.rotation.set(pose.rotation[0], pose.rotation[1], pose.rotation[2], pose.rotation[3]);
-
-        // the controller keeps its own spherical state and would otherwise pull the camera back on
-        // its next tick — the page's loop still runs it while paused
-        controller.from_transform(camera.transform);
-    }
-
-    /** Straight-line interpolation between two poses, with the rotation slerped. */
-    function interpolate(from, to, t) {
-        const position = from.position.map((c, i) => c + (to.position[i] - c) * t);
-
-        let dot = from.rotation.reduce((s, c, i) => s + c * to.rotation[i], 0);
-        let target_rotation = to.rotation;
-
-        if (dot < 0) {
-            dot = -dot;
-            target_rotation = to.rotation.map(c => -c);
-        }
-
-        let rotation;
-
-        if (dot > 0.9995) {
-            rotation = from.rotation.map((c, i) => c + (target_rotation[i] - c) * t);
-        } else {
-            const theta = Math.acos(dot);
-            const s0 = Math.sin((1 - t) * theta) / Math.sin(theta);
-            const s1 = Math.sin(t * theta) / Math.sin(theta);
-            rotation = from.rotation.map((c, i) => c * s0 + target_rotation[i] * s1);
-        }
-
-        const length = Math.hypot(...rotation);
-
-        return { position, rotation: rotation.map(c => c / length) };
-    }
-
-    /**
-     * Fly the camera from its current pose to `to` over `frames` frames, rendering every one of
-     * them, and record the frame-average luminance as it goes.
-     *
-     * The per-frame series is the point. A structure that swims under motion shows up as
-     * frame-to-frame jitter in it that a static capture cannot contain; ghosting shows up as a tail
-     * after the motion stops.
-     *
-     * @returns {Promise<number[]>} mean luminance, one entry per frame
-     */
-    async function fly(to, { frames = 60, hold = 0 } = {}) {
-        const from = read_pose();
-        const series = [];
-
-        const c = target();
-        const scratch = new Float32Array(c.width * c.height);
-
-        for (let i = 0; i <= frames + hold; i++) {
-            const t = Math.min(1, i / frames);
-
-            write_pose(interpolate(from, to, t));
-
-            frame();
-            await device.queue.onSubmittedWorkDone();
-
-            scratch.fill(0);
-            await accumulate_luminance(scratch);
-
-            series.push(mean(scratch));
-        }
-
-        return series;
-    }
-
-    /**
-     * How noisy a per-frame series is, and how much of it is a trend rather than flicker.
-     *
-     * `flicker` is the mean absolute successive difference — a temporal-noise measure that is blind
-     * to a smooth ramp, which is what makes it usable while the camera is still moving. `drift` is
-     * the total change across the window.
-     */
-    function series_stats(series) {
-        let successive = 0;
-        let largest = 0;
-
-        for (let i = 1; i < series.length; i++) {
-            const d = Math.abs(series[i] - series[i - 1]);
-            successive += d;
-
-            if (d > largest) {
-                largest = d;
-            }
-        }
-
-        return {
-            frames: series.length,
-            mean: mean(series),
-            flicker: successive / Math.max(1, series.length - 1),
-            max_step: largest,
-            drift: series[series.length - 1] - series[0],
-        };
-    }
-
-    /** Teleport, reset history and converge — the reference a flown-into pose is judged against. */
-    async function converge_at(pose, options = {}) {
-        write_pose(pose);
-        renderer.indicate_view_change();
-        return capture_average(options);
-    }
-
-    /**
-     * GPU-bound frame time, with the swap chain out of the measurement.
-     *
-     * Submits `frames` frames back to back and waits once, so the queue stays full and the number
-     * is throughput rather than latency. Interleave the settings being compared and take medians —
-     * a single reading here is worth nothing.
-     */
-    async function time_frames({ frames = 120 } = {}) {
-        await settle(8);
-
-        const started = performance.now();
-
-        for (let i = 0; i < frames; i++) {
-            frame();
-        }
-
-        await device.queue.onSubmittedWorkDone();
-
-        return (performance.now() - started) / frames;
-    }
-
-    /**
-     * Per-pass GPU durations, recorded and decoded in the page.
-     *
-     * This is the number to believe about cost, and the README says why in one line: at 1080p,
-     * whole-frame timing of Q-04 came back with the wrong sign three runs in a row while the
-     * per-pass capture read it cleanly. `time` measures a frame; this measures the passes the change
-     * is supposed to move.
-     *
-     * The `.sgpt` never reaches disk — the session's bytes go straight through `sgpt_read_capture`.
-     * A downloaded capture is the right artefact when the point is to keep it; when the point is a
-     * number, a file the browser may decline to save the second time is a step to skip.
-     *
-     * Two things about the draining. A frame is committed when its timestamp readback lands, a
-     * `mapAsync` a frame or two behind submit, so stopping the instant the last frame is encoded
-     * discards exactly the frames you asked for. And the readback resolves on a task, not on
-     * `onSubmittedWorkDone`, so the drain has to yield to the event loop rather than only to the
-     * queue.
-     *
-     * @param {object} [options]
-     * @param {number} [options.frames] frames to record
-     * @param {number} [options.settle] frames to run before recording starts
-     * @returns {Promise<Object<string, number>>} median duration in ms per pass label, plus
-     * `__frames` and `__defects`
-     */
-    async function profile_passes({ frames = 40, settle: settle_frames = 20 } = {}) {
-        const { GPUProfileSession } = await import('../../device/timing/profile/GPUProfileSession.js');
-        const { GPUProfileLevel } = await import('../../device/timing/profile/GPUProfileLevel.js');
-        const { sgpt_read_capture } = await import('../../device/timing/profile/sgpt_read_capture.js');
-
-        await settle(settle_frames);
-
-        const session = new GPUProfileSession({ level: GPUProfileLevel.WORKLOAD, note: 'measure.js' });
-
-        renderer.profile_session = session;
-        session.start();
-
-        await settle(frames);
-
-        for (let i = 0; i < 20; i++) {
-            await new Promise(resolve => setTimeout(resolve, 40));
-            frame();
-            await device.queue.onSubmittedWorkDone();
-        }
-
-        renderer.profile_session = null;
-
-        await device.queue.onSubmittedWorkDone();
-        await new Promise(resolve => setTimeout(resolve, 200));
-
-        const bytes = session.stop();
-
-        const buffer = bytes instanceof ArrayBuffer
-            ? bytes
-            : bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
-
-        const capture = sgpt_read_capture(buffer);
-
-        // Summed per frame before the median is taken across frames, because one frame graph pass
-        // routinely opens several GPU passes and a label is not unique — see GPUProfileSpan.
-        const per_frame = new Map();
-
-        for (const recorded of capture.frames) {
-            const totals = new Map();
-
-            for (const span of recorded.spans) {
-                totals.set(span.label, (totals.get(span.label) ?? 0) + span.duration_ns * 1e-6);
-            }
-
-            for (const [label, ms] of totals) {
-                if (!per_frame.has(label)) {
-                    per_frame.set(label, []);
-                }
-
-                per_frame.get(label).push(ms);
-            }
-        }
-
-        const out = { __frames: capture.frames.length, __defects: capture.defects.length };
-
-        for (const [label, values] of per_frame) {
-            values.sort((a, b) => a - b);
-            out[label] = values[values.length >> 1];
-        }
-
-        return out;
-    }
-
-    /**
-     * Raise the internal resolution until the GPU is the bottleneck. The page's loop assigns
-     * `renderer.pixel_ratio` from `window.devicePixelRatio` every tick, so the property has to go
-     * rather than the field.
-     */
-    function set_pixel_ratio(ratio) {
-        Object.defineProperty(window, 'devicePixelRatio', { get: () => ratio, configurable: true });
-        renderer.pixel_ratio = ratio;
-        make_target();
-        renderer.indicate_view_change();
-    }
-
-    return {
-        renderer, scene, camera, controller, device,
-        get capture() { return capture; },
-        make_target, target, frame, settle, accumulate_luminance,
-        capture: capture_average, compare, mean, ab,
-        read_pose, write_pose, interpolate, fly, series_stats, converge_at,
-        time: time_frames, profile: profile_passes, set_pixel_ratio,
-    };
-}
+/**
+ * The measurement protocol from this page's README, as code.
+ *
+ * Not imported by the page — it is loaded from the console when there is something to measure:
+ *
+ * ```js
+ * const m = await (await import('./measure.js')).attach();
+ * await m.ab(v => globalThis.__VOL_TAA_ENABLED = v, false, true);
+ * ```
+ *
+ * It exists because every trap the README lists is a trap about *procedure*, and a procedure
+ * written down in prose gets followed differently each time. Three of them are structural and are
+ * dealt with here rather than left to the operator:
+ *
+ *  - **The canvas cannot be read back.** A canvas texture is configured by the presentation path,
+ *    cannot carry `COPY_SRC`, and is rotated away the moment the frame is presented — a `drawImage`
+ *    off it a task later returns an empty bitmap, and a comparison of two blanks reports perfect
+ *    agreement. Everything here renders into a texture this module owns, via
+ *    `Renderer.render_to_target`, which shares the view context (and therefore all the temporal
+ *    history) with the canvas path.
+ *
+ *  - **Presentation throttling.** Whole-frame timing off the page's own loop is paced by the swap
+ *    chain, which is why the README says two settings that plainly differ can report the same
+ *    number. Driving the frames from here removes the swap chain from the measurement entirely.
+ *
+ *  - **The noise floor has to pay the same costs the signal does.** `ab` takes the floor by making
+ *    an identical no-op change and settling exactly as the real change does, and it interleaves the
+ *    two sides so drift lands on both.
+ *
+ * The camera-path helpers exist for a narrower reason: a structure that is fitted to the camera can
+ * be perfectly correct standing still and swim under motion, and the froxel volume then goes
+ * through a 0.95-blend temporal filter that turns swimming into either ghosting or flicker. Neither
+ * is visible in a still. `fly` drives a pose sequence one frame at a time and records what the
+ * image does while it happens.
+ */
+
+/**
+ * @param {object} [context] defaults to the globals the page publishes
+ * @param {Renderer} [context.renderer]
+ * @param {Scene} [context.scene]
+ * @param {PerspectiveCamera} [context.camera]
+ * @param {OrbitalCameraController} [context.controller]
+ */
+export async function attach({
+                                 renderer = globalThis.renderer,
+                                 scene = globalThis.scene,
+                                 camera = globalThis.camera,
+                                 controller = globalThis.controller,
+                             } = {}) {
+
+    const { GPUTextureContext } = await import('../../renderer/texture/GPUTextureContext.js');
+
+    const device = renderer.device;
+
+    /** @type {object|null} */
+    let capture = null;
+
+    // The page's loop must stop, and not only so the frame count is ours: it also assigns
+    // `renderer.pixel_ratio = window.devicePixelRatio` on every tick, ahead of its own pause check,
+    // so a raised pixel ratio would be undone before the next frame.
+    const pause_button = document.getElementById('pause');
+
+    if (pause_button !== null && pause_button.textContent === 'Pause') {
+        pause_button.click();
+    }
+
+    // A/B is meaningless with eye adaptation running — it keeps drifting for seconds after any
+    // change, by more than most changes to this pass are worth.
+    renderer.feature_automatic_exposure_enabled = false;
+
+    function make_target() {
+        if (capture !== null) {
+            capture.destroy();
+        }
+
+        const resolution = renderer.output_resolution;
+
+        const width = resolution.x;
+        const height = resolution.y;
+
+        // the rule the renderer's own context configuration follows
+        const format = window.matchMedia('(dynamic-range: high)').matches
+            ? 'rgba16float'
+            : navigator.gpu.getPreferredCanvasFormat();
+
+        const texture = device.createTexture({
+            label: 'measure/capture',
+            size: [width, height, 1],
+            format,
+            usage: GPUTextureUsage.RENDER_ATTACHMENT
+                | GPUTextureUsage.COPY_SRC
+                | GPUTextureUsage.COPY_DST
+                | GPUTextureUsage.TEXTURE_BINDING,
+        });
+
+        const bytes_per_pixel = format === 'rgba16float' ? 8 : 4;
+
+        // copyTextureToBuffer wants rows on a 256-byte boundary
+        const bytes_per_row = Math.ceil(width * bytes_per_pixel / 256) * 256;
+
+        capture = {
+            texture,
+            target: GPUTextureContext.fromTexture(texture, device),
+            width,
+            height,
+            format,
+            bytes_per_row,
+            buffer: device.createBuffer({
+                label: 'measure/readback',
+                size: bytes_per_row * height,
+                usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+            }),
+            destroy() {
+                this.texture.destroy();
+                this.buffer.destroy();
+            },
+        };
+
+        return capture;
+    }
+
+    function target() {
+        const resolution = renderer.output_resolution;
+
+        if (capture === null || capture.width !== resolution.x || capture.height !== resolution.y) {
+            make_target();
+        }
+
+        return capture;
+    }
+
+    function half_to_float(h) {
+        const sign = (h & 0x8000) !== 0 ? -1 : 1;
+        const exponent = (h & 0x7C00) >> 10;
+        const fraction = h & 0x03FF;
+
+        if (exponent === 0) {
+            return sign * Math.pow(2, -14) * (fraction / 1024);
+        }
+
+        if (exponent === 31) {
+            return fraction !== 0 ? NaN : sign * Infinity;
+        }
+
+        return sign * Math.pow(2, exponent - 15) * (1 + fraction / 1024);
+    }
+
+    /** One frame into the owned target. */
+    function frame(time_delta_s = 1 / 60) {
+        renderer.render_to_target(camera, scene, time_delta_s, target().target);
+    }
+
+    /** `n` frames, awaited, with nothing read back — for letting the temporal filter converge. */
+    async function settle(n) {
+        for (let i = 0; i < n; i++) {
+            frame();
+        }
+
+        await device.queue.onSubmittedWorkDone();
+    }
+
+    /**
+     * Per-pixel luminance of whatever is in the capture texture, added into `out`.
+     *
+     * @param {Float32Array} out length width*height
+     */
+    async function accumulate_luminance(out) {
+        const c = target();
+
+        const encoder = device.createCommandEncoder({ label: 'measure/readback' });
+
+        encoder.copyTextureToBuffer(
+            { texture: c.texture },
+            { buffer: c.buffer, bytesPerRow: c.bytes_per_row },
+            [c.width, c.height, 1]
+        );
+
+        device.queue.submit([encoder.finish()]);
+
+        await c.buffer.mapAsync(GPUMapMode.READ);
+
+        const raw = c.buffer.getMappedRange();
+
+        // The channel order is not cosmetic here: the preferred canvas format on Windows is
+        // bgra8unorm, and weighting it as if it were rgba silently swaps the 0.2126 and 0.0722
+        // coefficients — still a usable difference metric, but not the luminance it claims to be.
+        if (c.format === 'rgba16float') {
+            const source = new Uint16Array(raw);
+            const stride = c.bytes_per_row / 2;
+
+            for (let y = 0; y < c.height; y++) {
+                for (let x = 0; x < c.width; x++) {
+                    const i = y * stride + x * 4;
+
+                    out[y * c.width + x] += 0.2126 * half_to_float(source[i])
+                        + 0.7152 * half_to_float(source[i + 1])
+                        + 0.0722 * half_to_float(source[i + 2]);
+                }
+            }
+        } else {
+            const source = new Uint8Array(raw);
+            const bgra = c.format.startsWith('bgra');
+
+            for (let y = 0; y < c.height; y++) {
+                for (let x = 0; x < c.width; x++) {
+                    const i = y * c.bytes_per_row + x * 4;
+
+                    const r = bgra ? source[i + 2] : source[i];
+                    const b = bgra ? source[i] : source[i + 2];
+
+                    out[y * c.width + x] += 0.2126 * r + 0.7152 * source[i + 1] + 0.0722 * b;
+                }
+            }
+        }
+
+        c.buffer.unmap();
+    }
+
+    /**
+     * Settle, then average. The two numbers are the README's protocol: ~45 frames of
+     * re-convergence after any change that resets temporal accumulation, then a multi-frame average
+     * because the column jitter and the sample RNG both key on the frame index and consecutive
+     * frames genuinely differ.
+     *
+     * @returns {Promise<Float32Array>} mean luminance per pixel
+     */
+    async function capture_average({ settle: settle_frames = 45, average = 32 } = {}) {
+        await settle(settle_frames);
+
+        const c = target();
+        const accumulator = new Float32Array(c.width * c.height);
+
+        for (let i = 0; i < average; i++) {
+            frame();
+            await device.queue.onSubmittedWorkDone();
+            await accumulate_luminance(accumulator);
+        }
+
+        for (let i = 0; i < accumulator.length; i++) {
+            accumulator[i] /= average;
+        }
+
+        return accumulator;
+    }
+
+    function mean(values) {
+        let sum = 0;
+
+        for (let i = 0; i < values.length; i++) {
+            sum += values[i];
+        }
+
+        return sum / values.length;
+    }
+
+    /**
+     * Prefer the signed mean when the change has a direction — it discriminates far better than the
+     * mean absolute, which is dominated by noise.
+     */
+    function compare(a, b) {
+        let signed = 0;
+        let absolute = 0;
+        let largest = 0;
+
+        for (let i = 0; i < a.length; i++) {
+            const d = b[i] - a[i];
+
+            signed += d;
+            absolute += Math.abs(d);
+
+            if (Math.abs(d) > largest) {
+                largest = Math.abs(d);
+            }
+        }
+
+        return {
+            signed_mean: signed / a.length,
+            mean_abs: absolute / a.length,
+            max_abs: largest,
+            mean_a: mean(a),
+            mean_b: mean(b),
+        };
+    }
+
+    /**
+     * An interleaved A/B with its own noise floor.
+     *
+     * `apply` is called with `a` and with `b`; it must be the whole of the change, and cheap enough
+     * that the two sides pay the same fixed costs. Both sides then go through the identical
+     * settle-and-average, and the floor comes from the two captures of the *same* setting, which is
+     * what makes a small result readable — anything at or below the floor has not been shown.
+     */
+    async function ab(apply, a, b, options = {}) {
+        const run = async (value) => {
+            apply(value);
+            renderer.indicate_view_change();
+            return capture_average(options);
+        };
+
+        const a1 = await run(a);
+        const b1 = await run(b);
+        const a2 = await run(a);
+        const b2 = await run(b);
+
+        return {
+            floor: [compare(a1, a2), compare(b1, b2)],
+            signal: [compare(a1, b1), compare(a2, b2)],
+        };
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // camera paths
+    // -----------------------------------------------------------------------------------------
+
+    function read_pose() {
+        const t = camera.transform;
+
+        return {
+            position: [t.translation_x, t.translation_y, t.translation_z],
+            rotation: [t.rotation_x, t.rotation_y, t.rotation_z, t.rotation_w],
+        };
+    }
+
+    function write_pose(pose) {
+        camera.transform.setTranslation(pose.position[0], pose.position[1], pose.position[2]);
+        camera.transform.setRotation(pose.rotation[0], pose.rotation[1], pose.rotation[2], pose.rotation[3]);
+
+        // the controller keeps its own spherical state and would otherwise pull the camera back on
+        // its next tick — the page's loop still runs it while paused
+        controller.from_transform(camera.transform);
+    }
+
+    /** Straight-line interpolation between two poses, with the rotation slerped. */
+    function interpolate(from, to, t) {
+        const position = from.position.map((c, i) => c + (to.position[i] - c) * t);
+
+        let dot = from.rotation.reduce((s, c, i) => s + c * to.rotation[i], 0);
+        let target_rotation = to.rotation;
+
+        if (dot < 0) {
+            dot = -dot;
+            target_rotation = to.rotation.map(c => -c);
+        }
+
+        let rotation;
+
+        if (dot > 0.9995) {
+            rotation = from.rotation.map((c, i) => c + (target_rotation[i] - c) * t);
+        } else {
+            const theta = Math.acos(dot);
+            const s0 = Math.sin((1 - t) * theta) / Math.sin(theta);
+            const s1 = Math.sin(t * theta) / Math.sin(theta);
+            rotation = from.rotation.map((c, i) => c * s0 + target_rotation[i] * s1);
+        }
+
+        const length = Math.hypot(...rotation);
+
+        return { position, rotation: rotation.map(c => c / length) };
+    }
+
+    /**
+     * Fly the camera from its current pose to `to` over `frames` frames, rendering every one of
+     * them, and record the frame-average luminance as it goes.
+     *
+     * The per-frame series is the point. A structure that swims under motion shows up as
+     * frame-to-frame jitter in it that a static capture cannot contain; ghosting shows up as a tail
+     * after the motion stops.
+     *
+     * @returns {Promise<number[]>} mean luminance, one entry per frame
+     */
+    async function fly(to, { frames = 60, hold = 0 } = {}) {
+        const from = read_pose();
+        const series = [];
+
+        const c = target();
+        const scratch = new Float32Array(c.width * c.height);
+
+        for (let i = 0; i <= frames + hold; i++) {
+            const t = Math.min(1, i / frames);
+
+            write_pose(interpolate(from, to, t));
+
+            frame();
+            await device.queue.onSubmittedWorkDone();
+
+            scratch.fill(0);
+            await accumulate_luminance(scratch);
+
+            series.push(mean(scratch));
+        }
+
+        return series;
+    }
+
+    /**
+     * How noisy a per-frame series is, and how much of it is a trend rather than flicker.
+     *
+     * `flicker` is the mean absolute successive difference — a temporal-noise measure that is blind
+     * to a smooth ramp, which is what makes it usable while the camera is still moving. `drift` is
+     * the total change across the window.
+     */
+    function series_stats(series) {
+        let successive = 0;
+        let largest = 0;
+
+        for (let i = 1; i < series.length; i++) {
+            const d = Math.abs(series[i] - series[i - 1]);
+            successive += d;
+
+            if (d > largest) {
+                largest = d;
+            }
+        }
+
+        return {
+            frames: series.length,
+            mean: mean(series),
+            flicker: successive / Math.max(1, series.length - 1),
+            max_step: largest,
+            drift: series[series.length - 1] - series[0],
+        };
+    }
+
+    /** Teleport, reset history and converge — the reference a flown-into pose is judged against. */
+    async function converge_at(pose, options = {}) {
+        write_pose(pose);
+        renderer.indicate_view_change();
+        return capture_average(options);
+    }
+
+    /**
+     * GPU-bound frame time, with the swap chain out of the measurement.
+     *
+     * Submits `frames` frames back to back and waits once, so the queue stays full and the number
+     * is throughput rather than latency. Interleave the settings being compared and take medians —
+     * a single reading here is worth nothing.
+     */
+    async function time_frames({ frames = 120 } = {}) {
+        await settle(8);
+
+        const started = performance.now();
+
+        for (let i = 0; i < frames; i++) {
+            frame();
+        }
+
+        await device.queue.onSubmittedWorkDone();
+
+        return (performance.now() - started) / frames;
+    }
+
+    /**
+     * Per-pass GPU durations, recorded and decoded in the page.
+     *
+     * This is the number to believe about cost, and the README says why in one line: at 1080p,
+     * whole-frame timing of Q-04 came back with the wrong sign three runs in a row while the
+     * per-pass capture read it cleanly. `time` measures a frame; this measures the passes the change
+     * is supposed to move.
+     *
+     * The `.sgpt` never reaches disk — the session's bytes go straight through `sgpt_read_capture`.
+     * A downloaded capture is the right artefact when the point is to keep it; when the point is a
+     * number, a file the browser may decline to save the second time is a step to skip.
+     *
+     * Two things about the draining. A frame is committed when its timestamp readback lands, a
+     * `mapAsync` a frame or two behind submit, so stopping the instant the last frame is encoded
+     * discards exactly the frames you asked for. And the readback resolves on a task, not on
+     * `onSubmittedWorkDone`, so the drain has to yield to the event loop rather than only to the
+     * queue.
+     *
+     * @param {object} [options]
+     * @param {number} [options.frames] frames to record
+     * @param {number} [options.settle] frames to run before recording starts
+     * @returns {Promise<Object<string, number>>} median duration in ms per pass label, plus
+     * `__frames` and `__defects`
+     */
+    async function profile_passes({ frames = 40, settle: settle_frames = 20 } = {}) {
+        const { GPUProfileSession } = await import('../../device/timing/profile/GPUProfileSession.js');
+        const { GPUProfileLevel } = await import('../../device/timing/profile/GPUProfileLevel.js');
+        const { sgpt_read_capture } = await import('../../device/timing/profile/sgpt_read_capture.js');
+
+        await settle(settle_frames);
+
+        const session = new GPUProfileSession({ level: GPUProfileLevel.WORKLOAD, note: 'measure.js' });
+
+        renderer.profile_session = session;
+        session.start();
+
+        await settle(frames);
+
+        for (let i = 0; i < 20; i++) {
+            await new Promise(resolve => setTimeout(resolve, 40));
+            frame();
+            await device.queue.onSubmittedWorkDone();
+        }
+
+        renderer.profile_session = null;
+
+        await device.queue.onSubmittedWorkDone();
+        await new Promise(resolve => setTimeout(resolve, 200));
+
+        const bytes = session.stop();
+
+        const buffer = bytes instanceof ArrayBuffer
+            ? bytes
+            : bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+
+        const capture = sgpt_read_capture(buffer);
+
+        // Summed per frame before the median is taken across frames, because one frame graph pass
+        // routinely opens several GPU passes and a label is not unique — see GPUProfileSpan.
+        const per_frame = new Map();
+
+        for (const recorded of capture.frames) {
+            const totals = new Map();
+
+            for (const span of recorded.spans) {
+                totals.set(span.label, (totals.get(span.label) ?? 0) + span.duration_ns * 1e-6);
+            }
+
+            for (const [label, ms] of totals) {
+                if (!per_frame.has(label)) {
+                    per_frame.set(label, []);
+                }
+
+                per_frame.get(label).push(ms);
+            }
+        }
+
+        const out = { __frames: capture.frames.length, __defects: capture.defects.length };
+
+        for (const [label, values] of per_frame) {
+            values.sort((a, b) => a - b);
+            out[label] = values[values.length >> 1];
+        }
+
+        return out;
+    }
+
+    /**
+     * Raise the internal resolution until the GPU is the bottleneck. The page's loop assigns
+     * `renderer.pixel_ratio` from `window.devicePixelRatio` every tick, so the property has to go
+     * rather than the field.
+     */
+    function set_pixel_ratio(ratio) {
+        Object.defineProperty(window, 'devicePixelRatio', { get: () => ratio, configurable: true });
+        renderer.pixel_ratio = ratio;
+        make_target();
+        renderer.indicate_view_change();
+    }
+
+    return {
+        renderer, scene, camera, controller, device,
+        get capture() { return capture; },
+        make_target, target, frame, settle, accumulate_luminance,
+        capture: capture_average, compare, mean, ab,
+        read_pose, write_pose, interpolate, fly, series_stats, converge_at,
+        time: time_frames, profile: profile_passes, set_pixel_ratio,
+    };
+}