MRenderItem Class Reference

+ Related help topics:

#include <MHWGeometry.h>

Class Description

A single renderable entity.

MRenderItem represents a single renderable entity. Each such entity is defined by a name, a render item type and a primitive type. The render item type affects how Maya treats the render item under various contexts.

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

MRenderItem objects are also used by MPxSubSceneOverride for specifying all information about all drawable objects produced by the override.

+ Examples:

Public Types

enum  RenderItemType {
  MaterialSceneItem, NonMaterialSceneItem, DecorationItem, InternalItem,
  InternalMaterialItem, InternalTexturedMaterialItem, InternalUnsupportedMaterialItem, OverrideNonMaterialItem
}
 Type descriptor for render items which drives how Maya treats them in the render pipeline. More...
 
typedef void(* LinkLostCallback) (MUserData *userData)
 Definition for callback function triggered when shader instance assigned by setShaderFromNode() is no longer valid.
 

Public Member Functions

void setDrawMode (MGeometry::DrawMode mode)
 Set the draw mode for the render item. More...
 
bool setMatrix (const MMatrix *mat)
 Override the object to world transformation matrix to use when drawing this render item. More...
 
bool setShader (const MShaderInstance *shader, const MString *customStreamName=NULL)
 Set shader to use when drawing this render item. More...
 
bool setShaderFromNode (const MObject &shaderNode, const MDagPath &shapePath, LinkLostCallback linkLostCb=NULL, MUserData *linkLostUserData=NULL, bool nonTextured=false)
 Set shader to use when drawing this render item. More...
 
void setExcludedFromPostEffects (bool exclude)
 Set whether this item should be excluded from post-effects like SSAO and depth-of-field. More...
 
void setSupportsAdvancedTransparency (bool support)
 Set whether this item supports advanced transparency like depth peeling. More...
 
void setCustomData (MUserData *userData)
 Associate custom user data with this render item. More...
 
void enable (bool on)
 Enable or disable the render item for rendering. More...
 
void castsShadows (bool on)
 Enable or disable the ability of the render item to cast shadows. More...
 
void receivesShadows (bool on)
 Enable or disable the ability of the render item to receive shadows. More...
 
void depthPriority (unsigned int val)
 Set the depth priority of the render item. More...
 
bool isShaderFromNode () const
 Return true if the shader instance was set by evaluating the shading network of a surface shader node (either standard or custom) in the scene via setShaderFromNode() method.
 
MShaderInstancegetShader ()
 Get the shader used when drawing this render item. More...
 
const MShaderInstancegetShader () const
 Get a const pointer to the shader used by this render item. More...
 
bool associateWithIndexBuffer (const MIndexBuffer *buffer) const
 Use to indicate that a particular index buffer should be used with this render item. More...
 
bool excludedFromPostEffects () const
 Get whether this item is excluded from post-effects like SSAO and depth-of-field. More...
 
bool supportsAdvancedTransparency () const
 Returns true if this item supports advanced transparency like depth peeling. More...
 
MUserDatacustomData () const
 Retrieve custom data from the render item, returns NULL if no such data has ever been set on the render item. More...
 
bool isEnabled () const
 Get the enable state of the render item. More...
 
bool castsShadows () const
 Get the castsShadows state of the render item. More...
 
bool receivesShadows () const
 Get the receivesShadows state of the render item. More...
 
unsigned int depthPriority () const
 Get the depth priority value for the render item. More...
 
MString name () const
 Get the name of the render item. More...
 
RenderItemType type () const
 Get the type of the render item. More...
 
MGeometry::Primitive primitive () const
 Get the primitive type drawn by the render item. More...
 
MGeometry::Primitive primitive (int &stride) const
 Get the primitive type drawn by the render item, as well as its stride. More...
 
MGeometry::DrawMode drawMode () const
 Get the draw mode for the render item. More...
 
MDagPath sourceDagPath () const
 Retrieve the MDagPath for the instance of the object that generated this render item. More...
 
MObject component () const
 Get the optional component for the render item if the render item represents the drawing of a component as a result of per-face shader assignment, component selection highlighting etc. More...
 
MObject shadingComponent () const
 Get the optional shading component for the render item. More...
 
void setAllowIsolateSelectCopy (bool state)
 When a 3D model view activates Isolate Select for components, Viewport 2.0 will create and maintain necessary render items to represent the drawing of the isolate selected components specifically for that view. More...
 
bool allowIsolateSelectCopy () const
 Returns whether or not the render item allows its copies to be created for the drawing of isolate selected components. More...
 
bool isIsolateSelectCopy () const
 Returns whether or not the render item is a copy created to represent the drawing of an isolate selected component. More...
 
const MVertexBufferDescriptorListrequiredVertexBuffers () const
 Get a list of vertex buffer descriptors that describe the buffers required to draw the given render item. More...
 
const MGeometrygeometry () const
 Access full geometry data for the render item. More...
 
MBoundingBox boundingBox (MSpace::Space space=MSpace::kObject, MStatus *ReturnStatus=NULL) const
 Returns the bounding box for the geometry data of the render item. More...
 
bool isConsolidated () const
 Return whether or not this render item is a consolidated item. More...
 
bool isMultiDraw () const
 
void sourceIndexMapping (MGeometryIndexMapping &geometryIndexMapping) const
 Get the geometry index mapping of the multiples objects contained by this consolidated render item. More...
 
bool wantConsolidation () const
 Return whether or not this render item wants to participate in consolidation. More...
 
void setWantConsolidation (bool state)
 Set whether or not this render item wants to participate in consolidation. More...
 
bool isCompatibleWithMayaInstancer () const
 Returns whether or not this render item can be used as an instance object with Maya Instancer. More...
 
void setCompatibleWithMayaInstancer (bool state)
 Set whether or not this render item can be used as an instance object with Maya Instancer. More...
 
void setTreatAsTransparent (bool val)
 Set whether or not this object should be treated as a transparent item. More...
 
MSelectionMask selectionMask () const
 Get the render item selection mask. More...
 
void setSelectionMask (const MSelectionMask &mask)
 Set the render item selection mask. More...
 
unsigned int availableShaderParameters (MStringArray &parameterNames, MStatus *ReturnStatus=NULL) const
 Get the list of available shader parameters. More...
 
bool getShaderBoolParameter (const MString &parameterName, MStatus *ReturnStatus=NULL) const
 Get the boolean value of a shader parameter. More...
 
int getShaderIntParameter (const MString &parameterName, MStatus *ReturnStatus=NULL) const
 Get the integer value of a shader parameter. More...
 
float getShaderFloatParameter (const MString &parameterName, MStatus *ReturnStatus=NULL) const
 Get the float value of a shader parameter. More...
 
const float * getShaderFloatArrayParameter (const MString &parameterName, unsigned int &size, MStatus *ReturnStatus=NULL) const
 Get the float values of a shader parameter. More...
 
bool wantSubSceneConsolidation () const
 This method is obsolete. More...
 
void setWantSubSceneConsolidation (bool state)
 This method is obsolete. More...
 

Static Public Member Functions

static MRenderItemCreate (const MString &name, RenderItemType type, MGeometry::Primitive primitive)
 Static MRenderItem creation utility. More...
 
static MRenderItemCreate (const MString &name, RenderItemType type, MGeometry::Primitive primitive, int stride)
 Static MRenderItem creation utility. More...
 
static MRenderItemCreate (const MRenderItem &item)
 Static MRenderItem creation utility. More...
 
static void Destroy (MRenderItem *&item)
 Static MRenderItem destruction utility. More...
 
static const char * className ()
 Returns the name of this class. More...
 
static MRenderItemCreate (const MString &name, MGeometry::Primitive primitive, MGeometry::DrawMode mode, bool raiseAboveShaded)
 This method is obsolete. More...
 

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.
 
static unsigned int sSelectionDepthPriority
 Selection depth priority.
 

Member Enumeration Documentation

Type descriptor for render items which drives how Maya treats them in the render pipeline.

Enumerator
MaterialSceneItem 

A render item which represents an object in the scene that should interact with the rest of the scene and viewport settings (e.g.

a shaded piece of geometry which should be considered in processes like shadow computation, viewport effects, etc.). Inclusion in such processes can also still be controlled through the appropriate methods provided by this class.

NonMaterialSceneItem 

A render item which represents an object in the scene that should not interact with the rest of the scene and viewport settings, but that is also not part of the viewport UI (e.g.

a curve or a bounding box which should not be hidden when 'Viewport UI' is hidden but which should also not participate in processes like shadow computation, viewport effects, etc.).

DecorationItem 

A render item which should be considered to be part of the viewport UI (e.g.

selection wireframe, components, etc.).

