An instance of a shader that may be used with Viewport 2.0. More...

#include <MShaderManager.h>

Public Types
enum	ParameterType { kInvalid, kBoolean, kInteger, kFloat, kFloat2, kFloat3, kFloat4, kFloat4x4Row, kFloat4x4Col, kTexture1, kTexture2, kTexture3, kTextureCube, kSampler }
	Specifies parameter types. More...

enum	FragmentUsage { kPixelShader, kNormalShader, kNormalShader2, kVertexShader, kGeometryShader, kGlossShader, kGlossShader2, kRotationAngleShader, kRotationAngleShader2, kReflectanceShader, kReflectanceShader2, kRoughnessShader, kRoughnessShader2, kAnisotropyShader, kAnisotropyShader2, kDisplacementPosShader }
	Specifies where a fragment will be connected and used. More...

typedef void(*	DrawCallback) (MDrawContext &context, const MRenderItemList &renderItemList, MShaderInstance *shaderInstance)
	Definition for pre/post draw callback functions.

Public Member Functions
DrawCallback	preDrawCallback () const
	Access the pre-draw callback function pointer set for the this shader instance. More...

DrawCallback	postDrawCallback () const
	Access the post-draw callback function pointer set for the this shader instance. More...

void	parameterList (MStringArray &list) const
	Get the names of all parameters that are settable on this shader instance. More...

ParameterType	parameterType (const MString &parameterName) const
	Get the type of the named parameter, returns kInvalid if parameter is not found. More...

bool	isArrayParameter (const MString &parameterName) const
	Determine whether the named parameter is an array. More...

int	getArraySize (const MString &parameterName) const
	Get the size of the array. More...

MString	semantic (const MString &parameterName) const
	Return the semantic for a named parameter. More...

bool	isVaryingParameter (const MString &parameterName) const
	Determine whether the named parameter is varying or is uniform. More...

MStatus	setParameter (const MString &parameterName, bool value)
	Set a named, boolean parameter on the shader instance. More...

MStatus	setParameter (const MString &parameterName, int value)
	Set a named, integer parameter on the shader instance. More...

MStatus	setParameter (const MString &parameterName, float value)
	Set a named, float parameter on the shader instance. More...

MStatus	setParameter (const MString &parameterName, const float *value)
	Set a named, float, float2, float3 or float4 parameter on the shader instance. More...

MStatus	setParameter (const MString &parameterName, const MFloatVector &value)
	Set a named, float, float2, float3 parameter on the shader instance. More...

MStatus	setParameter (const MString &parameterName, const MMatrix &value)
	Set a named, matrix parameter on the shader instance. More...

MStatus	setParameter (const MString &parameterName, const MFloatMatrix &value)
	Set a named, matrix parameter on the shader instance. More...

MStatus	setParameter (const MString &parameterName, MTextureAssignment &textureAssignment)
	Set a texture parameter on the shader instance. More...

MStatus	setParameter (const MString &parameterName, MRenderTargetAssignment &targetAssignment)
	Set a named, texture parameter on the shader instance to a render target. More...

MStatus	setParameter (const MString &parameterName, const MSamplerState &sampler)
	Set a sampler parameter on the shader instance. More...

MStatus	setArrayParameter (const MString &parameterName, const bool *values, unsigned int count)
	Set a named, bool array parameter on the shader instance. More...

MStatus	setArrayParameter (const MString &parameterName, const int *values, unsigned int count)
	Set a named, integer array parameter on the shader instance. More...

MStatus	setArrayParameter (const MString &parameterName, const float *values, unsigned int count)
	Set a named, float array parameter on the shader instance. More...

MStatus	setArrayParameter (const MString &parameterName, const MMatrix *values, unsigned int count)
	Set a named, matrix array parameter on the shader instance. More...

MStatus	addInputFragment (const MString &fragmentName, const MString &outputName, const MString &inputName, const MString promotedInputName=MString())
	Connect a fragment that has been registered with the fragment manager to an input on the existing MShaderInstance. More...

MStatus	addInputFragmentForMultiParams (const MString &fragmentName, const MString &uniqueName, const MStringArray &outputNames, const MStringArray &inputNames, MUintArray *invalidParameterIndices=nullptr, FragmentUsage fragmentUsage=kPixelShader)
	Connect a named fragment that has been registered with the MFragmentManager to this MShaderInstance. More...

MStatus	addOutputFragment (const MString &fragmentName, const MString &inputName)
	Connect a fragment that has been registered with the fragment manager to an output on the existing MShaderInstance. More...

MStatus	renameParameter (const MString &oldName, const MString &newName)
	Rename the parameter. More...

MStatus	setSemantic (const MString &paramName, const MString &semantic)
	Set the semantic for a fragment based parameter. More...

MStatus	setAsVarying (const MString &paramName, bool)
	Set the parameter to be a varying parameter or not for a fragment based parameter. More...

MStatus	bind (const MDrawContext &context) const
	Binds the shader instance to the draw context, so that it is the active shader. More...

unsigned int	getPassCount (const MDrawContext &context, MStatus *status=NULL) const
	Returns the number of draw passes defined by the shader. More...

