The MUIDrawManager class provides a straight forward way for API users to draw basic UI elements such as: lines, circles, arcs, icons, and text.
While previous APIs allowed for what is commonly called immediate mode drawing, MUIDrawManager exposes a different type of interaction closer to retained mode drawing. The logic consists of queuing items to draw “drawables” into a “drawable” list.
Each drawable automatically uses the appropriate shader instance and geometry based on the type of draw item. For example, text has an appropriate “text shader”. This knowledge is hidden from the user for simplicity.
The manager checks each drawable and places the drawables into lists which are drawn at different times within the render pipeline. Currently, control over list placement is not exposed in MUIDrawManager. Users of MUIDrawManager should be aware that there are explicit properties depending on the list that the drawable is drawn from, and that the interface from which the MUIDrawManager is used generally determines list placement. For example, queuing drawables from the manager provided via the manipulator interface means that drawables are not depth tested nor written to depth.
MUIDrawManager is not designed for accessing at arbitrary time or at arbitrary places. Access to the interface is thus restricted to a few methods on various API interfaces. Any data and context information management is prepared by the manager and passed to the caller as appropriate. Examples of information that may be passed back to the caller include: DAG path, pass information, and view information. For example, some drawables like heads-up-display elements may need to scale with respect to the viewport rectangle.
The MUIDrawManager is owned by the renderer and cannot be explicitly constructed.
The following interfaces currently support MUIDrawManager:
MPxDrawOverride and MPxGeometryOverride have identical methods with signatures that can be overridden to use MUIDrawManager.
The method hasUIDrawables() can be overridden to return true to indicate that the user wishes to add drawables via the addUIDrawables() method. A false value means to skip calling addUIDrawables().
The method addUIDrawables() is the main method which allows access to MUIDrawManager. Drawables that are queued here can be thought of as additional render items that can be filtered or bucketed into the appropriate render item list in the pipeline.
For manipulators MPxManipContainer and MPxManipulatorNode, two override methods provide interaction with MUIDrawManager:
These methods are only called when the current renderer is Viewport 2.0.
preDrawUI() is always called before drawUI(). preDrawUI() allows the user to perform draw data preparation. Then, drawUI() uses the passed in MUIDrawManager to draw with the draw data. The drawables queued are rendered after a draw of scene DAG objects, and before the drawing of the HUD (heads-up-display).
For tool contexts, MPxContext has the following methods available:
These methods are only called when the current renderer is Viewport 2.0.
They can be thought of as the Viewport 2.0 version of doPress/doRelease/doDrag/doHold and doEnterRegion. Plug-ins can override these functions to implement the equivalent behavior to that of the default viewport.
MUIDrawManager can also be used for render overrides. For MUserRenderOperation and MHUDRender, two methods may be used:
For MSceneRender, three functions may be used:
Override these functions to define the drawables to be drawn during the user, HUD, pre-scene, or post-scene render operations.
As mentioned, MUIDrawManager can be thought of having retained mode drawing. As such, certain states can be set which are applied to the drawables queued after a given state is set.
To control line display attributes, possible line state controls include setting the width and line style.
sets line style from a set of pre-defined line styles. These include solid, short dotted, short dashed, dashed, and dotted. For greater control, the method:
For controlling primitive paint style, setPaintStyle() can be used to allow flat-shaded, stippled, or shaded drawing to be applied. Shaded drawing uses an internal fixed material.
For controlling text, size can be set as a retained mode state (setFontSize()).
MUIDrawManager supports both 3D and 2D drawable interfaces, and 2D interfaces are generally denoted with "2d" appended to the name of the method. For example line() is for 3D drawable, and line2d() is for a 2D drawable.
It should be noted that for 2D drawables, only x and y components of a 3d position or vector are used, and the unit for drawing is in screen pixels.