@woosh/meep-engine 3.0.1 → 3.1.0

package/src/engine/graphics/geometry/buffered/query/GeometrySpatialQueryAccelerator.js

@@ -1,288 +1,288 @@
-import { assert } from "../../../../../core/assert.js";
-import { BinaryUint32BVH } from "../../../../../core/bvh2/binary/2/BinaryUint32BVH.js";
-import { Cache } from "../../../../../core/cache/Cache.js";
-import { frustum3_planes_to_flat_from_three } from "../../../../../core/geom/3d/frustum/frustum3_planes_to_flat_from_three.js";
-import { bvh32_from_indexed_geometry } from "../../bvh/buffered/bvh32_from_indexed_geometry.js";
-import { bvh32_from_unindexed_geometry } from "../../bvh/buffered/bvh32_from_unindexed_geometry.js";
-import { buffer_attribute_deinterleave } from "../buffer_attribute_deinterleave.js";
-import { buffer_attribute_denormalize } from "../buffer_attribute_denormalize.js";
-import { bvh32_geometry_overlap_clipping_volume } from "./bvh32_geometry_overlap_clipping_volume.js";
-import { bvh32_geometry_raycast } from "./bvh32_geometry_raycast.js";
-
-/**
- * 4-tuples
- * @type {number[]}
- */
-const scratch_planes = []
-
-export class GeometrySpatialQueryAccelerator {
-    constructor(
-        cache_size = 100 * 1024 * 1024
-    ) {
-
-        assert.isNonNegativeInteger(cache_size,'cache_size');
-        assert.greaterThanOrEqual(cache_size, 0, 'cache_size must be greater than or equal to 0');
-
-        /**
-         * @private
-         * @type {Cache<THREE.BufferGeometry, BinaryUint32BVH>}
-         */
-        this.cache = new Cache({
-            maxWeight: cache_size,
-            keyHashFunction(geometry) {
-                return geometry.id;
-            },
-            keyEqualityFunction(a, b) {
-                return a.id === b.id && a.uuid === b.uuid;
-            },
-            /**
-             *
-             * @param {BinaryUint32BVH} tree
-             */
-            valueWeigher(tree) {
-                return tree.estimateByteSize();
-            }
-        });
-
-    }
-
-    /**
-     *
-     * @param {number} value in bytes
-     */
-    set cache_size(value) {
-        this.cache.maxWeight = value;
-    }
-
-    /**
-     *
-     * @return {number} in bytes
-     */
-    get cache_size() {
-        return this.cache.maxWeight;
-    }
-
-    /**
-     *
-     * @param {THREE.BufferGeometry} geometry
-     * @param {Plane[]} planes
-     * @returns {boolean} true means some overlap exists, false otherwise
-     */
-    queryContainmentViaClippingPlanes(geometry, planes) {
-        assert.notNull(geometry, 'geometry');
-        assert.defined(geometry, 'geometry');
-
-        const bvh = this.acquire_bvh(geometry);
-
-        frustum3_planes_to_flat_from_three(planes, scratch_planes);
-
-        const geometryIndices = geometry.getIndex()?.array;
-        const position_attribute = geometry.getAttribute('position');
-
-        let position_data;
-        let stride = 3;
-        let position_data_offset = 0;
-
-        if (position_attribute.isInterleavedBufferAttribute) {
-
-            position_data = position_attribute.data.array;
-
-            stride = position_attribute.data.stride;
-            position_data_offset = position_attribute.offset;
-
-        } else {
-
-            position_data = position_attribute.array;
-
-            stride = 3;
-            position_data_offset = 0;
-
-        }
-
-        return bvh32_geometry_overlap_clipping_volume(
-            bvh,
-            position_data, position_data_offset, stride, position_attribute.normalized,
-            geometryIndices,
-            scratch_planes, 0, planes.length
-        );
-    }
-
-    /**
-     *
-     * @param {SurfacePoint3} destination
-     * @param {THREE.BufferGeometry} geometry
-     * @param {number[]|ArrayLike<number>|Float32Array} ray 6 component vector, [origin_x, origin_y, origin_z, direction_x, direction_y, direction_z]
-     * @return {boolean}
-     */
-    queryRaycastNearest_array(destination, geometry, ray) {
-        return this.queryRaycastNearest_primitive(
-            destination,
-            geometry,
-            ray[0], ray[1], ray[2],
-            ray[3], ray[4], ray[5]
-        );
-    }
-
-    /**
-     *
-     * @param {SurfacePoint3} destination
-     * @param {THREE.BufferGeometry} geometry
-     * @param {number} ray_origin_x
-     * @param {number} ray_origin_y
-     * @param {number} ray_origin_z
-     * @param {number} ray_direction_x
-     * @param {number} ray_direction_y
-     * @param {number} ray_direction_z
-     * @return {boolean}
-     */
-    queryRaycastNearest_primitive(
-        destination,
-        geometry,
-        ray_origin_x, ray_origin_y, ray_origin_z,
-        ray_direction_x, ray_direction_y, ray_direction_z
-    ) {
-        assert.notNull(geometry, 'geometry');
-        assert.defined(geometry, 'geometry');
-
-
-        let bvh;
-
-        try {
-            bvh = this.acquire_bvh(geometry);
-        } catch (e) {
-            console.error(e);
-            return false;
-        }
-
-        const geometryIndices = geometry.getIndex()?.array;
-        const position_attribute = geometry.getAttribute('position');
-
-        let position_data;
-        let stride = 3;
-        let position_data_offset = 0;
-
-        if (position_attribute.isInterleavedBufferAttribute) {
-
-            position_data = position_attribute.data.array;
-
-            stride = position_attribute.data.stride;
-            position_data_offset = position_attribute.offset;
-
-        } else {
-
-            position_data = position_attribute.array;
-
-            stride = 3;
-            position_data_offset = 0;
-
-        }
-
-        return bvh32_geometry_raycast(
-            destination,
-            bvh,
-            position_data,
-            position_data_offset,
-            stride,
-            position_attribute.normalized,
-            geometryIndices,
-            ray_origin_x, ray_origin_y, ray_origin_z,
-            ray_direction_x, ray_direction_y, ray_direction_z,
-            Infinity
-        );
-
-    }
-
-    /**
-     * Get the nearest ray intersection
-     * @param {SurfacePoint3} destination
-     * @param {THREE.BufferGeometry} geometry
-     * @param {Vector3} ray_origin
-     * @param {Vector3} ray_direction
-     * @returns {boolean} true if hit detected, false otherwise
-     */
-    queryRaycastNearest(destination, geometry, ray_origin, ray_direction) {
-
-        return this.queryRaycastNearest_primitive(
-            destination, geometry,
-            ray_origin.x,
-            ray_origin.y,
-            ray_origin.z,
-            ray_direction.x,
-            ray_direction.y,
-            ray_direction.z
-        );
-
-    }
-
-    /**
-     * Destroys cache for a given geometry, useful for when geometry changes and cache needs to be invalidated
-     * @param {THREE.BufferGeometry} geometry
-     * @returns {boolean}
-     */
-    cache_remove_geometry(geometry) {
-
-        return this.cache.remove(geometry);
-
-    }
-
-    /**
-     * NOTE: do not modify the BVH
-     * @param {THREE.BufferGeometry} geometry
-     * @returns {BinaryUint32BVH}
-     */
-    acquire_bvh(geometry) {
-        assert.notNull(geometry, 'geometry');
-        assert.defined(geometry, 'geometry');
-
-        const existing = this.cache.get(geometry);
-
-        if (existing !== null) {
-            return existing;
-        }
-
-        const bvh = this.__build_bvh(geometry);
-
-        this.cache.put(geometry, bvh);
-
-        return bvh;
-    }
-
-    /**
-     * @private
-     * @param {THREE.BufferGeometry} geometry
-     * @returns {BinaryUint32BVH}
-     */
-    __build_bvh(geometry) {
-        const bvh = new BinaryUint32BVH();
-
-        const position_attribute = geometry.getAttribute('position');
-        const index_attribute = geometry.getIndex();
-
-        const de_interleaved_position_attribute = buffer_attribute_deinterleave(position_attribute);
-        const de_normalized_position_attribute = buffer_attribute_denormalize(de_interleaved_position_attribute);
-
-        const vertices = de_normalized_position_attribute.array;
-
-        if (index_attribute === undefined || index_attribute === null) {
-
-            bvh32_from_unindexed_geometry(bvh, vertices);
-
-        } else {
-
-            const de_interleaved_index_attribute = buffer_attribute_deinterleave(index_attribute);
-            const indices = de_interleaved_index_attribute.array;
-
-            bvh32_from_indexed_geometry(bvh, vertices, indices);
-
-        }
-
-        return bvh;
-    }
-
-}
-
-/**
- * @readonly
- * @type {GeometrySpatialQueryAccelerator}
- */
-GeometrySpatialQueryAccelerator.INSTANCE = new GeometrySpatialQueryAccelerator();
+import { assert } from "../../../../../core/assert.js";
+import { BinaryUint32BVH } from "../../../../../core/bvh2/binary/2/BinaryUint32BVH.js";
+import { Cache } from "../../../../../core/cache/Cache.js";
+import { StandardAttributes } from "../../../../../shade/renderer/geometry/StandardAttributes.js";
+import { bvh32_from_buffered_geometry } from "../../bvh/buffered/bvh32_from_buffered_geometry.js";
+import { bvh32_geometry_overlap_clipping_volume } from "./bvh32_geometry_overlap_clipping_volume.js";
+import { bvh32_geometry_raycast } from "./bvh32_geometry_raycast.js";
+
+/**
+ * A geometry's triangle BVH, and the geometry version it was built from.
+ *
+ * The version is what makes the cache safe to hold across an edit: `Geometry` bumps it when the
+ * caller says the vertex data changed, and a tree built before that no longer bounds what the
+ * arrays hold. Nothing infers a change from the arrays themselves — that is `Geometry`'s own
+ * contract, and it is the same bargain {@link GPUDynamicMeshResidency} makes with its uploads.
+ */
+class GeometryTree {
+    /**
+     * @type {BinaryUint32BVH|null}
+     */
+    bvh = null;
+
+    /**
+     * @type {number}
+     */
+    version = 0;
+}
+
+/**
+ * The positions a geometry's triangles are made of.
+ *
+ * @param {Geometry} geometry
+ * @returns {Attribute}
+ */
+function read_position_attribute(geometry) {
+    const attribute = geometry.getAttribute(StandardAttributes.Position);
+
+    assert.defined(attribute, 'position attribute');
+
+    return attribute;
+}
+
+/**
+ * A geometry's indices in the form {@link read_triangle_vertices} wants them: `undefined` for
+ * implicit indexing, rather than the `null` a geometry holds.
+ *
+ * @param {Geometry} geometry
+ * @returns {ArrayLike<number>|undefined}
+ */
+function read_geometry_indices(geometry) {
+    const index = geometry.index;
+
+    if (index === null) {
+        return undefined;
+    }
+
+    return index.data;
+}
+
+/**
+ * CPU spatial queries over a {@link Geometry}'s own triangles — a raycast, and an overlap against a
+ * clipping volume — accelerated by a triangle BVH built on first ask and cached per geometry.
+ *
+ * **This is the CPU side, and it is not what picking uses.** Picking under Shade reads the
+ * visibility buffer (I-9); this answers for callers that need a surface point rather than an entity,
+ * on geometry the CPU already holds — a generated primitive, a trail, a tile, anything a tool built.
+ *
+ * **A `MeshletGeometry` cannot be asked.** Its triangles are quantized inside meshlet pages;
+ * `geometry_build_from_meshlet_geometry` decodes one back into a `Geometry`, and that decode is the
+ * caller's to make and to hold on to, because it is far more expensive than the tree built over it.
+ */
+export class GeometrySpatialQueryAccelerator {
+    /**
+     * @type {Cache<Geometry, GeometryTree>}
+     */
+    #cache;
+
+    /**
+     * @param {number} [cache_size] in bytes
+     */
+    constructor(
+        cache_size = 100 * 1024 * 1024
+    ) {
+
+        assert.isNonNegativeInteger(cache_size, 'cache_size');
+        assert.greaterThanOrEqual(cache_size, 0, 'cache_size must be greater than or equal to 0');
+
+        this.#cache = new Cache({
+            maxWeight: cache_size,
+            keyHashFunction(geometry) {
+                return geometry.id;
+            },
+            keyEqualityFunction(a, b) {
+                // ids come off a counter that never recycles, so identity and id agree
+                return a === b;
+            },
+            /**
+             * @param {GeometryTree} tree
+             */
+            valueWeigher(tree) {
+                return tree.bvh.estimateByteSize();
+            }
+        });
+
+    }
+
+    /**
+     *
+     * @param {number} value in bytes
+     */
+    set cache_size(value) {
+        this.#cache.maxWeight = value;
+    }
+
+    /**
+     *
+     * @return {number} in bytes
+     */
+    get cache_size() {
+        return this.#cache.maxWeight;
+    }
+
+    /**
+     * Does any triangle of the geometry lie inside the volume the planes bound?
+     *
+     * @param {Geometry} geometry
+     * @param {number[]|Float32Array} planes 4-tuples of `normal_x, normal_y, normal_z, constant`; a point is inside when the dot product plus the constant is non-negative for every plane
+     * @param {number} planes_offset
+     * @param {number} plane_count
+     * @returns {boolean} true means some overlap exists, false otherwise
+     */
+    queryContainmentViaClippingPlanes(geometry, planes, planes_offset, plane_count) {
+        const bvh = this.acquire_bvh(geometry);
+
+        const position = read_position_attribute(geometry);
+
+        return bvh32_geometry_overlap_clipping_volume(
+            bvh,
+            position.data, 0, position.spec.itemSize,
+            position.spec.normalized,
+            read_geometry_indices(geometry),
+            planes, planes_offset, plane_count
+        );
+    }
+
+    /**
+     *
+     * @param {SurfacePoint3} destination
+     * @param {Geometry} geometry
+     * @param {number[]|ArrayLike<number>|Float32Array} ray 6 component vector, [origin_x, origin_y, origin_z, direction_x, direction_y, direction_z]
+     * @return {boolean}
+     */
+    queryRaycastNearest_array(destination, geometry, ray) {
+        return this.queryRaycastNearest_primitive(
+            destination,
+            geometry,
+            ray[0], ray[1], ray[2],
+            ray[3], ray[4], ray[5]
+        );
+    }
+
+    /**
+     *
+     * @param {SurfacePoint3} destination
+     * @param {Geometry} geometry
+     * @param {number} ray_origin_x
+     * @param {number} ray_origin_y
+     * @param {number} ray_origin_z
+     * @param {number} ray_direction_x
+     * @param {number} ray_direction_y
+     * @param {number} ray_direction_z
+     * @return {boolean}
+     */
+    queryRaycastNearest_primitive(
+        destination,
+        geometry,
+        ray_origin_x, ray_origin_y, ray_origin_z,
+        ray_direction_x, ray_direction_y, ray_direction_z
+    ) {
+        const bvh = this.acquire_bvh(geometry);
+
+        const position = read_position_attribute(geometry);
+
+        return bvh32_geometry_raycast(
+            destination,
+            bvh,
+            position.data, 0, position.spec.itemSize,
+            position.spec.normalized,
+            read_geometry_indices(geometry),
+            ray_origin_x, ray_origin_y, ray_origin_z,
+            ray_direction_x, ray_direction_y, ray_direction_z,
+            Infinity
+        );
+
+    }
+
+    /**
+     * Get the nearest ray intersection
+     * @param {SurfacePoint3} destination
+     * @param {Geometry} geometry
+     * @param {Vector3} ray_origin
+     * @param {Vector3} ray_direction
+     * @returns {boolean} true if hit detected, false otherwise
+     */
+    queryRaycastNearest(destination, geometry, ray_origin, ray_direction) {
+
+        return this.queryRaycastNearest_primitive(
+            destination, geometry,
+            ray_origin.x,
+            ray_origin.y,
+            ray_origin.z,
+            ray_direction.x,
+            ray_direction.y,
+            ray_direction.z
+        );
+
+    }
+
+    /**
+     * Drop a geometry's tree, releasing the memory it holds.
+     *
+     * Not needed to pick up an edit — a query does that off the geometry's own version — this is for
+     * a geometry that will not be asked again.
+     *
+     * @param {Geometry} geometry
+     * @returns {boolean}
+     */
+    cache_remove_geometry(geometry) {
+
+        return this.#cache.remove(geometry);
+
+    }
+
+    /**
+     * NOTE: do not modify the BVH
+     * @param {Geometry} geometry
+     * @returns {BinaryUint32BVH}
+     */
+    acquire_bvh(geometry) {
+        assert.defined(geometry, 'geometry');
+        assert.notNull(geometry, 'geometry');
+        assert.equal(geometry.isGeometry, true, 'geometry.isGeometry !== true');
+
+        const version = geometry.version;
+
+        const existing = this.#cache.get(geometry);
+
+        if (existing !== null && existing.version === version) {
+            return existing.bvh;
+        }
+
+        const tree = new GeometryTree();
+
+        tree.version = version;
+        tree.bvh = this.#build_bvh(geometry);
+
+        this.#cache.put(geometry, tree);
+
+        return tree.bvh;
+    }
+
+    /**
+     * @param {Geometry} geometry
+     * @returns {BinaryUint32BVH}
+     */
+    #build_bvh(geometry) {
+        const bvh = new BinaryUint32BVH();
+
+        const position = read_position_attribute(geometry);
+
+        bvh32_from_buffered_geometry(
+            bvh,
+            geometry.getPrimitiveCount(),
+            position.data, 0, position.spec.itemSize,
+            position.spec.normalized,
+            read_geometry_indices(geometry)
+        );
+
+        return bvh;
+    }
+
+}
+
+/**
+ * @readonly
+ * @type {GeometrySpatialQueryAccelerator}
+ */
+GeometrySpatialQueryAccelerator.INSTANCE = new GeometrySpatialQueryAccelerator();

