MFragmentManager Class Reference
This reference page is linked to from the following overview topics: Autodesk Maya 2014, Scene Overrides, Framework Classes, 3.2 The Renderer, 3.5 Shading Node Overrides, 5.3 Multiple Draw APIs, 6.1 XML Schema for Shading Fragments, 6.2 XML Schema for Fragment Graphs, Shader semantics supported by Viewport 2.0.
Detailed 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:
-
brickShader.cpp, checkerShader.cpp, contrastShader.cpp, depthShader.cpp, gammaShader.cpp, and mixtureShader.cpp.
#include <MFragmentManager.h>
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. | |
| 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. | |
| 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). | |
| MString | addShadeFragmentFromBuffer (const char *buffer, bool hidden) |
| Add a new fragment to the manager. | |
| MString | addShadeFragmentFromFile (const MString &fileName, bool hidden) |
| Add a new fragment to the manager. | |
| MString | addFragmentGraphFromBuffer (const char *buffer) |
| Add a new fragment graph to the manager. | |
| MString | addFragmentGraphFromFile (const MString &fileName) |
| Add a new fragment graph to the manager. | |
| 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. | |
| void | setEffectOutputDirectory (const MString &dir) |
| Set the path to use for dumping final effect files. | |
| MString | getEffectOutputDirectory () const |
| Get 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. | |
| MString | getIntermediateGraphOutputDirectory () const |
| Get the directory to be used for intermediate fragment graph output. | |
Static Public Member Functions | |
| static const char * | className () |
| Returns the name of this class. | |
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:
- brickShader.cpp, checkerShader.cpp, contrastShader.cpp, depthShader.cpp, gammaShader.cpp, and mixtureShader.cpp.
| 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
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
| 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.
- 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:
- brickShader.cpp, contrastShader.cpp, depthShader.cpp, gammaShader.cpp, and mixtureShader.cpp.
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.
- 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:
- checkerShader.cpp.
| 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.
- 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:
- depthShader.cpp.
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.
- 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:
- checkerShader.cpp.
| 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:
- checkerShader.cpp.
| 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] |
