@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/shader/chunk/bvh/chunk_bvh_query_aabb_cooperative.js

@@ -0,0 +1,286 @@
+import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+import { chunk_sort_bitonic_comparator } from "../../../gpu_primitive/sort/chunk_sort_bitonic_comparator.js";
+import { BVH2_NODE_STRUCT } from "./BVH2_NODE_STRUCT.js";
+import { BVH_NULL_NODE_DEFINITION } from "./BVH_NULL_NODE_DEFINITION.js";
+import { chunk_bvh_query_aabb_frontier } from "./chunk_bvh_query_aabb_frontier.js";
+
+/**
+ * Every leaf of a BVH whose box overlaps one query box, found by a whole workgroup together and
+ * returned as payloads in ascending order.
+ *
+ * ## Why not a stack per thread
+ *
+ * The engine's traversals (`chunk_sdf_query_distance`, `chunk_ray_query_*`) walk a stack per
+ * thread with no cap on visits, which is right for one ray per thread and wrong for one box per
+ * workgroup: the box meets a subtree, not a path, and one thread walking it serially is the slowest
+ * thread of the dispatch. This expands the tree a **level at a time** instead, as the vgeo cut does
+ * its descent: every node on the current level is tested by its own invocation, the survivors'
+ * children are appended to the next level, overlapping leaves to the candidate list, and a barrier
+ * separates the levels. Per-invocation work is bounded by the depth of the tree, not by the size of
+ * the answer.
+ *
+ * ## The contract
+ *
+ * Call `bvh_query_aabb_cooperative(root, query, lane)` from every invocation of a workgroup of
+ * exactly `BVH_QUERY_AABB_WORKGROUP_SIZE` invocations, in uniform control flow, with `lane` the
+ * `local_invocation_index` and `root` and `query` the same in every invocation. `root` is the
+ * tree's root word (word 0 of `BVH_BUFFER_LAYOUT`), and `BVH_NULL_NODE` for an empty tree. `query`
+ * is `[min.xyz, max.xyz]`; touching counts as overlapping, as in `aabb3_intersects_aabb3`.
+ *
+ * It returns a `BVHQueryAABBResult` whose fields are workgroup-uniform, so they can bound the
+ * caller's loops. The payloads are `bvh_query_aabb_candidates[0, candidate_count)`, ascending, and
+ * visible to every invocation when the call returns. They stay there until the next query.
+ *
+ * The node layout is `BVH_BUFFER_LAYOUT`'s: a node is a leaf exactly when `child_1` is
+ * `BVH_NULL_NODE`, and then `child_2` is its payload.
+ *
+ * ## The seam: two functions the enclosing shader defines
+ *
+ * The chunk binds nothing. It reads the tree and filters leaves through two functions the shader
+ * that includes it must define, in the manner of the particle VM's `vm_reg_read` and
+ * `vm_reg_write`:
+ *
+ * - `fn bvh_query_aabb_node(index: u32) -> BVH2Node` returns node `index`, where `BVH2Node` is
+ *   `BVH2_NODE_STRUCT.wgsl_ref`. A tree bound as `BVH_STRUCT` answers with `tree.nodes[index]`; one
+ *   inside a word arena reads its eight words.
+ * - `fn bvh_query_aabb_accept_leaf(payload: u32, bounds: array<f32, 6>) -> bool` is asked about
+ *   every leaf that overlaps the box, before it takes a place on the list. A caller with nothing to
+ *   filter returns `true`. The fluid's resolution cull lives here: a leaf too small for the cascade
+ *   is refused before it can crowd out one that is not.
+ *
+ * ## Deterministic order
+ *
+ * Appends from different subgroups land in whatever order the hardware runs them, so the list is
+ * sorted by payload before it is returned: the bitonic network of `chunk_sort_bitonic_comparator`
+ * over the smallest power-of-two prefix that holds the candidates (`sort_bitonic_size`), padded
+ * with `0xffffffff`, one compare-exchange per invocation per stage. A payload that is a stable row index then makes "the lowest K" the same K every frame for
+ * the same overlaps, however the traversal was scheduled.
+ *
+ * ## Bounds, and what is counted
+ *
+ * Nothing is dropped silently. A level whose appends pass `BVH_QUERY_AABB_FRONTIER_CAPACITY`, and a
+ * list still holding nodes when `BVH_QUERY_AABB_LEVEL_BUDGET` levels have been expanded, add those
+ * nodes to `nodes_dropped`: subtrees never tested. A leaf that passes the filter when the candidate
+ * list is full adds to `candidates_dropped`. With both zero the candidates are every overlapping
+ * leaf the filter accepted; with either non-zero they are a subset, and the lowest K of them need
+ * not be the lowest K overall.
+ *
+ * Per invocation, at most `BVH_QUERY_AABB_LEVEL_BUDGET * BVH_QUERY_AABB_FRONTIER_ROUNDS` = 51 * 4 =
+ * 204 node reads and filter calls, then two padding writes and 28 compare-exchanges. A query that
+ * meets nothing costs one level: the root is read, misses, and the loop leaves.
+ *
+ * Workgroup memory: two lists of 256 node indices, 128 payloads and five words, 2580 bytes.
+ *
+ * ## Subgroups
+ *
+ * Appends are aggregated per subgroup: an exclusive add numbers the subgroup's appends, one elected
+ * invocation reserves them all with one workgroup `atomicAdd`, and a broadcast hands each
+ * invocation its base. Nothing assumes which invocations share a subgroup or that a subgroup's
+ * invocations are contiguous in `local_invocation_index`: a subgroup reserves a run of its own
+ * wherever it lands. Every subgroup operation is reached in uniform control flow; the loops' trip
+ * counts are literals, and the one early exit is on a value read back through
+ * `workgroupUniformLoad`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_query_aabb_cooperative = CodeChunk.from(
+    //language=WGSL
+    `
+struct BVHQueryAABBResult {
+    // payloads in bvh_query_aabb_candidates[0, candidate_count), ascending
+    candidate_count: u32,
+    // leaves the filter accepted that found the candidate list full
+    candidates_dropped: u32,
+    // nodes never tested: frontier overflow, and what was left when the level budget ran out
+    nodes_dropped: u32,
+}
+
+// two lists of node indices, alternating by level; bvh_query_aabb_list says which one a level reads
+var<workgroup> bvh_query_aabb_frontier: array<array<u32, BVH_QUERY_AABB_FRONTIER_CAPACITY>, 2>;
+// appends asked of each list; past the capacity they were counted but not stored
+var<workgroup> bvh_query_aabb_frontier_reserved: array<atomic<u32>, 2>;
+var<workgroup> bvh_query_aabb_candidates: array<u32, BVH_QUERY_AABB_CANDIDATE_CAPACITY>;
+var<workgroup> bvh_query_aabb_candidates_reserved: atomic<u32>;
+// written by invocation 0 only
+var<workgroup> bvh_query_aabb_nodes_dropped: u32;
+// what invocation 0 publishes, read back through workgroupUniformLoad
+var<workgroup> bvh_query_aabb_broadcast: u32;
+
+// This invocation's first slot of count appends to a frontier list, reserved for the whole
+// subgroup by one atomic.
+fn bvh_query_aabb_reserve_frontier(list: u32, count: u32) -> u32 {
+    let offset = subgroupExclusiveAdd(count);
+    let total = subgroupAdd(count);
+
+    // elected before the branch, which then holds no subgroup operation and may be non-uniform
+    let elected = subgroupElect();
+
+    var base = 0u;
+
+    if (elected && total > 0u) {
+        base = atomicAdd(&bvh_query_aabb_frontier_reserved[list], total);
+    }
+
+    return subgroupBroadcastFirst(base) + offset;
+}
+
+// The same, for the candidate list.
+fn bvh_query_aabb_reserve_candidates(count: u32) -> u32 {
+    let offset = subgroupExclusiveAdd(count);
+    let total = subgroupAdd(count);
+
+    let elected = subgroupElect();
+
+    var base = 0u;
+
+    if (elected && total > 0u) {
+        base = atomicAdd(&bvh_query_aabb_candidates_reserved, total);
+    }
+
+    return subgroupBroadcastFirst(base) + offset;
+}
+
+// Test this level's list: the children of overlapping internal nodes go on the next list, the
+// payloads of overlapping leaves the filter accepts on the candidate list.
+fn bvh_query_aabb_expand(list: u32, expand_count: u32, query: array<f32, 6>, lane: u32) {
+    let next = list ^ 1u;
+
+    for (var iteration = 0u; iteration < BVH_QUERY_AABB_FRONTIER_ROUNDS; iteration++) {
+        let slot = bvh_query_aabb_slot(iteration, lane);
+
+        var node: ${BVH2_NODE_STRUCT.wgsl_ref};
+        var kind = BVH_QUERY_AABB_SKIP;
+
+        if (slot < expand_count) {
+            node = bvh_query_aabb_node(bvh_query_aabb_frontier[list][slot]);
+
+            kind = bvh_query_aabb_classify(node.bounds, node.child_1, query);
+
+            if (kind == BVH_QUERY_AABB_LEAF && !bvh_query_aabb_accept_leaf(node.child_2, node.bounds)) {
+                kind = BVH_QUERY_AABB_SKIP;
+            }
+        }
+
+        // every invocation reserves, holding or not, so the subgroup operations stay uniform
+        let frontier_slot = bvh_query_aabb_reserve_frontier(next, select(0u, 2u, kind == BVH_QUERY_AABB_DESCEND));
+        let candidate_slot = bvh_query_aabb_reserve_candidates(select(0u, 1u, kind == BVH_QUERY_AABB_LEAF));
+
+        if (kind == BVH_QUERY_AABB_DESCEND) {
+            if (frontier_slot < BVH_QUERY_AABB_FRONTIER_CAPACITY) {
+                bvh_query_aabb_frontier[next][frontier_slot] = node.child_1;
+            }
+            if (frontier_slot + 1u < BVH_QUERY_AABB_FRONTIER_CAPACITY) {
+                bvh_query_aabb_frontier[next][frontier_slot + 1u] = node.child_2;
+            }
+        }
+
+        if (kind == BVH_QUERY_AABB_LEAF && candidate_slot < BVH_QUERY_AABB_CANDIDATE_CAPACITY) {
+            bvh_query_aabb_candidates[candidate_slot] = node.child_2;
+        }
+    }
+}
+
+// Order the first count candidates ascending, through the power-of-two prefix that holds them.
+fn bvh_query_aabb_sort(count: u32, lane: u32) {
+    let span = sort_bitonic_size(count);
+
+    // the prefix past the candidates sorts last
+    for (var iteration = 0u; iteration < BVH_QUERY_AABB_CANDIDATE_ROUNDS; iteration++) {
+        let slot = iteration * BVH_QUERY_AABB_WORKGROUP_SIZE + lane;
+
+        if (slot >= count && slot < span) {
+            bvh_query_aabb_candidates[slot] = 0xffffffffu;
+        }
+    }
+
+    // span is workgroup-uniform, so is every bound and exit below
+    for (var k = 2u; k <= BVH_QUERY_AABB_CANDIDATE_CAPACITY; k = k << 1u) {
+        if (k > span) {
+            break;
+        }
+
+        for (var j = k >> 1u; j > 0u; j = j >> 1u) {
+            workgroupBarrier();
+
+            // the smaller of the two belongs in pair.x
+            let pair = sort_bitonic_comparator(lane, k, j);
+
+            // a pair is wholly inside the prefix or wholly past it
+            if (max(pair.x, pair.y) < span) {
+                let a = bvh_query_aabb_candidates[pair.x];
+                let b = bvh_query_aabb_candidates[pair.y];
+
+                if (b < a) {
+                    bvh_query_aabb_candidates[pair.x] = b;
+                    bvh_query_aabb_candidates[pair.y] = a;
+                }
+            }
+        }
+    }
+}
+
+fn bvh_query_aabb_cooperative(root: u32, query: array<f32, 6>, lane: u32) -> BVHQueryAABBResult {
+    // whatever the workgroup did with a previous query's candidates is done before they are reset
+    workgroupBarrier();
+
+    if (lane == 0u) {
+        bvh_query_aabb_frontier[0][0] = root;
+        atomicStore(&bvh_query_aabb_frontier_reserved[0], select(1u, 0u, root == BVH_NULL_NODE));
+        atomicStore(&bvh_query_aabb_frontier_reserved[1], 0u);
+        atomicStore(&bvh_query_aabb_candidates_reserved, 0u);
+        bvh_query_aabb_nodes_dropped = 0u;
+    }
+
+    // one pass past the budget, to count what the last expanded level left on its list; that
+    // pass publishes nothing to expand, so the loop always leaves through the break
+    for (var level = 0u; level <= BVH_QUERY_AABB_LEVEL_BUDGET; level++) {
+        let list = bvh_query_aabb_list(level);
+
+        // every append to this level's list has landed
+        workgroupBarrier();
+
+        if (lane == 0u) {
+            let published = bvh_query_aabb_publish(atomicLoad(&bvh_query_aabb_frontier_reserved[list]), level);
+
+            bvh_query_aabb_broadcast = published.x;
+            bvh_query_aabb_nodes_dropped += published.y;
+
+            // the list this level appends to, read two levels ago and empty again
+            atomicStore(&bvh_query_aabb_frontier_reserved[list ^ 1u], 0u);
+        }
+
+        let expand_count = workgroupUniformLoad(&bvh_query_aabb_broadcast);
+
+        if (expand_count == 0u) {
+            break;
+        }
+
+        bvh_query_aabb_expand(list, expand_count, query, lane);
+    }
+
+    // every invocation has read the last broadcast before invocation 0 writes the next
+    workgroupBarrier();
+
+    if (lane == 0u) {
+        bvh_query_aabb_broadcast = atomicLoad(&bvh_query_aabb_candidates_reserved);
+    }
+
+    let reserved = workgroupUniformLoad(&bvh_query_aabb_broadcast);
+    let count = min(reserved, BVH_QUERY_AABB_CANDIDATE_CAPACITY);
+
+    bvh_query_aabb_sort(count, lane);
+
+    // also the barrier that makes the sorted list visible to every invocation
+    let nodes_dropped = workgroupUniformLoad(&bvh_query_aabb_nodes_dropped);
+
+    return BVHQueryAABBResult(count, reserved - count, nodes_dropped);
+}
+`, [
+    BVH2_NODE_STRUCT.declaration_chunk,
+    BVH_NULL_NODE_DEFINITION,
+    chunk_bvh_query_aabb_frontier,
+    chunk_sort_bitonic_comparator,
+]);
+
+chunk_bvh_query_aabb_cooperative.addExtension(WebGPUExtensionType.Subgroups);

package/src/shade/renderer/shader/chunk/bvh/chunk_bvh_query_aabb_frontier.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Invocations in a workgroup running {@link chunk_bvh_query_aabb_cooperative}: two subgroups on a
+ * 32-wide part, one on a 64-wide one. Small on purpose, because the caller dispatches one workgroup
+ * per query box and most boxes meet only a handful of leaves.
+ * @type {number}
+ */
+export const BVH_QUERY_AABB_WORKGROUP_SIZE: number;
+/**
+ * Nodes one level of the frontier holds. Both children of every overlapping internal node go on
+ * it, so it carries 128 overlapping internal nodes a level: as wide as the candidate list.
+ * @type {number}
+ */
+export const BVH_QUERY_AABB_FRONTIER_CAPACITY: number;
+/**
+ * Leaf payloads the query gathers. Twice the workgroup, so the sort is one compare-exchange per
+ * invocation per stage.
+ * @type {number}
+ */
+export const BVH_QUERY_AABB_CANDIDATE_CAPACITY: number;
+/**
+ * Levels of the frontier the query expands, depths 0 through 50.
+ *
+ * The deepest leaf of a Karras LBVH over at most 2^20 leaves is at depth 50. An internal node's
+ * split is the common-prefix length of its range, and a child's is strictly longer than its
+ * parent's, so a root-to-leaf path holds at most as many internal nodes as there are distinct
+ * prefix lengths: 2..31 for distinct 30-bit codes (30 values) and 32 + 12..31 for equal codes
+ * whose indices are below 2^20 (20 values). Fifty internal nodes, then the leaf.
+ *
+ * A deeper tree, which another builder may produce, is not walked past the budget; what is left
+ * on the frontier is counted in `nodes_dropped`.
+ * @type {number}
+ */
+export const BVH_QUERY_AABB_LEVEL_BUDGET: number;
+/**
+ * The pure parts of {@link chunk_bvh_query_aabb_cooperative}: its bounds, how a node is classified
+ * against the query box, and how a level's list is published.
+ * Everything here is per invocation and runs under the emulator; the cooperative chunk is the
+ * workgroup memory, the barriers and the subgroup appends around it.
+ *
+ * Per-invocation work is `BVH_QUERY_AABB_LEVEL_BUDGET * BVH_QUERY_AABB_FRONTIER_ROUNDS` = 51 * 4 =
+ * 204 node reads at most, then the candidate sort's 28 compare-exchanges.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_query_aabb_frontier: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bvh_query_aabb_frontier.d.ts.map

package/src/shade/renderer/shader/chunk/bvh/chunk_bvh_query_aabb_frontier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bvh_query_aabb_frontier.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/bvh/chunk_bvh_query_aabb_frontier.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,4CAFU,MAAM,CAEgC;AAEhD;;;;GAIG;AACH,+CAFU,MAAM,CAEoC;AAEpD;;;;GAIG;AACH,gDAFU,MAAM,CAEqC;AASrD;;;;;;;;;;;;GAYG;AACH,0CAFU,MAAM,CAE6C;AAW7D;;;;;;;;;;GAUG;AACH,4CAFU,SAAS,CAqDhB;0BAvHuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/bvh/chunk_bvh_query_aabb_frontier.js

@@ -0,0 +1,121 @@
+import { assert } from "../../../../../core/assert.js";
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+import { chunk_aabb3_intersects_aabb3 } from "../geometry/aabb3/chunk_aabb3_intersects_aabb3.js";
+import { BVH_NULL_NODE_DEFINITION } from "./BVH_NULL_NODE_DEFINITION.js";
+
+/**
+ * Invocations in a workgroup running {@link chunk_bvh_query_aabb_cooperative}: two subgroups on a
+ * 32-wide part, one on a 64-wide one. Small on purpose, because the caller dispatches one workgroup
+ * per query box and most boxes meet only a handful of leaves.
+ * @type {number}
+ */
+export const BVH_QUERY_AABB_WORKGROUP_SIZE = 64;
+
+/**
+ * Nodes one level of the frontier holds. Both children of every overlapping internal node go on
+ * it, so it carries 128 overlapping internal nodes a level: as wide as the candidate list.
+ * @type {number}
+ */
+export const BVH_QUERY_AABB_FRONTIER_CAPACITY = 256;
+
+/**
+ * Leaf payloads the query gathers. Twice the workgroup, so the sort is one compare-exchange per
+ * invocation per stage.
+ * @type {number}
+ */
+export const BVH_QUERY_AABB_CANDIDATE_CAPACITY = 128;
+
+/**
+ * Bits of an LBVH sort key: a 30-bit Morton code (`shader_bvh_morton`, ten bits per axis) and the
+ * leaf index that breaks ties between equal codes (`bvh_delta`), 20 bits for up to 2^20 leaves.
+ * @type {number}
+ */
+const LBVH_KEY_BITS = 30 + 20;
+
+/**
+ * Levels of the frontier the query expands, depths 0 through 50.
+ *
+ * The deepest leaf of a Karras LBVH over at most 2^20 leaves is at depth 50. An internal node's
+ * split is the common-prefix length of its range, and a child's is strictly longer than its
+ * parent's, so a root-to-leaf path holds at most as many internal nodes as there are distinct
+ * prefix lengths: 2..31 for distinct 30-bit codes (30 values) and 32 + 12..31 for equal codes
+ * whose indices are below 2^20 (20 values). Fifty internal nodes, then the leaf.
+ *
+ * A deeper tree, which another builder may produce, is not walked past the budget; what is left
+ * on the frontier is counted in `nodes_dropped`.
+ * @type {number}
+ */
+export const BVH_QUERY_AABB_LEVEL_BUDGET = LBVH_KEY_BITS + 1;
+
+assert.equal(
+    BVH_QUERY_AABB_FRONTIER_CAPACITY % BVH_QUERY_AABB_WORKGROUP_SIZE, 0,
+    'the frontier is expanded in whole rounds of the workgroup'
+);
+assert.equal(
+    BVH_QUERY_AABB_CANDIDATE_CAPACITY, 2 * BVH_QUERY_AABB_WORKGROUP_SIZE,
+    'the sort is one compare-exchange per invocation per stage'
+);
+
+/**
+ * The pure parts of {@link chunk_bvh_query_aabb_cooperative}: its bounds, how a node is classified
+ * against the query box, and how a level's list is published.
+ * Everything here is per invocation and runs under the emulator; the cooperative chunk is the
+ * workgroup memory, the barriers and the subgroup appends around it.
+ *
+ * Per-invocation work is `BVH_QUERY_AABB_LEVEL_BUDGET * BVH_QUERY_AABB_FRONTIER_ROUNDS` = 51 * 4 =
+ * 204 node reads at most, then the candidate sort's 28 compare-exchanges.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_query_aabb_frontier = CodeChunk.from(
+    //language=WGSL
+    `
+const BVH_QUERY_AABB_WORKGROUP_SIZE = ${BVH_QUERY_AABB_WORKGROUP_SIZE}u;
+const BVH_QUERY_AABB_FRONTIER_CAPACITY = ${BVH_QUERY_AABB_FRONTIER_CAPACITY}u;
+const BVH_QUERY_AABB_FRONTIER_ROUNDS = ${BVH_QUERY_AABB_FRONTIER_CAPACITY / BVH_QUERY_AABB_WORKGROUP_SIZE}u;
+const BVH_QUERY_AABB_CANDIDATE_CAPACITY = ${BVH_QUERY_AABB_CANDIDATE_CAPACITY}u;
+const BVH_QUERY_AABB_CANDIDATE_ROUNDS = ${BVH_QUERY_AABB_CANDIDATE_CAPACITY / BVH_QUERY_AABB_WORKGROUP_SIZE}u;
+const BVH_QUERY_AABB_LEVEL_BUDGET = ${BVH_QUERY_AABB_LEVEL_BUDGET}u;
+
+// what a node on the frontier turns into
+const BVH_QUERY_AABB_SKIP = 0u;
+const BVH_QUERY_AABB_DESCEND = 1u;
+const BVH_QUERY_AABB_LEAF = 2u;
+
+// A node against the query box: outside it, an internal node whose two children go on the next
+// level, or a leaf whose payload is a candidate. Touching counts as overlapping.
+fn bvh_query_aabb_classify(bounds: array<f32, 6>, child_1: u32, query: array<f32, 6>) -> u32 {
+    if (!aabb3_intersects_aabb3(bounds, query)) {
+        return BVH_QUERY_AABB_SKIP;
+    }
+
+    return select(BVH_QUERY_AABB_DESCEND, BVH_QUERY_AABB_LEAF, child_1 == BVH_NULL_NODE);
+}
+
+// The list a level reads. The level appends to the other one, so two lists alternate.
+fn bvh_query_aabb_list(level: u32) -> u32 {
+    return level & 1u;
+}
+
+// The list entry an invocation expands in one of a level's rounds; the rounds tile the list.
+fn bvh_query_aabb_slot(iteration: u32, lane: u32) -> u32 {
+    return iteration * BVH_QUERY_AABB_WORKGROUP_SIZE + lane;
+}
+
+// A level's list once every append to it has landed, from the appends it was asked for: x is
+// how many entries to expand, y how many nodes are dropped. Appends past the capacity were never
+// stored. At the budget nothing more is expanded, so the whole list is dropped.
+fn bvh_query_aabb_publish(reserved: u32, level: u32) -> vec2<u32> {
+    let kept = min(reserved, BVH_QUERY_AABB_FRONTIER_CAPACITY);
+
+    if (level >= BVH_QUERY_AABB_LEVEL_BUDGET) {
+        return vec2<u32>(0u, reserved);
+    }
+
+    return vec2<u32>(kept, reserved - kept);
+}
+
+`, [
+    BVH_NULL_NODE_DEFINITION,
+    chunk_aabb3_intersects_aabb3,
+]);

package/src/shade/renderer/shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Levels a clipmap table holds at most, and how far `clipmap_select_finest` walks.
+ * @type {number}
+ */
+export const CLIPMAP_LEVEL_LIMIT: number;
+/**
+ * One level of a clipmap as a shader reads it: the level's window, and how big its cell is. Levels
+ * sit finest first in a {@link CLIPMAP_LEVEL_ARRAY}.
+ *
+ * 32 bytes, so an array of them meets a uniform buffer's 16-byte stride.
+ *
+ * @type {WebGPUStruct}
+ */
+export const CLIPMAP_LEVEL_STRUCT: WebGPUStruct;
+/**
+ * A clipmap's table of levels, as a field of the uniform that carries it.
+ * @type {WebGPUArray}
+ */
+export const CLIPMAP_LEVEL_ARRAY: WebGPUArray;
+import { WebGPUStruct } from "../../type/WebGPUStruct.js";
+import { WebGPUArray } from "../../type/WebGPUArray.js";
+//# sourceMappingURL=CLIPMAP_LEVEL_STRUCT.d.ts.map

