MPxMotionPathNode Class Reference

#include <MPxMotionPathNode.h>

Class Description

Base class for user defined motionPath nodes.

MPxMotionPathNode provides you with the ability to write your own motion path classes. A custom motionPath node provides access to Maya's internal motionPath engine while at the same time allows you to extend the functionality in ways that are not possible with the motionPath node.

There are two basic ways to work with the methods available in this class. The first way is to mimic how Maya's motionPath node works and then augment the result. You do this by calling the evaluatePath method with values you either read from the input plugs or modified yourself, and the method returns the location and orientation on the path.

The second way of working is to use the individual a-la-carte evaluator methods provided in this class to invoke the motionPath engine on a piecemeal basis. For example, you might call position() to calculate the location on the path, then getVectors() to compute the coordinate space vectors, then offset the position along those vectors, then call banking() to "tilt" the result. The example plug-in "motionPathNode.cpp" found in the API Developer's Toolkit provides an example of using the a-la-carte evaluation scheme to add sinusoidal offsets to the computed result.

Here are some examples of how you might use a custom motionPath node:

• Change how the range is interpreted, such as having 0 at the start of the path and 100 at the end regardless of the curve parameterisation. You could also implement wraparound, cycling, and oscillation when "u" is oustide the range.
• Modify the output of the motionPath engine calculation by adding your own custom offsets, rotations and other enhancements based on inputs to your custom node.
• If you want a behaviour where an object anticipates the turns ahead such as on a roller-coaster (i.e. starts to lean before reaching the turn), you do one extra evaluation a certain distance ahead on the path then adjust the rotation to point at that location.
• To model some objects spaced a certain distance along a path, you could input the spacing as a multi attribute, have the "u" attribute as the location of the first object, calculate all the positions when your compute() method is called, then feed the resulting position and orientation into an output multi that each geometry connects to.
• Similar to the above, create rows and columns of people marching in a parade, with each row turning smartly as the parade rounds a corner.
• Adding randomness and simple bounding-box avoidance logic, you could model a crowd moving in a general direction along a path but slowly dispersing.

The example plug-in, "motionPathNode.cpp" found in the API Developer's Toolkit provides a great starting point for exploring the capabilities of the MPxMotionPathNode class.

Examples:

Inheritance diagram for MPxMotionPathNode:

Public Types
enum	worldUpVectorValue {   kUpScene, kUpObject, kUpObjectRotation, kUpVector,   kUpNormal }
	possible values for worldUpType More...
Public Types inherited from MPxNode
enum	Type {   kDependNode, kLocatorNode, kDeformerNode, kManipContainer,   kSurfaceShape, kFieldNode, kEmitterNode, kSpringNode,   kIkSolverNode, kHardwareShader, kHwShaderNode, kTransformNode,   kObjectSet, kFluidEmitterNode, kImagePlaneNode, kParticleAttributeMapperNode,   kCameraSetNode, kConstraintNode, kManipulatorNode, kMotionPathNode,   kClientDeviceNode, kThreadedDeviceNode, kAssembly, kSkinCluster,   kGeometryFilter, kBlendShape, kLast }
	Defines the type of node. More...
enum	SchedulingType {   kParallel, kSerial, kGloballySerial, kUntrusted ,   kDefaultScheduling = kSerial, kSerialize = kSerial, kGloballySerialize = kGloballySerial }
	Defines the degree of parallelism of a node. More...

Public Member Functions
	MPxMotionPathNode ()
	Class constructor.
virtual	~MPxMotionPathNode ()
	Class destructor.
virtual MPxNode::Type	type () const
	Returns the type of node that this is. More...
MPoint	position (MDataBlock &data, double f, MStatus *status=NULL) const
	This method returns the position on the path associated with the motionPath node at a specified fractional distance along the path. More...
MStatus	getVectors (MDataBlock &data, double f, MVector &front, MVector &side, MVector &up, const MVector *worldUp=NULL) const
	Calculate the orientation on the motion path at the fractional distance `frac' along the path. More...
MQuaternion	banking (MDataBlock &data, double f, const MVector &worldUp, double bankScale, double bankLimit, MStatus *status=NULL) const
	Calculate the banking on the motion path at the fractional distance `frac' along the path. More...
