IMeshData script interface

The IMeshData interface represents a series of long-lived vertex buffers for use with the renderer. It includes position, texture co-ordinate, color, normal and index data. The data lives persistently on the GPU, ensuring it is a much more efficient way to draw complex meshes than the renderer drawMesh() method, which uploads all the provided data to the GPU with every call; in contrast the drawMeshData() method accepts an IMeshData and re-uses its content without having to upload any more data.

This interface is created using the renderer createMeshData() method. Once created the number of vertices or indices cannot be changed.

For code examples using IMeshData, see the Draw mesh data (JavaScript) or Draw mesh data (TypeScript) examples.

IMeshData APIs

vertexCount

indexCount

Read-only numbers with the vertex and index count the mesh data was created with.

positions

A Float32Array of vertex positions, with three components per vertex in X, Y, Z order (hence the length of this array is 3 * vertexCount).

texCoords

A Float32Array of texture co-ordinates, with two components per vertex in X, Y order (hence the length of this array is 2 * vertexCount).

colors

A Float16Array (where supported) or Float32Array of vertex colors, with four components per vertex in R, G, B, A order (hence the length of this array is 4 * vertexCount).

normals

A Float16Array (where supported) or Float32Array of vertex normals (unit vectors pointing in the direction perpendicular to the surface). These are only made use of by 3D lighting - if you do not need 3D lighting then normal data can be ignored as it will have no effect. Normal vectors have three components (X, Y and Z). However when the normal data is using Float16Array, due to hardware alignment requirements the normal data may in fact use four components, with the fourth component existing solely for alignment purposes and being ignored. Use the method copyNormalBuffer() to write normal data as that method internally handles 3 or 4 component normal data.

indices

A Uint16Array or Uint32Array of indices. Uint16Array is used when the vertex count fits within a 16-bit index, otherwise Uint32Array is used. Construct always uses indexed rendering, so this must be provided; if indices are not actually used, fill the buffer with incrementing numbers to render the provided vertices in order. As the index buffer specifies triangles, its length should be a multiple of three. Note that indices refer to the index of a vertex, rather than a direct index in to a data array like positions. For example a positions array with elements x1, y1, z1, x2, y2, z2 has six elements but defines two vertices, and so index 1 refers to the second vertex.

debugLabel

A read-only string with the debugLabel option specified when creating the mesh data.

markDataChanged(bufferType, start, end)

Mark a range of data changed in a specific data buffer. bufferType must be one of "positions", "texCoords", "colors". "normals" or "indices". start and end are optional: if omitted, the entire buffer is marked changed; if specified then only the given range (in vertices or indices) is marked changed up to but excluding end. end may also be omitted to update from start to the end of the buffer. Once data is marked as changed, it will be uploaded to the GPU the next time this mesh data is drawn.

markAllVertexDataChanged(start, end)

A shorthand method to mark the position, texture co-ordinate, color and normal buffers changed. The start and end parameters are optional and work the same way as with markDataChanged().

markIndexDataChanged(start, end)

A shorthand method that is equivalent to markDataChanged("indices", start, end).

fillColor(r, g, b, a)

A helper method to fill the entire color buffer with the same color repeated for every vertex. This can be useful if there is no color data provided for the mesh - filling the color buffer with opaque white (all parameters 1) will keep the original texture color. Note this method does not mark the buffer changed.

copyNormalBuffer(normalArr, offset)

Write the typed array (or array of numbers) normalArr to the IMeshData's normals. The provided array should use three components per vertex (in X, Y, Z order). This method automatically adjusts the copied data if the normals data array is actually using four components for hardware alignment reasons, so using this method is preferable to directly writing to normals. The offset parameter can be provided to start writing at the given index within normals; note this is in components, so must increase by 3 to skip a whole vertex. Also note this method does not mark the buffer changed.

computeNormalBuffer()

Fills the IMeshData's normals using an algorithm to calculate normals from the existing positions and indices. The positions and indices arrays should be filled with valid data before calling this method. This can be useful to provide normals for a mesh when the original mesh did not provide this data, and therefore allow the mesh to respond to 3D lighting. This method requires significant CPU work, so try to avoid calling it regularly. Note this method does not mark the buffer changed.

fillIndices()

A convenience method that fills indices with incrementing numbers (starting from 0). This can be used to provide index data for meshes that do not use indexed rendering (i.e. the vertices are a list of triangles with no re-used vertices). Note this method does not mark the buffer changed.

release()

Release this mesh data, freeing both the CPU and GPU memory associated with it. The mesh data cannot be accessed or drawn after releasing.