H3DU.MeshBuffer

Back to documentation index.

new H3DU.MeshBuffer()

A geometric mesh in the form of buffer objects. A mesh buffer is made up of one or more vertex attribute objects, and an optional array of vertex indices. Each vertex attribute object contains the values of one attribute of the mesh, such as positions, vertex normals, and texture coordinates. A mesh buffer can store vertices that make up triangles, line segments, or points.

This constructor creates an empty mesh buffer and sets the array of vertex indices to null.

The MeshBuffer class contains four methods (fromPositions, fromPositionsNormals, fromPositionsUV, and fromPositionsNormalsUV) that let you define a mesh buffer from a predefined array of vertex data. See the documentation for those methods for more information.

The Meshes class includes several handy methods for creating built-in shapes; those methods return a H3DU.MeshBuffer object that describes the triangles they are composed of.

Instancing

Some 3D rendering pipelines support instancing, which is a technique for rendering multiple versions of a mesh buffer with a single draw call. Instancing involves the use of a second mesh buffer (an instance buffer); rather than holding vertex data, the instance buffer holds instance data, that is, data to be used when rendering each instance of the first mesh buffer. Besides this, however, instance buffers are largely similar to vertex buffers as far as the MeshBuffer class is concerned; any reference to vertices in the documentation applies analogously to instances in instance buffers. However, instance buffers should use the primitive type MeshBuffer.POINTS; it makes little sense to have instance buffers describe triangles or line segments.

Examples

The following example converts a MeshBuffer object to three.js buffer geometries (and thus serves as a bridge between this library and three.js). Pass the return value to the THREE.Mesh, THREE.LineSegments, or THREE.Points constructor to generate the appropriate kind of shape object depending on the MeshBuffer's primitive type. This example requires the three.js library.

function toBufferGeometry(mesh) {
var p=mesh.getAttribute("POSITION")
var n=mesh.getAttribute("NORMAL")
var t=mesh.getAttribute("TEXCOORD_0")
var c=mesh.getAttribute("COLOR")
var ind=mesh.getIndices()
var geom=new THREE.BufferGeometry()
var attributes=[p,n,t,c]
var attributeNames=["position","normal","uv","color"]
for(var i=0;i<attributes.length;i++) {
if(attributes[i]) {
var a=attributes[i]
//console.log(a)
var attr=new THREE.InterleavedBufferAttribute(
new THREE.InterleavedBuffer(a.buffer,a.stride),
a.countPerValue,a.offset)
geom.addAttribute(attributeNames[i],attr)
}
}
if(ind)geom.index=new THREE.BufferAttribute(
ind,1)
return geom
}

Members

Methods

H3DU.MeshBuffer.LINES (constant)

TODO: Not documented yet.

H3DU.MeshBuffer.POINTS (constant)

TODO: Not documented yet.

H3DU.MeshBuffer.TRIANGLES (constant)

TODO: Not documented yet.

(static) H3DU.MeshBuffer.fromPositions(vertices, [indices])

Creates a new mesh buffer with the given array of vertex positions.

Parameters

Return Value

A new mesh buffer. (Type: MeshBuffer)

Examples

The following example shows how to define a mesh buffer from a predefined array of vertex positions.

// First, create an array of numbers giving the X, Y, and
// Z coordinate for each vertex position. Here, three vertices
// are defined.
var vertices = [x1, y1, z1, x2, y2, z2, x3, y3, z3 ];
// Second -- and this is optional -- create a second array of numbers
// giving the indices to vertices defined in the previous step.
// Each index refers to the (n+1)th vertex; since 3 vertices
// were defined, the highest index is 2.
var indices = [0, 1, 2];
// Finally, create the mesh buffer. (If there are no indices,
// leave out the "indices" argument.)
var meshBuffer=MeshBuffer.fromPositions(vertices, indices);

(static) H3DU.MeshBuffer.fromPositionsNormals(vertices, [indices])

Creates a new mesh buffer with the given array of vertex positions and vertex normals.

Parameters

Return Value

A new mesh buffer. (Type: MeshBuffer)

Examples

The following example shows how to define a mesh buffer from a predefined array of vertex positions and normals.

