M3dView Class Reference
[OpenMayaUI - API module for user interface]

#include <M3dView.h>

Detailed 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:

: apiMeshShapeUI.cpp, apiMeshShapeUI.h, apiSimpleShapeUI.cpp, apiSimpleShapeUI.h, blindDataShader.cpp, blindDataShader.h, cgfxShaderCmd.cpp, componentScaleManip.cpp, curvedArrowsNode.cpp, customAttrManip.cpp, cvColorNode.cpp, footPrintManip.cpp, footPrintNode.cpp, helixTool.cpp, hwAnisotropicShader_NV20.cpp, hwAnisotropicShader_NV20.h, hwColorPerVertexShader.cpp, hwDecalBumpShader_NV20.cpp, hwDecalBumpShader_NV20.h, hwPhongShader.cpp, hwPhongShader.h, hwReflectBumpShader_NV20.cpp, hwReflectBumpShader_NV20.h, hwRefractReflectShader_NV20.cpp, hwRefractReflectShader_NV20.h, hwToonShader_NV20.cpp, hwToonShader_NV20.h, hwUnlitShader.cpp, hwUnlitShader.h, lassoTool.cpp, lineManip.cpp, lineManip.h, lineManipContainer.cpp, lineManipContainer.h, marqueeTool.cpp, moveManip.cpp, moveNumericTool.cpp, moveTool.cpp, pnTrianglesNode.cpp, pnTrianglesNode.h, quadricShape.cpp, renderViewRenderCmd.cpp, renderViewRenderRegionCmd.cpp, rotateManip.cpp, simpleEmitter.cpp, simpleEmitter.h, squareScaleManip.cpp, squareScaleManip.h, squareScaleManipContext.cpp, squareScaleManipContext.h, surfaceBumpManip.cpp, swissArmyManip.cpp, torusField.cpp, torusField.h, viewCallbackTest.cpp, and viewCaptureCmd.cpp.


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 }
	Alignemnt values when drawing text. More...
enum	DisplayObjects { kDisplayEverything = 0, kDisplayNurbsCurves, kDisplayNurbsSurfaces, kDisplayMeshes, kDisplayPlanes, kDisplayLights, kDisplayCameras, kDisplayJoints, kDisplayIkHandles, kDisplayDeformers, kDisplayDynamics, kDisplayLocators, kDisplayDimensions, kDisplaySelectHandles, kDisplayPivots, kDisplayTextures, kDisplayGrid, kDisplayCVs, kDisplayHulls, kDisplayStrokes, kDisplaySubdivSurfaces }
	Display modes. More...
enum	LightingMode { kLightAll, kLightSelected, kLightActive, kLightDefault }
	Lighting mode used in this 3D view. More...
enum	RendererName { kDefaultQualityRenderer, kHighQualityRenderer, kExternalRenderer }
	Current hardware rendergn engine used in this view. More...
enum	DepthBufferFormat { kDepth_8 = 0, kDepth_Float }
	Possible depth buffer formats to read into. More...
