Class 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, 1  // uv 3
    1, 1, // uv 2
    1, 0, // uv 1
    0, 0, // uv 0
]);
const indices = [
    0, 1, 2, // triangle 0
    0, 2, 3  // triangle 1
];
mesh.setPositions(positions);
mesh.setNormals(pc.calculateNormals(positions, indices));
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.

Hierarchy

RefCountedObject
- Mesh

Index

Constructors

constructor

new Mesh(graphicsDevice, options?): Mesh
Create a new Mesh instance.
Parameters
- graphicsDevice: GraphicsDevice
  The graphics device used to manage this mesh.
- Optional options: {
  storageIndex: boolean;
  storageVertex: boolean;
  }
  Object for passing optional arguments.
  - storageIndex: boolean
    Defines if the index buffer can be used as a storage buffer by a compute shader. Defaults to false. Only supported on WebGPU.
  - storageVertex: boolean
    Defines if the vertex buffer can be used as a storage buffer by a compute shader. Defaults to false. Only supported on WebGPU.
Returns Mesh
Overrides RefCountedObject.constructor
- Defined in engine/src/scene/mesh.js:209

Properties

`Private` _aabb

_aabb: BoundingBox = ...

aabb representing object space bounds of the mesh.

`Private` _storageIndex

_storageIndex: boolean = false

True if the created index buffer should be accessible as a storage buffer in compute shader.

`Private` _storageVertex

_storageVertex: boolean = false

True if the created vertex buffer should be accessible as a storage buffer in compute shader.

indexBuffer

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.

primitive

primitive: {
    base: number;
    count: number;
    indexed?: boolean;
    type: number;
}[]

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.

Type declaration

base: number
count: number
Optional indexed?: boolean
type: number

skin

skin: Skin

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

vertexBuffer

vertexBuffer: VertexBuffer

The vertex buffer holding the vertex data of the mesh.

Accessors

aabb

get aabb(): BoundingBox
Returns BoundingBox
- Defined in engine/src/scene/mesh.js:369
set aabb(aabb): void
The axis-aligned bounding box for the object space vertices of this mesh.
Parameters
- aabb: BoundingBox
Returns void
- Defined in engine/src/scene/mesh.js:364

morph

get morph(): any
Returns any
- Defined in engine/src/scene/mesh.js:355
set morph(morph): void
The morph data (if any) that drives morph target animations for this mesh.
Parameters
- morph: any
Returns void
- Defined in engine/src/scene/mesh.js:340

refCount

get refCount(): number
The current reference count.

Returns number
Inherited from RefCountedObject.refCount
- Defined in engine/src/core/ref-counted-object.js:32

Methods

clear

clear(verticesDynamic?, indicesDynamic?, maxVertices?, maxIndices?): void
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
- Optional verticesDynamic: boolean
  Indicates the VertexBuffer should be created with BUFFER_DYNAMIC usage. If not specified, BUFFER_STATIC is used.
- Optional indicesDynamic: boolean
  Indicates the IndexBuffer should be created with BUFFER_DYNAMIC usage. If not specified, BUFFER_STATIC is used.
- Optional maxVertices: number = 0
  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.
- Optional maxIndices: number = 0
  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.
Returns void
- Defined in engine/src/scene/mesh.js:576

decRefCount

decRefCount(): void
Decrements the reference counter.

Returns void
Inherited from RefCountedObject.decRefCount
- Defined in engine/src/core/ref-counted-object.js:23

destroy

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

Returns void
- Defined in engine/src/scene/mesh.js:377

getColors

getColors(colors): number
Gets the vertex color data.
Parameters
- colors: number[] | ArrayBufferView
  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.
- Defined in engine/src/scene/mesh.js:801

getIndices

getIndices(indices): number
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.
- Defined in engine/src/scene/mesh.js:813

getNormals

getNormals(normals): number
Gets the vertex normals data.
Parameters
- normals: number[] | ArrayBufferView
  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.
- Defined in engine/src/scene/mesh.js:776

getPositions

getPositions(positions): number
Gets the vertex positions data.
Parameters
- positions: number[] | ArrayBufferView
  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.
- Defined in engine/src/scene/mesh.js:764

getUvs

getUvs(channel, uvs): number
Gets the vertex uv data.
Parameters
- channel: number
  The uv channel in [0..7] range.
- uvs: number[] | ArrayBufferView
  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.
- Defined in engine/src/scene/mesh.js:789

getVertexStream

getVertexStream(semantic, data): number
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[] | ArrayBufferView
  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.
- Defined in engine/src/scene/mesh.js:633

incRefCount

incRefCount(): void
Increments the reference counter.

Returns void
Inherited from RefCountedObject.incRefCount
- Defined in engine/src/core/ref-counted-object.js:16

setColors

setColors(colors, componentCount?, numVertices?): void
Sets the vertex color array. Colors are stored using TYPE_FLOAT32 format, which is useful for HDR colors.
Parameters
- colors: number[] | ArrayBufferView
  Vertex data containing colors.
- Optional componentCount: number = GeometryData.DEFAULT_COMPONENTS_COLORS
  The number of values that form a single color element. Defaults to 4 if not specified, corresponding to r, g, b and a.
- Optional 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.
Returns void
- Defined in engine/src/scene/mesh.js:721

setColors32

setColors32(colors, numVertices?): void
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[] | ArrayBufferView
  Vertex data containing colors. The array is expected to contain 4 components per vertex, corresponding to r, g, b and a.
- Optional 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.
Returns void
- Defined in engine/src/scene/mesh.js:736

setIndices

setIndices(indices, numIndices?): void
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.).
- Optional 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.
Returns void
- Defined in engine/src/scene/mesh.js:749

setNormals

setNormals(normals, componentCount?, numVertices?): void
Sets the vertex normals array. Normals are stored using TYPE_FLOAT32 format.
Parameters
- normals: number[] | ArrayBufferView
  Vertex data containing normals.
- Optional componentCount: number = GeometryData.DEFAULT_COMPONENTS_NORMAL
  The number of values that form a single normal element. Defaults to 3 if not specified, corresponding to x, y and z direction.
- Optional 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.
Returns void
- Defined in engine/src/scene/mesh.js:691

setPositions

setPositions(positions, componentCount?, numVertices?): void
Sets the vertex positions array. Vertices are stored using TYPE_FLOAT32 format.
Parameters
- positions: number[] | ArrayBufferView
  Vertex data containing positions.
- Optional componentCount: number = GeometryData.DEFAULT_COMPONENTS_POSITION
  The number of values that form a single position element. Defaults to 3 if not specified, corresponding to x, y and z coordinates.
- Optional 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.
Returns void
- Defined in engine/src/scene/mesh.js:677

setUvs

setUvs(channel, uvs, componentCount?, numVertices?): void
Sets the vertex uv array. Uvs are stored using TYPE_FLOAT32 format.
Parameters
- channel: number
  The uv channel in [0..7] range.
- uvs: number[] | ArrayBufferView
  Vertex data containing uv-coordinates.
- Optional componentCount: number = GeometryData.DEFAULT_COMPONENTS_UV
  The number of values that form a single uv element. Defaults to 2 if not specified, corresponding to u and v coordinates.
- Optional 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.
Returns void
- Defined in engine/src/scene/mesh.js:706

setVertexStream

setVertexStream(semantic, data, componentCount, numVertices?, dataType?, dataTypeNormalize?, asInt?): void
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[] | ArrayBufferView
  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.
- Optional 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.
- Optional dataType: number = TYPE_FLOAT32
  The format of data when stored in the VertexBuffer, see TYPE_* in VertexFormat. When not specified, TYPE_FLOAT32 is used.
- Optional dataTypeNormalize: boolean = false
  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.
- Optional asInt: boolean = false
  If true, vertex attribute data will be accessible as integer numbers in shader code. Defaults to false, which means that vertex attribute data will be accessible as floating point numbers. Can be only used with INT and UINT data types.
Returns void
- Defined in engine/src/scene/mesh.js:608

update

update(primitiveType?, updateBoundingBox?): void
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
- Optional primitiveType: number = PRIMITIVE_TRIANGLES
  The type of primitive to render. Can be:
  Defaults to PRIMITIVE_TRIANGLES if unspecified.
- Optional updateBoundingBox: boolean = true
  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.
Returns void
- Defined in engine/src/scene/mesh.js:864

`Static` fromGeometry

fromGeometry(graphicsDevice, geometry, options?): Mesh
Create a new Mesh instance from Geometry object.
Parameters
- graphicsDevice: GraphicsDevice
  The graphics device used to manage this mesh.
- geometry: Geometry
  The geometry object to create the mesh from.
- Optional options: {
  storageIndex: boolean;
  storageVertex: boolean;
  } = {}
  An object that specifies optional inputs for the function as follows:
  - storageIndex: boolean
    Defines if the index buffer of the mesh can be used as a storage buffer by a compute shader. Defaults to false. Only supported on WebGPU.
  - storageVertex: boolean
    Defines if the vertex buffer of the mesh can be used as a storage buffer by a compute shader. Defaults to false. Only supported on WebGPU.
Returns Mesh
A new mesh.
- Defined in engine/src/scene/mesh.js:289

Class Mesh

Mesh APIs

Simple Mesh API

Update Vertex and Index buffers

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

storageIndex: boolean

storageVertex: boolean

Returns Mesh

Properties

Private _aabb

Private _storageIndex

Private _storageVertex

indexBuffer

primitive

Type declaration

base: number

count: number

Optional indexed?: boolean

type: number

skin

vertexBuffer

Accessors

aabb

Returns BoundingBox

Parameters

Returns void

morph

Returns any

Parameters

Returns void

refCount

Returns number

Methods

clear

Parameters

Returns void

decRefCount

Returns void

destroy

Returns void

getColors

Parameters

Returns number

getIndices

Parameters

Returns number

getNormals

Parameters

Returns number

getPositions

Parameters

Returns number

getUvs

Parameters

Returns number

getVertexStream

Parameters

Returns number

incRefCount

Returns void

setColors

Parameters

Returns void

setColors32

Parameters

Returns void

setIndices

Parameters

Returns void

setNormals

Parameters

Returns void

`Private` _aabb

`Private` _storageIndex

`Private` _storageVertex

`Optional` indexed?: boolean

`Static` fromGeometry