@woosh/meep-engine 2.156.0 → 2.157.0

package/src/core/bvh8/BVH8.js

@@ -0,0 +1,436 @@
+import { assert } from "../assert.js";
+import { BinaryElementPool } from "../geom/3d/topology/struct/binary/BinaryElementPool.js";
+
+/**
+ * Highest triangle offset storable in a leaf slot's meta byte. The low 5 bits of a leaf meta
+ * hold the offset of the slot's first triangle relative to the node's `base_index_triangle`;
+ * values 24..31 in those bits mark internal slots, so leaf offsets must not exceed 23.
+ * @type {number}
+ */
+export const BVH8_MAX_LEAF_TRIANGLE_OFFSET = 23;
+
+/**
+ * Number of 32-bit words in a single node (80 bytes)
+ * @type {number}
+ */
+const NODE_WORD_COUNT = 20;
+
+/**
+ *
+ * @param {number} u32
+ * @param {number} i
+ * @returns {number}
+ */
+function u32_extract_byte(u32, i) {
+    return (u32 >> (i << 3)) & 0xFF;
+}
+
+/**
+ *
+ * @param {number} original
+ * @param {number} byte
+ * @param {number} i
+ * @returns {number}
+ */
+function u32_write_byte(original, byte, i) {
+    // mask out byte
+    const mask = 0xFF << (i << 3);
+
+    const masked = original & (~mask);
+
+    return masked | (byte << (i << 3));
+}
+
+/**
+ * @see https://github.com/jan-van-bergen/GPU-Raytracer/blob/6559ae2241c8fdea0ddaec959fe1a47ec9b3ab0d/Src/BVH/BVH.h#L61
+ * @description
+ * ```c
+ * struct BVHNode8 {
+ *    Vector3 p;
+ *    byte e[3];
+ *    byte imask;
+ *
+ *    unsigned base_index_child;
+ *    unsigned base_index_triangle;
+ *
+ *    byte meta[8] = { };
+ *
+ *    byte quantized_min_x[8] = { }, quantized_max_x[8] = { };
+ *    byte quantized_min_y[8] = { }, quantized_max_y[8] = { };
+ *    byte quantized_min_z[8] = { }, quantized_max_z[8] = { };
+ * }
+ * ```
+ *
+ * Slot encoding: `meta == 0` is an empty slot. A leaf slot stores the offset of its first
+ * triangle (relative to `base_index_triangle`) in the low 5 bits (≤ {@link BVH8_MAX_LEAF_TRIANGLE_OFFSET})
+ * and a unary triangle count in bits 5..7. An internal slot `i` stores `(24 + i) | 0b00100000` and has
+ * its bit set in `imask`; the k-th internal slot in ascending slot order is node `base_index_child + k`.
+ *
+ * Two triangle addressing conventions exist, depending on the build path:
+ * - direct (`bvh8_build_for_geometry`): `base_index_triangle` + meta offsets are geometry triangle
+ *   indices; the {@link BVH8#primitives} pool is unused.
+ * - indirect ({@link BVH8Converter}): they index into {@link BVH8#primitives}, whose entries are the
+ *   BVH2 leaves' user data (geometry triangle indices).
+ * Consumers must know which build path produced the tree — see `bvh8_geometry_validate` (direct)
+ * vs `bvh8_geometry_validate_indirect` (indirect).
+ */
+export class BVH8 {
+    #pool = new BinaryElementPool(80);
+    #primitives = new BinaryElementPool(4);
+
+    /**
+     *
+     * @returns {ArrayBufferLike}
+     */
+    get data_buffer() {
+        return this.#pool.data_uint32.buffer;
+    }
+
+    /**
+     *
+     * @returns {number}
+     */
+    get node_capacity() {
+        return this.#pool.capacity;
+    }
+
+    clear() {
+        this.#pool.clear();
+        this.#primitives.clear();
+    }
+
+    /**
+     *
+     * @return {BinaryElementPool}
+     */
+    get primitives() {
+        return this.#primitives;
+    }
+
+    /**
+     *
+     * @return {BinaryElementPool}
+     */
+    get nodes() {
+        return this.#pool;
+    }
+
+    /**
+     * Allocate a single node. The node is zeroed.
+     * @return {number}
+     */
+    allocate_node() {
+        return this.allocate_nodes(1);
+    }
+
+    /**
+     * Allocate a continuous run of nodes. Allocated nodes are zeroed — pool memory is recycled
+     * as-is across {@link BVH8#clear}, and `meta == 0` means "empty slot" to every consumer, so
+     * nodes must start from a clean state.
+     * @param {number} count
+     * @returns {number} index of the first allocated node
+     */
+    allocate_nodes(count) {
+        const pool = this.#pool;
+
+        const offset = pool.allocate_continuous(count);
+
+        const u32 = pool.data_uint32;
+        const first_word = pool.element_address(offset) >> 2;
+
+        u32.fill(0, first_word, first_word + count * NODE_WORD_COUNT);
+
+        return offset;
+    }
+
+    /**
+     *
+     * @param {number} node_index
+     * @param {number[]|Float32Array} output
+     */
+    node_get_p(node_index, output) {
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const i = address >> 2;
+
+        const f32 = pool.data_float32;
+
+        output[0] = f32[i];
+        output[1] = f32[i + 1];
+        output[2] = f32[i + 2];
+    }
+
+    /**
+     *
+     * @param {number} node_index
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    node_set_p(node_index, x, y, z) {
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const i = address >> 2;
+
+        const f32 = pool.data_float32;
+
+        f32[i] = x;
+        f32[i + 1] = y;
+        f32[i + 2] = z;
+    }
+
+    /**
+     *
+     * @param {number} node_index
+     * @param {number[]|Float32Array|Uint8Array} destination
+     */
+    node_get_e(node_index, destination) {
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const word = pool.data_uint32[(address >> 2) + 3];
+
+        destination[0] = u32_extract_byte(word, 0);
+        destination[1] = u32_extract_byte(word, 1);
+        destination[2] = u32_extract_byte(word, 2);
+    }
+
+    node_set_e(node_index, ex, ey, ez) {
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const u32 = pool.data_uint32;
+        const index = (address >> 2) + 3;
+
+        const word = u32[index];
+
+        u32[index] = (word & 0xFF000000)
+            | ((ex & 0xFF))
+            | ((ey & 0xFF) << 8)
+            | ((ez & 0xFF) << 16);
+    }
+
+    node_get_imask(node_index) {
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const u32 = pool.data_uint32;
+        const index = (address >> 2) + 3;
+
+        return u32_extract_byte(u32[index], 3);
+    }
+
+    node_set_imask(node_index, imask) {
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const u32 = pool.data_uint32;
+        const index = (address >> 2) + 3;
+
+        const word = u32[index];
+
+        u32[index] = u32_write_byte(word, imask, 3);
+    }
+
+    node_get_base_index_child(node_index) {
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const i = address >> 2;
+
+        return pool.data_uint32[i + 4];
+    }
+
+    node_set_base_index_child(node_index, value) {
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const i = address >> 2;
+
+        pool.data_uint32[i + 4] = value;
+    }
+
+    node_get_base_index_triangle(node_index) {
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const i = address >> 2;
+
+        return pool.data_uint32[i + 5];
+    }
+
+    node_set_base_index_triangle(node_index, value) {
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const i = address >> 2;
+
+        pool.data_uint32[i + 5] = value;
+    }
+
+    /**
+     *
+     * @param {number} node_index
+     * @param {number} child_index
+     * @returns {number}
+     */
+    node_get_meta(node_index, child_index) {
+        assert.isNonNegativeInteger(child_index, "child_index");
+        assert.lessThan(child_index, 8);
+
+
+        assert.isNonNegativeInteger(node_index, "node_index");
+
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const i = (address >> 2) + 6;
+
+        const word_offset = child_index >> 2;
+        const byte_index = child_index & 0b11;
+
+        const word = pool.data_uint32[i + word_offset];
+
+        return u32_extract_byte(word, byte_index);
+    }
+
+    node_set_meta(node_index, child_index, value) {
+
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const i = (address >> 2) + 6;
+
+        const word_offset = child_index >> 2;
+        const byte_index = child_index & 0b11;
+
+        const u32 = pool.data_uint32;
+        const word = u32[i + word_offset];
+
+        u32[i + word_offset] = u32_write_byte(word, value, byte_index);
+    }
+
+
+    node_get_quantized_min(node_index, child_index, output) {
+
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const word_offset = child_index >> 2;
+        const byte_index = child_index & 0b11;
+
+        const u32 = pool.data_uint32;
+
+        const i = address >> 2;
+
+        const i0 = i + 8 + word_offset;
+        const i1 = i + 12 + word_offset;
+        const i2 = i + 16 + word_offset;
+
+        const w0 = u32[i0];
+        const w1 = u32[i1];
+        const w2 = u32[i2];
+
+        output[0] = u32_extract_byte(w0, byte_index);
+        output[1] = u32_extract_byte(w1, byte_index);
+        output[2] = u32_extract_byte(w2, byte_index);
+    }
+
+    node_set_quantized_min(node_index, child_index, x, y, z) {
+
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const word_offset = child_index >> 2;
+        const byte_index = child_index & 0b11;
+
+        const u32 = pool.data_uint32;
+
+        const i = address >> 2;
+
+        const i0 = i + 8 + word_offset;
+        const i1 = i + 12 + word_offset;
+        const i2 = i + 16 + word_offset;
+
+        const w0 = u32[i0];
+        const w1 = u32[i1];
+        const w2 = u32[i2];
+
+        u32[i0] = u32_write_byte(w0, x, byte_index);
+        u32[i1] = u32_write_byte(w1, y, byte_index);
+        u32[i2] = u32_write_byte(w2, z, byte_index);
+    }
+
+    node_get_quantized_max(node_index, child_index, output) {
+
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const word_offset = child_index >> 2;
+        const byte_index = child_index & 0b11;
+
+        const u32 = pool.data_uint32;
+
+        const i = address >> 2;
+
+        const i0 = i + 10 + word_offset;
+        const i1 = i + 14 + word_offset;
+        const i2 = i + 18 + word_offset;
+
+        const w0 = u32[i0];
+        const w1 = u32[i1];
+        const w2 = u32[i2];
+
+        output[0] = u32_extract_byte(w0, byte_index);
+        output[1] = u32_extract_byte(w1, byte_index);
+        output[2] = u32_extract_byte(w2, byte_index);
+    }
+
+    node_set_quantized_max(node_index, child_index, x, y, z) {
+
+        const pool = this.#pool;
+        const address = pool.element_address(node_index);
+
+        const word_offset = child_index >> 2;
+        const byte_index = child_index & 0b11;
+
+        const u32 = pool.data_uint32;
+
+        const i = address >> 2;
+
+        const i0 = i + 10 + word_offset;
+        const i1 = i + 14 + word_offset;
+        const i2 = i + 18 + word_offset;
+
+        const w0 = u32[i0];
+        const w1 = u32[i1];
+        const w2 = u32[i2];
+
+        u32[i0] = u32_write_byte(w0, x, byte_index);
+        u32[i1] = u32_write_byte(w1, y, byte_index);
+        u32[i2] = u32_write_byte(w2, z, byte_index);
+    }
+
+    /**
+     *
+     * @param {number} node_index
+     * @param {number} child_index
+     * @return {boolean}
+     */
+    node_is_child_leaf(node_index, child_index) {
+        const meta = this.node_get_meta(node_index, child_index);
+
+        return ((meta & 0b00011111) < 24);
+    }
+
+    get byteSize() {
+        return this.#pool.byteSize;
+    }
+
+    trim() {
+        this.#pool.trim();
+        this.#primitives.trim();
+    }
+}

