MFragmentManager Class Reference

#include <MFragmentManager.h>

Class Description

Provides facilities for managing fragments for use with Viewport 2.0.

MFragmentManager provides functionality for dealing with Viewport 2.0 shade fragments and fragment graphs. Both are defined using an XML format and can be specified using either a file or a string buffer.

The XML format describes input and output parameters for the fragment as well as default values for parameters. It also allows the specification of multiple implementations of the fragment (e.g. a Cg implementation and an HLSL implementation) so that fragments can be created that work in both the OpenGL and DirectX versions of Viewport 2.0. The format can also be used to define how several fragments should be connected together into a single fragment graph.

Please see the Viewport 2.0 section of the Maya API guide for a more detailed description of the XML along with a complete XML Schema (XSD) for both fragments and fragment graphs.

In addition to the description in the API guide MFragmentManager provides several methods for examining how Maya works with fragments and graphs.

The XML for many of the fragments and fragment graphs used for Maya's internal nodes are available for inspection. fragmentList() will return a list of the names of all non-hidden fragments and fragment graphs. For any of these names, getFragmentXML() may be called to retrieve the XML for that fragment.

While combining fragments, Maya often creates intermediate fragment graphs on the fly. These are not stored in the manager so they may not be queried through getFragmentXML(). To see the XML for these intermediate graphs, call setIntermediateGraphOutputDirectory() with a directory and Maya will dump the XML to files in that directory every time it creates such a graph.

When all fragments have been connected and joined together, Maya will create a final effect. This effect is compiled and used to drive geometry requirements and final shading. The text for this effect can be dumped to disk every time it is created by calling setEffectOutputDirectory() with a valid directory. This text can be used to see how final effects are created out of fragment graphs.

Note that for the intermediate graph and effect output directories, Maya will use whatever value was set last. So multiple plugins that set these values may conflict with each other. These methods are intended to be used as debug tools only during development of a plugin. The usage of them incurs a performance penalty and so it is strongly discouraged to use them in a production setting.

Examples:

Public Member Functions
bool	hasFragment (const MString &fragmentName) const
	Returns true if a fragment of the given name has been registered with the fragment manager. More...
void	fragmentList (MStringArray &fragmentNames) const
	Returns a list of the names of all registered fragments and fragment graphs (both internal and external) which are not hidden. More...
bool	getFragmentXML (const MString &fragmentName, MString &buffer) const
	Fills the buffer with the XML representation of the named fragment or fragment graph (if it exists). More...
bool	getFragmentXML (const MObject &shadingNode, MString &buffer, bool includeUpstreamNodes=false, const MDagPath *objectContext=NULL) const
	Fills the buffer with the XML code for the fragment graph Maya would use to represent the given shading node in Viewport 2.0. More...
MString	addShadeFragmentFromBuffer (const char *buffer, bool hidden)
	Add a new fragment to the manager. More...
MString	addShadeFragmentFromFile (const MString &fileName, bool hidden)
	Add a new fragment to the manager. More...
MString	addFragmentGraphFromBuffer (const char *buffer)
	Add a new fragment graph to the manager. More...
MString	addFragmentGraphFromFile (const MString &fileName)
	Add a new fragment graph to the manager. More...
bool	removeFragment (const MString &fragmentName)
	Remove a named fragment or fragment graph from the fragment manager. More...
bool	addFragmentPath (const MString &path)
	Add a path to the list of fragment search paths used when parsing the file path for any methods which add fragments to the manager from files on disk. More...
void	setEffectOutputDirectory (const MString &dir)
	Set the path to use for dumping final effect files. More...
MString	getEffectOutputDirectory () const
	Get the directory to be used for effect file output. More...
void	setIntermediateGraphOutputDirectory (const MString &dir)
	Set the path to use for dumping intermediate fragment graph XML files. More...
MString	getIntermediateGraphOutputDirectory () const
	Get the directory to be used for intermediate fragment graph output. More...

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

