V7

How To

Mirror Engine API

Mirror Engine API / Mesh

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

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.

Extends

RefCountedObject

Constructors

new Mesh()

new Mesh(graphicsDevice: GraphicsDevice, options?: {
  storageIndex: boolean;
  storageVertex: boolean;
 }): Mesh

Create a new Mesh instance.

Parameters

graphicsDevice

GraphicsDevice

The graphics device used to manage this mesh.

options?

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

Overrides

RefCountedObject.constructor

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.

type is the type of primitive to render. Can be:
- PRIMITIVE_POINTS
- PRIMITIVE_LINES
- PRIMITIVE_LINELOOP
- PRIMITIVE_LINESTRIP
- PRIMITIVE_TRIANGLES
- PRIMITIVE_TRISTRIP
- PRIMITIVE_TRIFAN
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.

base

base: number

count

count: number

indexed?

optional indexed: boolean;

type

type: number

skin

skin: null | Skin = null;

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

vertexBuffer

vertexBuffer: VertexBuffer = null

The vertex buffer holding the vertex data of the mesh.

aabb

Get Signature

get aabb(): BoundingBox

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

Returns

Set Signature

set aabb(aabb: BoundingBox): void

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

Parameters

aabb

Returns

void

morph

Get Signature

get morph(): null | Morph

Gets the morph data that drives morph target animations for this mesh.

Returns

null | Morph

Set Signature

set morph(morph: null | Morph): void

Sets the morph data that drives morph target animations for this mesh. Set to null if morphing is not used.

Parameters

morph

null | Morph

Returns

void

refCount

Get Signature

get refCount(): number

Gets the current reference count.

Returns

number

Inherited from

RefCountedObject.refCount

Methods

clear()

clear(
   verticesDynamic?: boolean,
   indicesDynamic?: boolean,
   maxVertices?: number,
   maxIndices?: number): 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

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

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

decRefCount()

decRefCount(): void

Decrements the reference counter.

Returns

void

Inherited from

RefCountedObject.decRefCount

destroy()

destroy(): void

Destroys the VertexBuffer and IndexBuffers associated with the mesh. This is normally called by Model#destroy and does not need to be called manually.

Returns

void

getColors()

getColors(colors: number[] | ArrayBufferView<ArrayBufferLike>): number

Gets the vertex color data.

Parameters

colors

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.

number[] | ArrayBufferView<ArrayBufferLike>

Returns

number

Returns the number of vertices populated.

getIndices()

getIndices(indices:
  | number[]
  | Uint8Array<ArrayBufferLike>
  | Uint16Array<ArrayBufferLike>
  | Uint32Array<ArrayBufferLike>): number

Gets the index data.

Parameters

indices

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.

number[] | Uint8Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike>

Returns

number

Returns the number of indices populated.

getNormals()

getNormals(normals: number[] | ArrayBufferView<ArrayBufferLike>): number

Gets the vertex normals data.

Parameters

normals

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.

number[] | ArrayBufferView<ArrayBufferLike>

Returns

number

Returns the number of vertices populated.

getPositions()

getPositions(positions: number[] | ArrayBufferView<ArrayBufferLike>): number

Gets the vertex positions data.

Parameters

positions

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.

number[] | ArrayBufferView<ArrayBufferLike>

Returns

number

Returns the number of vertices populated.

getUvs()

getUvs(channel: number, uvs: number[] | ArrayBufferView<ArrayBufferLike>): number

Gets the vertex uv data.

Parameters

channel

number

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

uvs

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.

number[] | ArrayBufferView<ArrayBufferLike>

Returns

number

Returns the number of vertices populated.

getVertexStream()

getVertexStream(semantic: string, data: number[] | ArrayBufferView<ArrayBufferLike>): 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

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.

number[] | ArrayBufferView<ArrayBufferLike>

Returns

number

Returns the number of vertices populated.

incRefCount()

incRefCount(): void

Increments the reference counter.

Returns

void

Inherited from

RefCountedObject.incRefCount

setColors()

setColors(
   colors: number[] | ArrayBufferView<ArrayBufferLike>,
   componentCount?: number,
   numVertices?: number): void

Sets the vertex color array. Colors are stored using TYPE_FLOAT32 format, which is useful for HDR colors.

Parameters

colors

Vertex data containing colors.

number[] | ArrayBufferView<ArrayBufferLike>

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.

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

setColors32()

setColors32(colors: number[] | ArrayBufferView<ArrayBufferLike>, numVertices?: number): 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

Vertex data containing colors. The array is expected to contain 4 components per vertex, corresponding to r, g, b and a.

number[] | ArrayBufferView<ArrayBufferLike>

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

setIndices()

setIndices(indices:
  | number[]
  | Uint8Array<ArrayBufferLike>
  | Uint16Array<ArrayBufferLike>
  | Uint32Array<ArrayBufferLike>, numIndices?: number): 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

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

number[] | Uint8Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike>

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

setNormals()

setNormals(
   normals: number[] | ArrayBufferView<ArrayBufferLike>,
   componentCount?: number,
   numVertices?: number): void

Sets the vertex normals array. Normals are stored using TYPE_FLOAT32 format.

Parameters

normals

Vertex data containing normals.

number[] | ArrayBufferView<ArrayBufferLike>

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.

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

setPositions()

setPositions(
   positions: number[] | ArrayBufferView<ArrayBufferLike>,
   componentCount?: number,
   numVertices?: number): void

Sets the vertex positions array. Vertices are stored using TYPE_FLOAT32 format.

Parameters

positions

Vertex data containing positions.

number[] | ArrayBufferView<ArrayBufferLike>

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.

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

setUvs()

setUvs(
   channel: number,
   uvs: number[] | ArrayBufferView<ArrayBufferLike>,
   componentCount?: number,
   numVertices?: number): void

Sets the vertex uv array. Uvs are stored using TYPE_FLOAT32 format.

Parameters

channel

number

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

uvs

Vertex data containing uv-coordinates.

number[] | ArrayBufferView<ArrayBufferLike>

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.

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

setVertexStream()

setVertexStream(
   semantic: string,
   data: number[] | ArrayBufferView<ArrayBufferLike>,
   componentCount: number,
   numVertices?: number,
   dataType?: number,
   dataTypeNormalize?: boolean,
   asInt?: boolean): 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

Vertex data for the specified semantic.

number[] | ArrayBufferView<ArrayBufferLike>

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 = TYPE_FLOAT32

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

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.

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

update()

update(primitiveType?: number, updateBoundingBox?: boolean): 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

primitiveType?

number = PRIMITIVE_TRIANGLES

The type of primitive to render. Can be:

PRIMITIVE_POINTS
PRIMITIVE_LINES
PRIMITIVE_LINELOOP
PRIMITIVE_LINESTRIP
PRIMITIVE_TRIANGLES
PRIMITIVE_TRISTRIP
PRIMITIVE_TRIFAN

Defaults to PRIMITIVE_TRIANGLES if not specified.

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 not specified. Set this to false to avoid update of the bounding box and use aabb property to set it instead.

Returns

void

fromGeometry()

static fromGeometry(
   graphicsDevice: GraphicsDevice,
   geometry: Geometry,
   options?: {
  storageIndex: boolean;
  storageVertex: boolean;
 }): Mesh

Create a new Mesh instance from Geometry object.

Parameters

graphicsDevice

GraphicsDevice

The graphics device used to manage this mesh.

geometry

The geometry object to create the mesh from.

options?

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

A new mesh.