// First, create an array of numbers giving the X, Y, and
// Z coordinate for each vertex position and normal. Here, three vertices
// are defined. For each vertex, the position is given, followed by
// the normal.
var vertices = [
x1, y1, z1, nx1, ny1, nz1,
x2, y2, z2, nx2, ny2, nz2,
x3, y3, z3, nx3, ny3, nz3 ];
// Second -- and this is optional -- create a second array of numbers
// giving the indices to vertices defined in the previous step.
// Each index refers to the (n+1)th vertex; since 3 vertices
// were defined, the highest index is 2.
var indices = [0, 1, 2];
// Finally, create the mesh buffer. (If there are no indices,
// leave out the "indices" argument.)
var meshBuffer=MeshBuffer.fromPositionsNormals(vertices, indices);

(static) H3DU.MeshBuffer.fromPositionsNormalsUV(vertices, [indices])

Creates a new mesh buffer with the given array of vertex positions, vertex normals, and texture coordinates.

Parameters

Return Value

A new mesh buffer. (Type: MeshBuffer)

Examples

The following example shows how to define a mesh buffer from a predefined array of vertex positions, normals, and texture cordinates.

// First, create an array of numbers giving the X, Y, and
// Z coordinate for each vertex position, normal, and associated
// texture coordinates. Here, three vertices
// are defined. For each vertex, the position is given, followed by
// the normal, followed by the texture coordinates.
var vertices = [
x1, y1, z1, nx1, ny1, nz1, u1, v1,
x2, y2, z2, nx2, ny2, nz2, u2, v2,
x3, y3, z3, nx3, ny3, nz3, u3, v3 ];
// Second -- and this is optional -- create a second array of numbers
// giving the indices to vertices defined in the previous step.
// Each index refers to the (n+1)th vertex; since 3 vertices
// were defined, the highest index is 2.
var indices = [0, 1, 2];
// Finally, create the mesh buffer. (If there are no indices,
// leave out the "indices" argument.)
var meshBuffer=MeshBuffer.fromPositionsNormalsUV(vertices, indices);

(static) H3DU.MeshBuffer.fromPositionsUV(vertices, [indices])

Creates a new mesh buffer with the given array of vertex positions and texture coordinates.

Parameters

Return Value

A new mesh buffer. (Type: MeshBuffer)

Examples

The following example shows how to define a mesh buffer from a predefined array of vertex positions, normals, and texture cordinates.

// First, create an array of numbers giving the X, Y, and
// Z coordinate for each vertex position and associated
// texture coordinates. Here, three vertices
// are defined. For each vertex, the position is given, followed by
// the texture coordinates.
var vertices = [
x1, y1, z1, u1, v1,
x2, y2, z2, u2, v2,
x3, y3, z3, u3, v3 ];
// Second -- and this is optional -- create a second array of numbers
// giving the indices to vertices defined in the previous step.
// Each index refers to the (n+1)th vertex; since 3 vertices
// were defined, the highest index is 2.
var indices = [0, 1, 2];
// Finally, create the mesh buffer. (If there are no indices,
// leave out the "indices" argument.)
var meshBuffer=MeshBuffer.fromPositionsUV(vertices, indices);

H3DU.MeshBuffer#getAttribute(name, [semanticIndex])

Gets a vertex attribute included in this mesh buffer.

Parameters

Return Value

A vertex buffer accessor, or null if the attribute doesn't exist. (Type: BufferAccessor)

Examples

The following function gets the positions, normals, texture coordinates and colors of each primitive (line, text, or point) in the mesh buffer. A point will have one vertex per primitive, a line two vertices and a triangle three. The attributes, if present, will be stored in the "position", "normal", "uv", and "color" properties of each vertex.

function getPrimitives(mesh) {
var p=mesh.getAttribute("POSITION")
var n=mesh.getAttribute("NORMAL")
var t=mesh.getAttribute("TEXCOORD_0")
var c=mesh.getAttribute("COLOR")
var count=mesh.vertexCount()
var primSize = 3;
if(mesh.primitiveType() === MeshBuffer.LINES)
primSize = 2;
if(mesh.primitiveType() === MeshBuffer.POINTS)
primSize = 1;
var ret=[]
for(var i=0;i<ind.length;i+=primSize) {
var prim=[]
var index=mesh.getIndex(i)
for(var j=0;j<primSize;j++) {
var info={}
if(p)info.position=p.getVec(index,[])
if(n)info.normal=n.getVec(index,[])
if(t)info.uv=t.getVec(index,[])
if(c)info.color=c.getVec(index,[])
}
ret.push(prim)
}
return ret
}