MStatus	activatePass (const MDrawContext &context, unsigned int pass) const
	Activates the given pass of the shader. More...

MStatus	unbind (const MDrawContext &context) const
	Unbinds the shader instance from the draw context. More...

MStatus	updateParameters (const MDrawContext &context) const
	Updates the bound shader instance with the current parameter data. More...

bool	isTransparent () const
	Return whether the shader will render with transparency. More...

MStatus	setIsTransparent (bool value)
	Set whether the shader will render with transparency. More...

MShaderInstance *	clone () const
	Clone the shader. More...

MShaderInstance *	createShaderInstanceWithColorManagementFragment (const MString &inputColorSpace)
	Return a new shader instance with Color Management fragment added, which is based on the callee. More...

MStatus	requiredVertexBuffers (MVertexBufferDescriptorList &list) const
	Get the vertex buffer descriptors that describe the buffers required by a given shader instance. More...

int	annotationAsInt (const MString &parameterName, const MString &annotationName, MStatus &status)
	Returns annotation value for a given parameter as integer. More...

float	annotationAsFloat (const MString &parameterName, const MString &annotationName, MStatus &status)
	Returns annotation value for a given parameter as float. More...

MString	annotationAsString (const MString &parameterName, const MString &annotationName, MStatus &status)
	Returns annotation value for a given parameter as MString. More...

MString	parameterSemantic (const MString &parameterName, MStatus &status)
	Returns the semantic associated to a given parameter. More...

void *	parameterDefaultValue (const MString &parameterName, MStatus &status)
	Returns the default value of a given parameter. More...

MString	resourceName (const MString &parameterName, MStatus &status)
	Returns the resource name of a given texture parameter. More...

MString	uiWidget (const MString &parameterName, MStatus &status)
	Returns the UI widget type associated with a given parameter. More...

MString	uiName (const MString &parameterName, MStatus &uiName)
	Returns the UI name associated with a given parameter. More...

MStatus	techniqueNames (MStringArray &techniqueNames) const
	Returns a list of the technique names for the effect. More...

int	techniqueAnnotationAsInt (const MString &annotationName, MStatus &status)
	Returns the value of the current technique annotation as integer. More...

float	techniqueAnnotationAsFloat (const MString &annotationName, MStatus &status)
	Returns the value of the current technique annotation as float. More...

MString	techniqueAnnotationAsString (const MString &annotationName, MStatus &status)
	Returns the value of the current technique annotation as MString. More...

int	passAnnotationAsInt (unsigned int pass, const MString &annotationName, MStatus &status)
	Returns the value of the current technique's pass annotation as int. More...

float	passAnnotationAsFloat (unsigned int pass, const MString &annotationName, MStatus &status)
	Returns the value of the current technique's pass annotation as float. More...

MString	passAnnotationAsString (unsigned int pass, const MString &annotationName, MStatus &status)
	Returns the value of the current technique's pass annotation as MString. More...

MStatus	writeEffectSourceToFile (const MString &filePath) const
	Write the source of the final OGSFX/HLSL/CgFX effect to a specified file. More...

Static Public Member Functions
static const char *	className ()
	Returns the name of this class. More...

Detailed Description

An instance of a shader that may be used with Viewport 2.0.

This class represents a shader that may be used with the MRenderItem class for rendering in Viewport 2.0.

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, apiMeshShape/apiMeshGeometryOverride.h, apiMeshShape/apiMeshSubSceneOverride.h, blindDataShader/blindDataShaderOverride.cpp, blindDataShader/blindDataShaderOverride.h, customSpriteShader/customSpriteShader.cpp, customTextureShader/customTextureShaderOverride.cpp, customTextureShader/customTextureShaderOverride.h, fileTexture/fileTexture.cpp, footPrintNode_AnimatedMaterial/footPrintNode_GeometryOverride_AnimatedMaterial.cpp, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, footPrintNode_SubSceneOverride/footPrintNode_SubSceneOverride.cpp, geometryOverrideExample1/geometryOverrideExample1.cpp, geometryOverrideExample2/geometryOverrideExample2.cpp, geometryReplicator/geometryReplicator.cpp, glslShader/GLSLShader.cpp, glslShader/GLSLShader.h, glslShader/GLSLShaderOverride.cpp, glslShader/GLSLShaderOverride.h, gpuCache/gpuCacheSubSceneOverride.cpp, hwPhongShader/hwPhongShader.cpp, phongShader/phongShaderOverride.cpp, phongShader/phongShaderOverride.h, rawfootPrintNode/rawfootPrintNode.cpp, simpleNoiseShader/simpleNoiseShaderOverride.cpp, simpleNoiseShader/simpleNoiseShaderOverride.h, swissArmyManip/swissArmyManip.cpp, tessellatedQuad/TessellatedQuadGeomOverride.cpp, viewImageBlitOverride/viewImageBlitOverride.cpp, viewImageBlitOverride/viewImageBlitOverride.h, viewMRenderOverride/viewMRenderOverride.cpp, viewOverrideTrackTexture/viewOverrideTrackTexture.cpp, viewOverrideTrackTexture/viewOverrideTrackTexture.h, viewRenderOverride/viewRenderOverride.h, viewRenderOverride/viewRenderOverrideOperations.cpp, viewRenderOverrideFrameCache/viewRenderOverrideFrameCache.cpp, viewRenderOverrideFrameCache/viewRenderOverrideFrameCache.h, viewRenderOverrideMRT/viewRenderOverrideMRT.cpp, viewRenderOverrideMRT/viewRenderOverrideMRT.h, viewRenderOverridePointLightShadows/viewRenderOverridePointLightShadows.cpp, viewRenderOverridePointLightShadows/viewRenderOverridePointLightShadows.h, viewRenderOverridePostColor/viewRenderOverridePostColor.cpp, viewRenderOverridePostColor/viewRenderOverridePostColor.h, viewRenderOverrideShadows/viewRenderOverrideShadows.cpp, viewRenderOverrideShadows/viewRenderOverrideShadows.h, viewRenderOverrideTargets/viewRenderOverrideTargets.cpp, viewRenderOverrideTargets/viewRenderOverrideTargets.h, and vp2BlinnShader/vp2BlinnShader.cpp.