InternalItem 

A render item which was created by Maya for internal purposes (e.g.

A render item created as the result of a shader being assigned to a DAG node).

InternalMaterialItem 

An internally created MaterialSceneItem for non-textured mode display.

InternalTexturedMaterialItem 

An internally created MaterialSceneItem for textured mode display.

InternalUnsupportedMaterialItem 

An internally created MaterialSceneItem for showing an unsupported material.

OverrideNonMaterialItem 

A render item which was created by Maya for internal purposes and has been assigned a user defined effect (see MPxShaderOverride::overridesNonMaterialItems)

Member Function Documentation

MRenderItem * Create ( const MString name,
RenderItemType  type,
MGeometry::Primitive  primitive 
)
static

Static MRenderItem creation utility.

By default, newly created render items will draw in shaded, textured and wireframe viewport draw modes. This behavior may be modified by calling setDrawMode() on the newly created render item.

Parameters
[in]nameThe name of the render item (should be non-empty)
[in]typeThe type of the render item. Internal types are not allowed and will result no item being created.
[in]primitiveThe primitive type of the render item
Returns
A new render item
+ Examples:
MRenderItem * Create ( const MString name,
RenderItemType  type,
MGeometry::Primitive  primitive,
int  stride 
)
static

Static MRenderItem creation utility.

By default, newly created render items will draw in shaded, textured and wireframe viewport draw modes. This behavior may be modified by calling setDrawMode() on the newly created render item.

This method allows the stride value to be set. Stride is the number of bytes from the beginning of one element to the beginning of another.

Parameters
[in]nameThe name of the render item (should be non-empty)
[in]typeThe type of the render item. Internal types are not allowed and will result no item being created.
[in]primitiveThe primitive type of the render item
[in]strideThe stride number (default is 1).
Returns
A new render item
MRenderItem * Create ( const MRenderItem item)
static

Static MRenderItem creation utility.

Will copy all parameters from the incoming MRenderItem. The MGeometry and the MShaderInstance stored in the MRenderItems will be shared by both items.

Parameters
[in]itemThe item to copy
Returns
A new render item
void Destroy ( MRenderItem *&  item)
static

Static MRenderItem destruction utility.

The render item will be deleted and the pointer set to be NULL.

Parameters
[in]itemReference 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.

If this item is consolidated, invoking this method may cause this item to be reconsolidated.

This method only affects items explicitly created by the plug-in.

Parameters
[in]modeThe draw mode for the render item
+ Examples:
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.

If this item is consolidated, invoking this method may cause this item to be reconsolidated.

This method only affects items explicitly created by the plug-in.

Parameters
[in]matThe matrix to use when drawing this item
Returns
True on success
+ Examples:
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.

If the shader is NULL this method will clear the shader assignment on the 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
+ Examples:
bool setShaderFromNode ( const MObject shaderNode,
const MDagPath shapePath,
LinkLostCallback  linkLostCb = NULL,
MUserData linkLostUserData = NULL,
bool  nonTextured = false 
)

Set shader to use when drawing this render item.

If no shader is ever set this render item will not draw. This method sets the shader instance to a render item by evaluating the shading network of a surface shader node (either standard or custom) in the scene.

This method only affects items explicitly created by the plug-in.

If the surface shader node is NULL or supported by neither Maya nor the plug-in, this method will clear the shader assignment on the render item, which will thus not be drawn.

The shape path is used as the object context for shading network evaluation to ensure that the shader instance fits its requirements. If the shape path is invalid (e.g. an empty path), a shader instance to fit basic requirements is created but will not include any geometry-dependent requirements.

The linkLostCb will be invoked whenever the link to the surface shader node is lost. The link can be lost in a number of ways, e.g. shader nodes are deleted or shading network connections are modified. However, the linkLostCb will not be invoked for changes to a shading group; if needed, it is the plug-in's responsibility to monitor any changes to the shading group (via MNodeMessage and/or MPxNode::connectionMade/connectionBroken).

There is no guarantee that the surface shader node is still valid after the link is lost. The linkLostCb should check the validity and assign the render item with a shader instance appropriately.

After the shader instance is set, its parameter values can be automatically updated by Viewport 2.0 whenever the related shading attributes are changed, therefore access to the shader instance is not provided in order to avoid unexpected behavior.