Public Member Functions
void	getScreenPosition (int &x, int &y, MStatus *ReturnStatus=NULL) const
M3dWindow	window (MStatus *ReturnStatus=NULL)
int	portWidth (MStatus *ReturnStatus=NULL)
int	portHeight (MStatus *ReturnStatus=NULL)
MStatus	pushViewport (unsigned int x, unsigned int y, unsigned int width, unsigned int height)
MStatus	popViewport ()
MStatus	viewport (unsigned int &x, unsigned int &y, unsigned int &width, unsigned int &height) const
MStatus	beginGL ()
MStatus	endGL ()
void	beginSelect (GLuint *buffer=NULL, GLsizei size=0)
GLint	endSelect ()
bool	selectMode () const
bool	textureMode () const
void	loadName (GLuint name)
void	pushName (GLuint name)
void	popName ()
void	initNames ()
MStatus	beginOverlayDrawing ()
MStatus	endOverlayDrawing ()
MStatus	clearOverlayPlane ()
MStatus	setDrawColor (unsigned int index, ColorTable table=kActiveColors)
MStatus	setDrawColor (const MColor &color)
bool	isColorIndexMode (MStatus *ReturnStatus=NULL)
unsigned int	numDormantColors (MStatus *ReturnStatus=NULL)
unsigned int	numActiveColors (MStatus *ReturnStatus=NULL)
unsigned int	numUserDefinedColors (MStatus *ReturnStatus=NULL)
MStatus	setUserDefinedColor (unsigned int index, const MColor &color)
unsigned int	userDefinedColorIndex (unsigned int index, MStatus *ReturnStatus=NULL)
MColor	templateColor (MStatus *ReturnStatus=NULL)
MColor	backgroundColor (MStatus *ReturnStatus=NULL)
MColor	colorAtIndex (unsigned int index, ColorTable table=kActiveColors, MStatus *ReturnStatus=NULL)
MStatus	getColorIndexAndTable (unsigned int glindex, unsigned int &index, ColorTable &table) const
MStatus	colorMask (bool &r, bool &g, bool &b, bool &a)
MStatus	setColorMask (bool r, bool g, bool b, bool a)
MStatus	drawText (const MString &text, const MPoint position, TextPosition textPosition=kLeft)
MStatus	getCamera (MDagPath &camera)
MStatus	setCamera (MDagPath &camera)
MStatus	refresh (bool all=false, bool force=false)
MStatus	refresh (bool all, bool force, bool offscreen)
MStatus	refresh (MPxGlBuffer &buffer)
MStatus	refresh (MPxGlBuffer &buffer, bool offscreen)
MStatus	refresh (MPxGlBuffer &buffer, bool offscreen, const MMatrix &projectionMatrix)
MStatus	getLightCount (unsigned int &count, bool visible=TRUE)
MStatus	getLightingMode (LightingMode &mode)
MStatus	getLightPath (unsigned int lightNumber, MDagPath &light)
MStatus	isLightVisible (unsigned int lightNumber, bool &visible)
MStatus	getLightIndex (unsigned int lightNumber, unsigned int &lightIndex)
MStatus	viewToWorld (short x_pos, short y_pos, MPoint &worldPt, MVector &worldVector) const
MStatus	viewToWorld (short x_pos, short y_pos, MPoint &nearClipPt, MPoint &farClipPt) const
MStatus	viewToObjectSpace (short x_pos, short y_pos, const MMatrix &localMatrixInverse, MPoint &oPt, MVector &oVector) const
bool	worldToView (const MPoint &worldPt, short &x_pos, short &y_pos, MStatus *ReturnStatus=NULL) const
MStatus	projectionMatrix (MMatrix &projectionMatrix) const
MStatus	modelViewMatrix (MMatrix &modelViewMatrix) const
MString	viewSelectedPrefix (MStatus *ReturnStatus) const
MStatus	setViewSelectedPrefix (const MString &prefix)
bool	showViewSelectedChildren (MStatus *ReturnStatus) const
MStatus	setShowViewSelectedChildren (bool)
DisplayStyle	displayStyle (MStatus *ReturnStatus=NULL) const
bool	isShadeActiveOnly (MStatus *ReturnStatus=NULL) const
MStatus	setDisplayStyle (DisplayStyle style, bool activeOnly=false)
RendererName	getRendererName (MStatus *ReturnStatus) const
MString	rendererString (MStatus *ReturnStatus=NULL) const
bool	wireframeOnlyInShadedMode (MStatus *ReturnStatus) const
MStatus	readColorBuffer (MImage &image, bool readRGBA=false)
MStatus	writeColorBuffer (const MImage &image, signed short x=0, signed short y=0) const
MStatus	readDepthMap (unsigned short x, unsigned short y, unsigned int width, unsigned int height, unsigned char *bufferPtr, DepthBufferFormat depthMapPrecision)
MStatus	readBufferTo2dTexture (unsigned short x, unsigned short y, unsigned int width, unsigned int height)
bool	usingMipmappedTextures () const
MStatus	getRendererString (MString &stringName) const
	NO SCRIPT SUPPORT.
Static Public Member Functions
static M3dView	active3dView (MStatus *ReturnStatus=NULL)
static unsigned int	numberOf3dViews ()
static MStatus	get3dView (const unsigned int index, M3dView &view)
static MWindow	applicationShell (MStatus *ReturnStatus=NULL)
static MStatus	getM3dViewFromModelPanel (const MString &modelPaneName, M3dView &view)
static MStatus	getM3dViewFromModelEditor (const MString &modelPaneName, M3dView &view)

Member Enumeration Documentation

enum M3dView::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 M3dView::DisplayStatus

Drawing modes for individual objects.

Enumerator:

kActive	Object is active (selected).
kLive	Object is live (construction surface).
kDormant	Object is domant.
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.

Examples:

: simpleEmitter.cpp, simpleEmitter.h, torusField.cpp, and torusField.h.

enum M3dView::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 M3dView::TextPosition

Alignemnt 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 M3dView::DisplayObjects

Display modes.

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.
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.

enum M3dView::LightingMode

Lighting mode used in this 3D view.

Enumerator:

kLightAll	All lights ON mode.
kLightSelected	Selected lights ON mode.
kLightActive	Active lights ON mode.
kLightDefault	Default light ON mode.

enum M3dView::RendererName

Current hardware rendergn 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.
kExternalRenderer	An externally defined renderer name has been set.

enum M3dView::DepthBufferFormat

Possible depth buffer formats to read into.

Enumerator:

kDepth_8	8 bits.
kDepth_Float	Floating point.

Member Function Documentation

M3dView 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:

: cgfxShaderCmd.cpp, helixTool.cpp, hwPhongShader.cpp, lassoTool.cpp, marqueeTool.cpp, moveNumericTool.cpp, moveTool.cpp, renderViewRenderCmd.cpp, renderViewRenderRegionCmd.cpp, sampleCmd.cpp, sampleParticles.cpp, viewCaptureCmd.cpp, and zoomCameraCmd.cpp.

unsigned int M3dView::numberOf3dViews ( ) [static]

Returns the number of 3D views currently in existance.

Returns:: Number of 3D views.

MStatus M3dView::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

MWindow M3dView::applicationShell ( MStatus * ReturnStatus = NULL ) [static]

Returns the X display for this view.

The X display is neccessary for using openGL.

Parameters:

[out] ReturnStatus Status Code

Returns:: The X display

Status Codes:

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

Returns the GLXContext for this view.

This context is neccessary for using the offscreen rendering API to share textures and display lists with Maya.

Parameters:

[out] ReturnStatus Status Code

Returns:: The GLXContext

Status Codes:

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

Returns the Window handle for Maya. On Unix, this is an X Widget on Windows, this is an HWND on Macintosh this is a WindowRef.

This is necessary if you wish to open your own windows on top of Maya.

Parameters:

[out] ReturnStatus Status Code

Returns:: The window handle

Status Codes:

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

void M3dView::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

M3dWindow M3dView::window ( MStatus * ReturnStatus = NULL )

Returns the X window for this view.

The X window is neccessary for using openGL.

Parameters:

[out] ReturnStatus Status Code

Returns:: The X window

Status Codes:

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

int M3dView::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:

: viewCallbackTest.cpp, and viewCaptureCmd.cpp.

int M3dView::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:

: viewCallbackTest.cpp, and viewCaptureCmd.cpp.

MStatus M3dView::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:

: viewCallbackTest.cpp.

MStatus M3dView::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:

: viewCallbackTest.cpp.

MStatus M3dView::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

MStatus M3dView::beginGL ( )

Setup port for native OpenGL drawing calls.

Returns:: Status code

Status Codes:

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

Examples:

MStatus M3dView::endGL ( )

End OpenGL drawing.

Returns:: Status code

Status Codes:

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

Examples:

void M3dView::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:

: apiMeshShapeUI.cpp, and apiSimpleShapeUI.cpp.

GLint M3dView::endSelect ( )

Finish a selection sequence. Result is stored in the buffer passed in the beginSelect call.

Examples:

: apiMeshShapeUI.cpp, and apiSimpleShapeUI.cpp.

bool M3dView::selectMode ( ) const

Tells if this M3dView is in selection mode.

Returns:: true between beginSelect and endSelect calls.

bool M3dView::textureMode ( ) const

Tells if this M3dView is in texture mode.

Returns:: true if this modelling view is in texture mode.

void M3dView::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 M3dView::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.

void M3dView::popName ( )

Removes the top of the name stack. Valid only when beginSelect() has been called.

void M3dView::initNames ( )

Reset the name stack. Valid only when beginSelect() has been called.

MStatus M3dView::beginOverlayDrawing ( )

Setup the OpenGL context for drawing on the overlay plane.

The overlay plane is commonly used for drawing guidelines for tools.

Returns:: Status code

Status Codes:

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

MStatus M3dView::endOverlayDrawing ( )

Set the OpenGL context to for normal screen drawing.

Returns:: Status code

Status Codes:

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

