[page:Mesh] →

[name]

A special version of [page:Mesh] with multi draw batch rendering support. Use [name] if you have to render a large number of objects with the same material but with different geometries or world transformations. The usage of [name] will help you to reduce the number of draw calls and thus improve the overall rendering performance in your application.

If the [link:https://developer.mozilla.org/en-US/docs/Web/API/WEBGL_multi_draw WEBGL_multi_draw extension] is not supported then a less performant fallback is used.

Code Example


		const box = new THREE.BoxGeometry( 1, 1, 1 );
		const sphere = new THREE.SphereGeometry( 1, 12, 12 );
		const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );

		// initialize and add geometries into the batched mesh
		const batchedMesh = new BatchedMesh( 10, 5000, 10000, material );
		const boxGeometryId = batchedMesh.addGeometry( box );
		const sphereGeometryId = batchedMesh.addGeometry( sphere );

		// create instances of those geometries
		const boxInstancedId1 = batchedMesh.addInstance( boxGeometryId );
		const boxInstancedId2 = batchedMesh.addInstance( boxGeometryId );

		const sphereInstancedId1 = batchedMesh.addInstance( sphereGeometryId );
		const sphereInstancedId2 = batchedMesh.addInstance( sphereGeometryId );

		// position the geometries
		batchedMesh.setMatrixAt( boxInstancedId1, boxMatrix1 );
		batchedMesh.setMatrixAt( boxInstancedId2, boxMatrix2 );

		batchedMesh.setMatrixAt( sphereInstancedId1, sphereMatrix1 );
		batchedMesh.setMatrixAt( sphereInstancedId2, sphereMatrix2 );

		scene.add( batchedMesh );

Examples

[example:webgl_mesh_batch WebGL / mesh / batch]

Constructor

[name]( [param:Integer maxInstanceCount], [param:Integer maxVertexCount], [param:Integer maxIndexCount], [param:Material material], )

[page:Integer maxInstanceCount] - the max number of individual instances planned to be added and rendered.
[page:Integer maxVertexCount] - the max number of vertices to be used by all unique geometries.
[page:Integer maxIndexCount] - the max number of indices to be used by all unique geometries.
[page:Material material] - an instance of [page:Material]. Default is a new [page:MeshBasicMaterial].

Properties

See the base [page:Mesh] class for common properties.

[property:Box3 boundingBox]

This bounding box encloses all instances of the [name]. Can be calculated with [page:.computeBoundingBox](). Default is `null`.

[property:Sphere boundingSphere]

This bounding sphere encloses all instances of the [name]. Can be calculated with [page:.computeBoundingSphere](). Default is `null`.

[property:Boolean perObjectFrustumCulled]

If true then the individual objects within the [name] are frustum culled. Default is `true`.

[property:Boolean sortObjects]

If true then the individual objects within the [name] are sorted to improve overdraw-related artifacts. If the material is marked as "transparent" objects are rendered back to front and if not then they are rendered front to back. Default is `true`.

[property:Integer maxInstanceCount]

The maximum number of individual instances that can be stored in the [name]. Read only.

[property:Boolean isBatchedMesh]

Read-only flag to check if a given object is of type [name].

Methods

See the base [page:Mesh] class for common methods.

[method:undefined computeBoundingBox]()

Computes the bounding box, updating [page:.boundingBox] attribute.
Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are `null`.

[method:undefined computeBoundingSphere]()

Computes the bounding sphere, updating [page:.boundingSphere] attribute.
Bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are `null`.

[method:undefined dispose]()

Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer used in your app.

[method:this setCustomSort]( [param:Function sortFunction] )

Takes a sort a function that is run before render. The function takes a list of instances to sort and a camera. The objects in the list include a "z" field to perform a depth-ordered sort with.

[method:undefined getColorAt]( [param:Integer instanceId], [param:Color target] )

[page:Integer instanceId]: The id of an instance to get the color of.

[page:Color target]: The target object to copy the color in to.

Get the color of the defined geometry.

[method:Matrix4 getMatrixAt]( [param:Integer instanceId], [param:Matrix4 target] )

[page:Integer instanceId]: The id of an instance to get the matrix of.

[page:Matrix4 target]: This 4x4 matrix will be set to the local transformation matrix of the defined instance.

Get the local transformation matrix of the defined instance.

[method:Boolean getVisibleAt]( [param:Integer instanceId] )

[page:Integer instanceId]: The id of an instance to get the visibility state of.

Get whether the given instance is marked as "visible" or not.

