C++ API Reference
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
MPxHwShaderNode Class Reference
OpenMayaUI - API module for user interface | Proxy classes

Base class for user defined hardware shaders. More...

#include <MPxHwShaderNode.h>

+ Inheritance diagram for MPxHwShaderNode:

Classes

struct  RenderParameters
 Provides information on how to render the image. More...
 

Public Types

enum  Writeable {
  kWriteNone = 0x0000, kWriteVertexArray = 0x0001, kWriteNormalArray = 0x0002, kWriteColorArrays = 0x0004,
  kWriteTexCoordArrays = 0x0008, kWriteAll = 0x000f
}
 Bit masks used in conjuction with the 'writeable' parameter passed to the geometry() method to determine which arrays the shader is allowed to write to. More...
 
enum  DirtyMask {
  kDirtyNone = 0x0000, kDirtyVertexArray = 0x0001, kDirtyNormalArray = 0x0002, kDirtyColorArrays = 0x0004,
  kDirtyTexCoordArrays = 0x0008, kDirtyAll = 0x000f
}
 Bit masks used in combination with the return value of the dirtyMask() method to determine which portions of the geometry are dirty. More...
 
enum  TransparencyOptions { kIsTransparent = 0x0001, kNoTransparencyFrontBackCull = 0x0002, kNoTransparencyPolygonSort = 0x0004 }
 Bit masks to be returned by the shader's transparencyOptions() method. 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

 MPxHwShaderNode ()
 Class constructor.
 
virtual ~MPxHwShaderNode ()
 Class destructor.
 
virtual MPxNode::Type type () const
 This method returns the type of the node. More...
 
virtual MStatus bind (const MDrawRequest &request, M3dView &view)
 This method is invoked for hardware rendering to Maya's 3D view. More...
 
virtual MStatus unbind (const MDrawRequest &request, M3dView &view)
 This method is invoked for hardware rendering to Maya's 3D view. More...
 
virtual MStatus geometry (const MDrawRequest &request, M3dView &view, int prim, unsigned int writable, int indexCount, const unsigned int *indexArray, int vertexCount, const int *vertexIDs, const float *vertexArray, int normalCount, floatArrayPtr normalArrays, int colorCount, floatArrayPtr colorArrays, int texCoordCount, floatArrayPtr texCoordArrays)
 This method is obsolete. More...
 
virtual MStatus geometry (const MDrawRequest &request, M3dView &view, int prim, unsigned int writable, int indexCount, const unsigned int *indexArray, int vertexCount, const int *vertexIDs, const float *vertexArray, int normalCount, floatArrayPtr normalArrays, int colorCount, floatArrayPtr colorArrays, int texCoordCount, floatArrayPtr texCoordArrays, const int *faceIDs, const float *localUVCoord)
 This method is invoked for hardware rendering to Maya's 3D view. More...
 
virtual MStatus glBind (const MDagPath &shapePath)
 This method should only be overridden for hardware rendering. More...
 
virtual MStatus glUnbind (const MDagPath &shapePath)
 This method should only be overridden for hardware rendering. More...
 
virtual MStatus glGeometry (const MDagPath &shapePath, int glPrim, unsigned int writeMask, int indexCount, const unsigned int *indexArray, int vertexCount, const int *vertexIDs, const float *vertexArray, int normalCount, floatArrayPtr normalArrays, int colorCount, floatArrayPtr colorArrays, int texCoordCount, floatArrayPtr texCoordArrays)
 This method is obsolete. More...
 
virtual MStatus glGeometry (const MDagPath &shapePath, int glPrim, unsigned int writeMask, int indexCount, const unsigned int *indexArray, int vertexCount, const int *vertexIDs, const float *vertexArray, int normalCount, floatArrayPtr normalArrays, int colorCount, floatArrayPtr colorArrays, int texCoordCount, floatArrayPtr texCoordArrays, const int *faceIDs, const float *localUVCoord)
 This method should only be overridden for hardware rendering. More...
 
virtual bool supportsBatching () const
 Specifies whether or not this shader supports batched rendering of shapes. More...
 
virtual bool invertTexCoords () const
 Specifies whether this shader requires inverted texture coordinates. More...
 
const MDagPath & currentPath () const
 This method returns a reference to the current path that the shader is invoked for. More...
 
unsigned int dirtyMask () const
 This method returns a "dirty" mask that indicates which geometry items have changed from the last invocation of the plugin to draw. More...
 
virtual int normalsPerVertex ()
 Specifies how many normals per vertex the HW shader would like Maya to provide. More...
 
virtual int colorsPerVertex ()
 This method returns the number of color values per vertex that the hw shader node would like to receive from Maya. More...
 
virtual int getColorSetNames (MStringArray &names)
 NO SCRIPT SUPPORT. More...
 
virtual int texCoordsPerVertex ()
 This method returns the number of texture coordinate values per vertex that the hw shader node would like to receive from Maya. More...
 
virtual int getTexCoordSetNames (MStringArray &names)
 NO SCRIPT SUPPORT. More...
 
virtual bool hasTransparency ()
 This method returns a boolean value that indicates whether the object will be drawn transparently or not. More...
 
virtual bool provideVertexIDs ()
 This method returns a boolean value that indicates whether a map of the vertex IDs will be provided to the geometry method. More...
 
virtual bool provideFaceIDs ()
 This method returns a boolean value that indicates whether a map of the face IDs will be provided to the geometry method. More...
 
