Write script fragments and fragment graphs to control render passes in the viewport

Introduction

Maya's viewport relies on a system of fragments (scripts serialized in an XML format) of two different types: * Shade fragments wrap code fragments in a real-time shading language (GLSL, HLSL or Cg) together with their input and output definitions in XML. Such fragments are connected into nested shade fragment graphs which are ultimately compiled by Maya into final shaders executed by the GPU. * Script fragments define sequences of imperative script commands which are interpreted by Maya at runtime and ultimately result in GPU state changes and draw calls. Script fragments can also be connected into nested script fragment graphs which determine the high-level control flow.

A set of script fragment and fragment graph XML files is provided with the Maya installation in the bin/ScriptFragment subdirectory of your installation directory.

In Maya 2020 and earlier releases, default.xml was the top-level fragment graph that defined the default implementation of the beauty pass (including scene and post-effect passes but excluding shadow map and various UI and HUD passes). It connected various fragments and fragment graphs such as Maya_3d_Renderer.xml, which connected fragment graphs such as HoldOutPasses.xml and Maya_PostEffects.xml, which in turn connected fragments and fragment graphs such as mayaUIDrawPass.xml and Maya_SSAO.xml, and so forth. Some of the fragments referenced in these graphs are implemented as hardcoded C++ procedural fragments.

In newer versions of Maya, default.xml and its dependencies are still shipped with Maya but the default beauty pass implementation has been redesigned and can no longer be described by a single script fragment graph.

In an MRenderOverride plug-in, the beauty pass is represented with the MSceneRender operation. When constructing the MSceneRender, the fragmentName parameter can be used to provide the name of a custom script fragment or fragment graph to override the default Maya beauty pass implementation, for example:

class FragmentRenderOverride(omr.MRenderOverride):

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

You can use the XML files shipped in the bin/ScriptFragment directory as a reference when writing your custom fragment however modifying files in that directory directly is not recommended, to avoid corrupting Maya.

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: