@woosh/meep-engine 3.14.0 → 3.14.2

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

@@ -0,0 +1,242 @@
+import { FramePhase } from "../../renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+import { SceneColor } from "../../renderer/extension/SceneColor.js";
+import { ImageShader } from "../../renderer/shader/ImageShader.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { graph_image_pass } from "../../renderer/shader/graph/graph_image_pass.js";
+import { graph_import_texture } from "../../renderer/shader/graph/graph_import_texture.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../renderer/shader/ShaderDescriptor.js";
+import { GPUTextureContext } from "../../renderer/texture/GPUTextureContext.js";
+
+/**
+ * Copy the scene colour, exactly, into a texture the caller owns.
+ *
+ * A `textureLoad` at the fragment's own integer coordinate — no sampler, no filtering, no
+ * conversion. The point of this capture is to compare frames against each other at the texel, so
+ * anything that mixed neighbours would put the answer into the measurement.
+ */
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup().addTexture("tSource");
+
+const shader_copy_scene_color = new ImageShader({
+    descriptor: ShaderDescriptor.from({
+        label: "ground_seam/copy scene colour",
+        resources,
+        body: CodeChunk.from(
+            //language=WGSL
+            `
+@fragment
+fn main(
+    @builtin(position) coord: vec4<f32>,
+) -> @location(0) vec4<f32> {
+    return textureLoad(tSource, vec2<u32>(coord.xy), 0);
+}
+`
+        ),
+    }),
+    targets: [
+        {
+            label: "ground_seam capture",
+            format: "rgba16float",
+        }
+    ],
+});
+
+/**
+ * The scene colour *before* the temporal filter, made readable.
+ *
+ * This exists to split one question in two. The burst measurement sees the picture the temporal
+ * filter produced, and a seam in it can come from either side of that filter: the shading may be
+ * responding differently to the sub-pixel jitter on the two triangles, or the shading may be
+ * identical and the filter may be resolving it differently. Those want opposite fixes, and no
+ * amount of staring at the output distinguishes them.
+ *
+ * {@link FramePhase.AfterTransparency} is the last phase before the upscale, so what is captured
+ * here is the full pre-TAA frame at internal resolution — the temporal filter's *input*.
+ *
+ * The pass writes an imported texture, which the graph treats as a side effect, so it is not elided
+ * for having no consumer inside the frame.
+ */
+export class CaptureSceneColor extends RenderExtension {
+    name = 'ground_seam/capture scene colour';
+
+    /**
+     * Which phase to capture at. {@link FramePhase.AfterTransparency} is the temporal filter's
+     * *input* — the last phase before the upscale. {@link FramePhase.BeforePresent} is its output,
+     * still HDR but past DOF, motion blur and bloom. Capturing at both is how the chain gets split
+     * into 'what TAA was given' and 'what TAA produced'.
+     *
+     * Assigning it after the extension is registered has no effect: the registry resolves the
+     * ordering when an extension is added, so a phase change means removing and re-adding.
+     *
+     * @type {FramePhase}
+     */
+    phase = FramePhase.AfterTransparency;
+
+    /**
+     * @type {GPUTextureContext|undefined}
+     */
+    #texture;
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * @type {GPUBuffer|undefined}
+     */
+    #buffer;
+
+    #width = 0;
+    #height = 0;
+    #bytes_per_row = 0;
+
+    /**
+     * Whether to record at all. Off by default: a capture costs a full-resolution copy every frame,
+     * and the burst measurement this page mostly runs does not want one.
+     *
+     * @type {boolean}
+     */
+    enabled = false;
+
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        super();
+
+        this.#device = device;
+    }
+
+    /**
+     * @param {number} width
+     * @param {number} height
+     */
+    #ensure(width, height) {
+        if (this.#width === width && this.#height === height) {
+            return;
+        }
+
+        this.#texture?.destroy();
+        this.#buffer?.destroy();
+
+        const device = this.#device;
+
+        this.#texture = GPUTextureContext.fromTexture(
+            device.createTexture({
+                label: 'ground_seam/scene colour capture',
+                size: [width, height, 1],
+                format: 'rgba16float',
+                usage: GPUTextureUsage.RENDER_ATTACHMENT
+                    | GPUTextureUsage.TEXTURE_BINDING
+                    | GPUTextureUsage.COPY_SRC,
+            }),
+            device
+        );
+
+        this.#bytes_per_row = Math.ceil(width * 8 / 256) * 256;
+
+        this.#buffer = device.createBuffer({
+            label: 'ground_seam/scene colour readback',
+            size: this.#bytes_per_row * height,
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+        });
+
+        this.#width = width;
+        this.#height = height;
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        if (!this.enabled) {
+            return;
+        }
+
+        const colour = frame.get(SceneColor).color;
+
+        const resolution = frame.resolution;
+
+        this.#ensure(resolution[0], resolution[1]);
+
+        graph_image_pass({
+            graph: frame.graph,
+            shader: shader_copy_scene_color,
+            inputs: { tSource: colour },
+            output: [graph_import_texture(frame.graph, this.#texture, 'ground_seam capture')],
+        });
+    }
+
+    /**
+     * Luminance of the captured frame, one entry per pixel.
+     *
+     * Rec. 709 weights on the linear HDR values — this is upstream of the tonemap, so the numbers
+     * are radiance rather than display code values and there is no 8-bit quantization floor under
+     * the measurement.
+     *
+     * @returns {Promise<{luma: Float32Array, width: number, height: number}>}
+     */
+    async read_luminance() {
+        if (this.#texture === undefined) {
+            throw new Error('nothing has been captured yet — enable the extension and render a frame');
+        }
+
+        const device = this.#device;
+
+        const encoder = device.createCommandEncoder({ label: 'ground_seam/scene colour readback' });
+
+        encoder.copyTextureToBuffer(
+            { texture: this.#texture.gpu_texture, mipLevel: 0 },
+            { buffer: this.#buffer, bytesPerRow: this.#bytes_per_row },
+            [this.#width, this.#height, 1]
+        );
+
+        device.queue.submit([encoder.finish()]);
+
+        await this.#buffer.mapAsync(GPUMapMode.READ);
+
+        const source = new Uint16Array(this.#buffer.getMappedRange());
+
+        const stride = this.#bytes_per_row / 2;
+
+        const luma = new Float32Array(this.#width * this.#height);
+
+        for (let y = 0; y < this.#height; y++) {
+            for (let x = 0; x < this.#width; x++) {
+                const i = y * stride + x * 4;
+
+                luma[y * this.#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]);
+            }
+        }
+
+        this.#buffer.unmap();
+
+        return { luma, width: this.#width, height: this.#height };
+    }
+}
+
+/**
+ * @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);
+}

package/src/shade/playground/ground_seam/depth_step_across_seam.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @param {Float32Array} depth
+ * @param {Int8Array} side −1 / +1 / 0, as {@link classify_ground} produces
+ * @param {function(number, number): number} distance signed screen distance to the seam, in pixels
+ * @param {number} width
+ * @param {number} height
+ * @param {number} [exclude] pixels either side of the seam to leave out of the fits
+ * @returns {object}
+ */
+export function depth_step_across_seam(depth: Float32Array, side: Int8Array, distance: (arg0: number, arg1: number) => number, width: number, height: number, exclude?: number): object;
+//# sourceMappingURL=depth_step_across_seam.d.ts.map

package/src/shade/playground/ground_seam/depth_step_across_seam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"depth_step_across_seam.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ground_seam/depth_step_across_seam.js"],"names":[],"mappings":"AAgHA;;;;;;;;GAQG;AACH,8CARW,YAAY,QACZ,SAAS,mBACA,MAAM,QAAE,MAAM,KAAG,MAAM,SAChC,MAAM,UACN,MAAM,YACN,MAAM,GACJ,MAAM,CAiElB"}

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

@@ -0,0 +1,185 @@
+/**
+ * Does the rasterized depth step across the shared edge, and by how much?
+ *
+ * This is the first of the checks the ground-seam brief calls for and the only one that reaches the
+ * rasterizer's own output rather than an inference about it. The reasoning it rests on:
+ *
+ * Under a reverse-Z, infinite-far projection the depth written is `near / (−z_view)`, and
+ * `1/(−z_view)` is an affine function of the screen coordinate over a planar surface. So the depth
+ * across each of the ground quad's triangles is **exactly** a plane in `(x, y)` — not approximately.
+ * The two triangles share two vertices, so the seam is one segment and both interpolations must
+ * agree along it. Whether they *do* is a number.
+ *
+ * Each side is fitted separately by least squares over pixels at least `exclude` from the seam, so
+ * neither fit sees the other's pixels or the boundary's partially covered ones. The two fits are
+ * then evaluated *on* the seam and differenced. The residuals come back with them: the fit is exact
+ * for a plane, so a residual much above the depth format's own quantization means the premise is
+ * broken and the difference is not the quantity it claims to be.
+ */
+
+/**
+ * Least-squares fit of `depth ≈ a·x + b·y + c` over the pixels a predicate accepts.
+ *
+ * Normal equations in f64 over a 3×3 symmetric system. The coordinates are centred on the frame
+ * before the system is built — `x` running to 1258 against a constant term of 1 spans six orders of
+ * magnitude, and the inverse of that would be all rounding.
+ *
+ * @param {Float32Array} depth
+ * @param {number} width
+ * @param {number} height
+ * @param {function(number): boolean} accept given the pixel index
+ * @returns {{a: number, b: number, c: number, residual_rms: number, count: number}}
+ */
+function fit_plane(depth, width, height, accept) {
+    let sxx = 0, sxy = 0, sx1 = 0, syy = 0, sy1 = 0, s11 = 0;
+    let sxd = 0, syd = 0, s1d = 0;
+    let count = 0;
+
+    const cx = width * 0.5;
+    const cy = height * 0.5;
+
+    for (let py = 0; py < height; py++) {
+        for (let px = 0; px < width; px++) {
+            const p = py * width + px;
+
+            if (!accept(p)) {
+                continue;
+            }
+
+            const x = px - cx;
+            const y = py - cy;
+            const d = depth[p];
+
+            sxx += x * x;
+            sxy += x * y;
+            sx1 += x;
+            syy += y * y;
+            sy1 += y;
+            s11 += 1;
+            sxd += x * d;
+            syd += y * d;
+            s1d += d;
+
+            count++;
+        }
+    }
+
+    if (count < 16) {
+        throw new Error(`only ${count} pixels accepted — not enough to fit a plane`);
+    }
+
+    const m = [sxx, sxy, sx1, sxy, syy, sy1, sx1, sy1, s11];
+
+    const c00 = m[4] * m[8] - m[5] * m[7];
+    const c01 = m[5] * m[6] - m[3] * m[8];
+    const c02 = m[3] * m[7] - m[4] * m[6];
+
+    const det = m[0] * c00 + m[1] * c01 + m[2] * c02;
+
+    if (det === 0) {
+        throw new Error('degenerate depth fit');
+    }
+
+    const c10 = m[2] * m[7] - m[1] * m[8];
+    const c11 = m[0] * m[8] - m[2] * m[6];
+    const c12 = m[1] * m[6] - m[0] * m[7];
+    const c20 = m[1] * m[5] - m[2] * m[4];
+    const c21 = m[2] * m[3] - m[0] * m[5];
+    const c22 = m[0] * m[4] - m[1] * m[3];
+
+    const a = (c00 * sxd + c10 * syd + c20 * s1d) / det;
+    const b = (c01 * sxd + c11 * syd + c21 * s1d) / det;
+    const c = (c02 * sxd + c12 * syd + c22 * s1d) / det;
+
+    let residual = 0;
+
+    for (let py = 0; py < height; py++) {
+        for (let px = 0; px < width; px++) {
+            const p = py * width + px;
+
+            if (!accept(p)) {
+                continue;
+            }
+
+            const e = depth[p] - (a * (px - cx) + b * (py - cy) + c);
+
+            residual += e * e;
+        }
+    }
+
+    return { a, b, c, residual_rms: Math.sqrt(residual / count), count };
+}
+
+/**
+ * @param {Float32Array} depth
+ * @param {Int8Array} side −1 / +1 / 0, as {@link classify_ground} produces
+ * @param {function(number, number): number} distance signed screen distance to the seam, in pixels
+ * @param {number} width
+ * @param {number} height
+ * @param {number} [exclude] pixels either side of the seam to leave out of the fits
+ * @returns {object}
+ */
+export function depth_step_across_seam(depth, side, distance, width, height, exclude = 8) {
+
+    const far_enough = new Uint8Array(width * height);
+
+    for (let py = 0; py < height; py++) {
+        for (let px = 0; px < width; px++) {
+            far_enough[py * width + px] = Math.abs(distance(px, py)) >= exclude ? 1 : 0;
+        }
+    }
+
+    const negative = fit_plane(depth, width, height, p => side[p] === -1 && far_enough[p] === 1);
+    const positive = fit_plane(depth, width, height, p => side[p] === 1 && far_enough[p] === 1);
+
+    /*
+     Walk the seam and evaluate both fits along it. One point would do for two exact planes; the
+     walk reports the worst disagreement anywhere on the edge, which is what a slight *rotation*
+     between the two planes looks like and what a single sample would miss.
+    */
+    const cx = width * 0.5;
+    const cy = height * 0.5;
+
+    let worst = 0;
+    let worst_at = null;
+    let worst_ulps = 0;
+    let samples = 0;
+
+    for (let py = 0; py < height; py++) {
+        for (let px = 0; px < width; px++) {
+            if (Math.abs(distance(px, py)) > 0.5) {
+                continue;
+            }
+
+            const x = px - cx;
+            const y = py - cy;
+
+            const dn = negative.a * x + negative.b * y + negative.c;
+            const dp = positive.a * x + positive.b * y + positive.c;
+
+            const difference = Math.abs(dn - dp);
+
+            samples++;
+
+            if (difference > worst) {
+                worst = difference;
+                worst_at = [px, py];
+
+                // one ULP of an f32 at this magnitude, which is the unit the question is asked in
+                const magnitude = Math.max(Math.abs(dn), 1e-30);
+                const ulp = Math.pow(2, Math.floor(Math.log2(magnitude)) - 23);
+
+                worst_ulps = difference / ulp;
+            }
+        }
+    }
+
+    return {
+        negative,
+        positive,
+        seam_samples: samples,
+        worst_difference: worst,
+        worst_difference_ulps: worst_ulps,
+        worst_at,
+    };
+}

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

@@ -0,0 +1,195 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — ground seam repro</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --bg: #14161a;
+            --panel: #1c1f25;
+            --line: #2b3038;
+            --text: #d6dae0;
+            --muted: #8b939f;
+            --pass: #55c46a;
+            --fail: #ff6b6b;
+            --warn: #e5b54a;
+        }
+
+        * { box-sizing: border-box; }
+
+        body {
+            margin: 0;
+            padding: 16px;
+            background: var(--bg);
+            color: var(--text);
+            font: 13px/1.5 system-ui, -apple-system, Segoe UI, sans-serif;
+        }
+
+        h1 { font-size: 16px; font-weight: 600; margin: 0 0 4px; }
+
+        p.lede { margin: 0 0 14px; color: var(--muted); max-width: 90ch; }
+
+        .stage { display: flex; gap: 16px; align-items: flex-start; flex-wrap: wrap; }
+
+        canvas {
+            display: block;
+            border: 1px solid var(--line);
+            border-radius: 4px;
+            background: #000;
+        }
+
+        aside {
+            width: 300px;
+            background: var(--panel);
+            border: 1px solid var(--line);
+            border-radius: 8px;
+            padding: 12px 14px;
+        }
+
+        aside h2 {
+            font-size: 11px;
+            text-transform: uppercase;
+            letter-spacing: 0.06em;
+            color: var(--muted);
+            margin: 0 0 8px;
+        }
+
+        aside h2 + * { margin-top: 0; }
+
+        label { display: flex; gap: 8px; align-items: center; padding: 3px 0; }
+
+        label span { flex: 1; }
+
+        select, input[type="number"] {
+            font: inherit;
+            background: #14161a;
+            color: var(--text);
+            border: 1px solid var(--line);
+            border-radius: 4px;
+            padding: 3px 6px;
+            width: 110px;
+        }
+
+        button {
+            font: inherit;
+            padding: 6px 12px;
+            border-radius: 6px;
+            border: 1px solid var(--line);
+            background: #22303f;
+            color: var(--text);
+            cursor: pointer;
+            margin-top: 10px;
+            width: 100%;
+        }
+
+        button:disabled { opacity: 0.45; cursor: default; }
+
+        #status { color: var(--muted); }
+        #status.pass { color: var(--pass); }
+        #status.fail { color: var(--fail); }
+        #status.warn { color: var(--warn); }
+
+        pre {
+            background: #14161a;
+            border: 1px solid var(--line);
+            border-radius: 6px;
+            padding: 8px 10px;
+            font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
+            font-size: 11.5px;
+            white-space: pre-wrap;
+            margin: 10px 0 0;
+            max-height: 40vh;
+            overflow: auto;
+        }
+
+        hr { border: 0; border-top: 1px solid var(--line); margin: 12px 0; }
+    </style>
+</head>
+<body>
+
+<h1>ground seam — temporal repro</h1>
+<p class="lede">
+    One 425×425 ground quad, two triangles, a tiling grid albedo, a still camera. “Measure” settles
+    the temporal filter, records a burst of frames into a texture this page owns, and maps the
+    per-pixel luminance spread across the burst. Pixels are labelled by which triangle covers them
+    by unprojecting through the camera’s own matrix — nothing is fitted to the picture.
+</p>
+
+<div class="stage">
+    <div>
+        <canvas id="view"></canvas>
+        <canvas id="diff" style="margin-top: 12px"></canvas>
+    </div>
+
+    <aside>
+        <h2>scene</h2>
+
+        <label><span>subdivision</span>
+            <select id="segments">
+                <option value="1" selected>1 × 1 (2 tris)</option>
+                <option value="2">2 × 2</option>
+                <option value="8">8 × 8</option>
+                <option value="32">32 × 32</option>
+            </select>
+        </label>
+
+        <label><span>triangulation</span>
+            <select id="triangulation">
+                <option value="default" selected>default (x = −z)</option>
+                <option value="flipped">flipped (x = z)</option>
+                <option value="rotated">same tris, anchor rotated</option>
+            </select>
+        </label>
+
+        <label><span>extent</span>
+            <select id="extent">
+                <option value="425" selected>425</option>
+                <option value="4000">4000</option>
+                <option value="40000">40000</option>
+            </select>
+        </label>
+
+        <label><span>anisotropy</span><input type="checkbox" id="anisotropy" checked></label>
+
+        <label><span>ground yaw°</span><input type="number" id="yaw" value="0" step="90"></label>
+
+        <hr>
+
+        <h2>renderer</h2>
+
+        <label><span>TAA</span><input type="checkbox" id="taa" checked></label>
+        <label><span>GTAO</span><input type="checkbox" id="ssao" checked></label>
+        <label><span>shadows</span><input type="checkbox" id="shadows" checked></label>
+        <label><span>sharpening</span><input type="checkbox" id="sharpening" checked></label>
+        <label><span>auto exposure</span><input type="checkbox" id="exposure"></label>
+        <label><span>environment</span><input type="checkbox" id="environment"></label>
+
+        <label><span>exposure (stops)</span><input type="number" id="exposure_compensation" value="2.5" step="0.5"></label>
+
+        <label><span>width</span><input type="number" id="width" value="1258" step="2"></label>
+        <label><span>height</span><input type="number" id="height" value="566" step="2"></label>
+
+        <hr>
+
+        <h2>burst</h2>
+
+        <label><span>settle frames</span><input type="number" id="settle" value="240"></label>
+        <label><span>burst frames</span><input type="number" id="frames" value="16"></label>
+        <label><span>diff gain</span><input type="number" id="gain" value="8"></label>
+
+        <button id="measure">Measure</button>
+        <button id="apply">Apply scene / renderer</button>
+
+        <pre id="report">ready</pre>
+    </aside>
+</div>
+
+<script type="module">
+    import { start } from './main.js';
+
+    start();
+</script>
+
+</body>
+</html>

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

@@ -0,0 +1,2 @@
+export function start(): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

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

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