|
C++ API Reference
|
|
C++ API Reference
|
Base class for user defined motionPath nodes. More...
#include <MPxMotionPathNode.h>
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. | |
| ~MPxMotionPathNode () override | |
| Class destructor. | |
| MPxNode::Type | type () const override |
| 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 void | getCacheSetup (const MEvaluationNode &, MNodeCacheDisablingInfo &, MNodeCacheSetupInfo &, MObjectArray &) const |
| Provide node-specific setup info for the Cached Playback system. More... | |
| virtual void | configCache (const MEvaluationNode &, MCacheSchema &) const |
| Defines the node's behavior when participating in Cached Playback. More... | |
| virtual MTimeRange | transformInvalidationRange (const MPlug &source, const MTimeRange &input) const |
| Override this method to register this node as an Invalidation-Range-Transformation kernel (IRT kernel) An IRT kernel node will change the invalidation time range for its downstream nodes For example, Dynamics-solver will transform invalidation time range [a,b] to [a,+inf) And Clip-Time-Editor will send out the invalidation range for each of the clip [a,b] to ( [t0+a,t0+b] U [t1+a,t1+b] U [t2+a,t2+b] U ... More... | |
| bool | hasInvalidationRangeTransformation () const |
| Checks if this MPxNode derived node overrides the MPxNode::transformInvalidationRange method. | |
| 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 bool | isTrackingTopology () const |
| Override this class to return true if this node wants to track topology. 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... | |
| void | _setMPSafe (bool isMPSafe) |
| This method is obsolete. 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 MStatus | attributeAffects (const MObject &whenChanges, const MObject &isAffected, bool affectsTopology) |
| This method is an extension to the other version of the attributeAffects method. 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 MStatus | setDoNotWrite (bool flag) |
| USE _setDoNotWrite() IN SCRIPT. More... | |
| virtual bool | doNotWrite (MStatus *ReturnStatus=NULL) const |
| USE _doNotWrite() IN SCRIPT. More... | |
| virtual void | setMPSafe (bool isMPSafe) |
| This method is obsolete. More... | |
| virtual MDataBlock | forceCache (const MDGContext &) |
| This method is obsolete. More... | |
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:
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.
| enum worldUpVectorValue |
possible values for worldUpType
|
overridevirtual |
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.
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.
| [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. |
| 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).
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [in] | u | the location along the path curve in parametric space to convert to a fractional value. |
| [out] | ReturnStatus | Status Code. |
| 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().
| [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. |
| 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.
| [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. |
| 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.
| [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. |
1.8.10 