Member Function Documentation

bool hasFragment

(

const MString &

fragmentName

)

const

Returns true if a fragment of the given name has been registered with the fragment manager.

Parameters

[in]

fragmentName

The name of the fragment to search for

Returns

True if such a fragment is registered, false otherwise

Examples:

void fragmentList

(

MStringArray &

fragmentNames

)

const

Returns a list of the names of all registered fragments and fragment graphs (both internal and external) which are not hidden.

Parameters

[out]

fragmentNames

The string array to fill with the fragment names

Examples:

bool getFragmentXML	(	const MString &	fragmentName,
		MString &	buffer
	)		const

Fills the buffer with the XML representation of the named fragment or fragment graph (if it exists).

This can be used to view the structure and implementation of internal Maya fragments in order to better understand how they work when writing fragments for plugins.

This method will fail for any fragment which was added to the manager as a "hidden" fragment.

Parameters

[in]	fragmentName	The name of the fragment to get the XML for
[out]	buffer	Buffer for storing the XML

Returns

True if the XML was successfully retrieved

Examples:

bool getFragmentXML	(	const MObject &	shadingNode,
		MString &	buffer,
		bool	includeUpstreamNodes = false,
		const MDagPath *	objectContext = NULL
	)		const

Fills the buffer with the XML code for the fragment graph Maya would use to represent the given shading node in Viewport 2.0.

If includeUpstreamNodes is true, this method will return the XML code of the fragment graph that Maya would use to represent the shading node network rooted at the given shading node in Viewport 2.0.

The fragment graphs for some shaders depend on the DAG objects they are associated with in Maya. For example, the single/double/triple switch shaders all depend on objects in the DAG. For these cases, callers to this method may optionally supply object context via a DAG path to an instance of an object in the scene. The requested shading node must be part of the shading network assigned to the object specified by the DAG path.

This method can be helpful for determining how Maya builds up fragment graphs to render various shading node configurations in the viewport.

This method will fail if Maya does not have a defined fragment graph representation for the given shading node or if the required fragments are marked as "hidden" and thus cannot be output as XML. In the case where includeUpstreamNodes is true, only supported upstream nodes will be included in the fragment graph.

Note that for surface shaders, the returned XML code for the fragment graph will include connections for lights. When defining custom fragment graphs in XML for use with MPxShadingNodeOverride it is important to exclude the light connections as they are added automatically at runtime. For the "pure" XML version of Maya's surface shader fragments, use MFragmentManager::getFragmentXML(const MString&, MString& buffer) with the name of the required fragment graph.

Parameters

[in]	shadingNode	The node to get the XML code for
[out]	buffer	Buffer for storing the XML
[in]	includeUpstreamNodes	Return the XML for the entire fragment graph rooted at the given shading node if true
[in]	objectContext	Optional path to an instance that is associated with the shading node to provide object context

Returns

True if the XML was successfully retrieved

MString addShadeFragmentFromBuffer	(	const char *	buffer,
		bool	hidden
	)

Add a new fragment to the manager.

The fragment is defined as XML stored in a string buffer. If a fragment with the same name is already registered with the fragment manager, registration will fail.

Errors encountered parsing the XML will be echoed to stderr.

Parameters

[in]	buffer	A null-terminated string containing an XML description of the fragment
[in]	hidden	If true, this fragment will not appear in the list returned by fragmentList() and it will not be possible to query the XML for it using getFragmentXML(). This will not affect the return value of hasFragment() for this fragment.

Returns

The name of the registered fragment, or empty string on failure

Examples:

MString addShadeFragmentFromFile	(	const MString &	fileName,
		bool	hidden
	)

Add a new fragment to the manager.

The fragment is defined as XML stored in the given file. If a fragment with the same name is already registered with the fragment manager, registration will fail.

Errors encountered parsing the XML will be echoed to stderr.

Parameters

