InstancedMesh2

Defined in: core/InstancedMesh2.ts:53

Alternative InstancedMesh class to support additional features like frustum culling, fast raycasting, LOD and more.

Extends

unknown<TGeometry, TMaterial, TEventMap>

Type Parameters

• TData = {}

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>

Defined in: core/InstancedMesh2.ts:252

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

Geometry cannot be shared. If reused, it will be cloned.

Overrides

Mesh<TGeometry, TMaterial, TEventMap>.constructor

Properties

autoUpdate

autoUpdate: boolean = true

Defined in: core/InstancedMesh2.ts:136

Flag indicating whether to automatically perform frustum culling before rendering.

Default

true

availabilityArray

readonly availabilityArray: boolean[]

Defined in: core/InstancedMesh2.ts:127

Array storing visibility and availability for instances. [visible0, active0, visible1, active1, …]

bindMatrix

bindMatrix: Matrix4 = null

Defined in: core/InstancedMesh2.ts:146

The base matrix that is used for the bound bone transforms.

bindMatrixInverse

bindMatrixInverse: Matrix4 = null

Defined in: core/InstancedMesh2.ts:150

The base matrix that is used for resetting the bound bone transforms.

bindMode

bindMode: BindMode = AttachedBindMode

Defined in: core/InstancedMesh2.ts:142

Either AttachedBindMode or DetachedBindMode. AttachedBindMode means the skinned mesh shares the same world space as the skeleton. This is not true when using DetachedBindMode which is useful when sharing a skeleton across multiple skinned meshes.

Default

AttachedBindMode

boneTexture

boneTexture: SquareDataTexture = null

Defined in: core/InstancedMesh2.ts:91

Texture storing bones for instances.

boundingBox

boundingBox: Box3 = null

Defined in: core/InstancedMesh2.ts:100

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.

boundingSphere

boundingSphere: Sphere = null

Defined in: core/InstancedMesh2.ts:105

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.

bvh

bvh: InstancedMeshBVH = null

Defined in: core/InstancedMesh2.ts:110

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.

colorsTexture

colorsTexture: SquareDataTexture = null

Defined in: core/InstancedMesh2.ts:83

Texture storing colors for instances.

customSort

customSort: CustomSortCallback = null

Defined in: core/InstancedMesh2.ts:116

Custom sort function for instances. It’s possible to create the radix sort using the createRadixSort method.

Default

null

instanceIndex

instanceIndex: GLInstancedBufferAttribute = null

Defined in: core/InstancedMesh2.ts:75

Attribute storing indices of the instances to be rendered.

instances

instances: Entity<TData>[] = null

Defined in: core/InstancedMesh2.ts:71

An array of Entity representing individual instances. This array is only initialized if createEntities is set to true in the constructor parameters.

isInstancedMesh2

readonly isInstancedMesh2: true = true

Defined in: core/InstancedMesh2.ts:66

Indicates if this is an InstancedMesh2.

LODinfo

LODinfo: LODInfo<TData> = null

Defined in: core/InstancedMesh2.ts:131

Contains data for managing LOD, allowing different levels of detail for rendering and shadow casting.

matricesTexture

matricesTexture: SquareDataTexture

Defined in: core/InstancedMesh2.ts:79

Texture storing matrices for instances.

morphTexture

morphTexture: DataTexture = null

Defined in: core/InstancedMesh2.ts:87

Texture storing morph target influences for instances.

onFrustumEnter

onFrustumEnter: OnFrustumEnterCallback = null

Defined in: core/InstancedMesh2.ts:158

Callback function called if an instance is inside the frustum.

raycastOnlyFrustum

raycastOnlyFrustum: boolean = false

Defined in: core/InstancedMesh2.ts:122

Flag indicating if raycasting should only consider the last frame frustum culled instances. This is ignored if the bvh has been created.

Default

false

skeleton

skeleton: Skeleton = null

Defined in: core/InstancedMesh2.ts:154

Skeleton representing the bone hierarchy of the skinned mesh.

type

readonly type: "InstancedMesh2" = 'InstancedMesh2'

Defined in: core/InstancedMesh2.ts:62

Default Value

InstancedMesh2

uniformsTexture

uniformsTexture: SquareDataTexture = null

Defined in: core/InstancedMesh2.ts:95

Texture storing custom uniforms per instance.

Accessors

capacity

Get Signature

get capacity(): number

Defined in: core/InstancedMesh2.ts:189

The capacity of the instance buffers.

Returns

number

count

Get Signature

get count(): number

Defined in: core/InstancedMesh2.ts:194

The number of instances rendered in the last frame.

Returns

number

geometry

Get Signature

get geometry(): TGeometry

Defined in: core/InstancedMesh2.ts:225

An instance of BufferGeometry (or derived classes), defining the object’s structure.

Returns

TGeometry

Set Signature

set geometry(value): void

Defined in: core/InstancedMesh2.ts:226

Parameters

value

TGeometry

Returns

void

