#import "CC3Foundation.h"

Classes
union	CC3Matrix3x3

Macros
#define	kCC3Matrix3x3ColumnCount 3

#define	kCC3Matrix3x3ElementCount 9

#define	kCC3Matrix3x3RowCount 3

Functions
static GLfloat	CC3Det2x2 (GLfloat a1, GLfloat a2, GLfloat b1, GLfloat b2)

static CC3Vector	CC3Matrix3x3ExtractForwardDirection (const CC3Matrix3x3 *mtx)

CC3Quaternion	CC3Matrix3x3ExtractQuaternion (const CC3Matrix3x3 *mtx)

static CC3Vector	CC3Matrix3x3ExtractRightDirection (const CC3Matrix3x3 *mtx)

CC3Vector	CC3Matrix3x3ExtractRotationYXZ (const CC3Matrix3x3 *mtx)

CC3Vector	CC3Matrix3x3ExtractRotationZYX (const CC3Matrix3x3 *mtx)

static CC3Vector	CC3Matrix3x3ExtractUpDirection (const CC3Matrix3x3 *mtx)

BOOL	CC3Matrix3x3InvertAdjoint (CC3Matrix3x3 *mtx)

static BOOL	CC3Matrix3x3InvertAdjointTranspose (CC3Matrix3x3 *mtx)

static void	CC3Matrix3x3InvertRigid (CC3Matrix3x3 *mtx)

static void	CC3Matrix3x3InvertRigidTranspose (CC3Matrix3x3 *mtx)

static BOOL	CC3Matrix3x3IsIdentity (const CC3Matrix3x3 *mtx)

void	CC3Matrix3x3Multiply (CC3Matrix3x3 mOut, const CC3Matrix3x3 mL, const CC3Matrix3x3 *mR)

void	CC3Matrix3x3Orthonormalize (CC3Matrix3x3 *mtx, NSUInteger startColNum)

static void	CC3Matrix3x3PopulateFrom3x3 (CC3Matrix3x3 mtx, const CC3Matrix3x3 mtxSrc)

static void	CC3Matrix3x3PopulateFromGLKMatrix3 (CC3Matrix3x3 mtx, const GLKMatrix3 mtxSrc)

void	CC3Matrix3x3PopulateFromQuaternion (CC3Matrix3x3 *mtx, CC3Quaternion q)

void	CC3Matrix3x3PopulateFromRotationX (CC3Matrix3x3 *mtx, const GLfloat degrees)

void	CC3Matrix3x3PopulateFromRotationY (CC3Matrix3x3 *mtx, const GLfloat degrees)

void	CC3Matrix3x3PopulateFromRotationYXZ (CC3Matrix3x3 *mtx, CC3Vector aRotation)

void	CC3Matrix3x3PopulateFromRotationZ (CC3Matrix3x3 *mtx, const GLfloat degrees)

void	CC3Matrix3x3PopulateFromRotationZYX (CC3Matrix3x3 *mtx, CC3Vector aRotation)

void	CC3Matrix3x3PopulateFromScale (CC3Matrix3x3 *mtx, const CC3Vector aScale)

static void	CC3Matrix3x3PopulateIdentity (CC3Matrix3x3 *mtx)

void	CC3Matrix3x3PopulateToPointTowards (CC3Matrix3x3 *mtx, const CC3Vector fwdDirection, const CC3Vector upDirection)

static void	CC3Matrix3x3PopulateZero (CC3Matrix3x3 *mtx)

static void	CC3Matrix3x3RotateByQuaternion (CC3Matrix3x3 *mtx, CC3Quaternion aQuaternion)

static void	CC3Matrix3x3RotateYXZBy (CC3Matrix3x3 *mtx, CC3Vector aRotation)

static void	CC3Matrix3x3RotateZYXBy (CC3Matrix3x3 *mtx, CC3Vector aRotation)

static void	CC3Matrix3x3ScaleBy (CC3Matrix3x3 *mtx, CC3Vector aScale)

CC3Vector	CC3Matrix3x3TransformCC3Vector (const CC3Matrix3x3 *mtx, CC3Vector v)

void	CC3Matrix3x3Transpose (CC3Matrix3x3 *mtx)

static void	GLKMatrix3PopulateFromCC3Matrix3x3 (GLKMatrix3 mtx, const CC3Matrix3x3 mtxSrc)