virtual bool provideLocalUVCoord ()
 This method returns a boolean value that indicates whether the local uv coordinates of the subdivided face vertices will be provided to the geometry method. 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 MStatus getAvailableImages (const MString &uvSetName, MStringArray &imageNames)
 NO SCRIPT SUPPORT. More...
 
virtual MStatus renderImage (const MString &imageName, floatRegion region, int &imageWidth, int &imageHeight)
 NO SCRIPT SUPPORT. More...
 
virtual MStatus renderImage (const MString &imageName, floatRegion region, const MPxHwShaderNode::RenderParameters &parameters, int &imageWidth, int &imageHeight)
 NO SCRIPT SUPPORT. More...
 
virtual MStatus renderImage (MHWRender::MUIDrawManager &uiDrawManager, const MString &imageName, floatRegion region, const MPxHwShaderNode::RenderParameters &parameters, int &imageWidth, int &imageHeight)
 NO SCRIPT SUPPORT. 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...
 
MObject currentShadingEngine () const
 This method returns an MObject to the shading engine that is currently being rendered. 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 MPxHwShaderNode * getHwShaderNodePtr (MObject &object)
 This is a static convenience method to be able to get an MPxHwShaderNode from an MObject provided by a swatch generator class (Class derived from MSwatchRenderRegister). 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 MObject outTransparency
 output transparency value
 
static MObject outTransparencyR
 output transparency red
 
static MObject outTransparencyG
 output transparency green
 
static MObject outTransparencyB
 output transparency blue
 
static MObject outMatteOpacity
 output matte opacity value
 
static MObject outMatteOpacityR
 output matte opacity red
 
static MObject outMatteOpacityG
 output matte opacity green
 
static MObject outMatteOpacityB
 output matte opacity blue
 
static MObject outGlowColor
 output glow color value
 
static MObject outGlowColorR
 output glow color red
 
static MObject outGlowColorG
 output glow color green
 
static MObject outGlowColorB
 output glow 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...
 

Detailed Description

Base class for user defined hardware shaders.

MPxHwShaderNode 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 MPxHwShaderNode for it to have any affect on the on-screen display at all. In addition to their affect 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 bind(), unbind(), and geometry() methods. If your hardware shader uses texture coordinates from Maya, you also need to override either texCoordsPerVertex or getTexCoordSetNames(). 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 if the glBind/glGeometry/glUnbind methods of this class are implemented.

Examples:
blindDataShader/blindDataShader.h, cgFx/cgfxShaderNode.h, and hwPhongShader/hwPhongShader.h.

Member Enumeration Documentation

enum Writeable

Bit masks used in conjuction with the 'writeable' parameter passed to the geometry() method to determine which arrays the shader is allowed to write to.

Enumerator
kWriteNone 

 

kWriteVertexArray 

 

kWriteNormalArray 

 

kWriteColorArrays 

 

kWriteTexCoordArrays 

 

kWriteAll 

 

enum DirtyMask

Bit masks used in combination with the return value of the dirtyMask() method to determine which portions of the geometry are dirty.

Enumerator
kDirtyNone 

 

kDirtyVertexArray 

 

kDirtyNormalArray 

 

kDirtyColorArrays 

 

kDirtyTexCoordArrays 

 

kDirtyAll 

 

enum TransparencyOptions

Bit masks to be returned by the shader's transparencyOptions() method.

Enumerator
kIsTransparent 

Draw as a transparent object.

If this bit is not set then the others are ignored.

kNoTransparencyFrontBackCull 

Do not use the two-pass front-and-back culling algorithm.

kNoTransparencyPolygonSort 

Do not use two-pass drawing of back-to-front sorted polygons.

Member Function Documentation

MPxNode::Type type ( ) const
virtual

This method returns the type of the node.

This method should not be overridden by the user. It will return MPxNode::kHwShaderNode.

Returns
The type of node.

Reimplemented from MPxNode.

MStatus bind ( const MDrawRequest &  request,
M3dView &  view 
)
virtual

This method is invoked for hardware rendering to Maya's 3D view.

This is the preferred method of interactive feedback and performance. the "gl" version should be used for batch hardware rendering.

This method is called to set up the OpenGL state. It would typically ensure that textures were bound and that any specific OpenGL extensions are enabled. A status code of MS::kSuccess should be returned unless there was a problem during the display, such as insufficient memory or required input data is missing or invalid.

Parameters
[in]requestthe draw request.
[in]viewthe view in which to draw.
Returns
Status code.
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure An error has occurred.
MStatus unbind ( const MDrawRequest &  request,
M3dView &  view 
)
virtual

This method is invoked for hardware rendering to Maya's 3D view.

This is the preferred method of interactive feedback and performance. the "gl" version should be used for batch hardware rendering.

This method is called to restore the OpenGL state. Specifically, it must disable any OpenGL extensions that the matching bind() method may have enabled. This is necessary to ensure that the rest of Maya's drawing code continues to work correctly. A status code of MS::kSuccess should be returned unless there was a problem such as insufficient memory or required input data is missing or invalid.

The arguments passed to this method are the same ones that were passed to the bind() method.

Parameters
[in]requestthe draw request.
[in]viewthe view in which to draw.
Returns
Status code.
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure An error has occurred.
MStatus geometry ( const MDrawRequest &  request,
M3dView &  view,
int  prim,
unsigned int  writable,
int  indexCount,
const unsigned int *  indexArray,
int  vertexCount,
const int *  vertexIDs,
const float *  vertexArray,
int  normalCount,
floatArrayPtr  normalArrays,
int  colorCount,
floatArrayPtr  colorArrays,
int  texCoordCount,
floatArrayPtr  texCoordArrays 
)
virtual