Parameters
[in]shaderNodeThe surface shader node.
[in]shapePathThe DAG path of a shape to be used as the object context for shading network evaluation.
[in]linkLostCbA pointer to callback function to be invoked whenever the link to the surface shader node is lost.
[in]linkLostUserDataUser supplied data to be passed into the link lost callback. This data will not be deleted internally and the lifetime must be managed by the caller. The link lost callback will only be called once so it is safe to delete this data anytime after the callback has been triggered.
[in]nonTexturedWhether or not a non-textured effect instance is needed. The default value is false.
Returns
True on success
+ Examples:
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.

If this item is consolidated, invoking this method may cause this item to be reconsolidated.

This method only affects items explicitly created by the plug-in.

Parameters
[in]excludeSet to true if the item should be excluded from post-effects
+ Examples:
void setSupportsAdvancedTransparency ( bool  support)

Set whether this item supports advanced transparency like depth peeling.

The render item type should be MaterialSceneItem in order to draw the item in transparent pass. Also the shader instance should be transparent. If either of the above conditions is not true, this flag has no effect. Default value is false.

If this item is consolidated, invoking this method may cause this item to be reconsolidated.

This method only affects items explicitly created by the plug-in.

Parameters
[in]supportSet to true if the item supports advanced transparency
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.

This item can only be consolidated with others that have matching MUserData pointers, in addition to standard consolidation conditions. If this item is consolidated, invoking this method may cause this item to be reconsolidated.

Parameters
[in]userDataThe custom data to store on the render item
+ Examples:
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.

If this item is consolidated, invoking this method may cause this item to be reconsolidated.

Parameters
[in]onNew cast shadow state for the render item
+ Examples:
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.

If this item is consolidated, invoking this method may cause this item to be reconsolidated.

Parameters
[in]onNew receive shadow state for the render item
+ Examples:
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:

  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.

If this item is consolidated, invoking this method may cause this item to be reconsolidated.

This method only affects items explicitly created by the plug-in.

Parameters
[in]valDepth priority value to set
+ Examples:
MShaderInstance * getShader ( )

Get the shader used when drawing this render item.

The return value is NULL in two cases:

  • No shader instance was set on the render item.
  • The shader instance was set by evaluating shading network of a surface shader node in the scene via setShaderFromNode() method. Because the parameter values of the shader instance can be automatically updated by Viewport 2.0 whenever the related shading attributes changed, access to the shader instance is not provided in order to avoid unexpected behavior.
Returns
The shader instance for the render item or NULL.
+ Examples:
const MShaderInstance * getShader ( ) const

Get a const pointer to the shader used by this render item.

The return value is NULL in two cases:

  • No shader instance was set on the render item.
  • The shader instance was set by evaluating shading network of a surface shader node in the scene via setShaderFromNode() method. Because the parameter values of the shader instance can be automatically updated by Viewport 2.0 whenever the related shading attributes changed, access to the shader instance is not provided in order to avoid unexpected behavior.
Returns
The shader instance for the render item or NULL.
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
+ Examples:
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
bool supportsAdvancedTransparency ( ) const

Returns true if this item supports advanced transparency like depth peeling.

Returns
True if the item supports advanced transparency.
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:
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

Get the type of the render item.

Returns
The type of the render item
+ Examples:
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
+ Examples:
MDagPath sourceDagPath ( ) const

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

If there are many object instances contributing due to consolidation then only one dag path out of all the objects is returned.

The method sourceIndexMapping() should be used if the item is consolidated to access the corresponding dag paths for the objects making up this 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
+ Examples:
MObject component ( ) const

Get the optional component for the render item if the render item represents the drawing of a component as a result of per-face shader assignment, component selection highlighting etc.

If the render item doesn't represent the drawing of a component, then a null MObject will be returned. Use the isNull() method of the MObject to check.

Returns
the component.
MObject shadingComponent ( ) const

Get the optional shading component for the render item.

It is different from the component() method only when a view selected filter is applied.

Therefore, a typical use of this method is to query the isolate selected component on a render item created by Viewport 2.0 when a 3D model view activates Isolate Select for components. See setAllowIsolateSelectCopy() for more information.

If the render item doesn't represent the drawing of a shading component, then a null MObject will be returned. Use the isNull() method of the MObject to check.

Returns
the shading component.
+ Examples:
void setAllowIsolateSelectCopy ( bool  state)

