Frame and draw contexts

Frame context

MFrameContext provides access to information for the current render frame. The information available is independent of the device state and hence is available outside of draw time.

This interface is generally available to all Viewport 2.0 interfaces. This includes access from within any interfaces that are using MUIDrawManager to draw transient UI (such as tools and manipulators).

One important advantage of using MFrameContext (and MDrawContext) is that the state is cached to avoiding recomputation. Data queries, in general, do not access the GPU device, which helps to avoid expensive pipeline stalls. For example, a plug-in may make a call to get the model view and projection matrices in OpenGL:

float tmp[4][4];
glGetFloatv(GL_MODELVIEW_MATRIX, &tmp[0][0]);
glGetFloatv(GL_PROJECTION_MATRIX, &tmp[0][0]);

The following calls can be made instead:

HWRender::MDrawContext& context;
MStatus status;
MMatrix transform = context.getMatrix(MHWRender::MDrawContext::kWorldViewMtx, &status);
MMatrix projection = context.getMatrix(MHWRender::MDrawContext::kProjectionMtx, &status);

Data that is accessible may update at different frequencies. Viewport size is an example of per frame data. A modeling matrix is an example of data per render item.

Another notable piece of available device information is the current color and depth targets (buffers) being used. This information can change on a per pass basis if multi-pass rendering is being performed. This pass information is only available at draw time and hence via the MDrawContext interface.

In addition to device state, various display mode information is available, such as: whether Maya is drawing in wireframe versus shaded mode, the current lighting mode, and global render settings (such as the current transparency algorithm being used). Even though this information is available at the per frame level, it would generally be accessed for self drawing interfaces that require an MDrawContext.

Draw context

MDrawContext is a class derived from MFrameContext and has additional methods and method overrides that provide device level state at draw time.

MDrawContext is almost solely geared towards interfaces that draw themselves and attempt to integrate with Maya by using the state to render in accordance with the internal renderer state. This includes MPxShaderOverride and MPxDrawOverride and MUserRenderOperations used for MRenderOverrides.

The state manager (MStateManager) is only accessible from this class, because only when an MDrawContext is active can device state be modified.

Additional semantic information is provided in the form of a “pass context” (MPassContext). Currently an identifier for a pass and a list of semantics can be queried. The pass identifier can be internally generated, or specified by a render loop override. See Render Loop Overrides for more information.

Items in the semantic list provide a progressively refined set of information as to the state or location within a pipeline. (The first element provides the broadest description and additional elements provide additional details about the previous element.) Some examples include:

• A semantic can indicate that drawing is occurring for shadow map creation. The plug-in can therefore make performance optimizations based on this indication.
• A set of semantics may indicate that a color pass is occurring and that transparent objects are being drawn with back-face culling enabled.
• A set of semantics may indicate that a color pass is occurring and that the UI elements for a surface are being drawn. Note that:
  • The drawing done by MPxDrawOverride is not categorized as an UI element and therefore would never be called within this semantic context.
  • MPxGeometryOverride can have render items drawn within this semantic context by specifying that it is to be drawn in "wireframe draw mode". See apiMeshGeometryOverride.cpp in the apiMeshShape Developer Kit example.

Lighting information (MLightParameterInformation) is available via MDrawContext. See Lighting Interfaces for more information.

Additional render target functionality is available at draw time, including the ability to make copies of the current color and depth targets, as well as access to specific textures used for certain passes. For example, the textures used for depth peeling are available.

The plug-in writer can decide on how integrated the plug-in should be with the active options enabled by Maya for rendering. The frame and draw context interfaces (MFrameContext and MDrawContext) allow for access to draw time “context” to determine any additional code required.

For example, to handle the display style returned by MFrameContext::getDisplayStyle():

• If x-ray mode is required by an MPxShaderOverride, then the state can be queried and the transparency method used for drawing adjusted. This is how x-ray mode is handled internally. For example, a different shader can be used while calling MPxShaderOverride::activateKey().
• The same approach can be used for handling two-sided lighting by adjusting the back-face lighting.

Features such as hardware fog can also be supported via shader adjustments based on the information returned from MFrameContext::getHwFogParameters().

Occasionally, shaders require access to the current color and/or depth render targets in order to bind as shader inputs. The methods MDrawContext::copyCurrentColorRenderTargetToTexture() and MDrawContext::copyCurrentDepthRenderTargetToTexture() are suitable for such applications.

Additional more complex integration scenarios such as light handling, custom geometry, and post effects are described under the Advanced Topics heading.