MRenderItem Class Reference
This reference page is linked to from the following overview topics: Autodesk Maya 2014, Extension for Autodesk Maya 2013, Data Classes, Scene Overrides, 2.1 Render Items (MRenderItem), 2.2 Geometric Data (MGeometry), 2.3 Shader Instances, 3.7 Sub-scene Overrides, 3.8 Render Loop Overrides, 4.5 Handling custom renderables for object overrides.
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>
Public Member Functions | |
| void | setDrawMode (MGeometry::DrawMode mode) |
| Set the draw mode for the render item. | |
| bool | setMatrix (const MMatrix *mat) |
| Override the object to world transformation matrix to use when drawing this render item. | |
| bool | setShader (const MShaderInstance *shader, const MString *customStreamName=NULL) |
| Set shader to use when drawing this render item. | |
| MShaderInstance * | getShader () |
| Get the shader used by this render item. | |
| void | setExcludedFromPostEffects (bool exclude) |
| Set whether this item should be excluded from post-effects like SSAO and depth-of-field. | |
| 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. | |
| void | depthPriority (unsigned int val) |
| Set the depth priority of the render item. | |
| const MShaderInstance * | getShader () const |
| Get a const pointer to the shader used by this render item. | |
| bool | associateWithIndexBuffer (const MIndexBuffer *buffer) const |
| Use to indicate that a particular index buffer should be used with this render item. | |
| bool | excludedFromPostEffects () const |
| Get whether this item is excluded from post-effects like SSAO and depth-of-field. | |
| MUserData * | customData () 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. | |
| unsigned int | depthPriority () const |
| Get the depth priority value for 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 MVertexBufferDescriptorList & | requiredVertexBuffers () const |
| Get a list of vertex buffer descriptors that describe the buffers required to draw the given render item. | |
| const MGeometry * | geometry () 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 MRenderItem * | Create (const MString &name, MGeometry::Primitive primitive, MGeometry::DrawMode mode, bool raiseAboveShaded) |
| Static MRenderItem creation utility. | |
| static void | Destroy (MRenderItem *&item) |
| Static MRenderItem destruction utility. | |
| static const char * | className () |
| Returns the name of this class. | |
Static Public Attributes | |
| static unsigned int | sDormantFilledDepthPriority |
| Dormant filled primitive depth priority. | |
| static unsigned int | sDormantWireDepthPriority |
| Dormant wireframe primitive depth priority. | |
| static unsigned int | sHiliteWireDepthPriority |
| Hilite wireframe primitive depth priority. | |
| static unsigned int | sActiveWireDepthPriority |
| Active wireframe primitive depth priority. | |
| static unsigned int | sActiveLineDepthPriority |
| Active line / edge depth priority. | |
| static unsigned int | sDormantPointDepthPriority |
| Dormant point depth priority. | |
| static unsigned int | sActivePointDepthPriority |
| Active point depth priority. | |
Friends | |
| class | MGeometryRequirements |
Member Function Documentation
| MRenderItem * Create | ( | const MString & | name, |
| MGeometry::Primitive | primitive, | ||
| MGeometry::DrawMode | mode, | ||
| bool | raiseAboveShaded | ||
| ) | [static] |
Static MRenderItem creation utility.
If the draw mode is not MGeometry::kAll, the render item will only be drawn when the specified viewport mode is active.
- Parameters:
-
[in] name The name of the render item (should be non-empty) [in] primitive The primitive type of the render item [in] mode The draw mode of the render item [in] raiseAboveShaded Push this render item above all shaded items drawn for the same object. This will set the depth priority value for this render item to be MRenderItem::sActiveWireDepthPriority. The default depth priority value is MRenderItem::sDormantFilledDepthPriority.
| void Destroy | ( | MRenderItem *& | item | ) | [static] |
Static MRenderItem destruction utility.
The render item will be deleted and the pointer set to be NULL.
- Parameters:
-
[in] item Reference to a pointer to the item to delete
| void setDrawMode | ( | MGeometry::DrawMode | mode | ) |
Set the draw mode for the render item.
If the draw mode is all, the render item will be drawn regardless of the viewport draw mode. Otherwise the render item will only be drawn when the viewport is set to draw objects in the specified mode.
This method only affects items explicitly created by the plug-in.
- Parameters:
-
[in] mode The draw mode for the render item
| bool setMatrix | ( | const MMatrix * | mat | ) |
Override the object to world transformation matrix to use when drawing this render item.
If unset, the render item will draw using the transformation matrix of the associated Maya DAG node. Pass a NULL matrix to this method to remove the override.
This method only affects items explicitly created by the plug-in.
- Parameters:
-
[in] mat The matrix to use when drawing this item
- Returns:
- True on success
| 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).
This method only affects items explicitly created by the plug-in.
- Parameters:
-
[in] shader The shader to use when drawing this item [in] customStreamName If non-null, shader will generate geometry requirements with the given name
- Returns:
- True on success
| MShaderInstance * getShader | ( | ) |
Get the shader used by this render item.
The return value may be NULL if no shader is set on the render item.
- Returns:
- The shader instance for the render item or NULL if none
| void setExcludedFromPostEffects | ( | bool | exclude | ) |
Set whether this item should be excluded from post-effects like SSAO and depth-of-field.
Render items default to being excluded from post-effects.
This method only affects items explicitly created by the plug-in.
- Parameters:
-
[in] exclude Set to true if the item should be excluded from post-effects
| 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] userData The 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] on New 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.
This method only affects items explicitly created by the plug-in. If an item is categorized as drawing in wireframe mode then it will by default not cast shadows.
- Parameters:
-
[in] on New 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.
This method only affects items explicitly created by the plug-in. If an item is categorized as drawing in wireframe mode then it will by default not receive shadows.
- Parameters:
-
[in] on New receive shadow state for the render item
| void depthPriority | ( | unsigned int | val | ) |
Set the depth priority of the render item.
The higher the depth priority the closer it will be drawn to the camera.
A set of internally used depth priorites is provided. They are listed below in increasing priority order:
- MRenderItem::sDormantFilledDepthPriority
- MRenderItem::sDormantWireDepthPriority
- MRenderItem::sHiliteWireDepthPriority
- MRenderItem::sActiveWireDepthPriority
- MRenderItem::sDormantPointDepthPriority
- MRenderItem::sActivePointDepthPriority
Setting depth priority can avoid depth fighting issues which may arise when the depth of the pixels drawn for a given render item may be the same as for another. For example a wireframe render item and a shaded render item may be drawn at the same depth. To avoid depth fighting the wireframe render items' depth priority may be set to a greater value.
This method only affects items explicitly created by the plug-in.
- Parameters:
-
[in] val Depth priority value to set
| const MShaderInstance * getShader | ( | ) | const |
Get a const pointer to the shader used by this render item.
The return value may be NULL if no shader is set on the render item.
- Returns:
- The shader instance for the render item or NULL if none
| 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] buffer The buffer to associate
- Returns:
- True on success
| bool excludedFromPostEffects | ( | ) | const |
Get whether this item is excluded from post-effects like SSAO and depth-of-field.
- Returns:
- True if the item is excluded from post-effects
| 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
| unsigned int depthPriority | ( | ) | const |
Get the depth priority value for the render item.
- Returns:
- Depth priority value
| MString name | ( | ) | const |
| 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] stride The stride of the primitive.
- Returns:
- The primitive type
| MGeometry::DrawMode drawMode | ( | ) | const |
| 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] space The requested space of the bounding box. [out] ReturnStatus Status code.
- Returns:
- The bounding box for the geometry of this render item
- Status Codes:
- MStatus::kSuccess The method was successful
- MStatus::kFailure The render item is unbounded or does not have a valid associated geometry.
- 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] geometryIndexMapping The geometry index mapping
| const char * className | ( | ) | [static] |