MStatus	evaluatePath (MDataBlock &data, double u, double uRange, bool wraparound, double sideOffset, double upOffset, bool follow, bool inverseFront, bool inverseUp, int frontAxis, int upAxis, double frontTwist, double upTwist, double sideTwist, bool bank, double bankScale, double bankLimit, MPoint &resultPosition, MMatrix &resultOrientation) const
	Callable from your custom plug-ins compute() method to evaluate the path at the specified location. More...
double	parametricToFractional (double u, MStatus *status=NULL) const
	Converts a parametric location on the path curve to the corresponding fraction of the total path curve length. More...
double	fractionalToParametric (double f, MStatus *status=NULL) const
	Converts a fractional location on the path curve to the corresponding parametric location. More...
double	wraparoundFractionalValue (double f, MStatus *status=NULL) const
	Given the fractional distance `frac' along the path, this method checks if the value goes beyond the 0 to 1 range and if so chooses the appropriate value to continue the motion on the opposing end of the path such that the motion will appear to "wrap around" the beginning (or end) of the path as appropriate. More...
MMatrix	matrix (const MVector &front, const MVector &side, const MVector &up, int frontAxisIdx=1, int upAxisIdx=2, MStatus *status=NULL) const
	Create a matrix given vector space specified by the three orthogonal input vectors. More...
Public Member Functions inherited from MPxNode
	MPxNode ()
	Constructor. More...
virtual	~MPxNode ()
	Destructor.
virtual void	postConstructor ()
	Post constructor. More...
virtual MStatus	compute (const MPlug &, MDataBlock &)
	This method should be overridden in user defined nodes. More...
virtual bool	getInternalValue (const MPlug &, MDataHandle &)
	This method is overridden by nodes that store attribute data in some internal format. More...
virtual bool	setInternalValue (const MPlug &, const MDataHandle &)
	This method is overridden by nodes that store attribute data in some internal format. More...
virtual int	internalArrayCount (const MPlug &) const
	This method is overridden by nodes that have internal array attributes which are not stored in Maya's datablock. More...
virtual void	copyInternalData (MPxNode *)
	This method is overridden by nodes that store attribute data in some internal format. More...
virtual MStatus	legalConnection (const MPlug &, const MPlug &, bool asSrc, bool &isLegal) const
	This method allows you to check for legal connections being made to attributes of this node. More...
virtual MStatus	legalDisconnection (const MPlug &, const MPlug &, bool asSrc, bool &isLegal) const
	This method allows you to check for legal disconnections being made to attributes of this node. More...
virtual MStatus	setDependentsDirty (const MPlug &plug, MPlugArray &plugArray)
	This method can be overridden in user defined nodes to specify which plugs should be set dirty based upon an input plug {plugBeingDirtied} which Maya is marking dirty. More...
virtual MStatus	preEvaluation (const MDGContext &context, const MEvaluationNode &evaluationNode)
	Prepare a node's internal state for threaded evaluation. More...
virtual MStatus	postEvaluation (const MDGContext &context, const MEvaluationNode &evaluationNode, PostEvaluationType evalType)
	Clean up node's internal state after threaded evaluation. More...
virtual SchedulingType	schedulingType () const
	When overridden this method controls the degree of parallelism supported by the node during threaded evaluation. More...
virtual MStatus	connectionMade (const MPlug &, const MPlug &, bool asSrc)
	This method gets called when connections are made to attributes of this node. More...
virtual MStatus	connectionBroken (const MPlug &, const MPlug &, bool asSrc)
	This method gets called when connections are broken with attributes of this node. More...
virtual MStatus	dependsOn (const MPlug &, const MPlug &, bool &depends) const
	This method may be overridden by the user defined node. More...
virtual bool	isPassiveOutput (const MPlug &) const
	This method may be overridden by the user defined node if it wants to provide output attributes which do not prevent value modifications to the destination attribute. More...
virtual MStatus	shouldSave (const MPlug &, bool &isSaving)
	This method may be overridden by the user defined node. More...
virtual MPlug	passThroughToOne (const MPlug &) const
	This method may be overridden by nodes that have a one-to-one relationship between an input attribute and a corresponding output attribute. More...
virtual bool	passThroughToMany (const MPlug &, MPlugArray &) const
	This method is overridden by nodes that want to control the traversal behavior of some Maya search algorithms which traverse the history/future of shape nodes looking for directly related nodes. More...
virtual bool	isAbstractClass () const
	Override this class to return true if this node is an abstract node. More...
virtual MStringArray	getFilesToArchive (bool shortName=false, bool unresolvedName=false, bool markCouldBeImageSequence=false) const
	Use this method to return all external files used by this node. More...
virtual void	getExternalContent (MExternalContentInfoTable &table) const
	Returns the external content (files) that this node depends on. More...
bool	addExternalContentForFileAttr (MExternalContentInfoTable &, const MObject &attr) const
	Adds content info to the specified table from a file path attribute. More...
bool	setExternalContentForFileAttr (const MObject &attr, const MExternalContentLocationTable &)
	Sets content info in the specified attribute from the table. More...
virtual void	setExternalContent (const MExternalContentLocationTable &)
	Changes the location of external content in batch. More...
virtual MTypeId	typeId () const
	Returns the TYPEID of this node. More...
virtual MString	typeName () const
	Returns the type name of this node. More...
virtual MString	name () const
	Returns the name of this particular instance of this class. More...
virtual MObject	thisMObject () const
	Returns the MObject associated with this user defined node. More...
virtual MStatus	setExistWithoutInConnections (bool flag)
	This method specifies whether or not the node can exist without input connections. More...
virtual bool	existWithoutInConnections (MStatus *ReturnStatus=NULL) const
	Determines whether or not this node can exist without input connections. More...
virtual MStatus	setExistWithoutOutConnections (bool flag)
	This method specifies whether or not the node can exist without output connections. More...
virtual bool	existWithoutOutConnections (MStatus *ReturnStatus=NULL) const
	Determines whether or not this node can exist without output connections. More...
MDataBlock	_forceCache (const MDGContext &)
	This method is obsolete. More...
virtual bool	getInternalValueInContext (const MPlug &, MDataHandle &, MDGContext &)
	This method is obsolete. More...
virtual bool	setInternalValueInContext (const MPlug &, const MDataHandle &, MDGContext &)
	This method is obsolete. More...
virtual int	internalArrayCount (const MPlug &, const MDGContext &) const
	This method is obsolete. More...

Static Public Attributes
static MObject	uValue
	u value
static MObject	frontTwist
	front twist
static MObject	upTwist
	up twist
static MObject	sideTwist
	side twist
static MObject	flowNode
	flow node
static MObject	pathGeometry
	path geometry
static MObject	positionMarkerTime
	position marker time
static MObject	orientationMarkerTime
	orientation marker time
static MObject	follow
	follow
static MObject	normal
	normal
static MObject	inverseUp
	inverse up
static MObject	inverseFront
	inverse front
static MObject	frontAxis
	front axis
static MObject	upAxis
	up axis
static MObject	worldUpType
	world up type
static MObject	worldUpVector
	world up vector
static MObject	worldUpMatrix
	world up matrix
static MObject	bank
	bank
static MObject	bankScale
	bank scale
static MObject	bankThreshold
	bank threshold
static MObject	fractionMode
	fraction mode
static MObject	updateOrientationMarkers
	update orientation markers
static MObject	allCoordinates
	The computed world space position.
static MObject	xCoordinate
	X-component of the computed world space position.
static MObject	yCoordinate
	Y-component of the computed world space position.
static MObject	zCoordinate
	Z-component of the computed world space position.
static MObject	orientMatrix
	The computed world space orientation matrix.
static MObject	rotate
	The computed world space rotation.
static MObject	rotateX
	Angle of rotation about the X axis.
static MObject	rotateY
	Angle of rotation about the Y axis.
static MObject	rotateZ
	Angle of rotation about the Z axis.
static MObject	rotateOrder
	The order of rotations for the rotate attribute.
Static Public Attributes inherited from MPxNode
static MObject	message
	message attribute
static MObject	isHistoricallyInteresting
	is historically interesting attribute
static MObject	caching
	caching attribute
static MObject	state
	state attribute
static MObject	frozen
	frozen attribute

Additional Inherited Members
Static Public Member Functions inherited from MPxNode
static MStatus	addAttribute (const MObject &attr)
	This method adds a new attribute to a user defined node type during the type's initialization. More...
static MStatus	inheritAttributesFrom (const MString &parentClassName)
	This method allows a class of plugin node to inherit all of the attributes of a second class of plugin node. More...
static MStatus	attributeAffects (const MObject &whenChanges, const MObject &isAffected)
	This method specifies that a particular input attribute affects a specific output attribute. More...
static const char *	className ()
	Returns the name of this class. More...
Protected Member Functions inherited from MPxNode
virtual MDataBlock	forceCache ()
	USE _forceCache() IN SCRIPT. More...
virtual void	setMPSafe (bool flag)
	USE _setMPSafe() IN SCRIPT. More...
virtual MStatus	setDoNotWrite (bool flag)
	USE _setDoNotWrite() IN SCRIPT. More...
virtual bool	doNotWrite (MStatus *ReturnStatus=NULL) const
	USE _doNotWrite() IN SCRIPT. More...
virtual MDataBlock	forceCache (const MDGContext &)
	This method is obsolete. More...

Member Enumeration Documentation

enum worldUpVectorValue

possible values for worldUpType

Enumerator
kUpScene	Use the scene up vector as world up.
kUpObject	Use the object's up vector as world up.
kUpObjectRotation	Use the object's rotation up vector as world up.
kUpVector	Use the value of the worldUpVector plug as world up.
kUpNormal	Use the path normal world up.

Member Function Documentation

MPxNode::Type type ( ) const

virtual

Returns the type of node that this is.

This is used to differentiate user defined nodes that are derived off different MPx base classes.

It is not necessary to override this method.

Returns

Type of the node

Reimplemented from MPxNode.

MPoint position	(	MDataBlock &	data,
		double	frac,
		MStatus *	ReturnStatus = NULL
	)		const

This method returns the position on the path associated with the motionPath node at a specified fractional distance along the path.

This method is designed to be called from within your compute() method and requires an MDataBlock (`data') to access the path. Typically you would pass in the current value of the `uValue' plug to get the current location on the path. However, you could offset the value to get a position ahead of you on the path, for example to simulate someone leaning ahead of time to anticpate an upcoming curve on a roller-coaster.

