MPxShadingNodeOverride Class Reference

#include <MPxShadingNodeOverride.h>

Class Description

Base class for user defined shading node overrides.

MPxShadingNodeOverride allows the user to specify how a plugin shading node in Maya should interact with other shading nodes in Viewport 2.0. Specifically this class lets the user inform Maya which shading fragment (or fragment graph) to use to represent the node in the Viewport 2.0 shading graph. Using this system, plugin nodes may function seamlessly with internal nodes as well as other plugin nodes from unrelated plugins (both geometry and shaders).

MPxShadingNodeOverride differs from MPxShaderOverride in that implementations of MPxShaderOverride are required to produce the whole shading effect for a shader graph (including lighting) while MPxShadingNodeOverride is only required to produce a small fragment for an individual node.

Shade fragments and graphs are managed by MFragmentManager. New fragments and/or graphs may be defined using XML and registered with Maya through MFragmentManager. These fragments and graphs may then be referenced by implementations of MPxShadingNodeOverride. For the purposes of MPxShadingNodeOverride, fragments and fragment graphs can be used interchangeably. A fragment graph is merely a special case of a fragment. It still has input and output parameters it is just composed of other fragments instead of directly defining shading code itself. In the following descriptions assume that any reference to a fragment can also refer to a fragment graph.

Implementations of MPxShadingNodeOverride have two main responsibilities. One is to define the fragment to use and how the parameters of that fragment are related to the attributes on the Maya node. The second (optional) responsibility is to manually set the values of the parameters for the fragment on the final shader when the associated Maya shading node changes.

When Maya needs to create a shading effect for a particular shading node graph, it will create a shading fragment for each node and connect them together to form the full effect. Any node in the node graph whose node type is associated with an implementation of MPxShadingNodeOverride will use the shade fragment named by the fragmentName() method. This will happen any time the Maya shading node graph changes in such a way as to require a rebuild of the full effect (for example, if connections are changed).

The parameters on the shading fragment are automatically driven by attributes on the Maya node which have matching names and types. The plugin may also specify associations between attributes and parameters of the same type but with different names by overriding the getCustomMappings() function. This method is called immediately after the fragment is created and before the automatic mappings are done. No automatic mapping will be created for any parameter on the fragment that already has a custom mapping.

All functionality is driven through these attribute parameter mappings. When Maya is traversing the shading node graph building and connecting fragments it will only traverse connections where the input attribute on the node has a defined mapping (custom or automatic). Also, as fragments are combined for all the nodes in the Maya shading graph, their parameters are renamed in order to avoid collisions (allowing the same fragment type to be used multiple times in a graph). Only parameters with mappings will be renamed, all others may suffer name collisions which will produce unpredictable results.

In addition to informing Maya about the relationship between attributes and parameters, custom mappings can be used to prevent Maya from trying to connect other fragments to a particular parameter or to prevent a parameter from being renamed (name collisions become the responsibility of the user). Custom mappings may also be used to tell Maya to rename a parameter to avoid name collisions but not to associate it with any attribute (when the attribute name of the mapping is the empty string). The values for such a parameter must be set manually in updateShader(). This can be useful when a parameter is not directly driven by an attribute but must still be set with a computed value.

An implementation of MPxShadingNodeOverride which specifies a shade fragment to use along with optional custom mappings will function well in the Viewport 2.0 shading system. The parameter values on the final effect will automatically be set to the values of the attributes on the Maya node whenever the Maya node changes. However, if additional control is required, the implementation can also override the updateDG() and updateShader() methods. These two methods will be called when Maya needs to update the parameter values on the final shader.

In updateDG() the implementation should query and cache any information it needs from the Maya dependency graph. It is an error to attempt to access the DG in updateShader() and doing so may result in instability.

In updateShader() the implementation is given the MShaderInstance of which the fragment it specified is a part. It is also given the full list of attribute parameter mappings known to Maya for the node (both automatic and custom). Since most parameters are renamed from the original names on the fragment, the implementation must use the "resolved" name from the mappings to set values on the MShaderInstance. The implementation may set the value of any parameter on the shader instance but any parameter with a mapping that defines an attribute will be set automatically. Only parameters that need special computation to set their values need to be handled. Although it is possible to set values on the MShaderInstance for parameters from other fragments in the Maya shading node graph, this behaviour is not recommended or supported. Such values may get overwritten and behaviour will be unpredictable.

