class MPxTransformationMatrix

Jump to documentation

public members:

	MPxTransformationMatrix ()
	MPxTransformationMatrix (const MTransformationMatrix &)
	MPxTransformationMatrix (const MPxTransformationMatrix &)
	MPxTransformationMatrix (const MMatrix &)
virtual	~MPxTransformationMatrix ()
virtual void	copyValues ( MPxTransformationMatrix *)
virtual MTypeId	typeId () const
MPxTransformationMatrix &	operator = (const MPxTransformationMatrix &src)
MPxTransformationMatrix &	operator = (const MMatrix &src)
MPxTransformationMatrix &	operator = (const MTransformationMatrix &src)
bool	operator == (const MPxTransformationMatrix &)
bool	operator != (const MPxTransformationMatrix &)
bool	operator == (const MTransformationMatrix &)
bool	operator != (const MTransformationMatrix &)
bool	operator == (const MMatrix &)
bool	operator != (const MMatrix &)
virtual bool	isEquivalent (const MPxTransformationMatrix &, double tolerance = MMatrix_kTol) const
virtual bool	isEquivalent (const MTransformationMatrix &, double tolerance = MMatrix_kTol) const
virtual bool	isEquivalent (const MMatrix &, double tolerance = MMatrix_kTol) const
virtual MPxTransformationMatrix	reverse () const
virtual MPxTransformationMatrix &	transformBy (const MTransformationMatrix &)
virtual MMatrix	asMatrix () const
virtual MMatrix	asMatrixInverse () const
virtual MMatrix	asScaleMatrix () const
virtual MMatrix	asScaleMatrixInverse () const
virtual MMatrix	asRotateMatrix () const
virtual MMatrix	asRotateMatrixInverse () const
virtual MMatrix	asMatrix (double percent) const
virtual MMatrix	asInterpolationMatrix (const MTransformationMatrix &toM, double percent, bool rot, int direction = 0) const
virtual MTransformationMatrix	asTransformationMatrix () const
virtual MVector	translation ( MSpace::Space = MSpace::kTransform , MStatus * ReturnStatus = NULL) const
virtual MStatus	translateTo (const MVector &vector, MSpace::Space = MSpace::kTransform )
virtual MStatus	translateBy (const MVector &vector, MSpace::Space = MSpace::kTransform )
virtual MQuaternion	rotation ( MSpace::Space = MSpace::kTransform , MStatus *ReturnStatus = NULL) const
virtual MEulerRotation	eulerRotation ( MSpace::Space = MSpace::kTransform , MStatus *ReturnStatus = NULL) const
virtual MStatus	rotateTo (const MQuaternion &q, MSpace::Space = MSpace::kTransform )
virtual MStatus	rotateBy (const MQuaternion &q, MSpace::Space = MSpace::kTransform )
virtual MStatus	rotateTo (const MEulerRotation &e, MSpace::Space = MSpace::kTransform )
virtual MStatus	rotateBy (const MEulerRotation &e, MSpace::Space = MSpace::kTransform )
virtual MTransformationMatrix::RotationOrder	rotationOrder ( MStatus * ReturnStatus = NULL) const
virtual MStatus	setRotationOrder ( MTransformationMatrix::RotationOrder , bool preserve = true)
virtual MQuaternion	rotateOrientation ( MSpace::Space = MSpace::kTransform , MStatus * ReturnStatus = NULL) const
virtual MStatus	setRotateOrientation (const MQuaternion &q, MSpace::Space = MSpace::kTransform , bool balance = true)
virtual MEulerRotation	eulerRotateOrientation ( MSpace::Space = MSpace::kTransform , MStatus * ReturnStatus = NULL) const
virtual MVector	scale ( MSpace::Space = MSpace::kTransform , MStatus * ReturnStatus = NULL) const
virtual MStatus	scaleTo (const MVector &, MSpace::Space = MSpace::kTransform )
virtual MStatus	scaleBy (const MVector &, MSpace::Space = MSpace::kTransform )
virtual MVector	shear ( MSpace::Space = MSpace::kTransform , MStatus * ReturnStatus = NULL) const
virtual MStatus	shearTo (const MVector & shear , MSpace::Space = MSpace::kTransform )
virtual MStatus	shearBy (const MVector & shear , MSpace::Space = MSpace::kTransform )
virtual MPoint	scalePivot ( MSpace::Space = MSpace::kTransform , MStatus * ReturnStatus = NULL) const
virtual MStatus	setScalePivot (const MPoint &, MSpace::Space = MSpace::kTransform , bool balance = true)
virtual MVector	scalePivotTranslation ( MSpace::Space = MSpace::kTransform , MStatus * ReturnStatus = NULL) const
virtual MStatus	setScalePivotTranslation (const MVector &vector, MSpace::Space = MSpace::kTransform )
virtual MPoint	rotatePivot ( MSpace::Space = MSpace::kTransform , MStatus * ReturnStatus = NULL) const
virtual MStatus	setRotatePivot (const MPoint &, MSpace::Space = MSpace::kTransform , bool balance = true)
virtual MVector	rotatePivotTranslation ( MSpace::Space = MSpace::kTransform , MStatus * ReturnStatus = NULL) const
virtual MStatus	setRotatePivotTranslation (const MVector &vector, MSpace::Space = MSpace::kTransform )
virtual MStatus	unSquishIt ()
virtual MMatrix	unSquishMatrix () const
static MEulerRotation::RotationOrder	convertTransformationRotationOrder ( MTransformationMatrix::RotationOrder , MStatus *ReturnStatus = NULL)
static MTransformationMatrix::RotationOrder	convertEulerRotationOrder ( MEulerRotation::RotationOrder , MStatus *ReturnStatus = NULL)
static const MPxTransformationMatrix	identity
static MTypeId	baseTransformationMatrixId
static MEulerRotation::RotationOrder	convertRotationOrder ( MTransformationMatrix::RotationOrder , MStatus *ReturnStatus = NULL) OBSOLETE & NO SCRIPT SUPPORT
static MTransformationMatrix::RotationOrder	convertRotationOrder ( MEulerRotation::RotationOrder , MStatus *ReturnStatus = NULL) OBSOLETE & NO SCRIPT SUPPORT
friend std::ostream &	operator << (std::ostream &os, const MPxTransformationMatrix &m) NO SCRIPT SUPPORT