This method is obsolete.

Deprecated:
Use the version MPxHwShaderNode::geometry() with the faceIDs argument instead

This method is invoked for hardware rendering to Maya's 3D view.

This is the preferred method of interactive feedback and performance. the "gl" version should be used for batch hardware rendering.

This method does all the actual OpenGL drawing. The arguments contain all the data to successfully call glDrawElements or glDrawRangeElements. It is possible that there will be multiple calls to this method surrounded by a single call to bind() and unbind().

Note 1. The array of vertex IDs returned corresponds to each triangle's vertex. This allows access to associated blind data per vertex. The vertexIDs array allows querying of information such as color per vertex etc.

Note 2. The array of array parameters passed to this method can contain sparse information. Check array positions against NULL to ensure that the array information item is valid.

It is necessary to use the indexArray to access information contained in the data arrays.

Parameters
[in]requestthe draw request.
[in]viewthe view in which to draw.
[in]primthe type of primitive to draw. This is one of the values accepted by glBegin(). Typically it will be GL_TRIANGLES but it could be any of the others.
[in]writablethis is a mask which indicates which of the various array arguments can be modified in place. If a bit in writable is set then you can modify corresponding data array (after casting it to a non-const type). If the bit is not set in writable then you must not modify the data since it points to internal Maya storage. You can test the bits in writeable against the values defined by the enum MPxHwShaderNode::Writable.
[in]indexCountspecifies both the number of indices to draw and the size of the indexArray argument.
[in]indexArraythe array of index values. This array is in a format suitable for passing as the indices argument to glDrawElements() or glDrawRangeElements(). See the OpenGL documentation for details on calling these routines.
[in]vertexCountthe number of elements in the vertexArray, the normalArray, each of the colorArrays, and each of the texCoordArrays.
[in]vertexIDsthe component IDs of the vertices in vertexArray. This array is only provided if it was requested by overriding the provideVertexIDs() method to return true.
[in]vertexArraythe array of vertex data. Currently, this is always 3 element floating point values. This data is in a format suitable for passing to glVertexPointer(). See the OpenGL documentation for details.
[in]normalCountthe number of individual "normal" arrays that are being provided in normalArrays. See the description of normalsPerVertex method below for details.
[in]normalArraysthe normal (and tangent) data suitable. There may be 0, 1, 2, or 3 "normal" arrays. See the description of the normalsPerVertex method below for details.
[in]colorCountthe number of individual color arrays.
[in]colorArraysthe arrays of color data. The first set of color data is pointed to by colorArrays[0]. Each color array contains vertexCount color values, each of which is 4 floating point values long and represents the red, green, blue, and alph values on a 0 to 1 scale. Each individual array is suitable for passing to glColorPointer().
[in]texCoordCountthe number of texture coordinate arrays. Each array contains one set of UV texture coordinates.
[in]texCoordArraysthe arrays of texture coordinate data. The first set of texture coordinate data is pointed to by texCoordArrays[0]. Each array contains vertexCount coordinate values, each of which is 2 floating point values long. Each individual array is suitable for passing to glTexCoordPointer().
Returns
Status code.
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure An error has occurred.
MStatus geometry ( const MDrawRequest &  request,
M3dView &  view,
int  prim,
unsigned int  writable,
int  indexCount,
const unsigned int *  indexArray,
int  vertexCount,
const int *  vertexIDs,
const float *  vertexArray,
int  normalCount,
floatArrayPtr  normalArrays,
int  colorCount,
floatArrayPtr  colorArrays,
int  texCoordCount,
floatArrayPtr  texCoordArrays,
const int *  faceIDs,
const float *  localUVCoord 
)
virtual

This method is invoked for hardware rendering to Maya's 3D view.

This is the preferred method of interactive feedback and performance. the "gl" version should be used for batch hardware rendering.

This method does all the actual OpenGL drawing. The arguments contain all the data to successfully call glDrawElements or glDrawRangeElements. It is possible that there will be multiple calls to this method surrounded by a single call to bind() and unbind().

Note 1. The array of vertex IDs passed in corresponds to each triangle's vertex. This allows access to associated blind data per vertex. The vertexIDs array allows querying of information such as color per vertex etc.

The array of face IDs passed in can be used to query information at a per face level.

The array of local uv coords passed in stores the local uv of the subdivided face vertices.

Note 2. The array of array parameters passed to this method can contain sparse information. Check array positions against NULL to ensure that the array information item is valid.

It is necessary to use the indexArray to access information contained in the data arrays.