package/src/engine/graphics/geometry/bvh/buffered/bvh32_from_buffered_geometry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Build a triangle BVH over a vertex buffer, reading it through the buffered-geometry contract:
+ * interleaving, normalization and index resolution are all {@link read_triangle_vertices}'s, which
+ * is the same reader every query over such a BVH already uses.
+ *
+ * {@link bvh32_from_indexed_geometry} and {@link bvh32_from_unindexed_geometry} are this function
+ * at the tightly packed, unquantized defaults their callers all have; reach for this one only when
+ * the positions are interleaved with other attributes or are integer-quantized.
+ *
+ * @param {BinaryUint32BVH} bvh
+ * @param {number} triangle_count
+ * @param {number[]|ArrayLike<number>} vertices
+ * @param {number} vertex_offset index of the first position value in {@link vertices}
+ * @param {number} vertex_stride step between two vertices, in values
+ * @param {boolean} vertex_data_normalized whether position values are integer-quantized
+ * @param {number[]|ArrayLike<number>|undefined} indices `undefined` means implicit indexing; `null` is not accepted
+ */
+export function bvh32_from_buffered_geometry(bvh: BinaryUint32BVH, triangle_count: number, vertices: number[] | ArrayLike<number>, vertex_offset: number, vertex_stride: number, vertex_data_normalized: boolean, indices: number[] | ArrayLike<number> | undefined): void;
+//# sourceMappingURL=bvh32_from_buffered_geometry.d.ts.map

