Basic Viewport 2.0 pipeline sequencing


This section covers the basic sequencing of the Viewport 2.0 pipeline when rendering a 3d representation of the scene to the viewport or image on disk. It is within this sequence where various render items or UI drawables are handled.

The assumption is that render items and UI drawables have gone through the renderer’s internal consolidation, filtering and categorization mechanism to produce lists of render items or lists of UI drawables. An example would be a list of opaque shaded render items.

Certain lists may be sorted based on a given criteria. For example, a transparent render item list may be sorted by distance to the current camera, while material items may be sorted by shader uniqueness (key). When unsorted, the ordering in the list does not necessarily reflect the ordering that render items are stored on an override, or any Maya scene object ordering.

The finest granularity used to describe a sequence is called a logical operation, to match the nomenclature used for Viewport 2.0 render overrides (MRenderOverride). Even for a complex internal render graph, the assumption is that it can be broken down into a linear sequence of operations.

At the highest level, a sequence is broken down into frames, where a frame performs rendering in order to produce the contents of an off-screen color and depth output target. The targets that are used to present to an interactive viewport or save to disk image are called final targets.

Where applicable, an indication as to whether a pass semantic is used is shown in the description of the internal sequencing. Operations that specify a unique pass semantic are denoted using the characters (P).

Rendering for a frame is broken down into roughly three parts: pre-scene rendering, scene rendering, and post-scene rendering. The main conditional branching for UI items is dependant on whether post-effects have been enabled. This generally entails UI items being moved to lists that draw after post-effects have been applied.


The following is a snapshot of a typical frame render, and the actual sequencing may deviate from what is presented here depending on the render graph produced. Also, the categorizations of various items are a reflection of the current implementation and can also deviate if the implementation changes.

Pre-scene rendering

Within the pre-scene rendering phase, the basic operations include:

Scene rendering

Scene rendering, which can also be thought of as representing the beauty pass, renders using the following operations:

Post-scene rendering

Post-scene rendering includes operations for 2D post effects, and any additional UI drawing that should not participate when any 2D post effect is enabled. By default, certain items do not take part in post effects. Otherwise, the option to override the MRenderItem::setExcludedFromPostEffects() method is available.

Transparency rendering

The process of rendering transparent items differs based on the transparency algorithm chosen, and the categorization of the item.

The basic logic is:

Particle rendering

Different type of items can be created for particle systems, since the object can specify different display variations. Points and streaks, for the most part, are added to the opaque or transparent render item lists and the transparent bitmap lists. Any numeric will also end up in x-ray lists. (Note that stock numeric shaders acquired from MShaderManager also end up in x-ray lists.). Sphere and blobby items will end up on opaque or opaque UI lists (latter for wireframe). Cloud and tube will end up in transparent or opaque UI lists (the latter for wireframe).

Shadow pass rendering

Any shadow maps used for 3d scene rendering are updated during pre-scene rendering as needed. Only render items (not UI drawables) are considered for shadow map creation, with the following sequencing:

Image Plane rendering

Image plane rendering can create opaque or transparent objects, but they are categorized to not take part in post-effects and hence are always added to non post-effect lists.

API UI Draw Manager

MUIDrawManager is the API interface for handling various UI drawing, and is available from various API interfaces. Both API as well as internal drawing can produce different drawables based on the class methods used.

For object override and render override drawing, the following general mapping occurs:


  • All items are added to the manipulator item list, except for 2D text which will be added to the on top list.

  • footPrintManip example: The Stretch Me! and Stretch Me 2D! text is drawn on top of the footprint locator (MPxDrawOverride) text (x-ray) and uiDrawManager (MPxDrawOverride ) sample text (transparent UI 2D).

Tool context drawing

  • All items will be added to the 2D or 3D overlay item list (see below).

UV Editor

  • 2d meshes that are used for drawing the background texture are added as items to the pre UI list.

API Overlay Rendering

Tool context drawing all reside within the pipeline operations for drawing overlays. This means items are added to the 2D or 3D overlay lists. This applies for 3d viewports as well as the UV Editor. 3D scene elements are generally not redrawn when drawing overlays.

API UV Editor Rendering

The background texture rendering can be supplied by a shader override (MPxShaderOverride). In this case, the drawing is done via MUIDrawManager and is always drawn before any object UI, or 2D manipulators.

API Object Rendering


MPxDrawOverride drawing is, by default, categorized as an opaque render item, but never participates in any post effects, nor transparency, although it can participate in shadow map creation.

Developer kit example: rawFootPrintNode

  • 1 internally defined item is added to the opaque list

  • 1 item is added to the x-ray list (text via MUIDrawManager).

MPxGeometryOverride and MPxSubSceneOverride

Render items created by MPxGeometryOverride and MPxSubSceneOverride may or may not be categorized as opaque UI or non UI render items, depending on the properties set per item.

