- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions

# MFragmentManager Class Reference
OpenMayaRender - API module for rendering

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.

Search for all occurrences

## 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>`

List of all members.

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

Search for all occurrences

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

Search for all occurrences

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

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

Search for all occurrences

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

Search for all occurrences

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.

MString addShadeFragmentFromFile | ( | const MString & | fileName,
|  | bool | hidden
| ) |  |

Search for all occurrences

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

Search for all occurrences

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.

MString addFragmentGraphFromFile | ( | const MString & | fileName | ) |

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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]`

Search for all occurrences

Returns the name of this class.

Returns:
  Name of this class.

MFragmentManager MFragmentManager MFragmentManager MFragmentManager MFragmentManager MFragmentManager MFragmentManager MFragmentManager MFragmentManager MFragmentManager
MFragmentManager MFragmentManager MFragmentManager MFragmentManager MFragmentManager MFragmentManager MFragmentManager MFragmentManager MFragmentManager MFragmentManager