Implementations of MPxShadingNodeOverride must be registered with Maya through MDrawRegistry.

+ Examples:
+ Inheritance diagram for MPxShadingNodeOverride:

Public Member Functions

 MPxShadingNodeOverride (const MObject &obj)
 Construct an MPxShadingNodeOverride. More...
 
virtual ~MPxShadingNodeOverride ()
 Destructor.
 
virtual MHWRender::DrawAPI supportedDrawAPIs () const
 Returns the draw API supported by this override. More...
 
virtual bool allowConnections () const
 An override may prevent Maya from connecting fragments to specific parameters of the fragment for this override by providing custom attribute parameter mappings. More...
 
virtual MString fragmentName () const =0
 Override this method to return the name of the fragment or fragment graph to use for rendering the shading node associated with this override. More...
 
virtual void getCustomMappings (MAttributeParameterMappingList &mappings)
 Maya will automatically match parameters on the shade fragment specified by this override with attributes on the associated Maya node as long as the names and types match. More...
 
virtual MString outputForConnection (const MPlug &sourcePlug, const MPlug &destinationPlug)
 When Maya attempts to connect the fragment for this override to the fragment for another node in the shading network, it will call this method to get the name of the output on the fragment to use for the connection. More...
 
virtual bool valueChangeRequiresFragmentRebuild (const MPlug *plug) const
 This method will be called by Maya when it detects changes in the attribute values of nodes in the shading network. More...
 
virtual void updateDG ()
 This method is called every time Maya needs to update the parameter values on the final shading effect of which the fragment produced by this override is a part. More...
 
virtual void updateShader (MShaderInstance &shader, const MAttributeParameterMappingList &mappings)
 This method is called every time Maya needs to update the parameter values on the final shading effect of which the fragment produced by this override is a part. More...
 

Static Public Member Functions

static const char * className ()
 Returns the name of this class. More...
 

Constructor & Destructor Documentation

MPxShadingNodeOverride ( const MObject obj)

Construct an MPxShadingNodeOverride.

Parameters
[in]objThe Maya shading node this override will be used for

Member Function Documentation

MHWRender::DrawAPI supportedDrawAPIs ( ) const
virtual

Returns the draw API supported by this override.

The returned value may be formed as the bitwise 'or' of MHWRender::DrawAPI elements to indicate that the override supports multiple draw APIs. This method returns 'MHWRender::kOpenGL' by default.

Returns
The draw API supported by this override
+ Examples:
bool allowConnections ( ) const
virtual

An override may prevent Maya from connecting fragments to specific parameters of the fragment for this override by providing custom attribute parameter mappings.

It is also possible to prevent connections to all parameters on the fragment by overriding this method to return false. In that case, the fragment for this override will become a final fragment, and nothing will be connected to it. This is equivalent to creating an attribute parameter mapping for every parameter on the fragment and setting the allowConnection flag on each mapping to false.

This method is called once only, just after creation of the override.

The default return value is true.

Returns
True if connections should be allowed to parameters of the fragment that do not have custom mappings that specifically prevent connections.
MString fragmentName ( ) const
pure virtual

Override this method to return the name of the fragment or fragment graph to use for rendering the shading node associated with this override.

This fragment will be automatically connected to the other fragments for the other nodes in the shading network to produce a complete shading effect.

A fragment with the returned name must already exist in the fragment manager for rendering to succeed. If the fragment does not exist, the associated node will not contribute to shading.

The parameter values for the fragment will be automatically populated from the attribute values on the node wherever the name and type of a parameter on the fragment match the name and type of an attribute on the node.

The fragment will only be connected to the other fragments in the graph if the output parameter of the fragment has the same name as the output attribute of the node that is connected to the rest of the shading network. To support multiple output attributes of a node, the fragment should return a "struct" type parameter. The names of the members of the struct should match the names of the output attributes for which support is desired. The fragment must compute all output attributes on every execution.

