API Reference

Class List

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 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.

Parameters

graphicsDevicepc.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.

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

verticesDynamicboolean

Indicates the pc.VertexBuffer should be created with pc.BUFFER_DYNAMIC usage. If not specified, pc.BUFFER_STATIC is used.

indicesDynamicboolean

Indicates the pc.IndexBuffer should be created with pc.BUFFER_DYNAMIC usage. If not specified, pc.BUFFER_STATIC is used.

maxVerticesnumber

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.

maxIndicesnumber

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(colors)

Gets the vertex color data.

Parameters

colorsnumber[], 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

indicesnumber[], 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

normalsnumber[], 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

positionsnumber[], 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

channelnumber

The uv channel in [0..7] range.

uvsnumber[], 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

semanticstring

The semantic of the vertex element to get. For supported semantics, see pc.SEMANTIC_* in pc.VertexFormat.

datanumber[], 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

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

Vertex data containing colors.

componentCountnumber

The number of values that form a single color element. Defaults to 4 if not specified, corresponding to r, g, b and a.

numVerticesnumber

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

colorsnumber[], 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.

numVerticesnumber

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

indicesnumber[], Uint8Array, Uint16Array, Uint32Array

The array of indicies that define primitives (lines, triangles, etc.).

numIndicesnumber

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

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

Vertex data containing normals.

componentCountnumber

The number of values that form a single normal element. Defaults to 3 if not specified, corresponding to x, y and z direction.

numVerticesnumber

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

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

Vertex data containing positions.

componentCountnumber

The number of values that form a single position element. Defaults to 3 if not specified, corresponding to x, y and z coordinates.

numVerticesnumber

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

channelnumber

The uv channel in [0..7] range.

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

Vertex data containing uv-coordinates.

componentCountnumber

The number of values that form a single uv element. Defaults to 2 if not specified, corresponding to u and v coordinates.

numVerticesnumber

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

semanticstring

The meaning of the vertex element. For supported semantics, see pc.SEMANTIC_* in pc.VertexFormat.

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

Vertex data for the specified semantic.

componentCountnumber

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.

numVerticesnumber

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.

dataTypenumber

The format of data when stored in the pc.VertexBuffer, see pc.TYPE_* in pc.VertexFormat. When not specified, pc.TYPE_FLOAT32 is used.

dataTypeNormalizeboolean

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

primitiveTypenumber

The type of primitive to render. Can be one of pc.PRIMITIVE_* - see primitive[].type section above. Defaults to pc.PRIMITIVE_TRIANGLES if unspecified.

updateBoundingBoxboolean

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.