@three.ez/instanced-mesh/src/core/InstancedMeshBVH.d.ts

Enhanced InstancedMesh with frustum culling, fast raycasting (using BVH), sorting, visibility management and more.

import { BVH, onFrustumIntersectionCallback, onFrustumIntersectionLODCallback, onIntersectionCallback, onIntersectionRayCallback } from 'bvh.js';
import { Box3, Matrix4, Raycaster, Sphere, Vector3 } from 'three';
import { LODLevel } from './feature/LOD.js';
import { InstancedMesh2 } from './InstancedMesh2.js';
/**
 * Parameters for configuring the BVH (Bounding Volume Hierarchy).
 */
export interface BVHParams {
    /**
     * Margin applied to accommodate animated or moving objects.
     * Improves BVH update performance but slows down frustum culling and raycasting.
     * For static objects, set to 0 to optimize culling and raycasting efficiency.
     * @default 0
     */
    margin?: number;
    /**
     * Uses the geometry bounding sphere to compute instance bounding boxes.
     * Otherwise it's calculated by applying the object's matrix to all 8 bounding box points.
     * This is faster but less precise. Useful for moving objects.
     * Only works if the geometry's bounding sphere is centered at the origin.
     * @default false
     */
    getBBoxFromBSphere?: boolean;
    /**
     * Enables accurate frustum culling by checking intersections without applying margin to the bounding box.
     * @default true
     */
    accurateCulling?: boolean;
}
interface SphereTarget {
    centerX: number;
    centerY: number;
    centerZ: number;
    maxScale: number;
}
/**
 * Class to manage BVH (Bounding Volume Hierarchy) for `InstancedMesh2`.
 * Provides methods for managing bounding volumes, frustum culling, raycasting, and bounding box computation.
 */
export declare class InstancedMeshBVH {
    /**
     * The target `InstancedMesh2` object that the BVH is managing.
     */
    target: InstancedMesh2;
    /**
     * The geometry bounding box of the target.
     */
    geoBoundingBox: Box3;
    /**
     * The BVH instance used to organize bounding volumes.
     */
    bvh: BVH<{}, number>;
    /**
     * A map that stores the BVH nodes for each instance.
     */
    nodesMap: Map<number, {
        box: import("bvh.js").FloatArray;
        parent?: /*elided*/ any;
        left?: /*elided*/ any;
        right?: /*elided*/ any;
        object?: number;
    }>;
    /**
     * Enables accurate frustum culling by checking intersections without applying margin to the bounding box.
     */
    accurateCulling: boolean;
    protected LODsMap: Map<LODLevel<{}>[], Float32Array<ArrayBufferLike>>;
    protected _margin: number;
    protected _origin: Float32Array;
    protected _dir: Float32Array;
    protected _boxArray: Float32Array;
    protected _cameraPos: Float32Array;
    protected _getBoxFromSphere: boolean;
    protected _geoBoundingSphere: Sphere;
    protected _sphereTarget: SphereTarget;
    /**
     * @param target The target `InstancedMesh2`.
     * @param margin The margin applied for bounding box calculations (default is 0).
     * @param getBBoxFromBSphere Flag to determine if instance bounding boxes should be computed from the geometry bounding sphere. Faster but less precise (default is false).
     * @param accurateCulling Flag to enable accurate frustum culling without considering margin (default is true).
     */
    constructor(target: InstancedMesh2, margin?: number, getBBoxFromBSphere?: boolean, accurateCulling?: boolean);
    /**
     * Builds the BVH from the target mesh's instances using a top-down construction method.
     * This approach is more efficient and accurate compared to incremental methods, which add one instance at a time.
     */
    create(): void;
    /**
     * Inserts an instance into the BVH.
     * @param id The id of the instance to insert.
     */
    insert(id: number): void;
    /**
     * Inserts a range of instances into the BVH.
     * @param ids An array of ids to insert.
     */
    insertRange(ids: number[]): void;
    /**
     * Moves an instance within the BVH.
     * @param id The id of the instance to move.
     */
    move(id: number): void;
    /**
     * Deletes an instance from the BVH.
     * @param id The id of the instance to delete.
     */
    delete(id: number): void;
    /**
     * Clears the BVH.
     */
    clear(): void;
    /**
     * Performs frustum culling to determine which instances are visible based on the provided projection matrix.
     * @param projScreenMatrix The projection screen matrix for frustum culling.
     * @param onFrustumIntersection Callback function invoked when an instance intersects the frustum.
     */
    frustumCulling(projScreenMatrix: Matrix4, onFrustumIntersection: onFrustumIntersectionCallback<{}, number>): void;
    /**
     * Performs frustum culling with Level of Detail (LOD) consideration.
     * @param projScreenMatrix The projection screen matrix for frustum culling.
     * @param cameraPosition The camera's position used for LOD calculations.
     * @param levels An array of LOD levels.
     * @param onFrustumIntersection Callback function invoked when an instance intersects the frustum.
     */
    frustumCullingLOD(projScreenMatrix: Matrix4, cameraPosition: Vector3, levels: LODLevel[], onFrustumIntersection: onFrustumIntersectionLODCallback<{}, number>): void;
    /**
     * Performs raycasting to check if a ray intersects any instances.
     * @param raycaster The raycaster used for raycasting.
     * @param onIntersection Callback function invoked when a ray intersects an instance.
     */
    raycast(raycaster: Raycaster, onIntersection: onIntersectionRayCallback<number>): void;
    /**
     * Checks if a given box intersects with any instance bounding box.
     * @param target The target bounding box.
     * @param onIntersection Callback function invoked when an intersection occurs.
     * @returns `True` if there is an intersection, otherwise `false`.
     */
    intersectBox(target: Box3, onIntersection: onIntersectionCallback<number>): boolean;
    protected getBox(id: number, array: Float32Array): Float32Array;
    protected getSphereFromMatrix_centeredGeometry(id: number, array: Float32Array, target: SphereTarget): SphereTarget;
}
export {};
//# sourceMappingURL=InstancedMeshBVH.d.ts.map