package/src/core/bvh8/NOTES.md

@@ -0,0 +1,63 @@
+References:
+
+* "Efficient Incoherent Ray Traversal on GPUs Through Compressed Wide BVHs" 2017, NVIDIA
+* https://github.com/jan-van-bergen/GPU-Raytracer
+* https://github.com/WeiPhil/nbvh/blob/0a7f8e0e09898ba6e161cd7433325368355e2d2a/include/cuda/accel/bvh8.cuh#L35
+* https://github.com/DGriffin91/obvhs/tree/main/src/cwbvh
+*
+
+Build
+
+* Consider triangles in groups of up-to 32 (bitmask)
+    * Find "lowest" index
+    * Walk up, and mark bitmask
+
+Explore additional metrics such as:
+
+* % of empty nodes
+* % of utilized triangle slots (up to 3 per child)
+
+Runtime
+
+* Debug shader for raycast, visualize:
+    * traversal depth (number of node intersection tests)
+    * number of triangle tests
+    * amount of memory bandwidth (estimate based on size of what we have to load)
+
+# Findings [2024/12/27]:
+
+> [2026-06-11] The numbers below predate the review-01 fixes (see REVIEW_01_ACTION_PLAN.md) —
+> notably the morton sort keyed on box *size* instead of box *center* (F4) and the converter's
+> corrupted SAH cost table (F3), both of which directly degrade build quality and time.
+> Re-measure before drawing conclusions from this section.
+
+Conclusion for now - not worth it. Too slow to build, and runtime performance inadequate.
+
+// RUNGHOLT, ORIGINAL build mechanism
+BVH8 triangles = 24, size = 480 bytes, quality = 88.16 (total=53.92515886274739)
+Geometry build: 27701.5078125 ms
+BVH2 size total: 465,232,160
+BLAS size: 134,670,480 bytes
+
+// RUNGHOLT, NEW (by A.G.)
+BVH8 triangles = 24, size = 240 bytes, quality = 145.27999999999997 (total=594.418961181131)
+Geometry build: 315166.4069824219 ms
+BVH2 size total: 465,232,160
+BLAS size: 302,576,640 bytes
+
+## Findings
+
+* Build times are far too long for runtime.
+* Binary sizes are considerably smaller than BVH2
+* Render times are much worse, in some cases 10x on shadows alone
+* Sorting children during traversal does help, as paper claims, by as much as 10%
+* packing a lot of triangles is tricky, due to restriction of only being able to address 24 contiunuous primitives per
+  node
+* you have to try and pack at least 1 triangle per node, otherwise you're wasting the 4 bytes reserved for base triangle
+  offset
+* original paper requires an extra triangle index array, which is hugely wasteful and creates an extra indirection
+  table, which is bad for perf
+
+# microsoft's DXR fallback implementation
+
+https://github.com/microsoft/DirectX-Graphics-Samples/tree/master/Libraries/D3D12RaytracingFallback

