Public Types | Public Member Functions

MDrawTraversal Class Reference

This reference page is linked to from the following overview topics: 3.6 Render Loop Overrides.


Search for all occurrences

Detailed Description

A scene drawing traverser.

MDrawTraversal is a utility class for interactive drawing. The purpose of the class is to traverse through the current scene dag and provide a means of accessing a list of visible objects with respect to a given frustum specification, and application "visibility" criteria.

The additional "visibility" criteria include:

Note that as the traversal is not dependent on a 3d modeling viewport. There are thus no checks for per viewport visibility properties such as per viewport dag object type overrides, and "isolate select".

Additionally, render layer visibility checks are not performed, as these pertain to software rendering.

After traversal the list will contain leaf level nodes (shapes), which have passed the "visibility" criteria.

For the actual frustum culling, there is a choice of two culling algorithms:

Note that hierarchical culling may force evaluation of geometry on dag objects which are not visible.

The default is thus to perform leaf level culling only.

Frustum culling is performed against the bounding boxes of dag objects encountered.

API writers can derive from this class and change the filterNode() virtual method to perform custom filtering of objects during traversal. That is they will be excluded from the output list. By default this class does no additional filtering.

Examples:

D3DViewportRenderer.cpp, and OpenGLViewportRenderer.cpp.

#include <MDrawTraversal.h>

List of all members.

Public Types

enum  { kActiveItem, kTemplateItem }
 

Item status enum.

More...

Public Member Functions

 MDrawTraversal ()
 Default constructor.
virtual ~MDrawTraversal ()
 Default destructor.
virtual MStatus traverse ()
 Perform traversal of the current scene from the root of the dag hierarchy.
virtual bool filterNode (const MDagPath &traversalItem)
 Method to allow filtering during traversal.
MStatus setFrustum (const MDagPath &cameraPath, unsigned int portWidth, unsigned int portHeight)
 Set the frustum to cull with.
MStatus setOrthoFrustum (double left, double right, double bottom, double top, double nearpt, double farpt, const MMatrix &worldXform)
 Set up an orthographic view frustum to cull with.
MStatus setPerspFrustum (double fovX, double aspectXY, double nearDist, double farDist, const MMatrix &worldXform)
 Set up an perspective view frustum to cull with.
MStatus setFrustum (double left, double right, double bottom, double top, double nearpt, double farpt, const MMatrix &worldXform)
 Set up a frustum to cull with.
MStatus setFrustum (const MPoint &nearBottomLeft, const MPoint &nearBottomRight, const MPoint &nearTopLeft, const MPoint &nearTopRight, const MPoint &farBottomLeft, const MPoint &farBottomRight, const MPoint &farTopLeft, const MPoint &farTopRight, const MMatrix &worldXform)
 Set up a frustum to cull with by specifying the 8 corner points.
bool frustumValid () const
 Returns whether the current frustum set is valid or not.
void setLeafLevelCulling (bool cullAtLeafLevel)
 Set whether to cull at the leaf levels, or perform hierarchical culling.
bool leafLevelCulling () const
 Returns whether the current cull algorithm will cull at the leaf levels, or perform hierarchical culling.
void enableFiltering (bool val)
 Sets whether to use enable usage of the filterNode() method to perform custom filtering.
bool filteringEnabled () const
 Tells whether custom filtering has been enabled.
unsigned int numberOfItems () const
 Return the number of items found after traversal.
MStatus itemPath (unsigned int itemNumber, MDagPath &path) const
 Get the path for a given item in the list of found items after traversal.
bool itemHasStatus (unsigned int itemNumber, unsigned int test) const
 Test the display status for a given item in the list of found items after traversal.

Member Enumeration Documentation

anonymous enum

Item status enum.

Enumerator:
kActiveItem 

Check if item is active.

kTemplateItem 

Check if item is templated.


Constructor & Destructor Documentation

Default constructor.

Sets leaf level culling to be true by default, and filtering to be disabled.


Member Function Documentation

MStatus traverse ( ) [virtual]

Perform traversal of the current scene from the root of the dag hierarchy.

A valid frustum must be set before calling this method.

If the traversal was succesfull a list of traversal items will have been evaluated.

Returns:
MStatus::kSuccess if successful traversal.
Examples:
D3DViewportRenderer.cpp, and OpenGLViewportRenderer.cpp.
bool filterNode ( const MDagPath traversalItem) [virtual]

Method to allow filtering during traversal.

The traversalItem can be examined, and if it is not match the desired criteria, it will not be added to the output traversal list.

A return value of "false" will result in filtering out this item. A return value of "true" will result in regular filtering to occuring.

API writers can derive from MDrawTraversal, and implement their own filterNode() method to perform custom filtering as desired.

Parameters:
[in]traversalItempath to item to test.
Returns:
Will always return false for MDrawTraversal class.
Examples:
OpenGLViewportRenderer.cpp.
MStatus setFrustum ( const MDagPath cameraPath,
unsigned int  portWidth,
unsigned int  portHeight 
)

Set the frustum to cull with.

The frustum is based on the attributes of the camera argument provided.

Note that traversal always requries that a valid frustum to be set. There is no default frustum provided.

Parameters:
[in]cameraPathpath to a valid scene camera.
[in]portWidthwidth of the viewport to cull against.
[in]portHeightheight of the viewport to cull against.
Returns:
MStatus::kSuccess if successfully set.
Examples:
D3DViewportRenderer.cpp, and OpenGLViewportRenderer.cpp.
MStatus setOrthoFrustum ( double  left,
double  right,
double  bottom,
double  top,
double  nearpt,
double  farpt,
const MMatrix worldXform 
)