protected members:

virtual MStatus	decomposeMatrix (const MMatrix &)
MVector	scaleValue
MEulerRotation	rotationValue
MVector	translationValue
MVector	shearValue
MPoint	scalePivotValue
MVector	scalePivotTranslationValue
MPoint	rotatePivotValue
MVector	rotatePivotTranslationValue
MQuaternion	rotateOrientationValue

Documentation

Description

MPxTransformationMatrix is the parent class for all user defined transformation matrices. A transformation matrix is a class that holds the individual components (i.e. translate, rotate, scale, pivots, etc.) that are used to construct a 4x4 matrix. Given that different combinations of transform components may produce similar 4x4 matrices, it is not always possible to get a generic 4x4 matrix and decompose it into unique components. This class allows better control over which components are changed than a generic 4x4 MMatrix could offer.

The MPxTransformationMatrix class is designed for use as the mathematical brains behind the MPxTransform node. This separation is useful for class reuse (different types of MPxTransform nodes may still use the same MPxTransformationMatrix class) as well as simplifying the MPxTransform class.

The MPxTransformationMatrix class is registered using the MFnPlugin::registerTransform() method. Both the MPxTransform and the MPxTransformationMatrix classes are registered in the same method. This allows for a clear association between a MPxTransform and a MPxTransformationMatrix.

When registering the MPxTransformationMatrix, a MTypeId is required. For nodes using the default MPxTransformationMatrix, a statically defined MTypeId is provided by the MPxTransformationMatrix::baseTransformationMatrixId data member.

Since the MPxTransformationMatrix class gives extended functionality to a native Maya class, several methods are given that are needed by Maya for this class to properly function in different settings.

To create a transformation matrix, derive from this class and overload the creator() method and the assignment operator for the derived class. If any additional data items are added to this class, the copyValues() method should also be overloaded. This will ensure that the new values will get properly handed by Maya. The rest of the methods may be overloaded as needed.

Functions

MPxTransformationMatrix:: MPxTransformationMatrix ()

Description

Class Constructor.

MPxTransformationMatrix:: MPxTransformationMatrix ( const MTransformationMatrix &src)

Description

Class constructor.

