MDrawContext Class Reference

MDrawContext Class Reference
+ Related help topics:

#include <MDrawContext.h>

Class Description

Class to allow access to hardware draw context information.

MDrawContext provides access to current hardware draw context information. It is read-only and cannot be instantiated by the plugin writer.

The information provided includes various transformation matrices, camera information, and render target information such as output buffer size. It is also possible to access and alter GPU state through this class.

There are a few main advantages for using this class:

1. The data is computed and cached as required. This can avoid work for the plugin writer to extract this information themselves. 2. The plugin writer should not need to directly access the device to extract this information. Any data extraction from the device has a performance penalty which can be avoided. 3. The information is device aware, meaning that it will return the correct results based on the current active device. For example it will return the appropriate values for DirectX versus an OpenGL device.

MDrawContext is derived from MFrameContext and provides its own implementation for all virtual methods. The values returned from these methods may differ slightly between MFrameContext and MDrawContext as MFrameContext retrieves the values from Maya and MDrawContext retrieves the values from the GPU device state.

Some information will vary from one draw to the next draw such as the object-to-world matrix which will change as different objects are being drawn.

+ Examples:
+ Inheritance diagram for MDrawContext:

Public Types

enum  LightFilter { kFilteredToLightLimit, kFilteredIgnoreLightLimit }
 Options on which lights to return information for from light query methods. More...
 
enum  InternalTexture {
  kDepthPeelingTranspDepthTexture = 0, kDepthPeelingOpaqueDepthTexture, kIrradianceEnvironment, kSpecularEnvironment,
  kNumberOfInternalTextures
}
 Options on which internal texture to get. More...
 
- Public Types inherited from MFrameContext
enum  MatrixType {
  kWorldMtx, kWorldTransposeMtx, kWorldInverseMtx, kWorldTranspInverseMtx,
  kViewMtx, kViewTransposeMtx, kViewInverseMtx, kViewTranspInverseMtx,
  kProjectionMtx, kProjectionTranposeMtx, kProjectionInverseMtx, kProjectionTranspInverseMtx,
  kViewProjMtx, kViewProjTranposeMtx, kViewProjInverseMtx, kViewProjTranspInverseMtx,
  kWorldViewMtx, kWorldViewTransposeMtx, kWorldViewInverseMtx, kWorldViewTranspInverseMtx,
  kWorldViewProjMtx, kWorldViewProjTransposeMtx, kWorldViewProjInverseMtx, kWorldViewProjTranspInverseMtx
}
 Matrices that can be accessed. More...
 
enum  TupleType {
  kViewPosition, kViewDirection, kViewUp, kViewRight,
  kViewportPixelSize, kViewNearClipValue, kViewFarClipValue, kViewUnnormlizedNearClipValue,
  kViewUnnormalizedFarClipValue
}
 Tuples that can be accessed. May be one or more values returned depending on the tuple requested. More...
 
enum  DisplayStyle {
  kGouraudShaded = (0x1), kWireFrame = (0x1 << 1), kBoundingBox = (0x1 << 2), kTextured = (0x1 << 3),
  kDefaultMaterial = (0x1 << 4), kXrayJoint = (0x1 << 5), kXray = (0x1 << 6), kTwoSidedLighting = (0x1 << 7),
  kFlatShaded = (0x1 << 8), kShadeActiveOnly = (0x1 << 9), kXrayActiveComponents = (0x1 << 10), kBackfaceCulling = (0x1 << 11),
  kSmoothWireframe = (0x1 << 12)
}
 Display styles. More...
 
enum  LightingMode {
  kNoLighting, kAmbientLight, kLightDefault, kSelectedLights,
  kSceneLights, kCustomLights
}
 Lighting modes. More...
 
enum  PostEffectType {
  kAmbientOcclusion, kMotionBlur, kGammaCorrection, kViewColorTransformEnabled = kGammaCorrection,
  kDepthOfField, kAntiAliasing
}
 Types of post effects which may be enabled during rendering. More...
 
