Index buffer for use with MGeometry. More...
#include <MHWGeometry.h>
Public Member Functions | |
MIndexBuffer (MGeometry::DataType type, bool softwareStaged=true) | |
Constructor. More... | |
MIndexBuffer (const MIndexBuffer &) | |
Constructor. More... | |
~MIndexBuffer () | |
Destructor. More... | |
MGeometry::DataType | dataType () const |
Get the data type of the buffer. More... | |
unsigned int | size () const |
Get the size of the buffer in units of dataType(). More... | |
void * | resourceHandle () const |
Gets a graphics device dependent handle to the vertex indexing data. More... | |
void | resourceHandle (void *handle, unsigned int size) |
Directly set the graphics-device-dependent hardware buffer resource handle. More... | |
bool | hasCustomResourceHandle () const |
Returns true if this index buffer is using a custom resource handle set by the plugin using MIndexBuffer::resourceHandle(void*, unsigned int). More... | |
void | lockResourceHandle () |
Lock the resource handle. More... | |
void | unlockResourceHandle () |
Unlock the resource handle. More... | |
void * | acquire (unsigned int size, bool writeOnly) |
Get a pointer to memory for the buffer. More... | |
void | commit (void *buffer) |
Commit the data stored in the memory given by acquire() to the buffer. More... | |
void * | map () |
Get a read-only pointer to the existing content of the buffer. More... | |
void | unmap () |
Release the data exposed by map(). More... | |
MStatus | update (const void *buffer, unsigned int destOffset, unsigned int numIndices, bool truncateIfSmaller) |
Set a portion (or all) of the contents of the MIndexBuffer using the data in the provided software buffer. More... | |
void | unload () |
If the buffer is resident in GPU memory, calling this method will move it to system memory and free the GPU memory. More... | |
void * | acquire (unsigned int size) |
This method is obsolete. More... | |
void * | getIndexBuffer () const |
Private friend class only access to the internal OGS index buffer. More... | |
void | setIndexBuffer (void *ib) |
Private friend class only to set the internal OGS index buffer. More... | |
Static Public Member Functions | |
static const char * | className () |
Returns the name of this class. More... | |
Index buffer for use with MGeometry.
This class represents an index buffer with a specific data type.
When retrieving an index buffer for binding to custom shaders (MPxShaderOverride), resourceHandle() may be called to get the device dependent handle to the index buffer on the GPU.
When creating an index buffer to supply geometric data to Maya (MPxGeometryOverride), acquire() may be called to get a pointer to a block of memory to fill with said data. Once filled, commit() must be called to apply the data to the buffer.
MIndexBuffer | ( | MGeometry::DataType | type, |
bool | softwareStaged = true |
||
) |
Constructor.
[in] | type | The data type for the index buffer |
[in] | softwareStaged | A flag defining how buffers are managed and updated. When software staged is specified the system may keep an extra copy of the buffer in system memory for fast read-back and access. Software staging is useful for cases where the buffer is written once and changes infrequently. Software staging helps to improve consolidation performance and handling under low memory conditions. For buffers that change frequently (animated) and are accessed in write only mode you may see better performance if you set this option to false. (default: true) |
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride the MIndexBuffers used must be software staged.
MIndexBuffer | ( | const MIndexBuffer & | buffer | ) |
Constructor.
[in] | buffer | The buffer to copy |
~MIndexBuffer | ( | ) |
Destructor.
Note that it is an error to delete MIndexBuffer objects that are owned by or in use by an MGeometry object. Such actions may cause instability.
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride it is only safe to destroy an MIndexBuffer object during MPxGeometryOverride::cleanUp() or MPxGeometryOverride::~MPxGeometryOverride().
When using MIndexBuffer in conjunction with VP2 Custom Caching in MPxGeometryOverride it is only safe to destroy an MIndexBuffer buffer during MPxGeometryOverride::~MPxGeometryOverride().
MGeometry::DataType dataType | ( | ) | const |
Get the data type of the buffer.
unsigned int size | ( | ) | const |
Get the size of the buffer in units of dataType().
Returns 0 if unallocated.
void * resourceHandle | ( | ) | const |
Gets a graphics device dependent handle to the vertex indexing data.
For OpenGL the return value is a pointer to an OpenGL identifier (GLuint) for a vertex buffer containing the indexing data. (e.g. using glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, handle)). For DirectX11 the return value is a pointer to an ID3D11Buffer interface of the index buffer.
The index buffer identifier can be used to perform drawing of vertex buffer data identified by handles returned from MVertexBuffer::resourceHandle().
An example setup could be:
A NULL pointer will be returned if the graphics device dependent handle is not yet available.
If the pointer is not NULL, the value is only guaranteed to exist during the current draw. The value should never be cached or modified.
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride it is not safe to access the resourceHandle of an MIndexBuffer.
void resourceHandle | ( | void * | handle, |
unsigned int | size | ||
) |
Directly set the graphics-device-dependent hardware buffer resource handle.
This will result in the creation of a custom user index buffer. Maya can render it, but the plugin owns the underlying device resource. When the Maya buffer is deleted, the actual hardware buffer will not be deleted. These buffers cannot be filled with Acquire or read-back with Map. They must be created and pre-filled, by the plugin.
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride it is not safe to set the resourceHandle of an MIndexBuffer.
[in] | handle | For OpenGL, handle is a pointer to a GLuint resource identifier for a vertex buffer object. For DirectX11, handle is a pointer to an ID3D11Buffer interface. This pointer must remain valid after MPxGeometryOverride::populateGeometry() returns, though not indefinitely after that. |
[in] | size | The number of indices in the indicated buffer. |
bool hasCustomResourceHandle | ( | ) | const |
Returns true if this index buffer is using a custom resource handle set by the plugin using MIndexBuffer::resourceHandle(void*, unsigned int).
void lockResourceHandle | ( | ) |
Lock the resource handle.
The pointer returned from resourceHandle() is guaranteed to exist between lockResourceHandle() and unlockResourceHandle().
MIndexBuffer may store data in system memory, GPU memory or both. Direct access to the GPU representation of the data is possible through the buffer's resourceHandle(). If the GPU representation of the data is to be directly modified using an external graphics or compute API, then lockResourceHandle() must be called on the MIndexBuffer once, before any modifications to the buffer are made.
While a resource handle is locked, any external modifications to the GPU buffer will be recognized by Maya.
While a resource handle is locked, consolidated world will take longer to consolidate the corresponding object. After unlocking a resource handle, consolidated world will take longer to consolidate the corresponding object one more time, the first time the unlocked resource handle is consolidated.
Calling lockResourceHandle() and unlockResourceHandle() on a custom resource handle has no effect.
Reallocating or deleting the GPU representation of the data between lockResourceHandle() and unlockResourceHandle() will result in undefined behavior. acquire(), commit() and update() may reallocate the GPU representation. unload() may delete the GPU representation.
map() and unmap() will work if they are called between lockResourceHandle() and unlockResourceHandle(). They operate on the GPU representation.
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride it is not safe to access the GPU representation of the buffer. Therefore, calling lockResourceHandle(), or calling acquire(), commit(), update(), map() or unmap() on an MVertexBuffer locked resource handle is only safe during MPxGeometryOverride::cleanUp() or MPxGeometryOverride::~MPxGeometryOverride.
When using MIndexBuffer in conjunction with VP2 Custom Caching in MPxGeometryOverride it is only safe to access the GPU representation of an MIndexBuffer buffer during MPxGeometryOverride::~MPxGeometryOverride().
void unlockResourceHandle | ( | ) |
Unlock the resource handle.
The pointer returned from resourceHandle is not guaranteed to exist any more.
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride it is not safe to unlockResourceHande() an MIndexBuffer.
See lockResourceHandle() for more details.
void * acquire | ( | unsigned int | size, |
bool | writeOnly | ||
) |
Get a pointer to memory for the buffer.
This method is meant to be used in MPxGeometryOverride::populateGeometry() in order to provide data to Maya for drawing the associated object. The size of the buffer returned will be (size * sizeof(dataType())) bytes. The memory for the buffer is managed internally.
Note that not all data types are currently supported for index buffers. If the data type for this buffer is not supported this method will return NULL.
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride it is safe to acquire() an MIndexBuffer if the buffer is software staged and the buffer is not locked.
[in] | size | The size of the buffer to acquire |
[in] | writeOnly | Specified if the returned memory should be uninitialized or filled with actual buffer content. When the current buffer content is not needed, it is preferable to set the writeOnly flag to true for better performance. |
void commit | ( | void * | buffer | ) |
Commit the data stored in the memory given by acquire() to the buffer.
If this method is not called, the acquired buffer will not be used in drawing. The pointer must be the same pointer returned from acquire().
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride it is safe to commit() an MIndexBuffer if the buffer is software staged and the buffer is not locked.
[in] | buffer | A pointer to the data. |
void * map | ( | ) |
Get a read-only pointer to the existing content of the buffer.
Writing new content in this memory block is not supported and can lead to unexpected behavior.
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride it is safe to map() an MIndexBuffer if the buffer is software staged and the buffer is not locked.
void unmap | ( | ) |
Release the data exposed by map().
If this method is not called, the buffer will not be recycled.
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride it is not safe to unmap() an MIndexBuffer.
In OpenGL mode, this will leave the ARRAY_BUFFER and ELEMENT_ARRAY_BUFFER bindings to 0.
MStatus update | ( | const void * | buffer, |
unsigned int | destOffset, | ||
unsigned int | numIndices, | ||
bool | truncateIfSmaller | ||
) |
Set a portion (or all) of the contents of the MIndexBuffer using the data in the provided software buffer.
The internal hardware buffer will be allocated or reallocated to fit if required. The buffer size will be at least (size * sizeof(dataType())) bytes. If this operation requires enlarging an existing buffer and specifies an offset to update only a portion of the contents, then the old data before that offset may not be preserved.
Note that not all data types are currently supported for index buffers. If the data type for this buffer is not supported this method will return MStatus::kFailure.
If the index data is already available in the correct format for a simple memory copy, then this function should be more efficient than using acquire/commit or map/unmap. It should require fewer buffer copy operations.
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride it is safe to update() an MIndexBuffer if the buffer is software staged and the buffer is not locked.
[in] | buffer | The input data buffer, starting with the first index to copy. |
[in] | destOffset | The offset (in indices) from the beginning of the buffer to start writing to. |
[in] | numIndices | The number of indices to copy. |
[in] | truncateIfSmaller | If true and offset+numIndices is less than the pre-existing size of the buffer, then the buffer contents will be truncated to the new size. Truncating the buffer size will not cause a reallocation and will not lose data before the destOffset. |
void unload | ( | ) |
If the buffer is resident in GPU memory, calling this method will move it to system memory and free the GPU memory.
The buffer will be automatically reloaded into GPU memory the next time it is needed to draw an object. This method may be used to help manage GPU memory when working with extremely large sets of data.
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride it is only safe to unload() an MIndexBuffer object during MPxGeometryOverride::cleanUp() or MPxGeometryOverride::~MPxGeometryOverride().
When using MIndexBuffer in conjunction with VP2 Custom Caching in MPxGeometryOverride it is only safe to unload an MIndexBuffer buffer during MPxGeometryOverride::~MPxGeometryOverride().
|
static |
Returns the name of this class.
void * acquire | ( | unsigned int | size | ) |
This method is obsolete.
Get a pointer to memory for the buffer.
[from before Maya 2015]
This method is meant to be used in MPxGeometryOverride::populateGeometry() in order to provide data to Maya for drawing the associated object. The size of the buffer returned will be (size * sizeof(dataType())) bytes. The memory for the buffer is managed internally.
Note that not all data types are currently supported for index buffers. If the data type for this buffer is not supported this method will return NULL.
When using MIndexBuffer in conjunction with Evaluation Manager Parallel Update in MPxGeometryOverride it is safe to acquire() an MIndexBuffer if the buffer is software staged and the buffer is not locked.
[in] | size | The size of the buffer to acquire |
void * getIndexBuffer | ( | ) | const |
Private friend class only access to the internal OGS index buffer.
void setIndexBuffer | ( | void * | ib | ) |
Private friend class only to set the internal OGS index buffer.
[in] | ib | An OGS::Devices::AIndexBuffer* as a void* |