The contents of the passed MTransformationMatrix are used to initialize the new MPxTransformationMatrix.

Arguments

• src matrix to be copied.

MPxTransformationMatrix:: MPxTransformationMatrix ( const MPxTransformationMatrix &src)

Description

A copy constructor.

The contents of the passed MPxTransformationMatrix are used to initialize this MPxTransformationMatrix.

Arguments

• src The transformation matrix to copy.

MPxTransformationMatrix:: MPxTransformationMatrix (const MMatrix &src)

Description

MMatrix copy constructor.

The contents of the passed MMatrix are used to initialize the new MPxTransformationMatrix. In order to fill the individual components of the transformation matrix, decomposeMatrix() is called with the passed MMatrix.

Arguments

• src The matrix used for transformation initialization.

MPxTransformationMatrix:: ~MPxTransformationMatrix ()

Description

Class destructor.

MPxTransformationMatrix & MPxTransformationMatrix:: operator = (const MPxTransformationMatrix &src)

Description

Assignment operator.

Arguments

• src User defined transformation matrix to be copied.

MPxTransformationMatrix & MPxTransformationMatrix:: operator = (const MTransformationMatrix &src)

Description

Assignment operator.

Arguments

• src Transformation matrix to be copied.

MPxTransformationMatrix & MPxTransformationMatrix:: operator = (const MMatrix &src)

Description

Assignment operator.

In order to convert the MMatrix to a MPxTransformationMatrix, decomposeMatrix() will be called.

Arguments

• src The matrix to copy.

bool MPxTransformationMatrix:: operator == (const MPxTransformationMatrix &rhs)

Description

Equality operator

Arguments

• rhs The user defined transformation matrix to compare.

Return Value

• true The transformation matrices are identical
• false The transformation matrices are not identical

bool MPxTransformationMatrix:: operator != (const MPxTransformationMatrix &rhs)

Description

Inequality operator

This method will compare the resulting 4x4 matrices for inequality.

Arguments

• rhs The user defined transformation matrix to compare.

Return Value

• true The transformation matrices are not identical
• false The transformation matrices are identical

bool MPxTransformationMatrix:: operator == (const MTransformationMatrix &rhs)

Description

Equality operator

This method will compare the resulting 4x4 matrices for equality.

Arguments

• rhs The user defined transformation matrix to compare.

Return Value

• true The transformation matrices are identical
• false The transformation matrices are not identical

bool MPxTransformationMatrix:: operator != (const MTransformationMatrix &rhs)

Description

Inequality operator.

This method will compare the resulting 4x4 matrices for inequality.

Arguments

• rhs The MTransformationMatrix to compare.

Return Value

• true The matrices are not identical.
• false The matrices are identical.

bool MPxTransformationMatrix:: operator == (const MMatrix &rhs)

Description

Equality operator

Arguments

• rhs the MMatrix to compare

Return Value

• true the matrices are identical
• false the matrices are not identical

bool MPxTransformationMatrix:: operator != (const MMatrix &rhs)

Description

Equality operator.

This method will compare the resulting 4x4 matrices for equality.

Arguments

• rhs The MMatrix to compare.

Return Value

• true The matrices are not identical.
• false The matrices are identical.

void MPxTransformationMatrix:: copyValues ( MPxTransformationMatrix *xform)

Description

This method should be overridden for any transform that uses more then the default transform values. The values from the passed class (which should be type checked and downcast to its appropriate value) should be copied to this class.

Without this method being overridden, only the default transform components will get copied.

Arguments

• xform The user defined transformation matrix that should be copied.

MTypeId MPxTransformationMatrix:: typeId () const

Description

Returns the MTypeId of this transformation matrix. The MTypeId is a four byte identifier that uniquely identifies this type of transformation matrix.

Return Value

• Type id of the transformation matrix.

bool MPxTransformationMatrix:: isEquivalent (const MPxTransformationMatrix &other, double tolerance ) const

Description

Determine if the MPxTransformationMatrix is equivalent within a specified tolerance. The comparison is done with the resulting 4x4 MMatrix and not on a component by component basis.

Arguments

• other The user defined transformation matrix to compare to.
• tolerance The tolerance used in the comparison.

Return Value

• true The matrices are identical within the specified tolerance.
• false The matrices are not identical within the specified tolerance.