enum  FogMode { kFogLinear, kFogExp, kFogExp2 }
 Types of the fog mode. More...
 
enum  TransparencyAlgorithm { kUnsorted = 0, kObjectSorting, kWeightedAverage, kDepthPeeling }
 Options for transparency algorithm. More...
 
enum  WireOnShadedMode { kWireframeOnShadedFull, kWireFrameOnShadedReduced, kWireFrameOnShadedNone }
 Wireframe on shaded modes. More...
 
enum  RenderingDestination { k3dViewport, k2dViewport, kImage }
 Rendering destinations. More...
 

Public Member Functions

virtual MMatrix getMatrix (MFrameContext::MatrixType mtype, MStatus *ReturnStatus=NULL) const
 Get a matrix value of a certain type. More...
 
virtual MDoubleArray getTuple (MFrameContext::TupleType ttype, MStatus *ReturnStatus=NULL) const
 Get a tuple (vector, position, or single) value of a certain type. More...
 
virtual MStatus getViewportDimensions (int &originX, int &originY, int &width, int &height) const
 Get the viewport dimensions. More...
 
MUint64 getFrameStamp () const
 Returns the current frame stamp. More...
 
MBoundingBox getSceneBox (MStatus *ReturnStatus=NULL) const
 Get a bounding box of the scene in world space. More...
 
MBoundingBox getFrustumBox (MStatus *ReturnStatus) const
 Get the bounding box of the current view frustum in world space. More...
 
MStatus getRenderTargetSize (int &width, int &height) const
 Get the size of the render target (output buffer) being rendered into. More...
 
MStatus getDepthRange (float &nearVal, float &farVal) const
 Get the depth range which specifies the mapping of depth values from normalized device coordinates to window coordinates. More...
 
bool viewDirectionAlongNegZ (MStatus *ReturnStatus) const
 Return whether the view direction is pointing down the -Z axis. More...
 
unsigned int numberOfActiveLights (LightFilter lightFilter=kFilteredToLightLimit, MStatus *ReturnStatus=NULL) const
 Return the number of available lights to render the scene. More...
 
MStatus getLightInformation (unsigned int lightNumber, MFloatPointArray &positions, MFloatVector &direction, float &intensity, MColor &color, bool &hasDirection, bool &hasPosition, LightFilter lightFilter=kFilteredToLightLimit) const
 Return common lighting information for a given active light. More...
 
MLightParameterInformationgetLightParameterInformation (unsigned int lightNumber, LightFilter lightFilter=kFilteredToLightLimit) const
 Return parameter information for a given active light. More...
 
MHWRender::MStateManagergetStateManager () const
 Access the GPU state manager for the current draw context. More...
 
const MHWRender::MPassContextgetPassContext () const
 Access the current pass context. More...
 
const MRenderTargetcopyCurrentColorRenderTarget (const MString &name) const
 Get a copy of the current color render target. More...
 
const MRenderTargetcopyCurrentDepthRenderTarget (const MString &name) const
 Get a copy of the current depth render target. More...
 
MTexturecopyCurrentColorRenderTargetToTexture () const
 Get a copy of the current color render target as a texture. More...
 
MTexturecopyCurrentDepthRenderTargetToTexture () const
 Get a copy of the current depth render target as a texture. More...
 
const MTexturegetInternalTexture (InternalTexture internalTexture) const
 Returns the internal texture as specified. More...
 
bool isMultiDraw () const
 Returns true if the context is rendering in MultiDraw mode. More...
 
unsigned int numberOfActiveLights (MStatus *ReturnStatus) const
 
- Public Member Functions inherited from MFrameContext
virtual float getGlobalLineWidth () const
 Get global line width. More...
 
MDagPath getCurrentCameraPath (MStatus *ReturnStatus=NULL) const
 Get the path to the camera being used to render the current frame. More...
 
const MRenderTargetgetCurrentColorRenderTarget () const
 Get current color render target. More...
 
