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.
- http://playcanvas.github.io/#graphics/mesh-decals
- http://playcanvas.github.io/#graphics/mesh-deformation
- http://playcanvas.github.io/#graphics/mesh-generation
- http://playcanvas.github.io/#graphics/point-cloud-simulation
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
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.
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.
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
numberReturns 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
numberReturns 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
numberReturns 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
numberReturns 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
numberReturns 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
numberReturns 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. |