H3DU.MeshBuffer#getBounds()

Finds the tightest bounding box that holds all vertices in the mesh buffer. Only positions with attribute semantic POSITION are used in the bounding box calculation.

Return Value

An array of six numbers describing the tightest axis-aligned bounding box that fits all vertices in the mesh. The first three numbers are the smallest-valued X, Y, and Z coordinates, and the last three are the largest-valued X, Y, and Z coordinates. This calculation uses the attribute with the semantic POSITION and set index 0. If there is no such attribute, or no vertices are defined in this buffer, returns the array [Inf, Inf, Inf, -Inf, -Inf, -Inf]. (Type: Array.<number>)

H3DU.MeshBuffer#getIndex(indicesIndex)

TODO: Not documented yet.

Parameters

Return Value

TODO: Not documented yet. (Type: *)

H3DU.MeshBuffer#getIndices()

Gets the array of vertex indices used by this mesh buffer.

Return Value

Return value. (Type: Uint16Array | Uint32Array | Uint8Array)

H3DU.MeshBuffer#getPositions()

Gets an array of vertex positions held by this mesh buffer, arranged by primitive. Only values with the attribute semantic POSITION_0 are returned.

Return Value

An array of primitives, each of which holds the vertices that make up that primitive. If this mesh holds triangles, each primitive will contain three vertices; if lines, two; and if points, one. Each vertex is an array containing that vertex's coordinates (for example, if the attribute holds 3 elements per value, the coordinates are X, Y, and Z coordinates, in that order). (Type: Array.<Array.<number>>)

(static) H3DU.MeshBuffer.lineLoopIndices(vertexCount)

Creates an array of vertex indices corresponding to triangles that make up a line loop, a series of vertices that make up a connected line segment path, with the last point also connected to the first.

Parameters

Return Value

Array of vertex indices corresponding to line segments that make up the line loop. Every two indices in the array is a separate line segment. Returns an empty array if 'vertexCount' is less than 2. (Type: Array.<number>)

Examples

The following example sets appropriate indices for a mesh buffer with vertices ordered in line loop vertex order.

mesh.setIndices(
MeshBuffer.lineLoopIndices(mesh.vertexCount())
.map(x=>mesh.getIndex(x)));

(static) H3DU.MeshBuffer.lineStripIndices(vertexCount)

Creates an array of vertex indices corresponding to triangles that make up a line strip, a series of vertices that make up a connected line segment path.

Parameters

Return Value

Array of vertex indices corresponding to line segments that make up the line strip. Every two indices in the array is a separate line segment. Returns an empty array if 'vertexCount' is less than 2. (Type: Array.<number>)

Examples

The following example sets appropriate indices for a mesh buffer with vertices ordered in line strip vertex order.

mesh.setIndices(
MeshBuffer.lineStripIndices(mesh.vertexCount())
.map(x=>mesh.getIndex(x)));

H3DU.MeshBuffer#merge(other)

Merges the vertices from another mesh into this one. The vertices from the other mesh will be copied into this one, and the other mesh's indices copied or adapted.

Parameters

Return Value

This object. (Type: MeshBuffer)

Examples

var copiedMesh = new MeshBuffer().merge(meshToCopy);

H3DU.MeshBuffer#normalizeNormals()

Modifies this mesh buffer by converting the normals it defines to unit vectors ("normalized" vectors with a length of 1). Has no effect if this mesh buffer doesn't define any normals. All attributes with the semantic NORMAL, regardless of semantic index, are affected.

Return Value

This object. (Type: MeshBuffer)

H3DU.MeshBuffer#primitiveCount()

Gets the number of primitives (triangles, lines, and points) composed by all shapes in this mesh.

Return Value

Return value. (Type: number)

H3DU.MeshBuffer#primitiveType()

Gets the type of primitive stored in this mesh buffer.

Return Value

Either MeshBuffer.TRIANGLES, MeshBuffer.LINES, or MeshBuffer.POINTS. (Type: number)

(static) H3DU.MeshBuffer.quadStripIndices(vertexCount)

