MRenderItem Class Reference


Detailed Description

A single renderable entity.

MRenderItem represents a single renderable entity. Each such entity is defined by a name, a primitive type and a draw mode.

A list of MRenderItem objects is passed to the draw method of implementations of MPxShaderOverride to indicate the objects that should be drawn immediately by the override. If the implementation wishes to manually bind data streams it can call MRenderItem::geometry() to access the vertex buffers and index buffers that have already been generate for the render item.

MRenderItem objects are used by implementations of MPxGeometryOverride for two purposes. First, MPxGeometryOverride::updateRenderItems() can create and add new render items to the list of items that will be drawn for a specific instance of a DAG object. This method can also enable/disable render items in the list and set a custom solid color shader on any user defined items. Later, a list of render items is provided to MPxGeometryOverride::populateGeometry(), to indicate index buffers that need to be generated. This list contains both the automatically generated render items Maya creates for shader assignments as well as the render items created in MPxGeometryOverride::updateRenderItems().

Examples:

cgfxShaderNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.

#include <MHWGeometry.h>

List of all members.

Public Member Functions

 MRenderItem (const MString &name, MGeometry::Primitive primitive, MGeometry::DrawMode mode, bool raiseAboveShaded)
 Constructor.
 ~MRenderItem ()
 Destructor.
bool setShader (const MShaderInstance *shader, const MString *customStreamName=NULL)
 Set shader to use when drawing this render item.
void setCustomData (MUserData *userData)
 Associate custom user data with this render item.
void enable (bool on)
 Enable or disable the render item for rendering.
void castsShadows (bool on)
 Enable or disable the ability of the render item to cast shadows.
void receivesShadows (bool on)
 Enable or disable the ability of the render item to receive shadows.
bool associateWithIndexBuffer (const MIndexBuffer *buffer) const
 Use to indicate that a particular index buffer should be used with this render item.
MUserDatacustomData () const
 Retrieve custom data from the render item, returns NULL if no such data has ever been set on the render item.
bool isEnabled () const
 Get the enable state of the render item.
bool castsShadows () const
 Get the castsShadows state of the render item.
bool receivesShadows () const
 Get the receivesShadows state of the render item.
MString name () const
 Get the name of the render item.
MGeometry::Primitive primitive () const
 Get the primitive type drawn by the render item.
MGeometry::Primitive primitive (int &stride) const
 Get the primitive type drawn by the render item, as well as its stride.
MGeometry::DrawMode drawMode () const
 Get the draw mode for the render item.
MDagPath sourceDagPath () const
 Retrieve the MDagPath for the instance of the object that generated this render item.
MObject component () const
 Get the optional component for the render item.
const MVertexBufferDescriptorListrequiredVertexBuffers () const
 Get a list of vertex buffer descriptors that describe the buffers required to draw the given render item.
const MGeometrygeometry () const
 Access full geometry data for the render item.
MBoundingBox boundingBox (MSpace::Space space=MSpace::kObject, MStatus *ReturnStatus=NULL) const
 Returns the bounding box for the geometry data of the render item.
bool isConsolidated () const
 Get the consolidated state of the render item.
void sourceIndexMapping (MGeometryIndexMapping &geometryIndexMapping) const
 Get the geometry index mapping of the multiples objects contained by this consolidated render item.

Static Public Member Functions

static const char * className ()
 Returns the name of this class.

Friends

class MGeometryRequirements

Constructor & Destructor Documentation

MRenderItem ( const MString name,
MGeometry::Primitive  primitive,
MGeometry::DrawMode  mode,
bool  raiseAboveShaded 
)

Constructor.

If the draw mode is not MGeometry::kAll, the render item will only be drawn when the specified viewport mode is active.

Parameters:
[in]nameThe name of the render item
[in]primitiveThe primitive type of the render item
[in]modeThe draw mode of the render item
[in]raiseAboveShadedPush this render item above all shaded items drawn for the same object

Member Function Documentation

bool setShader ( const MShaderInstance shader,
const MString customStreamName = NULL 
)

Set shader to use when drawing this render item.

If no shader is ever set the render item will not draw. The render item makes a copy of the instance so it is safe to delete the instance after assignment without affecting any render items the instance was assigned to.

In addition to assigning a shader, this method also allows users to modify the name of each geometry requirement that the shader will generate for MPxGeometryOverride::populateGeometry(). This allows different render items to use different data streams of the same semantic (e.g. a wireframe render item may want to use different position data than a shaded render item).

Parameters:
[in]shaderThe shader to use when drawing this item
[in]customStreamNameIf non-null, shader will generate geometry requirements with the given name
Returns:
True on success
void setCustomData ( MUserData userData)

Associate custom user data with this render item.

If deleteAfterUse() is true on the data, then the data object will automatically be deleted when the render item is deleted. Otherwise, the lifetime of the user data object is the responsibility of the caller.

If there is already custom data on this render item, it will be removed and replaced by the new data. If deleteAfterUse() is set on the old custom data it will also be deleted.

Custom data can be shared between render items, however deleteAfterUse() for the custom data should be false in this case and the user should manage the lifetime of the custom data.

To remove custom user data from a render item, simply call this method with NULL as the parameter.

Note that Maya objects which have render items that have custom user data cannot be consolidated and so draw performance may suffer.

Parameters:
[in]userDataThe custom data to store on the render item
void enable ( bool  on)

Enable or disable the render item for rendering.

Any render item (user or internal) may be enabled/disabled to allow/prevent draw.

Parameters:
[in]onNew enable state for render item
void castsShadows ( bool  on)

Enable or disable the ability of the render item to cast shadows.

By default the MRenderItem will use the value from the castsShadows attribute of the shape node it's representing.

Parameters:
[in]onNew cast shadow state for the render item
void receivesShadows ( bool  on)

Enable or disable the ability of the render item to receive shadows.

By default the MRenderItem will use the value from the receiveShadows attribute of the shape node it's representing.

Parameters:
[in]onNew receive shadow state for the render item
bool associateWithIndexBuffer ( const MIndexBuffer buffer) const

Use to indicate that a particular index buffer should be used with this render item.

This method must be called from MPxGeometryOverride in order to link index buffers generated in the MGeometry class with specific render items. Without an index buffer, a render item cannot draw.

Parameters:
[in]bufferThe buffer to associate
Returns:
True on success
MUserData * customData ( ) const

Retrieve custom data from the render item, returns NULL if no such data has ever been set on the render item.

Returns:
The custom data on the render item, or NULL if none
Examples:
hwPhongShader.cpp.
bool isEnabled ( ) const

Get the enable state of the render item.

Returns:
True if the render item is enabled
bool castsShadows ( ) const

Get the castsShadows state of the render item.

Returns:
True if the render item can cast shadows
bool receivesShadows ( ) const

Get the receivesShadows state of the render item.

Returns:
True if the render item can receive shadows
MString name ( ) const

Get the name of the render item.

Returns:
The name of the render item
MGeometry::Primitive primitive ( ) const

Get the primitive type drawn by the render item.

Returns:
The primitive type
Examples:
cgfxShaderNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.
MGeometry::Primitive primitive ( int &  stride) const

Get the primitive type drawn by the render item, as well as its stride.

Parameters:
[out]strideThe stride of the primitive.
Returns:
The primitive type
MGeometry::DrawMode drawMode ( ) const

Get the draw mode for the render item.

Returns:
The draw mode
MDagPath sourceDagPath ( ) const

Retrieve the MDagPath for the instance of the object that generated this render item.

NOTE: It is invalid to use the DAG path during a draw callback (e.g. MPxShaderOverride::draw()) to query information about Maya dependency nodes. Such behaviour may result in instability.

Returns:
The path to the instance of the object or an invalid path on failure
MObject component ( ) const

Get the optional component for the render item.

Returns:
the component. This will be null if there is no component.
const MVertexBufferDescriptorList & requiredVertexBuffers ( ) const

Get a list of vertex buffer descriptors that describe the buffers required to draw the given render item.

These are determined by the shader that will be used to draw the render item and so this method will return a non-empty list as long as there is a shader assigned to the render item (so any internal render item as well as any user render item that has had setUseSolidShader() called on it).

Returns:
A const reference to the list of descriptors
const MGeometry * geometry ( ) const

Access full geometry data for the render item.

Returns NULL if geometry has not been generated yet. This is meant to be called from MPxShaderOverride::draw() in order to access the hardware resource handles of the vertex and index buffers used by the render item to allow for manual stream binding. The memory for the MGeometry instance returned is owned and managed internally.

Returns:
The geometry data for this render item
Examples:
cgfxShaderNode.cpp, hwColorPerVertexShader.cpp, and hwPhongShader.cpp.
MBoundingBox boundingBox ( MSpace::Space  space = MSpace::kObject,
MStatus ReturnStatus = NULL 
) const

Returns the bounding box for the geometry data of the render item.

Returns a zero-bounding box if the geometry has not been generated yet. This is meant to be called from MPxShaderOverride::draw() to access the bounding box for the consolidated geometry that should be drawn.

Parameters:
[in]spaceThe requested space of the bounding box.
[out]ReturnStatusStatus code.
Returns:
The bounding box for the geometry of this render item
Status Codes:
Examples:
hwColorPerVertexShader.cpp.
bool isConsolidated ( ) const

Get the consolidated state of the render item.

When multiple objects are compatible, their geometry can be consolidated into a single render item, to provide better performance by concatening their index and vertex buffers.

Use sourceIndexMapping() to access the mapping of the geometries making up this item.

Returns:
True if the render item is consolidated
void sourceIndexMapping ( MGeometryIndexMapping geometryIndexMapping) const

Get the geometry index mapping of the multiples objects contained by this consolidated render item.

Multiple geometries can be concatenated to improve rendering performance. You can access the index mapping of the geometries in order to render them separately. The index mapping gives you the name, and index start and length of each geometry.

Parameters:
[out]geometryIndexMappingThe geometry index mapping
const char * className ( ) [static]

Returns the name of this class.

Returns:
The name of this class.

MRenderItem MRenderItem MRenderItem MRenderItem MRenderItem MRenderItem MRenderItem MRenderItem MRenderItem MRenderItem
MRenderItem MRenderItem MRenderItem MRenderItem MRenderItem MRenderItem MRenderItem MRenderItem MRenderItem MRenderItem