MeshBuffer
public final class MeshBuffer implements 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 |
|---|
public final class MeshBuffer.MeshUsageDescribes the intended usage and mutability of a |
Public methods |
|
|---|---|
void |
Closes the given |
static final @NonNull MeshBuffer |
@MainThreadCreates a new static |
static final @NonNull MeshBuffer |
@RequiresSpatialApi(value = 4)Creates a new dynamic |
final @NonNull MeshBuffer.MeshUsage |
|
final @NonNull VertexLayout |
|
final void |
@MainThreadUpdates index data in the |
final void |
@MainThreadUpdates vertex data for a specific buffer index in the |
Public methods
close
@MainThread
public void close()
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. |
create
@MainThread
public static final @NonNull MeshBuffer create(
@NonNull Session session,
@NonNull VertexLayout vertexLayout,
@NonNull List<@NonNull ByteBufferRegion> vertexData,
@NonNull ByteBufferRegion indexData
)
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 | |
|---|---|
@NonNull Session session |
session to use for creating the MeshBuffer |
@NonNull VertexLayout vertexLayout |
layout of the vertices in the vertex buffer(s) |
@NonNull List<@NonNull ByteBufferRegion> vertexData |
vertex data regions, one for each buffer index in |
@NonNull ByteBufferRegion indexData |
index data region containing 32-bit unsigned indices |
| Returns | |
|---|---|
@NonNull MeshBuffer |
a new static |
| Throws | |
|---|---|
IllegalArgumentException |
if |
createDynamic
@RequiresSpatialApi(value = 4)
@MainThread
public static final @NonNull MeshBuffer createDynamic(
@NonNull Session session,
@NonNull VertexLayout vertexLayout,
@IntRange(from = 1) int vertexCount,
@IntRange(from = 1) int indexCount,
List<ByteBufferRegion> vertexData,
ByteBufferRegion indexData
)
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 | |
|---|---|
@NonNull Session session |
session to use for creating the MeshBuffer |
@NonNull VertexLayout vertexLayout |
layout of the vertices in the vertex buffer(s) |
@IntRange(from = 1) int vertexCount |
fixed maximum capacity of vertices allocated in memory |
@IntRange(from = 1) int indexCount |
fixed maximum capacity of indices allocated in memory |
List<ByteBufferRegion> vertexData |
optional list of |
ByteBufferRegion indexData |
optional |
| Returns | |
|---|---|
@NonNull MeshBuffer |
a new |
| Throws | |
|---|---|
IllegalArgumentException |
if |
getMeshUsage
public final @NonNull MeshBuffer.MeshUsage getMeshUsage()
MeshUsage indicating the usage mode and mutability of this buffer
getVertexLayout
public final @NonNull VertexLayout getVertexLayout()
VertexLayout describing the structure of the vertex data
updateIndexData
@MainThread
public final void updateIndexData(
@NonNull ByteBufferRegion indexData,
@IntRange(from = 0) int offsetInBytes
)
Updates index data in the MeshBuffer.
This operation is only allowed if MeshBuffer.meshUsage is MeshUsage.DYNAMIC.
| Parameters | |
|---|---|
@NonNull ByteBufferRegion indexData |
source |
@IntRange(from = 0) int offsetInBytes |
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
public final void updateVertexData(
@IntRange(from = 0) int bufferIndex,
@NonNull ByteBufferRegion vertexData,
@IntRange(from = 0) int offsetInBytes
)
Updates vertex data for a specific buffer index in the MeshBuffer.
This operation is only allowed if MeshBuffer.meshUsage is MeshUsage.DYNAMIC.
| Parameters | |
|---|---|
@IntRange(from = 0) int bufferIndex |
index of the vertex buffer to update in |
@NonNull ByteBufferRegion vertexData |
source |
@IntRange(from = 0) int offsetInBytes |
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 |