#include
<MTransformationMatrix.h>
List of all
members.
Detailed Description
Transformation matrix.
An MTransformationMatrix allows the
manipulation of the individual transformation components (eg scale,
rotation, shear, etc) of a four by four transformation matrix.
The transformation in the node is represented as a 4x4
transformation matrix. This class allows access to the whole
matrix, or the individual components (eg scale, rotation, shear,
etc) of the transformation. This breakdown provides animators fine
control over the animation of these parameters. Therefore, it is
necessary to describe the order in which these attributes are
applied to build the final matrix attribute.
A transformation matrix is composed of the following
components:
- Scale pivot point point around which scales are
performed [Sp]
- Scale scaling about x, y, z axes [S]
- Shear shearing in xy, xz, yx [Sh]
- Scale pivot translation translation introduced to
preserve existing scale transformations when moving pivot. This is
used to prevent the object from moving when the objects pivot point
is not at the origin and a non-unit scale is applied to the object
[St].
- Rotate pivot point point about which rotations are
performed [Rp]
- Rotation orientation rotation to orient local rotation
space [Ro]
- Rotation rotation [R]
- Rotate pivot translation translation introduced to
preserve exisitng rotate transformations when moving pivot. This is
used to prevent the object from moving when the objects pivot point
is not at the origin and the pivot is moved. [Rt]
- Translate translation in x, y, z axes [T]
Note that the default RotationOrder is kXYZ.
The matrices are post-multiplied in Maya. For example, to
transform a point P from object-space to world-space (P') you would
need to post-multiply by the worldMatrix. (P' = P x WM)
The transformation matrix is then constructed as follows:
-1 -1
[Sp]x[S]x[Sh]x[Sp]x[St]x[Rp]x[Ro]x[R]x[Rp]x[Rt]x[T]
where 'x' denotes matrix multiplication and '-1' denotes matrix
inversion
Sp = | 1 0 0 0 | St = | 1 0 0 0 |
| 0 1 0 0 | | 0 1 0 0 |
| 0 0 1 0 | | 0 0 1 0 |
| spx spy spz 1 | | sptx spty sptz 1 |
S = | sx 0 0 0 | Sh = | 1 0 0 0 |
| 0 sy 0 0 | | shxy 1 0 0 |
| 0 0 sz 0 | | shxz shyz 1 0 |
| 0 0 0 1 | | 0 0 0 1 |
Rp = | 1 0 0 0 | Rt = | 1 0 0 0 |
| 0 1 0 0 | | 0 1 0 0 |
| 0 0 1 0 | | 0 0 1 0 |
| rpx rpy rpz 1 | | rptx rpty rptz 1 |
Ro = AX * AY * AZ
AX = | 1 0 0 0 | AY = | cy 0 -sy 0 |
| 0 cx sx 0 | | 0 1 0 0 |
| 0 -sx cx 0 | | sy 0 cy 0 |
| 0 0 0 1 | | 0 0 0 1 |
AZ = | cz sz 0 0 | sx = sin(rax), cx = cos(rax)
| -sz cz 0 0 | sy = sin(ray), cx = cos(ray)
| 0 0 1 0 | sz = sin(raz), cz = cos(raz)
| 0 0 0 1 |
R = RX * RY * RZ (Note: order is determined by rotateOrder)
RX = | 1 0 0 0 | RY = | cy 0 -sy 0 |
| 0 cx sx 0 | | 0 1 0 0 |
| 0 -sx cx 0 | | sy 0 cy 0 |
| 0 0 0 1 | | 0 0 0 1 |
RZ = | cz sz 0 0 | sx = sin(rx), cx = cos(rx)
| -sz cz 0 0 | sy = sin(ry), cx = cos(ry)
| 0 0 1 0 | sz = sin(rz), cz = cos(rz)
| 0 0 0 1 |
T = | 1 0 0 0 |
| 0 1 0 0 |
| 0 0 1 0 |
| tx ty tz 1 |
-
buildRotationNode.cpp,
D3DResourceManager.cpp,
D3DViewportRenderer.cpp,
dagPoseInfoCmd.cpp,
hwReflectBumpShader_NV20.cpp,
hwRefractReflectShader_NV20.cpp,
rockingTransform.cpp,
scanDagCmd.cpp, scanDagSyntax.cpp,
simpleFluidEmitter.cpp,
squareScaleManipContext.cpp,
and surfaceBumpManip.cpp.
|
Public Types
|
enum |
RotationOrder {
kInvalid,
kXYZ,
kYZX,
kZXY,
kXZY,
kYXZ,
kZYX,
kLast
} |
|
Order of rotation.
More...
|
Public Member Functions
|
|
~MTransformationMatrix () |
|
MTransformationMatrix () |
|
MTransformationMatrix (const MTransformationMatrix
&src) |
|
MTransformationMatrix (const MMatrix &src) |
MTransformationMatrix
& |
operator= (const MTransformationMatrix
&src) |
MTransformationMatrix
& |
operator= (const MMatrix &src) |
MMatrix |
asMatrix () const |
MMatrix |
asMatrix (double percent) const |
MMatrix |
asMatrixInverse () const |
MMatrix |
asScaleMatrix () const |
MMatrix |
asRotateMatrix () const |
MStatus |
getScale (double scale[3], MSpace::Space
space) const |
MStatus |
setScale (const double scale[3], MSpace::Space
space) |
MStatus |
addScale (const double scale[3], MSpace::Space
space) |
MQuaternion |
rotation () const |
MTransformationMatrix
& |
rotateTo (const MQuaternion &q) |
MTransformationMatrix
& |
rotateBy (const MQuaternion &q, MSpace::Space
space, MStatus
*ReturnStatus=NULL) |
MEulerRotation |
eulerRotation () const |
MTransformationMatrix
& |
rotateTo (const MEulerRotation &e) |
MTransformationMatrix
& |
rotateBy (const MEulerRotation &e, MSpace::Space
space, MStatus
*ReturnStatus=NULL) |
MStatus |
getRotationQuaternion (double &x, double &y, double
&z, double &w) const |
MStatus |
setRotationQuaternion (double x, double y, double z, double
w) |
MStatus |
addRotationQuaternion (double x, double y, double z, double w,
MSpace::Space) |
MStatus |
getRotation (double[3],
RotationOrder &order) const |
MStatus |
setRotation (const double rotation[3],
RotationOrder order) |
MStatus |
addRotation (const double rotation[3],
RotationOrder order, MSpace::Space) |
RotationOrder |
rotationOrder (MStatus *ReturnStatus=NULL) const |
MStatus |
reorderRotation (const
RotationOrder &order) |
MStatus |
setToRotationAxis (const MVector &axis, double rotation) |
MQuaternion |
rotationOrientation () const |
MTransformationMatrix
& |
setRotationOrientation (const MQuaternion &q) |
MVector |
getTranslation (MSpace::Space,
MStatus
*ReturnStatus=NULL) const |
MStatus |
setTranslation (const MVector &vector, MSpace::Space) |
MStatus |
addTranslation (const MVector &vector, MSpace::Space) |
MStatus |
setShear (const double shear[3], MSpace::Space
space) |
MStatus |
getShear (double shear[3], MSpace::Space
space) const |
MStatus |
addShear (const double shear[3], MSpace::Space
space) |
MPoint |
scalePivot (MSpace::Space,
MStatus
*ReturnStatus=NULL) const |
MStatus |
setScalePivot (const MPoint &, MSpace::Space,
bool balance) |
MVector |
scalePivotTranslation (MSpace::Space,
MStatus
*ReturnStatus=NULL) const |
MStatus |
setScalePivotTranslation (const MVector &vector, MSpace::Space) |
MPoint |
rotatePivot (MSpace::Space,
MStatus
*ReturnStatus=NULL) const |
MStatus |
setRotatePivot (const MPoint &point, MSpace::Space,
bool balance) |
MVector |
rotatePivotTranslation (MSpace::Space
space, MStatus
*ReturnStatus=NULL) const |
MStatus |
setRotatePivotTranslation (const MVector &vector, MSpace::Space
space) |
bool |
isEquivalent (const MTransformationMatrix
&other, double tolerance=1.0e-10) const |
bool |
operator== (const MTransformationMatrix
&other) const |
bool |
operator!= (const MTransformationMatrix
&other) const |
MStatus |
getRotation (double[3],
RotationOrder &order, MSpace::Space)
const |
|
This method is obsolete.
|
MStatus |
setRotation (const double rotation[3],
RotationOrder order, MSpace::Space) |
|
This method is obsolete.
|
MStatus |
getRotationQuaternion (double &x, double &y, double
&z, double &w, MSpace::Space)
const |
|
This method is obsolete.
|
MStatus |
setRotationQuaternion (double x, double y, double z, double w,
MSpace::Space) |
|
This method is obsolete.
|
MVector |
translation (MSpace::Space,
MStatus
*ReturnStatus=NULL) const |
|
This method is obsolete.
|
Static Public Attributes
|
static const MTransformationMatrix |
identity |
|
The identity transformation
matrix.
|
Member Enumeration Documentation
Order of rotation.
- Enumerator:
-
kInvalid |
|
kXYZ |
|
kYZX |
|
kZXY |
|
kXZY |
|
kYXZ |
|
kZYX |
|
kLast |
|
Constructor & Destructor Documentation
MTransformationMatrix::~MTransformationMatrix |
( |
|
) |
|
MTransformationMatrix::MTransformationMatrix |
( |
|
) |
|
Class Copy Constructor.
- Parameters:
-
[in] |
src |
transform matrix to be copied |
MTransformationMatrix::MTransformationMatrix |
( |
const MMatrix & |
src |
) |
|
Class Constructor.
- Parameters:
-
[in] |
src |
matrix to be copied |
Member Function Documentation
Copy operator.
- Parameters:
-
[in] |
src |
transform matrix to be copied |
Copy operator.
- Parameters:
-
[in] |
src |
matrix to be copied |
- Returns:
- This transformation matrix
MMatrix
MTransformationMatrix::asMatrix |
( |
|
) |
const |
Returns the four by four matrix that describes this
transformation
- Returns:
- The matrix
MMatrix
MTransformationMatrix::asMatrix |
( |
double |
percent |
) |
const |
Returns a matrix that represents the specified percentage of
this transformation matrix.
- Parameters:
-
[in] |
percent |
percent of the transformation to return |
- Returns:
- The percentage matrix
MMatrix
MTransformationMatrix::asMatrixInverse |
( |
|
) |
const |
Returns the inverse of the four by four matrix that describes
this transformation.
- Returns:
- The matrix
MMatrix
MTransformationMatrix::asScaleMatrix |
( |
|
) |
const |
Returns scale space matrix. The scale space matrix takes points
from object space to the space immediately following scale and
shear transformations.
- Returns:
- The scale space matrix
MMatrix
MTransformationMatrix::asRotateMatrix |
( |
|
) |
const |
Returns rotate space matrix. The rotate space matrix takes
points from object space to the space immediately following the
scale/shear/rotation transformations.
- Returns:
- The rotate space matrix
Get the scale component of the transformation matrix.
- Parameters:
-
[out] |
scale |
storage for the scale component |
[in] |
space |
transform space in which to get the scale |
- Returns:
- Return status
- Status Codes:
-
Set the scale component of the transformation matrix.
- Parameters:
-
[in] |
scale |
new scale component |
[in] |
space |
transform space in which to perform the scale |
- Returns:
- Return status
- Status Codes:
-
Add to the scale component by scaling relative to the existing
transformation.
- Parameters:
-
[in] |
scale |
relative value to scale by |
[in] |
space |
transform space in which to perform the scale |
- Returns:
- Return status
- Status Codes:
-
Returns the rotation component of the transformation matrix as a
quaternion. The rotation is returned in MSpace::kTransform
space.
- Returns:
- Quaternion that is the rotation component of the transformation
matrix
Sets the rotation component of the transformation matrix using a
quaternion. The rotation is performed in MSpace::kTransform
space.
- Parameters:
-
[in] |
q |
the quaternion to which the rotation component of the
transformation matrix should be set |
- Returns:
- A reference to the resulting transformation matrix
Adds to the rotation component of the rotation matrix by
rotating relative to the existing transformation using a
quaternion. The only valid transformation spaces for this method
are MSpace::kTransform
and MSpace::kPreTransform/MSpacekObject.
All other spaces are treated as being equivalent to MSpace::kTransform.
- Parameters:
-
[in] |
q |
the quaternion that indicates how much the transformation
matrix will be rotated by |
[in] |
space |
the space in which the rotation is performed |
[out] |
ReturnStatus |
return status |
- Returns:
- A reference to the resulting transformation matrix
- Status Codes:
-
Returns the rotation component of the transformation matrix as
an euler rotation.
- Returns:
- Euler rotation that is the rotation component of the
transformation matrix
Sets the rotation component of the transformation matrix using
an euler rotation. The rotation is performed in MSpace::kTransform
space.
- Parameters:
-
[in] |
e |
the euler rotation to which the rotation component of the
transformation matrix should be set |
- Returns:
- A reference to the resulting transformation matrix
Adds to the rotation component of the rotation matrix by
rotating relative to the existing transformation using an euler
rotation. The only valid transformation spaces for this method are
MSpace::kTransform
and MSpace::kPreTransform/MSpacekObject.
All other spaces are treated as being equivalent to MSpace::kTransform.
- Parameters:
-
[in] |
e |
the euler rotation that indicates how much the transformation
matrix will be rotated by |
[in] |
space |
the space in which the rotation is performed |
[out] |
ReturnStatus |
return status |
- Returns:
- A reference to the resulting transformation matrix
- Status Codes:
-
MStatus
MTransformationMatrix::getRotationQuaternion |
( |
double & |
x, |
|
|
double & |
y, |
|
|
double & |
z, |
|
|
double & |
w |
|
|
) |
|
|
const |
Get the rotation component of the transformation matrix as a
quaternion. The rotation is retrieved in MSpace::kTransform
space.
- Parameters:
-
[out] |
x |
storage for the x component of the quaternion |
[out] |
y |
storage for the y component of the quaternion |
[out] |
z |
storage for the z component of the quaternion |
[out] |
w |
storage for the w component of the quaternion |
- Returns:
- Return status
- Status Codes:
-
MStatus
MTransformationMatrix::setRotationQuaternion |
( |
double |
x, |
|
|
double |
y, |
|
|
double |
z, |
|
|
double |
w |
|
|
) |
|
|
|
Set the rotation component of the transformation matrix using a
quaternion. The rotation is set in MSpace::kTransform
space.
- Parameters:
-
[in] |
x |
x component of new quaternion |
[in] |
y |
y component of new quaternion |
[in] |
z |
z component of new quaternion |
[in] |
w |
w component of new quaternion |
- Returns:
- Return status
- Status Codes:
-
MStatus
MTransformationMatrix::addRotationQuaternion |
( |
double |
x, |
|
|
double |
y, |
|
|
double |
z, |
|
|
double |
w, |
|
|
MSpace::Space |
space |
|
|
) |
|
|
|
Add to the rotation component by rotating relative to the
existing transformation. Rotation is a quaternion. 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.
- Parameters:
-
[in] |
x |
x component of quaternion |
[in] |
y |
y component of quaternion |
[in] |
z |
z component of quaternion |
[in] |
w |
w component of quaternion |
- Returns:
- Return status
- Status Codes:
-
Get the rotation component of the transformation matrix in
radians. The rotation is retrieved in MSpace::kTransform
space.
- Parameters:
-
[out] |
rot |
storage for the rotation in radians |
[in] |
order |
storage for the rotation order |
- Returns:
- Return status
- Status Codes:
-
Set the rotation component of the transformation matrix. The
rotation is set in MSpace::kTransform
space.
- Parameters:
-
[in] |
rot |
new rotation component in radians |
[in] |
order |
order in which to apply rotations |
- Returns:
- Return status
- Status Codes:
-
Add to the rotation component by rotating relative to the
existing transformation. 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.
- Parameters:
-
[in] |
rot |
relative value to rotate by |
[in] |
space |
transform space in which to perform the rotation |
- Returns:
- Return status
- Status Codes:
-
Returns the rotation order for the transform matrix. That is the
order in which the Euler angles are applied to create the end
rotation.
- Parameters:
-
[out] |
ReturnStatus |
return status |
- Returns:
- Rotation order
- Status Codes:
-
Reorders the x, y, and z components of the rotation of this
transform. The overall rotation will remain the same. This
operation is not unique, so spin information will be lost.
- Parameters:
-
[in] |
order |
new order of the rotations |
- Returns:
- Return status
- Status Codes:
-
MStatus
MTransformationMatrix::setToRotationAxis |
( |
const MVector & |
axis, |
|
|
double |
rotation |
|
|
) |
|
|
|
Sets the rotation given an axis and a rotation about it.
- Parameters:
-
[in] |
axis |
axis to rotate about |
[in] |
rotation |
rotation in radians |
- Returns:
- Return status
- Status Codes:
-
MQuaternion
MTransformationMatrix::rotationOrientation |
( |
|
) |
const |
Returns the rotation orientation for the transformation matrix.
The rotation orientation is the rotation that orients the local
rotation space. The rotation is returned in MSpace::kTransform
space.
- Returns:
- Rotation orientation
Sets the rotation orientation for the transformation matrix. The
rotation orientation is the rotation that orients the local
rotation space. The rotation is set in MSpace::kTransform
space.
- Returns:
- Rotation orientation
Returns the translation component of the translation as a vector
in centimeters.
- Parameters:
-
[in] |
space |
space in which to perform the translation |
[out] |
ReturnStatus |
return status |
- Returns:
- Translation vector in centimeters
- Status Codes:
-
Set the translation component of the transformation matrix in
centimeters.
- Parameters:
-
[in] |
vector |
new translation component in centimeters. |
[in] |
space |
transform space in which to perform the translation |
- Returns:
- Return status
- Status Codes:
-
Add to the translation component by translating relative to the
existing transformation.
- Parameters:
-
[in] |
vector |
relative value to translate by |
[in] |
space |
transform space in which to perform the scale |
- Returns:
- Return status
- Status Codes:
-
Set the shear component of the transformation matrix. The shear
values represent (xy, xz, yx).
- Parameters:
-
[in] |
shear |
new shear component |
[in] |
space |
transform space in which to perform the shear |
- Returns:
- Return status
- Status Codes:
-
Get the shear component of the transformation matrix.
- Parameters:
-
[out] |
shear |
Shear. |
[in] |
space |
Transform space in which to get the shear. |
- Returns:
- Return status
- Status Codes:
-
Add to the shear component by shearing relative to the existing
transformation.
- Parameters:
-
[in] |
shear |
relative value to shear by |
[in] |
space |
transform space in which to perform the shear |
- Returns:
- Return status
- Status Codes:
-
Returns the pivot around which the scale is applied.
- Parameters:
-
[in] |
space |
space in which to get the pivot |
[out] |
ReturnStatus |
return status |
- Returns:
- Scale pivot point
- Status Codes:
-
Set the pivot around which the scale is applied.
If balance if true, then the overall transformation matrix will
not change and a compensating transformation will be added to the
scale transformation to achieve this.
- Parameters:
-
[in] |
point |
new scale pivot |
[in] |
space |
transform space in which to set the scale pivot |
[in] |
balance |
whether to balance the matrix |
- Returns:
- Return status
- Status Codes:
-
Returns the scale pivot translation. This is the translation
that is used to compensate for the movement of the scale pivot.
- Parameters:
-
[in] |
space |
space in which to get the pivot |
[out] |
ReturnStatus |
return status |
- Returns:
- Scale pivot translation
- Status Codes:
-
Set the pivot translation. This component is used to preserve
existing scale transformations when moving pivot. This method will
only be useful to advanced users.
- Parameters:
-
[in] |
vector |
new scale pivot translation |
[in] |
space |
transform space in which to set the scale translation |
- Returns:
- Return status
- Status Codes:
-
Returns the pivot around which the rotation is applied.
- Parameters:
-
[in] |
space |
space in which to get the pivot |
[out] |
ReturnStatus |
return status |
- Returns:
- Rotation pivot point
- Status Codes:
-
Set the pivot around which the rotation is applied.
If balance if true, then the overall transformation matrix will
not change and a compensating transformation will be added to the
rotation transformation to achieve this.
- Parameters:
-
[in] |
point |
new rotation pivot |
[in] |
space |
transform space in which to set the pivot |
[in] |
balance |
whether to balance the matrix |
- Returns:
- Return status
- Status Codes:
-
Returns the rotation pivot translation. This is the translation
that is used to compensate for the movement of the rotation
pivot.
- Parameters:
-
[in] |
space |
space in which to get the pivot translation |
[out] |
ReturnStatus |
return status |
- Returns:
- Scale pivot translation
- Status Codes:
-
Set the pivot translation. This component is used to preserve
existing transformations when moving pivot. This method will only
be useful to advanced users.
- Parameters:
-
[in] |
vector |
new rotation pivot translation |
[in] |
space |
transform space in which to set the rotation translation |
- Returns:
- Return status
- Status Codes:
-
bool MTransformationMatrix::isEquivalent |
( |
const MTransformationMatrix
& |
other, |
|
|
double |
tol = 1.0e-10 |
|
|
) |
|
|
const |
Returns true if this transform matrix is equivalent to the one
passed in within a certain tolerance.
- Parameters:
-
[in] |
other |
transform matrix to test against |
[in] |
tol |
tolerance to test using |
- Returns:
- True if equivalent
Equality operator.
- Parameters:
-
[in] |
other |
transform matrix to test against |
- Returns:
- True if equal
Inequality operator.
- Parameters:
-
[in] |
other |
transform matrix to test against |
- Returns:
- True if not equal
This method is obsolete.
- Deprecated:
- Use the other
MTransformationMatrix::getRotation method instead.
This method will be removed in a future Maya release. The
transformation space argument was always treated as
MSpace::kTransform
regardless of the actual argument.
Get the rotation component in radians of the transformation
matrix.
- Parameters:
-
[out] |
rot |
storage for the rotation in radians |
[out] |
order |
storage for the rotation order |
[in] |
space |
transform space in which to get the rotation |
- Returns:
- Return status
- Status Codes:
-
This method is obsolete.
- Deprecated:
- Use the other
MTransformationMatrix::setRotation method instead.
The transformation space argument was always treated as
MSpace::kTransform
regardless of the actual argument.
Set the rotation component of the transformation matrix.
- Parameters:
-
[in] |
rot |
new rotation component |
[in] |
order |
order in which to apply rotations |
[in] |
space |
transform space in which to perform the rotation |
- Returns:
- Return status
- Status Codes:
-
MStatus
MTransformationMatrix::getRotationQuaternion |
( |
double & |
x, |
|
|
double & |
y, |
|
|
double & |
z, |
|
|
double & |
w, |
|
|
MSpace::Space |
space |
|
|
) |
|
|
const |
This method is obsolete.
- Deprecated:
- Use the other
MTransformationMatrix::getRotationQuaternion method
instead.
The transformation space argument was always treated as
MSpace::kTransform
regardless of the actual argument.
Get the rotation component of the transformation matrix as a
quaternion.
- Parameters:
-
[out] |
x |
storage for the x component of the quaternion |
[out] |
y |
storage for the y component of the quaternion |
[out] |
z |
storage for the z component of the quaternion |
[out] |
w |
storage for the w component of the quaternion |
[in] |
space |
transform space in which to get the rotation |
- Returns:
- Return status
- Status Codes:
-
MStatus
MTransformationMatrix::setRotationQuaternion |
( |
double |
x, |
|
|
double |
y, |
|
|
double |
z, |
|
|
double |
w, |
|
|
MSpace::Space |
space |
|
|
) |
|
|
|
This method is obsolete.
- Deprecated:
- Use the other
MTransformationMatrix::setRotationQuaternion method
instead.
The transformation space argument was always treated as
MSpace::kTransform
regardless of the actual argument.
Set the rotation component of the transformation matrix using a
quaternion.
- Parameters:
-
[in] |
x |
x component of new quaternion |
[in] |
y |
y component of new quaternion |
[in] |
z |
z component of new quaternion |
[in] |
w |
w component of new quaternion |
[in] |
space |
transform space in which to perform the rotation |
- Returns:
- Return status
- Status Codes:
-
This method is obsolete.
- Deprecated:
- Use
MTransformationMatrix::getTranslation instead.
Returns the translation component of the translation as a vector in
centimeters.
- Parameters:
-
[in] |
space |
space in which to perform the translation |
[out] |
ReturnStatus |
return status |
- Returns:
- Translation vector in centimeters
- Status Codes:
-