#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:: apiDirectionalLightShape/apiDirectionalLightShape.cpp, apiMeshShape/apiMeshGeometryOverride.cpp, apiMeshShape/apiMeshGeometryOverride.h, apiMeshShape/apiMeshSubSceneOverride.cpp, apiMeshShape/apiMeshSubSceneOverride.h, cgFx/cgfxShaderNode.cpp, dx11Shader/dx11Shader.cpp, dx11Shader/dx11Shader.h, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, footPrintNode_SubSceneOverride/footPrintNode_SubSceneOverride.cpp, geometryReplicator/geometryReplicator.cpp, glslShader/GLSLShader.cpp, glslShader/GLSLShader.h, glslShader/GLSLShaderOverride.cpp, gpuCache/gpuCacheSubSceneOverride.cpp, gpuCache/gpuCacheSubSceneOverride.h, hwColorPerVertexShader/hwColorPerVertexShader.cpp, hwPhongShader/hwPhongShader.cpp, and viewRenderOverride/viewRenderOverrideOperations.cpp.

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.

MShaderInstance *	getShader ()
	Get the shader used when drawing this render item. More...

const MShaderInstance *	getShader () 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...

MUserData *	customData () 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. More...

const MVertexBufferDescriptorList &	requiredVertexBuffers () const
	Get a list of vertex buffer descriptors that describe the buffers required to draw the given render item. More...

const MGeometry *	geometry () 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
	Get the consolidated state of the render 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	wantSubSceneConsolidation () const
	Returns whether or not this render item is eligible for consolidation when added to an MSubSceneContainer. More...

void	setWantSubSceneConsolidation (bool state)
	Set whether or not this render item is eligible for consolidation when added to an MSubSceneContainer. 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...

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

Static Public Member Functions
static MRenderItem *	Create (const MString &name, RenderItemType type, MGeometry::Primitive primitive)
	Static MRenderItem creation utility. More...

static MRenderItem *	Create (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 MRenderItem *	Create (const MString &name, MGeometry::Primitive primitive, MGeometry::DrawMode mode, bool raiseAboveShaded)

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.

Friends
class	MGeometryRequirements

Member Enumeration Documentation

enum RenderItemType

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]	name	The name of the render item (should be non-empty)
[in]	type	The type of the render item. Internal types are not allowed and will result no item being created.
[in]	primitive	The primitive type of the render item

Returns: A new render item

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, apiMeshShape/apiMeshSubSceneOverride.cpp, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, and footPrintNode_SubSceneOverride/footPrintNode_SubSceneOverride.cpp.

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] item The 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] 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.

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] mode The draw mode for the render item

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, apiMeshShape/apiMeshSubSceneOverride.cpp, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, footPrintNode_SubSceneOverride/footPrintNode_SubSceneOverride.cpp, and geometryReplicator/geometryReplicator.cpp.

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] mat The matrix to use when drawing this item

Returns: True on success

Examples:: apiMeshShape/apiMeshSubSceneOverride.cpp, and footPrintNode_SubSceneOverride/footPrintNode_SubSceneOverride.cpp.

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

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, apiMeshShape/apiMeshSubSceneOverride.cpp, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, footPrintNode_SubSceneOverride/footPrintNode_SubSceneOverride.cpp, and geometryReplicator/geometryReplicator.cpp.

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 unsupported 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 during shading network evaluation to ensure that the shader instance fits its requirements. If it is invalid, a shader instance to fit basic requirements is still created but will not include any requirements which are geometry dependent.

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 changed, therefore access to the shader instance is not provided in order to avoid unexpected behavior.

Parameters

[in]	shaderNode	The surface shader node.
[in]	shapePath	The path to the instance of the assigned geometry.
[in]	linkLostCb	A pointer to callback function to be invoked whenever the link to the surface shader node is lost.
[in]	linkLostUserData	User 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]	nonTextured	Whether or not a non-textured effect instance is needed. The default value is false.

Returns: True on success

