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

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Friends

# MRenderItem Class Reference

# OpenMayaRender - API module for rendering

This reference page is linked to from the following overview topics: Data Classes.

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
| 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.
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.
## Static Public Member Functions
static const char * | className ()
| Returns the name of this class.
## Friends
class | MGeometryRequirements Search for all occurrences

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

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

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

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

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

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

bool isEnabled | ( |  | ) | const

Search for all occurrences

Get the enable state of the render item.

Returns:
  True if the render item is enabled

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

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