When a 3D model view activates Isolate Select for components, Viewport 2.0 will create and maintain necessary render items to represent the drawing of the isolate selected components specifically for that view.

These render items are copies of their original items and thus have the same properties including name, type, primitive type, draw mode etc., but their shading components are filtered from the view selected set of that view.

By default, a custom render item doesn't allow its copies to be created for the drawing of isolate selected components; plug-ins should call the method to allow this. When this is allowed and multiple views have view selected sets, the render item can have multiple copies and each copy represents the drawing in only one view.

Viewport 2.0 is responsible to update these copies for any changes applied to the original item and the view selected set. It is the duty of the plug-in to retrieve the isolate selected components by calling the shadingComponent() method and populate the geometric buffers appropriately.

The lifetime of the copies is managed by Viewport 2.0, thus it is not safe for plug-ins to cache their pointers.

Parameters
[in]stateTrue if the render item allows its copies to be created for the drawing of isolate selected components
+ Examples:
bool allowIsolateSelectCopy ( ) const

Returns whether or not the render item allows its copies to be created for the drawing of isolate selected components.

See setAllowIsolateSelectCopy() for more information.

Returns
True if the render item allows its copies to be created for the drawing of isolate selected components
bool isIsolateSelectCopy ( ) const

Returns whether or not the render item is a copy created to represent the drawing of an isolate selected component.

See setAllowIsolateSelectCopy() for more information.

Returns
True if the render item is a copy created for an isolate selected component
+ Examples:
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
+ Examples:
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:
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:
bool isConsolidated ( ) const

Return whether or not this render item is a consolidated item.

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

Use the method to identify this item and then use sourceIndexMapping() to access the corresponding DAG paths for the objects making up this item.

Returns
True if the render item is a consolidated item.
+ Examples:
bool isMultiDraw ( ) const
Returns
True if the render item is MultiDraw 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
+ Examples:
bool wantConsolidation ( ) const

Return whether or not this render item wants to participate in consolidation.

Returns
True if the render item wants to participate in consolidation.
void setWantConsolidation ( bool  state)

Set whether or not this render item wants to participate in consolidation.

This method only affects items explicitly created by the plug-in. The value is true by default, unless the item is added to an MSubSceneContainer. When it is true, the geometry of compatible render items will be consolidated into a single render item, to provide better performance.

Render items that are already instanced cannot be consolidated.

For render items added to an MSubSceneContainer, if wantConsolidation is set to true, this will prevent them from being instanced until wantConsolidation is set to false.

Parameters
[in]stateTrue if the render item wants to participate in consolidation.
+ Examples:
bool isCompatibleWithMayaInstancer ( ) const

Returns whether or not this render item can be used as an instance object with Maya Instancer.

Returns
True if the item can work with the Maya Instancer.
void setCompatibleWithMayaInstancer ( bool  state)

Set whether or not this render item can be used as an instance object with Maya Instancer.

There are many situations that the MRenderItem created by the plugin cannot work with the Maya Instancer, normally it is because the plugin developer use a customized vertex shader, and Maya cannot assemble the instanced shader correctly. One such example could be if the output of the instanced position must connect to the input of a customized shader fragment to get the correct result, Maya would fail to assemble the final vertex shader. Another example could be the vertex shader used by the plugin is already an instanced one. So it's the plugin developer's responsibility to inform Maya whether or not the MRenderItem is compatible with Maya Instancer when it is created. If this API is not called explicitly the state is default to false, which means the object will be ignored by Maya Instancer.

Parameters
[in]stateThe new sub scene compatibility state
void setTreatAsTransparent ( bool  val)

Set whether or not this object should be treated as a transparent item.

Set this to true if the object has vertex colors with alpha or other inputs that make it important to treat this object as if it were transparent.

Parameters
[in]valIf true the object will be treated as transparent
MSelectionMask selectionMask ( ) const

Get the render item selection mask.

Returns
The render item selection mask
void setSelectionMask ( const MSelectionMask mask)

Set the render item selection mask.

Parameters
[in]maskThe selection mask
+ Examples:
unsigned int availableShaderParameters ( MStringArray parameterNames,
MStatus ReturnStatus = NULL 
) const

Get the list of available shader parameters.

This is useful for OverrideNonMaterialItem to retrieve default parameters.

Parameters
[out]parameterNamesThe list of parameter names
[out]ReturnStatusStatus code.
Returns
The number of parameters
Status Codes:
  • MS::kSuccess The method was successful
  • MS::kFailure An internal error prevented the value from being retrieved
