MDrawTraversal Class Reference

#include <MDrawTraversal.h>

Class Description

This method is obsolete.

Deprecated:

Use MHWRender::MSceneRender and MHWRender::MRenderOverride instead.

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:

• Visibility overrides set per object .
• Visibility overrides set per application (global display settings) .
• Visibility overrides set per display layer (global display settings).

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:

• Perform culling tests only when leaf level dag objects (shapes) are encountered.
• Perform hierarchical culling (cull sub-trees) as they are encountered.

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:

Public Types
enum	{ kActiveItem, kTemplateItem }
	Item status enum. More...

Public Member Functions
	MDrawTraversal ()
	Default constructor. More...
virtual	~MDrawTraversal ()
	Default destructor.
virtual MStatus	traverse ()
	Perform traversal of the current scene from the root of the dag hierarchy. More...
virtual bool	filterNode (const MDagPath &traversalItem)
	Method to allow filtering during traversal. More...
MStatus	setFrustum (const MDagPath &cameraPath, unsigned int portWidth, unsigned int portHeight)
	Set the frustum to cull with. More...
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. More...
MStatus	setPerspFrustum (double fovX, double aspectXY, double nearDist, double farDist, const MMatrix &worldXform)
	Set up an perspective view frustum to cull with. More...
MStatus	setFrustum (double left, double right, double bottom, double top, double nearpt, double farpt, const MMatrix &worldXform)
	Set up a frustum to cull with. More...
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. More...
bool	frustumValid () const
	Returns whether the current frustum set is valid or not. More...
void	setLeafLevelCulling (bool cullAtLeafLevel)
	Set whether to cull at the leaf levels, or perform hierarchical culling. More...
bool	leafLevelCulling () const
	Returns whether the current cull algorithm will cull at the leaf levels, or perform hierarchical culling. More...
void	enableFiltering (bool val)
	Sets whether to use enable usage of the filterNode() method to perform custom filtering. More...
bool	filteringEnabled () const
	Tells whether custom filtering has been enabled. More...
unsigned int	numberOfItems () const
	Return the number of items found after traversal. More...
MStatus	itemPath (unsigned int itemNumber, MDagPath &path) const
	Get the path for a given item in the list of found items after traversal. More...
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. More...

Member Enumeration Documentation

anonymous enum

Item status enum.

Enumerator
kActiveItem	Check if item is active.
kTemplateItem	Check if item is templated.

Constructor & Destructor Documentation

OPENMAYA_MAJOR_NAMESPACE_OPEN MDrawTraversal

(

)

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:

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]

traversalItem

path to item to test.

Returns

Will always return false for MDrawTraversal class.

Examples:

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]	cameraPath	path to a valid scene camera.
[in]	portWidth	width of the viewport to cull against.
[in]	portHeight	height of the viewport to cull against.

Returns

MStatus::kSuccess if successfully set.

Examples:

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]	left	Left side of frustum (local space).
[in]	right	Right side of frustum (local space).
[in]	bottom	Bottom of frustum (local space).
[in]	top	Top of frustum (local space).
[in]	nearpt	Front / near point of frustum (local space).
[in]	farpt	Back / far point of frustum (local space).
[in]	worldXform	transformation 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]	fovX	Field of view in X.
[in]	aspectXY	aspect ratio X / Y.
[in]	nearDist	distance to near plane.
[in]	farDist	distance to far plane.
[in]	worldXform	transformation 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]	left	Left side of frustum (local space).
[in]	right	Right side of frustum (local space).
[in]	bottom	Bottom of frustum (local space).
[in]	top	Top of frustum (local space).
[in]	nearpt	Front / near point of frustum (local space).
[in]	farpt	Back / far point of frustum (local space).
[in]	worldXform	transformation 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]	nearBottomLeft	Near bottom left corner of frustum (local space).
[in]	nearBottomRight	Near bottom Right corner of frustum (local space).
[in]	nearTopLeft	Near top left corner of frustum (local space).
[in]	nearTopRight	Near top right corner of frustum (local space).
[in]	farBottomLeft	Far bottom left corner of frustum (local space).
[in]	farBottomRight	Far bottom right corner of frustum (local space).
[in]	farTopLeft	Far top left corner of frustum (local space).
[in]	farTopRight	Far top right corner of frustum (local space).
[in]	worldXform	transformation 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:

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]

cullAtLeafLevel

flag 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]

val

value for enabling.

Examples:

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:

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]	itemNumber	which item to return.
[out]	path	path of item (returned).

Returns

MStatus::kSuccess if the given element was present in the list.

Examples:

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]	itemNumber	which item to return.
[in]	test	the display status to check the item against.

Returns

true, if item status matches the display status to test against.

Examples:

---

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

• MDrawTraversal.h
• MDrawTraversal.cpp