@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/playground/ground_seam/measure_flicker.js

@@ -0,0 +1,531 @@
+import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
+import { GPUTextureContext } from "../../renderer/texture/GPUTextureContext.js";
+
+/**
+ * Temporal-difference measurement for the ground-seam repro.
+ *
+ * ## Why it renders into its own texture
+ *
+ * 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. `Renderer.render_to_target`
+ * exists for exactly this and shares the view context, so all the temporal history the measurement
+ * is *about* is the same history the on-screen path accumulates.
+ *
+ * Driving the frames from here rather than off `requestAnimationFrame` also takes the swap chain
+ * out of the loop, so the number of frames the temporal filter has seen is a number this module
+ * chose rather than one the compositor handed it.
+ *
+ * ## Why the seam is classified, not fitted
+ *
+ * The brief this repro came from retracted a conclusion that had been *fitted* to the seam's
+ * apparent slope, and the fit was wrong because the observer's camera basis had a sign error in it.
+ * Nothing here fits anything. Each pixel is unprojected through the camera's own
+ * `view_projection_matrix`, intersected with the ground plane, and labelled by the sign of
+ * `x + z` — which is the shared edge of the default triangulation, derived from the index buffer
+ * rather than from the picture. {@link classify_ground} round-trips one pixel back through the
+ * forward matrix and reports the error, so a broken convention shows up as a number instead of as a
+ * plausible story.
+ */
+
+/**
+ * @param {number} h a float16 bit pattern
+ * @returns {number}
+ */
+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);
+}
+
+/**
+ * Which of the ground quad's two triangles covers each pixel, and where on the plane it lands.
+ *
+ * The classification is `sign(x + z)`: the default triangulation's shared edge is the world line
+ * `x = −z` (v2→v1 of `make_plane_geometry`'s 1×1 quad, laid flat by the −90° X rotation), so the
+ * two triangles are exactly the two sides of `x + z = 0`. For the flipped index buffer the shared
+ * edge is `x = z` instead, so `side_flipped` carries `sign(x − z)` alongside it and a caller can
+ * ask about whichever diagonal is currently in the mesh.
+ *
+ * @param {PerspectiveCamera} camera must already have had `update_matrices` run for this frame
+ * @param {number} width in pixels
+ * @param {number} height in pixels
+ * @param {number} [extent] half-width of the quad; pixels outside it are not ground
+ * @returns {{side: Int8Array, side_flipped: Int8Array, round_trip_error_px: number, covered: number}}
+ * `side` is −1, +1 or 0 (not ground). `round_trip_error_px` is the worst error, in pixels, from
+ * projecting a recovered world point back through the forward matrix — a sanity check on the whole
+ * convention, which should be a small fraction of a pixel.
+ */
+export function classify_ground(camera, width, height, extent = 212.5) {
+
+    const inverse = new Float64Array(16);
+
+    if (!m4_invert(inverse, camera.view_projection_matrix)) {
+        throw new Error('camera view-projection matrix is not invertible');
+    }
+
+    const forward = camera.view_projection_matrix;
+
+    const side = new Int8Array(width * height);
+    const side_flipped = new Int8Array(width * height);
+
+    let round_trip_error_px = 0;
+    let covered = 0;
+
+    /**
+     * NDC → world, with the homogeneous divide.
+     *
+     * @param {number} ndc_x
+     * @param {number} ndc_y
+     * @param {number} ndc_z
+     * @param {number[]} out
+     */
+    function unproject(ndc_x, ndc_y, ndc_z, out) {
+        const x = inverse[0] * ndc_x + inverse[4] * ndc_y + inverse[8] * ndc_z + inverse[12];
+        const y = inverse[1] * ndc_x + inverse[5] * ndc_y + inverse[9] * ndc_z + inverse[13];
+        const z = inverse[2] * ndc_x + inverse[6] * ndc_y + inverse[10] * ndc_z + inverse[14];
+        const w = inverse[3] * ndc_x + inverse[7] * ndc_y + inverse[11] * ndc_z + inverse[15];
+
+        out[0] = x / w;
+        out[1] = y / w;
+        out[2] = z / w;
+    }
+
+    const near_point = [0, 0, 0];
+    const far_point = [0, 0, 0];
+
+    for (let py = 0; py < height; py++) {
+
+        /*
+         Framebuffer rows run top to bottom and NDC Y runs bottom to top, so the row index is
+         flipped here. This is precisely the convention the retracted analysis got wrong, which is
+         why `round_trip_error_px` below re-derives the pixel from the world point instead of
+         trusting this line.
+        */
+        const ndc_y = 1 - 2 * (py + 0.5) / height;
+
+        for (let px = 0; px < width; px++) {
+            const ndc_x = 2 * (px + 0.5) / width - 1;
+
+            // reverse-Z with an infinite far plane: z = 1 is the near plane, z = 0 is infinity.
+            // Two points at different depths give a ray without needing to know which is which.
+            unproject(ndc_x, ndc_y, 1, near_point);
+            unproject(ndc_x, ndc_y, 0.5, far_point);
+
+            const dx = far_point[0] - near_point[0];
+            const dy = far_point[1] - near_point[1];
+            const dz = far_point[2] - near_point[2];
+
+            if (dy === 0) {
+                continue;
+            }
+
+            // intersect the ray with the ground plane, y = 0
+            const t = -near_point[1] / dy;
+
+            if (t < 0) {
+                // the plane is behind the ray's start — this pixel is sky
+                continue;
+            }
+
+            const wx = near_point[0] + dx * t;
+            const wz = near_point[2] + dz * t;
+
+            if (Math.abs(wx) > extent || Math.abs(wz) > extent) {
+                continue;
+            }
+
+            const index = py * width + px;
+
+            side[index] = wx + wz >= 0 ? 1 : -1;
+            side_flipped[index] = wx - wz >= 0 ? 1 : -1;
+
+            covered++;
+
+            /*
+             Round-trip check, on a sparse sample so it costs nothing: push the recovered world
+             point back through the *forward* matrix and see whether it lands on the pixel it came
+             from. Any sign error, row flip or depth-range mistake in the block above shows up here
+             as a large number rather than as a confident wrong answer.
+            */
+            if ((px & 63) === 0 && (py & 63) === 0) {
+                const cx = forward[0] * wx + forward[8] * wz + forward[12];
+                const cy = forward[1] * wx + forward[9] * wz + forward[13];
+                const cw = forward[3] * wx + forward[11] * wz + forward[15];
+
+                const back_px = (cx / cw * 0.5 + 0.5) * width - 0.5;
+                const back_py = (0.5 - cy / cw * 0.5) * height - 0.5;
+
+                round_trip_error_px = Math.max(
+                    round_trip_error_px,
+                    Math.abs(back_px - px),
+                    Math.abs(back_py - py)
+                );
+            }
+        }
+    }
+
+    return { side, side_flipped, round_trip_error_px, covered };
+}
+
+/**
+ * Owns the render target, the readback buffer, and the frame-driving loop.
+ *
+ * @param {object} context
+ * @param {Renderer} context.renderer
+ * @param {Scene} context.scene
+ * @param {PerspectiveCamera} context.camera
+ */
+export function attach_measurement({ renderer, scene, camera }) {
+
+    const device = renderer.device;
+
+    /** @type {object|null} */
+    let capture = null;
+
+    function make_target() {
+        if (capture !== null) {
+            capture.texture.destroy();
+            capture.buffer.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: 'ground_seam/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: 'ground_seam/readback',
+                size: bytes_per_row * height,
+                usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+            }),
+        };
+
+        return capture;
+    }
+
+    function target() {
+        const resolution = renderer.output_resolution;
+
+        if (capture === null || capture.width !== resolution.x || capture.height !== resolution.y) {
+            make_target();
+        }
+
+        return capture;
+    }
+
+    /**
+     * One frame into the owned target.
+     * @param {number} [time_delta_s]
+     */
+    function frame(time_delta_s = 1 / 60) {
+        renderer.render_to_target(camera, scene, time_delta_s, target().target);
+    }
+
+    /**
+     * `n` frames with nothing read back, for letting the temporal filter converge.
+     * @param {number} n
+     */
+    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.
+     *
+     * @param {Float32Array} out length width*height
+     */
+    async function read_luminance(out) {
+        const c = target();
+
+        const encoder = device.createCommandEncoder({ label: 'ground_seam/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: the preferred canvas format on Windows is `bgra8unorm`,
+         and weighting it as if it were RGBA 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 stride = c.bytes_per_row;
+
+            const bgra = c.format.startsWith('bgra');
+
+            const r_offset = bgra ? 2 : 0;
+            const b_offset = bgra ? 0 : 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 * source[i + r_offset]
+                        + 0.7152 * source[i + 1]
+                        + 0.0722 * source[i + b_offset]
+                    ) / 255;
+                }
+            }
+        }
+
+        c.buffer.unmap();
+    }
+
+    /**
+     * Drive `frames` frames with the camera perfectly still and record, per pixel, the spread of
+     * luminance across the burst.
+     *
+     * `max − min` rather than a variance: a pixel that alternates between two values every frame and
+     * a pixel that drifts once both matter, and the spread catches both without weighting by how
+     * many frames were spent at each value.
+     *
+     * @param {object} [options]
+     * @param {number} [options.settle_frames] frames to converge before recording
+     * @param {number} [options.frames] frames in the burst
+     * @returns {Promise<{spread: Float32Array, mean: Float32Array, width: number, height: number}>}
+     */
+    async function burst({ settle_frames = 240, frames = 16 } = {}) {
+
+        await settle(settle_frames);
+
+        const c = target();
+
+        const count = c.width * c.height;
+
+        const current = new Float32Array(count);
+        const min = new Float32Array(count).fill(Infinity);
+        const max = new Float32Array(count).fill(-Infinity);
+        const total = new Float64Array(count);
+
+        for (let i = 0; i < frames; i++) {
+            frame();
+
+            await read_luminance(current);
+
+            for (let p = 0; p < count; p++) {
+                const v = current[p];
+
+                if (v < min[p]) {
+                    min[p] = v;
+                }
+
+                if (v > max[p]) {
+                    max[p] = v;
+                }
+
+                total[p] += v;
+            }
+        }
+
+        const spread = new Float32Array(count);
+        const mean = new Float32Array(count);
+
+        for (let p = 0; p < count; p++) {
+            spread[p] = max[p] - min[p];
+            mean[p] = total[p] / frames;
+        }
+
+        return { spread, mean, width: c.width, height: c.height };
+    }
+
+    /** @type {object|null} */
+    let depth_readback = null;
+
+    /**
+     * The frame's depth buffer, as the rasterizer left it.
+     *
+     * `Renderer.texture_depth_current` is public and the texture already carries `COPY_SRC`, so
+     * this needs no shader and no graph hook — what comes back is the rasterizer's own output,
+     * unmodified by anything downstream.
+     *
+     * It is at the *internal* resolution (output × `internal_resolution_scale`), so a caller lining
+     * it up against a colour readback has to use the size reported here rather than assume the two
+     * agree.
+     *
+     * @returns {Promise<{depth: Float32Array, width: number, height: number}>}
+     */
+    async function read_depth() {
+        const texture = renderer.texture_depth_current;
+
+        const width = texture.width;
+        const height = texture.height;
+
+        const bytes_per_row = Math.ceil(width * 4 / 256) * 256;
+
+        if (depth_readback === null
+            || depth_readback.width !== width
+            || depth_readback.height !== height) {
+
+            if (depth_readback !== null) {
+                depth_readback.buffer.destroy();
+            }
+
+            depth_readback = {
+                width,
+                height,
+                bytes_per_row,
+                buffer: device.createBuffer({
+                    label: 'ground_seam/depth_readback',
+                    size: bytes_per_row * height,
+                    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+                }),
+            };
+        }
+
+        const encoder = device.createCommandEncoder({ label: 'ground_seam/depth' });
+
+        encoder.copyTextureToBuffer(
+            { texture: texture.gpu_texture, mipLevel: 0 },
+            { buffer: depth_readback.buffer, bytesPerRow: bytes_per_row },
+            [width, height, 1]
+        );
+
+        device.queue.submit([encoder.finish()]);
+
+        await depth_readback.buffer.mapAsync(GPUMapMode.READ);
+
+        const raw = new Float32Array(depth_readback.buffer.getMappedRange());
+
+        const depth = new Float32Array(width * height);
+
+        const stride = bytes_per_row / 4;
+
+        for (let y = 0; y < height; y++) {
+            depth.set(raw.subarray(y * stride, y * stride + width), y * width);
+        }
+
+        depth_readback.buffer.unmap();
+
+        return { depth, width, height };
+    }
+
+    return {
+        frame,
+        settle,
+        burst,
+        read_depth,
+        get capture() {
+            return target();
+        },
+    };
+}
+
+/**
+ * Where a world-space line on the ground plane lands on screen, as a signed-distance function.
+ *
+ * A projective map takes a straight line to a straight line, so two projected points are the whole
+ * of it. This exists so a profile can be taken *across* the seam in pixels: the half-plane means a
+ * split reports cannot tell a step at the boundary from a smooth gradient over the whole frame, and
+ * that is exactly the difference between "a seam" and "one half of the view is more oblique".
+ *
+ * @param {PerspectiveCamera} camera
+ * @param {number} width
+ * @param {number} height
+ * @param {number[]} direction unit direction of the line in the XZ plane
+ * @returns {function(number, number): number} pixel → signed perpendicular distance, in pixels
+ */
+export function screen_line_distance(camera, width, height, direction) {
+
+    const m = camera.view_projection_matrix;
+
+    /**
+     * @param {number} x
+     * @param {number} z
+     * @returns {number[]} pixel coordinates
+     */
+    function project(x, z) {
+        const cx = m[0] * x + m[8] * z + m[12];
+        const cy = m[1] * x + m[9] * z + m[13];
+        const cw = m[3] * x + m[11] * z + m[15];
+
+        return [
+            (cx / cw * 0.5 + 0.5) * width - 0.5,
+            (0.5 - cy / cw * 0.5) * height - 0.5,
+        ];
+    }
+
+    /*
+     Two points on the line, both well inside the frustum. Taking them near the camera rather than
+     at the quad's corners keeps them away from the eye plane, where a projected point's magnitude
+     explodes and the difference of two large numbers is all rounding.
+    */
+    const a = project(direction[0] * 5, direction[1] * 5);
+    const b = project(direction[0] * -5, direction[1] * -5);
+
+    const dx = b[0] - a[0];
+    const dy = b[1] - a[1];
+
+    const length = Math.hypot(dx, dy);
+
+    if (!(length > 1e-6)) {
+        throw new Error('the seam projects to a point — the camera is looking along it');
+    }
+
+    // 2D cross product with the line direction gives the signed perpendicular offset
+    return (px, py) => ((px - a[0]) * dy - (py - a[1]) * dx) / length;
+}

