@woosh/meep-engine 3.2.0 → 3.4.0

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

@@ -0,0 +1,260 @@
+import {
+    BVH_NODE_BOUNDS_WORD,
+    BVH_NODE_CHILD_1_WORD,
+    BVH_NODE_CHILD_2_WORD,
+    BVH_NODE_STRIDE_WORDS
+} from "../../gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+
+/**
+ * The two things that make a fitted tree usable, checked against the bytes rather than the picture.
+ *
+ * A ray descends into a node only if it hits that node's box, so a box that fails to cover what is
+ * underneath it is a hole: rays are turned away at the top and the geometry below is simply absent
+ * from the traced image. Both properties below are exactly that statement, at the two levels it can
+ * be broken at.
+ *
+ * - **A leaf covers its triangle.** The box has to contain the three vertices the ray query will go
+ *   on to intersect. Fail this and the leaf is entered from some directions and not others, which
+ *   looks like geometry that appears and disappears as the camera moves.
+ * - **A parent covers its children.** Fail this and an entire subtree is unreachable from the
+ *   directions the parent's box excludes.
+ *
+ * Neither needs an image, a camera, a light, or a human to look at anything. They are properties of
+ * the buffer, they hold or they do not, and they are cheap enough to assert on every tree a test
+ * produces.
+ *
+ * @type {number}
+ */
+const BVH_NULL_NODE = 0xffffffff;
+
+/**
+ * Read a node's `[min.xyz, max.xyz]`.
+ *
+ * @param {Float32Array} floats
+ * @param {number} node
+ * @returns {number[]}
+ */
+function node_bounds(floats, node) {
+    const base = node * BVH_NODE_STRIDE_WORDS + BVH_NODE_BOUNDS_WORD;
+
+    return [
+        floats[base], floats[base + 1], floats[base + 2],
+        floats[base + 3], floats[base + 4], floats[base + 5],
+    ];
+}
+
+/**
+ * Is `inner` inside `outer`, allowing `slack` of overshoot per axis?
+ *
+ * @param {number[]} inner
+ * @param {number[]} outer
+ * @param {number} slack
+ * @returns {boolean}
+ */
+function contains(inner, outer, slack) {
+    for (let axis = 0; axis < 3; axis++) {
+        if (inner[axis] < outer[axis] - slack || inner[axis + 3] > outer[axis + 3] + slack) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Scale for `slack`, so a tolerance means the same thing whatever units the asset is in.
+ *
+ * @param {number[]} box
+ * @returns {number}
+ */
+function box_scale(box) {
+    return Math.max(
+        1,
+        Math.abs(box[0]), Math.abs(box[1]), Math.abs(box[2]),
+        Math.abs(box[3]), Math.abs(box[4]), Math.abs(box[5])
+    );
+}
+
+/**
+ * Does every node's box contain its children's, walking from the root?
+ *
+ * Containment rather than equality, because the two are different claims and only one of them is
+ * required for correctness. A refit that computes each node as the exact union of its children
+ * satisfies both; a builder that inflates boxes, or a refit that ran a frame before the leaves under
+ * it moved inward, satisfies containment alone and is still a tree rays can traverse. Equality is
+ * available as `tight` for callers who want to assert the stronger thing.
+ *
+ * Walks the tree rather than scanning the buffer: the arena holds `node_capacity` slots and the
+ * builder allocates from a free list, so slots the tree never reaches hold whatever their last
+ * occupant left and are not anybody's problem.
+ *
+ * @param {ArrayBuffer|Float32Array} nodes the tree's node region
+ * @param {object} [options]
+ * @param {number} [options.slack] fraction of the box's own magnitude a child may overshoot by
+ * @returns {{problems: string[], internal: number, leaves: number, tight: boolean}}
+ */
+export function bvh2_check_containment(nodes, { slack = 1e-6 } = {}) {
+    const floats = nodes instanceof Float32Array ? nodes : new Float32Array(nodes);
+    const words = new Uint32Array(floats.buffer, floats.byteOffset, floats.length);
+
+    const node_count = Math.floor(floats.length / BVH_NODE_STRIDE_WORDS);
+
+    const problems = [];
+
+    let internal = 0;
+    let leaves = 0;
+    let tight = true;
+
+    const stack = [0];
+
+    const seen = new Uint8Array(node_count);
+
+    while (stack.length > 0 && problems.length < 16) {
+        const node = stack.pop();
+
+        if (node >= node_count) {
+            problems.push(`node ${node} is past the ${node_count} slots this region holds`);
+
+            continue;
+        }
+
+        if (seen[node] === 1) {
+            problems.push(`node ${node} is reachable twice — a shared node, not a tree`);
+
+            continue;
+        }
+
+        seen[node] = 1;
+
+        const base = node * BVH_NODE_STRIDE_WORDS;
+
+        if (words[base + BVH_NODE_CHILD_1_WORD] === BVH_NULL_NODE) {
+            leaves += 1;
+
+            continue;
+        }
+
+        internal += 1;
+
+        const mine = node_bounds(floats, node);
+
+        const tolerance = box_scale(mine) * slack;
+
+        const children = [
+            words[base + BVH_NODE_CHILD_1_WORD],
+            words[base + BVH_NODE_CHILD_2_WORD],
+        ];
+
+        const union = [Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity];
+
+        for (const child of children) {
+            if (child >= node_count) {
+                problems.push(`node ${node} names child ${child}, past the ${node_count} slots`);
+
+                continue;
+            }
+
+            const box = node_bounds(floats, child);
+
+            if (!contains(box, mine, tolerance)) {
+                problems.push(
+                    `node ${node} does not contain its child ${child}: `
+                    + `[${box}] escapes [${mine}]`
+                );
+            }
+
+            for (let axis = 0; axis < 3; axis++) {
+                union[axis] = Math.min(union[axis], box[axis]);
+                union[axis + 3] = Math.max(union[axis + 3], box[axis + 3]);
+            }
+
+            stack.push(child);
+        }
+
+        for (let k = 0; k < 6; k++) {
+            if (Math.abs(union[k] - mine[k]) > tolerance) {
+                tight = false;
+            }
+        }
+    }
+
+    return { problems, internal, leaves, tight };
+}
+
+/**
+ * Does every leaf's box contain the triangle that leaf names?
+ *
+ * `triangle_bounds` is asked for the AABB of the three vertices behind a leaf's payload — the same
+ * payload the ray query decodes, so a caller supplies whatever reads vertices in its world and this
+ * stays out of the meshlet layout entirely.
+ *
+ * Returning `null` means "no triangle for this payload", which is itself a failure: a leaf naming a
+ * triangle nobody can find is a leaf a ray descends into for nothing.
+ *
+ * @param {ArrayBuffer|Float32Array} nodes
+ * @param {function(number, number): (number[]|null)} triangle_bounds `(payload, leaf_node)` to
+ * `[min.xyz, max.xyz]`
+ * @param {object} [options]
+ * @param {number} [options.slack]
+ * @returns {{problems: string[], leaves: number, tight: boolean}}
+ */
+export function bvh2_check_leaf_bounds(nodes, triangle_bounds, { slack = 1e-6 } = {}) {
+    const floats = nodes instanceof Float32Array ? nodes : new Float32Array(nodes);
+    const words = new Uint32Array(floats.buffer, floats.byteOffset, floats.length);
+
+    const node_count = Math.floor(floats.length / BVH_NODE_STRIDE_WORDS);
+
+    const problems = [];
+
+    let leaves = 0;
+    let tight = true;
+
+    const stack = [0];
+
+    while (stack.length > 0 && problems.length < 16) {
+        const node = stack.pop();
+
+        if (node >= node_count) {
+            continue;
+        }
+
+        const base = node * BVH_NODE_STRIDE_WORDS;
+
+        if (words[base + BVH_NODE_CHILD_1_WORD] !== BVH_NULL_NODE) {
+            stack.push(words[base + BVH_NODE_CHILD_1_WORD], words[base + BVH_NODE_CHILD_2_WORD]);
+
+            continue;
+        }
+
+        leaves += 1;
+
+        const payload = words[base + BVH_NODE_CHILD_2_WORD];
+
+        const triangle = triangle_bounds(payload, node);
+
+        if (triangle === null) {
+            problems.push(`leaf ${node} names payload ${payload}, which resolves to no triangle`);
+
+            continue;
+        }
+
+        const mine = node_bounds(floats, node);
+
+        const tolerance = box_scale(mine) * slack;
+
+        if (!contains(triangle, mine, tolerance)) {
+            problems.push(
+                `leaf ${node} does not cover its own triangle ${payload}: `
+                + `[${triangle}] escapes [${mine}]`
+            );
+        }
+
+        for (let k = 0; k < 6; k++) {
+            if (Math.abs(triangle[k] - mine[k]) > tolerance) {
+                tight = false;
+            }
+        }
+    }
+
+    return { problems, leaves, tight };
+}

package/src/shade/renderer/geometry/bvh/bvh2_derive_topology.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The two things a refit needs to know about a tree it did not build: who each node's parent is, and
+ * which nodes are the leaves.
+ *
+ * Read straight off the compressed node bytes — the same bytes that go to the GPU — rather than off
+ * the `BVH` object they came from. That is deliberate: the arena holds `node_capacity` slots and a
+ * `BVH` allocates from a free list, so the buffer contains holes that were never part of any tree
+ * and whose child words are whatever the last occupant left. Walking from the root visits exactly
+ * the tree, so a hole is never mistaken for a leaf and never gets a parent.
+ *
+ * Topology, not geometry. Every per-instance copy of a geometry has the same answer, so this is
+ * derived once per source and shared — only bounds are per-instance.
+ *
+ * @param {ArrayBuffer} nodes compressed BVH2 nodes, 32 bytes each, root at node 0
+ * @returns {{parents: Uint32Array, leaf_nodes: Uint32Array}} `parents` is indexed by node and holds
+ * `BVH_NULL_NODE` for the root and for every slot the tree does not reach; `leaf_nodes` lists the
+ * leaves in pre-order, which is the ordinal the refit dispatches one thread per.
+ */
+export function bvh2_derive_topology(nodes: ArrayBuffer): {
+    parents: Uint32Array;
+    leaf_nodes: Uint32Array;
+};
+//# sourceMappingURL=bvh2_derive_topology.d.ts.map

package/src/shade/renderer/geometry/bvh/bvh2_derive_topology.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bvh2_derive_topology.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/bvh2_derive_topology.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;GAiBG;AACH,4CALW,WAAW;aACC,WAAW;gBAAc,WAAW;EAuD1D"}

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

@@ -0,0 +1,82 @@
+import { assert } from "../../../../core/assert.js";
+import {
+    BVH_NODE_CHILD_1_WORD,
+    BVH_NODE_CHILD_2_WORD,
+    BVH_NODE_STRIDE_WORDS
+} from "../../gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+
+/**
+ * @type {number}
+ */
+const BVH_NULL_NODE = 0xffffffff;
+
+/**
+ * The two things a refit needs to know about a tree it did not build: who each node's parent is, and
+ * which nodes are the leaves.
+ *
+ * Read straight off the compressed node bytes — the same bytes that go to the GPU — rather than off
+ * the `BVH` object they came from. That is deliberate: the arena holds `node_capacity` slots and a
+ * `BVH` allocates from a free list, so the buffer contains holes that were never part of any tree
+ * and whose child words are whatever the last occupant left. Walking from the root visits exactly
+ * the tree, so a hole is never mistaken for a leaf and never gets a parent.
+ *
+ * Topology, not geometry. Every per-instance copy of a geometry has the same answer, so this is
+ * derived once per source and shared — only bounds are per-instance.
+ *
+ * @param {ArrayBuffer} nodes compressed BVH2 nodes, 32 bytes each, root at node 0
+ * @returns {{parents: Uint32Array, leaf_nodes: Uint32Array}} `parents` is indexed by node and holds
+ * `BVH_NULL_NODE` for the root and for every slot the tree does not reach; `leaf_nodes` lists the
+ * leaves in pre-order, which is the ordinal the refit dispatches one thread per.
+ */
+export function bvh2_derive_topology(nodes) {
+    assert.defined(nodes, 'nodes');
+
+    const words = new Uint32Array(nodes);
+
+    const node_count = Math.floor(words.length / BVH_NODE_STRIDE_WORDS);
+
+    assert.greaterThan(node_count, 0, 'node_count');
+
+    const parents = new Uint32Array(node_count).fill(BVH_NULL_NODE);
+
+    const leaf_nodes = [];
+
+    const stack = [0];
+
+    let visited = 0;
+
+    while (stack.length > 0) {
+        const node = stack.pop();
+
+        visited += 1;
+
+        assert.lessThanOrEqual(visited, node_count, 'walk visited more nodes than the buffer holds — the tree is not a tree');
+
+        const base = node * BVH_NODE_STRIDE_WORDS;
+
+        const child_1 = words[base + BVH_NODE_CHILD_1_WORD];
+
+        if (child_1 === BVH_NULL_NODE) {
+            leaf_nodes.push(node);
+
+            continue;
+        }
+
+        const child_2 = words[base + BVH_NODE_CHILD_2_WORD];
+
+        assert.lessThan(child_1, node_count, 'child_1 out of range');
+        assert.lessThan(child_2, node_count, 'child_2 out of range');
+
+        parents[child_1] = node;
+        parents[child_2] = node;
+
+        // child_1 first out, so the leaf order is a pre-order walk rather than an artefact of
+        // which way the stack happens to run
+        stack.push(child_2, child_1);
+    }
+
+    return {
+        parents,
+        leaf_nodes: Uint32Array.from(leaf_nodes),
+    };
+}

package/src/shade/renderer/geometry/bvh/record_blas_refit.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bring a BLAS's bounds back in line with vertices that have moved, leaving its shape alone.
+ *
+ * Two dispatches. The first rewrites every leaf's box from the triangle it names, as the vertex
+ * buffer holds it now; the second carries those boxes up the tree. Nothing is sorted, nothing is
+ * emitted, and no node's children change — which is the entire reason this is worth having next to
+ * a full build. A skinned mesh does it every frame.
+ *
+ * The caller supplies the *owner* rather than a tree, and this asks the manager where that owner's
+ * tree lives. Nothing here knows what a clone is, or that skinning is why the vertices moved.
+ *
+ * Silently does nothing when the owner has no resident tree — a geometry can reach a frame before
+ * its BLAS has been uploaded, and "there is nothing to refit yet" is an ordinary state rather than
+ * a failure.
+ *
+ * @param {ShadeGPUCommandContext} cmd
+ * @param {GPUGeometryBVHManager} blas tree residency — arenas for nodes, parents and leaf lists
+ * @param {GPUGeometryManager} geometries geometry metadata table the leaf pass reads vertices through
+ * @param {object} owner identity the tree was registered under, per {@link GPUGeometryBVHManager#obtain}
+ * @param {number} geometry_index row in the geometry table whose vertices the bounds come from —
+ * for a skinned mesh, the clone that skinning deformed, not the source holding the rest pose
+ * @returns {boolean} whether anything was recorded
+ */
+export function record_blas_refit(cmd: ShadeGPUCommandContext, { blas, geometries, owner, geometry_index }: GPUGeometryBVHManager): boolean;
+//# sourceMappingURL=record_blas_refit.d.ts.map

package/src/shade/renderer/geometry/bvh/record_blas_refit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record_blas_refit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/record_blas_refit.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,oIAFa,OAAO,CA2EnB"}

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

@@ -0,0 +1,102 @@
+import { assert } from "../../../../core/assert.js";
+import { BVH_BUILD_SETTINGS_STRUCT, BVH_NO_ROOT_WORD } from "../../gpu_primitive/bvh/BVH_BUILD_SETTINGS_STRUCT.js";
+import { shader_bvh_refit } from "../../gpu_primitive/bvh/shader_bvh_refit.js";
+import { BLAS_LEAF_BOUNDS_SETTINGS_STRUCT, shader_blas_refit_leaf_bounds } from "./shader_blas_refit_leaf_bounds.js";
+
+/**
+ * Bring a BLAS's bounds back in line with vertices that have moved, leaving its shape alone.
+ *
+ * Two dispatches. The first rewrites every leaf's box from the triangle it names, as the vertex
+ * buffer holds it now; the second carries those boxes up the tree. Nothing is sorted, nothing is
+ * emitted, and no node's children change — which is the entire reason this is worth having next to
+ * a full build. A skinned mesh does it every frame.
+ *
+ * The caller supplies the *owner* rather than a tree, and this asks the manager where that owner's
+ * tree lives. Nothing here knows what a clone is, or that skinning is why the vertices moved.
+ *
+ * Silently does nothing when the owner has no resident tree — a geometry can reach a frame before
+ * its BLAS has been uploaded, and "there is nothing to refit yet" is an ordinary state rather than
+ * a failure.
+ *
+ * @param {ShadeGPUCommandContext} cmd
+ * @param {GPUGeometryBVHManager} blas tree residency — arenas for nodes, parents and leaf lists
+ * @param {GPUGeometryManager} geometries geometry metadata table the leaf pass reads vertices through
+ * @param {object} owner identity the tree was registered under, per {@link GPUGeometryBVHManager#obtain}
+ * @param {number} geometry_index row in the geometry table whose vertices the bounds come from —
+ * for a skinned mesh, the clone that skinning deformed, not the source holding the rest pose
+ * @returns {boolean} whether anything was recorded
+ */
+export function record_blas_refit(cmd, { blas, geometries, owner, geometry_index }) {
+    assert.defined(cmd, 'cmd');
+    assert.defined(blas, 'blas');
+    assert.defined(geometries, 'geometries');
+    assert.defined(owner, 'owner');
+    assert.isNonNegativeInteger(geometry_index, 'geometry_index');
+
+    const target = blas.get_refit_target(owner);
+
+    if (target === undefined) {
+        return false;
+    }
+
+    const { node_word_offset, node_count, leaf_count, parents_offset, leaf_nodes_offset } = target;
+
+    if (leaf_count === 0) {
+        return false;
+    }
+
+    const meshlets = geometries.meshlets;
+
+    // ── 1. Leaf bounds: one thread per leaf, straight from the vertex buffer ──
+    shader_blas_refit_leaf_bounds.dispatchLinear({
+        encoder: cmd,
+        element_count: leaf_count,
+        bindings: {
+            settings: cmd.allocateTransientValueBuffer(BLAS_LEAF_BOUNDS_SETTINGS_STRUCT, {
+                leaf_count,
+                node_word_offset,
+                leaf_nodes_offset,
+                geometry_index,
+            }),
+            leaf_nodes: blas.buffer_leaf_nodes,
+            geometries: geometries.buffer_metadata,
+            meshlet_metadata: meshlets.buffer_metadata,
+            meshlet_data: meshlets.buffer_data,
+            nodes: blas.buffer_data,
+        },
+    });
+
+    // ── 2. Climb: arrival counters carry the new boxes to the root ──
+    //
+    // One counter per node of this tree, and every one of them has to start at zero: a leftover
+    // count lets a first arrival believe it is a second and fit a node from a sibling nothing has
+    // written yet. The transient allocator pools its buffers, so whatever comes back is carrying
+    // the last frame's counts and gets cleared. Sized by node rather than by leaf because the
+    // counters are indexed by node id, and a tree read off an arena has holes in that numbering.
+    const counters_size = Math.max(1, node_count) * Uint32Array.BYTES_PER_ELEMENT;
+
+    const counters = cmd.allocateTransientBuffer(GPUBufferUsage.STORAGE, counters_size);
+
+    cmd.clearBuffer(counters, 0, counters_size);
+
+    shader_bvh_refit.dispatchLinear({
+        encoder: cmd,
+        element_count: leaf_count,
+        bindings: {
+            settings: cmd.allocateTransientValueBuffer(BVH_BUILD_SETTINGS_STRUCT, {
+                element_count: leaf_count,
+                node_word_offset,
+                // a BLAS has no header — its root is node 0 by convention
+                root_word_offset: BVH_NO_ROOT_WORD,
+                parents_offset,
+                leaf_nodes_offset,
+            }),
+            parents: blas.buffer_parents,
+            leaf_nodes: blas.buffer_leaf_nodes,
+            counters,
+            nodes: blas.buffer_data,
+        },
+    });
+
+    return true;
+}

package/src/shade/renderer/geometry/bvh/shader_blas_refit_leaf_bounds.d.ts

@@ -0,0 +1,30 @@
+export const BLAS_LEAF_BOUNDS_WORKGROUP_SIZE: 64;
+/**
+ * Which tree, and where it lives.
+ *
+ * @type {WebGPUStruct}
+ */
+export const BLAS_LEAF_BOUNDS_SETTINGS_STRUCT: WebGPUStruct;
+/**
+ * Recompute a BLAS's leaf bounds from the geometry's current vertex positions.
+ *
+ * The first half of a refit-only update, and the only half that knows what a triangle is: one
+ * thread per leaf reads the triangle its node names, takes the AABB of that triangle as the vertex
+ * buffer holds it *now*, and writes it into the node. {@link shader_bvh_refit} then carries those
+ * bounds up the tree, unchanged from the TLAS build — topology is frozen, so there is nothing to
+ * emit and nothing to sort.
+ *
+ * For a skinned mesh this runs against the per-instance clone, after the skinning pass has deformed
+ * its vertex region. Reading the source instead would produce the rest pose, which is what a clone
+ * without its own BLAS gets today.
+ *
+ * Plain (non-atomic) node access, unlike the refit: every leaf is written by exactly one thread and
+ * read by nobody until the next dispatch, so there is no cross-workgroup communication here to
+ * discipline.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_blas_refit_leaf_bounds: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_blas_refit_leaf_bounds.d.ts.map

package/src/shade/renderer/geometry/bvh/shader_blas_refit_leaf_bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_blas_refit_leaf_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/shader_blas_refit_leaf_bounds.js"],"names":[],"mappings":"AAkBA,iDAAkD;AAElD;;;;GAIG;AACH,+CAFU,YAAY,CAqBO;AAqD7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,4CAFU,aAAa,CAOpB;6BAvH0B,mCAAmC;8BAElC,+BAA+B"}

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

@@ -0,0 +1,122 @@
+import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import {
+    BVH_NODE_BOUNDS_WORD,
+    BVH_NODE_CHILD_2_WORD,
+    BVH_NODE_STRIDE_WORDS
+} from "../../gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+import {
+    chunk_geometry_read_triangle_bounds
+} from "../../shader/chunk/geometry/format/chunk_geometry_read_triangle_bounds.js";
+import { GEOMETRY_METADATA_STRUCT } from "../GEOMETRY_METADATA_STRUCT.js";
+import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../GEOMETRY_ATTRIBUTE_DATA_TYPE.js";
+import { MESHLET_METADATA_STRUCT } from "../meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+
+export const BLAS_LEAF_BOUNDS_WORKGROUP_SIZE = 64;
+
+/**
+ * Which tree, and where it lives.
+ *
+ * @type {WebGPUStruct}
+ */
+export const BLAS_LEAF_BOUNDS_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. For a skinned mesh this is
+     * the per-instance clone, whose vertex region the skinning pass has already deformed — which is
+     * the entire point: the source's positions are the rest pose.
+     */
+    geometry_index: u32,
+}, "BlasLeafBoundsSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addUniform("settings", BLAS_LEAF_BOUNDS_SETTINGS_STRUCT)
+    // node index of each leaf ordinal, as tree construction published it
+    .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), false)
+    .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)
+    // the node arena, flat. Only leaf bounds are written, and a leaf is written by one thread.
+    .addStorageBuffer("nodes", WebGPUArray.from(f32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const NODE_STRIDE = ${BVH_NODE_STRIDE_WORDS}u;
+const NODE_BOUNDS = ${BVH_NODE_BOUNDS_WORD}u;
+const NODE_CHILD_2 = ${BVH_NODE_CHILD_2_WORD}u;
+
+@compute @workgroup_size(${BLAS_LEAF_BOUNDS_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let i = gid.x;
+
+    if (i >= settings.leaf_count) {
+        return;
+    }
+
+    let leaf_node = leaf_nodes[settings.leaf_nodes_offset + i];
+
+    let node_word = settings.node_word_offset + leaf_node * NODE_STRIDE;
+
+    // The leaf already says which triangle it holds — its payload is what the ray query hands to
+    // the triangle test. Reading it back means no side table has to agree with the tree about
+    // which leaf is which.
+    let meshlet_triangle_id = bitcast<u32>(nodes[node_word + NODE_CHILD_2]);
+
+    let bounds = geometry_read_triangle_bounds(
+        geometries[settings.geometry_index],
+        meshlet_triangle_id
+    );
+
+    nodes[node_word + NODE_BOUNDS] = bounds.min.x;
+    nodes[node_word + NODE_BOUNDS + 1u] = bounds.min.y;
+    nodes[node_word + NODE_BOUNDS + 2u] = bounds.min.z;
+    nodes[node_word + NODE_BOUNDS + 3u] = bounds.max.x;
+    nodes[node_word + NODE_BOUNDS + 4u] = bounds.max.y;
+    nodes[node_word + NODE_BOUNDS + 5u] = bounds.max.z;
+}
+`, [
+    chunk_geometry_read_triangle_bounds,
+]);
+
+/**
+ * Recompute a BLAS's leaf bounds from the geometry's current vertex positions.
+ *
+ * The first half of a refit-only update, and the only half that knows what a triangle is: one
+ * thread per leaf reads the triangle its node names, takes the AABB of that triangle as the vertex
+ * buffer holds it *now*, and writes it into the node. {@link shader_bvh_refit} then carries those
+ * bounds up the tree, unchanged from the TLAS build — topology is frozen, so there is nothing to
+ * emit and nothing to sort.
+ *
+ * For a skinned mesh this runs against the per-instance clone, after the skinning pass has deformed
+ * its vertex region. Reading the source instead would produce the rest pose, which is what a clone
+ * without its own BLAS gets today.
+ *
+ * Plain (non-atomic) node access, unlike the refit: every leaf is written by exactly one thread and
+ * read by nobody until the next dispatch, so there is no cross-workgroup communication here to
+ * discipline.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_blas_refit_leaf_bounds = ComputeShader.from({
+    label: "BLAS/RefitLeafBounds",
+    resources,
+    body,
+    group_size: [BLAS_LEAF_BOUNDS_WORKGROUP_SIZE, 1, 1],
+});

package/src/shade/renderer/global_illumination/brick4/cpu/brick4_empty_gpu_structure.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A valid brick4 structure that lights nothing.
+ *
+ * There is no way to *un-upload* a lightmap: {@link Brick4LightMap} owns one buffer and the shader
+ * reads it unconditionally whenever the renderer is in Brick4 mode. So "no lightmap" has to be said
+ * in the format itself, and this is what says it — a root brick with no children whose every probe
+ * is zero. RGBE9995 zero decodes to a zero DC term, and `sh3_uncompress` scales every higher band by
+ * that DC, so all nine coefficients come back at zero: black indirect light, everywhere.
+ *
+ * **Built by the real encoder rather than written out here.** The layout — metadata, then nodes,
+ * then the probe section, with probe pointers resolved to absolute word addresses — belongs to
+ * {@link brick4_to_gpu_structure}, and a second hand-rolled copy of it would be free to drift.
+ *
+ * **The bounds are a unit box, not the zero box a fresh `AABB3` carries.** A zero-size volume makes
+ * the shader's `(position - min) / size` divide by zero, and the NaN that comes out of it survives
+ * into the trilinear weights — where `probe * weight` is `0 * NaN`, which is NaN rather than the
+ * black this is for. Any non-degenerate box does; where it sits does not matter, because traversal
+ * stops at the root and every probe in it reads the same zero.
+ *
+ * @returns {ArrayBuffer}
+ */
+export function brick4_empty_gpu_structure(): ArrayBuffer;
+//# sourceMappingURL=brick4_empty_gpu_structure.d.ts.map