M3dView Class Reference

#include <M3dView.h>

Class Description

A 3-D view.

M3dView provides methods for working with 3D model views. 3D views are based on OpenGL drawing areas.

Maya can operate in two different color modes, RGBA and color index. Color index mode is used to increase performance when shading is not required. Drawing in color index mode is more complicated, but this class provides methods to simplify color selection.

Maya has four color tables that can be used in RGBA, and that must be used in color index mode. These four color tables represent four sets of bit planes that are independent of each other. So, for example, it is possible to clear all active objects from the display and redraw them without redrawing the dormant and templated objects. The active and dormant color tables contain the same colors, but use different bitplanes.

The extra performance of color index mode comes at the cost of a limited number of colors. If this restriction causes difficulty, then it is possible for the user to force all displays into RGBA mode where any color may be used.

When an object is affected by another in the scene, it is drawn in a magenta colour by default. This is denoted in the DisplayStatus enum by kActiveAffected. These objects are drawn in the active planes even though they are dormant for performance reasons.

Examples:

Public Types
enum	DisplayStyle {   kBoundingBox, kFlatShaded, kGouraudShaded, kWireFrame,   kPoints }
	Display styles for a 3D view. More...
enum	DisplayStatus {   kActive, kLive, kDormant, kInvisible,   kHilite, kTemplate, kActiveTemplate, kActiveComponent,   kLead, kIntermediateObject, kActiveAffected, kNoStatus }
	Drawing modes for individual objects. More...
enum	ColorTable { kActiveColors = kActive, kDormantColors = kDormant, kTemplateColor = kTemplate, kBackgroundColor }
	Reference to color palettes. More...
enum	TextPosition { kLeft, kCenter, kRight }
	Alignment values when drawing text. More...
enum	DisplayObjects {   kDisplayEverything = ~0, kDisplayNurbsCurves = 1 << 0, kDisplayNurbsSurfaces = 1 << 1, kDisplayMeshes = 1 << 2,   kDisplayPlanes = 1 << 3, kDisplayLights = 1 << 4, kDisplayCameras = 1 << 5, kDisplayJoints = 1 << 6,   kDisplayIkHandles = 1 << 7, kDisplayDeformers = 1 << 8, kDisplayDynamics = 1 << 9, kDisplayParticleInstancers = 1 << 10,   kDisplayLocators = 1 << 11, kDisplayDimensions = 1 << 12, kDisplaySelectHandles = 1 << 13, kDisplayPivots = 1 << 14,   kDisplayTextures = 1 << 15, kDisplayGrid = 1 << 16, kDisplayCVs = 1 << 17, kDisplayHulls = 1 << 18,   kDisplayStrokes = 1 << 19, kDisplaySubdivSurfaces = 1 << 20, kDisplayFluids = 1 << 21, kDisplayFollicles = 1 << 22,   kDisplayHairSystems = 1 << 23, kDisplayImagePlane = 1 << 24, kDisplayNCloths = 1 << 25, kDisplayNRigids = 1 << 26,   kDisplayDynamicConstraints = 1 << 27, kDisplayManipulators = 1 << 28, kDisplayNParticles = 1 << 29, kExcludeMotionTrails = 1<<(30),   kExcludePluginShapes = 1<<(31) }
	Display modes Bit masks used in combination with the return value of the dirtyMask() method to determine which portions of the geometry are dirty. More...
enum	LightingMode {   kLightAll, kLightSelected, kLightActive, kLightDefault,   kUnused1, kLightNone }
	Lighting mode used in this 3D view. More...
enum	RendererName { kDefaultQualityRenderer, kHighQualityRenderer, kViewport2Renderer, kExternalRenderer }
	Current hardware rendering engine used in this view. More...
enum	DepthBufferFormat { kDepth_8 = 0, kDepth_Float }
	Possible depth buffer formats to read into. More...
enum	LineStipplePattern { kStippleNone, kStippleDashed }
	Line stipple pattern. More...

Public Member Functions
MStatus	makeSharedContextCurrent ()
	makes the shared context current. More...
MGLContext	display (MStatus *ReturnStatus=NULL)
	Mac OS X and Windows. More...
void	getScreenPosition (int &x, int &y, MStatus *ReturnStatus=NULL) const
	Returns the current position of this view window in screen coordinates. More...
QWidget *	widget (MStatus *ReturnStatus=NULL) const
	Returns the view's Qt widget. More...
MNativeWindowHdl	window (MStatus *ReturnStatus=NULL)
	Returns the native window for this view. More...
int	portWidth (MStatus *ReturnStatus=NULL)
	Returns the width of the current viewport. More...
int	portHeight (MStatus *ReturnStatus=NULL)
	Returns the height of the current viewport. More...
bool	isVisible (MStatus *ReturnStatus=NULL)
	Returns true if this viewport is visible. More...
int	playblastPortWidth (MStatus *ReturnStatus=NULL)
	Returns the port width of current playblast. More...
int	playblastPortHeight (MStatus *ReturnStatus=NULL)
	Returns the port height of current playblast. More...
MStatus	pushViewport (unsigned int x, unsigned int y, unsigned int width, unsigned int height)
	Set the current viewport dimensions. More...
MStatus	popViewport ()
	Pop the current viewport off of the viewport stack. More...
MStatus	viewport (unsigned int &x, unsigned int &y, unsigned int &width, unsigned int &height) const
	Get the current viewport dimensions. More...
MStatus	beginGL ()
	This method is obsolete. More...
MStatus	endGL ()
	This method is obsolete. More...
void	beginSelect (GLuint *buffer=NULL, GLsizei size=0)
	Start selecting. More...
GLint	endSelect ()
	Finish a selection sequence. More...
bool	selectMode () const
	Tells if this M3dView is in selection mode. More...
bool	textureMode () const
	Tells if this M3dView is in texture mode. More...
void	loadName (GLuint name)
	Replace the top of the name stack with the given name. More...
void	pushName (GLuint name)
	Push a new name on the name stack. More...
void	popName ()
	Removes the top of the name stack. More...
void	initNames ()
	Reset the name stack. More...
MStatus	beginXorDrawing (bool drawOrthographic=true, bool disableDepthTesting=true, float lineWidth=1.0f, LineStipplePattern stipplePattern=kStippleNone, const MColor &lineColor=MColor(1, 1, 1))
	Setup the context for exclusive-or (XOR) drawing. More...
MStatus	endXorDrawing ()
	Reset the context to non-exclusive-or (non-XOR) screen drawing. More...
MStatus	setDrawColor (unsigned int index, ColorTable table=kActiveColors)
	This method is obsolete. More...
MStatus	setDrawColor (const MColor &color)
	This method is obsolete. More...
MStatus	setDrawColorAndAlpha (const MColor &color)
	This method is obsolete. More...
unsigned int	numDormantColors (MStatus *ReturnStatus=NULL)
	Returns the number of dormant object colors in the internal application color table. More...
unsigned int	numActiveColors (MStatus *ReturnStatus=NULL)
	Returns the number of active object colors in the internal application color table. More...
unsigned int	numUserDefinedColors (MStatus *ReturnStatus=NULL)
	Returns the number of user defined colors in the internal application color table. More...
MStatus	setUserDefinedColor (unsigned int index, const MColor &color)
	Sets the user defined color at the given index. More...
unsigned int	userDefinedColorIndex (unsigned int index, MStatus *ReturnStatus=NULL)
	Returns the index for the given user-defined color. More...
MColor	colorAtIndex (unsigned int index, ColorTable table=kActiveColors, MStatus *ReturnStatus=NULL)
	Returns the value of the color at the given index in the application's color table. More...
MStatus	getColorIndexAndTable (unsigned int glindex, unsigned int &index, ColorTable &table) const
	Returns the color table and index representing the given OpenGL color-index value. More...
MStatus	colorMask (bool &r, bool &g, bool &b, bool &a)
	This method is obsolete. More...
MStatus	setColorMask (bool r, bool g, bool b, bool a)
	This method is obsolete. More...