Developer kit example: footPrintNode_GeometryOverrride (MPxGeometryOverride)

  • Since a RenderItemType of MHWRender::MRenderItem::DecorationItem is used for all custom render items, they are categorized as opaque UI items.

  • Up to 4 explicitly defined items (2 for wireframe, and 2 for filled) may be added to lists when unconsolidated, and wireframe and shading draw modes are both enabled.

  • The minimum is 1 for wireframe or 1 for filled when consolidation is enabled, and only one draw mode is enabled.

Developer kit example: apiMeshShape (MPxGeometryOverride)

  • 6 opaque UI render items (wire, dormant vertices, active vertices, face centers, active wire, filled faces). They have a RenderItemType of MHWRender::MRenderItem::DecorationItem.
  • 1 opaque render item due to internal shader assignment. RenderItemType is MHWRender::MRenderItem::MaterialSceneItem. Therefore, it will participate in post-effects, for instance.

Developer kit example: apiMeshShape (MPxSubSceneOverride)

There are 6 transform instances of the same object in this example.

For a single object, there is 1 item added to the opaque list (shaded). This item will also be added to the post-effects list.

Because the subscene override uses hardware instancing; therefore, in total, there is only 1 item added. Each item will use hardware instance drawing with a different world space transform for each instance.

When an instance of an object is selected:

1 wireframe item is added to the opaque UI list.

When vertices are displayed, there is 1 additional item added to the opaque UI list.

Wireframe-on-shaded results in 2 UI items being added: One for dormant and 1 for active wireframe.

Two items are also added for bounding box. They have a RenderType of MHWRender:: MRenderItem::NonMaterialSceneItem, which means they are not considered as scene items but are still categorized and added to the opaque UI list.

Wireframe, vertices and bounding box items are all added to the non-post effects list.


MPxShaderOverride, MPxSurfaceShadingNodeOverride and internal Maya assigned shaders always produce opaque or transparent non-UI render items. As such, they are added to the post-effects lists, and are also rendered for shadow map passes.

As documented in the MPxShaderOverride C++ API Reference documentation, the plug-in instance will, by default, only be called to draw in the main color pass unless overridden. For example, the normal-depth pass for SSAO will not by default call back to the plug-in.

MPxSurfaceShadingNodeOverride only provides a single shader implementation, which in turn is used for the main color pass.

Item list tracking

It is possible to obtain trace information regarding the non-empty lists that are available for a regular 3d beauty render, as well as overlay rendering for 3d viewports. The command:

ogs -traceRenderPipeline true;

can be used to send debug output to the Script Editor in interactive mode, or to stderr in command line mode.

For example, tracing a sphere drawn filled with wireframe may produce output as follows:

// -- VP2 Rendering [modelPanel4] [3d Beauty Render] // 
// Count for list: [Opaque UI] = 1 // 
// Count for list: [Opaque] = 1 // 
// Count for list: [Post Effect] = 1 // 
// Count for list: [Non Post Effect] = 1 //

For context, the rendering destination (same value as returned by MFrameContext::renderingDestination()) is given, along with the render performed. Here, the name 3d Beauty Render is returned to indicate an internal render.

The results indicate that 1 opaque UI item (wireframe), and 1 opaque item (filled) have been categorized. In addition, the filled item is queued for post-effect drawing, and the wireframe is queued for non post-effect drawing. The fact that they are available does not necessarily mean that the list will be rendered, as this would be dependent on whether any post-effects are enabled.

The lists are not necessarily given in the order that they will be used, and each list is only given once per scene render. The sequencing in this section should be referenced to determine where a given list could be drawn.

Multiple scene renders hence show the items for each render. For example, stereo rendering could appear as follows:

// -- VP2 Trace[StereoPanel][stereoOverrideVP2] // 
// Count for list: [Opaque UI] = 18 // 
// Count for list: [Opaque] = 34 // 
// Count for list: [Post Effect] = 33 // 
// Count for list: [Non Post Effect] = 19 // 
// Count for list: [Opaque UI] = 18 // 
// Count for list: [Opaque] = 34 // 
// Count for list: [Post Effect] = 33 // 
// Count for list: [Non Post Effect] = 19 // 
// Count for list: [HUD] = 1 //

The second to fifth line represent one scene draw and the sixth to ninth represent another.

Note that when a render override (MRenderOverride) is active for the trace, then the UI name of the override is provided as part of the trace. In this case, the stereoOverrideVP2 override name is shown.

In another example, when tracing the viewOverrideSimple plug-in, the Simple VP2 Override name is given:

// -- VP2 Trace[modelPanel1][Simple VP2 Override] // 
// Count for list: [Opaque UI] = 17 // 
// Count for list: [Pre-Opaque UI] = 2 // 
// Count for list: [Opaque] = 34 // 
// Count for list: [Post Effect] = 33 // 
// Count for list: [Non Post Effect] = 18 // 
// Count for list: [Orthographic On-Top UI] = 5 // 
// Count for list: [HUD] = 1 //