package/src/shade/renderer/shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CLIPMAP_LEVEL_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js"],"names":[],"mappings":"AAIA;;;GAGG;AACH,kCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH,mCAFU,YAAY,CAeH;AAEnB;;;GAGG;AACH,kCAFU,WAAW,CAE0E;6BAnClE,4BAA4B;4BAD7B,2BAA2B"}

package/src/shade/renderer/shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js

@@ -0,0 +1,38 @@
+import { f32, vec3i } from "../../type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../type/WebGPUArray.js";
+import { WebGPUStruct } from "../../type/WebGPUStruct.js";
+
+/**
+ * Levels a clipmap table holds at most, and how far `clipmap_select_finest` walks.
+ * @type {number}
+ */
+export const CLIPMAP_LEVEL_LIMIT = 16;
+
+/**
+ * One level of a clipmap as a shader reads it: the level's window, and how big its cell is. Levels
+ * sit finest first in a {@link CLIPMAP_LEVEL_ARRAY}.
+ *
+ * 32 bytes, so an array of them meets a uniform buffer's 16-byte stride.
+ *
+ * @type {WebGPUStruct}
+ */
+export const CLIPMAP_LEVEL_STRUCT = WebGPUStruct.from({
+    /**
+     * The window's smallest cell on each axis, in the level's cells.
+     */
+    corner: vec3i,
+    /**
+     * World units on a side of a cell of the level.
+     */
+    cell_size: f32,
+    /**
+     * The window's side on each axis, in cells.
+     */
+    size: vec3i,
+}, "ClipmapLevel");
+
+/**
+ * A clipmap's table of levels, as a field of the uniform that carries it.
+ * @type {WebGPUArray}
+ */
+export const CLIPMAP_LEVEL_ARRAY = WebGPUArray.from(CLIPMAP_LEVEL_STRUCT, CLIPMAP_LEVEL_LIMIT);

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_contains.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether a clipmap level's window holds a cell: the window is `[corner, corner + size)` on each
+ * axis, in the level's cells.
+ *
+ * The CPU twin is `ClipmapWindowSet.contains`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_clipmap_contains: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_clipmap_contains.d.ts.map

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_contains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_clipmap_contains.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_contains.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,qCAFU,SAAS,CAWjB;0BAnBwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_contains.js