Parameters

[in]	data	is the data block for the computation.
[in]	frac	the fraction of the length along the path to sample at. The value is specified in 0 to 1 range where 0 represents the start of the path and 1 the end of the path. Values within the 0 to 1 range are unchanged. Values outside the range are clamped. If you instead have a parametric value for position on the path, use parameterToFractional() to convert the value to a fractional amount.
[out]	ReturnStatus	Status Code.

Returns

If successful, returns the calculated position on the path occurring at `frac'. If unsuccessful, a zero value is returned and ReturnStatus reports an error code.

Status Codes:

• MS::kSuccess Evaluation was successful.
• MS::kFailure An object error has occurred. No motion path geometry is available. Calculation of the motion path failed.

MStatus getVectors	(	MDataBlock &	data,
		double	frac,
		MVector &	front,
		MVector &	side,
		MVector &	up,
		const MVector *	worldUp = NULL
	)		const

Calculate the orientation on the motion path at the fractional distance `frac' along the path.

The returned vectors form an orthogonal basis oriented on the path. Only the path and `worldUp' factor into the calculation. Additional rotation parameters such as banking and twist are not applied here (see the example plug-in motionPathNode.cpp for details of how to apply these).

Parameters

[in]	data	is the data block for the computation.
[in]	frac	the fraction of the length along the path to sample at. The value is specified in 0 to 1 range where 0 represents the start of the path and 1 the end of the path. Values within the 0 to 1 range are unchanged. Values outside the range are clamped. If you instead have a parametric value for position on the path, use parameterToFractional() to convert the value to a fractional amount.
[out]	front	returns the forward direction of motion.
[out]	side	returns the vector perpendicular to the motion.
[out]	up	returns the vector perpendicular to the motion.
[in]	worldUp	is an optional parameter which specifies the direction that the computed `up' vector should point. The `front' vector always points along the path, and the `up' vector perpendicular to it in the `worldUp' direction. To instead use the normal to the path, specify NULL.

