@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -1,270 +1,267 @@
-import { Name } from "../../../engine/ecs/name/Name.js";
-import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
-import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
-import { ShadedGeometryFlags } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
-import { GEOMETRY_METADATA_STRUCT } from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
-import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
-import { align_4 } from "../../../core/binary/align_4.js";
-
-/**
- * Does every instance's published world box actually contain its geometry?
- *
- * This is upstream of the tree and cheap to get wrong, and getting it wrong looks exactly like a
- * broken BVH. `chunk_ray_query_nearest` tests the TLAS leaf's world AABB *before* it transforms the
- * ray and enters the BLAS:
- *
- * ```wgsl
- * if(!aabb3_intersects_ray(node.bounds, ...)){ ...; continue; }
- * ```
- *
- * So a leaf box smaller than the geometry it stands for is a hard clip. Rays that would have hit
- * the parts sticking out never get to ask the BLAS about them, and those parts are simply absent
- * from the traced image while the rasterizer — which consults no such box — draws them. The pieces
- * that go missing are the outlying ones, which is the tell: a compact core survives and the
- * extremities do not.
- *
- * The rasterizer cannot detect this and neither can any amount of checking the tree, because the
- * tree is fine. Only the composition is wrong.
- *
- * The check is exact rather than statistical: eight corners of the geometry's own bounding box,
- * through the node matrix the shader uses, against the box the shader tests. No sampling, no
- * thresholds, no images.
- */
-
-/**
- * Read a range of a GPU buffer back to the CPU.
- *
- * @param {GPUDevice} device
- * @param {GPUBuffer} buffer must carry `COPY_SRC`
- * @param {number} offset bytes
- * @param {number} size bytes
- * @returns {Promise<ArrayBuffer>}
- */
-async function read_back(device, buffer, offset, size) {
-    const aligned_offset = Math.floor(offset / 4) * 4;
-    const slack = offset - aligned_offset;
-    const aligned_size = align_4(size + slack);
-
-    const staging = device.createBuffer({
-        label: 'verify/bounds readback',
-        size: aligned_size,
-        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
-    });
-
-    const encoder = device.createCommandEncoder({ label: 'verify/bounds readback' });
-
-    encoder.copyBufferToBuffer(buffer, aligned_offset, staging, 0, aligned_size);
-
-    device.queue.submit([encoder.finish()]);
-
-    await staging.mapAsync(GPUMapMode.READ);
-
-    const copy = staging.getMappedRange().slice(slack, slack + size);
-
-    staging.unmap();
-    staging.destroy();
-
-    return copy;
-}
-
-/**
- * Apply a column-major 4x4 to a point.
- *
- * @param {ArrayLike<number>} m
- * @param {number} x
- * @param {number} y
- * @param {number} z
- * @returns {number[]}
- */
-function transform_point(m, x, y, z) {
-    const w = m[3] * x + m[7] * y + m[11] * z + m[15];
-
-    const inverse_w = w === 0 ? 1 : 1 / w;
-
-    return [
-        (m[0] * x + m[4] * y + m[8] * z + m[12]) * inverse_w,
-        (m[1] * x + m[5] * y + m[9] * z + m[13]) * inverse_w,
-        (m[2] * x + m[6] * y + m[10] * z + m[14]) * inverse_w,
-    ];
-}
-
-/**
- * The AABB of a box's eight corners under a transform.
- *
- * Eight corners rather than two: any rotation in the matrix makes a componentwise transform of the
- * min and max meaningless, which is the trap that makes this worth writing down. Michelle's root
- * carries the file's axis conversion, so her boxes are rotated and a two-corner comparison reports
- * violations that are not there and misses ones that are.
- *
- * @param {ArrayLike<number>} box `[min.xyz, max.xyz]`
- * @param {ArrayLike<number>} matrix column-major 4x4
- * @returns {number[]} `[min.xyz, max.xyz]`
- */
-export function transformed_box(box, matrix) {
-    const low = [Infinity, Infinity, Infinity];
-    const high = [-Infinity, -Infinity, -Infinity];
-
-    for (let corner = 0; corner < 8; corner++) {
-        const point = transform_point(
-            matrix,
-            box[(corner & 1) ? 3 : 0],
-            box[(corner & 2) ? 4 : 1],
-            box[(corner & 4) ? 5 : 2]
-        );
-
-        for (let axis = 0; axis < 3; axis++) {
-            low[axis] = Math.min(low[axis], point[axis]);
-            high[axis] = Math.max(high[axis], point[axis]);
-        }
-    }
-
-    return [...low, ...high];
-}
-
-/**
- * How far `inner` pokes out of `outer`, per axis, as a fraction of `inner`'s own size.
- *
- * Relative so the answer means the same thing whatever the asset's units are, and signed per side
- * so the report says which way it escaped.
- *
- * @param {number[]} inner
- * @param {number[]} outer
- * @returns {{worst: number, sides: object[]}}
- */
-function containment_error(inner, outer) {
-    const sides = [];
-
-    let worst = 0;
-
-    for (let axis = 0; axis < 3; axis++) {
-        const span = Math.max(1e-9, inner[axis + 3] - inner[axis]);
-
-        const below = (outer[axis] - inner[axis]) / span;
-        const above = (inner[axis + 3] - outer[axis + 3]) / span;
-
-        if (below > 0) {
-            sides.push({ axis, side: 'min', escapes_by: +below.toFixed(4) });
-
-            worst = Math.max(worst, below);
-        }
-
-        if (above > 0) {
-            sides.push({ axis, side: 'max', escapes_by: +above.toFixed(4) });
-
-            worst = Math.max(worst, above);
-        }
-    }
-
-    return { worst, sides };
-}
-
-/**
- * Check every mesh in the scene.
- *
- * @param {object} options
- * @param {Renderer} options.renderer
- * @param {Scene} options.scene
- * @param {PerspectiveCamera} [options.camera] rendered a few times first, so the bounds-refresh
- * chain has published something to check
- * @param {number} [options.tolerance] fraction of an instance's own size it may escape by
- * @returns {Promise<object>}
- */
-export async function verify_instance_bounds({ renderer, scene, camera, tolerance = 1e-3 }) {
-    const graphics = renderer.graphics;
-    const device = graphics.device;
-
-    const scene_context = renderer.scenes.obtain(scene);
-
-    const geometries = graphics.geometries;
-
-    if (camera !== undefined) {
-        for (let i = 0; i < 8; i++) {
-            renderer.render(camera, scene, 0);
-
-            await device.queue.onSubmittedWorkDone();
-        }
-    }
-
-    const stride = GEOMETRY_METADATA_STRUCT.aligned_size;
-
-    const box_offset = GEOMETRY_METADATA_STRUCT.fields.find(f => f.name === 'bounding_box').offset;
-
-    /**
-     * Every mesh row in the scene, with the matrix the GPU composes it under: the entities that
-     * draw — a character's primitives, and the floor.
-     *
-     * @type {{name: string, skinned: boolean, row: number, world: ArrayLike<number>}[]}
-     */
-    const instances = [];
-
-    const dataset = scene.dataset;
-
-    if (dataset !== null && dataset !== undefined) {
-        dataset.traverseComponents(ShadedGeometry, (geometry, entity) => {
-            if (!scene_context.rows.has_mesh(entity)) {
-                return;
-            }
-
-            const name = dataset.getComponent(entity, Name);
-
-            instances.push({
-                name: name === undefined ? `entity ${entity}` : name.getValue(),
-                skinned: geometry.getFlag(ShadedGeometryFlags.Skinned),
-                row: row_of_entity(entity),
-                world: dataset.getComponent(entity, Transform64).matrix,
-            });
-        });
-    }
-
-
-    const rows = [];
-
-    for (const instance of instances) {
-        const row = instance.row;
-
-        const record = await scene_context.scene_database.debug_table_read_element('meshes', row);
-
-        const geometry_index = record.geometry;
-
-        const geometry_box = [...new Float32Array(await read_back(
-            device,
-            geometries.buffer_metadata,
-            geometry_index * stride + box_offset,
-            24
-        ))];
-
-        // the same matrix `chunk_ray_query_nearest` inverts to put the ray in geometry space
-        const world_box = transformed_box(geometry_box, instance.world);
-
-        const error = containment_error(world_box, record.bounding_box);
-
-        rows.push({
-            name: instance.name,
-            skinned: instance.skinned,
-            row,
-            geometry_index,
-            geometry_box: geometry_box.map(v => +v.toFixed(3)),
-            geometry_in_world: world_box.map(v => +v.toFixed(3)),
-            published: [...record.bounding_box].map(v => +v.toFixed(3)),
-            worst_escape: +error.worst.toFixed(4),
-            escapes: error.sides,
-        });
-    }
-
-    const failures = rows.filter(entry => entry.worst_escape > tolerance);
-
-    const result = {
-        rows,
-        failures,
-        verdict: failures.length === 0
-            ? `pass — all ${rows.length} instances are contained by the box the TLAS tests them with`
-            : `FAIL — ${failures.length} of ${rows.length} instances stick out of their own TLAS box, `
-            + `worst by ${(Math.max(...failures.map(f => f.worst_escape)) * 100).toFixed(1)}% of its `
-            + `size. Rays are being clipped before they reach the BLAS, and the traced image loses `
-            + `whatever sticks out.`,
-    };
-
-    console.log(result.verdict, result);
-
-    return result;
-}
+import { Name } from "../../../engine/ecs/name/Name.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
+import { GEOMETRY_METADATA_STRUCT } from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
+import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
+import { align_4 } from "../../../core/binary/align_4.js";
+import { render_submitted_frames } from "../render_submitted_frames.js";
+
+/**
+ * Does every instance's published world box actually contain its geometry?
+ *
+ * This is upstream of the tree and cheap to get wrong, and getting it wrong looks exactly like a
+ * broken BVH. `chunk_ray_query_nearest` tests the TLAS leaf's world AABB *before* it transforms the
+ * ray and enters the BLAS:
+ *
+ * ```wgsl
+ * if(!aabb3_intersects_ray(node.bounds, ...)){ ...; continue; }
+ * ```
+ *
+ * So a leaf box smaller than the geometry it stands for is a hard clip. Rays that would have hit
+ * the parts sticking out never get to ask the BLAS about them, and those parts are simply absent
+ * from the traced image while the rasterizer — which consults no such box — draws them. The pieces
+ * that go missing are the outlying ones, which is the tell: a compact core survives and the
+ * extremities do not.
+ *
+ * The rasterizer cannot detect this and neither can any amount of checking the tree, because the
+ * tree is fine. Only the composition is wrong.
+ *
+ * The check is exact rather than statistical: eight corners of the geometry's own bounding box,
+ * through the node matrix the shader uses, against the box the shader tests. No sampling, no
+ * thresholds, no images.
+ */
+
+/**
+ * Read a range of a GPU buffer back to the CPU.
+ *
+ * @param {GPUDevice} device
+ * @param {GPUBuffer} buffer must carry `COPY_SRC`
+ * @param {number} offset bytes
+ * @param {number} size bytes
+ * @returns {Promise<ArrayBuffer>}
+ */
+async function read_back(device, buffer, offset, size) {
+    const aligned_offset = Math.floor(offset / 4) * 4;
+    const slack = offset - aligned_offset;
+    const aligned_size = align_4(size + slack);
+
+    const staging = device.createBuffer({
+        label: 'verify/bounds readback',
+        size: aligned_size,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+
+    const encoder = device.createCommandEncoder({ label: 'verify/bounds readback' });
+
+    encoder.copyBufferToBuffer(buffer, aligned_offset, staging, 0, aligned_size);
+
+    device.queue.submit([encoder.finish()]);
+
+    await staging.mapAsync(GPUMapMode.READ);
+
+    const copy = staging.getMappedRange().slice(slack, slack + size);
+
+    staging.unmap();
+    staging.destroy();
+
+    return copy;
+}
+
+/**
+ * Apply a column-major 4x4 to a point.
+ *
+ * @param {ArrayLike<number>} m
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number[]}
+ */
+function transform_point(m, x, y, z) {
+    const w = m[3] * x + m[7] * y + m[11] * z + m[15];
+
+    const inverse_w = w === 0 ? 1 : 1 / w;
+
+    return [
+        (m[0] * x + m[4] * y + m[8] * z + m[12]) * inverse_w,
+        (m[1] * x + m[5] * y + m[9] * z + m[13]) * inverse_w,
+        (m[2] * x + m[6] * y + m[10] * z + m[14]) * inverse_w,
+    ];
+}
+
+/**
+ * The AABB of a box's eight corners under a transform.
+ *
+ * Eight corners rather than two: any rotation in the matrix makes a componentwise transform of the
+ * min and max meaningless, which is the trap that makes this worth writing down. Michelle's root
+ * carries the file's axis conversion, so her boxes are rotated and a two-corner comparison reports
+ * violations that are not there and misses ones that are.
+ *
+ * @param {ArrayLike<number>} box `[min.xyz, max.xyz]`
+ * @param {ArrayLike<number>} matrix column-major 4x4
+ * @returns {number[]} `[min.xyz, max.xyz]`
+ */
+export function transformed_box(box, matrix) {
+    const low = [Infinity, Infinity, Infinity];
+    const high = [-Infinity, -Infinity, -Infinity];
+
+    for (let corner = 0; corner < 8; corner++) {
+        const point = transform_point(
+            matrix,
+            box[(corner & 1) ? 3 : 0],
+            box[(corner & 2) ? 4 : 1],
+            box[(corner & 4) ? 5 : 2]
+        );
+
+        for (let axis = 0; axis < 3; axis++) {
+            low[axis] = Math.min(low[axis], point[axis]);
+            high[axis] = Math.max(high[axis], point[axis]);
+        }
+    }
+
+    return [...low, ...high];
+}
+
+/**
+ * How far `inner` pokes out of `outer`, per axis, as a fraction of `inner`'s own size.
+ *
+ * Relative so the answer means the same thing whatever the asset's units are, and signed per side
+ * so the report says which way it escaped.
+ *
+ * @param {number[]} inner
+ * @param {number[]} outer
+ * @returns {{worst: number, sides: object[]}}
+ */
+function containment_error(inner, outer) {
+    const sides = [];
+
+    let worst = 0;
+
+    for (let axis = 0; axis < 3; axis++) {
+        const span = Math.max(1e-9, inner[axis + 3] - inner[axis]);
+
+        const below = (outer[axis] - inner[axis]) / span;
+        const above = (inner[axis + 3] - outer[axis + 3]) / span;
+
+        if (below > 0) {
+            sides.push({ axis, side: 'min', escapes_by: +below.toFixed(4) });
+
+            worst = Math.max(worst, below);
+        }
+
+        if (above > 0) {
+            sides.push({ axis, side: 'max', escapes_by: +above.toFixed(4) });
+
+            worst = Math.max(worst, above);
+        }
+    }
+
+    return { worst, sides };
+}
+
+/**
+ * Check every mesh in the scene.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {Scene} options.scene
+ * @param {PerspectiveCamera} [options.camera] rendered a few times first, so the bounds-refresh
+ * chain has published something to check
+ * @param {number} [options.tolerance] fraction of an instance's own size it may escape by
+ * @returns {Promise<object>}
+ */
+export async function verify_instance_bounds({ renderer, scene, camera, tolerance = 1e-3 }) {
+    const graphics = renderer.graphics;
+    const device = graphics.device;
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    const geometries = graphics.geometries;
+
+    if (camera !== undefined) {
+        await render_submitted_frames(renderer, camera, scene, 8, 0);
+    }
+
+    const stride = GEOMETRY_METADATA_STRUCT.aligned_size;
+
+    const box_offset = GEOMETRY_METADATA_STRUCT.fields.find(f => f.name === 'bounding_box').offset;
+
+    /**
+     * Every mesh row in the scene, with the matrix the GPU composes it under: the entities that
+     * draw — a character's primitives, and the floor.
+     *
+     * @type {{name: string, skinned: boolean, row: number, world: ArrayLike<number>}[]}
+     */
+    const instances = [];
+
+    const dataset = scene.dataset;
+
+    if (dataset !== null && dataset !== undefined) {
+        dataset.traverseComponents(ShadedGeometry, (geometry, entity) => {
+            if (!scene_context.rows.has_mesh(entity)) {
+                return;
+            }
+
+            const name = dataset.getComponent(entity, Name);
+
+            instances.push({
+                name: name === undefined ? `entity ${entity}` : name.getValue(),
+                skinned: geometry.getFlag(ShadedGeometryFlags.Skinned),
+                row: row_of_entity(entity),
+                world: dataset.getComponent(entity, Transform64).matrix,
+            });
+        });
+    }
+
+
+    const rows = [];
+
+    for (const instance of instances) {
+        const row = instance.row;
+
+        const record = await scene_context.scene_database.debug_table_read_element('meshes', row);
+
+        const geometry_index = record.geometry;
+
+        const geometry_box = [...new Float32Array(await read_back(
+            device,
+            geometries.buffer_metadata,
+            geometry_index * stride + box_offset,
+            24
+        ))];
+
+        // the same matrix `chunk_ray_query_nearest` inverts to put the ray in geometry space
+        const world_box = transformed_box(geometry_box, instance.world);
+
+        const error = containment_error(world_box, record.bounding_box);
+
+        rows.push({
+            name: instance.name,
+            skinned: instance.skinned,
+            row,
+            geometry_index,
+            geometry_box: geometry_box.map(v => +v.toFixed(3)),
+            geometry_in_world: world_box.map(v => +v.toFixed(3)),
+            published: [...record.bounding_box].map(v => +v.toFixed(3)),
+            worst_escape: +error.worst.toFixed(4),
+            escapes: error.sides,
+        });
+    }
+
+    const failures = rows.filter(entry => entry.worst_escape > tolerance);
+
+    const result = {
+        rows,
+        failures,
+        verdict: failures.length === 0
+            ? `pass — all ${rows.length} instances are contained by the box the TLAS tests them with`
+            : `FAIL — ${failures.length} of ${rows.length} instances stick out of their own TLAS box, `
+            + `worst by ${(Math.max(...failures.map(f => f.worst_escape)) * 100).toFixed(1)}% of its `
+            + `size. Rays are being clipped before they reach the BLAS, and the traced image loses `
+            + `whatever sticks out.`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}

package/src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify_skinned_blas_refit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js"],"names":[],"mappings":"AA6JA;;;;;;;;;;;;;;;GAeG;AACH;IAP6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACJ,MAAM,EAAtB,MAAM;IACW,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAoF3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAJ6B,QAAQ;IACD,QAAQ;IAC/B,QAAQ,MAAM,CAAC,CA8F3B"}
+{"version":3,"file":"verify_skinned_blas_refit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js"],"names":[],"mappings":"AA0JA;;;;;;;;;;;;;;;GAeG;AACH;IAP6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACJ,MAAM,EAAtB,MAAM;IACW,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAoF3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAJ6B,QAAQ;IACD,QAAQ;IAC/B,QAAQ,MAAM,CAAC,CA8F3B"}

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

@@ -10,6 +10,7 @@ import { bvh2_check_containment } from "../../renderer/geometry/bvh/bvh2_check_b
 import { GPUBLASRefitBatch } from "../../renderer/geometry/bvh/GPUBLASRefitBatch.js";
 import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { render_submitted_frames } from "../render_submitted_frames.js";
 import { geometry_of } from "./place_character.js";
 
 /**
@@ -144,15 +145,11 @@ function box_disagreement(a, b) {
  * @param {Renderer} renderer
  * @param {PerspectiveCamera} camera
  * @param {Scene} scene
- * @param {number} frames
+ * @param {number} frames submitted frames
  * @param {number} [dt] seconds per frame
  */
 async function advance(renderer, camera, scene, frames, dt = 1 / 60) {
-    for (let i = 0; i < frames; i++) {
-        renderer.render(camera, scene, dt);
-
-        await renderer.graphics.device.queue.onSubmittedWorkDone();
-    }
+    await render_submitted_frames(renderer, camera, scene, frames, dt);
 }
 
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_mesh_soup/main.js"],"names":[],"mappings":"AA+LA;;;;GAIG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAmTzB"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_mesh_soup/main.js"],"names":[],"mappings":"AAgMA;;;;GAIG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAiTzB"}

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

@@ -24,6 +24,7 @@ import { Renderer } from "../../renderer/Renderer.js";
 import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
 import { Scene } from "../../renderer/scene/Scene.js";
 import { load_default_environment } from "../load_default_environment.js";
+import { render_submitted_frames } from "../render_submitted_frames.js";
 import { grid_position, place_character } from "../skinned_blas_refit/place_character.js";
 
 /**
@@ -372,13 +373,11 @@ export async function start() {
 
     // ---- frames enough for the box to be worth framing on ----------------------------------------
 
+    // Submitted frames, not calls: the first several calls are refused while the renderer's prepared
+    // pipelines compile, and a refused frame publishes no box.
     set_status('first frames — uploading clones and their trees …');
 
-    for (let i = 0; i < 8; i++) {
-        renderer.render(camera, scene, 1 / 60);
-
-        await renderer.graphics.device.queue.onSubmittedWorkDone();
-    }
+    await render_submitted_frames(renderer, camera, scene, 8);
 
     let low = null;
     let high = null;