Member Enumeration Documentation

enum ParameterType

Specifies parameter types.

Enumerator
kInvalid	Invalid element type (default value)
kBoolean	Boolean.
kInteger	Signed 32-bit integer.
kFloat	IEEE single precision floating point.
kFloat2	IEEE single precision floating point (x2)
kFloat3	IEEE single precision floating point (x3)
kFloat4	IEEE single precision floating point (x4)
kFloat4x4Row	IEEE single precision floating point row-major matrix (4x4)
kFloat4x4Col	IEEE single precision floating point column-major matrix (4x4)
kTexture1	1D texture
kTexture2	2D texture
kTexture3	3D texture
kTextureCube	Cube texture.
kSampler	Sampler.

enum FragmentUsage

Specifies where a fragment will be connected and used.

Enumerator
kPixelShader	The fragment will be connected and used in pixel shader (default value)
kNormalShader	Not implemented.
kNormalShader2	Not implemented.
kVertexShader	Not implemented.
kGeometryShader	Not implemented.
kGlossShader	Not implemented.
kGlossShader2	Not implemented.
kRotationAngleShader	Not implemented.
kRotationAngleShader2	Not implemented.
kReflectanceShader	Not implemented.
kReflectanceShader2	Not implemented.
kRoughnessShader	Not implemented.
kRoughnessShader2	Not implemented.
kAnisotropyShader	Not implemented.
kAnisotropyShader2	Not implemented.
kDisplacementPosShader	Not implemented.

Member Function Documentation

MShaderInstance::DrawCallback preDrawCallback ( ) const

Access the pre-draw callback function pointer set for the this shader instance.

Returns: The pre-draw callback function pointer or NULL if not set

MShaderInstance::DrawCallback postDrawCallback ( ) const

Access the post-draw callback function pointer set for the this shader instance.

Returns: The post-draw callback function pointer or NULL if not set

void parameterList ( MStringArray & list ) const

Get the names of all parameters that are settable on this shader instance.

Parameters

[out] list The list to populate parameter names

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, hwPhongShader/hwPhongShader.cpp, and viewRenderOverride/viewRenderOverrideOperations.cpp.

MShaderInstance::ParameterType parameterType ( const MString & parameterName ) const

Get the type of the named parameter, returns kInvalid if parameter is not found.

Parameters

[in] parameterName Name of the parameter to query

Returns: The type of the named parameter

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

bool isArrayParameter ( const MString & parameterName ) const

Determine whether the named parameter is an array.

Parameters

[in] parameterName Name of the parameter to query

Returns: True if the named parameter is an array

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

int getArraySize ( const MString & parameterName ) const

Get the size of the array.

Parameters

[in] parameterName Name of the parameter to query, if the named parameter is an array

Returns: the size of the array or -1 if not an array

MString semantic ( const MString & parameterName ) const

Return the semantic for a named parameter.

Parameters

[in] parameterName Name of the parameter to query

Returns: Semantic string. String will be empty if there is no semantic.

bool isVaryingParameter ( const MString & parameterName ) const

Determine whether the named parameter is varying or is uniform.

Parameters

[in] parameterName Name of the parameter to query

Returns: True if the named parameter varies per-vertex

MStatus setParameter	(	const MString &	parameterName,
		bool	value
	)