MStatus M3dView::clearOverlayPlane ( )

Clear the overlay plane.

Returns:: Status code

Status Codes:

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

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

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:

: apiMeshShapeUI.cpp, curvedArrowsNode.cpp, cvColorNode.cpp, footPrintManip.cpp, footPrintNode.cpp, and swissArmyManip.cpp.

MStatus M3dView::setDrawColor ( const MColor & color )

Set the color to draw in. This method should only be used in RGBA mode. It is a convenient replacement for glColor.

Parameters:

[in] color color to draw in

Returns:: Status code

Status Codes:

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

bool M3dView::isColorIndexMode ( MStatus * ReturnStatus = NULL )

Returns true if this view is currently in the OpenGL color index mode. A false return means that it is in RGBA mode.

Parameters:

[out] ReturnStatus Status code

Returns:: Boolean indicating if color index mode is in use

Status Codes:

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

Examples:

: cvColorNode.cpp.

unsigned int M3dView::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 M3dView::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 M3dView::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 M3dView::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 M3dView::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 M3dView::templateColor ( MStatus * ReturnStatus = NULL )

Returns the RGB values of the template color.

Parameters:

[out] ReturnStatus Status code

Returns:: The template color

Status Codes:

MS::kSuccess Method was successful

MColor M3dView::backgroundColor ( MStatus * ReturnStatus = NULL )

Returns the RGB values of the active template color.

Parameters:

[out] ReturnStatus Status code

Returns:: The template color

Status Codes:

MS::kSuccess Method was successful

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

Returns the RGB values 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 M3dView::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 M3dView::colorMask	(	bool &	r,
		bool &	g,
		bool &	b,
		bool &	a
	)

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 M3dView::setColorMask	(	bool	r,
		bool	g,
		bool	b,
		bool	a
	)

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

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

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:

: apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, footPrintManip.cpp, lineManipContainer.cpp, moveManip.cpp, swissArmyManip.cpp, and viewCallbackTest.cpp.

MStatus M3dView::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:

: hwAnisotropicShader_NV20.cpp, hwDecalBumpShader_NV20.cpp, hwReflectBumpShader_NV20.cpp, hwRefractReflectShader_NV20.cpp, hwToonShader_NV20.cpp, lineManip.cpp, lineManipContainer.cpp, renderViewRenderCmd.cpp, renderViewRenderRegionCmd.cpp, sampleCmd.cpp, sampleParticles.cpp, squareScaleManip.cpp, and zoomCameraCmd.cpp.

MStatus M3dView::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 M3dView::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:

: viewCaptureCmd.cpp.

MStatus M3dView::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 M3dView::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 M3dView::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 M3dView::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 M3dView::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. Returned.
`[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:

: hwAnisotropicShader_NV20.cpp, and hwToonShader_NV20.cpp.

MStatus M3dView::getLightingMode ( M3dView::LightingMode & mode )

Get the current lighting mode for the view.

Parameters:

[out] mode The lighting mode for the view. Returned.

Returns:: Status code

Status Codes:

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

Examples:

: hwAnisotropicShader_NV20.cpp, and hwToonShader_NV20.cpp.

MStatus M3dView::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. Returned

Returns:: Status code

Status Codes:

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

Examples:

: hwAnisotropicShader_NV20.cpp, and hwToonShader_NV20.cpp.

MStatus M3dView::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. Returned

Returns:: Status code

Status Codes:

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

MStatus M3dView::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 M3dView::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

MStatus M3dView::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 M3dView::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 M3dView::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

MStatus M3dView::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

MStatus M3dView::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

MString M3dView::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 M3dView::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 M3dView::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::kSuccess Operation failed

MStatus M3dView::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 M3dView::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:

: viewCallbackTest.cpp.

MStatus M3dView::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 M3dView::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

bool M3dView::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 M3dView::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

M3dView::RendererName M3dView::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

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

MString M3dView::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 M3dView::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

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

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:

: viewCallbackTest.cpp.

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

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:

: viewCallbackTest.cpp.

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

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:

: viewCallbackTest.cpp.

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

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 M3dView::usingMipmappedTextures ( ) const

Returns if the view is using mipmapped texture display.

Returns:: Mipmap texture display state.

MStatus M3dView::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

M3dView Class Reference [OpenMayaUI - API module for user interface]

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Member Function Documentation

M3dView Class Reference
[OpenMayaUI - API module for user interface]