
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.