NSString *	NSStringFromCC3Matrix3x3 (const CC3Matrix3x3 *mtxPtr)

Macro Definition Documentation

#define kCC3Matrix3x3ColumnCount 3

The number of columns in a CC3Matrix3x3 structure.

#define kCC3Matrix3x3ElementCount 9

The number of GLfloat elements in a CC3Matrix3x3 structure.

#define kCC3Matrix3x3RowCount 3

The number of rows in a CC3Matrix3x3 structure.

Function Documentation

static GLfloat CC3Det2x2	(	GLfloat	a1,
		GLfloat	a2,
		GLfloat	b1,
		GLfloat	b2
	)

inlinestatic

Returns the determinant of the specified 2x2 matrix values.

| a1 b1 | | a2 b2 |

static CC3Vector CC3Matrix3x3ExtractForwardDirection ( const CC3Matrix3x3 * mtx)

inlinestatic

Extracts and returns the 'forward' direction vector from the rotation component of the specified matrix.

CC3Quaternion CC3Matrix3x3ExtractQuaternion ( const CC3Matrix3x3 * mtx)

Extracts and returns a unit 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:

sum of diagonal elements = c1r1 + c2r2 + c3r3 = (4w^2 - 1).
Therefore w = sqrt(c1r1 + c2r2 + c3r3 + 1) / 2.
And c3r2 - c2r3 = 4wx, therefore x = (c3r2 - c2r3) / 4w
And c1r3 - c3r1 = 4wy, therefore y = (c2r3 - c3r1) / 4w
And c3r1 - c1r2 = 4wz, therefore z = (c2r1 - c1r2) / 4w

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 CC3Matrix3x3ExtractRightDirection ( const CC3Matrix3x3 * mtx)

inlinestatic

Extracts and returns the 'right' direction vector from the rotation component of the specified matrix.

CC3Vector CC3Matrix3x3ExtractRotationYXZ ( const CC3Matrix3x3 * mtx)

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.

CC3Vector CC3Matrix3x3ExtractRotationZYX ( const CC3Matrix3x3 * mtx)

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 CC3Matrix3x3ExtractUpDirection ( const CC3Matrix3x3 * mtx)

inlinestatic

Extracts and returns the 'up' direction vector from the rotation component of the specified matrix.

BOOL CC3Matrix3x3InvertAdjoint ( CC3Matrix3x3 * mtx)

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, the inverse of the matrix is equal to its transpose. In this case, use the CC3Matrix3x3InvertRigid function instead, which is some 10 to 100 times faster than this function.

static BOOL CC3Matrix3x3InvertAdjointTranspose ( CC3Matrix3x3 * mtx)

inlinestatic

Inverts the specified matrix by using the algorithm of calculating the classical adjoint and dividing by the determinant, and then transposes the result.

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, the inverse of the matrix is equal to its transpose. In this case, use the CC3Matrix3x3InvertRigid function instead, which is some 10 to 100 times faster than this function.

static void CC3Matrix3x3InvertRigid ( CC3Matrix3x3 * mtx)

inlinestatic

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. 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 CC3Matrix3x3InvertAdjoint function. It is recommended that this function be used whenever possible.

static void CC3Matrix3x3InvertRigidTranspose ( CC3Matrix3x3 * mtx)

inlinestatic

Inverts the specified matrix using transposition, and then transposes the result.

Since rigid inversion uses transposition, this operation amounts to two consecutive transpositions, which leaves the original matrix as the result. Because of this, this function actually does nothing to the specified matrix.

static BOOL CC3Matrix3x3IsIdentity ( const CC3Matrix3x3 * mtx)

inlinestatic

Returns whether the specified matrix is an identity matrix (ones on the diagonal, zeros elsewhere).

void CC3Matrix3x3Multiply	(	CC3Matrix3x3 *	mOut,
		const CC3Matrix3x3 *	mL,
		const CC3Matrix3x3 *	mR
	)

Multiplies mL on the left by mR on the right, and stores the result in mOut.

void CC3Matrix3x3Orthonormalize	(	CC3Matrix3x3 *	mtx,
		NSUInteger	startColNum
	)

Orthonormalizes 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 column 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 CC3Matrix3x3PopulateFrom3x3	(	CC3Matrix3x3 *	mtx,
		const CC3Matrix3x3 *	mtxSrc
	)