MStatus	drawText (const MString &text, const MPoint position, TextPosition textPosition=kLeft)
	This method is obsolete. More...
MStatus	getCamera (MDagPath &camera)
	Get the camera for this view. More...
MStatus	setCamera (MDagPath &camera)
	Set the camera for this view. More...
MStatus	scheduleRefresh ()
	Schedule a forced refresh for this 3d-view. More...
MStatus	refresh (bool all=false, bool force=false)
	Refresh the this view. More...
MStatus	refresh (bool all, bool force, bool offscreen)
	Refresh the this view. More...
MStatus	refresh (MPxGlBuffer &buffer)
	Refresh the this view into the GL buffer buffer. More...
MStatus	refresh (MPxGlBuffer &buffer, bool offscreen)
	Refresh the this view into the GL buffer buffer. More...
MStatus	refresh (MPxGlBuffer &buffer, bool offscreen, const MMatrix &projectionMatrix)
	Refresh the this view into the GL buffer buffer. More...
MStatus	getLightCount (unsigned int &count, bool visible=true)
	Get the number of lights for the view. More...
MStatus	getLightingMode (LightingMode &mode)
	Get the current lighting mode for the view. More...
MStatus	getLightPath (unsigned int lightNumber, MDagPath &light)
	Get the path to a certain light. More...
MStatus	isLightVisible (unsigned int lightNumber, bool &visible)
	Find out if a light is visible in the view. More...
MStatus	getLightIndex (unsigned int lightNumber, unsigned int &lightIndex)
	Get the internal light index for a given light number. More...
MStatus	viewToWorld (short x_pos, short y_pos, MPoint &worldPt, MVector &worldVector) const
	Takes a point in port coordinates and returns a corresponding ray in world coordinates. More...
MStatus	viewToWorld (short x_pos, short y_pos, MPoint &nearClipPt, MPoint &farClipPt) const
	Takes a point in port coordinates and returns a point on the near and far clipping planes. More...
MStatus	viewToObjectSpace (short x_pos, short y_pos, const MMatrix &localMatrixInverse, MPoint &oPt, MVector &oVector) const
	Takes a point in port coordinates and returns a corresponding ray in object coordinates. More...
bool	worldToView (const MPoint &worldPt, short &x_pos, short &y_pos, MStatus *ReturnStatus=NULL) const
	converts a point in world space to port space. More...
MStatus	projectionMatrix (MMatrix &projectionMatrix) const
	Returns the projection matrix currently being used by OpenGL in the current view. More...
MStatus	modelViewMatrix (MMatrix &modelViewMatrix) const
	Returns the modelview matrix currently being used by OpenGL in the current view. More...
MString	viewSelectedPrefix (MStatus *ReturnStatus) const
	Returns the Returns the prefix used when displaying the camera name in the heads up display when view selected in on. More...
MStatus	setViewSelectedPrefix (const MString &prefix)
	Sets the prefix for the camera name as displayed in the heads up display when view selected is enabled. More...
bool	showViewSelectedChildren (MStatus *ReturnStatus) const
	Returns turn if view selected shows all of the children of the obejcts that are flagged for view selected. More...
MStatus	setShowViewSelectedChildren (bool)
	This method changes the way that view selected works. More...
DisplayStyle	displayStyle (MStatus *ReturnStatus=NULL) const
	Return the display style for this 3d view. More...
bool	isShadeActiveOnly (MStatus *ReturnStatus=NULL) const
	Returns true if this view's display style is shaded for objects that are active and wireframe otherwise. More...
MStatus	setDisplayStyle (DisplayStyle style, bool activeOnly=false)
	Sets the display style for this view. More...
MStatus	setObjectDisplay (unsigned int displayMask)
	Sets a display object mask that indicates which object types are drawn in current view. More...
unsigned int	objectDisplay (MStatus *ReturnStatus=NULL)
	Returns a display object mask that indicates which object types are drawn in the current view. More...
