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]fragmentNameThe 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]fragmentNamesThe 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]fragmentNameThe name of the fragment to get the XML for
[out]bufferBuffer 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]shadingNodeThe node to get the XML code for
[out]bufferBuffer for storing the XML
[in]includeUpstreamNodesReturn the XML for the entire fragment graph rooted at the given shading node if true
[in]objectContextOptional 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]bufferA null-terminated string containing an XML description of the fragment
[in]hiddenIf 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]fileNameThe name of the file containing the fragment description
[in]hiddenIf 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]bufferA 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]fileNameThe 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]fragmentNameThe 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]pathFragment 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]dirThe 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]dirThe 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