package/src/shade/playground/image_decode_bench/README.md

@@ -0,0 +1,42 @@
+# Image decode bench
+
+Measures the trade `ImageRGBADataLoader`'s codec chain would make by decoding JPEG in the image worker
+instead of leaving it to the browser. Run under the dev server (`npm run dev`) at
+`src/shade/playground/image_decode_bench/index.html`; it fetches three Sponza textures from
+`test_assets/` and reports medians of five runs per path after a warm-up.
+
+## Result, 2026-09-02
+
+Embedded Chromium (Claude Code's browser pane), Windows 11, this workstation. Medians.
+
+| texture | size | native wall | native main | js-main wall | js-worker wall | js-worker main |
+|---|---|---|---|---|---|---|
+| 8747919177698443163.jpg | 1024×1024, 852 KB | 10.6 ms | 1.4 ms | 172.6 ms | 177.7 ms | 0.1 ms |
+| 6047387724914829168.jpg | 1024×1024, 506 KB | 8.8 ms | 1.7 ms | 151.4 ms | 155.2 ms | 0.1 ms |
+| 2051777328469649772.jpg | 1024×1024, 202 KB | 6.0 ms | 1.5 ms | 129.9 ms | 128.5 ms | 0.0 ms |
+
+*native*: the browser's decoder through `createImageBitmap`, then the canvas read-back
+`NativeImageDecoder` pays on the main thread. *js-main*: `format/image/jpeg` on the main thread.
+*js-worker*: the same decoder in a module worker, bytes transferred both ways; *main* is posting and
+receiving.
+
+## Decision
+
+**JPEG stays with the browser's decoder. The worker does not learn it.**
+
+The in-tree decoder is fifteen to twenty times slower than the platform's, and moving it to a worker
+does not change that — it changes who waits. What the worker buys is about 1.5 ms of main-thread time
+per megapixel texture (the read-back), and what it costs is about 150 ms of latency per texture that
+every load would pay. For a loading screen that is the wrong trade outright; for streaming during play
+a 1.5 ms read-back is under a frame's budget and a 150 ms decode is not something to hide, it is
+something to avoid.
+
+`ThreadedImageDecoder` therefore keeps sniffing PNG only, and says so with these numbers. Where there
+is no browser decoder — node, a worker without `Image` — `JpegCodec` answers, on the thread it is
+called from, which is the only thread there is. If the in-tree decoder ever gets within about 2× of the
+platform's, this page is the thing to re-run, and the change is one sniff in `ThreadedImageDecoder`
+and one arm in `ImageDecoderWorker`.
+
+The `Image.decode()` form `NativeImageDecoder` uses never resolves on a blob URL in the embedded
+browser this was measured in; the page uses `createImageBitmap`, which is the same decoder. The
+read-back is what differs between the two loaders and it is measured either way.

package/src/shade/playground/image_decode_bench/decode_worker.d.ts

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

package/src/shade/playground/image_decode_bench/decode_worker.d.ts.map

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

package/src/shade/playground/image_decode_bench/decode_worker.js

@@ -0,0 +1,19 @@
+import { jpeg_decode } from "../../../format/image/jpeg/jpeg_decode.js";
+
+/**
+ * The in-tree JPEG decoder, one image per message. What `ImageDecoderWorker` would do for a JPEG,
+ * without the `WorkerBuilder` plumbing and the rollup bundle between: a module worker importing the
+ * decoder directly, so the number is the decoder's and not the bundle's.
+ */
+self.onmessage = (event) => {
+    const { id, buffer } = event.data;
+
+    const started = performance.now();
+    const image = jpeg_decode(buffer);
+    const decode_ms = performance.now() - started;
+
+    self.postMessage(
+        { id, decode_ms, width: image.width, height: image.height, data: image.data.buffer },
+        [image.data.buffer]
+    );
+};

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

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — image decode bench</title>
+    <style>
+        :root { color-scheme: dark; }
+        html, body { margin: 0; background: #0d0f12; color: #d6dae0; font: 13px/1.5 ui-monospace, Consolas, monospace; }
+        main { padding: 16px 20px; max-width: 1100px; }
+        h1 { font-size: 15px; margin: 0 0 4px; }
+        p { color: #8b939f; margin: 0 0 12px; max-width: 80ch; }
+        table { border-collapse: collapse; margin-top: 12px; }
+        td, th { padding: 3px 12px 3px 0; text-align: right; white-space: nowrap; }
+        th { color: #8b939f; font-weight: normal; border-bottom: 1px solid #2b3038; }
+        td:first-child, th:first-child { text-align: left; }
+        #status { color: #e5b54a; }
+    </style>
+</head>
+<body>
+<main>
+    <h1>JPEG decode: the browser's decoder against the in-tree one, on and off the main thread</h1>
+    <p>
+        Each row is one Sponza texture, decoded several times per path after one warm-up. <b>wall</b> is
+        what a caller waits for; <b>main</b> is how long the main thread was busy doing it. The native
+        path is what <code>NativeImageDecoder</code> does — <code>new Image()</code>, <code>decode()</code>,
+        a canvas read-back — so its <b>main</b> is the read-back. The worker path is the in-tree decoder in a
+        module worker, so its <b>main</b> is posting and receiving.
+    </p>
+    <div id="status">loading…</div>
+    <table id="results"></table>
+</main>
+<script type="module" src="./main.js"></script>
+</body>
+</html>

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

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

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

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