bool getShaderBoolParameter ( const MString parameterName,
MStatus ReturnStatus = NULL 
) const

Get the boolean value of a shader parameter.

This is useful for OverrideNonMaterialItem to retrieve default parameters. Use availableShaderParameters() to get the list of available parameters.

Parameters
[in]parameterNameName of the parameter
[out]ReturnStatusStatus code.
Returns
The boolean value
Status Codes:
  • MS::kSuccess The method was successful
  • MS::kInvalidParameter The named parameter is not a boolean parameter
  • MS::kUnknownParameter The named parameter is not a parameter of the render item
  • MS::kFailure An internal error prevented the value from being retrieved
int getShaderIntParameter ( const MString parameterName,
MStatus ReturnStatus = NULL 
) const

Get the integer value of a shader parameter.

This is useful for OverrideNonMaterialItem to retrieve default parameters. Use availableShaderParameters() to get the list of available parameters.

Parameters
[in]parameterNameName of the parameter
[out]ReturnStatusStatus code.
Returns
The integer value
Status Codes:
  • MS::kSuccess The method was successful
  • MS::kInvalidParameter The named parameter is not a integer parameter
  • MS::kUnknownParameter The named parameter is not a parameter of the render item
  • MS::kFailure An internal error prevented the value from being retrieved
float getShaderFloatParameter ( const MString parameterName,
MStatus ReturnStatus = NULL 
) const

Get the float value of a shader parameter.

This is useful for OverrideNonMaterialItem to retrieve default parameters. Use availableShaderParameters() to get the list of available parameters.

Parameters
[in]parameterNameName of the parameter
[out]ReturnStatusStatus code.
Returns
The float value
Status Codes:
  • MS::kSuccess The method was successful
  • MS::kInvalidParameter The named parameter is not a float parameter
  • MS::kUnknownParameter The named parameter is not a parameter of the render item
  • MS::kFailure An internal error prevented the value from being retrieved
const float * getShaderFloatArrayParameter ( const MString parameterName,
unsigned int &  size,
MStatus ReturnStatus = NULL 
) const

Get the float values of a shader parameter.

This is useful for OverrideNonMaterialItem to retrieve default parameters. Use availableShaderParameters() to get the list of available parameters.

Parameters
[in]parameterNameName of the parameter
[out]sizeThe number of values in the array
[out]ReturnStatusStatus code.
Returns
A pointer to the float values
Status Codes:
  • MS::kSuccess The value was successfuly retrieved.
  • MS::kInvalidParameter The named parameter is not a float array parameter of requested size.
  • MS::kUnknownParameter The named parameter is not a parameter of the render item.
  • MS::kFailure An internal error prevented the value from being retrieved.
+ Examples:
const char * className ( )
static

Returns the name of this class.

Returns
The name of this class.
MRenderItem * Create ( const MString name,
MGeometry::Primitive  primitive,
MGeometry::DrawMode  mode,
bool  raiseAboveShaded 
)
static

This method is obsolete.

[From Maya 2019]

Deprecated:
Please use the other MRenderItem::Create() method now.
Deprecated:
Please use the other MRenderItem::Create() method now.

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]nameThe name of the render item (should be non-empty)
[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. This will set the depth priority value for this render item to be MRenderItem::sActiveWireDepthPriority. The default depth priority value is MRenderItem::sDormantFilledDepthPriority.
Returns
A new render item
bool wantSubSceneConsolidation ( ) const

This method is obsolete.

Returns whether or not this render item is eligible for consolidation when added to an MSubSceneContainer.

[From Maya 2019]

Deprecated:
Please use MRenderItem::wantConsolidation().
Returns
True if the render item is eligible for sub scene consolidation.
void setWantSubSceneConsolidation ( bool  state)

This method is obsolete.

Set whether or not this render item is eligible for consolidation when added to an MSubSceneContainer.

[From Maya 2019]

Deprecated:
Please use MRenderItem::setWantConsolidation().

SubScene render items that are already instanced cannot be consolidated and will not be consolidated. When wantSubSceneConsolidation is true, this will prevent the render item from being instanced in a sub scene container until it is set to false.

Parameters
[in]stateThe new want sub scene consolidation state

The documentation for this class was generated from the following files:
  • MHWGeometry.h
  • MHWGeometry.cpp