const MRenderTargetgetCurrentDepthRenderTarget () const
 Get current depth render target. More...
 
unsigned int getDisplayStyle () const
 Get the current display style as a bit field. More...
 
LightingMode getLightingMode () const
 Get the current light mode. More...
 
unsigned int getLightLimit () const
 Get the current light limit. More...
 
EnvironmentParams getEnvironmentParameters () const
 Get parameters for currently used environment. More...
 
bool getPostEffectEnabled (PostEffectType postEffectType) const
 Returns if a given post effect is currently enabled. More...
 
HwFogParams getHwFogParameters () const
 Get all the hardware fog parameters. More...
 
TransparencyAlgorithm getTransparencyAlgorithm () const
 Get the current transparency algoritm. More...
 
RenderingDestination renderingDestination (MString &destinationName) const
 Return value indicates the destination that the renderer is drawing to. More...
 
MUint64 objectTypeExclusions () const
 Get the object type exclusions as a bitfield. More...
 
void classificationExclusions (MStringArray &classification) const
 Get a list of drawdb strings for object which are excluded from display. More...
 
void getBackgroundParameters (MFrameContext::BackgroundParams &params) const
 Get parameters related to how the background is cleared. More...
 
void getDOFParameters (MFrameContext::DOFParams &params) const
 Get the parameters generated by Maya for the circle-of-confusion depth shader used for a pass used when computing depth of field. More...
 
void getRenderOverrideInformation (RenderOverrideInformation &info) const
 Get information about any render override. More...
 
void worldToViewport (const MPoint &inPoint, double &xPos, double &yPos) const
 Convert coordinate in world space to coordinate in viewport. More...
 
void viewportToWorld (double xPos, double yPos, MPoint &worldNearPt, MPoint &worldFarPt) const
 Convert coordinate in viewport to near cliping plane coordinate in world space. More...
 

Static Public Member Functions

static const char * className ()
 Returns the name of this class. More...
 
- Static Public Member Functions inherited from MFrameContext
static MFrameContext::MatrixType semanticToMatrixType (const MString &value, MStatus *ReturnStatus=NULL)
 Given a semantic name return the corresponding matrix enumeration that can be used to retrieve a matrix value via the getMatrix() method. More...
 
static MFrameContext::TupleType semanticToTupleType (const MString &value, MStatus *ReturnStatus=NULL)
 Given a semantic name return the corresponding tuple enumeration that can be used to retrieve a value via the getTuple() method. More...
 
static bool inUserInteraction ()
 Returns true during any interactive refresh, as when user is interacting with the scene in any way including camera changes, object or component TRS changes, etc. More...
 
static bool userChangingViewContext ()
 Returns true during any interactive refresh, as when user is changing the view using view context tools such as tumble, dolly or track. More...
 
static WireOnShadedMode wireOnShadedMode ()
 Returns the global user display preference which indicates how wireframe should be drawn on top of objects while in shaded mode. More...
 
static bool shadeTemplates ()
 Returns the display preference indicating whether templated objects should be drawn shaded. More...
 
static const char * className ()
 Returns the name of this class. More...
 

Additional Inherited Members

- Static Public Attributes inherited from MFrameContext
static MUint64 kExcludeNone = 0
 Exclude no object types.
 
static MUint64 kExcludeNurbsCurves = MUint64(1)<<(0)
 Exclude NURBS curves.
 
static MUint64 kExcludeNurbsSurfaces = MUint64(1)<<(1)
 Exclude NURBS surface.
 
static MUint64 kExcludeMeshes = MUint64(1)<<(2)
 Exclude polygonal meshes.
 
static MUint64 kExcludePlanes = MUint64(1)<<(3)
 Exclude planes.
 
static MUint64 kExcludeLights = MUint64(1)<<(4)
 Exclude lights.
 
static MUint64 kExcludeCameras = MUint64(1)<<(5)
 Exclude camera.
 
static MUint64 kExcludeJoints = MUint64(1)<<(6)
 Exclude joints.
 
