Mesh

A graphical primitive. The mesh is defined by a VertexBuffer and an optional IndexBuffer. It also contains a primitive definition which controls the type of the primitive and the portion of the vertex or index buffer to use.

Mesh APIs

There are two ways a mesh can be generated or updated.

Simple Mesh API

Mesh class provides interfaces such as Mesh#setPositions and Mesh#setUvs that provide a simple way to provide vertex and index data for the Mesh, and hiding the complexity of creating the VertexFormat. This is the recommended interface to use.

A simple example which creates a Mesh with 3 vertices, containing position coordinates only, to form a single triangle.

const mesh = new pc.Mesh(device);
const positions = [
    0, 0, 0, // pos 0
    1, 0, 0, // pos 1
    1, 1, 0  // pos 2
];
mesh.setPositions(positions);
mesh.update();

An example which creates a Mesh with 4 vertices, containing position and uv coordinates in channel 0, and an index buffer to form two triangles. Float32Array is used for positions and uvs.

const mesh = new pc.Mesh(device);
const positions = new Float32Array([
    0, 0, 0, // pos 0
    1, 0, 0, // pos 1
    1, 1, 0, // pos 2
    0, 1, 0  // pos 3
]);
const uvs = new Float32Array([
    0, 0, // uv 0
    1, 0, // uv 1
    1, 1, // uv 2
    0, 1  // uv 3
]);
const indices = [
    0, 1, 2, // triangle 0
    0, 2, 3  // triangle 1
];
mesh.setPositions(positions);
mesh.setUvs(0, uvs);
mesh.setIndices(indices);
mesh.update();

This example demonstrates that vertex attributes such as position and normals, and also indices can be provided using Arrays ([]) and also Typed Arrays (Float32Array and similar). Note that typed arrays have higher performance, and are generally recommended for per-frame operations or larger meshes, but their construction using new operator is costly operation. If you only need to operate on a small number of vertices or indices, consider using Arrays to avoid the overhead associated with allocating Typed Arrays.

Follow these links for more complex examples showing the functionality.

Update Vertex and Index buffers

This allows greater flexibility, but is more complex to use. It allows more advanced setups, for example sharing a Vertex or Index Buffer between multiple meshes. See VertexBuffer, IndexBuffer and VertexFormat for details.

Summary

Properties

aabb	The axis-aligned bounding box for the object space vertices of this mesh.
indexBuffer	An array of index buffers.
morph	The morph data (if any) that drives morph target animations for this mesh.
primitive	Array of primitive objects defining how vertex (and index) data in the mesh should be interpreted by the graphics device.
skin	The skin data (if any) that drives skinned mesh animations for this mesh.
vertexBuffer	The vertex buffer holding the vertex data of the mesh.

Methods

clear	Clears the mesh of existing vertices and indices and resets the VertexFormat associated with the mesh.
destroy	Destroys VertexBuffer and IndexBuffer associate with the mesh.
getColors	Gets the vertex color data.
getIndices	Gets the index data.
getNormals	Gets the vertex normals data.
getPositions	Gets the vertex positions data.
getUvs	Gets the vertex uv data.
getVertexStream	Gets the vertex data corresponding to a semantic.
setColors	Sets the vertex color array.
setColors32	Sets the vertex color array.
setIndices	Sets the index array.
setNormals	Sets the vertex normals array.
setPositions	Sets the vertex positions array.
setUvs	Sets the vertex uv array.
setVertexStream	Sets the vertex data for any supported semantic.
update	Applies any changes to vertex stream and indices to mesh.

Details

Constructor

Mesh([graphicsDevice]) 

Create a new Mesh instance.

Parameters

graphicsDevice

GraphicsDevice

The graphics device used to manage this mesh. If it is not provided, a device is obtained from the Application.

Properties

BoundingBoxaabb 

The axis-aligned bounding box for the object space vertices of this mesh.

IndexBuffer[]indexBuffer 

An array of index buffers. For unindexed meshes, this array can be empty. The first index buffer in the array is used by MeshInstances with a renderStyle property set to RENDERSTYLE_SOLID. The second index buffer in the array is used if renderStyle is set to RENDERSTYLE_WIREFRAME.

