@woosh/meep-engine 3.14.2 → 3.14.4

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

@@ -1,5 +1,8 @@
+import package_json from "../../../../package.json";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { GPUProfileLevel } from "../../device/timing/profile/GPUProfileLevel.js";
+import { GPUProfileSession } from "../../device/timing/profile/GPUProfileSession.js";
 import { AnimationClipFlags } from "../../renderer/animation/AnimationClipFlags.js";
 import { camera_frame_sphere } from "../../renderer/camera/camera_frame_sphere.js";
 import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
@@ -50,6 +53,70 @@ const CHARACTER_URL = '/test_assets/Michelle.glb';
  */
 const SPACING = 1.1;
 
+/**
+ * How much each profile capture records. `WORKLOAD` is pass spans, the frame graph, and dispatch
+ * and draw counts — the level at which the refit reads as one pass whatever the dancer count, with
+ * its span next to the skinning and the bounds chain. Light enough that a hand-driven recording
+ * will not notice. `VERBOSE` above it adds bind group contents at several times the rate and wants
+ * a frame limit set, not a key you can lean on.
+ *
+ * @type {number}
+ */
+const PROFILE_LEVEL = GPUProfileLevel.WORKLOAD;
+
+/**
+ * Hand an ArrayBuffer to the browser as a file.
+ *
+ * @param {ArrayBuffer} bytes
+ * @param {string} filename
+ */
+function download_bytes(bytes, filename) {
+    const url = URL.createObjectURL(new Blob([bytes], { type: 'application/octet-stream' }));
+
+    const anchor = document.createElement('a');
+
+    anchor.href = url;
+    anchor.download = filename;
+
+    document.body.appendChild(anchor);
+    anchor.click();
+    anchor.remove();
+
+    // Revoking in the same task cancels the download in some browsers — the click only schedules it.
+    setTimeout(() => URL.revokeObjectURL(url), 60000);
+}
+
+/**
+ * `YYYYMMDD-HHMMSS` in local time, matching the naming the other `.sgpt` captures on this machine
+ * already use — same sort order, and it reads as the clock you took it by rather than as UTC.
+ *
+ * @returns {string}
+ */
+function file_timestamp() {
+    const now = new Date();
+
+    const pad = value => String(value).padStart(2, '0');
+
+    return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`
+        + `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+function format_bytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    }
+
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+
 /**
  * A frame-time readout, kept as a rolling mean so the number is readable rather than jittering.
  */