package/src/engine/graphics/geometry/bvh/buffered/bvh32_from_buffered_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bvh32_from_buffered_geometry.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/geometry/bvh/buffered/bvh32_from_buffered_geometry.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;GAgBG;AACH,mFAPW,MAAM,YACN,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,iBAC1B,MAAM,iBACN,MAAM,0BACN,OAAO,WACP,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,SAAS,QA2B9C"}

package/src/engine/graphics/geometry/bvh/buffered/bvh32_from_buffered_geometry.js

@@ -0,0 +1,52 @@
+import { read_triangle_vertices } from "../../buffered/read_triangle_vertices.js";
+import { bvh32_set_leaf_from_triangle } from "./bvh32_set_leaf_from_triangle.js";
+
+/**
+ * `ax, ay, az, bx, by, bz, cx, cy, cz` of the triangle currently being read
+ * @type {Float64Array}
+ */
+const triangle_scratch = new Float64Array(9);
+
+/**
+ * Build a triangle BVH over a vertex buffer, reading it through the buffered-geometry contract:
+ * interleaving, normalization and index resolution are all {@link read_triangle_vertices}'s, which
+ * is the same reader every query over such a BVH already uses.
+ *
+ * {@link bvh32_from_indexed_geometry} and {@link bvh32_from_unindexed_geometry} are this function
+ * at the tightly packed, unquantized defaults their callers all have; reach for this one only when
+ * the positions are interleaved with other attributes or are integer-quantized.
+ *
+ * @param {BinaryUint32BVH} bvh
+ * @param {number} triangle_count
+ * @param {number[]|ArrayLike<number>} vertices
+ * @param {number} vertex_offset index of the first position value in {@link vertices}
+ * @param {number} vertex_stride step between two vertices, in values
+ * @param {boolean} vertex_data_normalized whether position values are integer-quantized
+ * @param {number[]|ArrayLike<number>|undefined} indices `undefined` means implicit indexing; `null` is not accepted
+ */
+export function bvh32_from_buffered_geometry(
+    bvh,
+    triangle_count,
+    vertices, vertex_offset, vertex_stride,
+    vertex_data_normalized,
+    indices
+) {
+    bvh.setLeafCount(triangle_count);
+    bvh.initialize_structure();
+
+    for (let i = 0; i < triangle_count; i++) {
+
+        read_triangle_vertices(
+            triangle_scratch, 0,
+            vertices, vertex_offset, vertex_stride,
+            vertex_data_normalized,
+            indices,
+            i
+        );
+
+        bvh32_set_leaf_from_triangle(bvh, i, triangle_scratch, 0, 1, 2);
+    }
+
+    // finalize build
+    bvh.build();
+}