#include <MUIDrawManager.h>
Main interface for drawing basic UI drawables in Viewport 2.0 and Hardware Renderer 2.0.
The MUIDrawManager class provides a straight forward way to draw basic UI drawables like lines, icons, texts and other basic 2D/3D primitives.
MUIDrawManager is not designed for accessing at arbitrary time or arbitrary places. Access to the interface is restricted to certain methods on various API interfaces. An instance of MUIDrawManager is constructed and passed to these methods together with any required data and context information.
All drawing operations, including setting state like color and font size, must occur between calls to beginDrawable() and endDrawable(). For example, to draw a pair of red lines you would do the following:
The call to endDrawable() resets the draw state, so if you want to continue drawing in red later on you would have to repeat the call to setColor().
Note that draw operations may not take place immediately but instead be queued up for later execution during the draw phase.
To reduce draw overhead due to the small batch problem, Viewport 2.0 may batch the same type of UI drawables created by the same instance of MUIDrawManager, where the type means a combination of primitive type, internal shader, space dimension (2D/3D) and selection support. Some types are ineligible to be batched, e.g. line/triangle strip, textured drawing.
Public Member Functions | |
void | beginDrawable (Selectability selectability=kAutomatic, unsigned int selectionName=0) |
Resets all draw state, such as color and line style, to defaults and indicates the start of a sequence of drawing operations. More... | |
void | beginDrawable (unsigned int name, bool nameIsPickable) |
obsolete, please use the one with selectability and selection name parameters More... | |
void | endDrawable () |
Indicates the end of a sequence of drawing operations. More... | |
void | beginDrawInXray () |
The drawables to be drawn between calls to beginDrawInXray() and endDrawInXray() will display on the top of other geometries in the scene, as the depth test is disabled for these drawables. More... | |
void | endDrawInXray () |
Pair with "MUIDrawManager::beginDrawInXray()". | |
void | setColor (const MColor &color) |
Set the draw color. More... | |
void | setColorIndex (const short index) |
Set the color index for the later primitive and text drawing. More... | |
void | setPointSize (float value) |
Set the point size for the point drawing. More... | |
void | setLineWidth (float value) |
Set the line width for the primitive drawing (line, rect, box...) More... | |
void | setLineStyle (LineStyle style) |
Set the line style for the primitive drawing (line, rect, box...) More... | |
void | setLineStyle (unsigned int factor, unsigned short pattern) |
Set the dashed line pattern for the primitive drawing (line, rect, box...) More... | |
void | setPaintStyle (PaintStyle style) |
Set the paint style for filled primitive drawing. More... | |
unsigned int | depthPriority () const |
Get the current depth priority value for primitive drawing. More... | |
void | setDepthPriority (unsigned int priority) |
Set the depth priority for primitive drawing. More... | |
void | line (const MPoint &startPoint, const MPoint &endPoint) |
Draw a straight line between two points. More... | |
void | line2d (const MPoint &startPoint, const MPoint &endPoint) |
Draw a straight line between two points. More... | |
MStatus | lineList (const MPointArray &points, bool draw2D) |
Draw a series of line segments in 3D or 2D. More... | |
MStatus | lineStrip (const MPointArray &points, bool draw2D) |
Draw a series of connected line segments in 3D or 2D. More... | |
void | point (const MPoint &point) |
Draw a point. More... | |
void | point2d (const MPoint &point) |
Draw a point. More... | |
MStatus | points (const MPointArray &points, bool draw2D) |
Draw a series of points in 3D or 2D. More... | |
void | rect (const MPoint ¢er, const MVector &up, const MVector &normal, double scaleX, double scaleY, bool filled=false) |
Draw a rectangle. More... | |
void | rect2d (const MPoint ¢er, const MVector &up, double scaleX, double scaleY, bool filled=false) |
Draw a 2D rectangle on the screen. More... | |
void | sphere (const MPoint ¢er, double radius, bool filled=false) |
Draw a sphere. More... | |
void | circle (const MPoint ¢er, const MVector &normal, double radius, bool filled=false) |
Draw a circle. More... | |
void | circle2d (const MPoint ¢er, double radius, bool filled=false) |
Draw a 2D circle on the screen. More... | |
void | arc (const MPoint ¢er, const MVector &start, const MVector &end, const MVector &normal, double radius, bool filled=false) |
Draw an arc. More... | |
void | arc2d (const MPoint ¢er, const MVector &start, const MVector &end, double radius, bool filled=false) |
Draw a 2D arc on the screen. More... | |
void | mesh (Primitive mode, const MPointArray &position, const MVectorArray *normal=NULL, const MColorArray *color=NULL, const MUintArray *index=NULL, const MPointArray *texcoord=NULL) |
Draw custom geometric shapes from an array of vertices. More... | |
void | mesh2d (Primitive mode, const MPointArray &position, const MColorArray *color=NULL, const MUintArray *index=NULL, const MPointArray *texcoord=NULL) |
Draw custom 2d geometric shapes from an array of vertices. More... | |
void | cone (const MPoint &base, const MVector &direction, double radius, double height, bool filled=false) |
Draw a cone. More... | |
void | box (const MPoint ¢er, const MVector &up, const MVector &right, double scaleX=1.0, double scaleY=1.0, double scaleZ=1.0, bool filled=false) |
Draw a box. More... | |
void | setFontIncline (const int fontIncline) |
Set the incline of font to be used when drawing text. More... | |
void | setFontWeight (const int fontWeight) |
Set the weight of font to be used when drawing text. More... | |
void | setFontStretch (const int fontStretch) |
Set the stretch of font to be used when drawing text. More... | |
void | setFontLine (const int fontLine) |
Set the line of font to be used when drawing text. More... | |
void | setFontSize (const unsigned int fontSize) |
Set the size of font to be used when drawing text. More... | |
void | setFontName (const MString &faceName) |
Set the face name of font to be used when drawing text. More... | |
void | text (const MPoint &position, const MString &text, TextAlignment alignment=kLeft, const int *backgroundSize=NULL, const MColor *backgroundColor=NULL, bool dynamic=false) |
Draw a screen facing and horizontal aligned text in viewport 2.0. More... | |
void | text2d (const MPoint &position, const MString &text, TextAlignment alignment=kLeft, const int *backgroundSize=NULL, const MColor *backgroundColor=NULL, bool dynamic=false) |
Draw a text on the screen. More... | |
void | setTexture (MHWRender::MTexture *texture) |
Set the active texture to apply when drawing a mesh. More... | |
MStatus | setTextureSampler (MHWRender::MSamplerState::TextureFilter filter, MHWRender::MSamplerState::TextureAddress address) |
Set the filter and address mode used when applying a texture to a mesh. More... | |
MStatus | setTextureMask (MHWRender::MBlendState::ChannelMask mask) |
Set the channel mask to used when applying a texture to a mesh. More... | |
MStatus | icon (const MPoint &position, const MString &name, float scale) |
Draw an icon at a given 3d position. More... | |
Static Public Member Functions | |
static unsigned int | getFontList (MStringArray &list) |
Get the names of all font faces that are available on current system. More... | |
static unsigned int | getIconNames (MStringArray &names) |
Get list of icon names. More... | |
enum FontSize |
enum TextAlignment |
enum TextIncline |
Text incline.
Most of the font families support well for incline normal and italic. Oblique incline is not supported for most of the font families.
enum TextWeight |
Text weight.
Most of the font families support well for weight light and bold. Weight normal/demibold/black is not supported for most of the font families.
enum TextStretch |
Text stretch.
enum TextLine |
enum LineStyle |
enum PaintStyle |
enum Primitive |
enum Selectability |
void beginDrawable | ( | Selectability | selectability = kAutomatic , |
unsigned int | selectionName = 0 |
||
) |
Resets all draw state, such as color and line style, to defaults and indicates the start of a sequence of drawing operations.
All drawing operations must take place between calls to beginDrawable() and endDrawable().
Locators are by default selectable with the default kAutomatic parameter. Please specify kNonSelectable to mark it non-selectable. The second parameter is not relevant to locators.
Manipulators are by default non-selectable with the default kAutomatic parameter. Please specify kSelectable, and provide a selection name (an unsigned int) for it to be selectable. This name can be used with MPxManipulatorNode::glActiveName() and is device independent. The name is only used for selection and will be ignored in the regular draw pass.
[in] | selectability | Whether this drawable is selectable. Note the default value kAutomatic has different meaning for locators and manipulators. |
[in] | selectionName | Unique name (an unsigned int) of the component. This parameter is only relevant for manipulators. |
void beginDrawable | ( | unsigned int | name, |
bool | nameIsPickable | ||
) |
obsolete, please use the one with selectability and selection name parameters
This method is obsolete.
For manipulator drawing: resets all draw state, such as color and line style, to defaults and indicates the start of a sequence of drawing operations for the specified manipulator handle name. All drawing operations must take place between calls to beginDrawable() and endDrawable(). This name can be used with MPxManipulatorNode::glActiveName() and is device independant. The name is only used for selection and will be ignored in the regular draw pass.
[in] | name | Unique name (an unsigned int) of the component. |
[in] | nameIsPickable | If true, the component will be pickable |
void endDrawable | ( | ) |
Indicates the end of a sequence of drawing operations.
All internal drawing state, such as color and line style, are reset to defaults.
void beginDrawInXray | ( | ) |
The drawables to be drawn between calls to beginDrawInXray() and endDrawInXray() will display on the top of other geometries in the scene, as the depth test is disabled for these drawables.
These methods can be used to draw objects such as locators.
Limitations: Only the drawables meeting the following conditions will be affected by beginDrawInXray() and endDrawInXray(). 1. Created by the method "MUIDrawManager::mesh()"; 2. The first input parameter (primitive type) for "MUIDrawManager::mesh()" is one of "kTriangles", "kLines" and "kPoints". Any other drawables to be drawn between calls to beginDrawInXray() and endDrawInXray() will display as normal.
If several meshes are drawn between these two APIs, their draw order is reversed to the mesh() function call order. For example, in the above sample code: C will be drawn on top of B; B on top of A. If text calls are made after these two APIs, the text will be drawn on top. In above sample code: text D will be drawn on top of C.
void setColor | ( | const MColor & | color | ) |
Set the draw color.
This will remain in effect until the next call to setColor(), setColorIndex() or endDrawable().
For text this color will be used as the foreground color. Background color can be specified directly in the call to text().
Default: (0.7, 0.7, 0.7, 1)
[in] | color | The color which will affect the later drawing |
void setColorIndex | ( | const short | index | ) |
Set the color index for the later primitive and text drawing.
For default, it will use (0.7, 0.7, 0.7, 1) as default color.
[in] | index | Color index |
void setPointSize | ( | float | value | ) |
Set the point size for the point drawing.
[in] | value | Point size in pixels. |
void setLineWidth | ( | float | value | ) |
Set the line width for the primitive drawing (line, rect, box...)
[in] | value | Line width in pixels. |
void setLineStyle | ( | LineStyle | style | ) |
Set the line style for the primitive drawing (line, rect, box...)
[in] | style | Line style type. |
void setLineStyle | ( | unsigned int | factor, |
unsigned short | pattern | ||
) |
Set the dashed line pattern for the primitive drawing (line, rect, box...)
[in] | factor | a multiplier for each bit in the line stipple pattern. |
[in] | pattern | a pattern determines which fragments of a line will be drawn |
void setPaintStyle | ( | PaintStyle | style | ) |
Set the paint style for filled primitive drawing.
[in] | style | Paint style type. |
unsigned int depthPriority | ( | ) | const |
Get the current depth priority value for primitive drawing.
If the method failed to execute a value of 0 will be returned.
void setDepthPriority | ( | unsigned int | priority | ) |
Set the depth priority for primitive drawing.
The MRenderItem class lists some sample internal priorities which may be used.
[in] | priority | Depth priority. |
Draw a straight line between two points.
[in] | startPoint | The start point of the line. |
[in] | endPoint | The end point of the line. |
Draw a straight line between two points.
[in] | startPoint | The start point of the line, only x-y components(in pixels) are used. |
[in] | endPoint | The end point of the line, only x-y components(in pixels) are used. |
MStatus lineList | ( | const MPointArray & | points, |
bool | draw2D | ||
) |
Draw a series of line segments in 3D or 2D.
[in] | points | Array of point positions. Pairs of points are interpreted as line segments. If an odd number of points is specified then the last point will not be drawn, as it does not form a line segment. |
[in] | draw2D | Draw in 2D or 3D. |
MStatus lineStrip | ( | const MPointArray & | points, |
bool | draw2D | ||
) |
Draw a series of connected line segments in 3D or 2D.
[in] | points | Array of point positions. Each point in the array is connected to form a line strip. |
[in] | draw2D | Draw in 2D or 3D. |
void point | ( | const MPoint & | point | ) |
Draw a point.
[in] | point | Position of the point. |
void point2d | ( | const MPoint & | point | ) |
Draw a point.
[in] | point | Position of the point, only x-y components(in pixels) are used. |
MStatus points | ( | const MPointArray & | points, |
bool | draw2D | ||
) |
Draw a series of points in 3D or 2D.
[in] | points | Array of point positions. |
[in] | draw2D | Draw in 2D or 3D. |
void rect | ( | const MPoint & | center, |
const MVector & | up, | ||
const MVector & | normal, | ||
double | scaleX, | ||
double | scaleY, | ||
bool | filled = false |
||
) |
Draw a rectangle.
The rectangle is within the plane determined by a normal vector, and a up vector is given to determine the X-Y direction.
[in] | center | Center of the rectangle |
[in] | up | Up vector of the rectangle |
[in] | normal | Normal vector of the rectangle plane |
[in] | scaleX | Scale factor in X-direction |
[in] | scaleY | Scale factor in Y-direction |
[in] | filled | If true the rectangle will be filled otherwise it will just be drawn as an outline. |
void rect2d | ( | const MPoint & | center, |
const MVector & | up, | ||
double | scaleX, | ||
double | scaleY, | ||
bool | filled = false |
||
) |
Draw a 2D rectangle on the screen.
The rectangle is always facing the camera, and a up vector is given to determine the X-Y direction.
[in] | center | Center of the rectangle, only x-y components(in pixels) are used. |
[in] | up | Up vector of the rectangle, only x-y components are used. |
[in] | scaleX | Scale factor in X-direction |
[in] | scaleY | Scale factor in Y-direction |
[in] | filled | If true the rectangle will be filled otherwise it will just be drawn as an outline. |
void sphere | ( | const MPoint & | center, |
double | radius, | ||
bool | filled = false |
||
) |
Draw a sphere.
[in] | center | Center of the sphere. |
[in] | radius | Radius of the sphere. |
[in] | filled | If true the sphere will be filled otherwise it will just be drawn as a wireframe. |
Draw a circle.
The circle is drawn within the plane determined by a normal vector.
[in] | center | Center of the circle |
[in] | normal | Normal vector of the circle plane |
[in] | radius | Radius of the circle |
[in] | filled | If true the circle will be filled otherwise it will just be drawn as an outline. |
void circle2d | ( | const MPoint & | center, |
double | radius, | ||
bool | filled = false |
||
) |
Draw a 2D circle on the screen.
The circle is always facing the camera.
[in] | center | Center of the circle, only x-y components(in pixels) are used. |
[in] | radius | Radius(in pixels) of the circle |
[in] | filled | If true the circle will be filled otherwise it will just be drawn as an outline. |
void arc | ( | const MPoint & | center, |
const MVector & | start, | ||
const MVector & | end, | ||
const MVector & | normal, | ||
double | radius, | ||
bool | filled = false |
||
) |
Draw an arc.
The arc is within the plane determined by a normal vector. The arc sweeps in CCW from the vector that is the projection of the given start vector onto the arc plane, and ends at the vector that is the projection of the given end vector onto the arc plane.
[in] | center | Center of the arc |
[in] | start | Start vector, its projection onto the arc plane is the start of the arc. |
[in] | end | End vector, its projection onto the arc plane is the end of the arc. |
[in] | normal | Normal vector of the arc plane. |
[in] | radius | Radius of the arc. |
[in] | filled | If true the arc will be filled otherwise it will just be drawn as an outline. |
void arc2d | ( | const MPoint & | center, |
const MVector & | start, | ||
const MVector & | end, | ||
double | radius, | ||
bool | filled = false |
||
) |
Draw a 2D arc on the screen.
The arc is always facing the camera. The arc sweeps in CCW from the start vector and ends at the end vector.
[in] | center | Center of the arc, only x-y components(in pixels) are used |
[in] | start | Start vector, only x-y components are used. |
[in] | end | End vector, only x-y components are used. |
[in] | radius | Radius(in pixels) of the arc. |
[in] | filled | If true the arc will be filled otherwise it will just be drawn as an outline. |
void mesh | ( | Primitive | mode, |
const MPointArray & | position, | ||
const MVectorArray * | normal = NULL , |
||
const MColorArray * | color = NULL , |
||
const MUintArray * | index = NULL , |
||
const MPointArray * | texcoord = NULL |
||
) |
Draw custom geometric shapes from an array of vertices.
If the optional normal or color arrays are provided they must contain a single value per element of the positions array (i.e. all three arrays must be the same length).
The optional index array specifies the order in which the vertex positions (and their corresponding normals and colors) should be drawn. Vertices can be reused by having their indices appear multiple times, so the index array may be longer (or shorter) than the other three arrays.
If the index array is not provided then the vertices will be drawn in the order in which they appear in the positions array.
[in] | mode | Primitive mode, e.g., point list, line list, etc. |
[in] | position | List of the vertex positions. |
[in] | normal | List of the vertex normals. |
[in] | color | List of the vertex colors. |
[in] | index | List of the vertex indices. |
[in] | texcoord | List of the vertex texture coordinates. |
void mesh2d | ( | Primitive | mode, |
const MPointArray & | position, | ||
const MColorArray * | color = NULL , |
||
const MUintArray * | index = NULL , |
||
const MPointArray * | texcoord = NULL |
||
) |
Draw custom 2d geometric shapes from an array of vertices.
If the optional color arrays are provided they must contain a single value per element of the positions array (i.e. both arrays must be the same length).
The optional index array specifies the order in which the vertex positions (and their corresponding colors) should be drawn. Vertices can be reused by having their indices appear multiple times, so the index array may be longer (or shorter) than the other two arrays.
If the index array is not provided then the vertices will be drawn in the order in which they appear in the positions array.
[in] | mode | Primitive mode, e.g., point list, line list, etc. |
[in] | position | List of the vertex positions, only x-y components of the point are used. |
[in] | color | List of the vertex colors. |
[in] | index | List of the vertex indices. |
[in] | texcoord | List of the vertex texture coordinates. |
void cone | ( | const MPoint & | base, |
const MVector & | direction, | ||
double | radius, | ||
double | height, | ||
bool | filled = false |
||
) |
Draw a cone.
[in] | base | Base position for the cone |
[in] | direction | The cone's tip will point in this direction. |
[in] | radius | Radius of the cone |
[in] | height | Height of the cone |
[in] | filled | If true the cone will be filled otherwise it will just be drawn as an outline. |
void box | ( | const MPoint & | center, |
const MVector & | up, | ||
const MVector & | right, | ||
double | scaleX = 1.0 , |
||
double | scaleY = 1.0 , |
||
double | scaleZ = 1.0 , |
||
bool | filled = false |
||
) |
Draw a box.
[in] | center | Center position for the box |
[in] | up | The top of the box will be facing this direction. |
[in] | right | The side of the box will be facing this direction. |
[in] | scaleX | X size of the box |
[in] | scaleY | Y size of the box |
[in] | scaleZ | Z size of the box |
[in] | filled | If true the box will be filled otherwise it will just be drawn as an outline. |
|
static |
Get the names of all font faces that are available on current system.
The names can then be used for MUIDrawManager::setFontName().
[out] | list | The list to populate font names |
void setFontIncline | ( | const int | fontIncline | ) |
Set the incline of font to be used when drawing text.
[in] | fontIncline | The font incline to use. |
void setFontWeight | ( | const int | fontWeight | ) |
Set the weight of font to be used when drawing text.
[in] | fontWeight | The font weight to use. |
void setFontStretch | ( | const int | fontStretch | ) |
Set the stretch of font to be used when drawing text.
[in] | fontStretch | The font stretch to use. |
void setFontLine | ( | const int | fontLine | ) |
Set the line of font to be used when drawing text.
[in] | fontLine | The font line to use. |
void setFontSize | ( | const unsigned int | fontSize | ) |
Set the size of font to be used when drawing text.
[in] | fontSize | The font height(in pixel) to use. |
void setFontName | ( | const MString & | faceName | ) |
Set the face name of font to be used when drawing text.
[in] | faceName | The font face name(case-insensitive) to use, All system font faces are supported. "helvetica" is the default for invalid input. |
void text | ( | const MPoint & | position, |
const MString & | text, | ||
TextAlignment | alignment = kLeft , |
||
const int * | backgroundSize = NULL , |
||
const MColor * | backgroundColor = NULL , |
||
bool | dynamic = false |
||
) |
Draw a screen facing and horizontal aligned text in viewport 2.0.
It has a fixed size in screen space.
[in] | position | Position of the text to be drawn, it is 3d object space. |
[in] | text | Content of the text string. |
[in] | alignment | Alignment of the text. "kLeft", background box's left bottom will be located at "position". In width direction, text area will be aligned to the left side of background. In height direction, text are will be aligned in the middle of background. |
"kCenter", background box' center bottom will be located at "position". text area's center and background box's center will be the same point.
"kRight", background box's right bottom will be located at "position". In width direction, text area will be aligned to the right side of background. In height direction, text are will be aligned in the middle of background.
[in] | backgroundSize | The background box size of the text. Default is NULL, in this case there will be no background, just shows the text. If it is specified with smaller size than text, the text will be clipped. It is a int array with size 2, like "int backgroundSize[] = { width, height } " Size unit is the screen pixel. |
[in] | backgroundColor | The color of the background, it can be transparent. If NULL is passed, background will be fully transparent. |
[in] | dynamic | This is mostly used for performance. If the text draw is not changed frequently, we can leave it as default value false. If the text draw is changing very often like it is showing some dynamic numbers, in this case making dynamic true will give better performance. |
void text2d | ( | const MPoint & | position, |
const MString & | text, | ||
TextAlignment | alignment = kLeft , |
||
const int * | backgroundSize = NULL , |
||
const MColor * | backgroundColor = NULL , |
||
bool | dynamic = false |
||
) |
Draw a text on the screen.
[in] | position | Position of the text to be drawn, it is in screen space, only x-y components are used. |
[in] | text | Content of the text string. |
[in] | alignment | Alignment of the text. "kLeft", background box's left bottom will be located at "position". In width direction, text area will be aligned to the left side of background. In height direction, text are will be aligned in the middle of background. |
"kCenter", background box' center bottom will be located at "position". text area's center and background box's center will be the same point.
"kRight", background box's right bottom will be located at "position". In width direction, text area will be aligned to the right side of background. In height direction, text are will be aligned in the middle of background.
[in] | backgroundSize | The background box size(in pixels) of the text. Default is NULL, in this case there will be no background, just shows the text. If it is specified with smaller size than text, the text will be clipped. It is a int array with size 2, like "int backgroundSize[] = { width, height } " Size unit is the screen pixel. |
[in] | backgroundColor | The color of the background, it can be transparent. If NULL is passed, background will be fully transparent. |
[in] | dynamic | This is mostly used for performance. If the text draw is not changed frequently, we can leave it as default value false. If the text draw is changing very often like it is showing some dynamic numbers, in this case making dynamic true will give better performance. |
void setTexture | ( | MHWRender::MTexture * | texture | ) |
Set the active texture to apply when drawing a mesh.
This will remain in effect until the next call to setTexture();
[in] | texture | The texture which will affect the later drawing |
MStatus setTextureSampler | ( | MHWRender::MSamplerState::TextureFilter | filter, |
MHWRender::MSamplerState::TextureAddress | address | ||
) |
Set the filter and address mode used when applying a texture to a mesh.
This will remain in effect until the next call to setTextureSampler();
[in] | filter | The filter which will affect the later drawing. Currently, only kMinMagMipPoint and kMinMagMipLinear are supported. |
[in] | address | The canonical range which will affect the later drawing. Currently, only kTexWrap and kTexClamp are supported. |
MStatus setTextureMask | ( | MHWRender::MBlendState::ChannelMask | mask | ) |
Set the channel mask to used when applying a texture to a mesh.
This will remain in effect until the next call to setTextureMask();
[in] | mask | The channel mask which will affect the later drawing. Currently, only kRGBAChannels, kRGBChannels and kAlphaChannel are supported. |
Draw an icon at a given 3d position.
[in] | position | 3d location of the icon. |
[in] | name | The name of an icon. The list of available icon names can be found using the MUIDrawManager::getIconNames() method. |
[in] | scale | Uniform scaling factor for the icon |
|
static |
Get list of icon names.
The names can be used for drawing icons using the MUIDrawManager::icon() method.
[out] | names | List of icon names |