Set up an orthographic view frustum to cull with.

The frustum is symmetric about the vertical and horizontal.

Note that traversal always requries that a valid frustum to be set. There is no default frustum provided.

Parameters:
[in]leftLeft side of frustum (local space).
[in]rightRight side of frustum (local space).
[in]bottomBottom of frustum (local space).
[in]topTop of frustum (local space).
[in]nearptFront / near point of frustum (local space).
[in]farptBack / far point of frustum (local space).
[in]worldXformtransformation from local to world space.
Returns:
MStatus::kSuccess if successfully set.
MStatus setPerspFrustum ( double  fovX,
double  aspectXY,
double  nearDist,
double  farDist,
const MMatrix worldXform 
)

Set up an perspective view frustum to cull with.

The frustum is symmetric about the vertical and horizontal.

Note that traversal always requries that a valid frustum to be set. There is no default frustum provided.

Parameters:
[in]fovXField of view in X.
[in]aspectXYaspect ratio X / Y.
[in]nearDistdistance to near plane.
[in]farDistdistance to far plane.
[in]worldXformtransformation from local to world space.
Returns:
MStatus::kSuccess if successfully set.
MStatus setFrustum ( double  left,
double  right,
double  bottom,
double  top,
double  nearpt,
double  farpt,
const MMatrix worldXform 
)

Set up a frustum to cull with.

The frustum can be asymmetric is distance about the vertial and horizontal.

Note that traversal always requries that a valid frustum to be set. There is no default frustum provided.

Parameters:
[in]leftLeft side of frustum (local space).
[in]rightRight side of frustum (local space).
[in]bottomBottom of frustum (local space).
[in]topTop of frustum (local space).
[in]nearptFront / near point of frustum (local space).
[in]farptBack / far point of frustum (local space).
[in]worldXformtransformation from local to world space.
Returns:
MStatus::kSuccess if successfully set.
MStatus setFrustum ( const MPoint nearBottomLeft,
const MPoint nearBottomRight,
const MPoint nearTopLeft,
const MPoint nearTopRight,
const MPoint farBottomLeft,
const MPoint farBottomRight,
const MPoint farTopLeft,
const MPoint farTopRight,
const MMatrix worldXform 
)

Set up a frustum to cull with by specifying the 8 corner points.

Asymmetric frustum's can be set up using this method.

Note that traversal always requries that a valid frustum to be set. There is no default frustum provided.

Parameters:
[in]nearBottomLeftNear bottom left corner of frustum (local space).
[in]nearBottomRightNear bottom Right corner of frustum (local space).
[in]nearTopLeftNear top left corner of frustum (local space).
[in]nearTopRightNear top right corner of frustum (local space).
[in]farBottomLeftFar bottom left corner of frustum (local space).
[in]farBottomRightFar bottom right corner of frustum (local space).
[in]farTopLeftFar top left corner of frustum (local space).
[in]farTopRightFar top right corner of frustum (local space).
[in]worldXformtransformation from local to world space.
Returns:
MStatus::kSuccess if successfully set.
bool frustumValid ( ) const

Returns whether the current frustum set is valid or not.

If it is not valid a call to the traverse() function will result in returning failure.

Returns:
true if frustum is valid.
Examples:
D3DViewportRenderer.cpp, and OpenGLViewportRenderer.cpp.
void setLeafLevelCulling ( bool  cullAtLeafLevel)

Set whether to cull at the leaf levels, or perform hierarchical culling.

This value should be set before traversing using the traverse() function.

If a value is not explicitly set, the default is to perform culling at the leaf levels only.

Parameters:
[in]cullAtLeafLevelflag to indicate culling preference.
Returns:
MStatus::kSuccess if successfully set.
bool leafLevelCulling ( ) const

Returns whether the current cull algorithm will cull at the leaf levels, or perform hierarchical culling.

The default value is leaf level culling.

Returns:
true if peforming leaf level culling.
void enableFiltering ( bool  val)

Sets whether to use enable usage of the filterNode() method to perform custom filtering.

By default this is set to false.

Filtering must be enabled for filterNode() to be called during traversal.

Parameters:
[in]valvalue for enabling.
Examples:
D3DViewportRenderer.cpp, and OpenGLViewportRenderer.cpp.
bool filteringEnabled ( ) const

Tells whether custom filtering has been enabled.

That is, to use the filterNode() method during traversal.

By default this is set to false.

Filtering must be enabled for filterNode() to be called during traversal.

Returns:
true if filtering is enabled.
unsigned int numberOfItems ( ) const

Return the number of items found after traversal.

Returns:
Number of items.
Examples:
D3DViewportRenderer.cpp, and OpenGLViewportRenderer.cpp.
MStatus itemPath ( unsigned int  itemNumber,
MDagPath path 
) const

Get the path for a given item in the list of found items after traversal.

Parameters:
[in]itemNumberwhich item to return.
[out]pathpath of item (returned).
Returns:
MStatus::kSuccess if the given element was present in the list.
Examples:
D3DViewportRenderer.cpp, and OpenGLViewportRenderer.cpp.
bool itemHasStatus ( unsigned int  itemNumber,
unsigned int  test 
) const

Test the display status for a given item in the list of found items after traversal.

Parameters:
[in]itemNumberwhich item to return.
[in]testthe display status to check the item against.
Returns:
true, if item status matches the display status to test against.
Examples:
D3DViewportRenderer.cpp, and OpenGLViewportRenderer.cpp.

MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal
MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal MDrawTraversal