@@ -0,0 +1,20 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * Whether a clipmap level's window holds a cell: the window is `[corner, corner + size)` on each
+ * axis, in the level's cells.
+ *
+ * The CPU twin is `ClipmapWindowSet.contains`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_clipmap_contains = CodeChunk.from(
+    //language=WGSL
+    `
+fn clipmap_contains(cell: vec3<i32>, corner: vec3<i32>, size: vec3<i32>) -> bool {
+    let relative = cell - corner;
+
+    return all(relative >= vec3<i32>(0)) && all(relative < size);
+}
+`
+);

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_select_finest.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The finest level of a clipmap whose window holds a world point, and how far into that window's
+ * edge band the point is.
+ *
+ * Walks the first `count` levels of the table, finest first, at most {@link CLIPMAP_LEVEL_LIMIT}; the
+ * first whose window holds the cell the point is in answers. Its `edge_weight` is the point's distance
+ * to the window's nearest face, in the level's cells, through a linear ramp: 0 at `band_width` cells
+ * or deeper, 1 on the face. It is how much a reader blends toward the next coarser source — the
+ * parent level, or whatever stands outside the coarsest. `band_width` is positive.
+ *
+ * A point no level holds answers `CLIPMAP_LEVEL_NONE`, with a weight of 0.
+ *
+ * The CPU twin is `clipmap_select_finest` in `core/geom/clipmap/`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_clipmap_select_finest: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_clipmap_select_finest.d.ts.map

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_select_finest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_clipmap_select_finest.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_select_finest.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,0CAFU,SAAS,CAoDjB;0BAtEwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_select_finest.js