bool MPxTransformationMatrix:: isEquivalent (const MTransformationMatrix &other, double tolerance ) const

Description

Determine if the MTransformationMatrix is equivalent within a specified tolerance. The comparison is done with the resulting 4x4 MMatrix and not on a component by component basis.

Arguments

• other The transformation matrix to compare to
• tolerance The tolerance used in the comparison.

Return Value

• true The matrices are identical within the specified tolerance.
• false The matrices are not identical within the specified tolerance.

bool MPxTransformationMatrix:: isEquivalent (const MMatrix &other, double tolerance ) const

Description

Determine if the MMatrix is equivalent within a specified tolerance.

Arguments

• other The matrix to compare to.
• tolerance The tolerance used in the comparison.

Return Value

• true the matrices are identical
• false the matrices are not identical

MPxTransformationMatrix MPxTransformationMatrix:: reverse () const

Description

Returns the negated translate, rotate, and scale without taking the pivots into account.

Return Value

• the reversed transformation matrix

MPxTransformationMatrix & MPxTransformationMatrix:: transformBy (const MTransformationMatrix &transMat)

Description

Transforms the transformation matrix by the passed MTransformationMatrix. The individual components are considered with the exception of the pivot translations.

Arguments

• tm The transformation matrix to transform by.

Return Value

• This transformation matrix.

MMatrix MPxTransformationMatrix:: asMatrix () const

Description

Returns the four by four matrix that describes this transformation. The default matrix math is defined by:

	   -1                     -1 
	[Sp]x[S]x[Sh]x[Sp]x[St]x[Rp]x[Ro]x[R]x[Rp]x[Rt]x[T]

Where [Sp] is the scale pivot, [S] is the scale matrix, [Sh] is the shear matrix, [St] is the scale pivot translation, [Rp] is the rotate pivot, [Ro] is the rotate orientation, [R] is the rotate matrix, [Rt] is the rotate picot translation, and [T] is the translation.

Return Value

• The resulting matrix.

MMatrix MPxTransformationMatrix:: asMatrixInverse () const

Description

Returns the inverse of the four by four matrix that describes this transformation.

By default this is described as:

	     -1                     -1                         -1
	[ [Sp]x[S]x[Sh]x[Sp]x[St]x[Rp]x[Ro]x[R]x[Rp]x[Rt]x[T] ]

Where [Sp] is the scale pivot, [S] is the scale matrix, [Sh] is the shear matrix, [St] is the scale pivot translation, [Rp] is the rotate pivot, [Ro] is the rotate orientation, [R] is the rotate matrix, [Rt] is the rotate picot translation, and [T] is the translation.

Return Value

• The inverse matrix.

MMatrix MPxTransformationMatrix:: asScaleMatrix () const

Description

Returns scale matrix. The scale matrix takes points from object space to the space immediately following scale and shear transformations.

For the default matrix, the scale matrix combines the space pivot [Sp], scale [S], shear [Sh], and scale translate [St] components as follows:

	   -1                  
	[Sp]x[S]x[Sh]x[Sp]x[St]

Where [Sp] is the scale pivot, [S] is the scale matrix, [Sh] is the shear matrix, and [St] is the scale pivot translation.

Return Value

• The scale matrix.

MMatrix MPxTransformationMatrix:: asScaleMatrixInverse () const

Description

Returns inverse of the scale matrix. The scale matrix takes points from object space to the space immediately following scale and shear transformations.

By default this value is described by:

	     -1                    -1 
	[ [Sp]x[S]x[Sh]x[Sp]x[St] ]

Where [Sp] is the scale pivot, [S] is the scale matrix, [Sh] is the shear matrix, and [St] is the scale pivot translation.

Return Value

• The inverse space matrix.

MMatrix MPxTransformationMatrix:: asRotateMatrix () const

Description

Returns the rotate section of the transformation matrix. By default this is described as:

	   -1                  
	[Rp]x[Ro]x[R]x[Rp]

Where [Rp] is the rotate pivot, [Ro] is the rotate orientation, [R] is the rotate matrix, and [Rt] is the rotate pivot translation.

Return Value

• The rotate matrix.

MMatrix MPxTransformationMatrix:: asRotateMatrixInverse () const

Description