package/src/core/bvh8/build/BVH8Converter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @see https://github.com/jan-van-bergen/GPU-Raytracer/blob/6559ae2241c8fdea0ddaec959fe1a47ec9b3ab0d/Src/BVH/Converters/BVH8Converter.h#L4
+ */
+export class BVH8Converter {
+    /**
+     *
+     * @param {BVH8} bvh8
+     * @param {BVH} bvh2
+     */
+    constructor(bvh8: BVH8, bvh2: BVH);
+    /**
+     * Binary BVH
+     * @type {BVH}
+     */
+    bvh2: BVH;
+    /**
+     * @type {BVH8}
+     */
+    bvh8: BVH8;
+    /**
+     * Fill the decision table for the subtree of the given node, bottom-up.
+     * @param {number} node_index
+     * @returns {number} number of primitives under the given root
+     */
+    calculate_cost(node_index: number): number;
+    /**
+     * Resolve the BVH2 nodes that become the children of a BVH8 node, following the
+     * DISTRIBUTE decisions recorded by {@link BVH8Converter#calculate_cost}.
+     * @param {number} node_index
+     * @param {number[]|Uint32Array} children
+     * @param {number} child_offset
+     * @param {number} i
+     * @returns {number} number of children written
+     */
+    get_children(node_index: number, children: number[] | Uint32Array, child_offset: number, i: number): number;
+    /**
+     *
+     * @param {number} node_index
+     * @param {number[]|Uint32Array} children
+     * @param {number} child_count
+     */
+    order_children(node_index: number, children: number[] | Uint32Array, child_count: number): void;
+    /**
+     * Count triangles in the subtree of the given BVH2 node.
+     * Simultaneously fills the indices buffer of the BVH8, in left-to-right leaf order.
+     * @param {number} node_index
+     * @returns {number}
+     */
+    count_primitives(node_index: number): number;
+    /**
+     * Build the BVH8 subtree for a BVH2 subtree.
+     * @param {number} node_index_bvh8
+     * @param {number} node_index_bvh2
+     */
+    collapse(node_index_bvh8: number, node_index_bvh2: number): void;
+    convert(): void;
+    #private;
+}
+//# sourceMappingURL=BVH8Converter.d.ts.map

package/src/core/bvh8/build/BVH8Converter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BVH8Converter.d.ts","sourceRoot":"","sources":["../../../../../src/core/bvh8/build/BVH8Converter.js"],"names":[],"mappings":"AAmCA;;GAEG;AACH;IAYI;;;;OAIG;IACH,mCAGC;IAnBD;;;OAGG;IACH,UAAI;IAEJ;;OAEG;IACH,WAAI;IAkBJ;;;;OAIG;IACH,2BAHW,MAAM,GACJ,MAAM,CAgJlB;IAED;;;;;;;;OAQG;IACH,yBANW,MAAM,YACN,MAAM,EAAE,GAAC,WAAW,gBACpB,MAAM,KACN,MAAM,GACJ,MAAM,CAoDlB;IAED;;;;;OAKG;IACH,2BAJW,MAAM,YACN,MAAM,EAAE,GAAC,WAAW,eACpB,MAAM,QAkFhB;IAED;;;;;OAKG;IACH,6BAHW,MAAM,GACJ,MAAM,CAiClB;IAED;;;;OAIG;IACH,0BAHW,MAAM,mBACN,MAAM,QAYhB;IAoJD,gBAoBC;;CACJ"}