MVertexBuffer Class Reference
This reference page is linked to from the following overview topics: Autodesk Maya 2014, Extension for Autodesk Maya 2013, Data Classes, 2.2 Geometric Data (MGeometry), 3.3 Geometry Overrides, 4.3 Customizing Geometric Data for Shaders.
Detailed Description
Vertex buffer for use with MGeometry.
This class represents a vertex buffer with attributes described by the descriptor member.
When retrieving a vertex buffer for binding to custom shaders (MPxShaderOverride), resourceHandle() may be called to get the device dependent handle to the vertex buffer on the GPU.
When creating a vertex 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.
When exploring the contents of an already filled vertex buffer, map() may be called to get a pointer to the read-only block of memory containing the data. Once done exploring, unmap() must be called to allow the buffer to be reused.
- Examples:
-
cgfxShaderNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.
#include <MHWGeometry.h>
Public Member Functions | |
| MVertexBuffer (const MVertexBufferDescriptor &descriptor) | |
| Constructor. | |
| ~MVertexBuffer () | |
| Destructor. | |
| const MVertexBufferDescriptor & | descriptor () const |
| Get the the buffer descriptor. | |
| void * | resourceHandle () const |
| Gets a graphics device dependent handle to a vertex buffer. | |
| void | resourceHandle (void *handle, unsigned int size) |
| Directly set the graphics-device-dependent hardware buffer resource handle. | |
| bool | hasCustomResourceHandle () const |
| Returns true if this vertex buffer is using a custom resource handle set by the plugin using MVertexBuffer::resourceHandle(void*, unsigned int). | |
| void * | acquire (unsigned int size, bool writeOnly) |
| Get a pointer to memory for the buffer. | |
| void | commit (void *buffer) |
| Commit the data stored in the memory given by acquire() to the buffer. | |
| void * | map () |
| Get a read-only pointer to the existing content of the buffer. | |
| void | unmap () |
| Release the data exposed by map(). | |
| void | unload () |
| If the buffer is resident in GPU memory, calling this method will move it to system memory and free the GPU memory. | |
| unsigned int | vertexCount () const |
| Get the size of the vertex buffer. | |
| void * | acquire (unsigned int size) |
| This method is obsolete. | |
Static Public Member Functions | |
| static const char * | className () |
| Returns the name of this class. | |
Friends | |
| class | MGeometry |
Constructor & Destructor Documentation
| MVertexBuffer | ( | const MVertexBufferDescriptor & | desc | ) |
Constructor.
- Parameters:
-
[in] desc A descriptor to define the vertex buffer attributes
| ~MVertexBuffer | ( | ) |
Destructor.
Note that it is an error to delete MVertexBuffer objects that are owned by or in use by an MGeometry object. Such actions may cause instability.
Member Function Documentation
| const MVertexBufferDescriptor & descriptor | ( | ) | const |
Get the the buffer descriptor.
- Returns:
- The buffer descriptor
- Examples:
- cgfxShaderNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.
| void * resourceHandle | ( | ) | const |
Gets a graphics device dependent handle to a vertex buffer.
For OpenGL the return value is a pointer to an OpenGL identifier (GLuint) to an vertex buffer containing the data. Buffers can be set via the OpenGL API for drawing purposes. (e.g. using glBindBuffer).
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.
- Returns:
- A pointer to device dependent vertex data
- Examples:
- cgfxShaderNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.
| 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 vertex 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.
Multiple MVertexBuffers with the same handle pointer indicate an interleaved vertex format, with the offset member of the descriptor determining the field order.
Not currently supported in DirectX.
- Parameters:
-
[in] handle For OpenGL, handle is a pointer to a GLuint resource identifier for a vertex buffer object. This pointer must remain valid after MPxGeometryOverride::populateGeometry() returns, though not indefinitely after that. [in] size The number of 4-byte words (floats) in the indicated buffer.
| bool hasCustomResourceHandle | ( | ) | const |
Returns true if this vertex buffer is using a custom resource handle set by the plugin using MVertexBuffer::resourceHandle(void*, unsigned int).
- Returns:
- True if this vertex buffer is using a custom resource handle.
| 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 * descriptor.dataTypeSize() * descriptor.dimension()) bytes. The memory for the buffer is managed internally.
Note that not all vertex buffer descriptors can be used to create vertex buffers as not all combinations of data types, dimensions and semantics are currently supported. If the descriptor for this buffer is not supported this method will return NULL.
- Parameters:
-
[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.
- Returns:
- A pointer to memory for the buffer, or NULL on failure
| void commit | ( | void * | buffer | ) |
| 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.
- Returns:
- A pointer to memory for the buffer, or NULL on failure
| void unmap | ( | ) |
Release the data exposed by map().
If this method is not called, the buffer will not be recycled.
| 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.
| unsigned int vertexCount | ( | ) | const |
Get the size of the vertex buffer.
- Returns:
- The size of the vertex buffer.
| const char * className | ( | ) | [static] |
| void * acquire | ( | unsigned int | size | ) |
This method is obsolete.
- Deprecated:
- Please use acquire(unsigned int size, bool writeOnly) instead.
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 * descriptor.dataTypeSize() * descriptor.dimension()) bytes. The memory for the buffer is managed internally.
Note that not all vertex buffer descriptors can be used to create vertex buffers as not all combinations of data types, dimensions and semantics are currently supported. If the descriptor for this buffer is not supported this method will return NULL.
- Parameters:
-
[in] size The size of the buffer to acquire.
- Returns:
- A pointer to memory for the buffer, or NULL on failure