@@ -263,11 +330,11 @@ export async function start() {
     // root box against the bounds-refresh chain's box over the same deformed vertices. Useful when
     // the page cannot be looked at — a browser stops calling `requestAnimationFrame` for a page it
     // is not compositing, so a hidden tab renders no frames to look at in the first place.
-    globalThis.verify = async () => {
+    globalThis.verify = async () => paused(async () => {
         const { verify_skinned_blas_refit } = await import('./verify_skinned_blas_refit.js');
 
         return verify_skinned_blas_refit({ renderer, camera, scene, mesh: globalThis.dancers[0] });
-    };
+    });
 
     // The half `verify()` is blind to: whether each leaf's box belongs to the triangle that leaf
     // names. Run against the character's *source* geometry — skinning deforms the clone's vertex
@@ -279,6 +346,15 @@ export async function start() {
         return verify_leaf_correspondence({ renderer, geometry: globalThis.dancers[0].geometry });
     };
 
+    // The same question of the *clone*, live: after the frame's refit, does every leaf of the
+    // dancer's own tree bound the deformed triangle the intersector fetches for it? Reports the
+    // pattern of any that do not — runs of leaves, and the workgroups they fall in.
+    globalThis.verify_clone_leaves = async () => paused(async () => {
+        const { verify_clone_leaves } = await import('./verify_clone_leaves.js');
+
+        return verify_clone_leaves({ renderer, scene, mesh: globalThis.dancers[0] });
+    });
+
     const frame_timer = new FrameTimer();
 
     // Tracing by default — it is the reading of the scene this page exists to check.
@@ -305,6 +381,31 @@ export async function start() {
 
     let animating = true;
 
+    /**
+     * Run a check with the dance held still.
+     *
+     * The checks read the tree and the vertices in separate readbacks, and every await between
+     * those lets the frame loop advance the pose: a box read on one frame and a box read three
+     * frames later disagree by exactly the motion in between, however right the refit is. With the
+     * loop's frames passing a zero time step, only the frames a check drives itself move the pose —
+     * which is what its "did the tree follow the mesh" question needs.
+     *
+     * @template T
+     * @param {() => Promise<T>} check
+     * @returns {Promise<T>}
+     */
+    async function paused(check) {
+        const was_animating = animating;
+
+        animating = false;
+
+        try {
+            return await check();
+        } finally {
+            animating = was_animating;
+        }
+    }
+
     element('animation').addEventListener('click', () => {
         animating = !animating;
 
@@ -365,7 +466,9 @@ export async function start() {
 
     const parameters = new URLSearchParams(location.search);
 
-    const count = Math.min(64, Math.max(1, Number.parseInt(parameters.get('count'), 10) || 1));
+    // Hundreds, not dozens: the refit is one batch whatever the count, and the point of a large cast
+    // is to see that hold.
+    const count = Math.min(512, Math.max(1, Number.parseInt(parameters.get('count'), 10) || 1));
 
     element('character_count').value = String(count);
 
@@ -388,11 +491,26 @@ export async function start() {
     /** @type {SkinnedMesh[]} */
     const dancers = [];
 
+    /**
+     * Where the load's time goes, for the console: one parse per dancer — the glTF decoded, its
+     * meshlets built and compressed, its BLAS built on the CPU, every time — then the first frames
+     * that upload every clone and tree, then one bounds readback per dancer.
+     */
+    const load_timing = { parses: [], first_frames_ms: 0, bounds_ms: 0 };
+
     try {
         const asset_manager = await make_playground_asset_manager();
 
         for (let i = 0; i < count; i++) {
+            // One parse per dancer, in sequence: at a few hundred this is the better part of a
+            // minute, and a status that does not move looks like a page that has stopped.
+            set_status(`loading ${i + 1} / ${count} × ${CHARACTER_URL} …`);
+
+            const started = performance.now();
+
             dancers.push(...await add_dancer(scene, scene_context, asset_manager, i, count));
+
+            load_timing.parses.push(performance.now() - started);
         }
     } catch (error) {
         set_status(
@@ -412,16 +530,26 @@ export async function start() {
     // Frames enough for skinning to run and its bounds-refresh chain to publish a deformed box,
     // which is the only box worth framing on — see `world_bounds_of`. The camera is parked at the
     // origin until then, so nothing is worth looking at yet either.
+    set_status(`first frames — uploading ${count} clones and their trees …`);
+
+    const first_frames_started = performance.now();
+
     for (let i = 0; i < 8; i++) {
         renderer.render(camera, scene, 1 / 60);
 
         await renderer.graphics.device.queue.onSubmittedWorkDone();
     }
 
+    load_timing.first_frames_ms = performance.now() - first_frames_started;
+
     // union over every dancer, so a crowd is framed rather than whoever loaded first
     let low = null;
     let high = null;
 
+    set_status(`framing — reading ${dancers.length} boxes back …`);
+
+    const bounds_started = performance.now();
+
     for (const dancer of dancers) {
         const bounds = await world_bounds_of(scene_context, dancer);
 
@@ -434,6 +562,20 @@ export async function start() {
         );
     }
 
+    load_timing.bounds_ms = performance.now() - bounds_started;
+
+    {
+        const parses = load_timing.parses;
+        const total = parses.reduce((sum, ms) => sum + ms, 0);
+
+        console.log(
+            `load: ${parses.length} parses in ${(total / 1000).toFixed(1)} s `
+            + `(mean ${(total / parses.length).toFixed(0)} ms, max ${Math.max(...parses).toFixed(0)} ms, `
+            + `first ${parses[0].toFixed(0)} ms) · first frames ${(load_timing.first_frames_ms / 1000).toFixed(1)} s `
+            + `· bounds readback ${(load_timing.bounds_ms / 1000).toFixed(1)} s`
+        );
+    }
+
     const span = new Vector3(high.x - low.x, high.y - low.y, high.z - low.z);
 
     globalThis.floor = add_floor(scene, Math.max(span.x, span.z) * 6, low.y);
@@ -467,6 +609,200 @@ export async function start() {
 
     renderer.indicate_view_change();
 
+    // ---- profiling: T starts a recording, T again stops it and downloads the capture ---------
+
+    const profile_status = element('profile_status');
+
+    /**
+     * The recording in progress, or null.
+     *
+     * The engine never constructs one of these — `Renderer.profile_session` is a nullable field and
+     * the null checks around it are the entire integration, which is what keeps the profiler out of
+     * a bundle that does not ask for it. The two imports at the top of this file are the whole
+     * opt-in.
+     *
+     * @type {GPUProfileSession|null}
+     */
+    let profile_session = null;
+
+    /** Guards against T being leaned on while a stop is still draining. */
+    let profile_busy = false;
+
+    function set_profile_status(text, recording = false) {
+        profile_status.textContent = text;
+        profile_status.className = recording ? 'recording' : '';
+    }
+
+    function start_profile() {
+        const device = renderer.device;
+
+        const settings = [
+            `${count} dancer${count === 1 ? '' : 's'}`,
+            renderer.feature_path_tracing_enabled ? 'path traced' : 'rasterized',
+            animating ? 'dancing' : 'pose frozen',
+            `${renderer.pixel_ratio.toFixed(2)}x`,
+        ];
+
+        const session = new GPUProfileSession({
+            level: PROFILE_LEVEL,
+            note: `skinned_blas_refit — ${settings.join(' · ')}`,
+        });
+
+        // Populate before start(): the meta record is written into the stream there and not read
+        // again. Without it the capture is unreadable in the sense that matters — a pass taking
+        // 0.4 ms says nothing until you know which GPU and at what resolution.
+        const meta = session.meta;
+
+        // `GPUDevice.adapterInfo` is recent enough that a browser running this page may not have it,
+        // and several browsers withhold the fields even when they do. Empty is what the format
+        // expects in that case.
+        const info = device.adapterInfo;
+
+        if (info !== undefined && info !== null) {
+            meta.adapter_vendor = info.vendor ?? "";
+            meta.adapter_architecture = info.architecture ?? "";
+            meta.adapter_device = info.device ?? "";
+            meta.adapter_description = info.description ?? "";
+        }
+
+        meta.features = [...device.features];
+        meta.engine_version = package_json.version;
+
+        session.onBytesWritten.add(bytes => {
+            set_profile_status(
+                `● recording — ${session.frames_recorded} frames, ${format_bytes(bytes)}  ·  T to stop`,
+                true
+            );
+        });
+
+        renderer.profile_session = session;
+        session.start();
+
+        profile_session = session;
+
+        // The timers go quiet without this rather than failing, so the capture still carries the
+        // frame graph and the workload — it just has no durations in it. Worth knowing before you
+        // record for a minute and then look.
+        const timed = device.features.has('timestamp-query');
+
+        set_profile_status(
+            timed
+                ? '● recording — 0 frames  ·  T to stop'
+                : '● recording without timestamp-query — structure only, no durations  ·  T to stop',
+            true
+        );
+    }
+
+    /**
+     * Wait for frames already submitted to finish landing in the session.
+     *
+     * A frame is committed when its timestamp readback resolves — a `mapAsync` a frame or two behind
+     * submit, see `ShadeGPUCommandContext.profiling_absorbed` — and `record_frame` silently ignores
+     * anything arriving after `stop()`. Stopping the instant the key goes down therefore discards
+     * the last few frames, which are the ones you were most likely looking at.
+     *
+     * Drains the queue, then waits for the frame count to stop moving. Capped, because a recording
+     * taken while the page is paused never moves at all.
+     *
+     * @param {GPUProfileSession} session
+     */
+    async function drain_profile(session) {
+        const DEADLINE_MS = 1000;
+        const QUIET_MS = 60;
+
+        await renderer.device.queue.onSubmittedWorkDone();
+
+        const deadline = performance.now() + DEADLINE_MS;
+
+        let previous = session.frames_recorded;
+
+        while (performance.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, QUIET_MS));
+
+            if (session.frames_recorded === previous) {
+                return;
+            }
+
+            previous = session.frames_recorded;
+        }
+    }
+
+    async function stop_profile() {
+        const session = profile_session;
+
+        profile_session = null;
+
+        // Detach first, so nothing encoded during the drain below joins the recording. Frames
+        // already encoded are unaffected: Renderer captures the session into a local before it
+        // subscribes to the readback.
+        renderer.profile_session = null;
+
+        set_profile_status('stopping — draining in-flight frames…');
+
+        await drain_profile(session);
+
+        const bytes = session.stop();
+
+        const filename = `skinned_blas_refit-${file_timestamp()}.sgpt`;
+
+        download_bytes(bytes, filename);
+
+        // Also to the console, because the status line is the only other place the name appears and
+        // a browser that declines the save says nothing about which capture it declined.
+        console.log(
+            `profile: ${session.frames_recorded} frames, ${format_bytes(bytes.byteLength)}, `
+            + `${session.topology_count} topolog${session.topology_count === 1 ? 'y' : 'ies'} -> ${filename}`
+        );
+
+        set_profile_status(
+            `${session.frames_recorded} frames, ${format_bytes(bytes.byteLength)}`
+            + `, ${session.topology_count} topolog${session.topology_count === 1 ? 'y' : 'ies'}`
+            + `  ·  ${filename}`
+        );
+    }
+
+    window.addEventListener('keydown', event => {
+        if (event.ctrlKey || event.metaKey || event.altKey || event.repeat) {
+            return;
+        }
+
+        // `key` first, because it is the letter actually printed on the key the user pressed —
+        // `code` is physical position, so on AZERTY it names the key where T sits on QWERTY. `code`
+        // is the fallback for layouts whose `key` is not Latin at all (Cyrillic gives "е" here).
+        if (event.key.toLowerCase() !== 't' && event.code !== 'KeyT') {
+            return;
+        }
+
+        // the panel's fields and buttons are focusable; do not steal a key from a field
+        const target = event.target;
+
+        if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) {
+            return;
+        }
+
+        if (profile_busy) {
+            return;
+        }
+
+        event.preventDefault();
+
+        profile_busy = true;
+
+        const done = profile_session === null
+            ? Promise.resolve(start_profile())
+            : stop_profile();
+
+        done.catch(error => {
+            set_profile_status(`profiling failed: ${error?.message ?? error}`);
+            console.error(error);
+
+            profile_session = null;
+            renderer.profile_session = null;
+        }).finally(() => {
+            profile_busy = false;
+        });
+    });
+
     // ---- frame loop -----------------------------------------------------------------------
 
     const FRAME_RATE_LIMIT = 60;

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

@@ -1,11 +1,17 @@
 export const BLAS_AUDIT_WORKGROUP_SIZE: 64;
+/**
+ * Which tree, and where it lives — one tree at a time, which is what an audit is.
+ *
+ * @type {WebGPUStruct}
+ */
+export const BLAS_AUDIT_SETTINGS_STRUCT: WebGPUStruct;
 /**
  * Read every leaf's triangle back through the path the *intersector* uses.
  *
  * The refit computes a leaf's box with `geometry_read_triangle_bounds`; `ray_query_blas_nearest`
  * fetches the triangle it actually tests with `geometry_read_triangle_vertices`. Those are two
  * different functions over the same encoded payload, and nothing until now has held them against
- * each other on real data — only on a synthetic case in `blas_refit_leaf_bounds.spec.js`.
+ * each other on real data — only on a synthetic case in `chunk_geometry_read_triangle_bounds.spec.js`.
  *
  * If they disagree, a ray descends into a box, tests a triangle that is somewhere else, and misses.
  * Whole meshlets go absent while the tree itself checks out perfectly, which is exactly the shape of
@@ -17,5 +23,6 @@ export const BLAS_AUDIT_WORKGROUP_SIZE: 64;
  * @type {ComputeShader}
  */
 export const shader_blas_audit_leaf_triangles: ComputeShader;
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
 import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
 //# sourceMappingURL=shader_blas_audit_leaf_triangles.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"shader_blas_audit_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js"],"names":[],"mappings":"AAqBA,2CAA4C;AA8D5C;;;;;;;;;;;;;;;;GAgBG;AACH,+CAFU,aAAa,CAMpB;8BArG2B,wCAAwC"}
+{"version":3,"file":"shader_blas_audit_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js"],"names":[],"mappings":"AAmBA,2CAA4C;AAE5C;;;;GAIG;AACH,yCAFU,YAAY,CAmBE;AA8DxB;;;;;;;;;;;;;;;;GAgBG;AACH,+CAFU,aAAa,CAMpB;6BA7G0B,4CAA4C;8BAd3C,wCAAwC"}

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

@@ -15,16 +15,38 @@ import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../../renderer/geometry/GEOMETRY_A
 import {
     MESHLET_METADATA_STRUCT
 } from "../../renderer/geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
-import {
-    BLAS_LEAF_BOUNDS_SETTINGS_STRUCT
-} from "../../renderer/geometry/bvh/shader_blas_refit_leaf_bounds.js";
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
 
 export const BLAS_AUDIT_WORKGROUP_SIZE = 64;
 
+/**
+ * Which tree, and where it lives — one tree at a time, which is what an audit is.
+ *
+ * @type {WebGPUStruct}
+ */
+export const BLAS_AUDIT_SETTINGS_STRUCT = WebGPUStruct.from({
+    /**
+     * Leaves in this tree — one triangle each, so also its triangle count.
+     */
+    leaf_count: u32,
+    /**
+     * u32 word the tree's node 0 starts at inside the shared node arena.
+     */
+    node_word_offset: u32,
+    /**
+     * Word this tree's leaf list starts at inside the shared leaf-node arena.
+     */
+    leaf_nodes_offset: u32,
+    /**
+     * Row in the geometry table whose meshlets the leaves index into.
+     */
+    geometry_index: u32,
+}, "BlasAuditSettings");
+
 const resources = new ShaderResourceSetDescriptor();
 
 // per-dispatch, 16 bytes, read-only: immediate data rather than a uniform buffer
-resources.setImmediate("settings", BLAS_LEAF_BOUNDS_SETTINGS_STRUCT);
+resources.setImmediate("settings", BLAS_AUDIT_SETTINGS_STRUCT);
 resources.createGroup()
     .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), false)
     .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT), false)
@@ -87,7 +109,7 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
  * The refit computes a leaf's box with `geometry_read_triangle_bounds`; `ray_query_blas_nearest`
  * fetches the triangle it actually tests with `geometry_read_triangle_vertices`. Those are two
  * different functions over the same encoded payload, and nothing until now has held them against
- * each other on real data — only on a synthetic case in `blas_refit_leaf_bounds.spec.js`.
+ * each other on real data — only on a synthetic case in `chunk_geometry_read_triangle_bounds.spec.js`.
  *
  * If they disagree, a ray descends into a box, tests a triangle that is somewhere else, and misses.
  * Whole meshlets go absent while the tree itself checks out perfectly, which is exactly the shape of

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

@@ -0,0 +1,27 @@
+/**
+ * The leaf audit, on a skinned clone: its tree as the frame's refit left it, against the deformed
+ * triangles the intersector fetches for those leaves now.
+ *
+ * `verify_leaf_triangles` needs a target, and a clone's owner handle lives inside the skinning
+ * context. Every copy of a geometry shares one shape, so the clone's target is its source's with
+ * the clone's own node address substituted — and that address is what the published lookup holds
+ * for the clone's geometry row.
+ *
+ * The refit and this audit run a frame apart at most, so a leaf may be a little larger than its
+ * triangle; a leaf that is *somewhere else* is a leaf the frame did not refit. The pattern of those
+ * is the point: reported as runs of leaf ordinals and as the workgroups of 64 they fall in.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {Scene} options.scene
+ * @param {SkinnedMesh} options.mesh a mesh whose clone is being deformed
+ * @param {number} [options.tolerance]
+ * @returns {Promise<object>}
+ */
+export function verify_clone_leaves({ renderer, scene, mesh, tolerance }: {
+    renderer: Renderer;
+    scene: Scene;
+    mesh: SkinnedMesh;
+    tolerance?: number;
+}): Promise<object>;
+//# sourceMappingURL=verify_clone_leaves.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify_clone_leaves.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_clone_leaves.js"],"names":[],"mappings":"AAsDA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAN6B,QAAQ;IACX,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAsD3B"}

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

@@ -0,0 +1,127 @@
+import { verify_leaf_triangles } from "./verify_leaf_triangles.js";
+
+/**
+ * @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;
+}
+
+/**
+ * Contiguous runs of a sorted list of integers, as `[first, last]` pairs.
+ *
+ * @param {number[]} values
+ * @returns {number[][]}
+ */
+function runs_of(values) {
+    const runs = [];
+
+    for (const value of values) {
+        const last = runs[runs.length - 1];
+
+        if (last !== undefined && last[1] === value - 1) {
+            last[1] = value;
+        } else {
+            runs.push([value, value]);
+        }
+    }
+
+    return runs;
+}
+
+/**
+ * The leaf audit, on a skinned clone: its tree as the frame's refit left it, against the deformed
+ * triangles the intersector fetches for those leaves now.
+ *
+ * `verify_leaf_triangles` needs a target, and a clone's owner handle lives inside the skinning
+ * context. Every copy of a geometry shares one shape, so the clone's target is its source's with
+ * the clone's own node address substituted — and that address is what the published lookup holds
+ * for the clone's geometry row.
+ *
+ * The refit and this audit run a frame apart at most, so a leaf may be a little larger than its
+ * triangle; a leaf that is *somewhere else* is a leaf the frame did not refit. The pattern of those
+ * is the point: reported as runs of leaf ordinals and as the workgroups of 64 they fall in.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {Scene} options.scene
+ * @param {SkinnedMesh} options.mesh a mesh whose clone is being deformed
+ * @param {number} [options.tolerance]
+ * @returns {Promise<object>}
+ */
+export async function verify_clone_leaves({ renderer, scene, mesh, tolerance = 1e-3 }) {
+    const graphics = renderer.graphics;
+    const device = graphics.device;
+    const geometries = graphics.geometries;
+    const blas = geometries.blas;
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    const geometry_index = scene_context.skinning.obtain_geometry_index(mesh);
+
+    const source_target = blas.get_refit_target(geometries.get_metadata(mesh.geometry));
+
+    if (source_target === undefined) {
+        throw new Error('the source geometry has no resident tree');
+    }
+
+    const address = new Uint32Array(
+        await read_back(device, blas.buffer_metadata, geometry_index * 4, 4)
+    )[0];
+
+    const target = {
+        ...source_target,
+        node_word_offset: address * 8,
+    };
+
+    const audit = await verify_leaf_triangles({ renderer, target, geometry_index, tolerance });
+
+    const escaped = audit.escaped_leaves;
+
+    const workgroups = [...new Set(escaped.map(leaf => leaf >> 6))];
+
+    const result = {
+        geometry_index,
+        address,
+        leaf_count: audit.leaf_count,
+        escaped: audit.escaped,
+        worst: audit.worst,
+        // the shape of the failure, if any
+        escaped_runs: runs_of(escaped).slice(0, 20),
+        escaped_run_count: runs_of(escaped).length,
+        workgroups_hit: workgroups.length,
+        workgroup_runs: runs_of(workgroups).slice(0, 20),
+        examples: audit.examples,
+        verdict: audit.escaped === 0
+            ? `pass — all ${audit.leaf_count} of the clone's leaves bound their deformed triangle`
+            : `FAIL — ${audit.escaped} of ${audit.leaf_count} leaves of the clone's tree do not bound `
+            + `their deformed triangle, in ${runs_of(escaped).length} runs over ${workgroups.length} workgroups`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"verify_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_leaf_triangles.js"],"names":[],"mappings":"AA4DA;;;;;;;;;;;GAWG;AACH;IAV6B,QAAQ;IACT,KAAK,GAAtB,MAAM;IACW,MAAM,GAAvB,MAAM;IAIU,cAAc,EAA9B,MAAM;IACW,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAmI3B"}
+{"version":3,"file":"verify_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_leaf_triangles.js"],"names":[],"mappings":"AAyDA;;;;;;;;;;;GAWG;AACH;IAV6B,QAAQ;IACT,KAAK,GAAtB,MAAM;IACW,MAAM,GAAvB,MAAM;IAIU,cAAc,EAA9B,MAAM;IACW,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAsI3B"}