instancesCount

Get Signature

get instancesCount(): number

Defined in: core/InstancedMesh2.ts:199

The number of active instances.

Returns

number

perObjectFrustumCulled

Get Signature

get perObjectFrustumCulled(): boolean

Defined in: core/InstancedMesh2.ts:205

Determines if per-instance frustum culling is enabled.

Default

true

Returns

boolean

Set Signature

set perObjectFrustumCulled(value): void

Defined in: core/InstancedMesh2.ts:206

Parameters

value

boolean

Returns

void

sortObjects

Get Signature

get sortObjects(): boolean

Defined in: core/InstancedMesh2.ts:215

Determines if objects should be sorted before rendering.

Default

false

Returns

boolean

Set Signature

set sortObjects(value): void

Defined in: core/InstancedMesh2.ts:216

Parameters

value

boolean

Returns

void

Methods

addInstances()

addInstances(count, onCreation): this

Defined in: core/feature/Instances.ts:36

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.

addLOD()

addLOD(geometry, material, distance?, hysteresis?): this

Defined in: core/feature/LOD.ts:83

Adds a new LOD level with the given geometry, material, and distance.

Parameters

geometry

BufferGeometry

The geometry for the LOD level.

material

any

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.

addShadowLOD()

addShadowLOD(geometry, distance?, hysteresis?): this

Defined in: core/feature/LOD.ts:91

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.

clearInstances()

clearInstances(): this

Defined in: core/feature/Instances.ts:47

Clears all instances and resets the instance count.

Returns

this

The current InstancedMesh2 instance.

clone()

clone(recursive?): this

Defined in: core/InstancedMesh2.ts:792

Parameters

recursive?

boolean

Returns

this

computeBoundingBox()

computeBoundingBox(): void

Defined in: core/InstancedMesh2.ts:751

Computes the bounding box that encloses all instances, and updates the boundingBox attribute.

Returns

void

computeBoundingSphere()

computeBoundingSphere(): void

Defined in: core/InstancedMesh2.ts:773

Computes the bounding sphere that encloses all instances, and updates the boundingSphere attribute.

Returns

void

computeBVH()

computeBVH(config): void

Defined in: core/InstancedMesh2.ts:496

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

copy()

copy(source, recursive?): this

Defined in: core/InstancedMesh2.ts:802

Parameters

source

InstancedMesh2

recursive?

boolean

Returns

this

copyTo()

copyTo(id, target): void

Defined in: core/InstancedMesh2.ts:744

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

dispose()

dispose(): void

Defined in: core/InstancedMesh2.ts:844

Frees the GPU-related resources allocated.

Returns

void

disposeBVH()

disposeBVH(): void

Defined in: core/InstancedMesh2.ts:505

Disposes of the BVH structure.

Returns

void

getActiveAndVisibilityAt()

getActiveAndVisibilityAt(id): boolean

Defined in: core/InstancedMesh2.ts:662

Indicates if a specific instance is visible and active.

Parameters

id

number

The index of the instance.

Returns

boolean

Whether the instance is visible and active.

getActiveAt()

getActiveAt(id): boolean

Defined in: core/InstancedMesh2.ts:653

Gets the availability of a specific instance.

Parameters

id

number

The index of the instance.

Returns

boolean

Whether the instance is active (not deleted).

getColorAt()

getColorAt(id, color): Color

Defined in: core/InstancedMesh2.ts:706

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.

getMatrixAt()

getMatrixAt(id, matrix): Matrix4

Defined in: core/InstancedMesh2.ts:532

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.

getMorphAt()

getMorphAt(id, object?): Mesh

Defined in: core/feature/Morph.ts:12

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.

getObjectLODIndexForDistance()

getObjectLODIndexForDistance(levels, distance): number

Defined in: core/feature/LOD.ts:67

Retrieves the index of the LOD level for a given distance.

Parameters

levels

LODLevel<{}>[]

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.

getOpacityAt()

getOpacityAt(id): number

Defined in: core/InstancedMesh2.ts:734

Gets the opacity of a specific instance.

Parameters

id

number

The index of the instance.

Returns

number

The opacity of the instance.

getPositionAt()

getPositionAt(index, target): Vector3

Defined in: core/InstancedMesh2.ts:542

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.

getUniformAt()

getUniformAt(id, name, target?): any

Defined in: core/feature/Uniforms.ts:23

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.

getVisibilityAt()

getVisibilityAt(id): boolean

Defined in: core/InstancedMesh2.ts:634

Gets the visibility of a specific instance.

Parameters

id

number

The index of the instance.

Returns

boolean

Whether the instance is visible.

initSkeleton()

initSkeleton(skeleton, disableMatrixAutoUpdate?): void

Defined in: core/feature/Skeleton.ts:12

Initialize the skeleton of the instances.

Parameters

skeleton

Skeleton

The skeleton to initialize.

disableMatrixAutoUpdate?

boolean

Whether to disable the matrix auto update of the bones. Default is true.

