- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Static Public Attributes | Friends

# MRenderItem Class Reference
OpenMayaRender - API module for rendering

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.

Search for all occurrences

## 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
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. Search for all occurrences
static unsigned int | sDormantWireDepthPriority
| Dormant wireframe primitive depth priority. Search for all occurrences
static unsigned int | sHiliteWireDepthPriority
| Hilite wireframe primitive depth priority. Search for all occurrences
static unsigned int | sActiveWireDepthPriority
| Active wireframe primitive depth priority. Search for all occurrences
static unsigned int | sActiveLineDepthPriority
| Active line / edge depth priority. Search for all occurrences
static unsigned int | sDormantPointDepthPriority
| Dormant point depth priority. Search for all occurrences
static unsigned int | sActivePointDepthPriority
| Active point depth priority.
## Friends Search for all occurrences
class | MGeometryRequirements Search for all occurrences

## Member Function Documentation

MRenderItem * Create | ( | const MString & | name,
|  | MGeometry::Primitive | primitive,
|  | MGeometry::DrawMode | mode,
|  | bool | raiseAboveShaded
| ) |  | `[static]`

Search for all occurrences

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]`

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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`
| ) |  |

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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:

1. MRenderItem::sDormantFilledDepthPriority
2. MRenderItem::sDormantWireDepthPriority
3. MRenderItem::sHiliteWireDepthPriority
4. MRenderItem::sActiveWireDepthPriority
5. MRenderItem::sDormantPointDepthPriority
6. 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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

Get the enable state of the render item.

Returns:
  True if the render item is enabled

bool castsShadows | ( |  | ) | const

Search for all occurrences

Get the castsShadows state of the render item.

Returns:
  True if the render item can cast shadows

bool receivesShadows | ( |  | ) | const

Search for all occurrences

Get the receivesShadows state of the render item.

Returns:
  True if the render item can receive shadows

unsigned int depthPriority | ( |  | ) | const

Search for all occurrences

Get the depth priority value for the render item.

Returns:
  Depth priority value

MString name | ( |  | ) | const

Search for all occurrences

Get the name of the render item.

Returns:
  The name of the render item

MGeometry::Primitive primitive | ( |  | ) | const

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

Get the draw mode for the render item.

Returns:
  The draw mode

MDagPath sourceDagPath | ( |  | ) | const

Search for all occurrences

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

Search for all occurrences

Get the optional component for the render item.

Returns:
  the component. This will be null if there is no component.

const MVertexBufferDescriptorList & requiredVertexBuffers | ( |  | ) | const

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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]`

Search for all occurrences

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