static MUint64 kExcludeIkHandles = MUint64(1)<<(7)
 Exclude IK handles.
 
static MUint64 kExcludeDeformers = MUint64(1)<<(8)
 Exclude all deformations.
 
static MUint64 kExcludeDynamics = MUint64(1)<<(9)
 Exclude all dynamics objects (emiiters, cloth)
 
static MUint64 kExcludeParticleInstancers = MUint64(1)<<(10)
 Exclude all Particle Instancers.
 
static MUint64 kExcludeLocators = MUint64(1)<<(11)
 Exclude locators.
 
static MUint64 kExcludeDimensions = MUint64(1)<<(12)
 Exclude all measurement objects.
 
static MUint64 kExcludeSelectHandles = MUint64(1)<<(13)
 Exclude selection handles.
 
static MUint64 kExcludePivots = MUint64(1)<<(14)
 Exclude pivots.
 
static MUint64 kExcludeTextures = MUint64(1)<<(15)
 Exclude texure placement objects.
 
static MUint64 kExcludeGrid = MUint64(1)<<(16)
 Exclude grid drawing.
 
static MUint64 kExcludeCVs = MUint64(1)<<(17)
 Exclude NURBS control vertices.
 
static MUint64 kExcludeHulls = MUint64(1)<<(18)
 Exclude NURBS hulls.
 
static MUint64 kExcludeStrokes = MUint64(1)<<(19)
 Exclude PaintFX strokes.
 
static MUint64 kExcludeSubdivSurfaces = MUint64(1)<<(20)
 Exclude subdivision surfaces.
 
static MUint64 kExcludeFluids = MUint64(1)<<(21)
 Exclude fluid objects.
 
static MUint64 kExcludeFollicles = MUint64(1)<<(22)
 Exclude hair follicles.
 
static MUint64 kExcludeHairSystems = MUint64(1)<<(23)
 Exclude hair system.
 
static MUint64 kExcludeImagePlane = MUint64(1)<<(24)
 Exclude image planes.
 
static MUint64 kExcludeNCloths = MUint64(1)<<(25)
 Exclude N-cloth objects.
 
static MUint64 kExcludeNRigids = MUint64(1)<<(26)
 Exclude rigid-body objects.
 
static MUint64 kExcludeDynamicConstraints = MUint64(1)<<(27)
 Exclude rigid-body constraints.
 
static MUint64 kExcludeManipulators = MUint64(1)<<(28)
 Exclude manipulators.
 
static MUint64 kExcludeNParticles = MUint64(1)<<(29)
 Exclude N-particle objects.
 
static MUint64 kExcludeMotionTrails = MUint64(1)<<(30)
 Exclude motion trails.
 
static MUint64 kExcludeHoldOuts = MUint64(1)<<(31)
 Exclude Hold-Outs.
 
static MUint64 kExcludePluginShapes = MUint64(1)<<(32)
 Exclude plug-in shapes.
 
static MUint64 kExcludeHUD = MUint64(1)<<(33)
 Exclude HUD.
 
static MUint64 kExcludeClipGhosts = MUint64(1)<<(34)
 Exclude animation clip ghosts.
 
static MUint64 kExcludeGreasePencils = MUint64(1)<<(35)
 Exclude grease-pencil draw.
 
static MUint64 kExcludeAll = ~0
 Exclude all listed object types.
 

Member Enumeration Documentation

Options on which lights to return information for from light query methods.

Enumerator
kFilteredToLightLimit 

Return light information for lights which pass the VP2.0 filter options.

The number of lights accessible is clamped to the VP2.0 light limit option.

kFilteredIgnoreLightLimit 

Return light information for lights which pass the VP2.0 filter options.

The number of lights accessible ignores the VP2.0 light limit option.

Options on which internal texture to get.

Enumerator
kDepthPeelingTranspDepthTexture 

Depth texture of current transparent layer in depth-peeling transparency.

kDepthPeelingOpaqueDepthTexture 

Depth texture of all opaque objects in depth-peeling transparency.