@@ -0,0 +1,71 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+import { CLIPMAP_LEVEL_ARRAY, CLIPMAP_LEVEL_LIMIT, CLIPMAP_LEVEL_STRUCT } from "./CLIPMAP_LEVEL_STRUCT.js";
+import { chunk_clipmap_contains } from "./chunk_clipmap_contains.js";
+
+/**
+ * The finest level of a clipmap whose window holds a world point, and how far into that window's
+ * edge band the point is.
+ *
+ * Walks the first `count` levels of the table, finest first, at most {@link CLIPMAP_LEVEL_LIMIT}; the
+ * first whose window holds the cell the point is in answers. Its `edge_weight` is the point's distance
+ * to the window's nearest face, in the level's cells, through a linear ramp: 0 at `band_width` cells
+ * or deeper, 1 on the face. It is how much a reader blends toward the next coarser source — the
+ * parent level, or whatever stands outside the coarsest. `band_width` is positive.
+ *
+ * A point no level holds answers `CLIPMAP_LEVEL_NONE`, with a weight of 0.
+ *
+ * The CPU twin is `clipmap_select_finest` in `core/geom/clipmap/`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_clipmap_select_finest = CodeChunk.from(
+    //language=WGSL
+    `
+const CLIPMAP_LEVEL_NONE: u32 = 0xFFFFFFFFu;
+
+struct ClipmapSelection {
+    // the finest level holding the point, or CLIPMAP_LEVEL_NONE
+    level: u32,
+    // 0 deeper than the band, rising to 1 on the window's nearest face
+    edge_weight: f32,
+}
+
+fn clipmap_select_finest(
+    levels: ptr<uniform, ${CLIPMAP_LEVEL_ARRAY.wgsl_ref}>,
+    count: u32,
+    position_ws: vec3f,
+    band_width: f32,
+) -> ClipmapSelection {
+
+    for (var i = 0u; i < ${CLIPMAP_LEVEL_LIMIT}u; i++) {
+        if (i >= count) {
+            break;
+        }
+
+        let level = (*levels)[i];
+
+        // the point in the level's cells
+        let position_cells = position_ws / level.cell_size;
+
+        if (!clipmap_contains(vec3<i32>(floor(position_cells)), level.corner, level.size)) {
+            continue;
+        }
+
+        let from_corner = position_cells - vec3f(level.corner);
+        let to_far_corner = vec3f(level.size) - from_corner;
+
+        let edge = min(
+            min(min(from_corner.x, from_corner.y), from_corner.z),
+            min(min(to_far_corner.x, to_far_corner.y), to_far_corner.z)
+        );
+
+        return ClipmapSelection(i, saturate(1.0 - edge / band_width));
+    }
+
+    return ClipmapSelection(CLIPMAP_LEVEL_NONE, 0.0);
+}
+`, [
+        CLIPMAP_LEVEL_STRUCT.declaration_chunk,
+        chunk_clipmap_contains,
+    ]
+);

package/src/shade/renderer/shader/chunk/clipmap/chunk_clipmap_storage_coord.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Where a cell of a clipmap level sits in storage that wraps: `cell mod period` on each axis,
+ * Euclidean, so negative cells wrap too. Anchored to the world, not to the window, so a window that
+ * moves keeps every cell still inside it where it was.
+ *
+ * The period is the storage's extent on each axis — a window's side, or one more than it along the
+ * axis a face-centred component is stored on.
+ *
+ * The CPU twin is `ClipmapWindowSet.storage_cell`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_clipmap_storage_coord: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_clipmap_storage_coord.d.ts.map