Examples:: apiMeshShape/apiMeshSubSceneOverride.cpp.

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] exclude Set to true if the item should be excluded from post-effects

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, and apiMeshShape/apiMeshSubSceneOverride.cpp.

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] support Set 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.

Note that Maya objects which have render items that have custom user data cannot be consolidated and so draw performance may suffer.

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

Parameters

[in] userData The custom data to store on the render item

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, and apiMeshShape/apiMeshSubSceneOverride.cpp.

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

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, and geometryReplicator/geometryReplicator.cpp.

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] on New cast shadow state for the render item

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, and apiMeshShape/apiMeshSubSceneOverride.cpp.

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] on New receive shadow state for the render item

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, apiMeshShape/apiMeshSubSceneOverride.cpp, and dx11Shader/dx11Shader.cpp.

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:

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] val Depth priority value to set

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, apiMeshShape/apiMeshSubSceneOverride.cpp, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, footPrintNode_SubSceneOverride/footPrintNode_SubSceneOverride.cpp, and geometryReplicator/geometryReplicator.cpp.

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:: apiMeshShape/apiMeshGeometryOverride.cpp.

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] buffer The buffer to associate

Returns: True on success

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, and geometryReplicator/geometryReplicator.cpp.

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:: apiMeshShape/apiMeshGeometryOverride.cpp, apiMeshShape/apiMeshSubSceneOverride.cpp, gpuCache/gpuCacheSubSceneOverride.cpp, and hwPhongShader/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

Get the name of the render item.

Returns: The name of the render item

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, gpuCache/gpuCacheSubSceneOverride.cpp, and viewRenderOverride/viewRenderOverrideOperations.cpp.

MRenderItem::RenderItemType type ( ) const

Get the type of the render item.

Returns: The type of the render item

Examples:: dx11Shader/dx11Shader.cpp, and glslShader/GLSLShader.cpp.

MGeometry::Primitive primitive ( ) const

Get the primitive type drawn by the render item.

Returns: The primitive type

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, cgFx/cgfxShaderNode.cpp, dx11Shader/dx11Shader.cpp, geometryReplicator/geometryReplicator.cpp, glslShader/GLSLShader.cpp, hwColorPerVertexShader/hwColorPerVertexShader.cpp, and hwPhongShader/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

Get the draw mode for the render item.

Returns: The draw mode

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp.

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:: apiMeshShape/apiMeshGeometryOverride.cpp, hwPhongShader/hwPhongShader.cpp, and viewRenderOverride/viewRenderOverrideOperations.cpp.

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

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp.

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:: cgFx/cgfxShaderNode.cpp, dx11Shader/dx11Shader.cpp, hwColorPerVertexShader/hwColorPerVertexShader.cpp, and hwPhongShader/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/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

Examples:: hwPhongShader/hwPhongShader.cpp.

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] geometryIndexMapping The geometry index mapping

Examples:: hwPhongShader/hwPhongShader.cpp.

bool wantSubSceneConsolidation ( ) const

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

Returns: True if the render item is eligible for sub scene consolidation.

void setWantSubSceneConsolidation ( bool state )

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

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] state The new want sub scene consolidation state

Examples:: footPrintNode_SubSceneOverride/footPrintNode_SubSceneOverride.cpp.

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] state The new sub scene compatibility state

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] mask The selection mask

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, and apiMeshShape/apiMeshSubSceneOverride.cpp.

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]	parameterNames	The list of parameter names
[out]	ReturnStatus	Status 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]	parameterName	Name of the parameter
[out]	ReturnStatus	Status 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]	parameterName	Name of the parameter
[out]	ReturnStatus	Status 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]	parameterName	Name of the parameter
[out]	ReturnStatus	Status 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]	parameterName	Name of the parameter
[out]	size	The number of values in the array
[out]	ReturnStatus	Status 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:: dx11Shader/dx11Shader.cpp, and glslShader/GLSLShader.cpp.

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

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

Returns: A new render item

The documentation for this class was generated from the following files:

MHWGeometry.h
MHWGeometry.cpp

MRenderItem Class Reference

Class Description

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Member Enumeration Documentation

Member Function Documentation