@woosh/meep-engine 3.69.0 → 3.70.0

package/src/shade/renderer/geometry/bvh/shader_blas8_refit_batch.js

@@ -0,0 +1,464 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { AABB3_STRUCT } from "../../shader/chunk/geometry/aabb3/AABB3_STRUCT.js";
+import {
+    chunk_geometry_read_triangle_bounds
+} from "../../shader/chunk/geometry/format/chunk_geometry_read_triangle_bounds.js";
+import { F32_MAX_DEFINITION } from "../../shader/chunk/math/F32_MAX_DEFINITION.js";
+import { BVH8_BLAS_MAX_DEPTH } from "../../shader/chunk/bvh/bvh8/webgpu/BVH8_MAX_DEPTH.js";
+import { chunk_bvh8_node_grid } from "../../shader/chunk/bvh/bvh8/webgpu/chunk_bvh8_node_grid.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../GEOMETRY_ATTRIBUTE_DATA_TYPE.js";
+import { GEOMETRY_METADATA_STRUCT } from "../GEOMETRY_METADATA_STRUCT.js";
+import { MESHLET_METADATA_STRUCT } from "../meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { BLAS8_REFIT_TARGET_STRUCT } from "./BLAS8_REFIT_TARGET_STRUCT.js";
+
+/**
+ * Nodes per workgroup. A workgroup serves one tree and one aligned run of this many of its nodes,
+ * which is what the lookup's second word counts in.
+ *
+ * @type {number}
+ */
+export const BLAS8_REFIT_BATCH_WORKGROUP_SIZE = 64;
+
+/**
+ * `u32` words of spine a node takes: its box's six floats, 24 bits to a word, under a flag.
+ *
+ * @type {number}
+ */
+export const BLAS8_REFIT_SPINE_STRIDE_WORDS = 8;
+
+const resources = new ShaderResourceSetDescriptor();
+
+// Workgroups already covered by earlier sub-dispatches of the same batch, for a batch larger than
+// the device's per-dimension cap. Four bytes, per dispatch: immediate data.
+resources.setImmediate("dispatch_offset", u32);
+
+resources.createGroup()
+    // one row per tree in the batch
+    .addStorageBuffer("targets", WebGPUArray.from(BLAS8_REFIT_TARGET_STRUCT), false)
+    // `(target_index, node_base)` per workgroup, flat
+    .addStorageBuffer("lookup", WebGPUArray.from(u32), false)
+    // The node arena, flat. Of a node, this kernel reads words 4 to 7 — its child block, its triangle
+    // run and its metas — and writes the rest: its origin, exponents and quantized boxes. Nothing it
+    // writes does it read, of any node.
+    .addStorageBuffer("nodes", WebGPUArray.from(u32), true)
+    // every node's box as its own lane found it, for the lane of the node above; zero at the start of
+    // every batch, which reads "not here yet"
+    .addStorageBuffer("spine", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT), false)
+    .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT), false)
+    .addStorageBuffer("meshlet_data", GEOMETRY_ATTRIBUTE_DATA_TYPE, false);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const NODE_STRIDE = 20u;
+const NODE_CHILD_BASE = 4u;
+const NODE_TRIANGLE_BASE = 5u;
+const NODE_METAS = 6u;
+const NODE_BOXES = 8u;
+
+const SPINE_STRIDE = ${BLAS8_REFIT_SPINE_STRIDE_WORDS}u;
+const SPINE_HERE = 0x80000000u;
+const SPINE_BITS = 0x00ffffffu;
+
+// how many rounds a lane looks for its children's boxes before finding the missing ones out for itself;
+// the prefix scan's count
+const LOOKS = 4u;
+
+// what a node's four words of topology say
+struct Blas8RefitShape {
+    child_base: u32,
+    triangle_base: u32,
+    metas: vec2<u32>,
+    // a bit per slot that holds a child node
+    internal: u32,
+}
+
+struct Blas8RefitLook {
+    found: bool,
+    box: ${AABB3_STRUCT.wgsl_ref},
+}
+
+fn blas8_refit_shape(node_word: u32) -> Blas8RefitShape {
+    let metas = vec2<u32>(nodes[node_word + NODE_METAS], nodes[node_word + NODE_METAS + 1u]);
+
+    // a child node's meta has 24 or more in its low five bits: bits 3 and 4 both set
+    let first = metas.x & (metas.x >> 1u) & 0x08080808u;
+    let second = metas.y & (metas.y >> 1u) & 0x08080808u;
+
+    let internal =
+        ((first >> 3u) & 1u) | ((first >> 10u) & 2u) | ((first >> 17u) & 4u) | ((first >> 24u) & 8u)
+        | ((second << 1u) & 16u) | ((second >> 6u) & 32u) | ((second >> 13u) & 64u) | ((second >> 20u) & 128u);
+
+    return Blas8RefitShape(nodes[node_word + NODE_CHILD_BASE], nodes[node_word + NODE_TRIANGLE_BASE], metas, internal);
+}
+
+fn blas8_refit_slot_meta(shape: Blas8RefitShape, slot: u32) -> u32 {
+    return (select(shape.metas.y, shape.metas.x, slot < 4u) >> ((slot & 3u) * 8u)) & 0xffu;
+}
+
+fn blas8_refit_empty_box() -> ${AABB3_STRUCT.wgsl_ref} {
+    return ${AABB3_STRUCT.wgsl_ref}(vec3<f32>(F32_MAX), vec3<f32>(-F32_MAX));
+}
+
+// the box of the triangles a leaf slot names, as the vertices stand now
+fn blas8_refit_slot_triangles(
+    geometry: ${GEOMETRY_METADATA_STRUCT.wgsl_ref},
+    triangle_base: u32,
+    slot_meta: u32,
+) -> ${AABB3_STRUCT.wgsl_ref} {
+    var box = blas8_refit_empty_box();
+
+    let first = triangle_base + (slot_meta & 31u);
+    let count = countOneBits(slot_meta >> 5u);
+
+    for (var i = 0u; i < count; i++) {
+        let triangle = geometry_read_triangle_bounds(geometry, first + i);
+
+        box.min = min(box.min, triangle.min);
+        box.max = max(box.max, triangle.max);
+    }
+
+    return box;
+}
+
+// A node's box goes into the spine as 192 bits, 24 to a word, each word under its own flag: a reader
+// that finds all eight flags has the box, and one that does not has nothing, whatever order the
+// stores reach it in.
+fn blas8_refit_publish(spine_word: u32, box: ${AABB3_STRUCT.wgsl_ref}) {
+    let low = bitcast<vec3<u32>>(box.min);
+    let high = bitcast<vec3<u32>>(box.max);
+
+    atomicStore(&spine[spine_word], SPINE_HERE | (low.x & SPINE_BITS));
+    atomicStore(&spine[spine_word + 1u], SPINE_HERE | (low.x >> 24u) | ((low.y & 0xffffu) << 8u));
+    atomicStore(&spine[spine_word + 2u], SPINE_HERE | (low.y >> 16u) | ((low.z & 0xffu) << 16u));
+    atomicStore(&spine[spine_word + 3u], SPINE_HERE | (low.z >> 8u));
+    atomicStore(&spine[spine_word + 4u], SPINE_HERE | (high.x & SPINE_BITS));
+    atomicStore(&spine[spine_word + 5u], SPINE_HERE | (high.x >> 24u) | ((high.y & 0xffffu) << 8u));
+    atomicStore(&spine[spine_word + 6u], SPINE_HERE | (high.y >> 16u) | ((high.z & 0xffu) << 16u));
+    atomicStore(&spine[spine_word + 7u], SPINE_HERE | (high.z >> 8u));
+}
+
+fn blas8_refit_look(spine_word: u32) -> Blas8RefitLook {
+    var seen: Blas8RefitLook;
+    seen.found = false;
+
+    let w0 = atomicLoad(&spine[spine_word]);
+
+    if ((w0 & SPINE_HERE) == 0u) {
+        return seen;
+    }
+
+    let w1 = atomicLoad(&spine[spine_word + 1u]);
+    let w2 = atomicLoad(&spine[spine_word + 2u]);
+    let w3 = atomicLoad(&spine[spine_word + 3u]);
+    let w4 = atomicLoad(&spine[spine_word + 4u]);
+    let w5 = atomicLoad(&spine[spine_word + 5u]);
+    let w6 = atomicLoad(&spine[spine_word + 6u]);
+    let w7 = atomicLoad(&spine[spine_word + 7u]);
+
+    if ((w1 & w2 & w3 & w4 & w5 & w6 & w7 & SPINE_HERE) == 0u) {
+        return seen;
+    }
+
+    seen.found = true;
+
+    seen.box.min = bitcast<vec3<f32>>(vec3<u32>(
+        (w0 & SPINE_BITS) | ((w1 & 0xffu) << 24u),
+        ((w1 & SPINE_BITS) >> 8u) | ((w2 & 0xffffu) << 16u),
+        ((w2 & SPINE_BITS) >> 16u) | ((w3 & SPINE_BITS) << 8u),
+    ));
+
+    seen.box.max = bitcast<vec3<f32>>(vec3<u32>(
+        (w4 & SPINE_BITS) | ((w5 & 0xffu) << 24u),
+        ((w5 & SPINE_BITS) >> 8u) | ((w6 & 0xffffu) << 16u),
+        ((w6 & SPINE_BITS) >> 16u) | ((w7 & SPINE_BITS) << 8u),
+    ));
+
+    return seen;
+}
+
+// The box of everything under a node, found without waiting for anyone: from the triangles, except
+// where a node on the way down has published, whose box is then taken as it stands.
+fn blas8_refit_subtree_box(
+    tree: ${BLAS8_REFIT_TARGET_STRUCT.wgsl_ref},
+    geometry: ${GEOMETRY_METADATA_STRUCT.wgsl_ref},
+    root: u32,
+) -> ${AABB3_STRUCT.wgsl_ref} {
+    var box = blas8_refit_empty_box();
+
+    // a node, and its child slots still to take; one entry a level
+    var stack: array<vec2u, ${BVH8_BLAS_MAX_DEPTH}>;
+    var pointer = 0u;
+
+    var node = root;
+    var pending = 0u;
+    var arriving = true;
+
+    loop {
+        let shape = blas8_refit_shape((tree.node_offset + node) * NODE_STRIDE);
+
+        if (arriving) {
+            for (var slot = 0u; slot < 8u; slot++) {
+                let slot_meta = blas8_refit_slot_meta(shape, slot);
+
+                if (slot_meta == 0u || (shape.internal & (1u << slot)) != 0u) {
+                    continue;
+                }
+
+                let triangles = blas8_refit_slot_triangles(geometry, shape.triangle_base, slot_meta);
+
+                box.min = min(box.min, triangles.min);
+                box.max = max(box.max, triangles.max);
+            }
+
+            pending = shape.internal;
+        }
+
+        if (pending == 0u) {
+            if (pointer == 0u) {
+                break;
+            }
+
+            pointer--;
+
+            node = stack[pointer].x;
+            pending = stack[pointer].y;
+            arriving = false;
+
+            continue;
+        }
+
+        let slot = countTrailingZeros(pending);
+
+        pending &= pending - 1u;
+
+        let child = shape.child_base + countOneBits(shape.internal & ((1u << slot) - 1u));
+
+        let seen = blas8_refit_look((tree.spine_offset + child) * SPINE_STRIDE);
+
+        if (seen.found) {
+            box.min = min(box.min, seen.box.min);
+            box.max = max(box.max, seen.box.max);
+
+            arriving = false;
+
+            continue;
+        }
+
+        if (pending != 0u && pointer < ${BVH8_BLAS_MAX_DEPTH}u) {
+            stack[pointer] = vec2u(node, pending);
+            pointer++;
+        }
+
+        node = child;
+        arriving = true;
+    }
+
+    return box;
+}
+
+@compute @workgroup_size(${BLAS8_REFIT_BATCH_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) wg: vec3<u32>,
+    @builtin(local_invocation_id) lid: vec3<u32>,
+) {
+    // Which tree, and which run of its nodes: one lookup pair per workgroup.
+    let pair = (wg.x + dispatch_offset) * 2u;
+
+    // ("target" is a reserved word in WGSL)
+    let tree = targets[lookup[pair]];
+
+    let ordinal = lookup[pair + 1u] + lid.x;
+
+    if (ordinal >= tree.node_count) {
+        // the tail of a tree's last run; the next workgroup is another tree's
+        return;
+    }
+
+    // Last node first. A child's index is above its parent's, so the order workgroups are started in
+    // is the order the nodes depend on each other in, and a lane mostly finds what it looks for.
+    let node = tree.node_count - 1u - ordinal;
+
+    let node_word = (tree.node_offset + node) * NODE_STRIDE;
+
+    let geometry = geometries[tree.geometry_index];
+
+    let shape = blas8_refit_shape(node_word);
+
+    var slot_low: array<vec3<f32>, 8>;
+    var slot_high: array<vec3<f32>, 8>;
+
+    var box = blas8_refit_empty_box();
+
+    // The slots of triangles first. They are this lane's own work and take it a while, and for that
+    // while the lanes of the nodes below are at theirs: by the time this one turns to its child
+    // nodes, a child with only triangles under it has published.
+    for (var slot = 0u; slot < 8u; slot++) {
+        let slot_meta = blas8_refit_slot_meta(shape, slot);
+
+        if (slot_meta == 0u || (shape.internal & (1u << slot)) != 0u) {
+            continue;
+        }
+
+        let under = blas8_refit_slot_triangles(geometry, shape.triangle_base, slot_meta);
+
+        slot_low[slot] = under.min;
+        slot_high[slot] = under.max;
+
+        box.min = min(box.min, under.min);
+        box.max = max(box.max, under.max);
+    }
+
+    let spine_word = (tree.spine_offset + node) * SPINE_STRIDE;
+
+    // A node with nothing but triangles under it has its box now, and says so now: before any lane
+    // of this workgroup turns to its children, which may be this node.
+    if (shape.internal == 0u) {
+        blas8_refit_publish(spine_word, box);
+    }
+
+    // The child nodes, looked for in rounds: every one still missing, once a round. A node whose
+    // children have all turned up publishes there and then, inside the round, which is what lets the
+    // node above it find it in the next.
+    var missing = shape.internal;
+
+    for (var round = 0u; round < LOOKS && missing != 0u; round++) {
+        var unseen = missing;
+
+        while (unseen != 0u) {
+            let slot = countTrailingZeros(unseen);
+
+            unseen &= unseen - 1u;
+
+            let child = shape.child_base + countOneBits(shape.internal & ((1u << slot) - 1u));
+
+            let seen = blas8_refit_look((tree.spine_offset + child) * SPINE_STRIDE);
+
+            if (!seen.found) {
+                continue;
+            }
+
+            missing &= ~(1u << slot);
+
+            slot_low[slot] = seen.box.min;
+            slot_high[slot] = seen.box.max;
+
+            box.min = min(box.min, seen.box.min);
+            box.max = max(box.max, seen.box.max);
+        }
+
+        if (missing == 0u) {
+            blas8_refit_publish(spine_word, box);
+        }
+    }
+
+    if (missing != 0u) {
+        // not here, and not waited for
+        while (missing != 0u) {
+            let slot = countTrailingZeros(missing);
+
+            missing &= missing - 1u;
+
+            let child = shape.child_base + countOneBits(shape.internal & ((1u << slot) - 1u));
+
+            let under = blas8_refit_subtree_box(tree, geometry, child);
+
+            slot_low[slot] = under.min;
+            slot_high[slot] = under.max;
+
+            box.min = min(box.min, under.min);
+            box.max = max(box.max, under.max);
+        }
+
+        blas8_refit_publish(spine_word, box);
+    }
+
+    // this node, on the grid of its own box, and each slot's box in bytes on it
+    let grid = bvh8_node_grid(box.min, box.max);
+
+    var boxes: array<u32, 12>;
+
+    for (var slot = 0u; slot < 8u; slot++) {
+        if (blas8_refit_slot_meta(shape, slot) == 0u) {
+            continue;
+        }
+
+        let q_low = bvh8_node_grid_low(grid, slot_low[slot]);
+        let q_high = bvh8_node_grid_high(grid, slot_high[slot]);
+
+        let word = slot >> 2u;
+        let shift = (slot & 3u) * 8u;
+
+        // per axis: two words of low bytes, then two of high
+        boxes[word] |= q_low.x << shift;
+        boxes[2u + word] |= q_high.x << shift;
+        boxes[4u + word] |= q_low.y << shift;
+        boxes[6u + word] |= q_high.y << shift;
+        boxes[8u + word] |= q_low.z << shift;
+        boxes[10u + word] |= q_high.z << shift;
+    }
+
+    nodes[node_word] = bitcast<u32>(box.min.x);
+    nodes[node_word + 1u] = bitcast<u32>(box.min.y);
+    nodes[node_word + 2u] = bitcast<u32>(box.min.z);
+    nodes[node_word + 3u] = grid.exponent.x | (grid.exponent.y << 8u) | (grid.exponent.z << 16u) | (shape.internal << 24u);
+
+    for (var i = 0u; i < 12u; i++) {
+        nodes[node_word + NODE_BOXES + i] = boxes[i];
+    }
+}
+`, [
+    F32_MAX_DEFINITION,
+    AABB3_STRUCT.declaration_chunk,
+    GEOMETRY_METADATA_STRUCT.declaration_chunk,
+    BLAS8_REFIT_TARGET_STRUCT.declaration_chunk,
+    chunk_geometry_read_triangle_bounds,
+    chunk_bvh8_node_grid,
+]);
+
+/**
+ * Refit every BVH8 in a batch, from one dispatch.
+ *
+ * One lane per node, across every tree the batch lists. A node holds its slots' boxes on a grid of
+ * its own box, so a lane has two things to find: the box of everything under each of its slots, and
+ * from their union its own. A slot of triangles is read off the vertex buffer as it stands *now*. A
+ * slot that is a child node depends on that child's lane — as a tile of a prefix scan depends on the
+ * tiles before it, and this takes the scan's shape (`graph_prefix_scan_csdldf`):
+ *
+ * - **Published under a flag.** A lane leaves its node's box in the `spine`, box and flag in the same
+ *   atomic words, as soon as it has it. A reader has the whole box or none of it.
+ * - **Looked for, not waited for.** A lane looks for its children's boxes a fixed number of rounds,
+ *   and publishes the moment the last turns up. What has not turned up by then the lane finds out
+ *   for itself, from the triangles under that child, taking as it stands the box of any node on the
+ *   way down that has published. Nothing spins on another lane,
+ *   and nothing depends on when a store reaches whom.
+ * - **Never in place.** Everything a lane reads to find a box out — the vertices, and the four words
+ *   of a node that say what it holds — no lane writes. Everything a lane writes, no lane reads.
+ * - **In the order of the dependency.** Lanes take a tree's nodes last to first, and a child's index
+ *   is above its parent's, so a device that starts workgroups in order runs the children first. Within
+ *   a lane the order is the same: its own triangles, its box published if that is all there is to it,
+ *   and only then a look at its children. A device that keeps neither order is slower and no less
+ *   right.
+ *
+ * So there are no counters, no parents, no seeding pass and nothing to repair: a zeroed spine, then
+ * this, whatever the trees' depth.
+ *
+ * Boxes are rounded outward at every step that rounds, so a refitted node holds what is under it
+ * exactly as a built one does; it is not the same node the builder would write, whose arithmetic is
+ * exact where this is `f32`.
+ *
+ * For a skinned mesh this runs against the per-instance clone, after the skinning pass has deformed
+ * its vertex region; `geometry_index` on the row is the clone's.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_blas8_refit_batch = ComputeShader.from({
+    label: "BLAS8/RefitBatch",
+    resources,
+    body,
+});

package/src/shade/renderer/geometry/meshlet/MeshletBatch.d.ts

@@ -69,6 +69,18 @@ export class MeshletBatch {
         attribute_index: Uint32Array;
         attribute_position: Float32Array;
     };
+    /**
+     * Re-order the triangles of one meshlet: triangle `i` becomes the triangle that was at `order[i]`.
+     *
+     * Only the meshlet's index section is rewritten, in place. Vertices, attributes, bounds and the
+     * meshlet's address are untouched, so the meshlet draws exactly what it drew before; what changes is
+     * which triangle a `(meshlet, triangle)` id names. Anything that recorded such an id beforehand —
+     * a BLAS leaf, most of all — names a different triangle afterwards.
+     *
+     * @param {number} meshlet_id
+     * @param {Uint8Array|number[]} order a permutation of `0 .. primitive_count - 1`
+     */
+    reorder_triangles(meshlet_id: number, order: Uint8Array | number[]): void;
     build_bounds(): void;
     /**
      *

package/src/shade/renderer/geometry/meshlet/MeshletBatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MeshletBatch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/MeshletBatch.js"],"names":[],"mappings":"AA4DA;;GAEG;AACH;IAiBI;;;OAGG;IACH,oCAGC;IAXD,+BAEC;IA6BD;;;OAGG;IACH,wCAGC;IAfD;;;OAGG;IACH,mCAEC;IAuBD;;;OAGG;IACH,yBAEC;IAdD;;;OAGG;IACH,oBAEC;IAUD;;;OAGG;IACH,8BAEC;IAED;;;OAGG;IACH,QAFa,MAAM,CASlB;IAED;;;OAGG;IACH,cAFW,YAAY,WAQtB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAiHlB;IAED;;;OAGG;IACH,iBAEC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACL,EAAE,CAeb;IAED;;;OAGG;IACH,yBAFW,MAAM;;;;MAgChB;IAiMD,qBA+BC;IAED;;;OAGG;IACH,gBAFW,QAAQ,QASlB;IAIL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;uBA7iBY,OAAO,gBAAgB,EAAE,QAAQ"}
+{"version":3,"file":"MeshletBatch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/MeshletBatch.js"],"names":[],"mappings":"AA4DA;;GAEG;AACH;IAiBI;;;OAGG;IACH,oCAGC;IAXD,+BAEC;IA6BD;;;OAGG;IACH,wCAGC;IAfD;;;OAGG;IACH,mCAEC;IAuBD;;;OAGG;IACH,yBAEC;IAdD;;;OAGG;IACH,oBAEC;IAUD;;;OAGG;IACH,8BAEC;IAED;;;OAGG;IACH,QAFa,MAAM,CASlB;IAED;;;OAGG;IACH,cAFW,YAAY,WAQtB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAiHlB;IAED;;;OAGG;IACH,iBAEC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACL,EAAE,CAeb;IAED;;;OAGG;IACH,yBAFW,MAAM;;;;MAgChB;IAED;;;;;;;;;;OAUG;IACH,8BAHW,MAAM,SACN,UAAU,GAAC,MAAM,EAAE,QA0B7B;IAiMD,qBA+BC;IAED;;;OAGG;IACH,gBAFW,QAAQ,QASlB;IAIL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;uBAllBY,OAAO,gBAAgB,EAAE,QAAQ"}

package/src/shade/renderer/geometry/meshlet/MeshletBatch.js

@@ -349,6 +349,43 @@ export class MeshletBatch {
         }
     }
 
+    /**
+     * Re-order the triangles of one meshlet: triangle `i` becomes the triangle that was at `order[i]`.
+     *
+     * Only the meshlet's index section is rewritten, in place. Vertices, attributes, bounds and the
+     * meshlet's address are untouched, so the meshlet draws exactly what it drew before; what changes is
+     * which triangle a `(meshlet, triangle)` id names. Anything that recorded such an id beforehand —
+     * a BLAS leaf, most of all — names a different triangle afterwards.
+     *
+     * @param {number} meshlet_id
+     * @param {Uint8Array|number[]} order a permutation of `0 .. primitive_count - 1`
+     */
+    reorder_triangles(meshlet_id, order) {
+        assert.isNonNegativeInteger(meshlet_id, 'meshlet_id');
+        assert.lessThan(meshlet_id, this.#count, 'index overflow');
+
+        const header = this.read_header(meshlet_id);
+
+        const primitive_count = header.primitive_count;
+
+        assert.greaterThanOrEqual(order.length, primitive_count, 'order is too short');
+
+        const bytes = new Uint8Array(this.#data, header.address << 2, primitive_count * 3);
+
+        const original = bytes.slice();
+
+        for (let i = 0; i < primitive_count; i++) {
+            const source = order[i] * 3;
+            const target = i * 3;
+
+            assert.lessThan(order[i], primitive_count, 'order names a triangle the meshlet does not have');
+
+            bytes[target] = original[source];
+            bytes[target + 1] = original[source + 1];
+            bytes[target + 2] = original[source + 2];
+        }
+    }
+
     /**
      *
      * @param {Geometry} geometry

package/src/shade/renderer/geometry/sdf/bake/shader_mesh_sdf_classify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_mesh_sdf_classify.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/bake/shader_mesh_sdf_classify.js"],"names":[],"mappings":"AAyCA;;;;;GAKG;AACH,mDAFW,OAAO,2DAA2D,EAAE,6BAA6B,QAS3G;AA/BD;;GAEG;AACH,yCAFU,YAAY,CAeQ;AA6B9B;;;;;;;;;;;;;;;GAeG;AACH,uCAFU,aAAa,CAsDpB;6BA/H0B,sCAAsC;8BAJrC,kCAAkC"}
+{"version":3,"file":"shader_mesh_sdf_classify.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/bake/shader_mesh_sdf_classify.js"],"names":[],"mappings":"AAyCA;;;;;GAKG;AACH,mDAFW,OAAO,2DAA2D,EAAE,6BAA6B,QAS3G;AA/BD;;GAEG;AACH,yCAFU,YAAY,CAeQ;AA6B9B;;;;;;;;;;;;;;;GAeG;AACH,uCAFU,aAAa,CAsDpB;6BAjI0B,sCAAsC;8BAJrC,kCAAkC"}

package/src/shade/renderer/geometry/sdf/bake/shader_mesh_sdf_classify.js

@@ -1,6 +1,4 @@
 import { UINT32_MAX } from "../../../../../core/binary/UINT32_MAX.js";
-import { BVH2_NODE_STRUCT } from "../../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
-import { BVH_TRAVERSAL_STACK_SIZE } from "../../../shader/chunk/bvh/BVH_TRAVERSAL_STACK_SIZE.js";
 import { chunk_point_query_blas_nearest } from "../../../shader/chunk/sdf/chunk_point_query_blas_nearest.js";
 import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
 import { ComputeShader } from "../../../shader/ComputeShader.js";
@@ -20,6 +18,8 @@ import {
     MESH_SDF_RANGES_RESOURCE
 } from "./chunk_mesh_sdf_bake.js";
 import { MESH_SDF_BAKE_WORKGROUP_SIZE } from "./MESH_SDF_BAKE.js";
+import { BVH8_INODE_STRUCT } from "../../../shader/chunk/bvh/bvh8/webgpu/BVH8_INODE_STRUCT.js";
+import { BVH8_TRAVERSAL_STACK_SIZE } from "../../../shader/chunk/bvh/bvh8/webgpu/BVH8_MAX_DEPTH.js";
 
 /**
  * @type {WebGPUStruct}
@@ -48,7 +48,7 @@ export const MESH_SDF_CLASSIFY_SETTINGS = WebGPUStruct.from({
 export function mesh_sdf_add_blas_resources(group) {
     group
         .addStorageBuffer("blas_lookup", WebGPUArray.u32)
-        .addStorageBuffer("blas_data", WebGPUArray.from(BVH2_NODE_STRUCT))
+        .addStorageBuffer("blas_data", WebGPUArray.from(BVH8_INODE_STRUCT))
         .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
         .add(MESHLET_METADATA_RESOURCE)
         .add(GEOMETRY_ATTRIBUTE_DATA_RESOURCE);
@@ -113,7 +113,7 @@ fn main(
     let centre = mesh_sdf_brick_corner(header, brick) + vec3<f32>(0.5 * f32(MESH_SDF_BRICK_VOXELS) * voxel);
     let reach = (MESH_SDF_BAND_VOXELS + MESH_SDF_BRICK_HALF_DIAGONAL) * voxel;
 
-    var stack: array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>;
+    var stack: array<vec2u, ${BVH8_TRAVERSAL_STACK_SIZE}>;
 
     let nearest = point_query_blas_nearest(centre, reach, geometry, &stack, 0u);
 

package/src/shade/renderer/geometry/sdf/bake/shader_mesh_sdf_evaluate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_mesh_sdf_evaluate.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/bake/shader_mesh_sdf_evaluate.js"],"names":[],"mappings":"AAcA;;GAEG;AACH,yCAFU,YAAY,CAWQ;AAe9B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,uCAFU,aAAa,CAoFpB;6BA3I0B,sCAAsC;8BAJrC,kCAAkC"}
+{"version":3,"file":"shader_mesh_sdf_evaluate.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/bake/shader_mesh_sdf_evaluate.js"],"names":[],"mappings":"AAcA;;GAEG;AACH,yCAFU,YAAY,CAWQ;AAe9B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,uCAFU,aAAa,CAoFpB;6BA5I0B,sCAAsC;8BAJrC,kCAAkC"}

package/src/shade/renderer/geometry/sdf/bake/shader_mesh_sdf_evaluate.js

@@ -1,4 +1,3 @@
-import { BVH_TRAVERSAL_STACK_SIZE } from "../../../shader/chunk/bvh/BVH_TRAVERSAL_STACK_SIZE.js";
 import { SURFACE_POINT_3D } from "../../../shader/chunk/sdf/SURFACE_POINT_3D.js";
 import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
 import { ComputeShader } from "../../../shader/ComputeShader.js";
@@ -11,6 +10,7 @@ import { MESH_SDF_HEADERS_RESOURCE } from "../MESH_SDF_RESOURCES.js";
 import { chunk_mesh_sdf_bake, chunk_mesh_sdf_bake_settle, MESH_SDF_ARENA_RESOURCE } from "./chunk_mesh_sdf_bake.js";
 import { MESH_SDF_BAKE_WORKGROUP_SIZE } from "./MESH_SDF_BAKE.js";
 import { mesh_sdf_add_blas_resources } from "./shader_mesh_sdf_classify.js";
+import { BVH8_TRAVERSAL_STACK_SIZE } from "../../../shader/chunk/bvh/bvh8/webgpu/BVH8_MAX_DEPTH.js";
 
 /**
  * @type {WebGPUStruct}
@@ -93,7 +93,7 @@ fn main(
     let texel = (workgroup_id.x % MESH_SDF_GROUPS_PER_BRICK) * MESH_SDF_BAKE_WORKGROUP_SIZE + lane;
     let point = mesh_sdf_brick_corner(header, brick) + vec3<f32>(vec3<u32>(texel % t, (texel / t) % t, texel / (t * t))) * voxel;
 
-    var stack: array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>;
+    var stack: array<vec2u, ${BVH8_TRAVERSAL_STACK_SIZE}>;
     var contact: ${SURFACE_POINT_3D.wgsl_ref};
 
     let band = MESH_SDF_BAND_VOXELS * voxel;

package/src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_blas_query_band_sdf.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.js"],"names":[],"mappings":"AAgBA;;;;GAIG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,kCAFU,MAAM,CAEqE;AAErF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wCAFU,SAAS,CAgHjB;0BAjJwB,oCAAoC"}
+{"version":3,"file":"chunk_blas_query_band_sdf.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.js"],"names":[],"mappings":"AAgBA;;;;GAIG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,kCAFU,MAAM,CAEqE;AAErF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wCAFU,SAAS,CAgHjB;0BAlJwB,oCAAoC"}

package/src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.js

@@ -1,5 +1,4 @@
 import { UINT32_MAX } from "../../../../core/binary/UINT32_MAX.js";
-import { BVH_TRAVERSAL_STACK_SIZE } from "../../shader/chunk/bvh/BVH_TRAVERSAL_STACK_SIZE.js";
 import {
     chunk_geometry_read_triangle_vertices
 } from "../../shader/chunk/geometry/format/chunk_geometry_read_triangle_vertices.js";
@@ -13,6 +12,7 @@ import { PI_DECLARATION } from "../../shader/chunk/math/PI_DECLARATION.js";
 import { chunk_point_query_blas_nearest } from "../../shader/chunk/sdf/chunk_point_query_blas_nearest.js";
 import { SURFACE_POINT_3D } from "../../shader/chunk/sdf/SURFACE_POINT_3D.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { BVH8_TRAVERSAL_STACK_SIZE } from "../../shader/chunk/bvh/bvh8/webgpu/BVH8_MAX_DEPTH.js";
 
 /**
  * Strata along a side of each of the vote's two hemispheres, as UE 5.4 has them: 7 × 7 directions a
@@ -101,7 +101,7 @@ fn blas_query_band_sdf(
     band: f32,
     two_sided: bool,
     contact: ptr<function, ${SURFACE_POINT_3D.wgsl_ref}>,
-    traversal_stack: ptr<function, array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>>,
+    traversal_stack: ptr<function, array<vec2u, ${BVH8_TRAVERSAL_STACK_SIZE}>>,
     stack_top: u32
 ) -> f32 {
     *contact = point_query_blas_nearest(point, band, geometry_index, traversal_stack, stack_top);

package/src/shade/renderer/geometry/sdf/shader_sdf_visualize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_sdf_visualize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/shader_sdf_visualize.js"],"names":[],"mappings":"AAqKA;;;;;;;;;;;GAWG;AACH;IAT+B,KAAK;IACD,IAAI;IACZ,WAAW,EAA3B,MAAM;IACU,SAAS,EAAzB,MAAM;IACU,gBAAgB,EAAhC,MAAM;IACU,sBAAsB,EAAtC,MAAM;IAEJ,MAAM,CAsGlB;AA3HD,+CASG;4BAvIyB,6BAA6B"}
+{"version":3,"file":"shader_sdf_visualize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/shader_sdf_visualize.js"],"names":[],"mappings":"AAqKA;;;;;;;;;;;GAWG;AACH;IAT+B,KAAK;IACD,IAAI;IACZ,WAAW,EAA3B,MAAM;IACU,SAAS,EAAzB,MAAM;IACU,gBAAgB,EAAhC,MAAM;IACU,sBAAsB,EAAtC,MAAM;IAEJ,MAAM,CAsGlB;AA3HD,+CASG;4BAxIyB,6BAA6B"}

package/src/shade/renderer/geometry/sdf/shader_sdf_visualize.js

@@ -11,8 +11,7 @@ import {
 } from "./MESH_SDF_RESOURCES.js";
 import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
 import { DEPTH_BACKGROUND_VALUE } from "../../depth/DEPTH_BACKGROUND_VALUE.js";
-import { BVH2_NODE_STRUCT } from "../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
-import { BVH_STRUCT } from "../../shader/chunk/bvh/BVH_STRUCT.js";
+import { BVH8_TREE_TYPE } from "../../shader/chunk/bvh/bvh8/webgpu/chunk_bvh8_tree_read.js";
 import { chunk_project_position_from_depth } from "../../shader/chunk/camera/chunk_project_position_from_depth.js";
 import { chunk_hash_u32_to_v4f32 } from "../../shader/chunk/color/chunk_hash_u32_to_v4f32.js";
 import {
@@ -34,6 +33,7 @@ import { chunk_ray_query_sdf_raycast } from "../../shadow/sdf/chunk_ray_query_sd
 import { SDF_DRAW_SETTINGS_STRUCT } from "../../shadow/sdf/SDF_DRAW_SETTINGS_STRUCT.js";
 import { GEOMETRY_METADATA_STRUCT } from "../GEOMETRY_METADATA_STRUCT.js";
 import { dynamic_chunk_sdf_construct_normal } from "./dynamic_chunk_sdf_construct_normal.js";
+import { BVH8_INODE_STRUCT } from "../../shader/chunk/bvh/bvh8/webgpu/BVH8_INODE_STRUCT.js";
 
 const resources = new ShaderResourceSetDescriptor();
 
@@ -53,12 +53,12 @@ resources.createGroup()
 resources.createGroup()
     .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
     .addStorageBuffer("scene_database", WebGPUArray.from(u32))
-    .addStorageBuffer("tlas", BVH_STRUCT);
+    .addStorageBuffer("tlas", BVH8_TREE_TYPE);
 
 // debug
 resources.createGroup()
     .addStorageBuffer("blas_lookup", WebGPUArray.u32)
-    .addStorageBuffer("blas_data", WebGPUArray.from(BVH2_NODE_STRUCT))
+    .addStorageBuffer("blas_data", WebGPUArray.from(BVH8_INODE_STRUCT))
 
 resources.createGroup()
     .addUniform("camera", CAMERA_UNIFORM_STRUCT);