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

Constructors

constructor

Properties

indexBuffer primitive skin vertexBuffer

Accessors

aabb morph refCount

Methods

clear decRefCount destroy getColors getIndices getNormals getPositions getUvs getVertexStream incRefCount setColors setColors32 setIndices setNormals setPositions setUvs setVertexStream update fromGeometry

Constructors

constructor

  • new Mesh(graphicsDevice, options?): Mesh

  • Create a new Mesh instance.

    Parameters

    • graphicsDevice: GraphicsDevice

      The graphics device used to manage this mesh.

    • Optionaloptions: {
          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

Properties

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.

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

morph

refCount

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

    • OptionalverticesDynamic: boolean

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

    • OptionalindicesDynamic: boolean

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

    • OptionalmaxVertices: 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.

    • OptionalmaxIndices: 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

decRefCount

destroy

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.

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.

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.

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.

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.

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.

incRefCount

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.

    • OptionalcomponentCount: 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.

    • OptionalnumVertices: 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

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.

    • OptionalnumVertices: 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

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

    • OptionalnumIndices: 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

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.

    • OptionalcomponentCount: 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.

    • OptionalnumVertices: 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

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.

    • OptionalcomponentCount: 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.

    • OptionalnumVertices: 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

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.

    • OptionalcomponentCount: 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.

    • OptionalnumVertices: 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

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.

    • OptionalnumVertices: 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.

    • OptionaldataType: number = TYPE_FLOAT32

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

    • OptionaldataTypeNormalize: 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.

    • OptionalasInt: 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

update

StaticfromGeometry

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

    • Optionaloptions: {
          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.

Settings

Member Visibility

On This Page

Mesh APIs
Constructors
Properties
Accessors
Methods