@woosh/meep-engine 3.2.0 → 3.4.0

package/src/shade/renderer/scene/optimization/geometry/internal/match_validate_topology.js

@@ -1,4 +1,4 @@
-import { bt_face_read_triangle_corners } from "./bt_face_loop_helpers.js";
+import { bt_face_read_triangle_vertices } from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_face_read_triangle.js";
 
 const a_corners = [0, 0, 0];
 const b_corners = [0, 0, 0];
@@ -29,8 +29,8 @@ export function match_validate_topology(
         const face_b = face_b_for_a.get(face_a);
         if (face_b === undefined) return false;
 
-        if (!bt_face_read_triangle_corners(topology_a, face_a, a_corners)) return false;
-        if (!bt_face_read_triangle_corners(topology_b, face_b, b_corners)) return false;
+        if (!bt_face_read_triangle_vertices(a_corners, topology_a, face_a)) return false;
+        if (!bt_face_read_triangle_vertices(b_corners, topology_b, face_b)) return false;
 
         const exp0 = vertex_b_for_a.get(a_corners[0]);
         const exp1 = vertex_b_for_a.get(a_corners[1]);

package/src/shade/renderer/scene/optimization/geometry/internal/seed_correspondence_from_window.js

@@ -1,4 +1,4 @@
-import { bt_face_read_triangle_corners } from "./bt_face_loop_helpers.js";
+import { bt_face_read_triangle_vertices } from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_face_read_triangle.js";
 import { vertex_attribute_pairs, vertex_attributes_match } from "./vertex_attributes_equal.js";
 
 /**
@@ -37,8 +37,8 @@ export function seed_correspondence_from_window(
         const face_a = a_start + t;
         const face_b = b_start + t;
 
-        if (!bt_face_read_triangle_corners(topology_a, face_a, a_corners)) return null;
-        if (!bt_face_read_triangle_corners(topology_b, face_b, b_corners)) return null;
+        if (!bt_face_read_triangle_vertices(a_corners, topology_a, face_a)) return null;
+        if (!bt_face_read_triangle_vertices(b_corners, topology_b, face_b)) return null;
 
         const offset = find_matching_perm(va_to_vb, a_corners, b_corners, attrs);
         if (offset === -1) return null;

package/src/shade/renderer/scene/serialization/deserialize_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deserialize_scene.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/serialization/deserialize_scene.js"],"names":[],"mappings":"AAyMA;;;;;;GAMG;AACH,0CAJW,YAAY,iBAEV,cAAc,CA6R1B;AAED;;;;;;;GAOG;AACH,yCAJW,MAAM,iBAEJ,cAAc,CAuB1B;6BAzgB4B,yCAAyC"}
+{"version":3,"file":"deserialize_scene.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/serialization/deserialize_scene.js"],"names":[],"mappings":"AAuMA;;;;;;GAMG;AACH,0CAJW,YAAY,iBAEV,cAAc,CA6R1B;AAED;;;;;;;GAOG;AACH,yCAJW,MAAM,iBAEJ,cAAc,CAuB1B;6BAvgB4B,yCAAyC"}

package/src/shade/renderer/scene/serialization/deserialize_scene.js

@@ -109,8 +109,6 @@ function is_avif_hdr(array_buffer) {
     return false;
 }
 
-// ─── PQ EOTF (inverse of the OETF used during serialization) ────────────────
-
 /**
  * @param {BinaryBuffer} buffer
  * @param {ShadeTexture[]} textures  indexed texture table

package/src/shade/renderer/scene/shader_bvh_extract_instance_leaves.d.ts

@@ -0,0 +1,22 @@
+export const BVH_EXTRACT_WORKGROUP_SIZE: 64;
+/**
+ * Turn the TLAS's live instance rows into the flat leaf set {@link graph_bvh_build_lbvh} consumes,
+ * and reduce their union into the scene-bounds cell the Morton pass quantises against.
+ *
+ * World AABBs come from the scene database's `meshes` table rather than from the CPU tree's leaves:
+ * it is the single source of truth, it is refreshed GPU-side for GPU-authority rows (which the CPU
+ * never learns about at all), and reading it removes the build's dependency on CPU-side bounds
+ * bookkeeping.
+ *
+ * This is the only scene-aware pass in the build, which is why it lives here with the scene code
+ * rather than in `gpu_primitive/bvh/` — everything downstream of it takes flat boxes and payloads
+ * and serves geometry just as well as instances.
+ *
+ * `scene_bounds` must be seeded with +/-inf before this runs; a pool-cleared buffer is zeroed, and
+ * zero is a perfectly good coordinate.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_extract_instance_leaves: ComputeShader;
+import { ComputeShader } from "../shader/ComputeShader.js";
+//# sourceMappingURL=shader_bvh_extract_instance_leaves.d.ts.map

package/src/shade/renderer/scene/shader_bvh_extract_instance_leaves.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_bvh_extract_instance_leaves.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/shader_bvh_extract_instance_leaves.js"],"names":[],"mappings":"AAUA,4CAA6C;AA+G7C;;;;;;;;;;;;;;;;;GAiBG;AACH,iDAFU,aAAa,CAOpB;8BA3I2B,4BAA4B"}

package/src/shade/renderer/scene/shader_bvh_extract_instance_leaves.js

@@ -0,0 +1,145 @@
+import { WebGPUExtensionType } from "../../descriptor/WebGPUExtensionType.js";
+import { atomic_u32, f32, u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { chunk_aabb_atomic_f32 } from "../animation/skinning/bounds_refresh/chunk_aabb_atomic_f32.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { BVH_BUILD_SETTINGS_STRUCT } from "../gpu_primitive/bvh/BVH_BUILD_SETTINGS_STRUCT.js";
+import { chunk_scene_database_access } from "./chunk_scene_database_access.js";
+
+export const BVH_EXTRACT_WORKGROUP_SIZE = 64;
+
+/**
+ * Subgroup size is a runtime value of at least 4, so a workgroup splits into at most this many
+ * subgroups. The array of per-subgroup partials is sized for the worst case.
+ *
+ * @type {number}
+ */
+const MAX_SUBGROUPS = BVH_EXTRACT_WORKGROUP_SIZE / 4;
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addUniform("settings", BVH_BUILD_SETTINGS_STRUCT)
+    // occupied rows of the scene database's `meshes` table, compacted — dead and reused rows never
+    // reach the build
+    .addStorageBuffer("rows", WebGPUArray.from(u32), false)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32), false)
+    .addStorageBuffer("leaf_bounds", WebGPUArray.from(f32), true)
+    .addStorageBuffer("leaf_payload", WebGPUArray.from(u32), true)
+    // six words holding plain f32 bit patterns, seeded to +/-inf before this pass runs
+    .addStorageBuffer("scene_bounds", WebGPUArray.from(atomic_u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const WORKGROUP_SIZE = ${BVH_EXTRACT_WORKGROUP_SIZE}u;
+
+// The scatter sentinels in scene_bounds are true +/-inf, written host-side as u32 bit patterns.
+// Here they cannot be: WGSL will not const-fold bitcast<f32>(0x7F800000u), because the result is
+// not representable as a literal. The largest finite f32 is the identity element in practice —
+// no world-space bound comes within many orders of magnitude of it.
+const FLOAT_MAX = 3.4028234e38;
+
+var<workgroup> wg_low: array<vec3<f32>, ${MAX_SUBGROUPS}>;
+var<workgroup> wg_high: array<vec3<f32>, ${MAX_SUBGROUPS}>;
+
+@compute @workgroup_size(WORKGROUP_SIZE, 1, 1)
+fn main(
+    @builtin(global_invocation_id) gid: vec3<u32>,
+    @builtin(local_invocation_index) thread_id: u32,
+    @builtin(subgroup_invocation_id) lane_id: u32,
+    @builtin(subgroup_size) lane_count: u32,
+) {
+    let i = gid.x;
+
+    // Threads past the end contribute the identity element rather than returning: the reduction
+    // below is workgroup-wide and every lane has to reach it.
+    var low = vec3<f32>(FLOAT_MAX);
+    var high = vec3<f32>(-FLOAT_MAX);
+
+    if (i < settings.element_count) {
+        let row = rows[i];
+
+        let mesh = scene_read_mesh(&scene_database, row);
+
+        low = vec3<f32>(mesh.bounding_box[0], mesh.bounding_box[1], mesh.bounding_box[2]);
+        high = vec3<f32>(mesh.bounding_box[3], mesh.bounding_box[4], mesh.bounding_box[5]);
+
+        let destination = i * 6u;
+
+        leaf_bounds[destination] = low.x;
+        leaf_bounds[destination + 1u] = low.y;
+        leaf_bounds[destination + 2u] = low.z;
+        leaf_bounds[destination + 3u] = high.x;
+        leaf_bounds[destination + 4u] = high.y;
+        leaf_bounds[destination + 5u] = high.z;
+
+        // The leaf's payload IS the mesh row — what the traversal hands to scene_read_mesh on a hit.
+        leaf_payload[i] = row;
+    }
+
+    // Subgroups first, workgroup memory only across subgroup boundaries.
+    let subgroup_low = subgroupMin(low);
+    let subgroup_high = subgroupMax(high);
+
+    let subgroup_id = thread_id / lane_count;
+    let subgroup_count = WORKGROUP_SIZE / lane_count;
+
+    if (lane_id == 0u) {
+        wg_low[subgroup_id] = subgroup_low;
+        wg_high[subgroup_id] = subgroup_high;
+    }
+
+    workgroupBarrier();
+
+    // At most MAX_SUBGROUPS entries left; one thread walks them, so nothing here depends on the
+    // subgroup width and no barrier sits under a bound derived from it.
+    if (thread_id == 0u) {
+        var group_low = wg_low[0];
+        var group_high = wg_high[0];
+
+        for (var s = 1u; s < subgroup_count; s += 1u) {
+            group_low = min(group_low, wg_low[s]);
+            group_high = max(group_high, wg_high[s]);
+        }
+
+        aabb_atomic_min_f32(&scene_bounds[0], group_low.x);
+        aabb_atomic_min_f32(&scene_bounds[1], group_low.y);
+        aabb_atomic_min_f32(&scene_bounds[2], group_low.z);
+        aabb_atomic_max_f32(&scene_bounds[3], group_high.x);
+        aabb_atomic_max_f32(&scene_bounds[4], group_high.y);
+        aabb_atomic_max_f32(&scene_bounds[5], group_high.z);
+    }
+}
+`, [
+    chunk_scene_database_access,
+    chunk_aabb_atomic_f32,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * Turn the TLAS's live instance rows into the flat leaf set {@link graph_bvh_build_lbvh} consumes,
+ * and reduce their union into the scene-bounds cell the Morton pass quantises against.
+ *
+ * World AABBs come from the scene database's `meshes` table rather than from the CPU tree's leaves:
+ * it is the single source of truth, it is refreshed GPU-side for GPU-authority rows (which the CPU
+ * never learns about at all), and reading it removes the build's dependency on CPU-side bounds
+ * bookkeeping.
+ *
+ * This is the only scene-aware pass in the build, which is why it lives here with the scene code
+ * rather than in `gpu_primitive/bvh/` — everything downstream of it takes flat boxes and payloads
+ * and serves geometry just as well as instances.
+ *
+ * `scene_bounds` must be seeded with +/-inf before this runs; a pool-cleared buffer is zeroed, and
+ * zero is a perfectly good coordinate.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_extract_instance_leaves = ComputeShader.from({
+    label: "BVHBuild/ExtractInstanceLeaves",
+    resources,
+    body,
+    group_size: [BVH_EXTRACT_WORKGROUP_SIZE, 1, 1],
+});

package/src/shade/renderer/scene/verify_gpu_tlas_build.d.ts

@@ -0,0 +1,18 @@
+/**
+ * End-to-end verification of the GPU TLAS build against a real scene database.
+ *
+ * Builds a synthetic `meshes` table, drives the TLAS through the same calls `GPUSceneContext`
+ * makes, reads the tree back and checks it: root word, every node reachable once, every mesh row
+ * present exactly once as a leaf payload, every internal box containing its children, and the root
+ * containing every instance's world AABB — which is the statement that the extraction pass read the
+ * table correctly and the scene-bounds cell was seeded, not zeroed.
+ *
+ * Then it exercises the three things only the integration has: a pure movement (rebuild, no rows
+ * upload), a removal (a leaf really goes away), and an emptied TLAS (the host-written empty-tree
+ * word).
+ *
+ * @param {GraphicsContext} graphics
+ * @returns {Promise<void>}
+ */
+export function verify_gpu_tlas_build(graphics: GraphicsContext): Promise<void>;
+//# sourceMappingURL=verify_gpu_tlas_build.d.ts.map

package/src/shade/renderer/scene/verify_gpu_tlas_build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_gpu_tlas_build.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/verify_gpu_tlas_build.js"],"names":[],"mappings":"AA4NA;;;;;;;;;;;;;;;GAeG;AACH,kEAFa,QAAQ,IAAI,CAAC,CAmHzB"}

package/src/shade/renderer/scene/verify_gpu_tlas_build.js

@@ -0,0 +1,364 @@
+import { FrameGraph } from "../../../engine/graphics/render/frame_graph/FrameGraph.js";
+import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
+import { graph_inspect_gpu_buffer } from "../buffer/graph_inspect_gpu_buffer.js";
+import { bvh_buffer_size } from "../gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+import {
+    check_bvh_structure,
+    format_depth_histogram,
+    TRAVERSAL_STACK_SIZE
+} from "../gpu_primitive/bvh/check_bvh_structure.js";
+import { u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { GPUInstancesAccelerationStructure } from "./GPUInstancesAccelerationStructure.js";
+import { SCENE_DATABASE_SPEC } from "./SCENE_DATABASE_SPEC.js";
+
+/**
+ * The whole TLAS path, on a device, against a real scene database.
+ *
+ * `verify_gpu_bvh_build` hands the primitive builder leaf boxes and a scene-bounds cell it computed
+ * on the host, which is the right way to test the builder in isolation — and leaves exactly two
+ * things with no on-device coverage anywhere: `shader_bvh_extract_instance_leaves`, which is where
+ * world AABBs are actually read from the `meshes` table and where the scene bounds are reduced,
+ * and the +/-inf seeding of that cell, which a pool-cleared (zeroed) buffer would silently break by
+ * anchoring every Morton code to the origin. This covers both, by driving
+ * {@link GPUInstancesAccelerationStructure} the way `GPUSceneContext` drives it.
+ *
+ * It also covers what only the integration can show: that the rows list and the `meshes` rows agree,
+ * that a removal really drops a leaf, and that a pure movement rebuilds correctly without
+ * re-uploading rows.
+ */
+
+/**
+ * @param {number} seed
+ * @returns {function(): number}
+ */
+function make_random(seed) {
+    let state = seed >>> 0;
+
+    return () => (state = (state * 1664525 + 1013904223) >>> 0);
+}
+
+/**
+ * A mesh record with nothing in it but the world AABB the build reads. `geometry`, `material` and
+ * `node` are never dereferenced by the extraction pass, so they can be anything.
+ *
+ * @param {number[]} bounding_box
+ * @returns {object}
+ */
+function make_mesh_record(bounding_box) {
+    const centre = [
+        (bounding_box[0] + bounding_box[3]) * 0.5,
+        (bounding_box[1] + bounding_box[4]) * 0.5,
+        (bounding_box[2] + bounding_box[5]) * 0.5,
+    ];
+
+    const radius = Math.hypot(
+        bounding_box[3] - centre[0],
+        bounding_box[4] - centre[1],
+        bounding_box[5] - centre[2]
+    );
+
+    return {
+        geometry: 0,
+        material: 0,
+        node: 0,
+        bounding_box,
+        bounding_sphere: [centre[0], centre[1], centre[2], radius],
+    };
+}
+
+/**
+ * @param {number} count
+ * @param {number} seed
+ * @param {number} spread world extent the instances are scattered over; 0 piles them all in one place
+ * @returns {number[][]} one `[min.xyz, max.xyz]` per instance
+ */
+function make_boxes(count, seed, spread) {
+    const random = make_random(seed);
+    const unit = () => (random() / 0x100000000) * 2 - 1;
+
+    const boxes = [];
+
+    for (let i = 0; i < count; i++) {
+        const centre = [unit() * spread, unit() * spread, unit() * spread];
+        const half = [0.5 + Math.abs(unit()), 0.5 + Math.abs(unit()), 0.5 + Math.abs(unit())];
+
+        boxes.push([
+            centre[0] - half[0], centre[1] - half[1], centre[2] - half[2],
+            centre[0] + half[0], centre[1] + half[1], centre[2] + half[2],
+        ]);
+    }
+
+    return boxes;
+}
+
+/**
+ * Read the TLAS buffer back and check it. Resolves once the readback has landed and been checked.
+ *
+ * @param {GraphicsContext} graphics
+ * @param {GPUInstancesAccelerationStructure} tlas
+ * @param {string} label
+ * @param {number[]} expected_rows the `meshes` rows that should be the tree's leaves
+ * @param {number[][]} boxes_by_row world AABB per row, for the containment check on the root
+ * @returns {Promise<boolean>} whether the tree checked out
+ */
+function inspect_tree(graphics, tlas, label, expected_rows, boxes_by_row) {
+    const leaf_count = expected_rows.length;
+
+    if (leaf_count === 0) {
+        // nothing to traverse: the format's empty tree is the root word alone
+        return read_words(graphics, tlas.buffer, 1).then(words => {
+            const empty = words[0] === 0xffffffff;
+
+            report(label, empty ? [] : [`empty TLAS root word is ${words[0]}, expected BVH_NULL_NODE`], [], '', 0);
+
+            return empty;
+        });
+    }
+
+    const word_count = bvh_buffer_size(leaf_count) / Uint32Array.BYTES_PER_ELEMENT;
+
+    return read_words(graphics, tlas.buffer, word_count).then(tree => {
+        const result = check_bvh_structure(tree, leaf_count, expected_rows);
+
+        // The root has to hold every instance's world box — which is the end-to-end statement that
+        // the extraction pass read the right rows out of the `meshes` table.
+        if (result.problems.length === 0) {
+            const root_bounds = result.floats.subarray(1, 7);
+
+            for (const row of expected_rows) {
+                const box = boxes_by_row[row];
+
+                for (let axis = 0; axis < 3; axis++) {
+                    if (box[axis] < root_bounds[axis] - 1e-3 || box[3 + axis] > root_bounds[3 + axis] + 1e-3) {
+                        result.problems.push(
+                            `root does not contain row ${row} on axis ${axis}: `
+                            + `[${root_bounds[axis]}, ${root_bounds[3 + axis]}] vs [${box[axis]}, ${box[3 + axis]}]`
+                        );
+                        break;
+                    }
+                }
+
+                if (result.problems.length > 0) {
+                    break;
+                }
+            }
+        }
+
+        report(
+            label,
+            result.problems,
+            result.warnings,
+            format_depth_histogram(result.depth_histogram),
+            result.max_depth
+        );
+
+        return result.problems.length === 0;
+    });
+}
+
+/**
+ * @param {string} label
+ * @param {string[]} problems
+ * @param {string[]} warnings
+ * @param {string} depth_summary
+ * @param {number} max_depth
+ */
+function report(label, problems, warnings, depth_summary, max_depth) {
+    const headline = `${label} — max depth ${max_depth}/${TRAVERSAL_STACK_SIZE}`;
+
+    if (problems.length === 0) {
+        console.log(`%c[TLAS] PASS ${headline}`, 'color: #0c0');
+    } else {
+        console.error(`[TLAS] FAIL ${headline}\n  ${problems.join('\n  ')}`);
+    }
+
+    if (depth_summary !== '') {
+        console.log(`        depth histogram (depth:leaves) ${depth_summary}`);
+    }
+
+    for (const warning of warnings) {
+        console.warn(`[TLAS] ${label}: ${warning}`);
+    }
+}
+
+/**
+ * Copy `word_count` words out of a GPU buffer.
+ *
+ * @param {GraphicsContext} graphics
+ * @param {GPUBuffer} buffer
+ * @param {number} word_count
+ * @returns {Promise<Uint32Array>}
+ */
+function read_words(graphics, buffer, word_count) {
+    return new Promise(resolve => {
+        const graph = new FrameGraph('tlas readback');
+
+        const type = WebGPUArray.from(u32, word_count);
+
+        const imported = graph.import_resource(
+            "tlas",
+            BufferResourceDescriptor.fromBuffer(buffer),
+            buffer
+        );
+
+        graph_inspect_gpu_buffer({
+            graph, type, buffer: imported, count: 1,
+            callback([data]) {
+                resolve(data);
+            }
+        });
+
+        const cmd = ShadeGPUCommandContext.create(graphics, 'tlas readback');
+
+        cmd.encodeGraph(graph);
+        cmd.finish();
+    });
+}
+
+/**
+ * End-to-end verification of the GPU TLAS build against a real scene database.
+ *
+ * Builds a synthetic `meshes` table, drives the TLAS through the same calls `GPUSceneContext`
+ * makes, reads the tree back and checks it: root word, every node reachable once, every mesh row
+ * present exactly once as a leaf payload, every internal box containing its children, and the root
+ * containing every instance's world AABB — which is the statement that the extraction pass read the
+ * table correctly and the scene-bounds cell was seeded, not zeroed.
+ *
+ * Then it exercises the three things only the integration has: a pure movement (rebuild, no rows
+ * upload), a removal (a leaf really goes away), and an emptied TLAS (the host-written empty-tree
+ * word).
+ *
+ * @param {GraphicsContext} graphics
+ * @returns {Promise<void>}
+ */
+export async function verify_gpu_tlas_build(graphics) {
+
+    const cases = [
+        { name: 'scattered 1', count: 1, spread: 100 },
+        { name: 'scattered 2', count: 2, spread: 100 },
+        { name: 'scattered 3', count: 3, spread: 100 },
+        { name: 'scattered 64', count: 64, spread: 100 },
+        { name: 'scattered 1025', count: 1025, spread: 100 },
+        { name: 'scattered 20000', count: 20000, spread: 500 },
+        // every instance in the same place: one Morton code for the whole scene
+        { name: 'coincident 512', count: 512, spread: 0 },
+        // far from the origin in every axis — a zeroed scene-bounds cell would put the whole scene
+        // in one corner of the Morton grid and this is where that shows
+        { name: 'far from origin 700', count: 700, spread: 4 },
+    ];
+
+    let failures = 0;
+
+    for (const test_case of cases) {
+        const database = new GPUDatabase({
+            device: graphics.device,
+            definition: SCENE_DATABASE_SPEC,
+            label: 'verify/tlas scene database',
+        });
+
+        const meshes = database.get('meshes');
+
+        const tlas = new GPUInstancesAccelerationStructure(graphics);
+
+        let boxes = make_boxes(test_case.count, 0xa11ce ^ test_case.count, test_case.spread);
+
+        if (test_case.name.startsWith('far from origin')) {
+            boxes = boxes.map(box => box.map((value, i) => value + (i % 3 === 0 ? 9000 : (i % 3 === 1 ? -7000 : 5000))));
+        }
+
+        /** @type {number[]} */
+        const rows = [];
+        /** @type {number[][]} */
+        const boxes_by_row = [];
+
+        for (const box of boxes) {
+            const row = meshes.add(make_mesh_record(box));
+
+            rows.push(row);
+            boxes_by_row[row] = box;
+
+            tlas.instance_add(row, { bounding_box: box });
+        }
+
+        flush(graphics, database);
+
+        tlas.update(database.buffer);
+
+        if (!await inspect_tree(graphics, tlas, `${test_case.name} (n=${rows.length})`, rows, boxes_by_row)) {
+            failures += 1;
+        }
+
+        // ---- a frame in which everything moved, and nothing arrived or left ----
+
+        if (rows.length > 1) {
+            for (const row of rows) {
+                const box = boxes_by_row[row].map((value, i) => value + (i < 3 ? -3 : 3));
+
+                boxes_by_row[row] = box;
+
+                meshes.set(row, make_mesh_record(box));
+                tlas.instance_update(row, { bounding_box: box });
+            }
+
+            flush(graphics, database);
+
+            tlas.update(database.buffer);
+
+            if (!await inspect_tree(graphics, tlas, `${test_case.name} after movement`, rows, boxes_by_row)) {
+                failures += 1;
+            }
+        }
+
+        // ---- a removal, then an emptied TLAS ----
+
+        if (rows.length > 2) {
+            const dropped = rows.splice(1, 1)[0];
+
+            meshes.remove(dropped);
+            tlas.instance_remove(dropped);
+
+            flush(graphics, database);
+
+            tlas.update(database.buffer);
+
+            if (!await inspect_tree(graphics, tlas, `${test_case.name} after removal`, rows, boxes_by_row)) {
+                failures += 1;
+            }
+        }
+
+        for (const row of rows.slice()) {
+            tlas.instance_remove(row);
+        }
+
+        tlas.update(database.buffer);
+
+        if (!await inspect_tree(graphics, tlas, `${test_case.name} emptied`, [], boxes_by_row)) {
+            failures += 1;
+        }
+
+        database.destroy();
+    }
+
+    if (failures === 0) {
+        console.log(`%c[TLAS] all ${cases.length} scenes PASS`, 'color: #0c0; font-weight: bold');
+    } else {
+        console.error(`[TLAS] ${failures} check(s) FAILED`);
+    }
+}
+
+/**
+ * Push the database's pending row writes to the GPU, the way `GPUSceneContext.build()` does.
+ *
+ * @param {GraphicsContext} graphics
+ * @param {GPUDatabase} database
+ */
+function flush(graphics, database) {
+    const cmd = ShadeGPUCommandContext.create(graphics, 'verify/tlas database flush');
+
+    database.update(cmd);
+
+    cmd.finish();
+}

package/src/shade/renderer/shader/chunk/binary/chunk_split_by_3.d.ts

@@ -1,5 +1,13 @@
 /**
- * Morton code encoding
+ * Spreads the low 10 bits of `a` three positions apart — `ABC` becomes `00A00B00C` — the expansion
+ * step of a 30-bit 3D Morton code. Bits above 10 are dropped by the masks, as they are in the CPU
+ * {@link split_by_3}.
+ *
+ * The shifts are parenthesised against the `|` around them because WGSL gives `<<` and `|` no
+ * relative precedence at all: `x | x << 16` is a syntax error, not a differently-bracketed
+ * expression. This chunk had no importer until the GPU BVH builder's Morton pass, so it had never
+ * reached a parser.
+ *
  * @type {CodeChunk}
  */
 export const chunk_split_by_3: CodeChunk;

package/src/shade/renderer/shader/chunk/binary/chunk_split_by_3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_split_by_3.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/binary/chunk_split_by_3.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,+BAFU,SAAS,CAgBjB;0BApBwB,6BAA6B"}
+{"version":3,"file":"chunk_split_by_3.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/binary/chunk_split_by_3.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,+BAFU,SAAS,CAgBjB;0BA5BwB,6BAA6B"}