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

#include <M3dView.h>

List of all members.


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 }
  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, kDisplayLocators = 1 << 10,
   kDisplayDimensions = 1 << 11, kDisplaySelectHandles = 1 << 12, kDisplayPivots = 1 << 13, kDisplayTextures = 1 << 14,
   kDisplayGrid = 1 << 15, kDisplayCVs = 1 << 16, kDisplayHulls = 1 << 17, kDisplayStrokes = 1 << 18,
   kDisplaySubdivSurfaces = 1 << 19, kDisplayFluids = 1 << 20, kDisplayFollicles = 1 << 21, kDisplayHairSystems = 1 << 22,
   kDisplayImagePlane = 1 << 23, kDisplayNCloths = 1 << 24, kDisplayNRigids = 1 << 25, kDisplayDynamicConstraints = 1 << 26,
   kDisplayManipulators = 1 << 27, kDisplayNParticles = 1 << 28
}
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...
enum   LineStipplePattern { kStippleNone, kStippleDashed }
  Line stipple pattern. More...

Public Member Functions

MGLContext  display (MStatus *ReturnStatus=NULL)
  Mac OS X and Windows.
void  getScreenPosition (int &x, int &y, MStatus *ReturnStatus=NULL) const
QWidget *  widget (MStatus *ReturnStatus=NULL) const
MNativeWindowHdl  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  beginXorDrawing (bool drawOrthographic=true, bool disableDepthTesting=true, float lineWidth=1.0f, LineStipplePattern stipplePattern=kStippleNone, const MColor &lineColor=MColor(1, 1, 1))
MStatus  endXorDrawing ()
MStatus  beginOverlayDrawing ()
MStatus  endOverlayDrawing ()
MStatus  clearOverlayPlane ()
MStatus  setDrawColor (unsigned int index, ColorTable table=kActiveColors)
MStatus  setDrawColor (const MColor &color)
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)
MStatus  setObjectDisplay (unsigned int displayMask)
unsigned int  objectDisplay (MStatus *ReturnStatus=NULL)
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
bool  usingDefaultMaterial () const
MStatus  updateViewingParameters ()
bool  multipleDrawEnabled () const
void  setMultipleDrawEnable (bool enable)
unsigned  multipleDrawPassCount ()
void  setMultipleDrawPassCount (unsigned count)
MStatus  beginProjMatrixOverride (MMatrix &projectionMatrix)
MStatus  endProjMatrixOverride ()
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 MNativeWindowHdl  applicationShell (MStatus *ReturnStatus=NULL)
static MStatus  getM3dViewFromModelPanel (const MString &modelPaneName, M3dView &view)
static MStatus  getM3dViewFromModelEditor (const MString &modelPaneName, M3dView &view)

Member Enumeration Documentation

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.

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:

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.

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.

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

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.

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.

Possible depth buffer formats to read into.

Enumerator:
kDepth_8  8 bits.
kDepth_Float  Floating point.

Line stipple pattern.

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

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

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:

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

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

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:

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

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

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

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

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

MStatus M3dView::popViewport (  ) 

Pop the current viewport off of the viewport stack.

Returns:
Status code
Status Codes:
Examples:

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:

MStatus M3dView::beginGL (  ) 

MStatus M3dView::endGL (  ) 

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:

GLint M3dView::endSelect (  ) 

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

Examples:

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

MStatus M3dView::endXorDrawing (  ) 

Set the context for non-exclusive-or (non-XOR) screen drawing.

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

Returns:
Status code
Status Codes:

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:

MStatus M3dView::endOverlayDrawing (  ) 

Set the OpenGL context to for normal screen drawing.

Returns:
Status code
Status Codes:

MStatus M3dView::clearOverlayPlane (  ) 

Clear the overlay plane.

Returns:
Status code
Status Codes:

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

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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

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:

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

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:

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:

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:

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:

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.
[in]  visible  Specify whether to count visible lights only. By Default this is set true.
Returns:
Status code
Status Codes:
Examples:

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

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.
Returns:
Status code
Status Codes:
Examples:

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.
Returns:
Status code
Status Codes:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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:

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:

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:

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:

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

unsigned int M3dView::objectDisplay ( MStatus ReturnStatus = NULL  ) 

Returns a display object mask that indicates which object types are drawn in 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:

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:

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:

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:

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

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

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

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:

bool M3dView::usingMipmappedTextures (  )  const

Returns if the view is using mipmapped texture display.

Returns:
Mipmap texture display state.

bool M3dView::usingDefaultMaterial (  )  const

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

Returns:
The default material state.
Examples:

MStatus M3dView::updateViewingParameters (  ) 

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

Returns:
Status code
Status Codes:

bool M3dView::multipleDrawEnabled (  )  const

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

Returns:
  • true if multiple draw is enabled.

void M3dView::setMultipleDrawEnable ( bool  enable  ) 

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

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 M3dView::setMultipleDrawPassCount ( unsigned  count  ) 

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 M3dView::beginProjMatrixOverride ( MMatrix projectionMatrix  ) 

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:

MStatus M3dView::endProjMatrixOverride (  ) 

End projection matrix override enabled by beginProjMatrixOverride().

Returns:
Status code
Status Codes:

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:

Autodesk® Maya® 2011 © 1997-2010 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6