Returns

void

initUniformsPerInstance()

initUniformsPerInstance(schema): void

Defined in: core/feature/Uniforms.ts:35

Initializes per-instance uniforms using a schema.

Parameters

schema

UniformSchemaShader

The schema defining the uniforms.

Returns

void

multiplyBoneMatricesAt()

multiplyBoneMatricesAt(instanceIndex, boneIndex, m1, m2): void

Defined in: core/feature/Skeleton.ts:20

internal

Parameters

instanceIndex

number

boneIndex

number

m1

Matrix4

m2

Matrix4

Returns

void

onAfterRender()

onAfterRender(renderer, scene, camera, geometry, material, group): void

Defined in: core/InstancedMesh2.ts:325

Parameters

renderer

WebGLRenderer

scene

Scene

camera

Camera

geometry

BufferGeometry

material

Material

group

any

Returns

void

onAfterShadow()

onAfterShadow(renderer, scene, camera, shadowCamera, geometry, depthMaterial, group): void

Defined in: core/InstancedMesh2.ts:321

Parameters

renderer

WebGLRenderer

scene

Scene

camera

Camera

shadowCamera

Camera

geometry

BufferGeometry

depthMaterial

Material

group

any

Returns

void

onBeforeRender()

onBeforeRender(renderer, scene, camera, geometry, material, group): void

Defined in: core/InstancedMesh2.ts:299

Parameters

renderer

WebGLRenderer

scene

Scene

camera

Camera

geometry

BufferGeometry

material

Material

group

any

Returns

void

onBeforeShadow()

onBeforeShadow(renderer, scene, camera, shadowCamera, geometry, depthMaterial, group): void

Defined in: core/InstancedMesh2.ts:282

Parameters

renderer

WebGLRenderer

scene

Scene

camera

Camera

shadowCamera

Camera

geometry

BufferGeometry

depthMaterial

Material

group

any

Returns

void

performFrustumCulling()

performFrustumCulling(camera, cameraLOD?): void

Defined in: core/feature/FrustumCulling.ts:32

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

removeInstances()

removeInstances(…ids): this

Defined in: core/feature/Instances.ts:42

Removes instances by their ids.

Parameters

ids

…number[]

The ids of the instances to remove.

Returns

this

The current InstancedMesh2 instance.

resizeBuffers()

resizeBuffers(capacity): this

Defined in: core/feature/Capacity.ts:14

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.

setActiveAndVisibilityAt()

setActiveAndVisibilityAt(id, value): void

Defined in: core/InstancedMesh2.ts:673

Set if a specific instance is visible and active.

Parameters

id

number

The index of the instance.

value

boolean

Whether the instance is active and active (not deleted).

Returns

void

setActiveAt()

setActiveAt(id, active): void

Defined in: core/InstancedMesh2.ts:643

Sets the availability of a specific instance.

Parameters

id

number

The index of the instance.

active

boolean

Whether the instance is active (not deleted).

Returns

void

setBonesAt()

setBonesAt(id, updateBonesMatrices?, excludeBonesSet?): void

Defined in: core/feature/Skeleton.ts:19

Set the bones of the skeleton to the instance at the specified index.

Parameters

id

number

The index of the instance.

updateBonesMatrices?

boolean

Whether to update the matrices of the bones. Default is true.

excludeBonesSet?

Set<string>

An optional set of bone names to exclude from updates, skipping their local matrix updates.

Returns

void

setColorAt()

setColorAt(id, color): void

Defined in: core/InstancedMesh2.ts:686

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

setFirstLODDistance()

setFirstLODDistance(distance?, hysteresis?): this

Defined in: core/feature/LOD.ts:74

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.

setMatrixAt()

setMatrixAt(id, matrix): void

Defined in: core/InstancedMesh2.ts:514

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

setMorphAt()

setMorphAt(id, object): void

Defined in: core/feature/Morph.ts:18

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

setOpacityAt()

setOpacityAt(id, value): void

Defined in: core/InstancedMesh2.ts:715

Sets the opacity of a specific instance.

Parameters

id

number

The index of the instance.

value

number

The opacity value to assign.

Returns

void

setUniformAt()

setUniformAt(id, name, value): void

Defined in: core/feature/Uniforms.ts:30

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

setVisibilityAt()

setVisibilityAt(id, visible): void

Defined in: core/InstancedMesh2.ts:624

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

updateInstances()

updateInstances(onUpdate): this

Defined in: core/feature/Instances.ts:22

Updates instances by applying a callback function to each instance. It calls updateMatrix for each instance.

Parameters

onUpdate

UpdateEntityCallback<Entity<TData>>

A callback function to update each entity.

Returns

this

The current InstancedMesh2 instance.

updateInstancesPosition()

updateInstancesPosition(onUpdate): this

Defined in: core/feature/Instances.ts:29

Updates instances position by applying a callback function to each instance. It calls updateMatrixPosition for each instance. This method updates only the position attributes of the matrix.