Returns
The name of the fragment to use
+ Examples:
void getCustomMappings ( MAttributeParameterMappingList mappings)
virtual

Maya will automatically match parameters on the shade fragment specified by this override with attributes on the associated Maya node as long as the names and types match.

In order to specify custom attribute parameter mappings, override this method.

This method will be called before Maya performs its automatic matching so it can be used to prevent that process by defining mappings for parameters that would normally be mapped automatically. Such mappings will take precedence over automatic mappings.

It is an error to provide more than one mapping per fragment parameter. Only the first such mapping will be used.

The same attribute may be used for multiple parameters.

By default, this method defines no custom mappings.

Parameters
[out]mappingsAn attribute parameter mapping list; fill with any desired custom mappings
+ Examples:
MString outputForConnection ( const MPlug sourcePlug,
const MPlug destinationPlug 
)
virtual

When Maya attempts to connect the fragment for this override to the fragment for another node in the shading network, it will call this method to get the name of the output on the fragment to use for the connection.

By default, this will simply return the name of the output attribute on the node for the override that is driving the connection. Override this method to specify that a different output of the fragment should be used instead. This method may also be overridden to get information about how and where the fragment is being connected.

If the output of the fragment is of "struct" type, this method should return the name of one of the members of the struct.

This method is called after getCustomMappings().

If the name returned does not match the name of any output parameter (or struct member in the case of struct output) on the fragment for this override then the fragment will not be connected to the overall shading effect.

Parameters
[in]sourcePlugThe plug on the node for this override which is the source of the connection. By default the name of the attribute for this plug is returned.
[in]destinationPlugThe plug on the node which is the destination of the connection.
Returns
The name of an output parameter on the fragment for the override
bool valueChangeRequiresFragmentRebuild ( const MPlug plug) const
virtual

This method will be called by Maya when it detects changes in the attribute values of nodes in the shading network.

If this method returns true, Maya will assume that the change means that a new configuration of the total fragment graph is necessary and it will trigger a rebuild of the complete shading effect. This will cause fragmentName() to be invoked again at which point a different fragment name could be returned.

For example, if a texture node has multiple modes, each implemented with a different fragment, then a change to the active mode would require the shading effect to be rebuilt in order to switch which fragment is used.

The plug parameter passed in is Maya's best attempt at informing the implementation of what changed. However due to the nature of the change management system a single source plug cannot always be determined in which case the plug may be NULL.

The default implementation returns false.

Parameters
[in]plugThe plug that changed, may be NULL
Returns
True if a change in attribute values should cause a rebuild of the complete shading effect
void updateDG ( )
virtual

This method is called every time Maya needs to update the parameter values on the final shading effect of which the fragment produced by this override is a part.

In this method implementations should query and cache any values needed for setting parameters on the final shading effect in updateShader().

The default implementation does nothing.

+ Examples:
void updateShader ( MShaderInstance shader,
const MAttributeParameterMappingList mappings 
)
virtual

This method is called every time Maya needs to update the parameter values on the final shading effect of which the fragment produced by this override is a part.

Implementations may use the information from the mappings list to set parameter values on the shader. The list contains all parameter mappings for the override, both automatic and custom. Although it is possible to set the value for any parameter on the shader it is an error to do so for parameters which are not defined by the fragment for this override and doing so may result in unpredictable behaviour.

The default implementation does nothing. Note that values for parameters with valid attribute parameter mappings will be set automatically. This method need only be overridden if custom behaviour is required.

For performance, consider caching the resolved parameter names of parameters needing update the first time this method is called. This will avoid searching the mappings list and then retrieving the resolved name from the mapping on each update. Resolved names are guaranteed to remain constant until the next time fragmentName() is called. Const pointers to individual mappings may also be cached in this way and are valid for the same duration. Do not attempt to cache mappings created in the getCustomMappings() method.

It is an error to attempt to access the Maya dependency graph from within updateShader(). Any attempt to do so will result in instability. Required data should be retrieved and cached in updateDG().

Parameters
[in]shaderThe shader instance
[in]mappingsThe attribute parameter mappings for this override
+ Examples:
const char * className ( )
static

Returns the name of this class.

Returns
Name of this class.

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