C++ API Reference
|
Base class for user defined hardware shaders. More...
#include <MPxHardwareShader.h>
Classes | |
struct | RenderParameters |
Provides information on how to render the image. More... | |
struct | ShaderContext |
Provides contextual information about the current invocation of the shader. More... | |
Public Types | |
enum | TransparencyOptions { kIsTransparent = 0x0001, kNoTransparencyFrontBackCull = 0x0002, kNoTransparencyPolygonSort = 0x0004 } |
Transparency option bitmasks. More... | |
Public Types inherited from MPxNode | |
enum | Type { kDependNode, kLocatorNode, kDeformerNode, kManipContainer, kSurfaceShape, kFieldNode, kEmitterNode, kSpringNode, kIkSolverNode, kHardwareShader, kHwShaderNode, kTransformNode, kObjectSet, kFluidEmitterNode, kImagePlaneNode, kParticleAttributeMapperNode, kCameraSetNode, kConstraintNode, kManipulatorNode, kMotionPathNode, kClientDeviceNode, kThreadedDeviceNode, kAssembly, kSkinCluster, kGeometryFilter, kBlendShape, kLast } |
Defines the type of node. More... | |
enum | SchedulingType { kParallel, kSerial, kGloballySerial, kUntrusted , kDefaultScheduling = kSerial, kSerialize = kSerial, kGloballySerialize = kGloballySerial } |
Defines the degree of parallelism of a node. More... | |
Public Member Functions | |
MPxHardwareShader () | |
Class constructor. | |
virtual | ~MPxHardwareShader () |
Class destructor. | |
virtual MPxNode::Type | type () const |
This method returns the type of the node. More... | |
MStatus | setVaryingParameters (const MVaryingParameterList ¶meters, bool remapCurrentValues=true, MDagModifier *dagModifier=NULL) |
Call this method to set the list of varying parameters this shader uses. More... | |
MStatus | setUniformParameters (const MUniformParameterList ¶meters, bool remapCurrentValues=true, MDagModifier *dagModifier=NULL) |
Call this method to set the list of uniform parameters this shader uses. More... | |
virtual MStatus | render (MGeometryList &iterator) |
Override this method to render geometry using your hardware shader. More... | |
virtual unsigned int | transparencyOptions () |
This method returns transparency options for usage as hints for Maya's internal draw during a given rendering pass. More... | |
virtual const MRenderProfile & | profile () |
Override this method to specify the renderers your shader supports. More... | |
virtual MStatus | populateRequirements (const MPxHardwareShader::ShaderContext &context, MGeometryRequirementsLegacy &requirements) |
This method is not available in Python. More... | |
virtual MStatus | getAvailableImages (const MPxHardwareShader::ShaderContext &context, const MString &uvSetName, MStringArray &imageNames) |
This method is not available in Python. More... | |
virtual MStatus | renderImage (const MPxHardwareShader::ShaderContext &context, const MString &imageName, floatRegion region, int &imageWidth, int &imageHeight) |
This method is not available in Python. More... | |
virtual MStatus | renderImage (const MPxHardwareShader::ShaderContext &context, const MString &imageName, floatRegion region, const MPxHardwareShader::RenderParameters ¶meters, int &imageWidth, int &imageHeight) |
This method is not available in Python. More... | |
virtual MStatus | renderImage (const MPxHardwareShader::ShaderContext &context, MHWRender::MUIDrawManager &uiDrawManager, const MString &imageName, floatRegion region, const MPxHardwareShader::RenderParameters ¶meters, int &imageWidth, int &imageHeight) |
This method is not available in Python. More... | |
virtual MStatus | renderSwatchImage (MImage &image) |
If the shader specifies to override swatch rendering, then this method must be overridden in order to draw anything into a swatch. More... | |
Public Member Functions inherited from MPxNode | |
MPxNode () | |
Constructor. More... | |
virtual | ~MPxNode () |
Destructor. | |
virtual void | postConstructor () |
Post constructor. More... | |
virtual MStatus | compute (const MPlug &, MDataBlock &) |
This method should be overridden in user defined nodes. More... | |
virtual bool | getInternalValue (const MPlug &, MDataHandle &) |
This method is overridden by nodes that store attribute data in some internal format. More... | |
virtual bool | setInternalValue (const MPlug &, const MDataHandle &) |
This method is overridden by nodes that store attribute data in some internal format. More... | |
virtual int | internalArrayCount (const MPlug &) const |
This method is overridden by nodes that have internal array attributes which are not stored in Maya's datablock. More... | |
virtual void | copyInternalData (MPxNode *) |
This method is overridden by nodes that store attribute data in some internal format. More... | |
virtual MStatus | legalConnection (const MPlug &, const MPlug &, bool asSrc, bool &isLegal) const |
This method allows you to check for legal connections being made to attributes of this node. More... | |
virtual MStatus | legalDisconnection (const MPlug &, const MPlug &, bool asSrc, bool &isLegal) const |
This method allows you to check for legal disconnections being made to attributes of this node. More... | |
virtual MStatus | setDependentsDirty (const MPlug &plug, MPlugArray &plugArray) |
This method can be overridden in user defined nodes to specify which plugs should be set dirty based upon an input plug {plugBeingDirtied} which Maya is marking dirty. More... | |
virtual MStatus | preEvaluation (const MDGContext &context, const MEvaluationNode &evaluationNode) |
Prepare a node's internal state for threaded evaluation. More... | |
virtual MStatus | postEvaluation (const MDGContext &context, const MEvaluationNode &evaluationNode, PostEvaluationType evalType) |
Clean up node's internal state after threaded evaluation. More... | |
virtual SchedulingType | schedulingType () const |
When overridden this method controls the degree of parallelism supported by the node during threaded evaluation. More... | |
virtual void | getCacheSetup (const MEvaluationNode &, MNodeCacheDisablingInfo &, MNodeCacheSetupInfo &, MObjectArray &) const |
Provide node-specific setup info for the Cached Playback system. More... | |
virtual void | configCache (const MEvaluationNode &, MCacheSchema &) const |
Defines the node's behavior when participating in Cached Playback. More... | |
virtual MTimeRange | transformInvalidationRange (const MPlug &source, const MTimeRange &input) const |
Override this method to register this node as an Invalidation-Range-Transformation kernel (IRT kernel) An IRT kernel node will change the invalidation time range for its downstream nodes For example, Dynamics-solver will transform invalidation time range [a,b] to [a,+inf) And Clip-Time-Editor will send out the invalidation range for each of the clip [a,b] to ( [t0+a,t0+b] U [t1+a,t1+b] U [t2+a,t2+b] U ... More... | |
bool | hasInvalidationRangeTransformation () const |
Checks if this MPxNode derived node overrides the MPxNode::transformInvalidationRange method. | |
virtual MStatus | connectionMade (const MPlug &, const MPlug &, bool asSrc) |
This method gets called when connections are made to attributes of this node. More... | |
virtual MStatus | connectionBroken (const MPlug &, const MPlug &, bool asSrc) |
This method gets called when connections are broken with attributes of this node. More... | |
virtual MStatus | dependsOn (const MPlug &, const MPlug &, bool &depends) const |
This method may be overridden by the user defined node. More... | |
virtual bool | isPassiveOutput (const MPlug &) const |
This method may be overridden by the user defined node if it wants to provide output attributes which do not prevent value modifications to the destination attribute. More... | |
virtual MStatus | shouldSave (const MPlug &, bool &isSaving) |
This method may be overridden by the user defined node. More... | |
virtual MPlug | passThroughToOne (const MPlug &) const |
This method may be overridden by nodes that have a one-to-one relationship between an input attribute and a corresponding output attribute. More... | |
virtual bool | passThroughToMany (const MPlug &, MPlugArray &) const |
This method is overridden by nodes that want to control the traversal behavior of some Maya search algorithms which traverse the history/future of shape nodes looking for directly related nodes. More... | |
virtual bool | isAbstractClass () const |
Override this class to return true if this node is an abstract node. More... | |
virtual bool | isTrackingTopology () const |
Override this class to return true if this node wants to track topology. More... | |
virtual MStringArray | getFilesToArchive (bool shortName=false, bool unresolvedName=false, bool markCouldBeImageSequence=false) const |
Use this method to return all external files used by this node. More... | |
virtual void | getExternalContent (MExternalContentInfoTable &table) const |
Returns the external content (files) that this node depends on. More... | |
bool | addExternalContentForFileAttr (MExternalContentInfoTable &, const MObject &attr) const |
Adds content info to the specified table from a file path attribute. More... | |
bool | setExternalContentForFileAttr (const MObject &attr, const MExternalContentLocationTable &) |
Sets content info in the specified attribute from the table. More... | |
virtual void | setExternalContent (const MExternalContentLocationTable &) |
Changes the location of external content in batch. More... | |
virtual MTypeId | typeId () const |
Returns the TYPEID of this node. More... | |
virtual MString | typeName () const |
Returns the type name of this node. More... | |
virtual MString | name () const |
Returns the name of this particular instance of this class. More... | |
virtual MObject | thisMObject () const |
Returns the MObject associated with this user defined node. More... | |
virtual MStatus | setExistWithoutInConnections (bool flag) |
This method specifies whether or not the node can exist without input connections. More... | |
virtual bool | existWithoutInConnections (MStatus *ReturnStatus=NULL) const |
Determines whether or not this node can exist without input connections. More... | |
virtual MStatus | setExistWithoutOutConnections (bool flag) |
This method specifies whether or not the node can exist without output connections. More... | |
virtual bool | existWithoutOutConnections (MStatus *ReturnStatus=NULL) const |
Determines whether or not this node can exist without output connections. More... | |
void | _setMPSafe (bool isMPSafe) |
This method is obsolete. More... | |
MDataBlock | _forceCache (const MDGContext &) |
This method is obsolete. More... | |
virtual bool | getInternalValueInContext (const MPlug &, MDataHandle &, MDGContext &) |
This method is obsolete. More... | |
virtual bool | setInternalValueInContext (const MPlug &, const MDataHandle &, MDGContext &) |
This method is obsolete. More... | |
virtual int | internalArrayCount (const MPlug &, const MDGContext &) const |
This method is obsolete. More... | |
Static Public Member Functions | |
static MPxHardwareShader * | getHardwareShaderPtr (MObject &object) |
This is a static convenience method to be able to get an MPxHardwareShader from an MObject provided by a swatch generator class (Class derived from MSwatchRenderRegister). More... | |
static MString | findResource (const MString &name, const MString &shaderPath, MStatus *status=NULL) |
This is a static utility to find the full path to a shader resource (typically a texture). More... | |
static const char * | className () |
Returns the name of this class. More... | |
Static Public Member Functions inherited from MPxNode | |
static MStatus | addAttribute (const MObject &attr) |
This method adds a new attribute to a user defined node type during the type's initialization. More... | |
static MStatus | inheritAttributesFrom (const MString &parentClassName) |
This method allows a class of plugin node to inherit all of the attributes of a second class of plugin node. More... | |
static MStatus | attributeAffects (const MObject &whenChanges, const MObject &isAffected) |
This method specifies that a particular input attribute affects a specific output attribute. More... | |
static MStatus | attributeAffects (const MObject &whenChanges, const MObject &isAffected, bool affectsTopology) |
This method is an extension to the other version of the attributeAffects method. More... | |
static const char * | className () |
Returns the name of this class. More... | |
Static Public Attributes | |
static MObject | outColor |
output color value | |
static MObject | outColorR |
output color red | |
static MObject | outColorG |
output color green | |
static MObject | outColorB |
output color blue | |
Static Public Attributes inherited from MPxNode | |
static MObject | message |
message attribute | |
static MObject | isHistoricallyInteresting |
is historically interesting attribute | |
static MObject | caching |
caching attribute | |
static MObject | state |
state attribute | |
static MObject | frozen |
frozen attribute | |
Additional Inherited Members | |
Protected Member Functions inherited from MPxNode | |
virtual MDataBlock | forceCache () |
USE _forceCache() IN SCRIPT. More... | |
virtual MStatus | setDoNotWrite (bool flag) |
USE _setDoNotWrite() IN SCRIPT. More... | |
virtual bool | doNotWrite (MStatus *ReturnStatus=NULL) const |
USE _doNotWrite() IN SCRIPT. More... | |
virtual void | setMPSafe (bool isMPSafe) |
This method is obsolete. More... | |
virtual MDataBlock | forceCache (const MDGContext &) |
This method is obsolete. More... | |
Base class for user defined hardware shaders.
MPxHardwareShader allows the creation of user-defined hardware shaders. A hardware shader allows the plug-in writer to control the on-screen display of an object in Maya.
You must derive a hardware shader node from MPxHardwareShader for it to have any effect on the on-screen display at all. In addition to their effect on the on-screen display of objects, hardware shaders function as surface shader nodes. This allows you to connect any shading network up to the hardware shader's outColor attribute to handle the shading during a software render.
To create a working hardware shader, derive from this class and override the render() and optionally the populateRequirements() methods. The other methods of the parent class MPxNode may also be overridden to perform dependency node capabilities.
NOTE: Plug-in hardware shaders are fully supported for polygonal mesh shapes. NURBS surfaces are only supported in the High Quality Interactive viewport and Hardware Renderer.
enum TransparencyOptions |
|
virtual |
This method returns the type of the node.
This method should not be overridden by the user. It will return MPxNode::kHardwareShader.
Reimplemented from MPxNode.
MStatus setVaryingParameters | ( | const MVaryingParameterList & | parameters, |
bool | remapCurrentValues = true , |
||
MDagModifier * | dagModifier = NULL |
||
) |
Call this method to set the list of varying parameters this shader uses.
Once set, you can use these parameters directly to access geometry data for surfaces being shaded. When using this method to manage shader varying parameters, there is no need to override populateRequirements or handle the node interface as Maya will handle parameter setup, presentation and configuration for you.
It is important to call this method whenever the shader parameters are modified (including at load time).
This is an optional method - shader implementations are still free to manage geometry parameters independently if they wish.
[in] | parameters | the list of varying parameters for this shader |
[in] | remapCurrentValues | if true (the default), Maya will attempt to initialise the value of new parameters based on any equivalently named parameters that currently exist on the node. Otherwise, the parameters will be setup using default values. Unless you wish to forcibly reset parameter values, the default value of true should be used. |
[in] | dagModifier | an optional DG modifier to use when managing the attributes used to represent the geometry parameters on this shader. |
MStatus setUniformParameters | ( | const MUniformParameterList & | parameters, |
bool | remapCurrentValues = true , |
||
MDagModifier * | dagModifier = NULL |
||
) |
Call this method to set the list of uniform parameters this shader uses.
Once set, you can use these parameters to access the cached values of shader parameters, including testing when the value has been updated (to minimise the shader state changes). When using this method to manage uniform parameters, Maya will handle the underlyintg attributes, serialization and user interface for you.
It is important to call this method whenever the shader parameters are modified (including at load time).
This is an optional method - shader implementations are still free to manage uniform (i.e. shader-level) parameters independently if they wish.
[in] | parameters | the list of uniform parameters for this shader |
[in] | remapCurrentValues | if true (the default), Maya will attempt to initialise the value of new parameters based on any equivalently named parameters that currently exist on the node. Otherwise, the parameters will be setup using default values. Unless you wish to forcibly reset parameter values, the default value of true should be used. |
[in] | dagModifier | an optional DG modifier to use when managing the attributes used to represent the geometry parameters on this shader. |
|
virtual |
Override this method to render geometry using your hardware shader.
It is important to note that you can only access surface data (e.g. uv sets) that you specified in populateRequirements. Any data you did not ask for is unlikely to be available in the geometry cache passed to you.
For example:
[in] | iterator | an iterator containing the geometry items you need to render. |
|
virtual |
This method returns transparency options for usage as hints for Maya's internal draw during a given rendering pass.
Parameters are returned via an integer containing masked out bits. By default the mask is set to 0, meaning that the drawing should be treated as regular opaque object drawing. This will generally mean one call per draw pass.
Options to control transparency are specified by returning one or more masks specified by the TransparencyOptions enumeration :
Note : Setting the "hasTransparency()" method to true will override this method. This is for backward compatibility with behaviour on existing hardware shader nodes. It is recommended that shaders use the "transparencyOptions()" override, and not longer use the older "hasTransparency()" override from their shader classes.
|
virtual |
Override this method to specify the renderers your shader supports.
If this method is not overridden, Maya will assume your shader supports only Maya's iternal OpenGL based renderer.
Note that this method is called inside the rendering loop and as such, you should make this method as fast as possible - typically just returning a static/precalculated value.
|
virtual |
This method is not available in Python.
Override this method to let Maya know what surface data (e.g.
positions, normals, uv sets, tangents, binormals, etc) your shader needs in order to render the specified geometry. This is the only data your shader will be able to access when rendering the geometry. For example, if your shader needs uv set "foo" to render a texture, you must include that here before trying to use it in your render method.
The default implementation (in MPxHardwareShader) sets up the requirements for any public MVaryingParameters you have configured on this shader. If you override this method and use MVaryingParameters, you should make a call into the base class method as part of your implementation of the method.
[in] | context | Context of the draw request (e.g. the surface being shaded, shading engine making the request). |
[out] | requirements | The requirements structure you need to fill in. |
|
virtual |
This method is not available in Python.
Maya will call this method to get your shader's list of images which are available for use in the UV editor for the UV set specified.
Typically, this list will include one entry for each texture using the specified UV set, however, your shader is free to return as many images as you wish (for example, blending between two textures, texture alpha masks, artificially shaded views of bump/normal maps, etc). Your shader's renderImage() method will be used to render the images themselves.
[in] | context | Context of the draw request (e.g. the surface being shaded, shading engine making the request). |
[in] | uvSetName | Name of a UV set the channel list should be filtered against. |
[out] | imageNames | Array in which to return the names of the images this shader defines which are valid for the uvSetName specified. |
|
virtual |
This method is not available in Python.
This method is obsolete.
This method is obsolete. [From Maya 2019]
This method allows you to to render the background image used for this shader in the UV editor. The image requested will be one of the image names returned by your shader's getAvailableImages() method.
The implementation must return the dimensions of the image in the 'imageWidth' and 'imageHeight' parameters so that Maya can perform pixel snapping and other resolution-dependent operations.
The implementation can assume OpenGL context, model view projection matrix, and texture transformations have already been set. A default color of white will be set, however you are free to change this. The magnification filter will be set to either point or bilinear based on user configuration and should not be modified. The values of GL_TEXTURE_WRAP_S and GL_TEXTURE_WRAP_T are undefined on entry, and your implementation is responsible for setting them to appropriate values (e.g. GL_REPEAT).
The arguments contain the name of the image to render, and the vertex and texture coordinate values to use at each corner of the rectangular image being rendered. Your implementation is responsible for restoring the original the value of any OpenGL state that is modified.
For example:
[in] | context | Context of the draw request (e.g. the surface being shaded, shading engine making the request). |
[in] | imageName | Name of the image to render. This corresponds to one of the image names returned by your shader's getAvailableImages() method. |
[in] | region | Rectangular region to be rendered. The values of this parameter should be used to populate the vertex and texture coordinates of the rectangle being rendered. |
[out] | imageWidth | Native width (e.g. texture pixel width) of the image. This should be for the entire image, not just the portion within 'region'. |
[out] | imageHeight | Native height (e.g. texture pixel height) of the image. This should be for the entire image, not just the portion within 'region'. |
|
virtual |
This method is not available in Python.
This method allows you to to render the background image used for this shader in the UV editor.
The image requested will be one of the image names returned by your shader's getAvailableImages() method.
The implementation must return the dimensions of the image in the 'imageWidth' and 'imageHeight' parameters so that Maya can perform pixel snapping and other resolution-dependent operations.
The implementation can assume OpenGL context, model view projection matrix, and texture transformations have already been set. A default color of white will be set, however you are free to change this. The magnification filter will be set to either point or bilinear based on user configuration and should not be modified. The values of GL_TEXTURE_WRAP_S and GL_TEXTURE_WRAP_T are undefined on entry, and your implementation is responsible for setting them to appropriate values (e.g. GL_REPEAT).
The arguments contain the name of the image to render, and the vertex and texture coordinate values to use at each corner of the rectangular image being rendered. Your implementation is responsible for restoring the original the value of any OpenGL state that is modified.
For example:
[in] | context | Context of the draw request (e.g. the surface being shaded, shading engine making the request). |
[in] | imageName | Name of the image to render. This corresponds to one of the image names returned by your shader's getAvailableImages() method. |
[in] | region | Rectangular region to be rendered. The values of this parameter should be used to populate the vertex and texture coordinates of the rectangle being rendered. |
[in] | parameters | Additional parameters on how to render the image. The values reflect the image settings of the UV editor. |
[out] | imageWidth | Native width (e.g. texture pixel width) of the image. This should be for the entire image, not just the portion within 'region'. |
[out] | imageHeight | Native height (e.g. texture pixel height) of the image. This should be for the entire image, not just the portion within 'region'. |
|
virtual |
This method is not available in Python.
This method allows you to to render the background image used for this shader in the UV editor in viewport 2.0.
The image requested will be one of the image names returned by your shader's getAvailableImages() method.
The implementation must return the dimensions of the image in the 'imageWidth' and 'imageHeight' parameters so that Maya can perform pixel snapping and other resolution-dependent operations.
[in] | context | Context of the draw request (e.g. the surface being shaded, shading engine making the request). |
[in] | uiDrawManager | The UI draw manager, it can be used to draw some simple geometry |
[in] | imageName | Name of the image to render. This corresponds to one of the image names returned by your shader's getAvailableImages() method. |
[in] | region | Rectangular region to be rendered. The values of this parameter should be used to populate the vertex and texture coordinates of the rectangle being rendered. |
[in] | parameters | Additional parameters on how to render the image. The values reflect the image settings of the UV editor. |
[out] | imageWidth | Native width (e.g. texture pixel width) of the image. This should be for the entire image, not just the portion within 'region'. |
[out] | imageHeight | Native height (e.g. texture pixel height) of the image. This should be for the entire image, not just the portion within 'region'. |
If the shader specifies to override swatch rendering, then this method must be overridden in order to draw anything into a swatch.
The shader will only draw a swatch if it has been registered to do so, by providing a valid classification during MFnPlugin::registerNode(). The shader should provide a classification that defines a swatch rendering node such as : "shader/surface/utility/:drawdb/shader/surface/myCustomShader:swatch/myCustomShaderSwatchGenerator" and have "myCustomShaderSwatchGenerator" registered has a swatch renderer : MSwatchRenderRegister::registerSwatchRender("myCustomShaderSwatchGenerator", MHWShaderSwatchGenerator::createObj );
The default implementation is to draw nothing. The basic logic to draw a swatch is as follows:
[in,out] | image | Image object to which this method must write the rendered swatch. On input the image's dimensions are already set and pixel storage already allocated. |
|
static |
This is a static convenience method to be able to get an MPxHardwareShader from an MObject provided by a swatch generator class (Class derived from MSwatchRenderRegister).
[in] | object | The object to examine. |
|
static |
This is a static utility to find the full path to a shader resource (typically a texture).
This method will search the list of paths in the MAYA_HW_SHADER_RESOURCE_PATH environment variable, resolving relative paths based on the directory containing the shader.
[in] | name | The name of the resource to look for (e.g. "normals.dds") |
[in] | shaderPath | The full path to the current shader (e.g. "C:/shaders/myshader.fx") |
[in] | status | If a pointer to a status is provided, the status will be set to MS::kSuccess if the resource was found, and MS::kFailure otherwise. |
|
static |
Returns the name of this class.