[method:Object getGeometryRangeAt]( [param:Integer geometryId], [param:Object target] )

[page:Integer geometryId]: The id of the geometry to get the range of.

[page:Object target]: Optional target object to copy the range in to.

Get the range representing the subset of triangles related to the attached geometry, indicating the starting offset and count, or `null` if invalid.

Return an object of the form:

{ start: Integer, count: Integer }

[method:Integer getGeometryIdAt]( [param:Integer instanceId] )

[page:Integer instanceId]: The id of an instance to get the geometryIndex of.

Get the geometryIndex of the defined instance.

[method:undefined setColorAt]( [param:Integer instanceId], [param:Color color] )

[page:Integer instanceId]: The id of the instance to set the color of.

[page:Color color]: The color to set the instance to.

Sets the given color to the defined geometry instance.

[method:this setMatrixAt]( [param:Integer instanceId], [param:Matrix4 matrix] )

[page:Integer instanceId]: The id of an instance to set the matrix of.

[page:Matrix4 matrix]: A 4x4 matrix representing the local transformation of a single instance.

Sets the given local transformation matrix to the defined instance.

[method:this setVisibleAt]( [param:Integer instanceId], [param:Boolean visible] )

[page:Integer instanceId]: The id of the instance to set the visibility of.

[page:Boolean visible]: A boolean value indicating the visibility state.

Sets the visibility of the instance at the given index.

[method:this setGeometryIdAt]( [param:Integer instanceId], [param:Integer geometryId] )

[page:Integer instanceId]: The id of the instance to set the geometryIndex of.

[page:Integer geometryId]: The geometryIndex to be use by the instance.

Sets the geometryIndex of the instance at the given index.

[method:Integer addGeometry]( [param:BufferGeometry geometry], [param:Integer reservedVertexRange], [param:Integer reservedIndexRange] )

[page:BufferGeometry geometry]: The geometry to add into the [name].

[page:Integer reservedVertexRange]: Optional parameter specifying the amount of vertex buffer space to reserve for the added geometry. This is necessary if it is planned to set a new geometry at this index at a later time that is larger than the original geometry. Defaults to the length of the given geometry vertex buffer.

[page:Integer reservedIndexRange]: Optional parameter specifying the amount of index buffer space to reserve for the added geometry. This is necessary if it is planned to set a new geometry at this index at a later time that is larger than the original geometry. Defaults to the length of the given geometry index buffer.

Adds the given geometry to the [name] and returns the associated geometry id referring to it to be used in other functions.

[method:Integer deleteGeometry]( [param:Integer geometryId] )

[page:Integer geometryId]: The id of a geometry to remove from the [name] that was previously added via "addGeometry". Any instances referencing this geometry will also be removed as a side effect.

[method:Integer addInstance]( [param:Integer geometryId] )

[page:Integer geometryId]: The id of a previously added geometry via "addGeometry" to add into the [name] to render.

Adds a new instance to the [name] using the geometry of the given geometryId and returns a new id referring to the new instance to be used by other functions.

[method:Integer deleteInstance]( [param:Integer instanceId] )

[page:Integer instanceId]: The id of an instance to remove from the [name] that was previously added via "addInstance".

Removes an existing instance from the [name] using the given instanceId.

[method:Integer setGeometryAt]( [param:Integer geometryId], [param:BufferGeometry geometry] )

[page:Integer geometryId]: Which geometry id to replace with this geometry.

[page:BufferGeometry geometry]: The geometry to substitute at the given geometry id.

Replaces the geometry at `geometryId` with the provided geometry. Throws an error if there is not enough space reserved for geometry. Calling this will change all instances that are rendering that geometry.

[method:this optimize]()

Repacks the sub geometries in [name] to remove any unused space remaining from previously deleted geometry, freeing up space to add new geometry.

[method:this setGeometrySize]( maxVertexCount, maxIndexCount )

Resizes the available space in [name]'s vertex and index buffer attributes to the provided sizes. If the provided arguments shrink the geometry buffers but there is not enough unused space at the end of the geometry attributes then an error is thrown.

[page:Integer maxVertexCount] - the max number of vertices to be used by all unique geometries to resize to.
[page:Integer maxIndexCount] - the max number of indices to be used by all unique geometries to resize to.

[method:this setInstanceCount]( maxInstanceCount )

Resizes the necessary buffers to support the provided number of instances. If the provided arguments shrink the number of instances but there are not enough unused ids at the end of the list then an error is thrown.

[page:Integer maxInstanceCount] - the max number of individual instances that can be added and rendered by the [name].

Source

[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]