Set a named, boolean parameter on the shader instance.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	value	Value of the parameter

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not a boolean parameter.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, apiMeshShape/apiMeshSubSceneOverride.cpp, fileTexture/fileTexture.cpp, footPrintNode_AnimatedMaterial/footPrintNode_GeometryOverride_AnimatedMaterial.cpp, footPrintNode_GeometryOverride/footPrintNode_GeometryOverride.cpp, footPrintNode_SubSceneOverride/footPrintNode_SubSceneOverride.cpp, geometryOverrideExample1/geometryOverrideExample1.cpp, geometryOverrideExample2/geometryOverrideExample2.cpp, geometryReplicator/geometryReplicator.cpp, gpuCache/gpuCacheSubSceneOverride.cpp, hwPhongShader/hwPhongShader.cpp, phongShader/phongShaderOverride.cpp, rawfootPrintNode/rawfootPrintNode.cpp, simpleNoiseShader/simpleNoiseShaderOverride.cpp, tessellatedQuad/TessellatedQuadGeomOverride.cpp, viewMRenderOverride/viewMRenderOverride.cpp, viewRenderOverride/viewRenderOverrideOperations.cpp, viewRenderOverrideFrameCache/viewRenderOverrideFrameCache.cpp, viewRenderOverrideMRT/viewRenderOverrideMRT.cpp, viewRenderOverridePointLightShadows/viewRenderOverridePointLightShadows.cpp, viewRenderOverrideShadows/viewRenderOverrideShadows.cpp, viewRenderOverrideTargets/viewRenderOverrideTargets.cpp, and vp2BlinnShader/vp2BlinnShader.cpp.

MStatus setParameter	(	const MString &	parameterName,
		int	value
	)

Set a named, integer parameter on the shader instance.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	value	Value of the parameter

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not an integer parameter.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter	(	const MString &	parameterName,
		float	value
	)

Set a named, float parameter on the shader instance.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	value	Value of the parameter

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not a float parameter.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter	(	const MString &	parameterName,
		const float *	value
	)

Set a named, float, float2, float3 or float4 parameter on the shader instance.

The floating point data stored in "value" will be interpreted based on the type of the named parameter. For example, for a parameter of type kFloat3, the data will be assumed to be an array containing three floats.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	value	Value of the parameter

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not a float parameter.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter	(	const MString &	parameterName,
		const MFloatVector &	value
	)

Set a named, float, float2, float3 parameter on the shader instance.

The floating point data stored in "value" will be interpreted based on the type of the named parameter. For example, for a parameter of type kFloat3, the first 3 elements of the data will be set.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	value	Value of the parameter

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not a float parameter.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter	(	const MString &	parameterName,
		const MMatrix &	value
	)

Set a named, matrix parameter on the shader instance.

Note that this method does not alter the matrix and it is up to the caller to set the values correctly depending on whether the parameter is row-major or column-major.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	value	Value of the parameter

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not a matrix parameter.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter	(	const MString &	parameterName,
		const MFloatMatrix &	value
	)

Set a named, matrix parameter on the shader instance.

Note that this method does not alter the matrix and it is up to the caller to set the values correctly depending on whether the parameter is row-major or column-major.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	value	Value of the parameter

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not a matrix parameter.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter	(	const MString &	parameterName,
		MTextureAssignment &	textureAssignment
	)

Set a texture parameter on the shader instance.

If the texture assignment contains a NULL value for texture then the shader parameter will be set to NULL.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	textureAssignment	Texture to assign

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not a texture parameter.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter	(	const MString &	parameterName,
		MRenderTargetAssignment &	targetAssignment
	)

Set a named, texture parameter on the shader instance to a render target.

If the render target assignment contains a NULL value then the shader parameter will be set to NULL.

Note, there is a significant performance penalty when binding MSAA targets (i.e. targets where multiSampleCount > 1).

Parameters

[in]	parameterName	Name of the parameter to set
[in]	targetAssignment	Render target to assign

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not a texture parameter.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter	(	const MString &	parameterName,
		const MSamplerState &	sampler
	)

Set a sampler parameter on the shader instance.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	sampler	Sampler state to assign

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not a sampler parameter.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus setArrayParameter	(	const MString &	parameterName,
		const bool *	values,
		unsigned int	count
	)

Set a named, bool array parameter on the shader instance.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	values	The array of values to set
[in]	count	The number of values in the array

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not a bool array parameter or count is out of bounds.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus setArrayParameter	(	const MString &	parameterName,
		const int *	values,
		unsigned int	count
	)

Set a named, integer array parameter on the shader instance.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	values	The array of values to set
[in]	count	The number of values in the array

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not an integer array parameter or count is out of bounds.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus setArrayParameter	(	const MString &	parameterName,
		const float *	values,
		unsigned int	count
	)

Set a named, float array parameter on the shader instance.

This method is used for setting not just float arrays but float2, float3 and float4 array parameters as well. The floating point data stored in "values" will be interpreted based on the type of the named parameter. For example, for a parameter of type kFloat3, the data will be assumed to be a list of float-triples containing a total of "count" float-triples. So if "count" in this example is 5, that means the total number of raw floats is 3*5=15.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	values	The array of values to set
[in]	count	The number of floats stored in the array divided by the dimension of the data

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not a float array parameter or count is out of bounds.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus setArrayParameter	(	const MString &	parameterName,
		const MMatrix *	values,
		unsigned int	count
	)

Set a named, matrix array parameter on the shader instance.

Note that this method does not alter the matrices and it is up to the caller to set the values correctly depending on whether the parameter is row-major or column-major.

Parameters

[in]	parameterName	Name of the parameter to set
[in]	values	The array of values to set
[in]	count	The number of values in the array

Returns: Status code

Status Codes:

MS::kSuccess The parameter was set.
MS::kInvalidParameter The named parameter is not a matrix array parameter or count is out of bounds.
MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
MS::kFailure An internal error prevented the parameter from being set.

