InstancedMesh2
Alternative InstancedMesh class to support additional features like frustum culling, fast raycasting, LOD and more.
Extends
unknown<TGeometry,TMaterial,TEventMap>
Type Parameters
• TData = object
Type for additional instance data.
• TGeometry extends BufferGeometry = BufferGeometry
Type extending BufferGeometry.
• TMaterial extends Material | Material[] = Material | Material[]
Type extending Material or an array of Material.
• TEventMap extends Object3DEventMap = Object3DEventMap
Type extending Object3DEventMap.
Constructors
new InstancedMesh2()
new InstancedMesh2<
TData,TGeometry,TMaterial,TEventMap>(geometry,material,params?):InstancedMesh2<TData,TGeometry,TMaterial,TEventMap>
Parameters
• geometry: TGeometry
An instance of BufferGeometry.
• material: TMaterial
A single or an array of Material.
• params?: InstancedMesh2Params
Optional configuration parameters object. See InstancedMesh2Params for details.
Returns
InstancedMesh2<TData, TGeometry, TMaterial, TEventMap>
Remarks
Geometries and materials cannot be shared. If reused, they will be cloned.
Overrides
Mesh<TGeometry, TMaterial, TEventMap>.constructor
Defined in
Properties
autoUpdate
autoUpdate:
boolean=true
Flag indicating whether to automatically perform frustum culling before rendering.
Default
trueDefined in
boundingBox
boundingBox:
Box3=null
This bounding box encloses all instances, which can be calculated with computeBoundingBox method.
Bounding box isn’t computed by default. It needs to be explicitly computed, otherwise it’s null.
Defined in
boundingSphere
boundingSphere:
Sphere=null
This bounding sphere encloses all instances, which can be calculated with computeBoundingSphere method.
Bounding sphere is computed during its first render. You may need to recompute it if an instance is transformed.
Defined in
bvh
bvh:
InstancedMeshBVH=null
BVH structure for optimized culling and intersection testing.
It’s possible to create the BVH using the computeBVH method. Once created it will be updated automatically.
Defined in
colorsTexture
colorsTexture:
SquareDataTexture=null
Texture storing colors for instances.
Defined in
customDepthMaterial
customDepthMaterial:
any
Default Value
new MeshDepthMaterial({ depthPacking: RGBADepthPacking })
Defined in
customDistanceMaterial
customDistanceMaterial:
any
Default Value
new MeshDistanceMaterial()
Defined in
customSort
customSort:
CustomSortCallback=null
Custom sort function for instances.
It’s possible to create the radix sort using the createRadixSort method.
Default
nullDefined in
instanceIndex
instanceIndex:
GLInstancedBufferAttribute
Attribute storing indices of the instances to be rendered.
Defined in
instances
instances:
Entity<TData>[] =null
An array of Entity representing individual instances.
This array is only initialized if createInstances is set to true in the constructor parameters.
Defined in
isInstancedMesh2
readonlyisInstancedMesh2:true=true
Indicates if this is an InstancedMesh2.
Defined in
LODinfo
LODinfo:
LODInfo<TData> =null
Contains data for managing LOD, allowing different levels of detail for rendering and shadow casting.
Defined in
matricesTexture
matricesTexture:
SquareDataTexture
Texture storing matrices for instances.
Defined in
morphTexture
morphTexture:
DataTexture=null
Texture storing morph target influences for instances.
Defined in
raycastOnlyFrustum
raycastOnlyFrustum:
boolean=false
Flag indicating if raycasting should only consider the last frame frustum culled instances. This is ignored if the bvh has been created.
Default
falseDefined in
type
readonlytype:"InstancedMesh2"='InstancedMesh2'
Default Value
InstancedMesh2
Defined in
uniformsTexture
uniformsTexture:
SquareDataTexture=null
Texture storing custom uniforms per instance.
Defined in
visibilityArray
visibilityArray:
boolean[]
Array storing visibility for instances.
Defined in
Accessors
capacity
Get Signature
get capacity():
number
The capacity of the instance buffers.
Returns
number
Defined in
count
Get Signature
get count():
number
The number of instances rendered in the last frame.
Returns
number
Defined in
geometry
Get Signature
get geometry():
TGeometry
An instance of BufferGeometry (or derived classes), defining the object’s structure.
Returns
TGeometry
Set Signature
set geometry(
value):void
Parameters
• value: TGeometry
Returns
void
Defined in
instancesCount
Get Signature
get instancesCount():
number
The number of active instances.
If a number greater than the capacity is set, the capacity will be increased automatically.
Returns
number
Set Signature
set instancesCount(
value):void
Parameters
• value: number
Returns
void
Defined in
material
Get Signature
get material():
TMaterial
An instance of material (or derived classes) or an array of materials, defining the object’s appearance.
Returns
TMaterial
Set Signature
set material(
value):void
Parameters
• value: TMaterial
Returns
void
Defined in
perObjectFrustumCulled
Get Signature
get perObjectFrustumCulled():
boolean
Determines if per-instance frustum culling is enabled.
Default
trueReturns
boolean
Set Signature
set perObjectFrustumCulled(
value):void
Parameters
• value: boolean
Returns
void
Defined in
sortObjects
Get Signature
get sortObjects():
boolean
Determines if objects should be sorted before rendering.
Default
falseReturns
boolean
Set Signature
set sortObjects(
value):void
Parameters
• value: boolean
Returns
void
Defined in
Methods
addInstances()
addInstances(
count,onCreation?):this
Adds new instances and optionally initializes them using a callback function.
Parameters
• count: number
The number of new instances to add.
• onCreation?: UpdateEntityCallback<Entity<TData>>
A callback function to initialize each new entity.
Returns
this
The current InstancedMesh2 instance.
Defined in
addLOD()
addLOD(
geometry,material,distance?,hysteresis?):this
Adds a new LOD level with the given geometry, material, and distance.
Parameters
• geometry: BufferGeometry
The geometry for the LOD level.
• material: Material
The material for the LOD level.
• distance?: number
The distance for this LOD level.
• hysteresis?: number
The hysteresis value for this LOD level.
Returns
this
The current InstancedMesh2 instance.
Defined in
addShadowLOD()
addShadowLOD(
geometry,distance?,hysteresis?):this
Adds a shadow-specific LOD level with the given geometry and distance.
Parameters
• geometry: BufferGeometry
The geometry for the shadow LOD.
• distance?: number
The distance for this LOD level.
• hysteresis?: number
The hysteresis value for this LOD level.
Returns
this
The current InstancedMesh2 instance.
Defined in
clone()
clone(
recursive?):this
Parameters
• recursive?: boolean
Returns
this
Defined in
computeBoundingBox()
computeBoundingBox():
void
Computes the bounding box that encloses all instances, and updates the boundingBox attribute.
Returns
void
Defined in
computeBoundingSphere()
computeBoundingSphere():
void
Computes the bounding sphere that encloses all instances, and updates the boundingSphere attribute.
Returns
void
Defined in
computeBVH()
computeBVH(
config):void
Creates and computes the BVH (Bounding Volume Hierarchy) for the instances. It’s recommended to create it when all the instance matrices have been assigned. Once created it will be updated automatically.
Parameters
• config: BVHParams = {}
Optional configuration parameters object. See BVHParams for details.
Returns
void
Defined in
copy()
copy(
source,recursive?):this
Parameters
• source: InstancedMesh2<object, BufferGeometry, any, Object3DEventMap>
• recursive?: boolean
Returns
this
Defined in
copyTo()
copyTo(
id,target):void
Copies position, quaternion, and scale of a specific instance to the specified target Object3D.
Parameters
• id: number
The index of the instance.
• target: Object3D
The Object3D where to copy transformation data.
Returns
void
Defined in
dispose()
dispose():
void
Frees the GPU-related resources allocated.
Returns
void
Defined in
disposeBVH()
disposeBVH():
void
Disposes of the BVH structure.
Returns
void
Defined in
getColorAt()
getColorAt(
id,color):Color
Gets the color of a specific instance.
Parameters
• id: number
The index of the instance.
• color: any = _tempCol
Optional Color to store the result.
Returns
Color
The color of the instance.
Defined in
getMatrixAt()
getMatrixAt(
id,matrix):Matrix4
Gets the local transformation matrix of a specific instance.
Parameters
• id: number
The index of the instance.
• matrix: any = _tempMat4
Optional Matrix4 to store the result.
Returns
Matrix4
The transformation matrix of the instance.
Defined in
getMorphAt()
getMorphAt(
id,object?):Mesh
Gets the morph target data for a specific instance.
Parameters
• id: number
The index of the instance.
• object?: Mesh
Optional Mesh to store the morph target data.
Returns
Mesh
The mesh object with updated morph target influences.
Defined in
getObjectLODIndexForDistance()
getObjectLODIndexForDistance(
levels,distance):number
Retrieves the index of the LOD level for a given distance.
Parameters
• levels: LODLevel<object>[]
The array of LOD levels.
• distance: number
The squared distance from the camera to the object.
Returns
number
The index of the LOD level that should be used.
Defined in
getOpacityAt()
getOpacityAt(
id):number
Gets the opacity of a specific instance.
Parameters
• id: number
The index of the instance.
Returns
number
The opacity of the instance.
Defined in
getPositionAt()
getPositionAt(
index,target):Vector3
Retrieves the position of a specific instance.
Parameters
• index: number
The index of the instance.
• target: any = _position
Optional Vector3 to store the result.
Returns
Vector3
The position of the instance as a Vector3.
Defined in
getUniformAt()
getUniformAt(
id,name,target?):any
Retrieves a uniform value for a specific instance.
Parameters
• id: number
The index of the instance.
• name: string
The name of the uniform.
• target?: any
Optional target object to store the uniform value.
Returns
any
The uniform value for the specified instance.
Defined in
getVisibilityAt()
getVisibilityAt(
id):boolean
Gets the visibility of a specific instance.
Parameters
• id: number
The index of the instance.
Returns
boolean
Whether the instance is visible.
Defined in
initUniformsPerInstance()
initUniformsPerInstance(
schema):void
Initializes per-instance uniforms using a schema.
Parameters
• schema: UniformSchema
The schema defining the uniforms.
Returns
void
Defined in
onAfterRender()
onAfterRender(
renderer,scene,camera,geometry,material,group):void
Parameters
• renderer: WebGLRenderer
• scene: Scene
• camera: Camera
• geometry: BufferGeometry
• material: Material
• group: any
Returns
void
Defined in
onBeforeRender()
onBeforeRender(
renderer,scene,camera,geometry,material,group):void
Parameters
• renderer: WebGLRenderer
• scene: Scene
• camera: Camera
• geometry: BufferGeometry
• material: Material
• group: any
Returns
void
Defined in
onBeforeShadow()
onBeforeShadow(
renderer,scene,camera,shadowCamera,geometry,depthMaterial,group):void
Parameters
• renderer: WebGLRenderer
• scene: Scene
• camera: Camera
• shadowCamera: Camera
• geometry: BufferGeometry
• depthMaterial: Material
• group: any
Returns
void
Defined in
performFrustumCulling()
performFrustumCulling(
camera,cameraLOD?):void
Performs frustum culling and manages LOD visibility.
Parameters
• camera: Camera
The main camera used for rendering.
• cameraLOD?: Camera
An optional camera for LOD calculations. Defaults to the main camera.
Returns
void
Defined in
core/feature/FrustumCulling.ts:22
resizeBuffers()
resizeBuffers(
capacity):this
Resizes internal buffers to accommodate the specified capacity. This ensures that the buffers are large enough to handle the required number of instances.
Parameters
• capacity: number
The new capacity of the buffers.
Returns
this
The current InstancedMesh2 instance.
Defined in
setColorAt()
setColorAt(
id,color):void
Sets the color of a specific instance.
Parameters
• id: number
The index of the instance.
• color: ColorRepresentation
The color to assign to the instance.
Returns
void
Defined in
setFirstLODDistance()
setFirstLODDistance(
distance?,hysteresis?):this
Sets the first LOD (using current geometry) distance and hysteresis.
Parameters
• distance?: number
The distance for the first LOD.
• hysteresis?: number
The hysteresis value for the first LOD.
Returns
this
The current InstancedMesh2 instance.
Defined in
setInstancesCount()
setInstancesCount(
count):void
Sets the number of instances to render and resizes buffers if necessary.
Parameters
• count: number
The desired number of instances.
Returns
void
Defined in
setMatrixAt()
setMatrixAt(
id,matrix):void
Sets the local transformation matrix for a specific instance.
Parameters
• id: number
The index of the instance.
• matrix: Matrix4
A Matrix4 representing the local transformation to apply to the instance.
Returns
void
Defined in
setMorphAt()
setMorphAt(
id,object):void
Sets the morph target influences for a specific instance.
Parameters
• id: number
The index of the instance.
• object: Mesh
The Mesh containing the morph target influences to apply.
Returns
void
Defined in
setOpacityAt()
setOpacityAt(
id,value):void
Sets the opacity of a specific instance.
Parameters
• id: number
The index of the instance.
• value: number
The opacity value to assign.
Returns
void
Defined in
setUniformAt()
setUniformAt(
id,name,value):void
Sets a uniform value for a specific instance.
Parameters
• id: number
The index of the instance.
• name: string
The name of the uniform.
• value: any
The value to set for the uniform.
Returns
void
Defined in
setVisibilityAt()
setVisibilityAt(
id,visible):void
Sets the visibility of a specific instance.
Parameters
• id: number
The index of the instance.
• visible: boolean
Whether the instance should be visible.
Returns
void
Defined in
updateInstances()
updateInstances(
onUpdate,start?,count?):this
Updates instances by applying a callback function to each instance.
Parameters
• onUpdate: UpdateEntityCallback<Entity<TData>>
A callback function to update each entity.
• start?: number
The starting index of the instances to update. Defaults to 0.
• count?: number
The number of instances to update. Defaults to the total instance count.
Returns
this
The current InstancedMesh2 instance.
Defined in
updateInstancesPosition()
updateInstancesPosition(
onUpdate,start?,count?):this
Updates instances position by applying a callback function to each instance. This method updates only the position attributes of the matrix.
Parameters
• onUpdate: UpdateEntityCallback<Entity<TData>>
A callback function to update each entity.
• start?: number
The starting index of the instances to update. Defaults to 0.
• count?: number
The number of instances to update. Defaults to the total instance count.
Returns
this
The current InstancedMesh2 instance.