@woosh/meep-engine 3.3.0 → 3.4.0

package/src/shade/renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Bytes a complete tree over `leaf_count` leaves occupies, header included.
+ *
+ * A Karras hierarchy over N leaves is exactly `2N - 1` nodes: `N - 1` internal and `N` leaves. One
+ * leaf is the degenerate case — a single leaf node, no internal node at all.
+ *
+ * @param {number} leaf_count
+ * @returns {number}
+ */
+export function bvh_buffer_size(leaf_count: number): number;
+/**
+ * The BVH buffer's byte contract, resolved from the structs the traversal shaders read rather than
+ * restated as literals — `.pack()` and WGSL layout rules decide these offsets, and a builder that
+ * hard-codes them is one struct edit away from writing trees nothing can traverse.
+ *
+ * The layout every RT consumer depends on:
+ *
+ *   [u32 root][node 0][node 1] ... where a node is
+ *   [min.x, min.y, min.z, max.x, max.y, max.z : f32][child_1 : u32][child_2 : u32]
+ *
+ * A node is a leaf exactly when `child_1 == BVH_NULL_NODE`, and then `child_2` carries the payload
+ * (for the TLAS, a row in the scene database's `meshes` table). An internal node always has two
+ * real children with meaningful bounds — the distance-ordered point queries dereference both before
+ * descending, so a placeholder child is not an option.
+ *
+ * @see BVH2_NODE_STRUCT
+ * @see BVH_STRUCT
+ */
+/**
+ * Words per node.
+ * @type {number}
+ */
+export const BVH_NODE_STRIDE_WORDS: number;
+/**
+ * Word offset of the node's six bounds floats, within the node.
+ * @type {number}
+ */
+export const BVH_NODE_BOUNDS_WORD: number;
+/**
+ * Word offset of `child_1` within the node — the field whose `BVH_NULL_NODE` value means "leaf".
+ * @type {number}
+ */
+export const BVH_NODE_CHILD_1_WORD: number;
+/**
+ * Word offset of `child_2` within the node — right child, or payload on a leaf.
+ * @type {number}
+ */
+export const BVH_NODE_CHILD_2_WORD: number;
+/**
+ * Words the `root` header occupies in front of node 0. This is the `+ 4` in every sizing expression
+ * in the tree.
+ * @type {number}
+ */
+export const BVH_HEADER_WORDS: number;
+//# sourceMappingURL=BVH_BUFFER_LAYOUT.d.ts.map

package/src/shade/renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BVH_BUFFER_LAYOUT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js"],"names":[],"mappings":"AAsDA;;;;;;;;GAQG;AACH,4CAHW,MAAM,GACJ,MAAM,CAQlB;AAjED;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,oCAFU,MAAM,CAE2E;AAE3F;;;GAGG;AACH,mCAFU,MAAM,CAE0F;AAE1G;;;GAGG;AACH,oCAFU,MAAM,CAE4F;AAE5G;;;GAGG;AACH,oCAFU,MAAM,CAE4F;AAE5G;;;;GAIG;AACH,+BAFU,MAAM,CAE+E"}

package/src/shade/renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js

@@ -0,0 +1,70 @@
+import { assert } from "../../../../core/assert.js";
+import { BVH2_NODE_STRUCT } from "../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
+import { BVH_STRUCT } from "../../shader/chunk/bvh/BVH_STRUCT.js";
+
+/**
+ * The BVH buffer's byte contract, resolved from the structs the traversal shaders read rather than
+ * restated as literals — `.pack()` and WGSL layout rules decide these offsets, and a builder that
+ * hard-codes them is one struct edit away from writing trees nothing can traverse.
+ *
+ * The layout every RT consumer depends on:
+ *
+ *   [u32 root][node 0][node 1] ... where a node is
+ *   [min.x, min.y, min.z, max.x, max.y, max.z : f32][child_1 : u32][child_2 : u32]
+ *
+ * A node is a leaf exactly when `child_1 == BVH_NULL_NODE`, and then `child_2` carries the payload
+ * (for the TLAS, a row in the scene database's `meshes` table). An internal node always has two
+ * real children with meaningful bounds — the distance-ordered point queries dereference both before
+ * descending, so a placeholder child is not an option.
+ *
+ * @see BVH2_NODE_STRUCT
+ * @see BVH_STRUCT
+ */
+
+/**
+ * Words per node.
+ * @type {number}
+ */
+export const BVH_NODE_STRIDE_WORDS = BVH2_NODE_STRUCT.size / Uint32Array.BYTES_PER_ELEMENT;
+
+/**
+ * Word offset of the node's six bounds floats, within the node.
+ * @type {number}
+ */
+export const BVH_NODE_BOUNDS_WORD = BVH2_NODE_STRUCT.get('bounds').offset / Uint32Array.BYTES_PER_ELEMENT;
+
+/**
+ * Word offset of `child_1` within the node — the field whose `BVH_NULL_NODE` value means "leaf".
+ * @type {number}
+ */
+export const BVH_NODE_CHILD_1_WORD = BVH2_NODE_STRUCT.get('child_1').offset / Uint32Array.BYTES_PER_ELEMENT;
+
+/**
+ * Word offset of `child_2` within the node — right child, or payload on a leaf.
+ * @type {number}
+ */
+export const BVH_NODE_CHILD_2_WORD = BVH2_NODE_STRUCT.get('child_2').offset / Uint32Array.BYTES_PER_ELEMENT;
+
+/**
+ * Words the `root` header occupies in front of node 0. This is the `+ 4` in every sizing expression
+ * in the tree.
+ * @type {number}
+ */
+export const BVH_HEADER_WORDS = BVH_STRUCT.get('nodes').offset / Uint32Array.BYTES_PER_ELEMENT;
+
+/**
+ * Bytes a complete tree over `leaf_count` leaves occupies, header included.
+ *
+ * A Karras hierarchy over N leaves is exactly `2N - 1` nodes: `N - 1` internal and `N` leaves. One
+ * leaf is the degenerate case — a single leaf node, no internal node at all.
+ *
+ * @param {number} leaf_count
+ * @returns {number}
+ */
+export function bvh_buffer_size(leaf_count) {
+    assert.isNonNegativeInteger(leaf_count, 'leaf_count');
+
+    const node_count = leaf_count === 0 ? 0 : 2 * leaf_count - 1;
+
+    return BVH_HEADER_WORDS * Uint32Array.BYTES_PER_ELEMENT + node_count * BVH2_NODE_STRUCT.size;
+}

