#import "CC3Matrix3x3.h"
#define kCC3Matrix4x3ColumnCount 4 |
The number of columns in a CC3Matrix4x3 structure.
#define kCC3Matrix4x3ElementCount 12 |
The number of GLfloat elements in a CC3Matrix4x3 structure.
#define kCC3Matrix4x3RowCount 3 |
The number of rows in a CC3Matrix4x3 structure.
static void CC3Matrix3x3CopyInto4x3 | ( | const CC3Matrix3x3 * | mtxSrc, |
CC3Matrix4x3 * | mtx | ||
) | [inline, static] |
Copies the specified 3x3 matrix into the specified 4x3 matrix, without changing content within the 4x3 matrix that is outside the first three rows and columns.
The fourth column of the 4x3 matrix is left unchanged.
static void CC3Matrix3x3PopulateFrom4x3 | ( | CC3Matrix3x3 * | mtx, |
const CC3Matrix4x3 * | mtxSrc | ||
) | [inline, static] |
Populates the specified 3x3 matrix from the specified 4x3 matrix.
The fourth column is dropped.
static CC3Vector CC3Matrix4x3ExtractForwardDirection | ( | const CC3Matrix4x3 * | mtx ) | [inline, static] |
Extracts and returns the 'forward' direction vector from the rotation component of the specified matrix.
static CC3Quaternion CC3Matrix4x3ExtractQuaternion | ( | const CC3Matrix4x3 * | mtx ) | [inline, static] |
Extracts and returns the rotation quaternion from the specified matrix.
This algorithm uses the technique of finding the largest combination of the diagonal elements to select which quaternion element (w,x,y,z) to solve for from the diagonal, and then using that value along with pairs of diagonally-opposite matrix elements to derive the other three quaternion elements. For example, if we want to solve for the quaternion w value first:
Similar equations exist for the other combinations of the diagonal elements. Selecting the largest combination helps numerical stability and avoids divide-by-zeros and square roots of negative numbers.
static CC3Vector CC3Matrix4x3ExtractRightDirection | ( | const CC3Matrix4x3 * | mtx ) | [inline, static] |
Extracts and returns the 'right' direction vector from the rotation component of the specified matrix.
static CC3Vector CC3Matrix4x3ExtractRotationYXZ | ( | const CC3Matrix4x3 * | mtx ) | [inline, static] |
Extracts the rotation component of the specified matrix and returns it as an Euler rotation vector, assuming the rotations should be applied in YXZ order, which is the OpenGL default.
Each element of the returned rotation vector represents an Euler angle in degrees.
static CC3Vector CC3Matrix4x3ExtractRotationZYX | ( | const CC3Matrix4x3 * | mtx ) | [inline, static] |
Extracts the rotation component of the specified matrix and returns it as an Euler rotation vector, assuming the rotations should be applied in ZYX order.
Each element of the returned rotation vector represents an Euler angle in degrees.
static CC3Vector CC3Matrix4x3ExtractUpDirection | ( | const CC3Matrix4x3 * | mtx ) | [inline, static] |
Extracts and returns the 'up' direction vector from the rotation component of the specified matrix.
static BOOL CC3Matrix4x3InvertAdjoint | ( | CC3Matrix4x3 * | mtx ) | [inline, static] |
Inverts the specified matrix by using the algorithm of calculating the classical adjoint and dividing by the determinant.
The contents of the matrix are changed.
Not all matrices are invertable. Returns whether the matrix was inverted. If this function returns NO, then the matrix was not inverted, and remains unchanged.
Matrix inversion using the classical adjoint algorithm is computationally-expensive. If it is known that the matrix contains only rotation and translation, use the CC3Matrix4x3InvertRigid function instead, which is some 10 to 100 times faster than this function.
For an affine matrix, we can invert the 3x3 linear matrix, and use it to transform the negated translation vector:
M(-1) = | L(-1) -L(-1)(t) |
where L(-1) is the inverted 3x3 linear matrix, and t is the translation vector, both extracted from the 4x3 matrix.
static void CC3Matrix4x3InvertRigid | ( | CC3Matrix4x3 * | mtx ) | [inline, static] |
Inverts the specified matrix using transposition.
The contents of this matrix are changed.
This function assumes that the matrix represents a rigid transformation, containing only rotation and translation. Use this function only if it is known that this is the case.
Inversion of a rigid transform matrix via transposition is very fast, and is consistently 10 to 100 times faster than the classical adjoint algorithm used in the CC3Matrix4x3InvertAdjoint function. It is recommended that this function be used whenever possible.
For an affine matrix that contains only rigid transforms, we can invert the 3x3 linear matrix by transposing it, and use it to transform the negated translation vector:
M(-1) = | LT -LT(t) |
where LT is the transposed 3x3 linear matrix, and t is the translation vector, both extracted from the 4x3 matrix. For a matrix containing only rigid transforms: L(-1) = LT,
static BOOL CC3Matrix4x3IsIdentity | ( | const CC3Matrix4x3 * | mtx ) | [inline, static] |
Returns whether the specified matrix is an identity matrix (ones on the diagonal, zeros elsewhere).
static void CC3Matrix4x3Multiply | ( | CC3Matrix4x3 * | mOut, |
const CC3Matrix4x3 * | mL, | ||
const CC3Matrix4x3 * | mR | ||
) | [inline, static] |
Multiplies mL on the left by mR on the right, and stores the result in mOut.
static void CC3Matrix4x3Orthonormalize | ( | CC3Matrix4x3 * | mtx, |
NSUInteger | startColNum | ||
) | [inline, static] |
Orthonormalizes the rotation component of the specified matrix, using a Gram-Schmidt process, and using the column indicated by the specified column number as the starting point of the orthonormalization process.
The specified column number should be between 1 and 3.
Upon completion, each of the first three columns in the specified matrix will be a unit vector that is orthagonal to the other two columns.
Since the Gram-Schmidt process is biased towards the starting column, if this function will be invoked repeatedly on the same matrix, it is recommended that the starting column number be changed on each invocation of this function, to ensure that the starting bias be averaged across each of the columns over the long term.
static void CC3Matrix4x3PopulateFrom3x3 | ( | CC3Matrix4x3 * | mtx, |
const CC3Matrix3x3 * | mtxSrc | ||
) | [inline, static] |
Populates the specified 4x3 matrix from the specified 3x3 matrix.
A fourth column, containing (0,0,0) is added.
static void CC3Matrix4x3PopulateFrom4x3 | ( | CC3Matrix4x3 * | mtx, |
const CC3Matrix4x3 * | mtxSrc | ||
) | [inline, static] |
Populates the specified matrix from the specified source matrix.
static void CC3Matrix4x3PopulateFromQuaternion | ( | CC3Matrix4x3 * | mtx, |
CC3Quaternion | aQuaternion | ||
) | [inline, static] |
Populates the specified matrix from the specified quaternion.
static void CC3Matrix4x3PopulateFromRotationX | ( | CC3Matrix4x3 * | mtx, |
const GLfloat | degrees | ||
) | [inline, static] |
Populates the specified matrix as a rotation around the X-axis, in degrees.
static void CC3Matrix4x3PopulateFromRotationY | ( | CC3Matrix4x3 * | mtx, |
const GLfloat | degrees | ||
) | [inline, static] |
Populates the specified matrix as a rotation around the Y-axis, in degrees.
static void CC3Matrix4x3PopulateFromRotationYXZ | ( | CC3Matrix4x3 * | mtx, |
CC3Vector | aRotation | ||
) | [inline, static] |
Populates the specified matrix as a rotation around three axes, y (yaw), x (pitch) and z (roll), in that order, from the specified Euler angle rotation.
Each Euler angle is specified in degrees.
This rotation places 'up' along the positive Y axis, which is the OpenGL ES default.
static void CC3Matrix4x3PopulateFromRotationZ | ( | CC3Matrix4x3 * | mtx, |
const GLfloat | degrees | ||
) | [inline, static] |
Populates the specified matrix as a rotation around the Z-axis, in degrees.
static void CC3Matrix4x3PopulateFromRotationZYX | ( | CC3Matrix4x3 * | mtx, |
CC3Vector | aRotation | ||
) | [inline, static] |
Populates the specified matrix as a rotation around three axes, z (roll), y (yaw), and x (pitch), in that order, from the specified Euler angle rotation.
Each Euler angle is specified in degrees.
This rotation places 'up' along the positive Z axis, which is used by some commercial 3D editors.
static void CC3Matrix4x3PopulateFromScale | ( | CC3Matrix4x3 * | mtx, |
const CC3Vector | aScale | ||
) | [inline, static] |
Populates the specified matrix from the specified scale.
static void CC3Matrix4x3PopulateFromTranslation | ( | CC3Matrix4x3 * | mtx, |
const CC3Vector | aTranslation | ||
) | [inline, static] |
Populates the specified matrix from the specified translation.
static void CC3Matrix4x3PopulateIdentity | ( | CC3Matrix4x3 * | mtx ) | [inline, static] |
Populates the specified matrix as an identity matrix (ones on the diagonal, zeros elsewhere).
static void CC3Matrix4x3PopulateInfiniteOrthoFrustum | ( | CC3Matrix4x3 * | mtx, |
const GLfloat | left, | ||
const GLfloat | right, | ||
const GLfloat | top, | ||
const GLfloat | bottom, | ||
const GLfloat | near | ||
) | [inline, static] |
Populates the specified matrix as an infinite-depth orthographic projection matrix with the specified frustum dimensions, where the far clipping plane is set at an infinite distance.
static void CC3Matrix4x3PopulateOrthoFrustum | ( | CC3Matrix4x3 * | mtx, |
const GLfloat | left, | ||
const GLfloat | right, | ||
const GLfloat | top, | ||
const GLfloat | bottom, | ||
const GLfloat | near, | ||
const GLfloat | far | ||
) | [inline, static] |
Populates the specified matrix as a orthographic projection matrix with the specified frustum dimensions.
static void CC3Matrix4x3PopulateToPointTowards | ( | CC3Matrix4x3 * | mtx, |
const CC3Vector | fwdDirection, | ||
const CC3Vector | upDirection | ||
) | [inline, static] |
Populates the specified matrix so that it will transform a vector pointed down the negative Z-axis to point in the specified forwardDirection, and transform the positive Y-axis to point in the specified upDirection.
static void CC3Matrix4x3PopulateZero | ( | CC3Matrix4x3 * | mtx ) | [inline, static] |
Populates the specified matrix so that all elements are zero.
static void CC3Matrix4x3RotateByQuaternion | ( | CC3Matrix4x3 * | mtx, |
CC3Quaternion | aQuaternion | ||
) | [inline, static] |
Rotates the specified matrix by the rotation specified in the given quaternion.
Since this operation rotates a matrix that potentially already contains rotations, the new rotation is performed first, followed by the rotation already contained within the specified matrix elements. If the matrix rotations were performed first, the new rotation would be performed in the rotated coordinate system defined by the matrix.
In mathematical terms, the incoming rotation is converted to matrix form, and is left-multiplied to the specified matrix elements.
static void CC3Matrix4x3RotateYXZBy | ( | CC3Matrix4x3 * | mtx, |
CC3Vector | aRotation | ||
) | [inline, static] |
Rotates the specified matrix by the specified Euler angles in degrees.
Rotation is performed in YXZ order, which is the OpenGL default.
Since this operation rotates a matrix that potentially already contains rotations, the new rotation is performed first, followed by the rotation already contained within the specified matrix elements. If the matrix rotations were performed first, the new rotation would be performed in the rotated coordinate system defined by the matrix.
In mathematical terms, the incoming rotation is converted to matrix form, and is left-multiplied to the specified matrix elements.
static void CC3Matrix4x3RotateZYXBy | ( | CC3Matrix4x3 * | mtx, |
CC3Vector | aRotation | ||
) | [inline, static] |
Rotates the specified matrix by the specified Euler angles in degrees.
Rotation is performed in ZYX order, which is used by some commercial 3D editors
Since this operation rotates a matrix that potentially already contains rotations, the new rotation is performed first, followed by the rotation already contained within the specified matrix elements. If the matrix rotations were performed first, the new rotation would be performed in the rotated coordinate system defined by the matrix.
In mathematical terms, the incoming rotation is converted to matrix form, and is left-multiplied to the specified matrix elements.
static void CC3Matrix4x3ScaleBy | ( | CC3Matrix4x3 * | mtx, |
CC3Vector | aScale | ||
) | [inline, static] |
Scales the specified matrix in three dimensions by the specified scaling vector.
Non-uniform scaling can be achieved by specifying different values for each element of the scaling vector.
static CC3Vector4 CC3Matrix4x3TransformCC3Vector4 | ( | const CC3Matrix4x3 * | mtx, |
CC3Vector4 | v | ||
) | [inline, static] |
Transforms the specified 4D vector using the specified matrix, and returns the transformed vector.
The specified matrix and the original specified vector remain unchanged.
static void CC3Matrix4x3TranslateBy | ( | CC3Matrix4x3 * | mtx, |
CC3Vector | aTranslation | ||
) | [inline, static] |
Translates the specified matrix in three dimensions by the specified translation vector.
static void CC3Matrix4x3Transpose | ( | CC3Matrix4x3 * | mtx ) | [inline, static] |
Transposes the specified matrix.
The contents of the matrix are changed.
Since a 4x3 matrix is not square, transposing an affine matrix will result in the contents of the fourth column being lost. After the transposition, the contents of both the forth column and the (implied) fourth row will contain (0,0,0,1).
If this is not the desired result, use the contents of this matrix to populate a CC3Matrix4x4 structure, and take the transpose of that matrix.
static CC3Vector4 CC3Vector4FromCC3Matrix4x3Col | ( | const CC3Matrix4x3 * | mtx, |
NSUInteger | colIdx | ||
) | [inline, static] |
Returns the column at the specified index from the specified matrix, as a 4D vector suitable for use in use with a 4x4 matrix.
The W component of the returned vector will be zero for the first three columns, and one for the fourth column.
In keeping with matrix math terminology, the index is one-based. The first column of the matrix has an index of one.
static CC3Vector4 CC3Vector4FromCC3Matrix4x3Row | ( | const CC3Matrix4x3 * | mtx, |
NSUInteger | rowIdx | ||
) | [inline, static] |
Returns the row at the specified index from the specified matrix, as a 4D vector suitable for use in use with a 4x4 matrix.
In keeping with matrix math terminology, the index is one-based. The first column of the matrix has an index of one.
static CC3Vector CC3VectorFromCC3Matrix4x3Col | ( | const CC3Matrix4x3 * | mtx, |
NSUInteger | colIdx | ||
) | [inline, static] |
Returns the column at the specified index from the specified matrix, as a 3D vector suitable for use in use with a 3x3 matrix.
In keeping with matrix math terminology, the index is one-based. The first column of the matrix has an index of one.
static CC3Vector CC3VectorFromCC3Matrix4x3Row | ( | const CC3Matrix4x3 * | mtx, |
NSUInteger | rowIdx | ||
) | [inline, static] |
Returns the row at the specified index from the specified matrix, as a 3D vector suitable for use in use with a 3x3 matrix.
The returned vector contains the first 3 elements of the row.
In keeping with matrix math terminology, the index is one-based. The first column of the matrix has an index of one.
static NSString* NSStringFromCC3Matrix4x3 | ( | CC3Matrix4x3 * | mtxPtr ) | [inline, static] |
Returns a string description of the specified CC3Matrix4x3, including contents.