Write fragments and fragment graphs to render to the viewport

Introduction

A fragment is a procedure or function definition in a high level language. It has typed inputs and outputs, and executes some procedure on the inputs to produce the output(s).

You can write shading fragments, or you can write script fragments that execute a series of commands to set up parameters and states and clear or render to various targets.

Fragments may then be connected into fragment graphs. A fragment graph does not contain commands; instead, it instantiates a set of fragments and describes the connections between them.

A single script fragment or fragment graph can be stored in a .xml file.

A set of script fragment and fragment graph xml files are provided with the Maya installation at the bin/ScriptFragment directory of your installation directory. These fragment and fragment graphs are used to render to Viewport 2.0.

Default.xml is the main fragment graph that describes how Maya renders in Viewport 2.0. When this fragment graph is executed, the scene is displayed in the viewport.

It connects various fragments and fragment graphs such as Maya_3d_Renderer, which connects fragment graphs such as HoldOutPasses and Maya_PostEffects, which connects fragments and fragment graphs such as the mayaUIDrawPass and Maya_SSAO, and so forth.

These xml files serve as examples of how to write your own script fragment and fragment graphs for a fragment renderer.

When creating your own fragment renderer, you can re-use existing Maya fragments, and only write the xml for the fragments that you want to customize. For example, to create your own custom motion blur pass, you can write a motion blur fragment and combine it with existing Maya fragments.

One way to accomplish this would be to do as follows:

  1. Copy the existing Maya fragment/fragment graph .xml files into a new folder.
  2. Modify the fragment/fragment graph that you want to customize and rename it.

    Note: Directly modifying the files in bin/ScriptFragment is not recommended, as you may inadvertently corrupt Maya. It is therefore recommended that the fragment files first be copied into a new folder.

  3. Modify the main fragment graph (default.xml) to point to your modified fragment/fragment graph (from step 2), and give the main fragment graph a new name.

Some procedurals cannot be easily represented as script fragments, and are provided as hardcoded C++ procedural fragments with Maya. You can combine C++ procedural fragments with script fragments in your fragment graph.

**Tip:** To reproduce Maya's renderer, first initialize an MRenderOverride with a list of operations such as the following:

class FragmentRenderOverride(omr.MRenderOverride):

   def __init__(self, name):
       self.operatioIndex = 0
       self.operations =  [omr.MSceneRender("myRendererSameAsMaya", “default”),
                          omr.MHUDRender(),
                          omr.MPresentTarget("present")]

Where “default” is the name of the render fragment that Maya uses when not overridden. default.xml can be found in the bin/ScriptFragment folder of your Maya installation directory.

Default only draws the beauty pass and does not include the drawing of UI, shadow maps, HUD, and so forth that are part of MSceneRender.

API classes and interfaces

API entry points for creating a fragment renderer are as follows. See the viewRenderOverrideFromFragments plug-in in the Developer Kit and Create a fragment renderer plug-in example for example usage of these interfaces.

Fragment and fragment graph XML definition

Parts of the fragment description

Refer to maya_DepthPrePass.xml for an example.

All fragments are contained within the compound element fragment.

<fragment  uiName="maya_DepthPrePass" name="maya_DepthPrePass" type="sceneEffect" class="ScriptFragment" version="1.0" feature_level="30" >

The fragment definition also contains the following elements:

Parts of a fragment graph definition

As described earlier, various script fragments and fragment graphs can be connected to one another to form a single fragment graph.

Refer to Maya_PostEffects.xml for an example.

All fragments are contained within the compound element fragment_graph as follows:

<fragment_graph  name="Maya_PostEffects" ref="Maya_PostEffects" class="FragmentGraph" version="1.0" feature_level="0" >

Set the ref attribute to the internal name of the fragment graph.

  • You can set the name attribute to be the same as the internal name, or provide it with an external name.

  • The class attribute must be set to FragmentGraph.

  • The fragment_graph definition also contains the following elements: