@woosh/meep-engine 2.163.10 → 2.164.0

package/src/core/bvh2/bvh3/BVH.d.ts

@@ -1,55 +1,388 @@
-export declare class BVH {
-    readonly root: number
-
-    node_capacity: number
-
-    readonly data_buffer: ArrayBuffer
-
-    allocate_node(): number
-
-    allocate_linear(node_count: number): void
-
-    release_node(node: number): void
-
-    insert_leaf(node: number): void
-
-    remove_leaf(node: number): void
-
-    node_is_leaf(node: number): boolean
-
-    collect_nodes_all(destination: ArrayLike<number>, destination_offset: number): void
-
-    node_set_aabb_primitive(node_id: number, x0: number, y0: number, z0: number, x1: number, y1: number, z1: number): void
-
-    node_set_aabb(node: number, aabb: ArrayLike<number>): void
-
-    node_get_aabb(node: number, aabb: ArrayLike<number>): void
-
-    node_set_user_data(node: number, data: number): void
-
-    node_get_user_data(node: number): number
-
-    node_set_child1(node: number, child1: number): void
-
-    node_get_child1(node: number): number
-
-    node_set_child2(node: number, child1: number): void
-
-    node_get_child2(node: number): number
-
-    node_set_parent(node: number, parent: number): void
-
-    node_get_parent(node: number): number
-
-    node_set_height(node: number, height: number): void
-
-    node_get_height(node: number): number
-
-    node_move_aabb(node: number, new_aabb: ArrayLike<number>): void
-
-    swap_nodes(node_a_id: number, node_b_id: number): boolean
-
-    release_all(): void
-
-    trim(): void
-}
+export const COLUMN_PARENT: 6;
+export const COLUMN_CHILD_1: 7;
+export const COLUMN_CHILD_2: 8;
+export const COLUMN_HEIGHT: 9;
+/**
+ * A non-leaf node have both CHILD_1 and CHILD_2 set, when CHILD_1 is not set - it's a leaf node
+ * So we can utilize space of CHILD_2 to store USER_DATA, hence there is overlap in schema
+ * @readonly
+ * @type {number}
+ */
+export const COLUMN_USER_DATA: number;
+/**
+ *
+ * @type {number}
+ */
+export const NULL_NODE: number;
+/**
+ * How many words are used for a single NODE in the tree
+ * One "word" is 4 bytes for the sake of alignment
+ * @readonly
+ * @type {number}
+ */
+export const ELEMENT_WORD_COUNT: number;
+/**
+ * Bounding Volume Hierarchy.
+ * Stores unsigned integer values at leaves, these are typically IDs or Index values.
+ * Highly optimized both in terms of memory usage and CPU. Most of the code is inlined for speed.
+ * No allocation are performed during usage (except for growing the tree capacity).
+ * RAM usage: 40 bytes per node, compared with V8s per-object allocation size of 80 bytes
+ * @see https://blog.dashlane.com/how-is-data-stored-in-v8-js-engine-memory
+ * @class
+ */
+export class BVH {
+    /**
+     *
+     * @type {ArrayBuffer}
+     * @private
+     */
+    private __data_buffer;
+    /**
+     * Replace data buffer.
+     * Remember to call {@link release_all} before this if you're using this for serialization.
+     * {@link size} and {@link __free} are not updated.
+     * @param {ArrayBuffer} v
+     */
+    set data_buffer(arg: ArrayBuffer);
+    /**
+     * Access raw data
+     * Useful for serialization
+     * If you intend to modify the data directly - make sure you fully understand the implications of doing so
+     * @returns {ArrayBuffer}
+     */
+    get data_buffer(): ArrayBuffer;
+    /**
+     *
+     * @type {Float32Array}
+     * @private
+     */
+    private __data_float32;
+    /**
+     *
+     * @type {Uint32Array}
+     * @private
+     */
+    private __data_uint32;
+    /**
+     * How many nodes are currently reserved, this will grow automatically through {@link #allocate_node} method usage
+     * @type {number}
+     * @private
+     */
+    private __capacity;
+    /**
+     *
+     * @return {Float32Array}
+     */
+    get data_float32(): Float32Array;
+    /**
+     * Number of used nodes. These are either live nodes, or node sitting in the {@link #__free} pool
+     * @type {number}
+     * @private
+     */
+    private __size;
+    /**
+     * Indices of released nodes. Nodes are pulled from here first if available, before the whole tree gets resized
+     * @type {number[]}
+     * @private
+     */
+    private __free;
+    /**
+     * Pointer into __free array that's used as a stack, so this pointer represents top of the stack
+     * @type {number}
+     * @private
+     */
+    private __free_pointer;
+    /**
+     * Root node of the hierarchy
+     * @type {number}
+     * @private
+     */
+    private __root;
+    /**
+     * Make sure you understand what you're doing before using this
+     * @param {number} v
+     */
+    set root(arg: number);
+    /**
+     *
+     * @returns {number}
+     */
+    get root(): number;
+    /**
+     * Number of used nodes. Note that this is not the same as number of live nodes
+     * Is the same as number of live nodes if compaction was performed recently
+     * @return {number}
+     */
+    get size(): number;
+    /**
+     *
+     * @param {number} v
+     */
+    set node_capacity(arg: number);
+    /**
+     *
+     * @returns {number}
+     */
+    get node_capacity(): number;
+    __grow_capacity(): void;
+    /**
+     *
+     * @param {number} new_capacity in number of nodes
+     * @private
+     */
+    private __set_capacity;
+    /**
+     * Trim allocated memory region to only contain allocated nodes
+     */
+    trim(): void;
+    /**
+     * Allocates specified number of nodes linearly.
+     * Can only be used when the tree is explicitly empty, call {@link release_all} to achieve that.
+     * Nodes from 0 through to count - 1 will be allocated, and you can use them immediately.
+     *
+     * This method is intended for static builds mainly, where we know ahead of time how many nodes we will need, and we want to avoid per-node allocation overhead.
+     * @param {number} node_count
+     */
+    allocate_linear(node_count: number): void;
+    /**
+     *
+     * @returns {number}
+     */
+    allocate_node(): number;
+    /**
+     * Release memory used by the node back into the pool
+     * NOTE: Make sure that the node is not "live" (not attached to the hierarchy), otherwise this operation may corrupt the tree
+     * @param {number} id
+     */
+    release_node(id: number): void;
+    /**
+     *
+     * @param {number} id
+     * @returns {boolean}
+     */
+    node_is_leaf(id: number): boolean;
+    /**
+     *
+     * @param {number} id
+     * @returns {number}
+     */
+    node_get_user_data(id: number): number;
+    /**
+     *
+     * @param {number} id
+     * @param {number} value
+     */
+    node_set_user_data(id: number, value: number): void;
+    /**
+     *
+     * @param {number} id
+     * @returns {number}
+     */
+    node_get_child1(id: number): number;
+    /**
+     *
+     * @param {number} node
+     * @param {number} child1
+     */
+    node_set_child1(node: number, child1: number): void;
+    /**
+     *
+     * @param {number} id
+     * @returns {number}
+     */
+    node_get_child2(id: number): number;
+    /**
+     *
+     * @param {number} node
+     * @param {number} child2
+     */
+    node_set_child2(node: number, child2: number): void;
+    /**
+     *
+     * @param {number} id
+     * @returns {number}
+     */
+    node_get_parent(id: number): number;
+    /**
+     *
+     * @param {number} node
+     * @param {number} parent
+     */
+    node_set_parent(node: number, parent: number): void;
+    /**
+     *
+     * @param {number} id
+     * @returns {number}
+     */
+    node_get_height(id: number): number;
+    /**
+     *
+     * @param {number} id
+     * @param {number} height
+     */
+    node_set_height(id: number, height: number): void;
+    /**
+     *
+     * @param {number} id
+     * @param {number[]|Float32Array} result
+     */
+    node_get_aabb(id: number, result: number[] | Float32Array): void;
+    /**
+     *
+     * @param {number} id
+     * @param {number[]|ArrayLike<number>|AABB3} aabb
+     */
+    node_set_aabb(id: number, aabb: number[] | ArrayLike<number> | AABB3): void;
+    /**
+     *
+     * @param {number} id
+     * @param {number[]} aabb
+     */
+    node_move_aabb(id: number, aabb: number[]): void;
+    /**
+     *
+     * @param {number} id
+     * @param {number} x0
+     * @param {number} y0
+     * @param {number} z0
+     * @param {number} x1
+     * @param {number} y1
+     * @param {number} z1
+     */
+    node_set_aabb_primitive(id: number, x0: number, y0: number, z0: number, x1: number, y1: number, z1: number): void;
+    /**
+     *
+     * @param {number} id
+     * @returns {number}
+     */
+    node_get_surface_area(id: number): number;
+    /**
+     *
+     * @param {number} index_a
+     * @param {number} index_b
+     * @returns {number}
+     */
+    node_get_combined_surface_area(index_a: number, index_b: number): number;
+    /**
+     *
+     * @param {number} destination
+     * @param {number} index_a
+     * @param {number} index_b
+     */
+    node_set_combined_aabb(destination: number, index_a: number, index_b: number): void;
+    /**
+     *
+     * @param {number} leaf
+     * @returns {void}
+     */
+    insert_leaf(leaf: number): void;
+    /**
+     * refit and update nodes up the tree. Only updates bounds
+     * NOTE: Does not update "height"
+     * @param {number} parent
+     * @private
+     */
+    private bubble_up_refit;
+    /**
+     * refit and update nodes up the tree
+     * @param {number} parent
+     * @private
+     */
+    private bubble_up_update;
+    /**
+     * NOTE: Leaf node is not released, make sure to call {@link #release_node} separately when you no longer need the leaf node
+     * @param {number} leaf
+     * @returns {void}
+     */
+    remove_leaf(leaf: number): void;
+    /**
+     * **Height-balancing** rotation (Box2D v2 `b2DynamicTree::Balance`): if the
+     * two subtrees of node A differ in height by more than one, rotate the
+     * taller grandchild up. Keeps the tree height ≤ O(log N) but is chosen
+     * purely on *height* — it does not consider surface area, so the result is
+     * height-balanced yet not SAH-balanced (query cost can stay 1.3–2× above an
+     * SAH-optimal tree). See {@link balance_rotate} for the SAH-driven variant.
+     * Returns the (possibly new) subtree-root index.
+     * @param {number} iA
+     * @returns {number}
+     * @private
+     */
+    private balance_height;
+    /**
+     * **SAH-reducing** rotation (Kensler 2008 / Box2D v3 `b2RotateNodes`). For
+     * node A with children B, C, consider the four ways to swap a child of A
+     * with a grandchild (a child of the other child); each rotation re-forms
+     * exactly one internal node and changes the tree's total surface-area
+     * (SAH) cost by `area(old child) − area(new child)`. Apply the swap with
+     * the largest positive reduction, or none if no swap helps.
+     *
+     * Unlike {@link balance_height} the subtree root A never moves (so the
+     * return value is always `iA`), and the criterion is *surface area*, not
+     * height — keeping query cost near the SAH optimum. Height is not an
+     * explicit invariant here, but SAH-good trees stay well-shaped for
+     * spatially-distributed data (this is what modern Box2D ships).
+     *
+     * Deterministic: a pure function of the current tree state.
+     *
+     * @param {number} iA
+     * @returns {number} always `iA` (the subtree root is unchanged)
+     * @private
+     */
+    private balance_rotate;
+    /**
+     * Utility method for assigning both children at once
+     * Children must be valid nodes (non-null)
+     * @param {number} parent
+     * @param {number} child_1
+     * @param {number} child_2
+     */
+    node_assign_children(parent: number, child_1: number, child_2: number): void;
+    /**
+     * Utility method for assigning both children at once
+     * Children must be valid nodes (non-null)
+     * Does not update bounds.
+     * @param {number} parent
+     * @param {number} child_1
+     * @param {number} child_2
+     */
+    node_assign_children_only(parent: number, child_1: number, child_2: number): void;
+    /**
+     * Release all nodes, this essentially resets the tree to empty state
+     * NOTE: For performance reasons, released memory is not reset, this means that attempting to access cleared nodes' memory will yield garbage data
+     */
+    release_all(): void;
+    /**
+     *
+     * @param {function(node:number, tree:BVH):void} callback
+     * @param {*} [ctx]
+     */
+    traverse(callback: any, ctx?: any): void;
+    /**
+     *
+     * @param {number[]} destination
+     * @param {number} destination_offset
+     * @returns {number}
+     */
+    collect_nodes_all(destination: number[], destination_offset: number): number;
+    /**
+     * Update parent and child links of a given node to point to a new location, useful for re-locating nodes
+     * @param {number} node node to update
+     * @param {number} destination Where updated links should point to
+     * @private
+     */
+    private __move_node_links;
+    /**
+     * Swap two nodes in memory
+     * @param {number} a
+     * @param {number} b
+     * @returns {boolean}
+     */
+    swap_nodes(a: number, b: number): boolean;
+    /**
+     * Used for type checking
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isBVH: boolean;
+}
+//# sourceMappingURL=BVH.d.ts.map

package/src/core/bvh2/bvh3/BVH.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BVH.d.ts","sourceRoot":"","sources":["../../../../../src/core/bvh2/bvh3/BVH.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"BVH.d.ts","sourceRoot":"","sources":["../../../../../src/core/bvh2/bvh3/BVH.js"],"names":[],"mappings":"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"}

package/src/core/bvh2/bvh3/BVH.js

@@ -3,7 +3,7 @@ import { UINT32_MAX } from "../../binary/UINT32_MAX.js";
 import { array_copy } from "../../collection/array/array_copy.js";
 import { array_buffer_copy } from "../../collection/array/typed/array_buffer_copy.js";
 import { aabb3_array_combine } from "../../geom/3d/aabb/aabb3_array_combine.js";
-import { aabb3_compute_surface_area } from "../../geom/3d/aabb/aabb3_compute_surface_area.js";
+import { aabb3_surface_area } from "../../geom/3d/aabb/aabb3_surface_area.js";
 import { max2 } from "../../math/max2.js";
 import { min2 } from "../../math/min2.js";
 
@@ -104,7 +104,12 @@ export class BVH {
         this.__data_float32 = new Float32Array(this.__data_buffer);
         this.__data_uint32 = new Uint32Array(this.__data_buffer);
 
-        this.node_capacity = Math.floor(v.byteLength / ELEMENT_BYTE_COUNT);
+        // Adopt the supplied buffer by reference. Going through the public
+        // `node_capacity` setter would re-enter `__set_capacity`, which
+        // allocates a fresh buffer and discards `v` (and its data) whenever the
+        // implied capacity differs from the current one — silently breaking the
+        // serialization round-trip this setter exists for.
+        this.__capacity = Math.floor(v.byteLength / ELEMENT_BYTE_COUNT);
     }
 
     /**
@@ -521,7 +526,8 @@ export class BVH {
      * @param {number[]} aabb
      */
     node_move_aabb(id, aabb) {
-        // TODO only refit for small changes, and re-insert for large changes
+        // Intentionally a full bubble-up refit on every move (no fat-AABB margin
+        // / re-insert fast path). Keeps the tree exact for the current callers.
         this.node_set_aabb(id, aabb);
 
         const parent = this.__data_uint32[ELEMENT_WORD_COUNT * id + COLUMN_PARENT];
@@ -579,7 +585,7 @@ export class BVH {
         const y1 = float32[address + 4];
         const z1 = float32[address + 5];
 
-        return aabb3_compute_surface_area(
+        return aabb3_surface_area(
             x0, y0, z0,
             x1, y1, z1
         );
@@ -621,7 +627,7 @@ export class BVH {
         const b_z1 = float32[address_b + 5];
         const z1 = max2(a_z1, b_z1);
 
-        return aabb3_compute_surface_area(
+        return aabb3_surface_area(
             x0, y0, z0,
             x1, y1, z1,
         );

package/src/core/bvh2/bvh3/BvhClient.d.ts

@@ -1,11 +1,31 @@
-import {BVH} from "./BVH";
-
-export declare class BvhClient{
-    readonly is_linked:boolean
-    readonly bounds:ArrayLike<number>
-
-    write_bound():void
-
-    link(tree:BVH,data:number):void
-    unlink():void
-}
+/**
+ * A convenience class to work with BVH leaf nodes
+ */
+export class BvhClient {
+    /**
+     * @readonly
+     * @type {number[]}
+     */
+    readonly bounds: number[];
+    get is_linked(): boolean;
+    /**
+     *
+     * @param {BVH} tree
+     * @param {number} data Must be a uint32
+     */
+    link(tree: BVH, data: number): void;
+    unlink(): void;
+    write_bounds(): void;
+    /**
+     *
+     * @param {number} x0
+     * @param {number} y0
+     * @param {number} z0
+     * @param {number} x1
+     * @param {number} y1
+     * @param {number} z1
+     */
+    resize(x0: number, y0: number, z0: number, x1: number, y1: number, z1: number): void;
+    #private;
+}
+//# sourceMappingURL=BvhClient.d.ts.map

package/src/core/bvh2/bvh3/bvh_build_from_unindexed_triangles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bvh_build_from_unindexed_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/core/bvh2/bvh3/bvh_build_from_unindexed_triangles.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wEAHW,MAAM,EAAE,GAAC,YAAY,kBACrB,MAAM,QAyChB"}

package/src/core/bvh2/bvh3/ebvh_build_for_geometry_incremental.js

@@ -1,4 +1,4 @@
-import { compute_triangle_group_aabb3 } from "../../geom/3d/aabb/compute_triangle_group_aabb3.js";
+import { aabb3_from_triangle_group } from "../../geom/3d/aabb/aabb3_from_triangle_group.js";
 import { min2 } from "../../math/min2.js";
 
 /**
@@ -28,7 +28,7 @@ export function ebvh_build_for_geometry_incremental(
 
         const group_size = index_end - index_start;
 
-        compute_triangle_group_aabb3(leaf_aabb, 0, index_array, positions_array, index_start * 3, group_size, 3);
+        aabb3_from_triangle_group(leaf_aabb, 0, index_array, positions_array, index_start * 3, group_size, 3);
 
         const node_index = bvh.allocate_node();
         bvh.node_set_aabb(node_index, leaf_aabb);

package/src/core/bvh2/bvh3/ebvh_build_hierarchy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ebvh_build_hierarchy.d.ts","sourceRoot":"","sources":["../../../../../src/core/bvh2/bvh3/ebvh_build_hierarchy.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,kEARW,MAAM,EAAE,GAAC,WAAW,oBACpB,MAAM,aACN,MAAM,EAAE,GAAC,WAAW,oBACpB,MAAM,2BACN,MAAM,0BACN,MAAM,GACJ,MAAM,CAmFlB"}
+{"version":3,"file":"ebvh_build_hierarchy.d.ts","sourceRoot":"","sources":["../../../../../src/core/bvh2/bvh3/ebvh_build_hierarchy.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,kEARW,MAAM,EAAE,GAAC,WAAW,oBACpB,MAAM,aACN,MAAM,EAAE,GAAC,WAAW,oBACpB,MAAM,2BACN,MAAM,0BACN,MAAM,GACJ,MAAM,CA2FlB"}

package/src/core/bvh2/bvh3/ebvh_build_hierarchy.js

@@ -28,6 +28,14 @@ export function ebvh_build_hierarchy(
     assert.isNonNegativeInteger(input_node_count, 'input_node_count');
     assert.isNonNegativeInteger(node_pool_offset, 'node_pool_offset');
 
+    if (input_node_count === 0) {
+        // Empty input: there is no root. Return the NULL_NODE sentinel used
+        // everywhere else for an empty tree (matching ebvh_build_hierarchy_radix's
+        // leaf_count === 0 contract). Without this, the code below would read
+        // unprocessed_nodes[0] === undefined and assign an undefined root.
+        return NULL_NODE;
+    }
+
     let used_index = node_pool_offset;
 
     // Assemble hierarchy

package/src/core/bvh2/bvh3/ebvh_geometry_query_any_triangle_ray.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Find ANY triangle intersected by the ray within the (min_distance, max_distance) range.
+ *
+ * Unlike {@link ebvh_geometry_query_nearest_triangle_ray}, this does not search for the
+ * closest hit — it returns as soon as a single qualifying intersection is found, which makes
+ * it suited to occlusion / shadow-ray style queries where only the presence of a hit matters.
+ *
+ * @param {number[]} output On a hit, receives [triangle_index, u, v, t]
+ * @param {number} output_offset
+ * @param {BVH} bvh
+ * @param {number} root
+ * @param {number[]} ray `[origin_x, origin_y, origin_z, direction_x, direction_y, direction_z]`.
+ *        The direction MUST be unit length: `t`, `min_distance` and `max_distance` are interpreted as
+ *        Euclidean distances from the origin, and the AABB distance-prune relies on that scale.
+ * @param {number} min_distance
+ * @param {number} max_distance
+ * @param {number[]|Uint32Array} indices
+ * @param {number[]|Float32Array} positions
+ * @returns {boolean} true if any triangle was hit
+ */
+export function ebvh_geometry_query_any_triangle_ray(output: number[], output_offset: number, bvh: BVH, root: number, ray: number[], min_distance: number, max_distance: number, indices: number[] | Uint32Array, positions: number[] | Float32Array): boolean;
+//# sourceMappingURL=ebvh_geometry_query_any_triangle_ray.d.ts.map

package/src/core/bvh2/bvh3/ebvh_geometry_query_any_triangle_ray.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ebvh_geometry_query_any_triangle_ray.d.ts","sourceRoot":"","sources":["../../../../../src/core/bvh2/bvh3/ebvh_geometry_query_any_triangle_ray.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6DAbW,MAAM,EAAE,iBACR,MAAM,kBAEN,MAAM,OACN,MAAM,EAAE,gBAGR,MAAM,gBACN,MAAM,WACN,MAAM,EAAE,GAAC,WAAW,aACpB,MAAM,EAAE,GAAC,YAAY,GACnB,OAAO,CAyHnB"}