Returns the inverse of the rotate matrix. By default this is described as:

	     -1                    -1 
	[ [Rp]x[Ro]x[R]x[Rp]x[Rt] ]

Where [Rp] is the rotate pivot, [Ro] is the rotate orientation, [R] is the rotate matrix, and [Rt] is the rotate picot translation.

Return Value

• The inverse rotate matrix.

MMatrix MPxTransformationMatrix:: asMatrix (double percent) const

Description

Returns a matrix that represents the specified percentage of this transformation matrix. This is performed on a component basis.

Return Value

• The resulting matrix.

MMatrix MPxTransformationMatrix:: asInterpolationMatrix (const MTransformationMatrix &toM, double percent, bool rot, int direction ) const

Description

Returns a matrix that represents the specified percentage of this transformation matrix. The two matrices involved in the interpolation are this transformation matrix and the passed transformation matrix, toMatrix.

This is used by clusters.

Arguments

• toM The matrix to interpolate to.
• percent The percentage of the interpolation (between 0 and 1)
• rot Should the rotation values be included?
• direction The desired direction of the interpolation.
  • 0 Closest path between this matrix and toMatrix.
  • 1 From this matrix to toMatrix.
  • 2 From toMatrix to this matrix.

Return Value

• The interpolated matrix.

MTransformationMatrix MPxTransformationMatrix:: asTransformationMatrix () const

Description

Returns the custom transformation matrix as a standard MTransformationMatrix.

Return Value

• The transformation matrix.

MVector MPxTransformationMatrix:: translation ( MSpace::Space space , MStatus * ReturnStatus ) const

Description

Returns the translation component of the transformation matrix as a MVector in centimeters (the internal Maya linear unit).

Arguments

• space The space to use.
• ReturnStatus Return status.

Return Value

• The translation vector in centimeters.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus MPxTransformationMatrix:: translateTo (const MVector &t, MSpace::Space space )

Description

Sets the translate component of the transformation matrix in centimeters.

Arguments

• t The new translate value in centimeters.
• space The space to use.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus MPxTransformationMatrix:: translateBy (const MVector &t, MSpace::Space space )

Description

Add to the translate component by translating relative to the existing transformation. The relative translate should be in centimeters.

Arguments

• t The relative translate value in centimeters.
• space The space to use.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MQuaternion MPxTransformationMatrix:: rotation ( MSpace::Space space , MStatus *ReturnStatus ) const

Description

Returns the rotation component of the transformation matrix as a quaternion. If an invalid space is used, MQuaternion::identity will be returned.

Arguments

• space The space in which to get the rotation.
• ReturnStatus The status.

Return Value

• The quaternion that is the rotation component of the transformation matrix

Status Codes

• MS::kSuccess Operation successful
• MS::kInvalidParameter Invalid space

MEulerRotation MPxTransformationMatrix:: eulerRotation ( MSpace::Space , MStatus *ReturnStatus ) const

Description

Returns the rotation component of the transformation matrix as a euler rotation. If an invalid space is used, MEulerRotation::identity will be returned.

Arguments

• space The space in which to get the rotation.
• ReturnStatus Return status.

Return Value

• The euler angle that is the rotation component of the transformation matrix.

Status Codes

• MS::kSuccess Operation successful
• MS::kInvalidParameter Invalid space

MStatus MPxTransformationMatrix:: rotateTo (const MQuaternion &quat, MSpace::Space space )

Description

Sets the rotation component of the transformation matrix using a quaternion.

Arguments

• quat The quaternion used to set the rotation component of the transformation matrix.
• space The space to use.

Return Value

• Return status.

Status Codes

• MS::kSuccess Success
• MS::kInvalidParameter Invalid space

MStatus MPxTransformationMatrix:: rotateTo (const MEulerRotation &euler, MSpace::Space space )

Description

Sets the rotation component of the transformation matrix using an euler rotation.

Arguments

• euler The euler rotation used to set the transformation matrix.
• space The space used to set the rotation.

Return Value

• Return status.

Status Codes

• MS::kSuccess Success
• MS::kInvalidParameter Invalid space

MStatus MPxTransformationMatrix:: rotateBy (const MQuaternion &quat, MSpace::Space space )

Description

Rotates relative to the current rotation value of the transformation matrix. By default, the only valid transformation spaces for this method are MSpace::kTransform and MSpace::kPreTransform. All other spaces are treated as being equivalent to MSpace::kTransform.

