@woosh/meep-engine 3.69.0 → 3.70.0

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

@@ -1,202 +1,342 @@
-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 { 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: {
-                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 = [];
-    const escaped_leaves = [];
-
-    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;
-            escaped_leaves.push(i);
-
-            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,
-        escaped_leaves,
-        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 { bitCount } from "../../../core/binary/operations/bitCount.js";
+import { BVH8 } from "../../../core/bvh8/BVH8.js";
+import { bvh8_get_node_child_bounds } from "../../../core/bvh8/bvh8_get_node_child_bounds.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { BVH8_INODE_STRUCT } from "../../renderer/shader/chunk/bvh/bvh8/webgpu/BVH8_INODE_STRUCT.js";
+import {
+    BLAS_AUDIT_MESHLET_STRIDE,
+    shader_blas_audit_leaf_triangles
+} from "./shader_blas_audit_leaf_triangles.js";
+
+/**
+ * Does every leaf slot's box actually contain the triangles a ray will test inside it?
+ *
+ * This is the seam nothing else covers. The refit fills a slot's box using
+ * `geometry_read_triangle_bounds`; the ray queries fetch the triangles they test using
+ * `geometry_read_triangle_positions`. Two functions, one encoded payload — and the structural checks
+ * confirm only that the tree is a consistent tree, which a tree consistently bounding the *wrong*
+ * triangles is.
+ *
+ * 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 triangle of the live asset and holds its answer
+ * against the slot of the tree that names it. Containment, not equality: a slot's box is quantized
+ * outward, and under deformation the refit and this audit can run a frame apart. It is not allowed
+ * to be somewhere else. Every triangle has to be named by one slot, and by one only.
+ *
+ * The slots that name child nodes are held to the same triangles: a ray reaches a node only through
+ * the box its parent keeps for it, so that box has to hold every triangle under the node. Not the
+ * boxes of the node's own slots — those are rounded outward on the node's own grid, and may reach
+ * past what the parent keeps, without a ray being lost for it.
+ */
+
+/**
+ * @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 {{node_offset: number, node_count: number}} [options.target] an explicit refit target, for a
+ * tree whose owner handle is not at hand
+ * @param {number} options.geometry_index the row whose triangles the tree names
+ * @param {number} options.meshlet_count meshlets of that geometry
+ * @param {number} [options.tolerance] fraction of a slot's own size a triangle may sit outside by
+ * @returns {Promise<object>}
+ */
+export async function verify_leaf_triangles({
+                                                renderer,
+                                                owner,
+                                                target: explicit_target,
+                                                geometry_index,
+                                                meshlet_count,
+                                                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 { node_offset, node_count } = target;
+
+    const id_count = meshlet_count * BLAS_AUDIT_MESHLET_STRIDE;
+
+    const out_bytes = id_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: id_count,
+        bindings: {
+            settings: {
+                meshlet_count,
+                geometry_index,
+            },
+            geometries: geometries.buffer_metadata,
+            meshlet_metadata: meshlets.buffer_metadata,
+            meshlet_data: meshlets.buffer_data,
+            out_bounds,
+        },
+    });
+
+    cmd.finish();
+
+    await device.queue.onSubmittedWorkDone();
+
+    const intersector = new Float32Array(await read_back(device, out_bounds, 0, out_bytes));
+
+    const tree = new BVH8();
+
+    tree.nodes.fromArrayBuffer(await read_back(
+        device,
+        blas.buffer_data,
+        node_offset * BVH8_INODE_STRUCT.size,
+        node_count * BVH8_INODE_STRUCT.size
+    ), node_count);
+
+    out_bounds.destroy();
+
+    // how many slots name each triangle id
+    const named = new Uint8Array(id_count);
+
+    const slot_box = new Float32Array(6);
+
+    let triangle_count = 0;
+    let escaped = 0;
+    let worst = 0;
+
+    let child_slots = 0;
+    let child_escaped = 0;
+
+    const examples = [];
+    const escaped_nodes = new Set();
+
+    // the box of every triangle under a node, as the intersector reads them: six floats a node
+    const under = new Float32Array(node_count * 6);
+
+    for (let node = 0; node < node_count; node++) {
+        under.fill(Infinity, node * 6, node * 6 + 3);
+        under.fill(-Infinity, node * 6 + 3, node * 6 + 6);
+    }
+
+    // how far `inner`, six floats at `offset`, lies outside `slot_box`, as a fraction of the slot's own size
+    const escape_of = (inner, offset) => {
+        let error = 0;
+
+        for (let axis = 0; axis < 3; axis++) {
+            const span = Math.max(1e-9, slot_box[axis + 3] - slot_box[axis]);
+
+            error = Math.max(
+                error,
+                (slot_box[axis] - inner[offset + axis]) / span,
+                (inner[offset + axis + 3] - slot_box[axis + 3]) / span
+            );
+        }
+
+        return error;
+    };
+
+    // Last node first: a child's index is above its parent's, so by the time a slot names a child
+    // node, what is under that child is known.
+    for (let node = node_count - 1; node >= 0; node--) {
+        const imask = tree.node_get_imask(node);
+        const triangle_base = tree.node_get_base_index_triangle(node);
+        const child_base = tree.node_get_base_index_child(node);
+
+        for (let slot = 0; slot < 8; slot++) {
+            const slot_meta = tree.node_get_meta(node, slot);
+
+            if (slot_meta === 0) {
+                // empty
+                continue;
+            }
+
+            bvh8_get_node_child_bounds(slot_box, 0, tree, node, slot);
+
+            if ((imask & (1 << slot)) !== 0) {
+                // a child node: the slots below this one that hold child nodes say which
+                const child = child_base + bitCount(imask & ((1 << slot) - 1));
+
+                child_slots++;
+
+                if (child <= node || child >= node_count) {
+                    child_escaped += 1;
+                    escaped_nodes.add(node);
+
+                    if (examples.length < 5) {
+                        examples.push({ node, slot, child, problem: 'not a node below this one' });
+                    }
+
+                    continue;
+                }
+
+                // a child with no triangle under it holds nothing to escape
+                const error = under[child * 6] > under[child * 6 + 3] ? 0 : escape_of(under, child * 6);
+
+                if (error > tolerance) {
+                    child_escaped += 1;
+                    escaped_nodes.add(node);
+
+                    if (examples.length < 5) {
+                        examples.push({
+                            node,
+                            slot,
+                            child,
+                            tree_box: Array.from(slot_box, v => +v.toFixed(3)),
+                            triangles_under_child: Array.from(under.subarray(child * 6, child * 6 + 6), v => +v.toFixed(3)),
+                            escapes_by: +error.toFixed(4),
+                        });
+                    }
+                }
+
+                worst = Math.max(worst, error);
+
+                for (let axis = 0; axis < 3; axis++) {
+                    under[node * 6 + axis] = Math.min(under[node * 6 + axis], under[child * 6 + axis]);
+                    under[node * 6 + axis + 3] = Math.max(under[node * 6 + axis + 3], under[child * 6 + axis + 3]);
+                }
+
+                continue;
+            }
+
+            const first = triangle_base + (slot_meta & 0b11111);
+            const count = bitCount((slot_meta >> 5) & 0b111);
+
+            for (let j = 0; j < count; j++) {
+                const id = first + j;
+
+                // a triangle's id is `(meshlet << 8) | triangle`; the audit laid them out a fixed stride a meshlet
+                const index = (id >>> 8) * BLAS_AUDIT_MESHLET_STRIDE + (id & 0xFF);
+
+                const source = index * 6;
+
+                triangle_count++;
+
+                if (index >= id_count || (id & 0xFF) >= BLAS_AUDIT_MESHLET_STRIDE || intersector[source] > intersector[source + 3]) {
+                    escaped += 1;
+                    escaped_nodes.add(node);
+
+                    if (examples.length < 5) {
+                        examples.push({ node, slot, triangle: id, problem: 'the geometry has no such triangle' });
+                    }
+
+                    continue;
+                }
+
+                named[index] += 1;
+
+                const error = escape_of(intersector, source);
+
+                for (let axis = 0; axis < 3; axis++) {
+                    under[node * 6 + axis] = Math.min(under[node * 6 + axis], intersector[source + axis]);
+                    under[node * 6 + axis + 3] = Math.max(under[node * 6 + axis + 3], intersector[source + axis + 3]);
+                }
+
+                if (error > tolerance) {
+                    escaped += 1;
+                    escaped_nodes.add(node);
+
+                    if (examples.length < 5) {
+                        examples.push({
+                            node,
+                            slot,
+                            triangle: id,
+                            tree_box: Array.from(slot_box, v => +v.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);
+            }
+        }
+    }
+
+    // every triangle the geometry holds, named by exactly one slot
+    let unnamed = 0;
+    let repeated = 0;
+
+    for (let index = 0; index < id_count; index++) {
+        if (intersector[index * 6] > intersector[index * 6 + 3]) {
+            // not a triangle
+            continue;
+        }
+
+        if (named[index] === 0) {
+            unnamed += 1;
+        } else if (named[index] > 1) {
+            repeated += 1;
+        }
+    }
+
+    const sound = escaped === 0 && child_escaped === 0 && unnamed === 0 && repeated === 0;
+
+    const result = {
+        triangle_count,
+        child_slots,
+        escaped,
+        child_escaped,
+        escaped_nodes: [...escaped_nodes].sort((a, b) => a - b),
+        unnamed,
+        repeated,
+        worst: +worst.toFixed(5),
+        examples,
+        verdict: sound
+            ? `pass — all ${triangle_count} triangles sit inside the slot that names them, each named once, `
+            + `and ${child_slots} slots hold every triangle under the child node they name`
+            : `FAIL — of ${triangle_count} triangles named, ${escaped} lie outside the slot that names `
+            + `them (worst by ${(worst * 100).toFixed(1)}% of the slot's own size), ${unnamed} of the `
+            + `geometry's are named by no slot and ${repeated} by more than one; ${child_escaped} of `
+            + `${child_slots} slots do not hold the triangles under the child node they name. Rays `
+            + `descend into those boxes, test a triangle that is elsewhere, and miss.`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}

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

@@ -11,7 +11,8 @@
  * @param {PerspectiveCamera} options.camera
  * @param {Scene} options.scene
  * @param {number} options.entity a skinned mesh entity, whose clone is being deformed
- * @param {number} [options.tolerance] relative box disagreement to accept
+ * @param {number} [options.tolerance] slack on the fit, in steps of the root's grid, and the relative
+ * movement between the samples below which the pose is taken not to have moved
  * @returns {Promise<object>} the samples and the verdict
  */
 export function verify_skinned_blas_refit({ renderer, camera, scene, entity, tolerance, }: {
@@ -22,21 +23,19 @@ export function verify_skinned_blas_refit({ renderer, camera, scene, entity, tol
     tolerance?: number;
 }): Promise<object>;
 /**
- * Does each leaf's box belong to the triangle that leaf names?
+ * Does each leaf slot's box belong to the triangles that slot names?
  *
  * The check above cannot see this, and it is worth being explicit about why. Its two properties —
- * root box equals the metadata box, every internal node equals its children's union — are both
- * invariant under *any* permutation of triangles among leaves. Deal the same set of triangle boxes
- * out to the wrong leaves and the union of all of them is unchanged, so the root still matches, and
- * the climb still computes each node from whatever its children hold. A tree that fits every
- * triangle to the wrong leaf passes both and traces garbage: a ray descends into a box, tests the
- * triangle the leaf names, and that triangle is somewhere else entirely.
+ * the root holds the metadata box, every slot holds the child node it names — are both invariant
+ * under *any* permutation of triangles among leaf slots. Deal the same triangles out to the wrong
+ * slots and the union of all of them is unchanged, so the root still matches, and each node is still
+ * fitted to whatever its children hold. A tree that fits every triangle to the wrong slot passes both
+ * and traces garbage: a ray descends into a box, tests the triangles the slot names, and those
+ * triangles are somewhere else entirely.
  *
- * The way to see it is to refit a geometry that is **not** deforming, and hold the result against
- * the tree it was copied from. The CPU builder put each leaf's box there with the correspondence
- * that is correct by construction; the refit recomputes those boxes from the vertex buffer. Nothing
- * moved in between, so the two have to be the same bytes — and a permutation is exactly what stops
- * them being.
+ * The way to see it is to refit a geometry that is **not** deforming, and hold every slot against the
+ * triangles the intersector fetches for it. Nothing moved, so there is no frame of slack to hide
+ * behind: every triangle sits inside the slot that names it or the refit read another one.
  *
  * @param {object} options
  * @param {Renderer} options.renderer

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":"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"}
+{"version":3,"file":"verify_skinned_blas_refit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js"],"names":[],"mappings":"AAmNA;;;;;;;;;;;;;;;;GAgBG;AACH;IAR6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACJ,MAAM,EAAtB,MAAM;IACW,SAAS,GAA1B,MAAM;IAEJ,QAAQ,MAAM,CAAC,CAuG3B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAJ6B,QAAQ;IACD,QAAQ;IAC/B,QAAQ,MAAM,CAAC,CAuC3B"}