Morph, nullmorph 

The morph data (if any) that drives morph target animations for this mesh.

{type: number, base: number, count: number, indexed: (boolean|undefined)}[]primitive 

Array of primitive objects defining how vertex (and index) data in the mesh should be interpreted by the graphics device.

type is the type of primitive to render. Can be:
base is the offset of the first index or vertex to dispatch in the draw call.
count is the number of indices or vertices to dispatch in the draw call.
indexed specifies whether to interpret the primitive as indexed, thereby using the currently set index buffer.

Skin, nullskin 

The skin data (if any) that drives skinned mesh animations for this mesh.

VertexBuffervertexBuffer 

The vertex buffer holding the vertex data of the mesh.

Methods

clear([verticesDynamic], [indicesDynamic], [maxVertices], [maxIndices]) 

Clears the mesh of existing vertices and indices and resets the VertexFormat associated with the mesh. This call is typically followed by calls to methods such as Mesh#setPositions, Mesh#setVertexStream or Mesh#setIndices and finally Mesh#update to rebuild the mesh, allowing different VertexFormat.

Parameters

verticesDynamic	boolean	Indicates the VertexBuffer should be created with BUFFER_DYNAMIC usage. If not specified, BUFFER_STATIC is used.
indicesDynamic	boolean	Indicates the IndexBuffer should be created with BUFFER_DYNAMIC usage. If not specified, BUFFER_STATIC is used.
maxVertices	number	A VertexBuffer will be allocated with at least maxVertices, allowing additional vertices to be added to it without the allocation. If no value is provided, a size to fit the provided vertices will be allocated.
maxIndices	number	An IndexBuffer will be allocated with at least maxIndices, allowing additional indices to be added to it without the allocation. If no value is provided, a size to fit the provided indices will be allocated.

destroy() 

Destroys VertexBuffer and IndexBuffer associate with the mesh. This is normally called by Model#destroy and does not need to be called manually.

getColors(colors) 

Gets the vertex color data.

Parameters

colors

number[], Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array

An array to populate with the vertex data. When typed array is supplied, enough space needs to be reserved, otherwise only partial data is copied.

Returns

number

Returns the number of vertices populated.

getIndices(indices) 

Gets the index data.

Parameters

indices

number[], Uint8Array, Uint16Array, Uint32Array

An array to populate with the index data. When a typed array is supplied, enough space needs to be reserved, otherwise only partial data is copied.

Returns

number

Returns the number of indices populated.

getNormals(normals) 

Gets the vertex normals data.

Parameters

normals

number[], Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array

An array to populate with the vertex data. When typed array is supplied, enough space needs to be reserved, otherwise only partial data is copied.

Returns

number

Returns the number of vertices populated.

getPositions(positions) 

Gets the vertex positions data.

Parameters

positions

number[], Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array

An array to populate with the vertex data. When typed array is supplied, enough space needs to be reserved, otherwise only partial data is copied.

Returns

number

Returns the number of vertices populated.

getUvs(channel, uvs) 

Gets the vertex uv data.

Parameters

channel	number	The uv channel in [0..7] range.
uvs	number[], Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array	An array to populate with the vertex data. When typed array is supplied, enough space needs to be reserved, otherwise only partial data is copied.

Returns

number

Returns the number of vertices populated.

getVertexStream(semantic, data) 

Gets the vertex data corresponding to a semantic.

Parameters

semantic	string	The semantic of the vertex element to get. For supported semantics, see SEMANTIC_* in VertexFormat.
data	number[], Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array	An array to populate with the vertex data. When typed array is supplied, enough space needs to be reserved, otherwise only partial data is copied.

Returns

number

Returns the number of vertices populated.

setColors(colors, [componentCount], [numVertices]) 

Sets the vertex color array. Colors are stored using TYPE_FLOAT32 format, which is useful for HDR colors.

Parameters

