@woosh/meep-engine 3.11.3 → 3.12.0

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

@@ -1,202 +1,202 @@
-import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
-import {
-    BVH_NODE_BOUNDS_WORD,
-    BVH_NODE_STRIDE_WORDS
-} from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
-import {
-    BLAS_LEAF_BOUNDS_SETTINGS_STRUCT
-} from "../../renderer/geometry/bvh/shader_blas_refit_leaf_bounds.js";
-import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
-import { shader_blas_audit_leaf_triangles } from "./shader_blas_audit_leaf_triangles.js";
-
-/**
- * Does every leaf's box actually contain the triangle a ray will test inside it?
- *
- * This is the seam nothing else covers. The refit fills a leaf's box using
- * `geometry_read_triangle_bounds`; `ray_query_blas_nearest` fetches the triangle it tests using
- * `geometry_read_triangle_vertices`. Two functions, one encoded payload, and every check so far has
- * only ever exercised the first — the structural tests confirm the tree is a consistent tree, and a
- * tree consistently bounding the *wrong* triangles is consistent.
- *
- * When they disagree the failure is silent and view-dependent: a ray descends into a box, tests a
- * triangle that is elsewhere, misses, and a whole meshlet is absent from the traced image while the
- * rasterizer — which never consults the tree — draws it.
- *
- * So this runs the intersector's reader over every leaf on the live asset and holds its answer
- * against the box the tree carries. Containment, not equality: a leaf's box is allowed to be
- * larger than its triangle, and under deformation it will be, because the refit and this audit can
- * run a frame apart. It is not allowed to be somewhere else.
- */
-
-/**
- * @param {GPUDevice} device
- * @param {GPUBuffer} buffer
- * @param {number} offset
- * @param {number} size
- * @returns {Promise<ArrayBuffer>}
- */
-async function read_back(device, buffer, offset, size) {
-    const staging = device.createBuffer({
-        label: 'audit/readback',
-        size,
-        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
-    });
-
-    const encoder = device.createCommandEncoder({ label: 'audit/readback' });
-
-    encoder.copyBufferToBuffer(buffer, offset, 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;
-}
-
-/**
- * @param {object} options
- * @param {Renderer} options.renderer
- * @param {object} [options.owner] the identity the tree is registered under
- * @param {object} [options.target] an explicit refit target, for a tree whose owner handle is not
- * reachable — a skinned clone's metadata row lives inside the skinning context. Every copy of a
- * geometry shares one topology, so a clone's target is the source's with its own `node_word_offset`
- * substituted, and that is composable from the published lookup alone.
- * @param {number} options.geometry_index the row whose vertices the leaves index into
- * @param {number} [options.tolerance] fraction of a leaf's own size a vertex may sit outside by
- * @returns {Promise<object>}
- */
-export async function verify_leaf_triangles({
-                                                renderer,
-                                                owner,
-                                                target: explicit_target,
-                                                geometry_index,
-                                                tolerance = 1e-3,
-                                            }) {
-    const graphics = renderer.graphics;
-    const device = graphics.device;
-
-    const geometries = graphics.geometries;
-    const blas = geometries.blas;
-    const meshlets = geometries.meshlets;
-
-    const target = explicit_target ?? blas.get_refit_target(owner);
-
-    if (target === undefined) {
-        throw new Error('that owner has no resident tree');
-    }
-
-    const { leaf_count, node_word_offset, leaf_nodes_offset } = target;
-
-    const out_bytes = leaf_count * 6 * Float32Array.BYTES_PER_ELEMENT;
-
-    const out_bounds = device.createBuffer({
-        label: 'audit/leaf triangles',
-        size: out_bytes,
-        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
-    });
-
-    const cmd = ShadeGPUCommandContext.create(graphics, 'audit/leaf triangles');
-
-    shader_blas_audit_leaf_triangles.dispatchLinear({
-        encoder: cmd,
-        element_count: leaf_count,
-        bindings: {
-            settings: cmd.allocateTransientValueBuffer(BLAS_LEAF_BOUNDS_SETTINGS_STRUCT, {
-                leaf_count,
-                node_word_offset,
-                leaf_nodes_offset,
-                geometry_index,
-            }),
-            leaf_nodes: blas.buffer_leaf_nodes,
-            geometries: geometries.buffer_metadata,
-            meshlet_metadata: meshlets.buffer_metadata,
-            meshlet_data: meshlets.buffer_data,
-            nodes: blas.buffer_data,
-            out_bounds,
-        },
-    });
-
-    cmd.finish();
-
-    await device.queue.onSubmittedWorkDone();
-
-    const intersector = new Float32Array(await read_back(device, out_bounds, 0, out_bytes));
-
-    const leaves = new Uint32Array(await read_back(
-        device,
-        blas.buffer_leaf_nodes,
-        leaf_nodes_offset * Uint32Array.BYTES_PER_ELEMENT,
-        leaf_count * Uint32Array.BYTES_PER_ELEMENT
-    ));
-
-    const node_bytes = Math.max(...leaves) * BVH2_NODE_STRUCT.size + BVH2_NODE_STRUCT.size;
-
-    const nodes = new Float32Array(await read_back(
-        device,
-        blas.buffer_data,
-        node_word_offset * Uint32Array.BYTES_PER_ELEMENT,
-        node_bytes
-    ));
-
-    out_bounds.destroy();
-
-    let escaped = 0;
-    let worst = 0;
-
-    const examples = [];
-
-    for (let i = 0; i < leaf_count; i++) {
-        const base = leaves[i] * BVH_NODE_STRIDE_WORDS + BVH_NODE_BOUNDS_WORD;
-
-        const source = i * 6;
-
-        let error = 0;
-
-        for (let axis = 0; axis < 3; axis++) {
-            const span = Math.max(1e-9, nodes[base + axis + 3] - nodes[base + axis]);
-
-            error = Math.max(
-                error,
-                (nodes[base + axis] - intersector[source + axis]) / span,
-                (intersector[source + axis + 3] - nodes[base + axis + 3]) / span
-            );
-        }
-
-        if (error > tolerance) {
-            escaped += 1;
-
-            if (examples.length < 5) {
-                examples.push({
-                    leaf: i,
-                    node: leaves[i],
-                    tree_box: [0, 1, 2, 3, 4, 5].map(k => +nodes[base + k].toFixed(3)),
-                    intersector_box: [0, 1, 2, 3, 4, 5].map(k => +intersector[source + k].toFixed(3)),
-                    escapes_by: +error.toFixed(4),
-                });
-            }
-        }
-
-        worst = Math.max(worst, error);
-    }
-
-    const result = {
-        leaf_count,
-        escaped,
-        worst: +worst.toFixed(5),
-        examples,
-        verdict: escaped === 0
-            ? `pass — all ${leaf_count} leaves bound the triangle the intersector fetches for them`
-            : `FAIL — ${escaped} of ${leaf_count} leaves bound a different triangle than the `
-            + `intersector tests, worst by ${(worst * 100).toFixed(1)}% of the leaf's own size. `
-            + `Rays descend into those boxes, test a triangle that is elsewhere, and miss.`,
-    };
-
-    console.log(result.verdict, result);
-
-    return result;
-}
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import {
+    BVH_NODE_BOUNDS_WORD,
+    BVH_NODE_STRIDE_WORDS
+} from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+import {
+    BLAS_LEAF_BOUNDS_SETTINGS_STRUCT
+} from "../../renderer/geometry/bvh/shader_blas_refit_leaf_bounds.js";
+import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
+import { shader_blas_audit_leaf_triangles } from "./shader_blas_audit_leaf_triangles.js";
+
+/**
+ * Does every leaf's box actually contain the triangle a ray will test inside it?
+ *
+ * This is the seam nothing else covers. The refit fills a leaf's box using
+ * `geometry_read_triangle_bounds`; `ray_query_blas_nearest` fetches the triangle it tests using
+ * `geometry_read_triangle_vertices`. Two functions, one encoded payload, and every check so far has
+ * only ever exercised the first — the structural tests confirm the tree is a consistent tree, and a
+ * tree consistently bounding the *wrong* triangles is consistent.
+ *
+ * When they disagree the failure is silent and view-dependent: a ray descends into a box, tests a
+ * triangle that is elsewhere, misses, and a whole meshlet is absent from the traced image while the
+ * rasterizer — which never consults the tree — draws it.
+ *
+ * So this runs the intersector's reader over every leaf on the live asset and holds its answer
+ * against the box the tree carries. Containment, not equality: a leaf's box is allowed to be
+ * larger than its triangle, and under deformation it will be, because the refit and this audit can
+ * run a frame apart. It is not allowed to be somewhere else.
+ */
+
+/**
+ * @param {GPUDevice} device
+ * @param {GPUBuffer} buffer
+ * @param {number} offset
+ * @param {number} size
+ * @returns {Promise<ArrayBuffer>}
+ */
+async function read_back(device, buffer, offset, size) {
+    const staging = device.createBuffer({
+        label: 'audit/readback',
+        size,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+
+    const encoder = device.createCommandEncoder({ label: 'audit/readback' });
+
+    encoder.copyBufferToBuffer(buffer, offset, 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;
+}
+
+/**
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {object} [options.owner] the identity the tree is registered under
+ * @param {object} [options.target] an explicit refit target, for a tree whose owner handle is not
+ * reachable — a skinned clone's metadata row lives inside the skinning context. Every copy of a
+ * geometry shares one topology, so a clone's target is the source's with its own `node_word_offset`
+ * substituted, and that is composable from the published lookup alone.
+ * @param {number} options.geometry_index the row whose vertices the leaves index into
+ * @param {number} [options.tolerance] fraction of a leaf's own size a vertex may sit outside by
+ * @returns {Promise<object>}
+ */
+export async function verify_leaf_triangles({
+                                                renderer,
+                                                owner,
+                                                target: explicit_target,
+                                                geometry_index,
+                                                tolerance = 1e-3,
+                                            }) {
+    const graphics = renderer.graphics;
+    const device = graphics.device;
+
+    const geometries = graphics.geometries;
+    const blas = geometries.blas;
+    const meshlets = geometries.meshlets;
+
+    const target = explicit_target ?? blas.get_refit_target(owner);
+
+    if (target === undefined) {
+        throw new Error('that owner has no resident tree');
+    }
+
+    const { leaf_count, node_word_offset, leaf_nodes_offset } = target;
+
+    const out_bytes = leaf_count * 6 * Float32Array.BYTES_PER_ELEMENT;
+
+    const out_bounds = device.createBuffer({
+        label: 'audit/leaf triangles',
+        size: out_bytes,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+    });
+
+    const cmd = ShadeGPUCommandContext.create(graphics, 'audit/leaf triangles');
+
+    shader_blas_audit_leaf_triangles.dispatchThreads({
+        encoder: cmd,
+        thread_count_x: leaf_count,
+        bindings: {
+            settings: cmd.allocateTransientValueBuffer(BLAS_LEAF_BOUNDS_SETTINGS_STRUCT, {
+                leaf_count,
+                node_word_offset,
+                leaf_nodes_offset,
+                geometry_index,
+            }),
+            leaf_nodes: blas.buffer_leaf_nodes,
+            geometries: geometries.buffer_metadata,
+            meshlet_metadata: meshlets.buffer_metadata,
+            meshlet_data: meshlets.buffer_data,
+            nodes: blas.buffer_data,
+            out_bounds,
+        },
+    });
+
+    cmd.finish();
+
+    await device.queue.onSubmittedWorkDone();
+
+    const intersector = new Float32Array(await read_back(device, out_bounds, 0, out_bytes));
+
+    const leaves = new Uint32Array(await read_back(
+        device,
+        blas.buffer_leaf_nodes,
+        leaf_nodes_offset * Uint32Array.BYTES_PER_ELEMENT,
+        leaf_count * Uint32Array.BYTES_PER_ELEMENT
+    ));
+
+    const node_bytes = Math.max(...leaves) * BVH2_NODE_STRUCT.size + BVH2_NODE_STRUCT.size;
+
+    const nodes = new Float32Array(await read_back(
+        device,
+        blas.buffer_data,
+        node_word_offset * Uint32Array.BYTES_PER_ELEMENT,
+        node_bytes
+    ));
+
+    out_bounds.destroy();
+
+    let escaped = 0;
+    let worst = 0;
+
+    const examples = [];
+
+    for (let i = 0; i < leaf_count; i++) {
+        const base = leaves[i] * BVH_NODE_STRIDE_WORDS + BVH_NODE_BOUNDS_WORD;
+
+        const source = i * 6;
+
+        let error = 0;
+
+        for (let axis = 0; axis < 3; axis++) {
+            const span = Math.max(1e-9, nodes[base + axis + 3] - nodes[base + axis]);
+
+            error = Math.max(
+                error,
+                (nodes[base + axis] - intersector[source + axis]) / span,
+                (intersector[source + axis + 3] - nodes[base + axis + 3]) / span
+            );
+        }
+
+        if (error > tolerance) {
+            escaped += 1;
+
+            if (examples.length < 5) {
+                examples.push({
+                    leaf: i,
+                    node: leaves[i],
+                    tree_box: [0, 1, 2, 3, 4, 5].map(k => +nodes[base + k].toFixed(3)),
+                    intersector_box: [0, 1, 2, 3, 4, 5].map(k => +intersector[source + k].toFixed(3)),
+                    escapes_by: +error.toFixed(4),
+                });
+            }
+        }
+
+        worst = Math.max(worst, error);
+    }
+
+    const result = {
+        leaf_count,
+        escaped,
+        worst: +worst.toFixed(5),
+        examples,
+        verdict: escaped === 0
+            ? `pass — all ${leaf_count} leaves bound the triangle the intersector fetches for them`
+            : `FAIL — ${escaped} of ${leaf_count} leaves bound a different triangle than the `
+            + `intersector tests, worst by ${(worst * 100).toFixed(1)}% of the leaf's own size. `
+            + `Rays descend into those boxes, test a triangle that is elsewhere, and miss.`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}