Parameters
[in]requestthe draw request.
[in]viewthe view in which to draw.
[in]primthe type of primitive to draw. This is one of the values accepted by glBegin(). Typically it will be GL_TRIANGLES but it could be any of the others.
[in]writablethis is a mask which indicates which of the various array arguments can be modified in place. If a bit in writable is set then you can modify corresponding data array (after casting it to a non-const type). If the bit is not set in writable then you must not modify the data since it points to internal Maya storage. You can test the bits in writeable against the values defined by the enum MPxHwShaderNode::Writable.
[in]indexCountspecifies both the number of indices to draw and the size of the indexArray argument.
[in]indexArraythe array of index values. This array is in a format suitable for passing as the indices argument to glDrawElements() or glDrawRangeElements(). See the OpenGL documentation for details on calling these routines.
[in]vertexCountthe number of elements in the vertexArray, the normalArray, each of the colorArrays, and each of the texCoordArrays, the vertexID, the faceID and the localUVCoord array. The array length is (vertexCount * the size of the type of data). e.g. vertexCount*3 for vertexArray, and vertexCount*1 for vertexID.
[in]vertexIDsthe component IDs of the vertices in vertexArray. This array is only provided if it was requested by overriding the provideVertexIDs() method to return true.
[in]vertexArraythe array of vertex data. Currently, this is always 3 element floating point values. This data is in a format suitable for passing to glVertexPointer(). See the OpenGL documentation for details.
[in]normalCountthe number of individual "normal" arrays that are being provided in normalArrays. See the description of normalsPerVertex method below for details.
[in]normalArraysthe normal (and tangent) data suitable. There may be 0, 1, 2, or 3 "normal" arrays. See the description of the normalsPerVertex method below for details.
[in]colorCountthe number of individual color arrays.
[in]colorArraysthe arrays of color data. The first set of color data is pointed to by colorArrays[0]. Each color array contains vertexCount color values, each of which is 4 floating point values long and represents the red, green, blue, and alpha values on a 0 to 1 scale. Each individual array is suitable for passing to glColorPointer().
[in]texCoordCountthe number of texture coordinate arrays. Each array contains one set of UV texture coordinates.
[in]texCoordArraysthe arrays of texture coordinate data. The first set of texture coordinate data is pointed to by texCoordArrays[0]. Each array contains vertexCount coordinate values, each of which is 2 floating point values long. Each individual array is suitable for passing to glTexCoordPointer().
[in]faceIDsthe component IDs of the faces in vertexArray. This array is only provided if it was requested by overriding the provideFaceIDs() method to return true.
[in]localUVCoordthe local uv of the smooth vertices in vertexArray. This array is only provided if it was requested by overriding the provideLocalUVCoord() method to return true.
Returns
Status code.
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure An error has occurred.
MStatus glBind ( const MDagPath &  shapePath)
virtual

This method should only be overridden for hardware rendering.

The implementation can assume the graphics context and model view projection matrix have already been set.

This method will be invoked once per frame and should be overridden to allocate any resources needed for the draw. For example, binding vertex programs, fragment programs, or allocating textures. A status code of MS::kSuccess should be returned unless there was a problem such as insufficient memory or required input data is missing or invalid.

Parameters
[in]shapePathPath to the surface being drawn.
Returns
Status code
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure An error has occurred.
Examples:
cgFx/cgfxShaderNode.h.
MStatus glUnbind ( const MDagPath &  shapePath)
virtual

This method should only be overridden for hardware rendering.

The implementation can assume the graphics context and model view projection matrix have already been set.

This method will be invoked once per frame and should be overridden to deallocate any resources used to draw. It's important that all resources be released when a batch hardware render has occured because the graphics context will be deleted. It may be desireable to override the other version of bind/unbind to keep track of whether the draw is for the 3D view or the batch hardware renderer. This information could then be used to better track the reuse of resources and optimize performance.

A status code of MS::kSuccess should be returned unless there was a problem.

Parameters
[in]shapePathPath to the surface being drawn.
Returns
Status code
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure An error has occurred.
Examples:
cgFx/cgfxShaderNode.h.
MStatus glGeometry ( const MDagPath &  shapePath,
int  prim,
unsigned int  writable,
int  indexCount,
const unsigned int *  indexArray,
int  vertexCount,
const int *  vertexIDs,
const float *  vertexArray,
int  normalCount,
floatArrayPtr  normalArrays,
int  colorCount,
floatArrayPtr  colorArrays,
int  texCoordCount,
floatArrayPtr  texCoordArrays 
)
virtual

This method is obsolete.

Deprecated:
Use the version MPxHwShaderNode::glGeometry() with the faceIDs argument instead

This method should only be overridden for hardware rendering.

The implementation can assume graphics context and model view projection matrix have already been set.

This method does all the actual OpenGL drawing. The arguments contain all the data to successfully call glDrawElements or glDrawRangeElements. It is possible that there will be multiple calls to this method surrounded by a single call to bind() and unbind().

Note 1. The array of vertex IDs returned corresponds to each triangle's vertex. This allows access to associated blind data per vertex. The vertexIDs array allows querying of information such as color per vertex etc.

Note 2. The array of array parameters passed to this method can contain sparse information. Check array positions against NULL to ensure that the array information item is valid.

It is necessary to use the indexArray to access information contained in the data arrays.

Parameters
[in]shapePathPath to the surface being drawn.
[in]primthe type of GL primitive is supplied as it would be used for glBegin() or glDrawElements(). Typically it will be GL_TRIANGLES or GL_TRIANGLE_STRIP for drawing polygonal or nurb surfaces respectively.
[in]writablethis is a mask which indicates which of the various array arguments can be modified in place. If a bit in writable is set then you can modify corresponding data array (after casting it to a non-const type). If the bit is not set in writable then you must not modify the data since it points to internal Maya storage. You can test the bits in writeable against the values defined by the enum MPxHwShaderNode::Writable.
[in]indexCountspecifies both the number of indices to draw and the size of the indexArray argument.
[in]indexArraythe array of index values. This array is in a format suitable for passing as the indices argument to glDrawElements() or glDrawRangeElements(). See the OpenGL documentation for details on calling these routines.
[in]vertexCountthe number of elements in the vertexArray, the normalArray, each of the colorArrays, and each of the texCoordArrays.
[in]vertexIDsthe component IDs of the vertices in vertexArray. This array is only provided if it was requested by overriding the provideVertexIDs() method to return true.
[in]vertexArraythe array of vertex data. Currently, this is always 3 element floating point values. This data is in a format suitable for passing to glVertexPointer(). See the OpenGL documentation for details.
[in]normalCountthe number of individual "normal" arrays that are being provided in normalArrays. See the description of normalsPerVertex method below for details.
[in]normalArraysthe normal (and tangent) data suitable. There may be 0, 1, 2, or 3 "normal" arrays. See the description of the normalsPerVertex method below for details.
[in]colorCountthe number of individual color arrays.
[in]colorArraysthe arrays of color data. The first set of color data is pointed to by colorArrays[0]. Each color array contains vertexCount color values, each of which is 4 floating point values long and represents the red, green, blue, and alpha values on a 0 to 1 scale. The 3D view and hardware renderer handle missing color data differently. The 3D view will create an array and pass black colors for each vertex, whereas the hardware renderer will supply a NULL pointer to indicate that color per-vertex data is unavailable.
[in]texCoordCountthe number of texture coordinate arrays. Each array contains one set of UV texture coordinates.
[in]texCoordArraysthe arrays of texture coordinate data. The first set of texture coordinate data is pointed to by texCoordArrays[0]. Each array contains vertexCount coordinate values, each of which is 2 floating point values long. Each individual array is suitable for passing to glTexCoordPointer(). The 3D view and hardware renderer handle missing texture coordinates differently. The 3D view will create an array of [0,0] texture coordinates for each vertex, whereas the hardware renderer will supply a NULL pointer to indicate that uv-set data is unavailable.
Returns
Status code
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure An error has occurred.
Examples:
cgFx/cgfxShaderNode.h.
MStatus glGeometry ( const MDagPath &  shapePath,
int  prim,
unsigned int  writable,
int  indexCount,
const unsigned int *  indexArray,
int  vertexCount,
const int *  vertexIDs,
const float *  vertexArray,
int  normalCount,
floatArrayPtr  normalArrays,
int  colorCount,
floatArrayPtr  colorArrays,
int  texCoordCount,
floatArrayPtr  texCoordArrays,
const int *  faceIDs,
const float *  localUVCoord 
)
virtual

This method should only be overridden for hardware rendering.

The implementation can assume graphics context and model view projection matrix have already been set.

This method does all the actual OpenGL drawing. The arguments contain all the data to successfully call glDrawElements or glDrawRangeElements. It is possible that there will be multiple calls to this method surrounded by a single call to bind() and unbind().

Note 1. The array of vertex IDs passed in corresponds to each triangle's vertex. This allows access to associated blind data per vertex. The vertexIDs array allows querying of information such as color per vertex etc.

The array of face IDs passed in can be used to query information at a per face level.

The array of local uv coords passed in stores the local uv of the subdivided face vertices.

Note 2. The array of array parameters passed to this method can contain sparse information. Check array positions against NULL to ensure that the array information item is valid.

It is necessary to use the indexArray to access information contained in the data arrays.

Parameters
[in]shapePathPath to the surface being drawn.
[in]primthe type of GL primitive is supplied as it would be used for glBegin() or glDrawElements(). Typically it will be GL_TRIANGLES or GL_TRIANGLE_STRIP for drawing polygonal or nurb surfaces respectively.
[in]writablethis is a mask which indicates which of the various array arguments can be modified in place. If a bit in writable is set then you can modify corresponding data array (after casting it to a non-const type). If the bit is not set in writable then you must not modify the data since it points to internal Maya storage. You can test the bits in writeable against the values defined by the enum MPxHwShaderNode::Writable.
[in]indexCountspecifies both the number of indices to draw and the size of the indexArray argument.
[in]indexArraythe array of index values. This array is in a format suitable for passing as the indices argument to glDrawElements() or glDrawRangeElements(). See the OpenGL documentation for details on calling these routines.
[in]vertexCountthe number of elements in the vertexArray, the normalArray, each of the colorArrays, each of the texCoordArrays, the vertexID, the faceID and the localUVCoord array. The array length is (vertexCount * the size of the type of data). e.g. vertexCount*3 for vertexArray, and vertexCount*1 for vertexID.
[in]vertexIDsthe component IDs of the vertices in vertexArray. This array is only provided if it was requested by overriding the provideVertexIDs() method to return true.
[in]vertexArraythe array of vertex data. Currently, this is always 3 element floating point values. This data is in a format suitable for passing to glVertexPointer(). See the OpenGL documentation for details.
[in]normalCountthe number of individual "normal" arrays that are being provided in normalArrays. See the description of normalsPerVertex method below for details.
[in]normalArraysthe normal (and tangent) data suitable. There may be 0, 1, 2, or 3 "normal" arrays. See the description of the normalsPerVertex method below for details.
[in]colorCountthe number of individual color arrays.
[in]colorArraysthe arrays of color data. The first set of color data is pointed to by colorArrays[0]. Each color array contains vertexCount color values, each of which is 4 floating point values long and represents the red, green, blue, and alpha values on a 0 to 1 scale. The 3D view and hardware renderer handle missing color data differently. The 3D view will create an array and pass black colors for each vertex, whereas the hardware renderer will supply a NULL pointer to indicate that color per-vertex data is unavailable.
[in]texCoordCountthe number of texture coordinate arrays. Each array contains one set of UV texture coordinates.
[in]texCoordArraysthe arrays of texture coordinate data. The first set of texture coordinate data is pointed to by texCoordArrays[0]. Each array contains vertexCount coordinate values, each of which is 2 floating point values long. Each individual array is suitable for passing to glTexCoordPointer(). The 3D view and hardware renderer handle missing texture coordinates differently. The 3D view will create an array of [0,0] texture coordinates for each vertex, whereas the hardware renderer will supply a NULL pointer to indicate that uv-set data is unavailable.
[in]faceIDsthe component IDs of the faces in vertexArray. This array is only provided if it was requested by overriding the provideFaceIDs() method to return true.
[in]localUVCoordthe local uv of the smooth vertices in vertexArray. This array is only provided if it was requested by overriding the provideLocalUVCoord() method to return true.
Returns
Status code
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure An error has occurred.
bool supportsBatching ( ) const
virtual

Specifies whether or not this shader supports batched rendering of shapes.

In normal rendering, a shader is invoked using bind/geometry/unbind (or glBind/glGeometry/glUnbind) once for each shape being rendered. When a shader is used in batched rendering mode however, bind is called once, a series of geometry calls are made for each shape being rendered, followed by a single call to unbind (and similarly for glBind, glGeometry and glUnbind). As shader binding/unbinding can be expensive, batched rendering can significantly improve rendering performance. The more (particularly expensive) operations that can be moved out of the geometry/glGeometry methods the greater the performance improvement is. Ideally, only shape specific operations (such as binding geometry arrays and shape matrices) should be left in the geometry methods.

It is important to note that your shader can only use batched rendering mode if there is no shape (i.e. dag path) specific code in bind, glBind, unbind, or glUnbind. If any of these methods perform shape specific processing, this code must either be moved into geometry/glGeometry, or you must return false in this method to indicate batching should be disabled for this shader.

By default, this method will return false to ensure compatibility with existing shader code.

Returns
true if this shader supports batched rendering, false otherwise
Examples:
cgFx/cgfxShaderNode.h.
bool invertTexCoords ( ) const
virtual

Specifies whether this shader requires inverted texture coordinates.

(i.e. where the top-left hand corner of UV space is (0,0) instead of the bottom-left corner).

By default, this method will return false to ensure compatibility with existing shader code.

Returns
true if inverted texture coordinates are required, false otherwise
Examples:
cgFx/cgfxShaderNode.h.
const MDagPath & currentPath ( ) const

This method returns a reference to the current path that the shader is invoked for.

The path is only valid before a call to any of the attribute specifying routines:

The path is not guaranteed to be valid at any other time.

This method allows the plugin to return attribute queries which are relative to a specific path or object.

For example, the plugin can retrieve the MObject from the path, then use the MFnMesh class on the MObject, assuming the object is a polygonal surface. Through MFnMesh the code can query the actual number of texture coordinate sets on the surface and return appropriate values for the getTexCoordSetNames() routine.

The [gl]bind(), [gl]unbind() and [gl]geometry() routines already have access to a dag path which is the same path as the one which can be retrieved via this method.

For performance reasons, it is recommended that for those methods the MDagPath passed in as an argument should be used.

Returns
An MDagPath. Note that this path can be invalid Use MDagPath::isValid() to confirm the validity of the path.
unsigned int dirtyMask ( ) const

This method returns a "dirty" mask that indicates which geometry items have changed from the last invocation of the plugin to draw.

The mask is valid at the time that geometry() or glGeometry() is called and at no other time.

Note that this mask is relative to the geometry for the current object (path) being drawn by the shader. The current path is the MDagPath argument passed in via the geometry routines.

In general the mask will mark the geometry as not being dirty.

Scenarios where the geometry will be marked dirty include:

  • Whenever a geometry attribute changes. For example positions or normals are modified.
  • Whenever the attributes being requested changes from the previous invocation of the shader. For example, if in the previous invocation the plugin asks for position only, and in the current invocation asks for position and normals, then the geometry attributes returned will have changed and thus be marked "dirty".
Returns
The dirty mask which can be bit 'AND'ed against the MPxHwShaderNode::DirtyMask enum.
int normalsPerVertex ( )
virtual

Specifies how many normals per vertex the HW shader would like Maya to provide.

This can range from 0 to 3. The first normal is the surface normal. The second "normal" is the primary tangent (generally the "u" direction). The third "normal" is the secondary tangent or the binormal (generally the "v" direction). Together, the normal, tangent and binormal form an orthogonal basis frequently named "tangent space basis".

The tangent and binormal vectors are guaranteed to be normalized and orthogonal to the surface normal. Please note that extracting the tangent and/or binormal requires expensive calculations, that will slow down refresh time substantially. In a future version, Maya may cache the resulting tangent space basis; in the meantime, only ask for more than one normal per vertex if they are absolutely required.

Also note that the tangent and binormal calculation requires a uv map. Currently, they are always computed from the first available uv map; if there is no uv mapping on the surface, Maya will only provide surface normals in the geometry call, regardless of the value returned by normalsPerVertex().

If you do not override this method, Maya will provide 1 normal per vertex.

Maya will automatically and silently clamp the result of this function to the [0,3] range.

COMPATIBILITY NOTE: Automatic tangent space basis calculation is only supported starting with Maya 4.0.1. Maya 4.0 supported a different scheme that was much more complicated and no longer supported.

Returns
The number of normal values desired. (0 = none, 1 = surface normal only, 2 = surface normal + tangent, 3 = surface normal + tangent + binormal)
Examples:
cgFx/cgfxShaderNode.h, and hwPhongShader/hwPhongShader.h.
int colorsPerVertex ( )
virtual

This method returns the number of color values per vertex that the hw shader node would like to receive from Maya.

Maya will attempt to provide all the color data that the shader would like but it will never provide more data that is actually available in the shape. The color sets returned by getColorSetNames() will override the number of color sets specified by colorsPerVertex(). If you do not override this method or getColorSetNames(), Maya will provide no colors per vertex.

Returns
The number of color values desired
Examples:
cgFx/cgfxShaderNode.h.
int getColorSetNames ( MStringArray &  names)
virtual

NO SCRIPT SUPPORT.

This method returns an array of color per vertex set names.

Maya will attempt to provide color per vertex data from these maps in the corresponding array element in the colorArrays argument to the geometry method. For example, if the names[2] is "cpv56" then colorArrays[2] will be the array of values from cpv56, or NULL if the shape being rendered does not have a color set of that name. If this method is not overridden an empty list of names will be returned, and Maya will use colorsPerVertex() to determine how many color sets to provide.

Parameters
[in]namesa string array holding the names of the color per vertex sets from which color data should be extracted.
Returns
The number of elements in the names array.
Examples:
cgFx/cgfxShaderNode.h.
int texCoordsPerVertex ( )
virtual

This method returns the number of texture coordinate values per vertex that the hw shader node would like to receive from Maya.

Maya will attempt to provide all the texture coordinate data that the shader would like but it will never provide more data than is actually available in the shape. The uv sets returned by getTexCoordSetNames() will override the number of uv sets specified by texCoordsPerVertex(). If you do not override this method or getTexCoordSetNames(), Maya will provide no texture coordinates per vertex.

Note
Currently, Maya only retains 2 dimensional texture coordinate data but this may change in a future release.
Returns
The number of texture coordinate values desired
Examples:
hwPhongShader/hwPhongShader.h.
int getTexCoordSetNames ( MStringArray &  names)
virtual

NO SCRIPT SUPPORT.

This method returns an array of texture coordinate set names.

Maya will attempt to provide texture coordinates from these maps in the corresponding array element in the texCoordArrays argument to the geometry method. For example, if the names[2] is "uvSet3" then texCoordArrays[2] will be the array of values from uvSet3. If this method is not overridden an empty list of names will be returned, and Maya will use texCoordsPerVertex() to determine how many uv sets to provide.

Parameters
[in]namesa string array holding the names of the uvSets from which texture coordinate data should be extracted.
Returns
The number of elements in the names array.
Examples:
cgFx/cgfxShaderNode.h, and hwPhongShader/hwPhongShader.h.
bool hasTransparency ( )
virtual

This method returns a boolean value that indicates whether the object will be drawn transparently or not.

Transparent objects must be drawn after all the opaque objects in the scene or they will not display correctly. Maya uses the return value to determine when it can draw this shape.

Note : The functionality in this method has been subsumed by the transparencyOptions() method. It is recommended that shader node writers use this newer method as it provides greater control over how transparency is interpreted by Maya's refresh mechanism.

For backward compatibility, if this method is specified and returns a "true" value, it will override the transparencyOptions() method.

Returns
true if the object will be transparent or false if it will not.
Examples:
cgFx/cgfxShaderNode.h, and hwPhongShader/hwPhongShader.h.
bool provideVertexIDs ( )
virtual

This method returns a boolean value that indicates whether a map of the vertex IDs will be provided to the geometry method.

Returns
true if vertex IDs should be provided to the geometry method.
Examples:
hwPhongShader/hwPhongShader.h.
bool provideFaceIDs ( )
virtual

This method returns a boolean value that indicates whether a map of the face IDs will be provided to the geometry method.

Returns
true if face IDs should be provided to the geometry method.
Examples:
hwPhongShader/hwPhongShader.h.
bool provideLocalUVCoord ( )
virtual

This method returns a boolean value that indicates whether the local uv coordinates of the subdivided face vertices will be provided to the geometry method.

Returns
true if the local uv coordinates should be provided to the geometry method.
Examples:
hwPhongShader/hwPhongShader.h.
unsigned int transparencyOptions ( )
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 :

  • kIsTransparent : Draw as a transparent object. If no transparency overrides are specified, then control of how to draw during a given pass is determined internally by Maya's refresh algorithm, and options the user can set per modelling viewport.
  • kNoTransparencyFrontBackCull : When kisTransparent is set and this flag is set, do not perform transparency drawing using the internal 2-pass front-face + back-face culling algorithm.
  • kNoTransparencyPolygonSort : When kisTransparent is set and this flag is set, do not perform transparency drawing using the internal 2-pass drawing of back-to-front sorted triangles.

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.

Returns
Integer containing the appropriate options set via masks.
Examples:
cgFx/cgfxShaderNode.h.
MStatus getAvailableImages ( const MString &  uvSetName,
MStringArray &  imageNames 
)
virtual

NO SCRIPT SUPPORT.

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.

Parameters
[in]uvSetNameName of a UV set the channel list should be filtered against.
[out]imageNamesArray in which to return the names of the images this shader defines which are valid for the uvSetName specified.
Returns
Status code
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure An error has occurred.
  • MS::kNotImplemented Use the default behaviour.
Examples:
cgFx/cgfxShaderNode.h.
MStatus renderImage ( const MString &  imageName,
floatRegion  region,
int &  imageWidth,
int &  imageHeight 
)
virtual

NO SCRIPT SUPPORT.

This method is obsolete.

Deprecated:
Use renderImage() that provides RenderParameters instead.

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:

glPushAttrib( <GL bits your shader modifies> );
glPushClientAttrib( GL_CLIENT_VERTEX_ARRAY_BIT);
... setup material here ...
glBegin( GL_QUADS);
glTexCoord2f(region[0][0], region[0][1]);
glVertex2f(region[0][0], region[0][1]);
glTexCoord2f(region[0][0], region[1][1]);
glVertex2f(region[0][0], region[1][1]);
glTexCoord2f(region[1][0], region[1][1]);
glVertex2f(region[1][0], region[1][1]);
glTexCoord2f(region[1][0], region[0][1]);
glVertex2f(region[1][0], region[0][1]);
glEnd();
glPopAttrib();
glPopClientAttrib();
Parameters
[in]imageNameName of the image to render. This corresponds to one of the image names returned by your shader's getAvailableImages() method.
[in]regionRectangular 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]imageWidthNative width (e.g. texture pixel width) of the image. This should be for the entire image, not just the portion within 'region'.
[out]imageHeightNative height (e.g. texture pixel height) of the image. This should be for the entire image, not just the portion within 'region'.
Returns
Status code
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure An error has occurred.
Examples:
cgFx/cgfxShaderNode.h.
MStatus renderImage ( const MString &  imageName,
floatRegion  region,
const MPxHwShaderNode::RenderParameters &  parameters,
int &  imageWidth,
int &  imageHeight 
)
virtual

NO SCRIPT SUPPORT.

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:

glPushAttrib( <GL bits your shader modifies> );
glPushClientAttrib( GL_CLIENT_VERTEX_ARRAY_BIT);
... setup material here ...
glBegin( GL_QUADS);
glTexCoord2f(region[0][0], region[0][1]);
glVertex2f(region[0][0], region[0][1]);
glTexCoord2f(region[0][0], region[1][1]);
glVertex2f(region[0][0], region[1][1]);
glTexCoord2f(region[1][0], region[1][1]);
glVertex2f(region[1][0], region[1][1]);
glTexCoord2f(region[1][0], region[0][1]);
glVertex2f(region[1][0], region[0][1]);
glEnd();
glPopAttrib();
glPopClientAttrib();
Parameters
[in]imageNameName of the image to render. This corresponds to one of the image names returned by your shader's getAvailableImages() method.
[in]regionRectangular 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]parametersAdditional parameters on how to render the image. The values reflect the image settings of the UV editor.
[out]imageWidthNative width (e.g. texture pixel width) of the image. This should be for the entire image, not just the portion within 'region'.
[out]imageHeightNative height (e.g. texture pixel height) of the image. This should be for the entire image, not just the portion within 'region'.
Returns
Status code
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure An error has occurred.
MStatus renderImage ( MHWRender::MUIDrawManager &  uiDrawManager,
const MString &  imageName,
floatRegion  region,
const MPxHwShaderNode::RenderParameters &  parameters,
int &  imageWidth,
int &  imageHeight 
)
virtual

NO SCRIPT SUPPORT.

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.

Parameters
[in]uiDrawManagerThe UI draw manager, it can be used to draw some simple geometry
[in]imageNameName of the image to render. This corresponds to one of the image names returned by your shader's getAvailableImages() method.
[in]regionRectangular 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]parametersAdditional parameters on how to render the image. The values reflect the image settings of the UV editor.
[out]imageWidthNative width (e.g. texture pixel width) of the image. This should be for the entire image, not just the portion within 'region'.
[out]imageHeightNative height (e.g. texture pixel height) of the image. This should be for the entire image, not just the portion within 'region'.
Returns
Status code
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure An error has occurred.
MStatus renderSwatchImage ( MImage &  image)
virtual

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:

  • Determine the size of the swatch required. This is the dimensions of the MImage passed in as an argument. The pixels for the MImage will have been pre-allocated. The format of the pixels is 32-bit R,G,B,A, with 8-bits per channel.
  • Either use an offscreen "swatch context" provided to you or use your own offscreen context. The provided context is available via the MHardwareRenderer class method makeSwatchContextCurrent(). Note that the swatch context may be smaller than the desired image size. In this case the rendering dimensions will be clamped.
  • Either use swatch geometry provided to you, or use your own swatch geometry. The provided geometry is available via the method MHardwareRenderer::referenceDefaultGeometry(). The possible "default" geometries are either a sphere, cube or plane.
  • Either use the provided "default" light and "default" camera or set up your own. Use the methods (getSwatchOrthoCameraSetting(), getSwatchLightDirection()) on MHardwareRenderer to get these defaults.
  • Read back the swatch context into the provided MImage. The convenience method MHardwareRenderer::readSwatchContextPixels() can be used. By default the format of the MImage and the swatch context are the same, so the user does not need to worry about this. The context will read into the pre-allocated MImage pixels.
  • Unreference any swatch geometry used for rendering using MHardwareRenderer::dereferenceGeometry().
Parameters
[in,out]imageImage object to which this method must write the rendered swatch. On input the image's dimensions are already set and pixel storage already allocated.
Returns
Status code
Status Codes:
  • MS::kNotImplemented : No rendering will occur.
Examples:
cgFx/cgfxShaderNode.h, and hwPhongShader/hwPhongShader.h.
MPxHwShaderNode * getHwShaderNodePtr ( MObject &  object)
static

This is a static convenience method to be able to get an MPxHwShaderNode from an MObject provided by a swatch generator class (Class derived from MSwatchRenderRegister).

Parameters
[in]objectThe object to examine.
Returns
A pointer to an MPxHwShaderNode. If the method failed for any reason then a 0 (null) will be returned.
Examples:
cgFx/cgfxShaderNode.cpp, and hwPhongShader/hwPhongShader.cpp.
MObject currentShadingEngine ( ) const

This method returns an MObject to the shading engine that is currently being rendered.

This method will only return a valid MObject during the following calls:

Returns
The shading engine currently being rendered.
const char * className ( )
static

Returns the name of this class.

Returns
The name of this class.
The documentation for this class was generated from the following files: