pc.Mesh

A graphical primitive. The mesh is defined by a pc.VertexBuffer and an optional pc.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

pc.Mesh class provides interfaces such as pc.Mesh#setPositions and pc.Mesh#setUvs that provide a simple way to provide vertex and index data for the Mesh, and hiding the complexity of creating the pc.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.

var mesh = new pc.Mesh(device);
var positions = [0, 0, 0,     1, 0, 0,     1, 1, 0];
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.

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

This example demonstrated 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 generaly recommended for per-frame operations or larger meshes, but their construction using new operator is costly operation. If you only need to operate on small number of vertices or indices, consider using the Arrays instead to avoid Type Array allocation overhead.

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 pc.VertexBuffer, pc.IndexBuffer and pc.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.
primitive[].base	The offset of the first index or vertex to dispatch in the draw call.
primitive[].count	The number of indices or vertices to dispatch in the draw call.
primitive[].indexed	True to interpret the primitive as indexed, thereby using the currently set index buffer and false otherwise.
primitive[].type	The type of primitive to render.
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 pc.VertexFormat associated with the mesh.
destroy	Destroys pc.VertexBuffer and pc.IndexBuffer associate with the mesh.
getColors	Gets the index data.
getColors	Gets the vertex color 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.

Parameters

graphicsDevice

pc.GraphicsDevice

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

Properties

pc.BoundingBoxaabb 

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

pc.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 pc.MeshInstances with a renderStyle property set to pc.RENDERSTYLE_SOLID. The second index buffer in the array is used if renderStyle is set to pc.RENDERSTYLE_WIREFRAME.

pc.Morphmorph 

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

object[]primitive 

Array of primitive objects defining how vertex (and index) data in the mesh should be interpreted by the graphics device. For details on the primitive object, see.

numberprimitive[].base 

The offset of the first index or vertex to dispatch in the draw call.

numberprimitive[].count 

The number of indices or vertices to dispatch in the draw call.

booleanprimitive[].indexed 

True to interpret the primitive as indexed, thereby using the currently set index buffer and false otherwise. pc.GraphicsDevice#draw. The primitive is ordered based on render style like the indexBuffer property.

numberprimitive[].type 

The type of primitive to render. Can be:

pc.Skinskin 

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

pc.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 pc.VertexFormat associated with the mesh. This call is typically followed by calls to methods such as pc.Mesh#setPositions, pc.Mesh#setVertexStream or pc.Mesh#setIndices and finally pc.Mesh#update to rebuild the mesh, allowing different pc.VertexFormat.

Parameters

verticesDynamic	boolean	Indicates the pc.VertexBuffer should be created with pc.BUFFER_DYNAMIC usage. If not specified, pc.BUFFER_STATIC is used.
indicesDynamic	boolean	Indicates the pc.IndexBuffer should be created with pc.BUFFER_DYNAMIC usage. If not specified, pc.BUFFER_STATIC is used.
maxVertices	number	pc.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	pc.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 pc.VertexBuffer and pc.IndexBuffer associate with the mesh. This is normally called by pc.Model#destroy and does not need to be called manually.

getColors(indices) 

Gets the index data.

Parameters

indices

number[], Uint8Array, Uint16Array, Uint32Array

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

Returns

number

Returns the number of indices populated.

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.

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 pc.SEMANTIC_* in pc.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 pc.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 pc.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 indicies 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 pc.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 pc.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 pc.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 pc.SEMANTIC_* in pc.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 pc.VertexBuffer, see pc.TYPE_* in pc.VertexFormat. When not specified, pc.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 pc.vertexBuffer or pc.IndexBuffer to fit all provided vertices and indices, and fills them with data.

Parameters

primitiveType	number	The type of primitive to render. Can be one of pc.PRIMITIVE_* - see primitive[].type section above. Defaults to pc.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 pc.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.