BufferGeometry

An efficient representation of mesh, line, or point geometry. Includes vertex positions, face indices, normals, colors, UVs, and custom attributes within buffers, reducing the cost of passing all this data to the GPU.

To read and edit data in BufferGeometry attributes, see BufferAttribute documentation.

For a less efficient but easier-to-use representation of geometry, see Geometry.

Example

var geometry = new v3d.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 v3d.BufferAttribute(vertices, 3)); var material = new v3d.MeshBasicMaterial({ color: 0xff0000 }); var mesh = new v3d.Mesh(geometry, material);

Mesh with non-indexed faces
Mesh with indexed faces
Lines
Indexed Lines
Particles
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 Geometry, the 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 individual attributes. This means that to get the position data associated with a vertex (for instance), you must call .getAttribute to access the 'position' attribute, then access the individual x, y, and z coordinates of the position.

The following attributes are set by various members of this class:

position (itemSize: 3)

Stores the x, y, and z coordinates of each vertex in this geometry. Set by .fromGeometry().

normal (itemSize: 3)

Stores the x, y, and z components of the vertex normal vector of each vertex in this geometry. Set by .fromGeometry().

color (itemSize: 3)

Stores the red, green, and blue channels of vertex color of each vertex in this geometry. Set by .fromGeometry().

In addition to the the built-in attributes, you can set your own custom attributes using the addAttribute method. With Geometry, these attributes are set and stored on the 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

BufferGeometry()

This creates a new BufferGeometry. It also sets several properties to a default value.

Properties

.attributes : Object

This hashmap has as id the name of the attribute to be set and as value the buffer to set it to. Rather than accessing this property directly, use .addAttribute and .getAttribute to access attributes of this geometry.

.boundingBox : Box3

Bounding box for the bufferGeometry, which can be calculated with .computeBoundingBox(). Default is null.

.boundingSphere : Sphere

Bounding sphere for the bufferGeometry, which can be calculated with .computeBoundingSphere(). Default is null.

.drawRange : Object

Used to determine what part of the geometry should be rendered. This should not be set directly, instead use .setDrawRange.
Default is { start: 0, count: Infinity }

.groups : Array

Split the geometry into groups, each of which will be rendered in a separate WebGL draw call. This allows an array of materials to be used with the bufferGeometry.

Each group is an object of the form: { start: Integer, count: Integer, materialIndex: Integer } where start specifies the first element in this draw call – the first vertex for non-indexed geometry, otherwise the first triangle index. Count specifies how many vertices (or indices) are included, and materialIndex specifies the material array index to use.

Use .addGroup to add groups, rather than modifying this array directly.

.id : Integer

Unique number for this bufferGeometry instance.

.index : BufferAttribute

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 Geometry: each triangle is associated with the indices of three vertices. This attribute therefore stores the index of each vertex for each triangular face. If this attribute is not set, the renderer assumes that each three contiguous positions represent a single triangle. Default is null.

.isBufferGeometry : Boolean

Used to check whether this or derived classes are BufferGeometries. Default is true.

You should not change this, as it used internally for optimisation.

.morphAttributes : Object

Hashmap of BufferAttributes holding details of the geometry's morphTargets.

.name : String

Optional name for this bufferGeometry instance. Default is an empty string.

.userData : Object

An object that can be used to store custom data about the BufferGeometry. It should not hold references to functions as these will not be cloned.

.uuid : String

UUID of this object instance. This gets automatically assigned and shouldn't be edited.

Methods

EventDispatcher methods are available on this class.

.addAttribute (name : String, attribute : BufferAttribute) : BufferGeometry

Adds an attribute to this geometry. Use this rather than the attributes property, because an internal hashmap of .attributes is maintained to speed up iterating over attributes.

.addGroup (start : Integer, count : Integer, materialIndex : Integer) : null

Adds a group to this geometry; see the groups property for details.

.applyMatrix (matrix : Matrix4) : null

Bakes matrix transform directly into vertex coordinates.

.center () : BufferGeometry

Center the geometry based on the bounding box.

.clone () : BufferGeometry

Creates a clone of this BufferGeometry.

.copy (bufferGeometry : BufferGeometry) : BufferGeometry

Copies another BufferGeometry to this BufferGeometry.

.clearGroups () : null

Clears all groups.

.computeBoundingBox () : null

Computes bounding box of the geometry, updating .boundingBox attribute.
Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are null.

.computeBoundingSphere () : null

Computes bounding sphere of the geometry, updating .boundingSphere attribute.
Bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are null.

.computeVertexNormals () : null

Computes vertex normals by averaging face normals.

.dispose () : null

Disposes the object from memory.
You need to call this when you want the BufferGeometry removed while the application is running.

.fromDirectGeometry (Geometry : Geometry) : BufferGeometry

Populates this BufferGeometry with data from a DirectGeometry object containing faces. Not implemented for a line geometry.

Note: DirectGeometry is mainly used as an intermediary object for converting between Geometry and BufferGeometry.

.fromGeometry (Geometry : Geometry) : BufferGeometry

Populates this BufferGeometry with data from a Geometry object containing faces. Not implemented for a line geometry.

.getAttribute (name : String) : BufferAttribute

Returns the attribute with the specified name.

.getIndex () : BufferAttribute

Return the .index buffer.

.lookAt (vector : Vector3) : BufferGeometry

vector - A world vector to look at.

Rotates the geometry to face a point in space. This is typically done as a one time operation, and not during a loop. Use Object3D.lookAt for typical real-time mesh usage.

.merge (bufferGeometry : BufferGeometry, offset : Integer) : null

Merge in another BufferGeometry with an optional offset of where to start merging in.

.normalizeNormals () : null

Every normal vector in a geometry will have a magnitude of 1. This will correct lighting on the geometry surfaces.

.removeAttribute (name : String) : BufferAttribute

Removes the attribute with the specified name.

.rotateX (radians : Float) : BufferGeometry

Rotate the geometry about the X axis. This is typically done as a one time operation, and not during a loop. Use Object3D.rotation for typical real-time mesh rotation.

.rotateY (radians : Float) : BufferGeometry

Rotate the geometry about the Y axis. This is typically done as a one time operation, and not during a loop. Use Object3D.rotation for typical real-time mesh rotation.

.rotateZ (radians : Float) : BufferGeometry

Rotate the geometry about the Z axis. This is typically done as a one time operation, and not during a loop. Use Object3D.rotation for typical real-time mesh rotation.

.scale (x : Float, y : Float, z : Float) : BufferGeometry

Scale the geometry data. This is typically done as a one time operation, and not during a loop. Use Object3D.scale for typical real-time mesh scaling.

.setIndex (index : BufferAttribute) : null

Set the .index buffer.

.setDrawRange (start : Integer, count : Integer) : null

Set the .drawRange buffer. See that property for details.

.setFromObject (object : Object3D) : BufferGeometry

Sets the attributes for this BufferGeometry from an Object3D.

.setFromPoints (points : Array) : BufferGeometry

Sets the attributes for this BufferGeometry from an array of points.

.toJSON () : Object

Returns a JSON object representation of the BufferGeometry.

.toNonIndexed () : BufferGeometry

Return a non-index version of an indexed BufferGeometry.

.translate (x : Float, y : Float, z : Float) : BufferGeometry

Translate the geometry. This is typically done as a one time operation, and not during a loop. Use Object3D.position for typical real-time mesh translation.

.updateFromObject (object : Object3D) : BufferGeometry

Updates the attributes for this BufferGeometry from an Object3D.

Source

For more info on how to obtain the source code of this module see this page.