Creates an array of vertex indices corresponding to triangles that make up a strip of quadrilaterals. For a quadrilateral strip, the first 4 vertices make up the first quadrilateral, and each additional quadrilateral is made up of the last 2 vertices of the previous quadrilateral and 2 new vertices.

Parameters

Return Value

Array of vertex indices corresponding to triangles that make up the quadrilateral strip. Every three indices in the array is a separate triangle. Returns an empty array if 'vertexCount' is less than 4. If 'vertexCount' is not divisible by 2, the excess vertex is ignored. (Type: Array.<number>)

Examples

The following example sets appropriate indices for a mesh buffer with vertices ordered in quadrilateral strip vertex order.

mesh.setIndices(
MeshBuffer.quadStripIndices(mesh.vertexCount())
.map(x=>mesh.getIndex(x)));

(static) H3DU.MeshBuffer.quadsIndices(vertexCount)

Creates an array of vertex indices corresponding to triangles that make up a series of quadrilaterals, where every 4 vertices is a separate quadrilateral.

Parameters

Return Value

Array of vertex indices corresponding to triangles that make up the quadrilaterals. Every three indices in the array is a separate triangle. Returns an empty array if 'vertexCount' is less than 4. If 'vertexCount' is not divisible by 4, any excess vertices are ignored. (Type: Array.<number>)

Examples

The following example sets appropriate indices for a mesh buffer with vertices ordered in quadrilateral vertex order.

mesh.setIndices(
MeshBuffer.quadsIndices(mesh.vertexCount())
.map(x=>mesh.getIndex(x)));

H3DU.MeshBuffer#recalcNormals([flat], [inward])

