#include <MHWGeometry.h>

Class 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:: apiMeshShape/apiMeshGeometryOverride.cpp, apiMeshShape/apiMeshGeometryOverride.h, apiMeshShape/apiMeshSubSceneOverride.cpp, apiMeshShape/apiMeshSubSceneOverride.h, cgFx/cgfxShaderNode.cpp, customPrimitiveGenerator/customPrimitiveGenerator.cpp, dx11Shader/crackFreePrimitiveGenerator.cpp, dx11Shader/dx11Shader.cpp, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, footPrintNode_SubSceneOverride/footPrintNode_SubSceneOverride.cpp, geometryReplicator/geometryReplicator.cpp, glslShader/adjacentTrianglesPrimitiveGenerator.cpp, glslShader/crackFreePrimitiveGenerator.cpp, gpuCache/gpuCacheCmd.cpp, gpuCache/gpuCacheSubSceneOverride.cpp, gpuCache/gpuCacheSubSceneOverride.h, hwColorPerVertexShader/hwColorPerVertexShader.cpp, hwPhongShader/hwPhongShader.cpp, vertexBufferGenerator/vertexBufferGenerator.cpp, and vertexBufferMutator/vertexBufferMutator.cpp.

Public Member Functions
	MVertexBuffer (const MVertexBufferDescriptor &descriptor)
	Constructor. More...

	MVertexBuffer (const MVertexBuffer &)
	Copy constructor. More...

	~MVertexBuffer ()
	Destructor. More...

const MVertexBufferDescriptor &	descriptor () const
	Get the the buffer descriptor. More...

void *	resourceHandle () const
	Gets a graphics device dependent handle to a vertex buffer. 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 vertex buffer is using a custom resource handle set by the plugin using MVertexBuffer::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 numVerts, bool truncateIfSmaller)
	Set a portion (or all) of the contents of the MVertexBuffer 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...

unsigned int	vertexCount () const
	Get the size of the vertex buffer. More...

void *	acquire (unsigned int size)
	This method is obsolete. More...

Static Public Member Functions
static const char *	className ()
	Returns the name of this class. More...

Friends
class	MGeometry

Constructor & Destructor Documentation

MVertexBuffer ( const MVertexBufferDescriptor & desc )

Constructor.

Parameters

[in] desc A descriptor to define the vertex buffer attributes

MVertexBuffer ( const MVertexBuffer & buffer )

Copy constructor.

Use this constructor to share buffer data across multiple render items. The underlying hardware buffer will be shared with the buffer being copied.

Do not use this constructor to copy buffers that are currently being edited. A debug assertion will be thrown if the buffer passed in has been acquired but not yet committed.

Parameters

[in] buffer The buffer to share data with.

~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:: cgFx/cgfxShaderNode.cpp, customPrimitiveGenerator/customPrimitiveGenerator.cpp, dx11Shader/crackFreePrimitiveGenerator.cpp, dx11Shader/dx11Shader.cpp, glslShader/adjacentTrianglesPrimitiveGenerator.cpp, glslShader/crackFreePrimitiveGenerator.cpp, gpuCache/gpuCacheSubSceneOverride.cpp, hwColorPerVertexShader/hwColorPerVertexShader.cpp, hwPhongShader/hwPhongShader.cpp, vertexBufferGenerator/vertexBufferGenerator.cpp, and vertexBufferMutator/vertexBufferMutator.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). For DirectX11 the return value is a pointer to an ID3D11Buffer interface of the vertex buffer.

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:: cgFx/cgfxShaderNode.cpp, dx11Shader/dx11Shader.cpp, hwColorPerVertexShader/hwColorPerVertexShader.cpp, and hwPhongShader/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.

Parameters

[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 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 lockResourceHandle ( )

Lock the resource handle.

The pointer returned from resourceHandle() is guaranteed to exist between lockResourceHandle() and unlockResourceHandle().

MVertexBuffer 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 MVertexBuffer 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.

void unlockResourceHandle ( )

Unlock the resource handle.

The pointer returned from resourceHandle is not guaranteed to exist any more. 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 * 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

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, customPrimitiveGenerator/customPrimitiveGenerator.cpp, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, geometryReplicator/geometryReplicator.cpp, vertexBufferGenerator/vertexBufferGenerator.cpp, and vertexBufferMutator/vertexBufferMutator.cpp.

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().

Parameters

[in] buffer A pointer to the data.

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, customPrimitiveGenerator/customPrimitiveGenerator.cpp, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, geometryReplicator/geometryReplicator.cpp, vertexBufferGenerator/vertexBufferGenerator.cpp, and vertexBufferMutator/vertexBufferMutator.cpp.

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

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, dx11Shader/crackFreePrimitiveGenerator.cpp, dx11Shader/dx11Shader.cpp, glslShader/adjacentTrianglesPrimitiveGenerator.cpp, glslShader/crackFreePrimitiveGenerator.cpp, hwPhongShader/hwPhongShader.cpp, and vertexBufferGenerator/vertexBufferGenerator.cpp.

void unmap ( )

Release the data exposed by map().

If this method is not called, the buffer will not be recycled.

In OpenGL mode, this will leave the ARRAY_BUFFER and ELEMENT_ARRAY_BUFFER bindings to 0.

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, dx11Shader/crackFreePrimitiveGenerator.cpp, dx11Shader/dx11Shader.cpp, glslShader/adjacentTrianglesPrimitiveGenerator.cpp, glslShader/crackFreePrimitiveGenerator.cpp, hwPhongShader/hwPhongShader.cpp, and vertexBufferGenerator/vertexBufferGenerator.cpp.

MStatus update	(	const void *	buffer,
		unsigned int	destOffset,
		unsigned int	numVerts,
		bool	truncateIfSmaller
	)

Set a portion (or all) of the contents of the MVertexBuffer using the data in the provided software buffer.

The internal hardware buffer will be allocated or reallocated to fit if required, according to the vertex size from the descriptor. The buffer size will be at least (size * descriptor.dataTypeSize() * descriptor.dimension()) 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 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 MStatus::kFailure.

If the vertex 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.

Parameters

[in]	buffer	The input data buffer, starting with the first vertex to copy.
[in]	destOffset	The offset (in vertices) from the beginning of the buffer to start writing to.
[in]	numVerts	The number of vertices to copy.
[in]	truncateIfSmaller	If true and offset+numVerts 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.

MStatus::kSuccess The method was successful
MStatus::kInvalidParameter Buffer was NULL or numVerts was 0.
MStatus::kFailure The descriptor was not valid or there was an error while allocating or updating the hardware buffer.

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.

Examples:: dx11Shader/dx11Shader.cpp, geometryReplicator/geometryReplicator.cpp, gpuCache/gpuCacheSubSceneOverride.cpp, hwPhongShader/hwPhongShader.cpp, and vertexBufferMutator/vertexBufferMutator.cpp.

const char * className ( )

static

Returns the name of this class.

Returns: The name of this class.

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

The documentation for this class was generated from the following files:

MHWGeometry.h
MHWGeometry.cpp

MVertexBuffer Class Reference

Class Description

Public Member Functions

Static Public Member Functions

Friends

Constructor & Destructor Documentation

Member Function Documentation