package/src/shade/renderer/gpu_primitive/bvh/BVH_BUILD_SETTINGS_STRUCT.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `root_word_offset` value meaning "this tree has no root word".
+ *
+ * A TLAS buffer is `{root: u32, nodes: array<node>}` and every consumer reads that first word. A
+ * BLAS has no header at all — its root is node 0 by convention, asserted on the way in at
+ * `meshlet_batch_to_bvh` and relied on by `chunk_ray_query_blas_*`. One emission kernel serves
+ * both, so "where does the root word go" has to include "nowhere".
+ *
+ * @type {number}
+ */
+export const BVH_NO_ROOT_WORD: number;
+/**
+ * What the builder's passes need to know about where they are writing.
+ *
+ * `element_count` is the leaf count, and the whole node layout follows from it: `N - 1` internal
+ * nodes at `[0, N-2]`, leaf `j` at node `(N-1)+j`, `2N-1` nodes in total. Those are *node* indices,
+ * local to the tree.
+ *
+ * `node_word_offset` is where node 0 starts, in u32 words from the beginning of the bound buffer.
+ * A TLAS owns its buffer and puts node 0 straight after the root word, so it passes 1. A BLAS lives
+ * at some address inside a shared arena of every geometry's nodes, so it passes that address in
+ * words. Keeping this a parameter rather than a constant is what lets one emission kernel and one
+ * refit kernel serve a tree that owns its buffer and a tree that is a tenant in someone else's.
+ *
+ * `parents_offset` and `leaf_nodes_offset` say the same thing about the other two arrays the refit
+ * reads. A build allocates those transiently and passes 0; a refit-only update reads them out of
+ * per-geometry arenas that every registered tree's shape shares, and passes its own position in
+ * each. Same reason as `node_word_offset`: one kernel, tenant or owner.
+ *
+ * The Morton pass takes this struct too and ignores every offset; it writes keys and values, not
+ * nodes. One struct per recorder beats three structs that differ by a field.
+ *
+ * @type {WebGPUStruct}
+ */
+export const BVH_BUILD_SETTINGS_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=BVH_BUILD_SETTINGS_STRUCT.d.ts.map

package/src/shade/renderer/gpu_primitive/bvh/BVH_BUILD_SETTINGS_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BVH_BUILD_SETTINGS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/BVH_BUILD_SETTINGS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,+BAFU,MAAM,CAE2B;AAE3C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wCAFU,YAAY,CAQC;6BA3CM,mCAAmC"}

package/src/shade/renderer/gpu_primitive/bvh/BVH_BUILD_SETTINGS_STRUCT.js

@@ -0,0 +1,45 @@
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * `root_word_offset` value meaning "this tree has no root word".
+ *
+ * A TLAS buffer is `{root: u32, nodes: array<node>}` and every consumer reads that first word. A
+ * BLAS has no header at all — its root is node 0 by convention, asserted on the way in at
+ * `meshlet_batch_to_bvh` and relied on by `chunk_ray_query_blas_*`. One emission kernel serves
+ * both, so "where does the root word go" has to include "nowhere".
+ *
+ * @type {number}
+ */
+export const BVH_NO_ROOT_WORD = 0xffffffff;
+
+/**
+ * What the builder's passes need to know about where they are writing.
+ *
+ * `element_count` is the leaf count, and the whole node layout follows from it: `N - 1` internal
+ * nodes at `[0, N-2]`, leaf `j` at node `(N-1)+j`, `2N-1` nodes in total. Those are *node* indices,
+ * local to the tree.
+ *
+ * `node_word_offset` is where node 0 starts, in u32 words from the beginning of the bound buffer.
+ * A TLAS owns its buffer and puts node 0 straight after the root word, so it passes 1. A BLAS lives
+ * at some address inside a shared arena of every geometry's nodes, so it passes that address in
+ * words. Keeping this a parameter rather than a constant is what lets one emission kernel and one
+ * refit kernel serve a tree that owns its buffer and a tree that is a tenant in someone else's.
+ *
+ * `parents_offset` and `leaf_nodes_offset` say the same thing about the other two arrays the refit
+ * reads. A build allocates those transiently and passes 0; a refit-only update reads them out of
+ * per-geometry arenas that every registered tree's shape shares, and passes its own position in
+ * each. Same reason as `node_word_offset`: one kernel, tenant or owner.
+ *
+ * The Morton pass takes this struct too and ignores every offset; it writes keys and values, not
+ * nodes. One struct per recorder beats three structs that differ by a field.
+ *
+ * @type {WebGPUStruct}
+ */
+export const BVH_BUILD_SETTINGS_STRUCT = WebGPUStruct.from({
+    element_count: u32,
+    node_word_offset: u32,
+    root_word_offset: u32,
+    parents_offset: u32,
+    leaf_nodes_offset: u32,
+}, "BVHBuildSettings");