@woosh/meep-engine 3.11.3 → 3.12.0

package/src/shade/playground/skinned_blas_refit/verify_traversal_reachability.js

@@ -1,249 +1,249 @@
-import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
-import {
-    BLAS_VISIBILITY_SETTINGS_STRUCT,
-    shader_blas_audit_visibility
-} from "./shader_blas_audit_visibility.js";
-
-/**
- * Can the traversal reach every triangle in the tree?
- *
- * The last unexercised link. Everything about the tree itself checks out — leaf boxes contain the
- * triangles the intersector fetches, internal nodes are their children's union, the root matches an
- * independently computed box, the instance's world AABB contains the geometry, and the stack does
- * not overflow. None of that runs `ray_query_blas_nearest`, and that function is what the picture
- * is made of.
- *
- * So: one ray per triangle, from the camera to that triangle's own centroid. The centroid is inside
- * the triangle, so the ray intersects it, so a hit is guaranteed — this triangle, or whatever
- * occludes it. A miss cannot happen geometrically. Every miss is the traversal declining to enter a
- * box the ray is inside.
- *
- * Run it from a view that the picture disagrees at and from one it agrees at; the difference
- * between the two counts is the fault, expressed as triangles rather than pixels.
- */
-
-/**
- * @param {GPUDevice} device
- * @param {GPUBuffer} buffer
- * @param {number} size
- * @returns {Promise<ArrayBuffer>}
- */
-async function read_back(device, buffer, size) {
-    const staging = device.createBuffer({
-        label: 'reachability/readback',
-        size,
-        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
-    });
-
-    const encoder = device.createCommandEncoder({ label: 'reachability/readback' });
-
-    encoder.copyBufferToBuffer(buffer, 0, staging, 0, size);
-
-    device.queue.submit([encoder.finish()]);
-
-    await staging.mapAsync(GPUMapMode.READ);
-
-    const copy = staging.getMappedRange().slice(0);
-
-    staging.unmap();
-    staging.destroy();
-
-    return copy;
-}
-
-/**
- * Apply the inverse of a mesh's transform to a world point — the same trip `chunk_ray_query_nearest`
- * makes to put a ray into geometry space.
- *
- * Done on the host with a full inverse rather than by transposing a rotation, because the transform
- * carries the asset's centimetre scale and a shortcut that assumes orthonormality would silently be
- * a hundred times wrong here.
- *
- * @param {ArrayLike<number>} m column-major 4x4
- * @param {number[]} point
- * @returns {number[]}
- */
-function inverse_transform_point(m, point) {
-    const a = [
-        [m[0], m[4], m[8], m[12]],
-        [m[1], m[5], m[9], m[13]],
-        [m[2], m[6], m[10], m[14]],
-        [m[3], m[7], m[11], m[15]],
-    ];
-
-    const b = [point[0], point[1], point[2], 1];
-
-    // Gaussian elimination on the 4x4 — small, and clearer than an inlined cofactor expansion
-    for (let column = 0; column < 4; column++) {
-        let pivot = column;
-
-        for (let row = column + 1; row < 4; row++) {
-            if (Math.abs(a[row][column]) > Math.abs(a[pivot][column])) {
-                pivot = row;
-            }
-        }
-
-        [a[column], a[pivot]] = [a[pivot], a[column]];
-        [b[column], b[pivot]] = [b[pivot], b[column]];
-
-        const divisor = a[column][column];
-
-        for (let k = column; k < 4; k++) {
-            a[column][k] /= divisor;
-        }
-
-        b[column] /= divisor;
-
-        for (let row = 0; row < 4; row++) {
-            if (row === column) {
-                continue;
-            }
-
-            const factor = a[row][column];
-
-            for (let k = column; k < 4; k++) {
-                a[row][k] -= factor * a[column][k];
-            }
-
-            b[row] -= factor * b[column];
-        }
-    }
-
-    const w = b[3] === 0 ? 1 : b[3];
-
-    return [b[0] / w, b[1] / w, b[2] / w];
-}
-
-/**
- * @param {object} options
- * @param {Renderer} options.renderer
- * @param {PerspectiveCamera} options.camera whose position the rays start from
- * @param {Mesh} options.mesh the instance whose transform puts the camera into geometry space
- * @param {object} options.target refit target of the tree to audit
- * @param {number} options.geometry_index
- * @returns {Promise<object>}
- */
-export async function verify_traversal_reachability({
-                                                        renderer,
-                                                        camera,
-                                                        mesh,
-                                                        target,
-                                                        geometry_index,
-                                                    }) {
-    const graphics = renderer.graphics;
-    const device = graphics.device;
-
-    const geometries = graphics.geometries;
-    const blas = geometries.blas;
-    const meshlets = geometries.meshlets;
-
-    const { leaf_count, node_word_offset, leaf_nodes_offset } = target;
-
-    const origin = inverse_transform_point(
-        mesh.transform_global.matrix,
-        [...camera.transform.position]
-    );
-
-    const t_bytes = leaf_count * Float32Array.BYTES_PER_ELEMENT;
-
-    const out_t = device.createBuffer({
-        label: 'reachability/t',
-        size: t_bytes,
-        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
-    });
-
-    const out_triangle = device.createBuffer({
-        label: 'reachability/triangle',
-        size: t_bytes,
-        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
-    });
-
-    const out_expected_t = device.createBuffer({
-        label: 'reachability/expected t',
-        size: t_bytes,
-        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
-    });
-
-    const cmd = ShadeGPUCommandContext.create(graphics, 'audit/reachability');
-
-    shader_blas_audit_visibility.dispatchLinear({
-        encoder: cmd,
-        element_count: leaf_count,
-        bindings: {
-            settings: cmd.allocateTransientValueBuffer(BLAS_VISIBILITY_SETTINGS_STRUCT, {
-                origin,
-                leaf_count,
-                node_word_offset,
-                leaf_nodes_offset,
-                geometry_index,
-                tmax: 1e12,
-            }),
-            leaf_nodes: blas.buffer_leaf_nodes,
-            blas_lookup: blas.buffer_metadata,
-            blas_data: blas.buffer_data,
-            geometries: geometries.buffer_metadata,
-            meshlet_metadata: meshlets.buffer_metadata,
-            meshlet_data: meshlets.buffer_data,
-            nodes: blas.buffer_data,
-            out_t,
-            out_triangle,
-            out_expected_t,
-        },
-    });
-
-    cmd.finish();
-
-    await device.queue.onSubmittedWorkDone();
-
-    const t = new Float32Array(await read_back(device, out_t, t_bytes));
-    const expected = new Float32Array(await read_back(device, out_expected_t, t_bytes));
-
-    out_t.destroy();
-    out_triangle.destroy();
-    out_expected_t.destroy();
-
-    let missed = 0;
-    let overshot = 0;
-    let worst_overshoot = 0;
-
-    for (let i = 0; i < leaf_count; i++) {
-        if (!(t[i] >= 0)) {
-            missed += 1;
-
-            continue;
-        }
-
-        // 1e-3 of the aimed distance, which is far above float error on these magnitudes and far
-        // below the gap between one surface and the next
-        const overshoot = (t[i] - expected[i]) / Math.max(1e-9, expected[i]);
-
-        if (overshoot > 1e-3) {
-            overshot += 1;
-
-            worst_overshoot = Math.max(worst_overshoot, overshoot);
-        }
-    }
-
-    const lost = missed + overshot;
-
-    const result = {
-        leaf_count,
-        missed,
-        overshot,
-        worst_overshoot: +worst_overshoot.toFixed(4),
-        lost,
-        lost_pct: +(lost / leaf_count * 100).toFixed(3),
-        origin: origin.map(v => +v.toFixed(3)),
-        verdict: lost === 0
-            ? `pass — the traversal returns a surface at or before every one of ${leaf_count} `
-            + `triangles it was aimed at`
-            : `FAIL — ${lost} of ${leaf_count} (${(lost / leaf_count * 100).toFixed(2)}%) rays aimed `
-            + `at a triangle came back with nothing (${missed}) or with something behind it `
-            + `(${overshot}). Neither is geometrically possible, so the traversal is walking past `
-            + `surfaces it was pointed at — which is the hole in the traced image.`,
-    };
-
-    console.log(result.verdict, result);
-
-    return result;
-}
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import {
+    BLAS_VISIBILITY_SETTINGS_STRUCT,
+    shader_blas_audit_visibility
+} from "./shader_blas_audit_visibility.js";
+
+/**
+ * Can the traversal reach every triangle in the tree?
+ *
+ * The last unexercised link. Everything about the tree itself checks out — leaf boxes contain the
+ * triangles the intersector fetches, internal nodes are their children's union, the root matches an
+ * independently computed box, the instance's world AABB contains the geometry, and the stack does
+ * not overflow. None of that runs `ray_query_blas_nearest`, and that function is what the picture
+ * is made of.
+ *
+ * So: one ray per triangle, from the camera to that triangle's own centroid. The centroid is inside
+ * the triangle, so the ray intersects it, so a hit is guaranteed — this triangle, or whatever
+ * occludes it. A miss cannot happen geometrically. Every miss is the traversal declining to enter a
+ * box the ray is inside.
+ *
+ * Run it from a view that the picture disagrees at and from one it agrees at; the difference
+ * between the two counts is the fault, expressed as triangles rather than pixels.
+ */
+
+/**
+ * @param {GPUDevice} device
+ * @param {GPUBuffer} buffer
+ * @param {number} size
+ * @returns {Promise<ArrayBuffer>}
+ */
+async function read_back(device, buffer, size) {
+    const staging = device.createBuffer({
+        label: 'reachability/readback',
+        size,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+
+    const encoder = device.createCommandEncoder({ label: 'reachability/readback' });
+
+    encoder.copyBufferToBuffer(buffer, 0, staging, 0, size);
+
+    device.queue.submit([encoder.finish()]);
+
+    await staging.mapAsync(GPUMapMode.READ);
+
+    const copy = staging.getMappedRange().slice(0);
+
+    staging.unmap();
+    staging.destroy();
+
+    return copy;
+}
+
+/**
+ * Apply the inverse of a mesh's transform to a world point — the same trip `chunk_ray_query_nearest`
+ * makes to put a ray into geometry space.
+ *
+ * Done on the host with a full inverse rather than by transposing a rotation, because the transform
+ * carries the asset's centimetre scale and a shortcut that assumes orthonormality would silently be
+ * a hundred times wrong here.
+ *
+ * @param {ArrayLike<number>} m column-major 4x4
+ * @param {number[]} point
+ * @returns {number[]}
+ */
+function inverse_transform_point(m, point) {
+    const a = [
+        [m[0], m[4], m[8], m[12]],
+        [m[1], m[5], m[9], m[13]],
+        [m[2], m[6], m[10], m[14]],
+        [m[3], m[7], m[11], m[15]],
+    ];
+
+    const b = [point[0], point[1], point[2], 1];
+
+    // Gaussian elimination on the 4x4 — small, and clearer than an inlined cofactor expansion
+    for (let column = 0; column < 4; column++) {
+        let pivot = column;
+
+        for (let row = column + 1; row < 4; row++) {
+            if (Math.abs(a[row][column]) > Math.abs(a[pivot][column])) {
+                pivot = row;
+            }
+        }
+
+        [a[column], a[pivot]] = [a[pivot], a[column]];
+        [b[column], b[pivot]] = [b[pivot], b[column]];
+
+        const divisor = a[column][column];
+
+        for (let k = column; k < 4; k++) {
+            a[column][k] /= divisor;
+        }
+
+        b[column] /= divisor;
+
+        for (let row = 0; row < 4; row++) {
+            if (row === column) {
+                continue;
+            }
+
+            const factor = a[row][column];
+
+            for (let k = column; k < 4; k++) {
+                a[row][k] -= factor * a[column][k];
+            }
+
+            b[row] -= factor * b[column];
+        }
+    }
+
+    const w = b[3] === 0 ? 1 : b[3];
+
+    return [b[0] / w, b[1] / w, b[2] / w];
+}
+
+/**
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {PerspectiveCamera} options.camera whose position the rays start from
+ * @param {Mesh} options.mesh the instance whose transform puts the camera into geometry space
+ * @param {object} options.target refit target of the tree to audit
+ * @param {number} options.geometry_index
+ * @returns {Promise<object>}
+ */
+export async function verify_traversal_reachability({
+                                                        renderer,
+                                                        camera,
+                                                        mesh,
+                                                        target,
+                                                        geometry_index,
+                                                    }) {
+    const graphics = renderer.graphics;
+    const device = graphics.device;
+
+    const geometries = graphics.geometries;
+    const blas = geometries.blas;
+    const meshlets = geometries.meshlets;
+
+    const { leaf_count, node_word_offset, leaf_nodes_offset } = target;
+
+    const origin = inverse_transform_point(
+        mesh.transform_global.matrix,
+        [...camera.transform.position]
+    );
+
+    const t_bytes = leaf_count * Float32Array.BYTES_PER_ELEMENT;
+
+    const out_t = device.createBuffer({
+        label: 'reachability/t',
+        size: t_bytes,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+    });
+
+    const out_triangle = device.createBuffer({
+        label: 'reachability/triangle',
+        size: t_bytes,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+    });
+
+    const out_expected_t = device.createBuffer({
+        label: 'reachability/expected t',
+        size: t_bytes,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+    });
+
+    const cmd = ShadeGPUCommandContext.create(graphics, 'audit/reachability');
+
+    shader_blas_audit_visibility.dispatchThreads({
+        encoder: cmd,
+        thread_count_x: leaf_count,
+        bindings: {
+            settings: cmd.allocateTransientValueBuffer(BLAS_VISIBILITY_SETTINGS_STRUCT, {
+                origin,
+                leaf_count,
+                node_word_offset,
+                leaf_nodes_offset,
+                geometry_index,
+                tmax: 1e12,
+            }),
+            leaf_nodes: blas.buffer_leaf_nodes,
+            blas_lookup: blas.buffer_metadata,
+            blas_data: blas.buffer_data,
+            geometries: geometries.buffer_metadata,
+            meshlet_metadata: meshlets.buffer_metadata,
+            meshlet_data: meshlets.buffer_data,
+            nodes: blas.buffer_data,
+            out_t,
+            out_triangle,
+            out_expected_t,
+        },
+    });
+
+    cmd.finish();
+
+    await device.queue.onSubmittedWorkDone();
+
+    const t = new Float32Array(await read_back(device, out_t, t_bytes));
+    const expected = new Float32Array(await read_back(device, out_expected_t, t_bytes));
+
+    out_t.destroy();
+    out_triangle.destroy();
+    out_expected_t.destroy();
+
+    let missed = 0;
+    let overshot = 0;
+    let worst_overshoot = 0;
+
+    for (let i = 0; i < leaf_count; i++) {
+        if (!(t[i] >= 0)) {
+            missed += 1;
+
+            continue;
+        }
+
+        // 1e-3 of the aimed distance, which is far above float error on these magnitudes and far
+        // below the gap between one surface and the next
+        const overshoot = (t[i] - expected[i]) / Math.max(1e-9, expected[i]);
+
+        if (overshoot > 1e-3) {
+            overshot += 1;
+
+            worst_overshoot = Math.max(worst_overshoot, overshoot);
+        }
+    }
+
+    const lost = missed + overshot;
+
+    const result = {
+        leaf_count,
+        missed,
+        overshot,
+        worst_overshoot: +worst_overshoot.toFixed(4),
+        lost,
+        lost_pct: +(lost / leaf_count * 100).toFixed(3),
+        origin: origin.map(v => +v.toFixed(3)),
+        verdict: lost === 0
+            ? `pass — the traversal returns a surface at or before every one of ${leaf_count} `
+            + `triangles it was aimed at`
+            : `FAIL — ${lost} of ${leaf_count} (${(lost / leaf_count * 100).toFixed(2)}%) rays aimed `
+            + `at a triangle came back with nothing (${missed}) or with something behind it `
+            + `(${overshot}). Neither is geometrically possible, so the traversal is walking past `
+            + `surfaces it was pointed at — which is the hole in the traced image.`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}

package/src/shade/renderer/STATIC_GRAPHICS_ENGINE_ASSETS.js

@@ -23,7 +23,7 @@ export class StaticGraphicsEngineAssets {
         // Spatio-Temporal Blue Noise (NVIDIA 2020-ish)
 
         // vendored alongside the engine rather than at the repo root, so `src/shade` stays one
-        // directory that can be diffed against upstream (MEEP3 §4.1)
+        // directory that can be diffed against upstream (../../../SHADE_ORIGIN.md)
         const asset_url = (name) => new URL(`../assets/textures/${name}`, import.meta.url).href;
 
         const [

package/src/shade/renderer/animation/pose/PosePlayback.d.ts

@@ -5,7 +5,8 @@
  * Gameplay poses — a socket, an effect anchor, the muzzle a projectile leaves from — are a **pure
  * function of (clip set, time, weights)**, evaluated on demand at query time. They are never read
  * back from the GPU: readback is asynchronous and a frame late, which would make a projectile's
- * origin depend on frame pacing and poison determinism and replay (`EXECUTION.md` I-4).
+ * origin depend on frame pacing and poison determinism and replay — no GPU readback on a
+ * gameplay-affecting path.
  */
 export class PosePlayback {
     /**

package/src/shade/renderer/animation/pose/PosePlayback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PosePlayback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/pose/PosePlayback.js"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH;IAwBI;;;;;OAKG;IACH,4CAJW,MAAM,UACN,MAAM,GACJ,YAAY,CAcxB;IAzCD;;OAEG;IACH,yBAAY;IAEZ;;;;OAIG;IACH,MAFU,MAAM,CAEP;IAET;;;;;;;;OAQG;IACH,QAFU,MAAM,CAEL;CAqBd"}
+{"version":3,"file":"PosePlayback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/pose/PosePlayback.js"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH;IAwBI;;;;;OAKG;IACH,4CAJW,MAAM,UACN,MAAM,GACJ,YAAY,CAcxB;IAzCD;;OAEG;IACH,yBAAY;IAEZ;;;;OAIG;IACH,MAFU,MAAM,CAEP;IAET;;;;;;;;OAQG;IACH,QAFU,MAAM,CAEL;CAqBd"}

package/src/shade/renderer/animation/pose/PosePlayback.js

@@ -7,7 +7,8 @@ import { assert } from "../../../../core/assert.js";
  * Gameplay poses — a socket, an effect anchor, the muzzle a projectile leaves from — are a **pure
  * function of (clip set, time, weights)**, evaluated on demand at query time. They are never read
  * back from the GPU: readback is asynchronous and a frame late, which would make a projectile's
- * origin depend on frame pacing and poison determinism and replay (`EXECUTION.md` I-4).
+ * origin depend on frame pacing and poison determinism and replay — no GPU readback on a
+ * gameplay-affecting path.
  */
 export class PosePlayback {
     /**

package/src/shade/renderer/animation/shader_animation_apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_animation_apply.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/shader_animation_apply.js"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,gCAAiC;AAoFjC;;;;;;;;;;;;;;;;;;GAkBG;AACH,mDAKG;8BA3H2B,4BAA4B"}
+{"version":3,"file":"shader_animation_apply.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/shader_animation_apply.js"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,gCAAiC;AAoFjC;;;;;;;;;;;;;;;;;;GAkBG;AACH,mDAIG;8BA1H2B,4BAA4B"}