Returns

• MS::kSuccess Evaluation was successful.
• MS::kFailure An object error has occurred. No motion path geometry is available. Calculation of the motion path failed.

MQuaternion banking	(	MDataBlock &	data,
		double	frac,
		const MVector &	worldUp,
		double	bankScale,
		double	bankLimit,
		MStatus *	ReturnStatus = NULL
	)		const

Calculate the banking on the motion path at the fractional distance `frac' along the path.

Banking is a supplemental rotation about the direction of motion that can be added to the orientation obtained from getVectors. A typical use is to apply the result value to the up vector then cross the front vector and new up vector to obtain the new side vector.

Parameters

[in]	data	is the data block for the computation.
[in]	frac	the fraction of the length along the path to sample at. The value is specified in 0 to 1 range where 0 represents the start of the path and 1 the end of the path. Values within the 0 to 1 range are unchanged. Values outside the range are clamped. If you instead have a parametric value for position on the path, use parameterToFractional() to convert the value to a fractional amount.
[in]	worldUp	The "up" direction. Typically the world up, but could instead be the normal to a surface, for example.
[in]	bankScale	causes the effect of banking to be more (or less pronounced). A value of 2.0 causes twice the amount of banking. The value can be negative to compute the oppositive of a "lean-in" effect.
[in]	bankLimit	provides a threshold above which the banking effect is clamped.
[out]	ReturnStatus	Status Code.

Returns

If successful, returns the calculated rotation due to banking on the path at `frac'. If unsuccessful, a unit quaternion is returned and ReturnStatus reports an error code.