MStatus addInputFragment	(	const MString &	fragmentName,
		const MString &	outputName,
		const MString &	inputName,
		const MString	promotedInputName = `MString()`
	)

Connect a fragment that has been registered with the fragment manager to an input on the existing MShaderInstance.

Use this method to add shader instructions to an existing MShaderInstance. The code defined in the fragment will be compiled and executed on the GPU to compute the value for the input parameter.

Parameters

[in]	fragmentName	The name of a fragment that has been registered with the MFragmentManager.
[in]	outputName	The name of the output on the registered fragment to connect to.
[in]	inputName	The name of the input parameter on the MShaderInstance to connect to.
[in]	promotedInputName	The name of the input parameter on the new fragment that will be promoted to replace the input parameter being connected to. If this argument is not specified, and an input with the same name as inputName exist on the input fragment it will automatically be promoted.

Returns: Status code

Status Codes:

MS::kSuccess The input was added correctly.
MS::kFailure The shader instance was not compatible with an input fragment. For instance it uses a file based effect which cannot be modified.
MS::kNotFound The fragment was not registered with the fragment manager.
MS::kUnknownParameter The input or output name does not exist to connect to or their types do not match.

Examples:: customSpriteShader/customSpriteShader.cpp.

MStatus addInputFragmentForMultiParams	(	const MString &	fragmentName,
		const MString &	uniqueName,
		const MStringArray &	outputNames,
		const MStringArray &	inputNames,
		MUintArray *	invalidParameterIndices = `nullptr`,
		FragmentUsage	fragmentUsage = `kPixelShader`
	)

Connect a named fragment that has been registered with the MFragmentManager to this MShaderInstance.

The code defined in the fragment will be included in the new shader and executed on GPU to compute values for input parameters specified by inputNames.

To connect with fragments, this MShaderInstance needs to be created from a shader fragment or fragment graph as well. Thus, a shader instance created from a file-based effect cannot connect with any fragments.

After the fragment is connected, all input parameters with the same name in the new fragment graph are mapped to a single parameter in the shader by default. If uniqueness is required for input parameters on the fragment, uniqueName can be used to prefix names of the input parameters.

This method is particularly useful when plugin needs to make multiple connections from the input fragment to this MShaderInstance. It can be used to make a single connection, but addInputFragment() is more convenient in this case. The numbers of the output and input parameters must match. An output and an input parameter with the same index in the two string arrays will be connected. To specify fan-out connections, the same output name can be repeated in outputNames as need. Fan-in connections are not allowed.

If the numbers of the output and input parameters don't match, or a parameter (either output or input) doesn't exist, or their types don't match, the relevant parameters will not be connected and the method will return MStatus::kInvalidParameter. In this case, the fragment may still be connected partially to this MShaderInstance through other connectable parameter pairs, and plugin can use invalidParameterIndices to query indices of those invalid parameters in outputNames and inputNames.

Parameters

[in]	fragmentName	Name of the input fragment.
[in]	uniqueName	A unique name to prefix names of input parameters on the input fragment.
[in]	outputNames	Names of the output parameters on the input fragment to connect from.
[in]	inputNames	Names of the input parameters on the MShaderInstance to connect to.
[out]	invalidParameterIndices	Optional array to query indices of invalid parameters.
[in]	fragmentUsage	Not implemented.

Returns: Status code

Status Codes:

MS::kSuccess The fragment was connected correctly.
MS::kFailure The shader instance was not compatible with an input fragment. For instance it uses a file-based effect which cannot be modified.
MS::kNotFound The fragment was not registered with MFragmentManager.
MS::kInvalidParameter The fragment was connected partially due to invalid parameters.

MStatus addOutputFragment	(	const MString &	fragmentName,
		const MString &	inputName
	)

Connect a fragment that has been registered with the fragment manager to an output on the existing MShaderInstance.

The code defined in the fragment will be compiled and executed on the GPU to modify the value returned by the original shader. For example, use this method to add additional alpha or conditionals to the output color.

Parameters

[in]	fragmentName	The name of a fragment that has been registered with the MFragmentManager.
[in]	inputName	The name of the input parameter on the fragment to connect the shaders output to.

Returns: Status code

Status Codes:

MS::kSuccess The output was added correctly.
MS::kFailure The shader instance was not compatible with an output fragment. For instance it uses a file based effect which cannot be modified.
MS::kNotFound The fragment was not registered with the fragment manager.
MS::kUnknownParameter The input name does not exist to connect to.

MStatus renameParameter	(	const MString &	oldName,
		const MString &	newName
	)

Rename the parameter.

Note this only works for fragment based shader instances.

Parameters

[in]	oldName	The name of a parameter.
[in]	newName	The new name to give the parameter.

Returns: Status code

Status Codes:

MS::kSuccess The name was set correctly.
MS::kFailure The shader instance was not a fragment based shader instance. Renaming only works on fragment based shaders.
MS::kUnknownParameter A parameter by that name does not exist on the shader instance.

MStatus setSemantic	(	const MString &	paramName,
		const MString &	semantic
	)