MStatus	setPluginObjectDisplay (const MString &pluginDisplayFilter, bool on)
	Enables or disables a user-defined display filter (i.e. More...
bool	pluginObjectDisplay (const MString &pluginDisplayFilter, MStatus *ReturnStatus=NULL)
	Returns true if the plugin display filter specified by the pluginDisplayFilter is enabled in the current view. More...
RendererName	getRendererName (MStatus *ReturnStatus) const
	Get the name of the current renderer being used for drawing to this view. More...
MString	rendererString (MStatus *ReturnStatus=NULL) const
	Get the string name of the current renderer being used for drawing to this view. More...
bool	wireframeOnlyInShadedMode (MStatus *ReturnStatus) const
	Return whether we are in shaded mode, but that only non shaded drawing should occur (wireframe). More...
bool	wireframeOnShaded (MStatus *ReturnStatus=NULL) const
	Return whether we draw wireframe in shaded mode. More...
bool	xray (MStatus *ReturnStatus=NULL) const
	Return true if the X-Ray mode is enabled. More...
bool	xrayJoints (MStatus *ReturnStatus=NULL) const
	Return true if the X-Ray Joints mode is enabled. More...
bool	twoSidedLighting (MStatus *ReturnStatus=NULL) const
	Return true if the Two-sided lighting mode is enabled. More...
MStatus	readColorBuffer (MImage &image, bool readRGBA=false)
	This method is obsolete. More...
MStatus	writeColorBuffer (const MImage &image, signed short x=0, signed short y=0) const
	This method is obsolete. More...
MStatus	readDepthMap (unsigned short x, unsigned short y, unsigned int width, unsigned int height, unsigned char *bufferPtr, DepthBufferFormat depthMapPrecision)
	This method is obsolete. More...
MStatus	readBufferTo2dTexture (unsigned short x, unsigned short y, unsigned int width, unsigned int height)
	This method is obsolete. More...
bool	usingMipmappedTextures () const
	Returns if the view is using mipmapped texture display. More...
bool	usingDefaultMaterial () const
	Returns true if the view is currently displaying objects using the default material. More...
MStatus	setDisallowPolygonOffset (bool v)
	Certain Maya actions will use glPolygonOffset to offset polygons drawing into the depth buffer. More...
bool	disallowPolygonOffset () const
	Returns the current state of the disallow polygon offset bit. More...
MStatus	updateViewingParameters ()
	This method tells the camera to set the view's transformation matrix. More...
bool	multipleDrawEnabled () const
	This method returns the multiple draw enable state for this view. More...
void	setMultipleDrawEnable (bool enable)
	This method is obsolete. More...
unsigned	multipleDrawPassCount ()
	This method is obsolete. More...
void	setMultipleDrawPassCount (unsigned count)
	This method is obsolete. More...
MStatus	beginProjMatrixOverride (MMatrix &projectionMatrix)
	This method is obsolete. More...
MStatus	endProjMatrixOverride ()
	This method is obsolete. More...
MStatus	setRenderOverrideName (const MString &name)
	Set the name of a render override (MHWRender::MRenderOverride) to use. More...
MString	renderOverrideName (MStatus *ReturnStatus=NULL) const
	Get the current render override name. More...
MStatus	setObjectListFilterName (const MString &name)
	Set the name of the object list filter (MObjectListFilter) to use. More...
MString	objectListFilterName (MStatus *ReturnStatus=NULL) const
	Get the current object list filter name. More...
MStatus	setShowObjectFilterNameInHUD (bool show)
	Sets whether or not to display the object filter UI name in the heads up display when an object filter is active. More...
bool	showObjectFilterNameInHUD (MStatus *ReturnStatus) const
	Returns whether the object filter UI name is shown in the heads up display when an object filter is active. More...
bool	viewIsFiltered (MStatus *ReturnStatus=NULL) const
	Returns the state of view filtering for this view. More...
MStatus	filteredObjectList (MSelectionList &list) const
	Returns a selection list containing all of the objects that remain after filtering is applied to the view. More...
MStatus	getRendererString (MString &stringName) const
	NO SCRIPT SUPPORT. More...

Static Public Member Functions
static M3dView	active3dView (MStatus *ReturnStatus=NULL)
	Returns the active view in the form of a class (M3dView) that can operate on it. More...
static unsigned int	numberOf3dViews ()
	Returns the number of 3D views currently in existance. More...
static MStatus	get3dView (const unsigned int index, M3dView &view)
	Returns the 3D view at the given index. More...
static DisplayStatus	displayStatus (const MDagPath &path, MStatus *ReturnStatus=NULL)
	Returns the display status of the given DAG path. More...
static MNativeWindowHdl	applicationShell (MStatus *ReturnStatus=NULL)
	Returns the native handle for Maya's main window. More...
static bool	isBackgroundGradient (MStatus *ReturnStatus=NULL)
	Returns whether a gradient is being used as the background color. More...
static MColor	templateColor (MStatus *ReturnStatus=NULL)
	Returns the value of the template color. More...
static MColor	backgroundColor (MStatus *ReturnStatus=NULL)
	Returns the value of the background color. More...
static MColor	backgroundColorTop (MStatus *ReturnStatus=NULL)
	Returns the value of the background gradient top color. More...
static MColor	backgroundColorBottom (MStatus *ReturnStatus=NULL)
	Returns the value of the background gradient bottom color. More...
static MColor	liveColor (MStatus *ReturnStatus=NULL)
	Returns the color for live objects. More...
static MColor	referenceLayerColor (MStatus *ReturnStatus=NULL)
	Returns the color for objects which belong to a display layer whose display type is Reference. More...
static MColor	activeTemplateColor (MStatus *ReturnStatus=NULL)
	Returns the color for active template objects. More...
static MColor	leadColor (MStatus *ReturnStatus=NULL)
	Returns the color for lead objects. More...
static MColor	hiliteColor (MStatus *ReturnStatus=NULL)
	Returns the color for hilited objects. More...
static MColor	activeAffectedColor (MStatus *ReturnStatus=NULL)
	Returns the color for active affected objects. More...
static MStatus	scheduleRefreshAllViews ()
	Schedule a forced refresh for all 3d-views. More...
static MStatus	getM3dViewFromModelPanel (const MString &modelPaneName, M3dView &view)
	Given the name of a model panel, get the M3dView used by that panel. More...
static MStatus	getM3dViewFromModelEditor (const MString &modelPaneName, M3dView &view)
	Given the name of a model editor, get the M3dView used by that editor. More...
static const char *	className ()
	Returns the name of this class. More...

Member Enumeration Documentation

enum DisplayStyle

Display styles for a 3D view.

Enumerator
kBoundingBox	Bounding box display.
kFlatShaded	Flat shaded display.
kGouraudShaded	Gouraud shaded display.
kWireFrame	Wire frame display.
kPoints	Points only display.

enum DisplayStatus

Drawing modes for individual objects.

Enumerator
kActive	Object is active (selected).
kLive	Object is live (construction surface).
kDormant	Object is dormant (not selected, no other drawing mode enabled).
kInvisible	Object is invisible (not drawn).
kHilite	Object is hilited (has selectable components).
kTemplate	Object is templated (Not renderable).
kActiveTemplate	Object is active and templated.
kActiveComponent	Object has active components.
kLead	Last selected object.
kIntermediateObject	Construction object (not drawn).
kActiveAffected	Affected by active object(s).
kNoStatus	Object does not have a valid display status.

enum ColorTable

Reference to color palettes.

Enumerator
kActiveColors	Colors for active objects.
kDormantColors	Colors for dormant objects.
kTemplateColor	Colors for templated objects.
kBackgroundColor	Colors for background color.

enum TextPosition

Alignment values when drawing text.

Enumerator
kLeft	Draw text to the left of the point.
kCenter	Draw text centered around the point.
kRight	Draw text to the right of the point.

enum DisplayObjects

Display modes Bit masks used in combination with the return value of the dirtyMask() method to determine which portions of the geometry are dirty.

Enumerator
kDisplayEverything	Show everything.
kDisplayNurbsCurves	Show nurbs curves.
kDisplayNurbsSurfaces	Show nurbs surfaces.
kDisplayMeshes	Show meshes.
kDisplayPlanes	Show planes.
kDisplayLights	Show lights.
kDisplayCameras	Show camera.
kDisplayJoints	Show joints.
kDisplayIkHandles	Show IK handles.
kDisplayDeformers	Show deformers.
kDisplayDynamics	Show dynamics.
kDisplayParticleInstancers	Show particle instancers.
kDisplayLocators	Show locators.
kDisplayDimensions	Show dimensions.
kDisplaySelectHandles	Show selection handles.
kDisplayPivots	Show pivots.
kDisplayTextures	Show textures.
kDisplayGrid	Show the grid.
kDisplayCVs	Show NURBS CVs.
kDisplayHulls	Show NURBS hulls.
kDisplayStrokes	Show strokes.
kDisplaySubdivSurfaces	Show subdivision surfaces.
kDisplayFluids	Show fluids.
kDisplayFollicles	Show follcles.
kDisplayHairSystems	Show hair systems.
kDisplayImagePlane	Show image plane.
kDisplayNCloths	Show nCloths.
kDisplayNRigids	Show nRigids.
kDisplayDynamicConstraints	Show nDynamicConstraints.
kDisplayManipulators	Show Manipulators.
kDisplayNParticles	Show nParticles.
kExcludeMotionTrails	Show motion trails.
kExcludePluginShapes	Show plugin shapes.

enum LightingMode

Lighting mode used in this 3D view.

Enumerator
kLightAll	All lights.
kLightSelected	Selected lights.
kLightActive	Active lights.
kLightDefault	Default light.
kUnused1	Not currently used in Maya.
kLightNone	No lights / lighting disabled.

enum RendererName

Current hardware rendering engine used in this view.

Enumerator
kDefaultQualityRenderer	Equivalent to when the renderer name is "base_OpenGL_Renderer" when queried from the "modelEditor" command.
kHighQualityRenderer	Equivalent to when the renderer name is "hwRender_OpenGL_Renderer" when queried from the "modelEditor" command.
kViewport2Renderer	Equivalent to the viewport 2.0 renderer.
kExternalRenderer	An externally defined renderer name has been set.

enum DepthBufferFormat

Possible depth buffer formats to read into.

Enumerator
kDepth_8	8 bits.
kDepth_Float	Floating point.

enum LineStipplePattern

Line stipple pattern.

Enumerator
kStippleNone	No stipple. Solid line
kStippleDashed	Dashed line stipple.

Member Function Documentation

M3dView active3dView ( MStatus *  ReturnStatus = NULL )

static

Returns the active view in the form of a class (M3dView) that can operate on it.

Parameters

[out]

ReturnStatus

Returns

Active view class.

Status Codes:

• MS::kSuccess The 3d view was successfully returned
• MS::kFailure Error getting the active 3d view

Examples:

unsigned int numberOf3dViews ( )

static

Returns the number of 3D views currently in existance.

Returns

Number of 3D views.

Examples:

MStatus get3dView ( const unsigned int  index, M3dView &  view  )

static

Returns the 3D view at the given index.

Parameters

[in]	index	index of the view to get
[out]	view	storage for the returned view

Returns

Return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure Error getting the view
• MS::kInvalidParameter index is out of range

Examples:

M3dView::DisplayStatus displayStatus ( const MDagPath &  path, MStatus *  ReturnStatus = NULL  )

static

Returns the display status of the given DAG path.

Parameters

[in]	path	the DAG path to get.
[out]	ReturnStatus	Status code.

Returns

Display status for the DAG

Status Codes:

• MS::kSuccess Success
• MS::kFailure The DAG path is invalid

MStatus makeSharedContextCurrent

(

)

makes the shared context current.

If in DirectX mode it does nothing.

Returns

Operation status

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Method did not make context current

Examples:

MGLContext display

(

MStatus *

ReturnStatus = NULL

)

Mac OS X and Windows.

Returns the OpenGL context for this view.

Parameters

[out]

ReturnStatus

Status Code

Returns

The OpenGL context. On 32-bit OS X this is an AGLContext. On 64-bit OS X this is an NSOpenGLContext pointer. On Windows this is an HGLRC.

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MNativeWindowHdl applicationShell ( MStatus *  ReturnStatus = NULL )

static

Returns the native handle for Maya's main window.

This is equivalent to MQtUtil::nativeWindow(MQtUtil::mainWindow()).

Parameters

[out]

ReturnStatus

Status Code

Returns

The window handle.

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Main window does not yet exist.

void getScreenPosition	(	int &	x,
		int &	y,
		MStatus *	ReturnStatus = NULL
	)		const

Returns the current position of this view window in screen coordinates.

This is useful for finding out the exact location of the window as it appears on the screen. These values are in UI coordinate space so the y value increases from bottom to top.

Parameters

[out]	x	- x coordinate of the upper-left corner of the view
[out]	y	- y coordinate of the upper-left corner of the view
[out]	ReturnStatus	Status Code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

QWidget * widget

(

MStatus *

ReturnStatus = NULL

)

const

Returns the view's Qt widget.

Parameters

[out]

ReturnStatus

Status Code

Returns

A QWidget pointer to the Qt widget containing the view's drawing region, or NULL if the view's drawing region has not yet been created.

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure There is no view associated with this M3dView instance.

MNativeWindowHdl window

(

MStatus *

ReturnStatus = NULL

)

Returns the native window for this view.

This is equivalent to MQtUtil::nativeWindow(view.widget()).

Parameters

[out]

ReturnStatus

Status Code

Returns

The X window

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

int portWidth

(

MStatus *

ReturnStatus = NULL

)

Returns the width of the current viewport.

Parameters

[out]

ReturnStatus

Status Code

Returns

The width of this viewport

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

int portHeight

(

MStatus *

ReturnStatus = NULL

)

Returns the height of the current viewport.

Parameters

[out]

ReturnStatus

Status Code

Returns

The height of this viewport

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

bool isVisible

(

MStatus *

ReturnStatus = NULL

)

Returns true if this viewport is visible.

Parameters

[out]

ReturnStatus

Status Code

Returns

True if this viewport is visible

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

int playblastPortWidth

(

MStatus *

ReturnStatus = NULL

)

Returns the port width of current playblast.

Valid only when playblast command has been called. Otherwise, an invalid value 0 is returned.

Parameters

[out]

ReturnStatus

Status Code

Returns

The port width of current playblast.

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

int playblastPortHeight

(

MStatus *

ReturnStatus = NULL

)

Returns the port height of current playblast.

Valid only when playblast command has been called. Otherwise, an invalid value 0 is returned.

Parameters

[out]

ReturnStatus

Status Code

Returns

The height of current playblast.

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus pushViewport	(	unsigned int	x,
		unsigned int	y,
		unsigned int	width,
		unsigned int	height
	)

Set the current viewport dimensions.

Will keep track of the last viewport dimensions on a stack. When finished with this viewport, the current dimensions should be removed from the top of stack using M3dView::popViewport().

Parameters

[in]	x	Lower left corner of viewport (x coordinate).
[in]	y	Lower left corner of viewport (y coordinate).
[in]	width	Width of the viewport.
[in]	height	Height of the viewport.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus popViewport

(

)

Pop the current viewport off of the viewport stack.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus viewport	(	unsigned int &	x,
		unsigned int &	y,
		unsigned int &	width,
		unsigned int &	height
	)		const

Get the current viewport dimensions.

Parameters

[out]	x	Lower left corner of viewport (x coordinate).
[out]	y	Lower left corner of viewport (y coordinate).
[out]	width	Width of the viewport.
[out]	height	Height of the viewport.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus beginGL

(

)

This method is obsolete.

Deprecated:

Use Viewport 2.0 APIs instead. See "Viewport 2.0" chapter of the "API Guide" for alternatives.

Setup port for native OpenGL drawing calls.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus endGL

(

)

This method is obsolete.

Deprecated:

Use Viewport 2.0 APIs instead. See "Viewport 2.0" chapter of the "API Guide" for alternatives.

End OpenGL drawing.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

void beginSelect	(	GLuint *	buffer = NULL,
		GLsizei	size = 0
	)

Start selecting.

The buffer passed is used to record selection hits. A selection hit consists of the following 4 items:

• Number of names on selection stack when hit occurred.
• Min Z window-coordinate of all vertices that intersected view volume since last recorded hit. The value (which lies in the range [0..1] is multiplied by 2^32 - 1 and rounded to the nearest unsigned integer.
• Max Z window-coordinate. (computed as above)
• Contents of name stack with bottommost element first. When multiple names are pushed on the stack, several GLuint values will be stored.

Parameters

[in]	buffer	OpenGl pick buffer
[in]	size	Buffer size (number of GLint)

Examples:

GLint endSelect

(

)

Finish a selection sequence.

Result is stored in the buffer passed in the beginSelect call.

Examples:

bool selectMode

(

)

const

Tells if this M3dView is in selection mode.

Returns

true between beginSelect and endSelect calls.

bool textureMode

(

)

const

Tells if this M3dView is in texture mode.

Returns

true if this modelling view is in texture mode.

void loadName

(

GLuint

name

)

Replace the top of the name stack with the given name.

Valid only when beginSelect() has been called.

Parameters

[in]

name

Name to be loaded onto the top of the stack.

void pushName

(

GLuint

name

)

Push a new name on the name stack.

Valid only when beginSelect() has been called.

Parameters

[in]

name

Name to be loaded onto the top of the stack.

Examples:

void popName

(

)

Removes the top of the name stack.

Valid only when beginSelect() has been called.

Examples:

void initNames

(

)

Reset the name stack.

Valid only when beginSelect() has been called.

MStatus beginXorDrawing	(	bool	drawOrthographic = true,
		bool	disableDepthTesting = true,
		float	lineWidth = 1.0f,
		LineStipplePattern	stipplePattern = kStippleNone,
		const MColor &	lineColor = MColor(1, 1, 1)
	)

Setup the context for exclusive-or (XOR) drawing.

In XOR drawing the color values of the pixels being drawn is exclusive-ored with the color values already present in the view. The advantage of this is that exclusive-oring the same pixels with the same color values a second time will restore the pixels to their original colors, making it possible to temporarily display and erase lines without having to redraw the entire view. This makes XOR drawing particularly useful for drawing guidelines for tools.

One disadvantage of XOR drawing is that the final color after the exclusive-or will not match your drawing color, except when the original color of the pixel was black. For example, XORing a white line across a red background will result in a cyan line and XORing it across a changing background will result in a line of changing colors. However in most situations where you would use XOR drawing the color of the lines is irrelevant just so long as they are visible.

It is an error to call beginXorDrawing() again before calling endXorDrawing() first.

Parameters

[in]	drawOrthographic	Draw using orthographic projection. Default is true.
[in]	disableDepthTesting	Disable depth testing during draw. Default is true.
[in]	lineWidth	Set up line width. Default is 1.
[in]	stipplePattern	Line stipple pattern. Default is kStippleNone.
[in]	lineColor	Line color. Default is white (1,1,1).

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus endXorDrawing

(

)

Reset the context to non-exclusive-or (non-XOR) screen drawing.

If endXorDrawing() is called without first calling beginXorDrawing() an error will result.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus setDrawColor	(	unsigned int	index,
		ColorTable	table = kActiveColors
	)

This method is obsolete.

Deprecated:

Use MHWRender::MUIDrawManager instead.

Set the color to draw in. The index argument is an index into the application's color tables. Valid values range between zero and the size of the table minus one. The size of the active and dormant color tables can be found using methods of this class. The background and template color tables are both of size one.

These indices do not directly correspond to those of the underlying OpenGL color index mode. Using the glIndex call directly is not recommended and may cause unpredictable results. This method should be used instead.

Note that this method will work in either RGBA mode or color index mode.

Parameters

[in]	index	index of the color to draw in
[in]	table	color table to index into

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kInvalidParameter Index is out of range
• MS::kFailure Object error

Examples:

MStatus setDrawColor

(

const MColor &

color

)

This method is obsolete.

Deprecated:

Use MHWRender::MUIDrawManager instead.

Set the color to draw in. It is a convenient replacement for glColor3.

Parameters

[in]

color

color to draw in

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus setDrawColorAndAlpha

(

const MColor &

color

)

This method is obsolete.

Deprecated:

Use MHWRender::MUIDrawManager instead.

Set the color to draw in. It is a convenient replacement for glColor4.

Parameters

[in]

color

color to draw in

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

unsigned int numDormantColors

(

MStatus *

ReturnStatus = NULL

)

Returns the number of dormant object colors in the internal application color table.

Parameters

[out]

ReturnStatus

Status code

Returns

The number of dormant colors

Status Codes:

• MS::kSuccess Method was successful

unsigned int numActiveColors

(

MStatus *

ReturnStatus = NULL

)

Returns the number of active object colors in the internal application color table.

Parameters

[out]

ReturnStatus

Status code

Returns

The number of active colors

Status Codes:

• MS::kSuccess Method was successful

unsigned int numUserDefinedColors

(

MStatus *

ReturnStatus = NULL

)

Returns the number of user defined colors in the internal application color table.

These colors may be changed by the user and assigned to specific objects. See the methods of MFnDagNode for information on assigning user defined colors to individual objects.

The user defined colors are not a color table of their own. They exist in the active and dormant color tables.

Parameters

[out]

ReturnStatus

Status code

Returns

The number of user defined colors

Status Codes:

• MS::kSuccess Method was successful

MStatus setUserDefinedColor	(	unsigned int	index,
		const MColor &	color
	)

Sets the user defined color at the given index.

Valid indices range between zero and the number of user defined colors.

Parameters

[in]	index	index into the user defined color
[in]	color	color to set to

Returns

An index into the application's color table

Status Codes:

• MS::kSuccess Method was successful
• MS::kInvalidParameter Index is out of range

unsigned int userDefinedColorIndex	(	unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)

Returns the index for the given user-defined color.

Valid values for the index argument range between zero and the number of user-defined colors minus one.

The index returned gives the location of the specified color inside the active and dormant color tables (the index is the same in both tables).

Parameters

[in]	index	Index into user-defined colors
[out]	ReturnStatus	Status code

Returns

Index of user-defined color into the active and dormant tables

Status Codes:

• MS::kSuccess Method was successful

MColor colorAtIndex	(	unsigned int	index,
		ColorTable	table = kActiveColors,
		MStatus *	ReturnStatus = NULL
	)

Returns the value of the color at the given index in the application's color table.

Parameters

[in]	index	Index of the color to retrieve
[in]	table	Table to index into
[out]	ReturnStatus	Status code

Returns

The color

Status Codes:

• MS::kSuccess Method was successful
• MS::kInvalidParameter Index is out of range

MStatus getColorIndexAndTable	(	unsigned int	glindex,
		unsigned int &	index,
		ColorTable &	table
	)		const

Returns the color table and index representing the given OpenGL color-index value.

This method is useful when converting color indices obtained from glReadPixels(GL_COLOR_INDEX) to Maya color-index values suitable for use with the colorAtIndex and setDrawColor methods.

Parameters

[in]	glindex	Value of the OpenGL color-index to retrieve
[out]	index	Returned ColorTable index
[out]	table	Returned ColorTable

Returns

StatusCode

Status Codes:

• MS::kSuccess Method was successful
• MS::kInvalidParameter Index is out of range

MStatus colorMask	(	bool &	r,
		bool &	g,
		bool &	b,
		bool &	a
	)

This method is obsolete.

Deprecated:

Use MHWRender::MUIDrawManager instead.

Get the current color mask.

Parameters

[out]	r	Red color mask flag.
[out]	g	Green color mask flag.
[out]	b	Blue color mask flag.
[out]	a	Alpha color mask flag.

Returns

Status Code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus setColorMask	(	bool	r,
		bool	g,
		bool	b,
		bool	a
	)

This method is obsolete.

Deprecated:

Use MHWRender::MUIDrawManager instead.

Set the current color mask.

Parameters

[in]	r	Red color mask flag.
[in]	g	Green color mask flag.
[in]	b	Blue color mask flag.
[in]	a	Alpha color mask flag.

Returns

Status Code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

bool isBackgroundGradient ( MStatus *  ReturnStatus = NULL )

static

Returns whether a gradient is being used as the background color.

Parameters

[out]

ReturnStatus

Status code

Returns

• true background is a color gradient
• false background is a solid color

Status Codes:

• MS::kSuccess Method was successful

MColor templateColor ( MStatus *  ReturnStatus = NULL )

static

Returns the value of the template color.

Parameters

[out]

ReturnStatus

Status code

Returns

The template color

Status Codes:

• MS::kSuccess Method was successful

MColor backgroundColor ( MStatus *  ReturnStatus = NULL )

static

Returns the value of the background color.

Parameters

[out]

ReturnStatus

Status code

Returns

The background color

Status Codes:

• MS::kSuccess Method was successful

MColor backgroundColorTop ( MStatus *  ReturnStatus = NULL )

static

Returns the value of the background gradient top color.

Parameters

[out]

ReturnStatus

Status code

Returns

The background gradient top color

Status Codes:

• MS::kSuccess Method was successful

MColor backgroundColorBottom ( MStatus *  ReturnStatus = NULL )

static

Returns the value of the background gradient bottom color.

Parameters

[out]

ReturnStatus

Status code

Returns

The background gradient bottom color

Status Codes:

• MS::kSuccess Method was successful

MColor liveColor ( MStatus *  ReturnStatus = NULL )

static

Returns the color for live objects.

Parameters

[out]

ReturnStatus

Status code

Returns

The live color

Status Codes:

• MS::kSuccess Method was successful

MColor referenceLayerColor ( MStatus *  ReturnStatus = NULL )

static

Returns the color for objects which belong to a display layer whose display type is Reference.

This color is also used for objects whose display override is set to Reference.

Parameters

[out]

ReturnStatus

Status code

Returns

The reference layer color

Status Codes:

• MS::kSuccess Method was successful

MColor activeTemplateColor ( MStatus *  ReturnStatus = NULL )

static

Returns the color for active template objects.

Parameters

[out]

ReturnStatus

Status code

Returns

The active template color

Status Codes:

• MS::kSuccess Method was successful

MColor leadColor ( MStatus *  ReturnStatus = NULL )

static

Returns the color for lead objects.

Parameters

[out]

ReturnStatus

Status code

Returns

The lead color

Status Codes:

• MS::kSuccess Method was successful

MColor hiliteColor ( MStatus *  ReturnStatus = NULL )

static

Returns the color for hilited objects.

Parameters

[out]

ReturnStatus

Status code

Returns

The hilite color

Status Codes:

• MS::kSuccess Method was successful

MColor activeAffectedColor ( MStatus *  ReturnStatus = NULL )

static

Returns the color for active affected objects.

Parameters

[out]

ReturnStatus

Status code

Returns

The active affected color

Status Codes:

• MS::kSuccess Method was successful

MStatus drawText	(	const MString &	text,
		const MPoint	position,
		M3dView::TextPosition	textPosition = kLeft
	)

This method is obsolete.

Deprecated:

Use MHWRender::MUIDrawManager in a MHWRender::MHUDRender operation instead.

Draws the given text at the given spot in the default font. This method is provided as a convienient way to draw OpenGL text.

Parameters

[in]	text	Text to draw
[in]	position	Position in space to draw at
[in]	textPosition	Text position relative to the point

Returns

The color

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus getCamera

(

MDagPath &

camera

)

Get the camera for this view.

Parameters

[out]

camera

Dag path for the camera (allocated by caller)

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus setCamera

(

MDagPath &

camera

)

Set the camera for this view.

Parameters

[in]

camera

Dag path of the camera for this view

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus scheduleRefreshAllViews ( )

static

Schedule a forced refresh for all 3d-views.

This method may be called safely at any time from any thread. The refresh will occur on the main thread when Maya next becomes idle. If a refresh has already been scheduled but has not yet occurred then this method will do nothing.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus scheduleRefresh

(

)

Schedule a forced refresh for this 3d-view.

This method may be called safely at any time from any thread. The refresh will occur on the main thread when Maya next becomes idle. If a refresh has already been scheduled for this view but has not yet occurred then this method will do nothing.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus refresh	(	bool	all = false,
		bool	force = false
	)

Refresh the this view.

If all is set to true then all of the 3d-view will be refreshed.

If force is set to true, then the views will be refreshed even if they do not require it. This option should be used with extreme care because extra refreshes will greatly degrade application performance. In almost all cases it is better to use the default behavior where the view is only refreshed if it is required.

Parameters

[in]	all	If true then refresh all views, otherwise refresh this view.
[in]	force	If true then force views to refresh even if they do not require it.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus refresh	(	bool	all,
		bool	force,
		bool	offscreen
	)

Refresh the this view.

If all is set to true then all of the 3d-view will be refreshed.

If force is set to true, then the views will be refreshed even if they do not require it. This option should be used with extreme care because extra refreshes will greatly degrade application performance. In almost all cases it is better to use the default behavior where the view is only refreshed if it is required.

Parameters

[in]	all	If true then refresh all views, otherwise refresh this view.
[in]	force	If true then force views to refresh even if they do not require it.
[in]	offscreen	Should the buffer be redrawn if it's offscreen?

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus refresh

(

MPxGlBuffer &

buffer

)

Refresh the this view into the GL buffer buffer.

This refresh function always forces an update and always only draws the this view. The buffer argument should refer to a buffer that has been configured with the correct depth, color, z-buffer, etc. This configuration normally occurs in the constructor of the MPxGlBuffer and the behavior is undefined. If a buffer is configured for one view configuration and then is used for a different configuration. This may occur when Maya switches from wireframe to shaded mode since it also changes from color index to RGB mode.

If the MPxGlBuffer is double buffered, drawing always is done to the back buffer and swapping is left to the user.

Parameters

[in]

buffer

The MPxGlBuffer in which to draw the view.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus refresh	(	MPxGlBuffer &	buffer,
		bool	offscreen
	)

Refresh the this view into the GL buffer buffer.

This refresh function always forces an update and always only draws the this view. The buffer argument should refer to a buffer that has been configured with the correct depth, color, z-buffer, etc. This configuration normally occurs in the constructor of the MPxGlBuffer and the behavior is undefined. If a buffer is configured for one view configuration and then is used for a different configuration. This may occur when Maya switches from wireframe to shaded mode since it also changes from color index to RGB mode.

Parameters

[in]	buffer	The MPxGlBuffer in which to draw the view.
[in]	offscreen	Should the buffer be redrawn if it's offscreen?

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus refresh	(	MPxGlBuffer &	buffer,
		bool	offscreen,
		const MMatrix &	projMatrix
	)

Refresh the this view into the GL buffer buffer.

This refresh function always forces an update and always only draws the this view. The buffer argument should refer to a buffer that has been configured with the correct depth, color, z-buffer, etc. This configuration normally occurs in the constructor of the MPxGlBuffer and the behavior is undefined. If a buffer is configured for one view configuration and then is used for a different configuration. This may occur when Maya switches from wireframe to shaded mode since it also changes from color index to RGB mode.

Parameters

[in]	buffer	The MPxGlBuffer in which to draw the view.
[in]	offscreen	Should the buffer be redrawn if it's offscreen?
[in]	projMatrix	Projection matrix to provide to openGL before drawing

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus getLightCount	(	unsigned int &	count,
		bool	visible = true
	)

Get the number of lights for the view.

Parameters

[out]	count	The number of visible lights for the view.
[in]	visible	Specify whether to count visible lights only. By Default this is set true.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus getLightingMode

(

M3dView::LightingMode &

mode

)

Get the current lighting mode for the view.

Parameters

[out]

mode

The lighting mode for the view.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus getLightPath	(	unsigned int	lightNumber,
		MDagPath &	lightPath
	)

Get the path to a certain light.

Parameters

[in]	lightNumber	Number of the light interested in
[out]	lightPath	Path to light.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus isLightVisible	(	unsigned int	lightNumber,
		bool &	visible
	)

Find out if a light is visible in the view.

Parameters

[in]	lightNumber	The number of the light to check.
[out]	visible	Whether the light is visible or not.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus getLightIndex	(	unsigned int	lightNumber,
		unsigned int &	lightIndex
	)

Get the internal light index for a given light number.

Parameters

[in]	lightNumber	The number of the light to check.
[out]	lightIndex	The internal light index (returned)

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus viewToWorld	(	short	x_pos,
		short	y_pos,
		MPoint &	worldPt,
		MVector &	worldVector
	)		const

Takes a point in port coordinates and returns a corresponding ray in world coordinates.

Parameters

[in]	x_pos	the x position of the point in port coordinates
[in]	y_pos	the y position of the point in port coordinates
[out]	worldPt	(returned) the source of the ray
[out]	worldVector	(returned) the direction of the ray

Returns

Status Code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus viewToWorld	(	short	x_pos,
		short	y_pos,
		MPoint &	nearClipPt,
		MPoint &	farClipPt
	)		const

Takes a point in port coordinates and returns a point on the near and far clipping planes.

Parameters

[in]	x_pos	the x position of the point in port coordinates
[in]	y_pos	the y position of the point in port coordinates
[out]	nearClipPt	(returned) point on near clipping plane
[out]	farClipPt	(returned) point on far clipping plane

Returns

Status Code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus viewToObjectSpace	(	short	x_pos,
		short	y_pos,
		const MMatrix &	localMatrixInverse,
		MPoint &	oPt,
		MVector &	oVector
	)		const

Takes a point in port coordinates and returns a corresponding ray in object coordinates.

Parameters

[in]	x_pos	the x position of the point in port coordinates
[in]	y_pos	the y position of the point in port coordinates
[in]	localMatrixInverse	the inclusive matrix inverse of the object in question
[out]	oPt	(returned) the source of the ray in object space
[out]	oVector	(returned) the direction of the ray in object space

Returns

Status Code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

bool worldToView	(	const MPoint &	worldPt,
		short &	x_pos,
		short &	y_pos,
		MStatus *	ReturnStatus = NULL
	)		const

converts a point in world space to port space.

The return value indicates if the point is not clipped.

Parameters

[in]	worldPt	the point to world space
[out]	x_pos	(returned) The x coordinate of the world point in port space.
[out]	y_pos	(returned) The y coordinate of the world point in port space.
[out]	ReturnStatus	Status code

Returns

• true point is not clipped
• false point is undefined or outside frustum

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus projectionMatrix

(

MMatrix &

projMat

)

const

Returns the projection matrix currently being used by OpenGL in the current view.

Parameters

[out]

projMat

A place to store the projection matrix

Returns

Status Code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus modelViewMatrix

(

MMatrix &

modelViewMatrix

)

const

Returns the modelview matrix currently being used by OpenGL in the current view.

Parameters

[out]

modelViewMatrix

A place to store the modelview matrix

Returns

Status Code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MString viewSelectedPrefix

(

MStatus *

ReturnStatus

)

const

Returns the Returns the prefix used when displaying the camera name in the heads up display when view selected in on.

Parameters

[out]

ReturnStatus

the return status

Returns

The prefix.

Status Codes:

• MS::kSuccess Operation successful

MStatus setViewSelectedPrefix

(

const MString &

prefix

)

Sets the prefix for the camera name as displayed in the heads up display when view selected is enabled.

The prefix is concatenated with the camera name.

The default value is "isolate: "

Parameters

[in]

prefix

The prefix to use.

Returns

Status

Status Codes:

• MS::kSuccess Operation successful

bool showViewSelectedChildren

(

MStatus *

ReturnStatus

)

const

Returns turn if view selected shows all of the children of the obejcts that are flagged for view selected.

Parameters

[out]

ReturnStatus

The return status

Returns

true if the children of view selected objects are drawn.

Status Codes:

• MS::kSuccess Operation successful
• MS::kFailure Operation failed

MStatus setShowViewSelectedChildren

(

bool

show

)

This method changes the way that view selected works.

By default, view selected with show all of the children of the objects in the view selected set. If false is passed to this method, then only the obejcts in the view selected set and their shapes will be drawn.

Parameters

[in]

show

true if all of the children of view selected objects should be displayed. true is the default behavior for view selected.

Returns

Return status

Status Codes:

• MS::kSuccess Operation successful
• MS::kSuccess Operation failed

MStatus getM3dViewFromModelPanel ( const MString &  name, M3dView &  view  )

static

Given the name of a model panel, get the M3dView used by that panel.

If this fails, then a panel with the given name could not be located.

Parameters

[in]	name	The name of the model panel.
[out]	view	The M3dView from the model panel.

Returns

Return Status

Status Codes:

• MS::kSuccess Operation successful
• MS::kSuccess Operation failed

Examples:

MStatus getM3dViewFromModelEditor ( const MString &  name, M3dView &  view  )

static

Given the name of a model editor, get the M3dView used by that editor.

If this fails, then a editor with the given name could not be located.

Parameters

[in]	name	The name of the model editor.
[out]	view	The M3dView from the model editor.

Returns

Return Status

Status Codes:

• MS::kSuccess Operation successful
• MS::kSuccess Operation failed

M3dView::DisplayStyle displayStyle

(

MStatus *

ReturnStatus = NULL

)

const

Return the display style for this 3d view.

The display style can be wireframe, flat-shaded, or smooth-shaded.

Parameters

[out]

ReturnStatus

Status code

Returns

The display style for this view

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

bool isShadeActiveOnly

(

MStatus *

ReturnStatus = NULL

)

const

Returns true if this view's display style is shaded for objects that are active and wireframe otherwise.

Parameters

[out]

ReturnStatus

Status code

Returns

• true Only active objects are shaded if this view is in shaded mode
• false All objects are shaded if this view is in shaded mode

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus setDisplayStyle	(	DisplayStyle	style,
		bool	activeOnly = false
	)

Sets the display style for this view.

The display style can be wireframe, flat-shaded, or smooth-shaded.

Parameters

[in]	style	The display style to be set for this view
[in]	activeOnly	Specifies whether only active objects are to be shaded in shaded mode.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus setObjectDisplay

(

unsigned int

displayMask

)

Sets a display object mask that indicates which object types are drawn in current view.

By default every thing is displayed.

Parameters

[in]

displayMask

The display object mask made with M3dView::DisplayObjects enum

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

unsigned int objectDisplay

(

MStatus *

ReturnStatus = NULL

)

Returns a display object mask that indicates which object types are drawn in the current view.

Parameters

[out]

ReturnStatus

the return status

Returns

The display object mask which can be bit 'AND'ed against the M3dView::DisplayObjects enum.

Status Codes:

• MS::kSuccess Operation successful
• MS::kFailure Object error

MStatus setPluginObjectDisplay	(	const MString &	pluginDisplayFilter,
		bool	on
	)

Enables or disables a user-defined display filter (i.e.

one which was registered using MFnPlugin::registerDisplayFilter() or the 'pluginDisplayFilter' command).

In Default Viewport, the plug-in will have to check the state of the user-defined display filter in the node's draw code. In Viewport 2.0, nodes will be filtered automatically based on the classification associated with the filter. During selection/snapping, the plugin will have to check the state of the filter in the node's select/snap code.

Parameters

[in]	pluginDisplayFilter	The name of the plugin display filter.
[in]	on	Enable or disable the plugin display filter.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

bool pluginObjectDisplay	(	const MString &	pluginDisplayFilter,
		MStatus *	ReturnStatus = NULL
	)

Returns true if the plugin display filter specified by the pluginDisplayFilter is enabled in the current view.

Parameters

[in]	pluginDisplayFilter	The name of the plugin display filter.
[out]	ReturnStatus	the return status

Returns

true if the plugin display filter is enabled

Status Codes:

• MS::kSuccess Operation successful
• MS::kFailure Object error

M3dView::RendererName getRendererName

(

MStatus *

ReturnStatus

)

const

Get the name of the current renderer being used for drawing to this view.

The current possible return values are:

kDefaultQualityRenderer : This is equivalent to when the renderer name is "base_OpenGL_Renderer" when queried from the "modelEditor" command kHighQualityRenderer : This is equivalent to when the renderer name is "hwRender_OpenGL_Renderer" when queried from the "modelEditor" command kViewport2Renderer : This is equivalent to the viewport 2.0 renderer.

Note that the latter is not supported on platforms running the IRIX operating system.

Parameters

[out]

ReturnStatus

the return status

Returns

The name of the current renderer.

Status Codes:

• MS::kSuccess Operation successful

Examples:

MString rendererString

(

MStatus *

ReturnStatus = NULL

)

const

Get the string name of the current renderer being used for drawing to this view.

Parameters

[out]

ReturnStatus

Status code (see below)

Returns

String name

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

bool wireframeOnlyInShadedMode

(

MStatus *

ReturnStatus

)

const

Return whether we are in shaded mode, but that only non shaded drawing should occur (wireframe).

In general it will return true only when the current renderer is "hwRender_OpenGL_Renderer". See the M3dView::getRendererString() method for more details.

Parameters

[out]

ReturnStatus

the return status

Returns

true if we are in this mode.

Status Codes:

• MS::kSuccess Operation successful

bool wireframeOnShaded

(

MStatus *

ReturnStatus = NULL

)

const

Return whether we draw wireframe in shaded mode.

Parameters

[out]

ReturnStatus

the return status

Returns

true if we draw wireframe in shaded mode.

Status Codes:

• MS::kSuccess Operation successful

Examples:

bool xray

(

MStatus *

ReturnStatus = NULL

)

const

Return true if the X-Ray mode is enabled.

Parameters

[out]

ReturnStatus

the return status

Returns

true if the X-Ray mode is enabled.

Status Codes:

• MS::kSuccess Operation successful
• MS::kFailure Object error

Examples:

bool xrayJoints

(

MStatus *

ReturnStatus = NULL

)

const

Return true if the X-Ray Joints mode is enabled.

Parameters

[out]

ReturnStatus

the return status

Returns

true if the X-Ray Joints mode is enabled.

Status Codes:

• MS::kSuccess Operation successful
• MS::kFailure Object error

bool twoSidedLighting

(

MStatus *

ReturnStatus = NULL

)

const

Return true if the Two-sided lighting mode is enabled.

Parameters

[out]

ReturnStatus

the return status

Returns

true if the Two-sided lighting mode is enabled.

Status Codes:

• MS::kSuccess Operation successful
• MS::kFailure Object error

MStatus readColorBuffer	(	MImage &	image,
		bool	readRGBA = false
	)

This method is obsolete.

Deprecated:

Use MHWRender::MRenderTargetManager::acquireRenderTarget() instead.

Read the RGB values from the frame buffer for a given view. The buffer is read in a pixel format which is BGRA by default, such that each channel is one byte in size.

Parameters

[in]	image	The image contains the frame buffer pixels.
[in]	readRGBA	Read the image back in RGBA format. By default the format is BGRA.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus writeColorBuffer	(	const MImage &	image,
		signed short	x = 0,
		signed short	y = 0
	)		const

This method is obsolete.

Deprecated:

Use MHWRender::MQuadRender operation inside MHWRender::MRenderOverride instead.

Overwrite the RGB values for the frame buffer for a given view. Expected input is a block of RGBA, such that each channel is one byte in size.

Parameters

[in]	image	The image containing the block of pixels to write
[in]	x	The location in screen space of the lower left corner (X) of the image to write. The default value is 0.
[in]	y	The location in screen space of the lower left corner (Y) of the image to write. The default value is 0.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus readDepthMap	(	unsigned short	x,
		unsigned short	y,
		unsigned int	width,
		unsigned int	height,
		unsigned char *	bufferPtr,
		DepthBufferFormat	depthMapPrecision
	)

This method is obsolete.

Deprecated:

Use MHWRender::MRenderTargetManager::acquireRenderTarget() instead.

Read the depth values from the frame buffer for a given view. The buffer is read into a block of data as defined as an argument. The data block size must be large enough to accomodate ( view width * view height * depth map precision ) bytes of data.

Parameters

[in]	x	Start position x to read.
[in]	y	Start position y to read.
[in]	width	Number of pixels in x to read.
[in]	height	Number of pixels in y to read.
[in]	bufferPtr	Pointer to depth data allocated by the caller.
[in]	depthMapPrecision	Enumerated depth precision.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

Examples:

MStatus readBufferTo2dTexture	(	unsigned short	x,
		unsigned short	y,
		unsigned int	width,
		unsigned int	height
	)

This method is obsolete.

Deprecated:

Use MHWRender::MRenderTargetManager instead.

Read the depth values from the frame buffer for a given view into a predefined OpenGL 2d texture. It is assumed that such a texture has been created and bound before making this call.

Parameters

[in]	x	Start position x to read.
[in]	y	Start position y to read.
[in]	width	Number of pixels in x to read.
[in]	height	Number of pixels in y to read.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

bool usingMipmappedTextures

(

)

const

Returns if the view is using mipmapped texture display.

Returns

Mipmap texture display state.

bool usingDefaultMaterial

(

)

const

Returns true if the view is currently displaying objects using the default material.

Returns

The default material state.

Examples:

MStatus setDisallowPolygonOffset

(

bool

v

)

Certain Maya actions will use glPolygonOffset to offset polygons drawing into the depth buffer.

This method controls this behavior. When true, it prevents Maya from altering the polygon offset parameters.

Parameters

[in]

v

enable/disable the polygon offset

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

bool disallowPolygonOffset

(

)

const

Returns the current state of the disallow polygon offset bit.

See setDisallowPolygonOffset for more information.

Returns

True if Maya currently is disallowing the use of glPolygonOffset.

MStatus updateViewingParameters

(

)

This method tells the camera to set the view's transformation matrix.

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

bool multipleDrawEnabled

(

)

const

This method returns the multiple draw enable state for this view.

Returns

• true if multiple draw is enabled.

void setMultipleDrawEnable

(

bool

enable

)

This method is obsolete.

Deprecated:

Use MHWRender::MRenderOverride instead.

This method enables/disables multiple camera drawing for this view. If multiple draw is disabled, then this view will behave like a normal Maya view.

Parameters

[in]

enable

If true, then multiple draw is enabled.

unsigned multipleDrawPassCount

(

)

This method is obsolete.

Deprecated:

Use MHWRender::MRenderOverride instead.

This method returns the number of multiple draw passes that are going to be made. By default a 1 is returned.

Returns

• The number of multiple draw passes that will be made.

void setMultipleDrawPassCount

(

unsigned

count

)

This method is obsolete.

Deprecated:

Use MHWRender::MRenderOverride instead.

This method sets the number of multiple draw passes when multiple draw is enabled.

Parameters

[in]

count

The number of multiple draw passes.

NOTE: This method is designed to be used for default model view only, that means this method can not used in MPx3dModelView derived custom model view.

This method must be called in a pre-render callback that added by MUIMessage::add3dViewPreRenderMsgCallback().

By setting setMultipleDrawPassCount() in the pre-render callback, pre/post multiple draw pass callbacks that are added by MUIMessage::add3dViewPreMultipleDrawPassMsgCallback() and MUIMessage::add3dViewPreMultipleDrawPassMsgCallback() are called.

Note that setMultipleDrawPassCount value should be restored in the post-render callback that is added by MUIMessage::add3dViewPostRenderMsgCallback().

See following example code.

	preRenderCB()
	{
		view.setMultipleDrawEnable( true )
		view.setMultipleDrawPassCount( 2 )
	}

        preMultiplePassCB(0)
			draw()
		postMultiplePassCB(0)

        preMultiplePassCB(1)
			draw()
		postMultiplePassCB(1)

    postRenderCB()
	{
		view.setMultipleDrawEnable( false )
		view.setMultipleDrawPassCount( 1 )
	}

MStatus beginProjMatrixOverride

(

MMatrix &

projectionMatrix

)

This method is obsolete.

Deprecated:

Use MHWRender::MRenderOverride instead.

Begin overriding the projection matrix used in openGL drawing. This override is enabled until endProjMatrixOverride() is called.

Parameters

[in]

projectionMatrix

Projection matrix used in openGL drawing

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus endProjMatrixOverride

(

)

This method is obsolete.

Deprecated:

Use MHWRender::MRenderOverride instead.

End projection matrix override enabled by beginProjMatrixOverride().

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

MStatus setRenderOverrideName

(

const MString &

name

)

Set the name of a render override (MHWRender::MRenderOverride) to use.

The override must be registered before it can be used.

The override cannot be set unless the view is set to be using the Viewport 2.0 renderer.

If the override name is an empty string then the any existing override will be removed.

Parameters

[in]

name

Name of the override.

Returns

Status code

Status Codes:

• MS::kSuccess The override was set.
• MS::kFailure The override could not be set.

Examples:

MString renderOverrideName

(

MStatus *

ReturnStatus = NULL

)

const

Get the current render override name.

If none then an empty string will be returned.

Parameters

[out]

ReturnStatus

return status.

Returns

Override name.

MStatus setObjectListFilterName

(

const MString &

name

)

Set the name of the object list filter (MObjectListFilter) to use.

The filter must be registered before it can be used.

If the name is an empty string then any existing filter will be removed.

Any previously set filter will be replaced with the new one.

Parameters

[in]

name

Name of the filter.

Returns

Status code

Status Codes:

• MS::kSuccess The filter was set.
• MS::kFailure The filter could not be set.

MString objectListFilterName

(

MStatus *

ReturnStatus = NULL

)

const

Get the current object list filter name.

If none then an empty string will be returned.

Parameters

[out]

ReturnStatus

Returns

Filter name.

Status Codes:

• MS::kSuccess An object filter name can be returned
• MS::kFailure No object filter can be returned

Examples:

MStatus setShowObjectFilterNameInHUD

(

bool

show

)

Sets whether or not to display the object filter UI name in the heads up display when an object filter is active.

This string is concatenated with the camera name.

Parameters

[in]

show

If true, show the filter UI name in the HUD

Returns

Status

Status Codes:

• MS::kSuccess Operation successful
• MS::kFailure Object error

bool showObjectFilterNameInHUD

(

MStatus *

ReturnStatus

)

const

Returns whether the object filter UI name is shown in the heads up display when an object filter is active.

Parameters

[out]

ReturnStatus

the return status

Returns

True if the filter UI name is shown

Status Codes:

• MS::kSuccess Operation successful
• MS::kFailure Object error

bool viewIsFiltered

(

MStatus *

ReturnStatus = NULL

)

const

Returns the state of view filtering for this view.

Parameters

[out]

ReturnStatus

return status

Returns

True if the view is filtered.

Status Codes:

• MS::kSuccess Operation successful
• MS::kFailure Operation failed

Examples:

MStatus filteredObjectList

(

MSelectionList &

list

)

const

Returns a selection list containing all of the objects that remain after filtering is applied to the view.

Parameters

[out]

list

The list of objects left after filtering.

Returns

Return status

Status Codes:

• MS::kSuccess Operation successful
• MS::kFailure Operation failed

Examples:

MStatus getRendererString

(

MString &

stringName

)

const

NO SCRIPT SUPPORT.

Get the string name of the current renderer being used for drawing to this view.

Python Notes

This method is not supported in Python. See the version which returns a string.

Parameters

[out]

stringName

string name (returned).

Returns

Status code

Status Codes:

• MS::kSuccess Method was successful
• MS::kFailure Object error

const char * className ( )

static

Returns the name of this class.

Returns

The name of this class.

---

The documentation for this class was generated from the following files:

• M3dView.h
• M3dView.cpp