colors	number[], Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array	Vertex data containing colors.
componentCount	number	The number of values that form a single color element. Defaults to 4 if not specified, corresponding to r, g, b and a.
numVertices	number	The number of vertices to be used from data array. If not provided, the whole data array is used. This allows to use only part of the data array.

setColors32(colors, [numVertices]) 

Sets the vertex color array. Colors are stored using TYPE_UINT8 format, which is useful for LDR colors. Values in the array are expected in [0..255] range, and are mapped to [0..1] range in the shader.

Parameters

colors	number[], Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array	Vertex data containing colors. The array is expected to contain 4 components per vertex, corresponding to r, g, b and a.
numVertices	number	The number of vertices to be used from data array. If not provided, the whole data array is used. This allows to use only part of the data array.

setIndices(indices, [numIndices]) 

Sets the index array. Indices are stored using 16-bit format by default, unless more than 65535 vertices are specified, in which case 32-bit format is used.

Parameters

indices	number[], Uint8Array, Uint16Array, Uint32Array	The array of indices that define primitives (lines, triangles, etc.).
numIndices	number	The number of indices to be used from data array. If not provided, the whole data array is used. This allows to use only part of the data array.

setNormals(normals, [componentCount], [numVertices]) 

Sets the vertex normals array. Normals are stored using TYPE_FLOAT32 format.

Parameters

normals	number[], Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array	Vertex data containing normals.
componentCount	number	The number of values that form a single normal element. Defaults to 3 if not specified, corresponding to x, y and z direction.
numVertices	number	The number of vertices to be used from data array. If not provided, the whole data array is used. This allows to use only part of the data array.

setPositions(positions, [componentCount], [numVertices]) 

Sets the vertex positions array. Vertices are stored using TYPE_FLOAT32 format.

Parameters

positions	number[], Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array	Vertex data containing positions.
componentCount	number	The number of values that form a single position element. Defaults to 3 if not specified, corresponding to x, y and z coordinates.
numVertices	number	The number of vertices to be used from data array. If not provided, the whole data array is used. This allows to use only part of the data array.

setUvs(channel, uvs, [componentCount], [numVertices]) 

Sets the vertex uv array. Uvs are stored using TYPE_FLOAT32 format.

Parameters

channel	number	The uv channel in [0..7] range.
uvs	number[], Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array	Vertex data containing uv-coordinates.
componentCount	number	The number of values that form a single uv element. Defaults to 2 if not specified, corresponding to u and v coordinates.
numVertices	number	The number of vertices to be used from data array. If not provided, the whole data array is used. This allows to use only part of the data array.

setVertexStream(semantic, data, componentCount, [numVertices], [dataType], [dataTypeNormalize]) 

Sets the vertex data for any supported semantic.

Parameters

semantic	string	The meaning of the vertex element. For supported semantics, see SEMANTIC_* in VertexFormat.
data	number[], Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array	Vertex data for the specified semantic.
componentCount	number	The number of values that form a single Vertex element. For example when setting a 3D position represented by 3 numbers per vertex, number 3 should be specified.
numVertices	number	The number of vertices to be used from data array. If not provided, the whole data array is used. This allows to use only part of the data array.
dataType	number	The format of data when stored in the VertexBuffer, see TYPE_* in VertexFormat. When not specified, TYPE_FLOAT32 is used.
dataTypeNormalize	boolean	If true, vertex attribute data will be mapped from a 0 to 255 range down to 0 to 1 when fed to a shader. If false, vertex attribute data is left unchanged. If this property is unspecified, false is assumed.

update([primitiveType], [updateBoundingBox]) 

Applies any changes to vertex stream and indices to mesh. This allocates or reallocates vertexBuffer or IndexBuffer to fit all provided vertices and indices, and fills them with data.

Parameters

primitiveType

number

The type of primitive to render. Can be:

Defaults to PRIMITIVE_TRIANGLES if unspecified.

updateBoundingBox

boolean

True to update bounding box. Bounding box is updated only if positions were set since last time update was called, and componentCount for position was 3, otherwise bounding box is not updated. See Mesh#setPositions. Defaults to true if unspecified. Set this to false to avoid update of the bounding box and use aabb property to set it instead.