Status Codes:

• MS::kSuccess Evaluation was successful.
• MS::kFailure An object error has occurred. No motion path geometry is available. Calculation of the motion path failed.

MStatus evaluatePath	(	MDataBlock &	data,
		double	u,
		double	uRange,
		bool	wraparound,
		double	sideOffset,
		double	upOffset,
		bool	follow,
		bool	inverseFront,
		bool	inverseUp,
		int	frontAxisIdx,
		int	upAxisIdx,
		double	frontTwist,
		double	upTwist,
		double	sideTwist,
		bool	bank,
		double	bankScale,
		double	bankLimit,
		MPoint &	resultPosition,
		MMatrix &	resultOrientation
	)		const

Callable from your custom plug-ins compute() method to evaluate the path at the specified location.

This method provides an alternate to using the a-la-carte evaluator access provided elsewhere in this class (e.g. position()). Use this method if you want to emulate the evaluation as performed by the motionPath node as opposed to chaining several a-la-carte methods together.

Parameters

[in]	data	is the data block for the computation.
[in]	u	the locaion on the path to sample. See the uRange parameters for details on how the value is interpreted.
[in]	uRange	defines how the u parameter is interpreted. If a negative number, u is assumed to be a parametric value, otherwise u is assumed to be based on the path length. For example, a uRange of 360.0 means that `u' of 0.0 represents the start of the path and `u' of 360.0 represents the end of the path.
[in]	wraparound	true means that when values go past the end of the path they wrap around to the other end. If false, values are clamped to the ends of the path.
[in]	sideOffset	The amount to offset the computed position from the path. The offset is applied along the horizontal axis to the path.
[in]	upOffset	The amount to offset the computed position from the path. The offset is applied along the vertical axis to the path.
[in]	follow	If true, orientation aligns to the path direction. If false, orientation is fixed.
[in]	inverseFront	If true, the front direction is negated.
[in]	inverseUp	If true, the uo direction is negated.
[in]	frontAxisIdx	an index (x-0, y=1, z=2) specifying which local axis of the result is aligned to the front direction.
[in]	upAxisIdx	an index (x-0, y=1, z=2) specifying which local axis of the result is aligned to the up direction.
[in]	frontTwist	the amount of roll to add to the computed orientation.
[in]	upTwist	the amount of yaw to add to the computed orientation.
[in]	sideTwist	the amount of pitch to add to the computed orientation.
[in]	bank	if true, the computed orientation will be offset by a bank value derived from the tightness of the path at the sampled point.
[in]	bankScale	a multiplier on the banking calculation. For example, a value of two will double the banking effect. Negative values are permitted.
[in]	bankLimit	a threshold to specify that banking effect is clamped past the limit amount.
[out]	resultPosition	the computed sample position on the path.
[out]	resultOrientation	the computed sample orientation on the path.