Recalculates the normal vectors (directions that generally point up and away from the mesh buffer's surface) for triangles in this mesh buffer, in order to give the shape described by this buffer a flat or smooth appearance or to shade the shape from the inside or the outside upon rendering.

Each normal calculated will be normalized to have a length of 1 (unless the normal is (0,0,0)), and will be stored in an attribute with semantic NORMAL_0.

This method will have an effect only if the buffer includes an attribute with semantic POSITION_0 and each of that attribute's values is at least 3 elements long. If the buffer already includes an attribute with semantic NORMAL_0, ensures its values are each at least 3 elements long.

For normal calculation to properly affect shading:

Parameters

Return Value

This object. (Type: MeshBuffer)

Examples

// Use flat shading, and shape is shaded from the outside
meshBuffer.recalcNormals(true, false);
// Both parameters can be omitted, setting both to false
meshBuffer.recalcNormals();

H3DU.MeshBuffer#reverseNormals()

Modifies this mesh buffer by reversing the sign of normals it defines. Has no effect if this mesh buffer doesn't define any normals. All attributes with the semantic NORMAL, regardless of semantic index, are affected.

Return Value

This object. (Type: MeshBuffer)

Examples

The following code generates a two-sided mesh, where the normals on each side face in the opposite direction. This is only useful when drawing open geometric shapes, such as open cylinders and two-dimensional planar shapes. Due to the z-fighting effect, drawing a two-sided mesh is recommended only if face culling is enabled.

var twoSidedMesh = originalMesh.merge(
new MeshBuffer().merge(originalMesh)
.reverseWinding().reverseNormals()
);

H3DU.MeshBuffer#reverseWinding()

Reverses the winding order of the triangles in this mesh buffer by swapping the second and third vertex indices of each one. Has an effect only if this mesh buffer consists of triangles.

Return Value

This object. (Type: MeshBuffer)

Examples

The following code generates a mesh that survives face culling, since the same triangles occur on each side of the mesh, but with different winding orders. This is only useful when drawing open geometric shapes, such as open cylinders and two-dimensional planar shapes. Due to the z-fighting effect, drawing this kind of mesh is recommended only if face culling is enabled.

var frontBackMesh = originalMesh.merge(
new MeshBuffer().merge(originalMesh).reverseWinding()
);

H3DU.MeshBuffer#setAttribute(name, buffer, countPerValue, [offset], [stride])

Adds information about a buffer attribute to this mesh buffer (or sets an existing attribute's information). An attribute gives information about the per-vertex data used and stored in a vertex buffer.

Parameters

Return Value

This object. Throws an error if the given semantic is unsupported. (Type: MeshBuffer)

H3DU.MeshBuffer#setAttributeEx(name, index, buffer, [countPerValue], [offset], [stride])

Adds information about a buffer attribute to this mesh buffer (or sets an existing attribute's information), taking a semantic index as an additional parameter. An attribute gives information about the per-vertex data used and stored in a vertex buffer.

Parameters

Return Value

This object.Throws an error if the given semantic is unsupported. (Type: MeshBuffer)

H3DU.MeshBuffer#setColor(color)

Sets all the vertices in this mesh to the given color, by assigning each value with the attribute semantic COLOR to the given color. (If the attribute's count per value is less than 4, each such value will be set to as many elements of the converted 4-element color as possible.) If an attribute with the semantic COLOR doesn't exist, an attribute with the semantic COLOR_0 and a count per value of 3 is created.

All attributes with the semantic COLOR, regardless of semantic index, are affected by this method.

Parameters

Return Value

This object. (Type: MeshBuffer)

H3DU.MeshBuffer#setIndices([indices])

Sets the vertex indices used by this mesh buffer.

Parameters

Return Value

This object. (Type: MeshBuffer)

H3DU.MeshBuffer#setType(primType)

Sets the type of graphics primitives stored in this mesh buffer.

Parameters

Return Value

This object. (Type: MeshBuffer)

H3DU.MeshBuffer#transform(matrix)

Transforms the positions and normals of all the vertices currently in this mesh, with the help of a 4x4 matrix. Only values with the attribute semantic POSITION_0 or NORMAL_0 will be affected by this method; values of other attributes will be unaffected.

Parameters

Return Value

This object. (Type: MeshBuffer)

Examples

The following example transforms positions and normals to move the mesh 2 units to the right.

mesh.transform(MathUtil.mat4translated(2, 0, 0));

The following example transforms positions and normals to double the mesh's size.

mesh.transform(MathUtil.mat4scaled(2, 2, 2));

(static) H3DU.MeshBuffer.triangleFanIndices(vertexCount)

Creates an array of vertex indices corresponding to triangles that make up a triangle fan or convex polygon. For triangle fans and convex polygons, the first 3 vertices make up the first triangle, and each additional triangle is made up of the last vertex, the first vertex of the first trangle, and 1 new vertex.

Parameters

Return Value

Array of vertex indices corresponding to triangles that make up the triangle fan or convex polygon. Every three indices in the array is a separate triangle. Returns an empty array if 'vertexCount' is less than 3. (Type: Array.<number>)

Examples

The following example sets appropriate indices for a mesh buffer with vertices ordered in triangle fan vertex order.

mesh.setIndices(
MeshBuffer.triangleFanIndices(mesh.vertexCount())
.map(x=>mesh.getIndex(x)));

(static) H3DU.MeshBuffer.triangleStripIndices(vertexCount)

Creates an array of vertex indices corresponding to triangles that make up a triangle strip. For a triangle strip, the first 3 vertices make up the first triangle, and each additional triangle is made up of the last 2 vertices and 1 new vertex.

Parameters

Return Value

Array of vertex indices corresponding to triangles that make up the triangle strip. Every three indices in the array is a separate triangle. Returns an empty array if 'vertexCount' is less than 3. (Type: Array.<number>)

Examples

The following example sets appropriate indices for a mesh buffer with vertices ordered in triangle strip vertex order.

mesh.setIndices(
MeshBuffer.triangleStripIndices(mesh.vertexCount())
.map(x=>mesh.getIndex(x)));

H3DU.MeshBuffer#vertexCount()

Gets the number of vertices in this mesh buffer, that is, the number of vertex indices in its index buffer (some of which may be duplicates), or if there is no index buffer, the lowest maximum number of items that a buffer attribute can hold.

Return Value

Return value. (Type: number)

H3DU.MeshBuffer#vertexIndices(primitiveIndex, ret)

Gets the vertex indices of a given primitive (triangle, line, or point) in this mesh buffer.

Parameters

Return Value

The parameter "ret". (Type: Array.<number>)

H3DU.MeshBuffer#wireFrame()

Converts the triangles in this mesh to line segments. Has no effect if this mesh doesn't use triangles as primitives.

Return Value

This object. (Type: MeshBuffer)

Back to documentation index.