inlinestatic

Populates the specified matrix from the specified source matrix.

static void CC3Matrix3x3PopulateFromGLKMatrix3	(	CC3Matrix3x3 *	mtx,
		const GLKMatrix3 *	mtxSrc
	)

inlinestatic

Populates the specified matrix from the specified source GLKMatrix3.

Although CC3Matrix3x3 has the same internal structure as GLKMatrix3, the structures may have different byte alignment requirements. Avoid casting directly between GLKMatrix3 and CC3Matrix3x3, as this is not guaranteed to work reliably.

void CC3Matrix3x3PopulateFromQuaternion	(	CC3Matrix3x3 *	mtx,
		CC3Quaternion	q
	)

Populates the specified matrix from the specified quaternion.

void CC3Matrix3x3PopulateFromRotationX	(	CC3Matrix3x3 *	mtx,
		const GLfloat	degrees
	)

Populates the specified matrix as a rotation around the X-axis, in degrees.

void CC3Matrix3x3PopulateFromRotationY	(	CC3Matrix3x3 *	mtx,
		const GLfloat	degrees
	)

Populates the specified matrix as a rotation around the Y-axis, in degrees.

void CC3Matrix3x3PopulateFromRotationYXZ	(	CC3Matrix3x3 *	mtx,
		CC3Vector	aRotation
	)

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.

void CC3Matrix3x3PopulateFromRotationZ	(	CC3Matrix3x3 *	mtx,
		const GLfloat	degrees
	)

Populates the specified matrix as a rotation around the Z-axis, in degrees.

void CC3Matrix3x3PopulateFromRotationZYX	(	CC3Matrix3x3 *	mtx,
		CC3Vector	aRotation
	)

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.

void CC3Matrix3x3PopulateFromScale	(	CC3Matrix3x3 *	mtx,
		const CC3Vector	aScale
	)

Populates the specified matrix from the specified scale.

static void CC3Matrix3x3PopulateIdentity ( CC3Matrix3x3 * mtx)

inlinestatic

Populates the specified matrix as an identity matrix (ones on the diagonal, zeros elsewhere).

void CC3Matrix3x3PopulateToPointTowards	(	CC3Matrix3x3 *	mtx,
		const CC3Vector	fwdDirection,
		const CC3Vector	upDirection
	)

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 CC3Matrix3x3PopulateZero ( CC3Matrix3x3 * mtx)

inlinestatic

Populates the specified matrix so that all elements are zero.

static void CC3Matrix3x3RotateByQuaternion	(	CC3Matrix3x3 *	mtx,
		CC3Quaternion	aQuaternion
	)

inlinestatic

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 CC3Matrix3x3RotateYXZBy	(	CC3Matrix3x3 *	mtx,
		CC3Vector	aRotation
	)

inlinestatic

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 CC3Matrix3x3RotateZYXBy	(	CC3Matrix3x3 *	mtx,
		CC3Vector	aRotation
	)

inlinestatic

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 CC3Matrix3x3ScaleBy	(	CC3Matrix3x3 *	mtx,
		CC3Vector	aScale
	)

inlinestatic

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.

CC3Vector CC3Matrix3x3TransformCC3Vector	(	const CC3Matrix3x3 *	mtx,
		CC3Vector	v
	)

Transforms the specified 3D vector using the specified matrix, and returns the transformed vector.

The specified matrix and the original specified vector remain unchanged.

void CC3Matrix3x3Transpose ( CC3Matrix3x3 * mtx)

Transposes the specified matrix.

The contents of the matrix are changed.

static void GLKMatrix3PopulateFromCC3Matrix3x3	(	GLKMatrix3 *	mtx,
		const CC3Matrix3x3 *	mtxSrc
	)

inlinestatic

Populates the specified GLKMatrix3 from the specified source matrix.

Although GLKMatrix3 has the same internal structure as CC3Matrix3x3, the structures may have different byte alignment requirements. Avoid casting directly between CC3Matrix3x3 and GLKMatrix3, as this is not guaranteed to work reliably.

NSString* NSStringFromCC3Matrix3x3 ( const CC3Matrix3x3 * mtxPtr)

Returns a string description of the specified CC3Matrix3x3, including contents.

Classes

Macros

Functions

Macro Definition Documentation

Function Documentation