Set the semantic for a fragment based parameter.

Note this only works for fragment based shaders.

Parameters

[in]	paramName	The name of a parameter.
[in]	semantic	The semantic to assign to the parameter. Semantics can be used to identify parameters by their use, independent of their names.

Returns: Status code

Status Codes:

MS::kSuccess The semantic was set correctly.
MS::kFailure The shader instance was not a fragment based shader instance. Setting the semantic only works on fragment based shaders.
MS::kUnknownParameter A parameter by that name does not exist on the shader instance.

MStatus setAsVarying	(	const MString &	paramName,
		bool	isVarying
	)

Set the parameter to be a varying parameter or not for a fragment based parameter.

Note this only works for fragment based shaders.

Parameters

[in]	paramName	The name of a parameter.
[in]	isVarying	True if the parameter should vary per vertex, false if the parameter should be treated as a uniform value.

Returns: Status code

Status Codes:

MS::kSuccess The argument was set correctly.
MS::kFailure The shader instance was not a fragment based shader instance. Setting this option only works on fragment based shaders.
MS::kUnknownParameter A parameter by that name does not exist on the shader instance.

MStatus bind ( const MDrawContext & context ) const

Binds the shader instance to the draw context, so that it is the active shader.

The typical call sequence is

bind() getPassCount() activatePass( 0 ) do drawing activatePass( 1 ) do drawing ... unbind()

Note that it is the plug-in author's responsibility to call unbind() at the appropriate time. Failing to do so may corrupt subsequent drawing.

Parameters

[in] context The current draw context

Returns: Status code

Status Codes:

MS::kSuccess The bind operation succeeded
MS::kFailure The shader instance or draw context was invalid, or it failed to bind. This can happen on first bind when an OGSFX effect causes GLSL compilation errors.

Examples:: blindDataShader/blindDataShaderOverride.cpp, customSpriteShader/customSpriteShader.cpp, glslShader/GLSLShader.cpp, glslShader/GLSLShaderOverride.cpp, and swissArmyManip/swissArmyManip.cpp.

unsigned int getPassCount	(	const MDrawContext &	context,
		MStatus *	status = `NULL`
	)		const

Returns the number of draw passes defined by the shader.

Parameters

[in]	context	The current draw context
[out]	status	Status code

Returns: The pass count

Status Codes:

MS::kSuccess The operation succeeded
MS::kFailure The shader instance or draw context was invalid

Examples:: customTextureShader/customTextureShaderOverride.cpp, glslShader/GLSLShader.cpp, and glslShader/GLSLShaderOverride.cpp.

MStatus activatePass	(	const MDrawContext &	context,
		unsigned int	pass
	)		const

Activates the given pass of the shader.

Must be called between calls to bind() and unbind().

Parameters

[in]	context	The current draw context
[in]	pass	The index of the pass to activate

Returns: Status code

Status Codes:

MS::kSuccess The operation succeeded
MS::kFailure The shader instance or draw context was invalid

Examples:: customTextureShader/customTextureShaderOverride.cpp, glslShader/GLSLShaderOverride.cpp, and swissArmyManip/swissArmyManip.cpp.

MStatus unbind ( const MDrawContext & context ) const

Unbinds the shader instance from the draw context.

Parameters

[in] context The current draw context

Returns: Status code

Status Codes:

MS::kSuccess The unbind operation succeeded
MS::kFailure The shader instance or draw context was invalid

Examples:: customSpriteShader/customSpriteShader.cpp, glslShader/GLSLShader.cpp, glslShader/GLSLShaderOverride.cpp, and swissArmyManip/swissArmyManip.cpp.

MStatus updateParameters ( const MDrawContext & context ) const

Updates the bound shader instance with the current parameter data.

This is useful in cases where the same shader instance is reusable but with different input parameters.

Must be called between calls to bind() and unbind().

Calling this method will invalidate any currently active pass. Must invoke activatePass() after calling this method.

Parameters

[in] context The current draw context

Returns: Status code

Status Codes:

MS::kSuccess The update operation succeeded
MS::kFailure The shader instance or draw context was invalid

Examples:: glslShader/GLSLShaderOverride.cpp, and swissArmyManip/swissArmyManip.cpp.

bool isTransparent ( ) const

Return whether the shader will render with transparency.

Returns: true if shader will render with transparency

MStatus setIsTransparent ( bool value )

Set whether the shader will render with transparency.

Parameters

[in] value Value to set

Returns: Status code

Status Codes:

MS::kSuccess The value was set.
MS::kFailure The value could not be set.

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, and gpuCache/gpuCacheSubSceneOverride.cpp.

MShaderInstance * clone ( ) const

Clone the shader.

This will return a new MShaderInstance object which is identical to the existing shader. The new shader is completely independent of the original. Setting parameter values on either shader after calling clone will have no effect on the other.

Using clone can improve performance when many copies of the same shader are needed. When requesting MShaderInstance objects from MShaderManager the shader is recompiled for each request. The clone() method does not cause a recompilation.

Returns: A clone of this shader or NULL on failure

MShaderInstance * createShaderInstanceWithColorManagementFragment ( const MString & inputColorSpace )