kIrradianceEnvironment 

Irradiance environment map.

kSpecularEnvironment 

Specular environment map.

kNumberOfInternalTextures 

Number of internal textures, not to be used to describe an internal texture.

Member Function Documentation

MMatrix getMatrix ( MFrameContext::MatrixType  mtype,
MStatus ReturnStatus = NULL 
) const
virtual

Get a matrix value of a certain type.

Parameters
[in]mtypeType of matrix to return
[out]ReturnStatusReturn status
Returns
The requested matrix
Status Codes:

Reimplemented from MFrameContext.

+ Examples:
MDoubleArray getTuple ( MFrameContext::TupleType  ttype,
MStatus ReturnStatus = NULL 
) const
virtual

Get a tuple (vector, position, or single) value of a certain type.

Parameters
[in]ttypeType of information to return
[out]ReturnStatusReturn status
Returns
The requested tuple
Status Codes:

Reimplemented from MFrameContext.

+ Examples:
MStatus getViewportDimensions ( int &  originX,
int &  originY,
int &  width,
int &  height 
) const
virtual

Get the viewport dimensions.

The origin is the upper left corner of the viewport.

Parameters
[out]originXX coordinate of the viewport origin
[out]originYY coordinate of the viewport origin
[out]widthWidth of the viewport
[out]heightHeight of the viewport
Returns
Status code
Status Codes:

Reimplemented from MFrameContext.

+ Examples:
MUint64 getFrameStamp ( ) const

Returns the current frame stamp.

Returns
Unique render ID
+ Examples:
MBoundingBox getSceneBox ( MStatus ReturnStatus = NULL) const

Get a bounding box of the scene in world space.

Parameters
[out]ReturnStatusreturn status
Returns
The world space scene bounding box.
Status Codes:
+ Examples:
MBoundingBox getFrustumBox ( MStatus ReturnStatus) const

Get the bounding box of the current view frustum in world space.

Parameters
[out]ReturnStatusreturn status
Returns
The world space bounding box for the view frustum
Status Codes:
+ Examples:
MStatus getRenderTargetSize ( int &  width,
int &  height 
) const

Get the size of the render target (output buffer) being rendered into.

The dimensions of the target are in pixels.

Parameters
[out]widthWidth of the render target
[out]heightHeight of the render target
Returns
Status code
Status Codes:
+ Examples:
MStatus getDepthRange ( float &  nearVal,
float &  farVal 
) const

Get the depth range which specifies the mapping of depth values from normalized device coordinates to window coordinates.

The depth range values are normally 0.0 and 1.0.

Parameters
[out]nearValSpecifies the near clipping plane
[out]farValSpecifies the far clipping plane
Returns
Status code
Status Codes:
+ Examples:
bool viewDirectionAlongNegZ ( MStatus ReturnStatus) const

Return whether the view direction is pointing down the -Z axis.

Different devices will have difference conventions. For OpenGL the conventions is -Z. For DirectX the convention is +Z.

Parameters
[out]ReturnStatusreturn status
Returns
True if the view direction is pointing down the -Z axis.
Status Codes:
+ Examples:
unsigned int numberOfActiveLights ( LightFilter  lightFilter = kFilteredToLightLimit,
MStatus ReturnStatus = NULL 
) const

Return the number of available lights to render the scene.

This method takes into consideration the VP2.0 lighting mode options, whether lights are visible, and whether the light is a member of the default light set (illuminates by default).

When the light mode is set to use all lights, if the lightFilter argument is set to be 'kFilteredIgnoreLightLimit', then the light limit value in the VP2.0 settings will be ignored. Otherwise the value returned is clamped to the light limit.

Parameters
[in]lightFilterOnly consider lights which pass this filter option. The default value is kFilteredToLightLimit.
[out]ReturnStatusreturn status
Returns
The number of active lights.
Status Codes:
+ Examples:
MStatus getLightInformation ( unsigned int  lightNumber,
MFloatPointArray positions,
MFloatVector direction,
float &  intensity,
MColor color,
bool &  hasDirection,
bool &  hasPosition,
LightFilter  lightFilter = kFilteredToLightLimit 
) const