Returns

• MS::kSuccess Evaluation was successful.
• MS::kFailure An object error has occurred. No motion path geometry is available. Calculation of the motion path failed.

double parametricToFractional	(	double	u,
		MStatus *	ReturnStatus = NULL
	)		const

Converts a parametric location on the path curve to the corresponding fraction of the total path curve length.

The resulting fractional value will be 0.0 at the start of the path, 1.0 at the end of the path, and values betwixt the start and end being proportionately positioned based on arc length. If `u' preceeds the start or succeeds the end of the curve then the returned value will be outside the 0 to 1 range.

Parameters

[in]	u	the location along the path curve in parametric space to convert to a fractional value.
[out]	ReturnStatus	Status Code.

Returns

If successful, returns the calculated fractional value corresponding to the parametric value `u'. If unsuccessful, -1.0 is returned and ReturnStatus reports an error code.

Status Codes:

• MS::kSuccess Evaluation was successful.
• MS::kFailure An object error has occurred. No motion path geometry is available. Could not evaluate the path.

double fractionalToParametric	(	double	frac,
		MStatus *	ReturnStatus = NULL
	)		const

Converts a fractional location on the path curve to the corresponding parametric location.

This method is the converse of parametricToFractional().

Parameters

[in]	frac	the location along the path curve as a fraction of the total length of the path. A value of zero represents the start of the path, one represents the end of the path, and values betwixt zero and one represent the proportionate distance along the path in arc length.
[out]	ReturnStatus	Status Code.

Returns

If successful, returns the calculated parametric location that is equivalent to the fractional value `frac'. If unsuccessful, -1.0 is returned and ReturnStatus reports an error code.

Status Codes:

• MS::kSuccess Evaluation was successful.
• MS::kFailure An object error has occurred. No motion path geometry is available. Could not evaluate the path.

double wraparoundFractionalValue	(	double	f,
		MStatus *	ReturnStatus = NULL
	)		const

Given the fractional distance `frac' along the path, this method checks if the value goes beyond the 0 to 1 range and if so chooses the appropriate value to continue the motion on the opposing end of the path such that the motion will appear to "wrap around" the beginning (or end) of the path as appropriate.

For example, a value of -0.2 will return the result 0.8.

Parameters

[in]	f	the fraction of the length along the path to sample at. The value is specified in 0 to 1 range where 0 represents the start of the path and 1 the end of the path. Values within the 0 to 1 range are unchanged. Values outside the range are wrapped around.
[out]	ReturnStatus	Status Code.

Returns

If successful, returns the remapped fractional value in the 0 - 1 range. If unsuccessful, -1.0 is returned and ReturnStatus reports an error code.

Status Codes:

• MS::kSuccess Evaluation was successful.
• MS::kFailure An object error has occurred.

MMatrix matrix	(	const MVector &	front,
		const MVector &	side,
		const MVector &	up,
		int	frontAxisIdx = 1,
		int	upAxisIdx = 2,
		MStatus *	ReturnStatus = NULL
	)		const

Create a matrix given vector space specified by the three orthogonal input vectors.

The resulting matrix will be a rotation matrix that aligns data with the given vector space. The vectors should be normalised and must be orthogonal, otherwise an error will be returned.

Parameters

[in]	front	is the first vector.
[in]	side	is the second vector.
[in]	up	is the third vector.
[in]	frontAxisIdx	an optional index (x=0, y=1, z=2) specifying which local axis of the result is aligned to the front direction. The default is 1.
[in]	upAxisIdx	an optional index (x=0, y=1, z=2) specifying which local axis of the result is aligned to the up direction. The default is 2.
[out]	ReturnStatus	Status Code.

Returns

If successful, returns the calculated rotation matrix. If unsuccessful, the identity matrix is returned and ReturnStatus reports an error code.

Status Codes:

• MS::kSuccess Evaluation was successful.
• MS::kFailure Either one or more of the vectors was not normalised, or the vectors were not orthoganol.

---

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

• MPxMotionPathNode.h
• MPxMotionPathNode.cpp