Arguments

• quat The relative rotation as a quaternion.
• space The space in which the rotation is performed.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method was successful.
• MS::kInvalidParameter An invalid space was used.

MStatus MPxTransformationMatrix:: rotateBy (const MEulerRotation &euler, MSpace::Space space )

Description

Rotates relative to the current rotation value of the transformation matrix. By default, the only valid transformation spaces for this method are MSpace::kTransform and MSpace::kPreTransform. All other spaces are treated as being equivalent to MSpace::kTransform.

Arguments

• euler The relative rotation as an euler angle.
• space The space in which the rotation is performed.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method was successful.
• MS::kInvalidParameter An invalid space was used.

MTransformationMatrix::RotationOrder MPxTransformationMatrix:: rotationOrder ( MStatus *ReturnStatus ) const

Description

Returns the rotation order used by the rotation component of the transformation matrix.

Arguments

• ReturnStatus Return status.

Return Value

• The rotation order use by the rotation component of the transformation matrix.

Status Codes

• MS::kSuccess The method was successful.
• MS::kFailure The method failed.

MStatus MPxTransformationMatrix:: setRotationOrder ( MTransformationMatrix::RotationOrder rotOrder, bool preserve )

Description

Sets the rotation order used by the rotation component of the transformation matrix.

Arguments

• rotOrder The rotation order to use
• preserve If true then the values will change to preserve the rotation.

Return Value

• the return status

Status Codes

• MS::kSuccess The method was successful.
• MS::kFailure The method failed.

MQuaternion MPxTransformationMatrix:: rotateOrientation ( MSpace::Space space , MStatus * ReturnStatus ) const

Description

Returns the rotate orientation for the transformation matrix as a quaternion. The rotate orientation orients the local rotation space.

Arguments

• space The space to use.
• ReturnStatus The return status.

Return Value

• The rotate orientation.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed.

MStatus MPxTransformationMatrix:: setRotateOrientation (const MQuaternion &q, MSpace::Space space , bool balance )

Description

Sets the rotate orientation for the transformation matrix to the passed euler rotation. The rotate orientation is the rotation that orients the local rotation space.

Arguments

• q The rotate orientation.
• space The space to use.
• balance If true, the overall rotation will be preserved by altering the rotation to compensate for the change in rotate orientation.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter An invalid space was used.

MEulerRotation MPxTransformationMatrix:: eulerRotateOrientation ( MSpace::Space space , MStatus * ReturnStatus ) const

Description

Returns the rotate orientation for the transformation matrix as an euler rotation. The rotate orientation orients the local rotation space.

Arguments

• space The space to use.
• ReturnStatus Return status.

Return Value

• The rotate orientation as an euler angle.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter An invalid space was used.

MStatus MPxTransformationMatrix:: setRotateOrientation (const MEulerRotation &euler, MSpace::Space space , bool balance )

Description

Sets the rotate orientation for the transformation matrix to the passed quaternion. The rotate orientation is the rotation that orients the local rotation space.

Arguments

• euler The rotate orientation.
• space The space to use.
• balance If true, the overall rotation will be preserved by altering the rotation to compensate for the change in rotate orientation.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter An invalid space was used.

MVector MPxTransformationMatrix:: scale ( MSpace::Space space , MStatus * ReturnStatus ) const

Description

Returns the scale component of the transformation matrix. If the space is invalid a MVector with all of its components being 1.0 is returned.

Only the scale is returned, without the scale pivot, scale pivot translate, or shear values applied.

Arguments

• space transform space in which to get the scale
• ReturnStatus return status

Return Value

• vector holding the x, y, and z scale components

Status Codes

• MS::kSuccess Success
• MS::kInvalidParameter Invalid space

MStatus MPxTransformationMatrix:: scaleTo (const MVector &newScale, MSpace::Space space )

Description

Set the scale component of the transformation matrix. If an invalid space is passed, the scale will not be changed.

Arguments

• newScale A vector holding the scale components.
• space The space in which to perform the scale.

Return Value

• return status

Status Codes

• MS::kSuccess Success
• MS::kInvalidParameter Invalid space

MStatus MPxTransformationMatrix:: scaleBy (const MVector &scaleFactor, MSpace::Space space )

Description

Apply a relative scale to the existing scale.

Arguments

• scaleFactor A MVector holding the scale components.
• space The space in which to perform the scale.

Return Value

• return status.

Status Codes

• MS::kSuccess Success
• MS::kInvalidParameter Invalid space

MVector MPxTransformationMatrix:: shear ( MSpace::Space space , MStatus * ReturnStatus ) const

Description

Returns the shear component of the transformation matrix.

Arguments

• space The space to use.
• ReturnStatus Return status.

Return Value

• A MVector holding the xy, xz, yz values of shear.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus MPxTransformationMatrix:: shearTo (const MVector & newShear, MSpace::Space space )

Description

Sets the shear component of the transformation matrix.

Arguments

• newShear The new shear value.
• space The space to use for setting the shear.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus MPxTransformationMatrix:: shearBy (const MVector & shearOffset, MSpace::Space space )

Description

Apply a new shear to the existing shear component of the transformation matrix. The shear values are added by multiplying the individual shear components with the offset values.

Arguments

• shearOffset The relative shear value.
• space The space to use.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MPoint MPxTransformationMatrix:: scalePivot ( MSpace::Space space , MStatus * ReturnStatus ) const

Description

Returns the pivot used by the scale. The value is in centimeters.

Arguments

• space The space to use.
• ReturnStatus Return status.

Return Value

• The scale pivot point.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus MPxTransformationMatrix:: setScalePivot (const MPoint & scalePivot , MSpace::Space space , bool balance )

Description

Set the pivot used by the scale.

If balance if true, then the overall transformation matrix will not change and a compensating translation will be added to the scale pivot transformation to achieve this.

If an invalid space is used, the scale pivot will not change.

Arguments

• scalePivot The new scale pivot value.
• space The space to use.
• balance Set true is the overall transform should remain unchanged after setting the new scale pivot value.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MVector MPxTransformationMatrix:: scalePivotTranslation ( MSpace::Space space , MStatus * ReturnStatus ) const

Description

Returns the scale pivot translation, which is used to compensate for changes of the scale pivot.

Arguments

• space The space to use.
• ReturnStatus Return status.

Return Value

• The scale pivot translation.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus MPxTransformationMatrix:: setScalePivotTranslation (const MVector &v, MSpace::Space space )

Description

Set the scale pivot translation. When the scale pivot is changed, there is an option to automatically compensate for the change so that the overall transformation is not altered. The compensating factor is the scale pivot translation.

This method will manually change the scale pivot translation.

Arguments

• v The new scale pivot translation.
• space The space to use.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MPoint MPxTransformationMatrix:: rotatePivot ( MSpace::Space space , MStatus * ReturnStatus ) const

Description

Returns the pivot used by the rotation.

Arguments

• space The space to use.
• ReturnStatus Return status.

Return Value

• The rotation pivot point.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space.

MStatus MPxTransformationMatrix:: setRotatePivot (const MPoint & rotatePivot , MSpace::Space space , bool balance )

Description

Set the pivot used by the rotation.

If balance if true, then the overall transformation will not change and a compensating translation will be added to the rotation transformation to achieve this.

For the default case, the balance calculation is as follows:

    Let [Rp] be the previous rotate pivot and [Rt] be the previous 
    rotate pivot translation. The new rotate pivot will be marked as
    [Rp'] and the new rotate pivot translation as [Rt']

    If balance is true the entire rotate section of the transform
    must be the same before and after the rotate pivot is changed:

       -1                         -1
    [Rp]x[Ro]x[R]x[Rp]x[Rt] = [Rp']x[Ro]x[R]x[Rp']x[Rt']

    solving for [Rt'] produces:
                 -1               -1     -1
    [Rt'] = [[Rp']x[Ro]x[R]x[Rp']]  x  [Rp]x[Ro]x[R]x[Rp]x[Rt]

Arguments

• rotatePivot The new rotate pivot.
• space The space to use.
• balance Set true is the overall transform should remain unchanged after setting the new rotate pivot value.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MVector MPxTransformationMatrix:: rotatePivotTranslation ( MSpace::Space space , MStatus * ReturnStatus ) const

Description

Returns the rotate pivot translation, which is used to compensate for changes of the rotate pivot.

Arguments

• space The space to use.
• ReturnStatus Return status.

Return Value

• The rotate pivot translation.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space.

MStatus MPxTransformationMatrix:: setRotatePivotTranslation (const MVector &v, MSpace::Space space )

Description

Set the rotate pivot translation. When the scale pivot is changed, there is an option to automatically compensate for the change so that the overall transformation is not altered. The compensating factor is the rotate pivot translation.

See the documentation for setRotatePivot for an explanation of the compensating calculation.

Arguments

• v The new rotate pivot translation.
• space The space to use.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus MPxTransformationMatrix:: unSquishIt ()

Description

Remove any shearing and any non-proportional scaling from this transform. If the scaling is non-proportional, then the maximum scale of the three scale axes will be used on all of the scale axes.

If new scaling or shearing types are added to a derived class, this method should be overloaded.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space.

MMatrix MPxTransformationMatrix:: unSquishMatrix () const

Description

Remove any shearing and any non-proportional scaling. If the scaling is non-proportional, then the maximum scale of the three scale axes will be used on all of the scale axes. The method creates a new 4x4 MMatrix and leaves this transformation matrix unchanged.

If new scaling or shearing types are added to a derived class, this method should be overloaded.

Return Value

• The unsquished 4x4 matrix.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space.

MTransformationMatrix::RotationOrder MPxTransformationMatrix:: convertEulerRotationOrder ( MEulerRotation::RotationOrder eulerOrder, MStatus *ReturnStatus )

Description

Convert from MEulerRotation::RotationOrder to MTransformationMatrix::RotationOrder.

Arguments

• eulerOrder The MEulerRotation::RotationOrder
• ReturnStatus return status

Return Value

• The corresponding MTransformationMatrix::RotationOrder.

Status Codes

• MS::kInvalidParameter No matching enum was found.
• MS::kSuccess Operation successful

MTransformationMatrix::RotationOrder MPxTransformationMatrix:: convertRotationOrder ( MEulerRotation::RotationOrder eulerOrder, MStatus *ReturnStatus )

Description

This method is OBSOLETE and has NO SCRIPT SUPPORT. Please use the convertEulerRotationOrder() method instead.

MEulerRotation::RotationOrder MPxTransformationMatrix:: convertTransformationRotationOrder ( MTransformationMatrix::RotationOrder xformOrder, MStatus *ReturnStatus )

Description

Convert from MTransformationMatrix::RotationOrder to MEulerRotation::RotationOrder. If MTransformationMatrix::kLast or MTransformationMatrix::kInvalid is passed in, MEulerRotation::kXYZ will be returned along with a kInvalidParameter return status.

Arguments

• xformOrder The MTransformationMatrix::RotationOrder
• ReturnStatus return status

Return Value

• The corresponding MEulerRotation::RotationOrder.

Status Codes

• MS::kInvalidParameter No matching enum was found.
• MS::kSuccess Operation successful

MEulerRotation::RotationOrder MPxTransformationMatrix:: convertRotationOrder ( MTransformationMatrix::RotationOrder xformOrder, MStatus *ReturnStatus )

Description

This method is OBSOLETE and has NO SCRIPT SUPPORT. Please use the convertTransformationRotationOrder() method instead.

void *MPxTransformationMatrix:: creator ()

Description

A method to use when registering a custom transform that uses a default MPxTransformationMatrix.

The caller is responsible for deleting the memory created by this method.

Return Value

• The new MPxTransformationMatrix

std::ostream & operator << (std::ostream &os, const MPxTransformationMatrix &m)

Description

A method to easily dump the contents of a transformation matrix.

Arguments

• os The ostream to use.
• m The transformation matrix to print.

Return Value

• ostream

MStatus MPxTransformationMatrix:: decomposeMatrix (const MMatrix &m)

Description

This method converts a passed MMatrix into individual transformation matrix components. The default algorithm will solve under the assumption that the pivots and pivot translates are all zero.

It is possible that multiple transformation matrices may produce identical 4x4 matrices. This means that taking a generic transformation matrix and converting it to a MMatrix and back to a transformation matrix may have different components, but the net transformation will still be the same.

Arguments

• m The matrix to break up into components.

Return Value

• Return status.

Status Codes

• MS::kSuccess The method succeeded.
• MS::kFailure The method failed.

This class has no child classes.