Return common lighting information for a given active light.

Note that any ambient lighting information is returned as the last light.

Parameters
[in]lightNumberLight index number starting from 0 to the number of lights returned from numberOfActiveLights() minus one. Index 0 indicates the first light. There is no correspondance to fixed-function OpenGL light indices.
[out]positionsThe world space positions on a light. If a light is purely directional or represents ambient lighting then the position value has no meaning and the return value will be an empty array. In all other cases except for area lights a single position entry will be returned. Multiple positions are returned to represent different sample points on area lights.
[out]directionThe world space direction of the light. If a light is purely positional or represents ambient lighting then the direction value has no meaning and will be set to a value of (0,0,0,1).
[out]intensityThe intensity of the light.
[out]colorThe color value of the light.
[out]hasDirectionThis will indicate if the light has any directional properties.
[out]hasPositionThis will indicate if the light has any positional properties.
[in]lightFilterOnly consider lights which pass this filter option. The default value is kFilteredToLightLimit.
Returns
Status code
Status Codes:
+ Examples:
MLightParameterInformation * getLightParameterInformation ( unsigned int  lightNumber,
LightFilter  lightFilter = kFilteredToLightLimit 
) const

Return parameter information for a given active light.

Parameters
[in]lightNumberLight index number starting from 0 to the number of lights returned from numberOfActiveLights() minus one. Index 0 indicates the first light. There is no correspondance to fixed-function OpenGL light indices.
[in]lightFilterOnly consider lights which pass this filter option. The default value is kFilteredToLightLimit.
Returns
Light information instance
+ Examples:
const MRenderTarget * copyCurrentColorRenderTarget ( const MString name) const

Get a copy of the current color render target.

When the object is no longer needed, MRenderTargetManager::releaseRenderTarget() should be called to notify the target manager that the caller is done with the render target.

Parameters
[in]nameUnique name for copy. A non-empty string must be provided otherwise the method will fail.
Returns
Copy of the current color target
const MRenderTarget * copyCurrentDepthRenderTarget ( const MString name) const

Get a copy of the current depth render target.

When the object is no longer needed, MRenderTargetManager::releaseRenderTarget() should be called to notify the target manager that the caller is done with the render target.

Parameters
[in]nameUnique name for copy. A non-empty string must be provided otherwise the method will fail.
Returns
Copy of the current depth target
MTexture * copyCurrentColorRenderTargetToTexture ( ) const

Get a copy of the current color render target as a texture.

When the texture is no longer needed, MTextureManager::releaseTexture() should be called.

Returns
Copy of the current depth target
+ Examples:
MTexture * copyCurrentDepthRenderTargetToTexture ( ) const

Get a copy of the current depth render target as a texture.

When the texture is no longer needed, MTextureManager::releaseTexture() should be called.

Returns
Copy of the current depth target
+ Examples:
const MTexture * getInternalTexture ( InternalTexture  internalTexture) const

Returns the internal texture as specified.

The internal texture is owned by MDrawContext and only valid during the lifetime of the MDrawContext object.

Parameters
[in]internalTextureSpecifies which internal texture to get.
Returns
Internal texture.
+ Examples:
bool isMultiDraw ( ) const

Returns true if the context is rendering in MultiDraw mode.

Returns
true if the context is rendering in MultiDraw mode.
+ Examples:
const char * className ( )
static

Returns the name of this class.

Returns
Name of this class.
unsigned int numberOfActiveLights ( MStatus ReturnStatus) const
Deprecated:

In place of this method the following interface should be used instead:

unsigned int numberOfActiveLights(LightFilter lightFilter, MStatus* ReturnStatus) const;

Parameters
[out]ReturnStatusreturn status
Returns
The number of active lights.
Status Codes:

The documentation for this class was generated from the following files:
  • MDrawContext.h
  • MDrawContext.cpp