[in]	fileName	The name of the file containing the fragment description
[in]	hidden	If true, this fragment will not appear in the list returned by fragmentList() and it will not be possible to query the XML for it using getFragmentXML(). This will not affect the return value of hasFragment() for this fragment.

Returns

The name of the registered fragment, or empty string on failure

Examples:

MString addFragmentGraphFromBuffer

(

const char *

buffer

)

Add a new fragment graph to the manager.

The fragment graph is defined as XML stored in a string buffer. If a fragment with the same name is already registered with the fragment manager, registration will fail.

Unlike fragments, fragments graphs cannot be explicitly marked as hidden. A graph is considered hidden if any of the fragments that make it up are hidden.

Errors encountered parsing the XML will be echoed to stderr.

Parameters

[in]

buffer

A null-terminated string containing an XML description of the fragment graph

Returns

The name of the registered fragment graph, or empty string on failure

Examples:

MString addFragmentGraphFromFile

(

const MString &

fileName

)

Add a new fragment graph to the manager.

The fragment graph is defined as XML stored in the given file. If a fragment with the same name is already registered with the fragment manager, registration will fail.

Unlike fragments, fragments graphs cannot be explicitly marked as hidden. A graph is considered hidden if any of the fragments that make it up are hidden.

Errors encountered parsing the XML will be echoed to stderr.

Parameters

[in]

fileName

The name of the file containing the fragment graph description

Returns

The name of the registered fragment graph, or empty string on failure

Examples:

bool removeFragment

(

const MString &

fragmentName

)

Remove a named fragment or fragment graph from the fragment manager.

This can be used to remove registered fragments on plug-in unload.

Any fragment may be removed including those defined by Maya. In this way users may replace default Maya fragments with custom fragments. When replacing an existing Maya fragment it is important to maintain the same fragment interface (i.e. input and output parameters) otherwise Maya's behavior will be undefined. Maya's behavior will also be undefined if a default Maya fragment is removed without replacing it.

Parameters

[in]

fragmentName

The name of the fragment or fragment graph to remove

Returns

True on success

Examples:

bool addFragmentPath

(

const MString &

path

)

Add a path to the list of fragment search paths used when parsing the file path for any methods which add fragments to the manager from files on disk.

Parameters

[in]

path

Fragment search path

Returns

True on success

Examples:

void setEffectOutputDirectory

(

const MString &

dir

)

Set the path to use for dumping final effect files.

When Maya builds a shader effect out of shade fragments it will output the text of the final CgFX or HLSL effect to a file in the directory named here. Use this for debugging to see how fragments are turned into final effects. The directory must be an absolute path and must end with a '/' character.

Setting the directory to the empty string will disable effect output.

Note that effect files will not be output if any fragment used in the effect is marked as hidden.

Parameters

[in]

dir

The directory to use for effect file output

MString getEffectOutputDirectory

(

)

const

Get the directory to be used for effect file output.

Returns

The directory to be used for effect file output

void setIntermediateGraphOutputDirectory

(

const MString &

dir

)

Set the path to use for dumping intermediate fragment graph XML files.

When Maya assembles the shade fragment graph for a Maya shader network it takes all the fragments and graphs for each node and dynamically builds up larger and more complex fragment graphs. Maya will output the XML for these fragment graphs to the directory named here. Use this for debugging to see how fragments and graphs for single nodes are combined with the fragments and graphs of other Maya nodes in the process of building a final shader effect. The directory must be an absolute path and must end with a '/' character.

Setting the directory to the empty string will disable intermediate fragment graph output.

Note that XML files will not be output if any fragment used in the intermediate graphs are hidden.

Parameters

[in]

dir

The directory to use for intermediate fragment graph output

MString getIntermediateGraphOutputDirectory

(

)

const

Get the directory to be used for intermediate fragment graph output.

Returns

The directory to be used for intermediate fragment graph output

const char * className ( )

static

Returns the name of this class.

Returns

Name of this class.

---

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

• MFragmentManager.h
• MFragmentManager.cpp