class MPxHardwareShader

Jump to documentation

Inheritance:

MPxHardwareShader < MPxNode

public members:

enum	TransparencyOptions kIsTransparent kNoTransparencyFrontBackCull kNoTransparencyPolygonSort
struct	ShaderContext MDagPath path MObject shadingEngine
	MPxHardwareShader ()
virtual	~MPxHardwareShader ()
virtual MPxNode::Type	type () const
MStatus	setVaryingParameters ( const MVaryingParameterList & parameters, bool remapCurrentValues = true, MDagModifier * dagModifier = NULL)
MStatus	setUniformParameters ( const MUniformParameterList & parameters, bool remapCurrentValues = true, MDagModifier * dagModifier = NULL)
virtual MStatus	populateRequirements ( const MPxHardwareShader::ShaderContext & context, MGeometryRequirements & requirements)
virtual MStatus	render ( MGeometryList & iterator)
virtual unsigned int	transparencyOptions ()
virtual MStatus	getAvailableImages ( const MPxHardwareShader::ShaderContext & context, const MString & uvSetName, MStringArray & imageNames) NO SCRIPT SUPPORT
virtual MStatus	renderImage ( const MPxHardwareShader::ShaderContext & context, const MString & imageName, floatRegion region, int& imageWidth, int& imageHeight) NO SCRIPT SUPPORT
virtual MStatus	renderSwatchImage ( MImage & image )
static MPxHardwareShader *	getHardwareShaderPtr ( MObject & object )
static MString	findResource ( const MString & name, const MString & shaderPath, MStatus * status = NULL)
static MObject	outColor output color value
static MObject	outColorR output color red
static MObject	outColorG output color green
static MObject	outColorB output color blue

Inherited from MPxNode:

public members:

enum	Type kDependNode kLocatorNode kDeformerNode kManipContainer kSurfaceShape kFieldNode kEmitterNode kSpringNode kIkSolverNode kHardwareShader Custom shader derived from MPxHardwareShader kHwShaderNode Custom shader derived from MPxHwShaderNode kTransformNode kObjectSet kFluidEmitterNode kImagePlaneNode kParticleAttributeMapperNode kConstraintNode kLast
virtual void	postConstructor ()
virtual MStatus	compute ( const MPlug & plug, MDataBlock & dataBlock )
virtual bool	getInternalValueInContext ( const MPlug & plug, MDataHandle & dataHandle, MDGContext & ctx)
virtual bool	setInternalValueInContext ( const MPlug & plug, const MDataHandle & dataHandle, MDGContext & ctx)
virtual bool	getInternalValue ( const MPlug & plug, MDataHandle & dataHandle)
virtual bool	setInternalValue ( const MPlug & plug, const MDataHandle & dataHandle)
virtual int	internalArrayCount ( const MPlug & plug, const MDGContext & ctx) const
virtual void	copyInternalData ( MPxNode * )
virtual MStatus	legalConnection ( const MPlug & plug, const MPlug & otherPlug, bool asSrc, bool& isLegal ) const
virtual MStatus	legalDisconnection ( const MPlug & plug, const MPlug & otherPlug, bool asSrc, bool& isLegal ) const
virtual MStatus	setDependentsDirty ( const MPlug & plug, MPlugArray & plugArray)
virtual MStatus	connectionMade ( const MPlug & plug, const MPlug & otherPlug, bool asSrc )
virtual MStatus	connectionBroken ( const MPlug & plug, const MPlug & otherPlug, bool asSrc )
virtual bool	isPassiveOutput ( const MPlug & plug ) const
virtual MStatus	shouldSave ( const MPlug & plug, bool& isSaving )
virtual MPlug	passThroughToOne ( const MPlug & plug ) const
virtual bool	passThroughToMany ( const MPlug & plug, MPlugArray & plugArray ) const
MTypeId	typeId () const
MString	typeName () const
MString	name () const
virtual Type	type () const
virtual bool	isAbstractClass () const
MObject	thisMObject () const
static MStatus	addAttribute ( const MObject & attr )
static MStatus	inheritAttributesFrom ( const MString & parentClassName )
static MStatus	attributeAffects ( const MObject & whenChanges, const MObject & isAffected )
MStatus	setExistWithoutInConnections ( bool flag )
bool	existWithoutInConnections ( MStatus * ReturnStatus = NULL ) const
MStatus	setExistWithoutOutConnections ( bool flag )
bool	existWithoutOutConnections ( MStatus * ReturnStatus = NULL ) const
static MObject	message
static MObject	isHistoricallyInteresting
static MObject	caching
static MObject	state

protected members:

MDataBlock	forceCache ( MDGContext & ctx= MDGContext::fsNormal )
void	setMPSafe ( bool flag )
MStatus	setDoNotWrite ( bool flag )
bool	doNotWrite ( MStatus *ReturnStatus = NULL ) const

Documentation

Description

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

Functions

MPxHardwareShader:: MPxHardwareShader ()

Constructor

Class constructor.

MPxHardwareShader:: ~MPxHardwareShader ()

Destructor

Class destructor.

MPxNode::Type MPxHardwareShader:: type () const

Description

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

Return Value

• the type of node

MStatus MPxHardwareShader:: setVaryingParameters ( const MVaryingParameterList & parameters, bool remapCurrentValues, MDagModifier * dagModifier)