Return a new shader instance with Color Management fragment added, which is based on the callee.

The callee shader instance is the one used for rendering a render item with image(a MPxNode with image, etc.) The new shader is completely independent of the original shader. Setting parameter values on either shader after calling this function will have no effect on the other. The function won't keep a copy of input parameter.

When the returned new shader instance is no longer needed, MShaderManager::releaseShader() should be called to notify the shader manager that the caller is done with the shader.

Parameters

[in] inputColorSpace The color space the current image is in

Returns: A new shader instance or NULL on failure

MStatus requiredVertexBuffers ( MVertexBufferDescriptorList & list ) const

Get the vertex buffer descriptors that describe the buffers required by a given shader instance.

The descriptor elements will be appended to the passed list. It is the responsibility of the caller to clear the list if desired before calling this method using the MVertexBufferDescriptorList::clear() method.

Parameters

[out] list List of vertex buffer descriptors

Returns: MStatus::kSuccess if successful

const char * className ( )

static

Returns the name of this class.

Returns: Name of this class.

int annotationAsInt	(	const MString &	parameterName,
		const MString &	annotationName,
		MStatus &	status
	)

Returns annotation value for a given parameter as integer.

Parameters

[in]	parameterName	The name of the parameter.
[in]	annotationName	The name of the annotation.
[in]	status	Reference to a status object to output operation status.

Returns: The annotation value as integer.

Status Codes:

MS::kSuccess The annotation value was found and returned correctly.
MS::kUnknownParameter The parameter is not a parameter of the instance or annotation is not defined for this parameter.
MS::kInvalidParameter The annotation value is not an integer, the returned value may still be valid.
MS::kNotFound An internal error prevented the parameter from being found.

float annotationAsFloat	(	const MString &	parameterName,
		const MString &	annotationName,
		MStatus &	status
	)

Returns annotation value for a given parameter as float.

Parameters

[in]	parameterName	The name of the parameter.
[in]	annotationName	The name of the annotation.
[in]	status	Reference to a status object to output operation status.

Returns: The annotation value as float.

Status Codes:

MS::kSuccess The annotation value was found and returned correctly.
MS::kUnknownParameter The parameter is not a parameter of the instance or annotation is not defined for this parameter.
MS::kInvalidParameter The annotation value is not a float, the returned value may still be valid.
MS::kNotFound An internal error prevented the parameter from being found.

MString annotationAsString	(	const MString &	parameterName,
		const MString &	annotationName,
		MStatus &	status
	)

Returns annotation value for a given parameter as MString.

Parameters

[in]	parameterName	The name of the parameter.
[in]	annotationName	The name of the annotation.
[in]	status	Reference to a status object to output operation status.

Returns: The annotation value as MString.

Status Codes:

MS::kSuccess The annotation value was found and returned correctly.
MS::kUnknownParameter The parameter is not a parameter of the instance or annotation is not defined for this parameter.
MS::kInvalidParameter The annotation value is not a string, the returned value may still be valid.
MS::kNotFound An internal error prevented the parameter from being found.

MString parameterSemantic	(	const MString &	parameterName,
		MStatus &	status
	)

Returns the semantic associated to a given parameter.

Parameters

[in]	parameterName	The name of the parameter.
[in]	status	Reference to a status object to output operation status.

Returns: The semantic name as a MString.

Status Codes:

MS::kSuccess The semantic was found and returned correctly.
MS::kUnknownParameter The parameter is not a parameter of the instance.
MS::kFailure An internal error prevented the parameter from being found.

void * parameterDefaultValue	(	const MString &	parameterName,
		MStatus &	status
	)

Returns the default value of a given parameter.

Parameters

[in]	parameterName	The name of the parameter.
[in]	status	Reference to a status object to output operation status.

Returns: A void pointer to the default value.

Status Codes:

MS::kSuccess The default value was found.
MS::kUnknownParameter The parameter is not a parameter of the instance.
MS::kFailure An internal error prevented the parameter from being found.

MString resourceName	(	const MString &	parameterName,
		MStatus &	status
	)

Returns the resource name of a given texture parameter.

The resource name of a texture parameter can be specified in the effect file using the "ResourceName" annotation. It allows users to define a default texture using an external file. If no resource was defined for a texture, this function returns an empty string.

Parameters

[in]	parameterName	The name of the texture parameter.
[in]	status	Reference to a status object to output operation status.

Returns: The resource name as MString.

Status Codes:

MS::kSuccess The resource name was found and returned correctly.
MS::kUnknownParameter The parameter is not a parameter of the instance.
MS::kFailure An internal error prevented the parameter from being found.

MString uiWidget	(	const MString &	parameterName,
		MStatus &	status
	)

Returns the UI widget type associated with a given parameter.

The UI widget type can be specified in shader using the "UIWidget" annotation.

Parameters

[in]	parameterName	The name of the parameter.
[in]	status	Reference to a status object to output operation status.

Returns: The name of the UI widget type as MString.

Status Codes:

MS::kSuccess The uiWidget type was found and returned correctly.
MS::kUnknownParameter The parameter is not a parameter of the instance.
MS::kFailure An internal error prevented the parameter from being found.

