[name]
This class is an efficient alternative to [page:Geometry], because it stores all data, including
vertex positions, face indices, normals, colors, UVs, and custom attributes within buffers; this
reduces the cost of passing all this data to the GPU.
This also makes BufferGeometry harder to work with than [page:Geometry]; rather than accessing
position data as [page:Vector3] objects, color data as [page:Color] objects, and so on, you have to
access the raw data from the appropriate [page:BufferAttribute attribute] buffer. This makes
BufferGeometry best-suited for static objects where you don't need to manipulate the geometry much
after instantiating it.
Example
var geometry = new THREE.BufferGeometry();
// create a simple square shape. We duplicate the top left and bottom right
// vertices because each vertex needs to appear once per triangle.
var vertices = new Float32Array( [
-1.0, -1.0, 1.0,
1.0, -1.0, 1.0,
1.0, 1.0, 1.0,
1.0, 1.0, 1.0,
-1.0, 1.0, 1.0,
-1.0, -1.0, 1.0
] );
// itemSize = 3 because there are 3 values (components) per vertex
geometry.addAttribute( 'position', new THREE.BufferAttribute( vertices, 3 ) );
var material = new THREE.MeshBasicMaterial( { color: 0xff0000 } );
var mesh = new THREE.Mesh( geometry, material );
More examples: [example:webgl_buffergeometry Complex mesh with non-indexed faces], [example:webgl_buffergeometry_uint Complex mesh with indexed faces], [example:webgl_buffergeometry_lines Lines], [example:webgl_buffergeometry_lines_indexed Indexed Lines], [example:webgl_buffergeometry_custom_attributes_particles Particles], and [example:webgl_buffergeometry_rawshader Raw Shaders].
Accessing attributes
WebGL stores data associated with individual vertices of a geometry in attributes.
Examples include the position of the vertex, the normal vector for the vertex, the vertex color,
and so on. When using [page:Geometry], the [page:WebGLRenderer renderer] takes care of wrapping
up this information into typed array buffers and sending this data to the shader. With
BufferGeometry, all of this data is stored in buffers associated with an individual attributes.
This means that to get the position data associated with a vertex (for instance), you must call
[page:.getAttribute] to access the 'position' [page:BufferAttribute attribute], then access the individual
x, y, and z coordinates of the position.
The following attributes are set by various members of this class:
[page:BufferAttribute position] (itemSize: 3)
Stores the x, y, and z coordinates of each vertex in this geometry. Set by [page:.fromGeometry]().
[page:BufferAttribute normal] (itemSize: 3)
Stores the x, y, and z components of the face or vertex normal vector of each vertex in this geometry.
Set by [page:.fromGeometry]().
[page:BufferAttribute color] (itemSize: 3)
Stores the red, green, and blue channels of vertex color of each vertex in this geometry.
Set by [page:.fromGeometry]().
[page:BufferAttribute index] (itemSize: 1)
Allows for vertices to be re-used across multiple triangles; this is called using "indexed triangles," and works much the same as it does in [page:Geometry]: each triangle is associated with the index of three vertices. This attribute therefore stores the index of each vertex for each triangular face.
If this attribute is not set, the [page:WebGLRenderer renderer] assumes that each three contiguous positions represent a single triangle.
In addition to the the built-in attributes, you can set your own custom attributes using the addAttribute method. With [page:Geometry], these attributes are set and stored on the [page:Material]. In BufferGeometry, the attributes are stored with the geometry itself. Note that you still need to set the attributes information on the material as well, but the value of each attribute is stored in the BufferGeometry.
Constructor
[name]()
This creates a new [name]. It also sets several properties to a default value.
Properties
[property:Integer id]
Unique number for this buffergeometry instance.
[property:Hashmap attributes]
This hashmap has as id the name of the attribute to be set and as value the [page:BufferAttribute buffer] to set it to.
Rather than accessing this property directly, use addAttribute and getAttribute to access attributes of this geometry.
[property:Array drawcalls] (previously [property:Array offsets])
For geometries that use indexed triangles, this Array can be used to split the object into multiple WebGL draw calls. Each draw call will draw some subset of the vertices in this geometry using the configured [page:Material shader]. This may be necessary if, for instance, you have more than 65535 vertices in your object.
Each element is an object of the form:
{ start: Integer, count: Integer, index: Integer }
where start specifies the index of the first vertex in this draw call, count specifies how many vertices are included, and index specifies an optional offset.
Use addDrawCall to add draw calls, rather than modifying this array directly.
[property:Box3 boundingBox]
Bounding box.
{ min: new THREE.Vector3(), max: new THREE.Vector3() }
[property:Sphere boundingSphere]
Bounding sphere.
{ radius: float }
Methods
[page:EventDispatcher EventDispatcher] methods are available on this class.
[property:null addAttribute]( [page:String name], [page:BufferAttribute attribute] )
Adds an attribute to this geometry. Use this rather than the attributes property,
because an internal array of attributes is maintained to speed up iterating over
attributes.
[method:null addDrawCall]( [page:Integer start], [page:Integer count], [page:Integer indexOffset] )
Adds a draw call to this geometry; see the [page:BufferGeometry.drawcalls drawcalls] property for details.
[method:null clearDrawCalls]( )
Clears all draw calls.
[method:null applyMatrix]( [page:Matrix4 matrix] )
Bakes matrix transform directly into vertex coordinates.
[method:null center] ()
Center the geometry based on the bounding box.
[method:BufferGeometry rotateX] ( [page:Float radians] )
Rotate the geometry about the X axis. This is typically done as a one time operation, and not during a loop
Use [page:Object3D.rotation] for typical real-time mesh rotation.
[method:BufferGeometry rotateY] ( [page:Float radians] )
Rotate the geometry about the Y axis. This is typically done as a one time operation, and not during a loop
Use [page:Object3D.rotation] for typical real-time mesh rotation.
[method:BufferGeometry rotateZ] ( [page:Float radians] )
Rotate the geometry about the Z axis. This is typically done as a one time operation, and not during a loop
Use [page:Object3D.rotation] for typical real-time mesh rotation.
[method:BufferGeometry translate] ( [page:Float x], [page:Float y], [page:Float z] )
Translate the geometry. This is typically done as a one time operation, and not during a loop
Use [page:Object3D.position] for typical real-time mesh translation.
[method:BufferGeometry scale] ( [page:Float x], [page:Float y], [page:Float z] )
Scale the geometry data. This is typically done as a one time operation, and not during a loop
Use [page:Object3D.scale] for typical real-time mesh scaling.
[method:BufferGeometry lookAt] ( [page:Vector3 vector] )
vector - A world vector to look at.
Rotates the geometry to face point in space. This is typically done as a one time operation, and not during a loop
Use [page:Object3D.lookAt] for typical real-time mesh usage.
[method:BufferGeometry setFromObject] ( [page:Object3D object] )
Sets the attributes for this BufferGeometry from an [page:Object3D].
[method:null computeVertexNormals]()
Computes vertex normals by averaging face normals.
[method:null computeBoundingBox]()
Computes bounding box of the geometry, updating [page:Geometry Geometry.boundingBox] attribute.
Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are *null*.
[method:null computeBoundingSphere]()
Computes bounding sphere of the geometry, updating [page:Geometry Geometry.boundingSphere] attribute.
Bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are *null*.
[method:null computeOffsets] ( [page:Integer size] )
Compute the draw offset for large models by chunking the index buffer into chunks of 65k addressable vertices.
This method will effectively rewrite the index buffer and remap all attributes to match the new indices.
WARNING: This method will also expand the vertex count to prevent sprawled triangles across draw offsets.
size - Defaults to 65535 or 4294967296 if extension OES_element_index_uint supported, but allows for larger or smaller chunks.
[method:null merge]( [page:BufferGeometry bufferGeometry], [page:Integer offset] )
Merge in another BufferGeometry with an optional offset of where to start merging in.
[method:null dispose]()
Disposes the object from memory.
You need to call this when you want the bufferGeometry removed while the application is running.
[method:null fromGeometry]( [page:Geometry] )
Populates this BufferGeometry with data from a [page:Geometry] object.
[method:BufferAttribute getAttribute]( [page:String name] )
Returns the [page:BufferAttribute attribute] with the specified name.
[method:BufferAttribute removeAttribute]( [page:String name] )
Removes the [page:BufferAttribute attribute] with the specified name.
[method:null normalizeNormals]()
Every normal vector in a geometry will have a magnitude of 1.
This will correct lighting on the geometry surfaces.
[method:Object toJSON]()
Returns a raw object representation of the BufferGeometry.
[method:BufferGeometry clone]()
Creates a clone of this BufferGeometry.
[method:BufferGeometry copy]( [page:BufferGeometry bufferGeometry] )
Copies another BufferGeometry to this BufferGeometry.
Source
[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]