Description

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.

Arguments

• parameters the list of varying parameters for this shader
• 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.
• dagModifier an optional DG modifier to use when managing the attributes used to represent the geometry parameters on this shader.

Return Value

• status code

Status Codes

• MS::kSuccess The method was successful.
• MS::kFailure An error has occurred.

MStatus MPxHardwareShader:: setUniformParameters ( const MUniformParameterList & parameters, bool remapCurrentValues, MDagModifier * dagModifier)

Description

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.

Arguments

• parameters the list of uniform parameters for this shader
• 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.
• dagModifier an optional DG modifier to use when managing the attributes used to represent the geometry parameters on this shader.

Return Value

• status code

Status Codes

• MS::kSuccess The method was successful.
• MS::kFailure An error has occurred.

MStatus MPxHardwareShader:: populateRequirements ( const MPxHardwareShader::ShaderContext & context, MGeometryRequirements & requirements)

Description

Override this method to let Maya know what surface data (e.g. positions, normals, uv sets, tangents, binormals, etc) you 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.

Arguments

• context a structure containing data relevant for the current draw request
  • path a path to the surface you should specify requirements for
  • shadingEngine an MObject pointer to the shading engine driving this draw request
• requirements the requirements structure you need to fill in

Return Value

• status code

Status Codes

• MS::kSuccess The method was successful.
• MS::kFailure An error has occurred.

MStatus MPxHardwareShader:: render ( MGeometryList & iterator)

Description

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:

		for( ; !iter.isDone(); iter.next())
		{
			MGeometry& geometry = iter.geometry( MGeometryList::kMatrices | MGeometryList::kCulling);
			glVertexPointer( 3, GL_FLOAT, 0, geometry.position().data());
			glNormalPointer( GL_FLOAT, 0, geometry.normal().data());
			MGeometryPrimitive primitives = geometry.primitiveArray( 0);
			glDrawElements( GL_TRIANGLES, primitives.elementCount(), GL_UNSIGNED_INT, primitives.data());
		}

   

Arguments

• iterator an iterator containing the geometry items you need to render.

Return Value

• status code

Status Codes

• MS::kSuccess The method was successful.
• MS::kFailure An error has occurred.

unsigned int MPxHardwareShader:: transparencyOptions ()

Description

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.

Return Value

• integer containing the appropriate options set via masks.

MStatus MPxHardwareShader:: getAvailableImages ( const MPxHardwareShader::ShaderContext & context, const MString & uvSetName, MStringArray & imageNames)

Description

This method allows your shader to define the list of images which are available in the UV texture 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.

Arguments

• context a structure containing data relevant for the current draw request
  • path a path to the surface you should specify requirements for
  • shadingEngine an MObject pointer to the shading engine driving this draw request

• uvSetName a string specifying the name of a UV set the channel list should be filtered against.

• imageNames a string array holding the names of the images this shader defines which are valid for the uvSetName specified.

Return Value

• status code

Status Codes

• MS::kSuccess The method was successful.
• MS::kFailure An error has occurred.
• MS::kNotImplemented Use the default behaviour.

MStatus MPxHardwareShader:: renderImage ( const MPxHardwareShader::ShaderContext & context, const MString & imageName, floatRegion region, int& imageWidth, int& imageHeight)

Description

This method allows you to to render the background image used for this shader in the UV texture editor. The image requested will be one of the image names returned by your shader's getAvailableImages method.

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

   

Arguments

• context a structure containing data relevant for the current draw request
  • path a path to the surface you should specify requirements for
  • shadingEngine an MObject pointer to the shading engine driving this draw request
• imageName the name of the image to render. This corresponds to one of the image names returned by your shader's getAvailableImages method.
• region the rectangular region that should be rendered. The values of this parameter should be used to populate the vertex and texture coordinates of the rectangle being rendered.
• imageWidth if applicable, this argument should be set to the image's native width (e.g. texture pixel width).
• imageHeight if applicable, this argument should be set to the image's native height (e.g. texture pixel height).

Return Value

• status code

Status Codes

• MS::kSuccess The method was successful.
• MS::kFailure An error has occurred.

MStatus MPxHardwareShader:: renderSwatchImage ( MImage & image )

Description

If the shader specifies to override swatch rendering, then this method must be overridden in order to draw anything into a swatch. 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().

Arguments

• image The image which contain the pixels of the rendered swatch.

Return Value

• status code

Status Codes

• MS::kNotImplemented : No rendering will occur.

MPxHardwareShader * MPxHardwareShader:: getHardwareShaderPtr ( MObject & object )

Description

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

Arguments

• MObject The object to examine.

Return Value

• A pointer to an MPxHardwareShader. If the method failed for any reason then a 0 (null) will be returned.

MString MPxHardwareShader:: findResource ( const MString & name, const MString & shaderPath, MStatus * status)

Description

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.

Arguments

• name The name of the resource to look for (e.g. "normals.dds")
• shaderPath The full path to the current shader (e.g. "C:/shaders/myshader.fx")
• 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.

Return Value

• The full path of the resource (e.g. "C:/shaders/textures/normals.dds")

const MRenderProfile & MPxHardwareShader:: profile ()

Description

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.

Return Value

• A reference to the render profile for this Shader. Your shader class should create this once (usually for the whole class) and return the same object each time this method is called.

This class has no child classes.