MString uiName	(	const MString &	parameterName,
		MStatus &	status
	)

Returns the UI name associated with a given parameter.

The UI name can be specified in shader using the "UIName" annotation.

Parameters

[in]	parameterName	The name of the parameter.
[in]	status	Reference to a status object to output operation status.

Returns: The name of the UI name as MString.

Status Codes:

MS::kSuccess The parameter UI name was found and returned correctly.
MS::kUnknownParameter The parameter is not a parameter of the instance.
MS::kFailure An internal error prevented the parameter from being found.

MStatus techniqueNames ( MStringArray & techniqueNames ) const

Returns a list of the technique names for the effect.

Parameters

[out] techniqueNames Returns the list of technique names for the effect.

Returns: Status code

Status Codes:

MS::kSuccess The techniques list was found and returned correctly.
MS::kFailure An internal error prevented the list of techniques from being retrieved.

int techniqueAnnotationAsInt	(	const MString &	annotationName,
		MStatus &	status
	)

Returns the value of the current technique annotation as integer.

Parameters

[in]	annotationName	The name of the technique annotation.
[in]	status	Reference to a status object to output operation status.

Returns: The technique annotation value as integer.

Status Codes:

MS::kSuccess The technique annotation was found and returned correctly.
MS::kNotFound The technique annotation was not found.
MS::kInvalidParameter The annotation value is not an integer, the returned value may still be valid.
MS::kFailure An internal error prevented the annotation from being found.

float techniqueAnnotationAsFloat	(	const MString &	annotationName,
		MStatus &	status
	)

Returns the value of the current technique annotation as float.

Parameters

[in]	annotationName	The name of the technique annotation.
[in]	status	Reference to a status object to output operation status.

Returns: The technique annotation value as float.

Status Codes:

MS::kSuccess The technique annotation was found and returned correctly.
MS::kNotFound The technique annotation was not found.
MS::kInvalidParameter The annotation value is not a float, the returned value may still be valid.
MS::kFailure An internal error prevented the annotation from being found.

MString techniqueAnnotationAsString	(	const MString &	annotationName,
		MStatus &	status
	)

Returns the value of the current technique annotation as MString.

Parameters

[in]	annotationName	The name of the technique annotation.
[in]	status	Reference to a status object to output operation status.

Returns: The technique annotation value as MString.

Status Codes:

MS::kSuccess The technique annotation was found and returned correctly.
MS::kNotFound The technique annotation was not found.
MS::kInvalidParameter The annotation value is not a string, the returned value may still be valid.
MS::kFailure An internal error prevented the annotation from being found.

int passAnnotationAsInt	(	unsigned int	pass,
		const MString &	annotationName,
		MStatus &	status
	)

Returns the value of the current technique's pass annotation as int.

Parameters

[in]	pass	The index of the pass.
[in]	annotationName	The name of the pass annotation.
[in]	status	Reference to a status object to output operation status.

Returns: The pass annotation value as int.

Status Codes:

MS::kSuccess The pass annotation was found and returned correctly.
MS::kNotFound The pass annotation was not found.
MS::kInvalidParameter The annotation value is not an integer, the returned value may still be valid.
MS::kFailure An internal error prevented the parameter from being found.

float passAnnotationAsFloat	(	unsigned int	pass,
		const MString &	annotationName,
		MStatus &	status
	)

Returns the value of the current technique's pass annotation as float.

Parameters

[in]	pass	The index of the pass.
[in]	annotationName	The name of the pass annotation.
[in]	status	Reference to a status object to output operation status.

Returns: The pass annotation value as float.

Status Codes:

MS::kSuccess The pass annotation was found and returned correctly.
MS::kNotFound The pass annotation was not found.
MS::kInvalidParameter The annotation value is not a float, the returned value may still be valid.
MS::kFailure An internal error prevented the parameter from being found.

MString passAnnotationAsString	(	unsigned int	pass,
		const MString &	annotationName,
		MStatus &	status
	)

Returns the value of the current technique's pass annotation as MString.

Parameters

[in]	pass	The index of the pass.
[in]	annotationName	The name of the pass annotation.
[in]	status	Reference to a status object to output operation status.

Returns: The pass annotation value as MString.

Status Codes:

MS::kSuccess The pass annotation was found and returned correctly.
MS::kNotFound The pass annotation was not found.
MS::kInvalidParameter The annotation value is not a string, the returned value may still be valid.
MS::kFailure An internal error prevented the parameter from being found.

Examples:: glslShader/GLSLShader.cpp.

MStatus writeEffectSourceToFile ( const MString & filePath ) const

Write the source of the final OGSFX/HLSL/CgFX effect to a specified file.

Use this for debugging to see how fragments are turned into the final effect for the current drawing API.

Note that the effect will not be written if the effect is not generated from shader fragments or any of the shader fragments is marked as hidden.

Parameters

[in] filePath Path of the file to write the effect source

Returns: Status code

Status Codes:

MS::kSuccess The effect was written successfully.
MS::kFailure The effect could not be written.

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp.

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

MShaderManager.h
MShaderManager.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation