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>
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. |
|
| bool | associateWithIndexBuffer (const MIndexBuffer *buffer) const |
| Use to indicate that a particular index
buffer should be used with this render item. |
|
| 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.
|
|
| MString | name () const |
| Get the name of the render item. |
|
| MGeometry::Primitive | primitive () const |
| Get the primitive type drawn by the render
item. |
|
| MGeometry::DrawMode | drawMode () const |
| Get the draw mode 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. |
|
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] name The name of the render item [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
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] 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
| 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
| 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
| 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
| bool isEnabled | ( | ) | const |
Get the enable state of the render item.
- Returns:
- True if the render item is enabled
| 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::DrawMode drawMode | ( | ) | const |
| 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.
| const char * className | ( | ) | [static] |
