MeshBuffer
class MeshBuffer : AutoCloseable
Container holding raw vertex and index data for custom meshes.
A MeshBuffer represents a compilation of one or more vertex buffers and an index buffer in the underlying rendering engine. The vertex buffers contain the vertex data according to the provided VertexLayout, and the index buffer contains the indices of the vertices that form the primitives of the mesh.
The raw buffer data is provided during the creation of the MeshBuffer and is immediately copied into the rendering engine's memory. As a result, the MeshBuffer does not retain references to the original ByteBuffer objects, which can be modified or released by the application after creation.
Summary
Nested types |
|---|
class MeshBuffer.MeshUsageDescribes the intended usage and mutability of a |
Public companion functions |
|
|---|---|
MeshBuffer |
@MainThreadCreates a new static |
MeshBuffer |
@RequiresSpatialApi(value = 4)Creates a new dynamic |
Public functions |
|
|---|---|
open Unit |
Closes the given |
Unit |
@MainThreadUpdates index data in the |
Unit |
@MainThreadUpdates vertex data for a specific buffer index in the |
Public properties |
|
|---|---|
MeshBuffer.MeshUsage |
|
VertexLayout |
|
Public companion functions
create
@MainThread
fun create(
session: Session,
vertexLayout: VertexLayout,
vertexData: List<ByteBufferRegion>,
indexData: ByteBufferRegion
): MeshBuffer
Creates a new static MeshBuffer.
The raw buffer data is copied immediately into rendering engine memory. The original ByteBuffer objects can be modified or released after creation without affecting the mesh buffer.
| Parameters | |
|---|---|
session: Session |
session to use for creating the MeshBuffer |
vertexLayout: VertexLayout |
layout of the vertices in the vertex buffer(s) |
vertexData: List<ByteBufferRegion> |
vertex data regions, one for each buffer index in |
indexData: ByteBufferRegion |
index data region containing 32-bit unsigned indices |
| Returns | |
|---|---|
MeshBuffer |
a new static |
| Throws | |
|---|---|
IllegalArgumentException |
if |
createDynamic
@RequiresSpatialApi(value = 4)
@MainThread
fun createDynamic(
session: Session,
vertexLayout: VertexLayout,
vertexCount: @IntRange(from = 1) Int,
indexCount: @IntRange(from = 1) Int,
vertexData: List<ByteBufferRegion?>? = null,
indexData: ByteBufferRegion? = null
): MeshBuffer
Creates a new dynamic MeshBuffer supporting runtime updates.
The vertexCount and indexCount parameters define the fixed maximum capacity of the underlying GPU buffers. The allocated buffer cannot be resized after creation. Any runtime updates via updateVertexData or updateIndexData that exceed these capacities will throw an IllegalArgumentException.
If initial vertex or index data is omitted or partially provided (smaller than the allocated capacities), the unpopulated regions will be filled with zeros.
Note: Automatic bounding box calculation only considers the initial vertex data supplied at creation time and is never recalculated on subsequent dynamic updates. When working with dynamic meshes, set a bounding box on the mesh that covers all possible vertex positions across the mesh's lifetime.
| Parameters | |
|---|---|
session: Session |
session to use for creating the MeshBuffer |
vertexLayout: VertexLayout |
layout of the vertices in the vertex buffer(s) |
vertexCount: @IntRange(from = 1) Int |
fixed maximum capacity of vertices allocated in memory |
indexCount: @IntRange(from = 1) Int |
fixed maximum capacity of indices allocated in memory |
vertexData: List<ByteBufferRegion?>? = null |
optional list of |
indexData: ByteBufferRegion? = null |
optional |
| Returns | |
|---|---|
MeshBuffer |
a new |
| Throws | |
|---|---|
IllegalArgumentException |
if |
Public functions
close
@MainThread
open fun close(): Unit
Closes the given MeshBuffer.
The MeshBuffer can be explicitly closed at anytime or garbage collected. An exception will be thrown if the MeshBuffer is used after being closed.
| Throws | |
|---|---|
IllegalStateException |
if the resource has already been closed. |
updateIndexData
@MainThread
fun updateIndexData(
indexData: ByteBufferRegion,
offsetInBytes: @IntRange(from = 0) Int = 0
): Unit
Updates index data in the MeshBuffer.
This operation is only allowed if MeshBuffer.meshUsage is MeshUsage.DYNAMIC.
| Parameters | |
|---|---|
indexData: ByteBufferRegion |
source |
offsetInBytes: @IntRange(from = 0) Int = 0 |
starting offset in bytes in the target buffer where the data should be written |
| Throws | |
|---|---|
IllegalStateException |
if the buffer is closed, or was not created as dynamic |
IllegalArgumentException |
if |
updateVertexData
@MainThread
fun updateVertexData(
bufferIndex: @IntRange(from = 0) Int,
vertexData: ByteBufferRegion,
offsetInBytes: @IntRange(from = 0) Int = 0
): Unit
Updates vertex data for a specific buffer index in the MeshBuffer.
This operation is only allowed if MeshBuffer.meshUsage is MeshUsage.DYNAMIC.
| Parameters | |
|---|---|
bufferIndex: @IntRange(from = 0) Int |
index of the vertex buffer to update in |
vertexData: ByteBufferRegion |
source |
offsetInBytes: @IntRange(from = 0) Int = 0 |
starting offset in bytes in the target buffer where the data should be written |
| Throws | |
|---|---|
IllegalStateException |
if the buffer is closed, or was not created as dynamic |
IllegalArgumentException |
if |
Public properties
meshUsage
val meshUsage: MeshBuffer.MeshUsage
MeshUsage indicating the usage mode and mutability of this buffer
vertexLayout
val vertexLayout: VertexLayout
VertexLayout describing the structure of the vertex data