fdk::Mat4< T > Class Template Reference

A 4x4 transformation matrix. You multiply a Vec4 by one of these to go from a transformed space to normal space. More...

#include <Mat4.h>

Public Member Functions
	Mat4 ()=default
	Default constructor leaves garbage in contents.
template<typename S >
	Mat4 (const Mat4< S > &b, bool transpose=false)
template<typename S >
	Mat4 (const S *src, bool transpose=false)
	Mat4 (T d)
	Initialize to identity matrix with a constant in the diagonal.
	Mat4 (T a, T b, T c, T d, T e, T f, T g, T h, T i, T j, T k, T l, T m, T n, T o, T p, bool transpose=false)
	Initialize with a00=a, a01=b, a02=c, etc. ie the arguments are given as rows.
	operator Mat4< float > () const
	Transmogrify as a specific type:
	operator Mat4< double > () const
Mat4< float >	asMat4f () const
Mat4< double >	asMat4d () const
T *	operator[] (int col)
	Return a pointer to the start of column 'c'.
const T *	operator[] (int col) const
T *	array ()
	Return a pointer to the first element a00.
const T *	array () const
T &	element (int i)
	Return the value of matrix element a00 + 'i'.
const T &	element (int i) const
Vec4< T >	row0 () const
	Return row 0 as a Vec4.
Vec4< T >	row1 () const
	Return row 1 as a Vec4.
Vec4< T >	row2 () const
	Return row 2 as a Vec4.
Vec4< T >	row3 () const
	Return row 3 as a Vec4.
Vec4< T >	col0 () const
	Return column 0 as a Vec4.
Vec4< T >	col1 () const
	Return column 1 as a Vec4.
Vec4< T >	col2 () const
	Return column 2 as a Vec4.
Vec4< T >	col3 () const
	Return column 3 as a Vec4.
template<typename S >
void	setRow0 (const Vec3< S > &v)
	Assign row 0, 1, or 2 from a Vec3.
template<typename S >
void	setRow1 (const Vec3< S > &v)
template<typename S >
void	setRow2 (const Vec3< S > &v)
template<typename S >
void	xAxis (Vec3< S > &v) const
	Return col 0, 1 or 2 as a Vec3.
Vec3< T >	xAxis () const
template<typename S >
void	yAxis (Vec3< S > &v) const
Vec3< T >	yAxis () const
template<typename S >
void	zAxis (Vec3< S > &v) const
Vec3< T >	zAxis () const
template<typename S >
void	setXAxis (const Vec3< S > &v)
	Assign col 0, 1, or 2 from a Vec3.
template<typename S >
void	setYAxis (const Vec3< S > &v)
template<typename S >
void	setZAxis (const Vec3< S > &v)
template<typename S >
void	setXYZAxis (const Vec3< S > &x, const Vec3< S > &y, const Vec3< S > &z)
template<typename S >
void	getTranslation (Vec3< S > &v) const
	Return the translations or scale of the matrix as a Vec3.
Vec3< T >	getTranslation () const
template<typename S >
void	getScaleAxis (Vec3< S > &v) const
Vec3< T >	getScaleAxis () const
Vec3< T >	getRotations (fdk::RotateOrder order) const
void	getRotations (fdk::RotateOrder order, T &radian_rX, T &radian_rY, T &radian_rZ) const
Vec3< T >	getScale () const
	Return the scaling of the matrix.
bool	isValid () const
	Return whether all of the components are valid numbers.
template<typename S >
void	setToArray (const S *src, bool transpose=false)
template<typename S >
void	setTo (S a, S b, S c, S d, S e, S f, S g, S h, S i, S j, S k, S l, S m, S n, S o, S p, bool transpose=false)
	Set each component in memory order, unless transposed.
void	setToZero ()
	Set all components to 0 or 1.
void	setToOne ()
void	clear ()
	Type-specific clear. Sets all components to 0.
void	append (fdk::Hash &hash) const
	Add this to a fdk::Hash object.
Mat4	operator* (const Mat4 &b) const
Mat4 &	operator*= (const Mat4 &b)
Mat4	operator* (T d) const
Mat4 &	operator*= (T d)
Mat4	operator/ (T d) const
Mat4 &	operator/= (T d)
Mat4	operator+ (const Mat4 &b) const
	Add each matching location.
Mat4 &	operator+= (const Mat4 &b)
Mat4	operator- (const Mat4 &b) const
	Subtract each matching location.
Mat4 &	operator-= (const Mat4 &b)
bool	operator== (const Mat4 &b) const
	Returns true if all 16 locations are equal. Compares on each element individually.
bool	operator!= (const Mat4 &b) const
	Returns true if any of the 16 locations are different. Compares on each element individually.
template<typename S , typename R >
Vec3< R > &	transform (const Vec3< S > &in, Vec3< R > &out) const
template<typename S >
Vec3< S >	operator* (const Vec3< S > &v) const
template<typename S >
Vec3< S >	transform (const Vec3< S > &v) const
template<typename S >
void	transform (Vec3< S > *dstPoints, const Vec3< S > *srcPoints, size_t nPoints) const
template<typename S , typename R >
Vec4< R > &	transform (const Vec4< S > &in, Vec4< R > &out) const
template<typename S >
Vec4< S >	operator* (const Vec4< S > &v) const
template<typename S >
Vec4< S >	transform (const Vec4< S > &v) const
template<typename S , typename R >
Vec4< S >	transform (const Vec3< S > &v, R w) const
template<typename S >
Vec2< S >	transform (const Vec2< S > &v) const
	Transform a Vec2 assuming z = 0.0.
template<typename S >
Vec2< S >	vecTransform (const Vec2< S > &v) const
	Transform a Vec2 with no translation applied, assuming z = 0.0.
template<typename S >
Vec3< S >	vecTransform (const Vec3< S > &v) const
	Transform a vector with no translation applied.
template<typename S >
void	vecTransform (Vec3< S > *dstVecs, const Vec3< S > *srcVecs, size_t nVecs) const
template<typename S >
Vec3< S >	normalTransform (const Vec3< S > &n) const
	Transform a normal - same as transpose().transform(n).
template<typename S >
void	normalTransform (Vec3< S > *dstNormals, const Vec3< S > *srcNormalss, size_t nNormals) const
template<typename S , typename R >
Box3< R > &	transform (const Box3< S > &in, Box3< R > &out) const
template<typename S >
Box3< S >	operator* (const Box3< S > &bbox) const
template<typename S >
Box3< S >	transform (const Box3< S > &bbox) const
T	getDeterminant () const
	Return the determinant. Non-zero means the matrix can be inverted.
void	invert (Mat4 &out, T determinant) const
T	invert (Mat4 &out) const
Mat4 &	invert ()
	Invert this matrix in place.
Mat4	inverse () const
	Returns the inverse of this matrix. Returns garbage if this cannot be inverted.
Mat4	inverse (T determinant) const
	Returns the inverse of this matrix (must supply a precomputed non-zero determinant)
void	setToIdentity ()
	Set the matrix to the identity.
bool	isIdentity () const
	Returns true if matrix is an identity matrix.
bool	isNotIdentity () const
Mat4 &	setToScale (T d)
	Set the contents to a uniform scale by d.
Mat4 &	setToScale (T sx, T sy, T sz=static_cast< T >(1))
	Set the contents to a scale by x,y,z.
template<typename S >
Mat4 &	setToScale (const Vec3< S > &s)
Mat4 &	setToTranslation (T tx, T ty, T tz=static_cast< T >(0))
	Set the contents to a translation by x,y,z.
template<typename S >
Mat4 &	setToTranslation (const Vec3< S > &t)
Mat4 &	setToRotations (fdk::RotateOrder order, T radian_x_angle, T radian_y_angle, T radian_z_angle)
	Set the contents to xyz rotation angles (in radians).
template<typename S >
Mat4 &	setToRotations (fdk::RotateOrder order, const Vec3< S > &v)
Mat4 &	setToRotationX (T radian_angle)
	Set the contents to an angle (in radians) around the X axis.
Mat4 &	setToRotationY (T radian_angle)
	Set the contents to an angle (in radians) around the Y axis.
Mat4 &	setToRotationZ (T radian_angle)
	Set the contents to an angle (in radians) around the Z axis.
template<typename S >
Mat4 &	setToRotation (T radian_angle, const Vec3< S > &v)
	Set the contents to an angle (in radians) around about the vector x,y,z.
Mat4 &	setToRotation (T radian_angle, T x, T y, T z)
void	applyXform (fdk::XformOrder xformOrder, fdk::RotateOrder rotateOrder, const Vec3< T > &translation, const Vec3< T > &rotationsInDegrees, const Vec3< T > &scaling, const Vec3< T > &skewing, const Vec3< T > &pivotOriginTranslate, const Vec3< T > &pivotOriginRotateInDegrees)
void	setToXform (fdk::XformOrder xformOrder, fdk::RotateOrder rotateOrder, const Vec3< T > &translation, const Vec3< T > &rotationsInDegrees, const Vec3< T > &scaling, const Vec3< T > &skewing, const Vec3< T > &pivotOriginTranslate, const Vec3< T > &pivotOriginRotateInDegrees)
void	transpose ()
	Replace the contents with the transposition (reflect through diagonal)
void	scale (T d)
	Scale the transformation by uniform scale d.
void	scale (T sx, T sy, T sz=static_cast< T >(1))
	Scale columns 0,1,2 by x,y,z.
template<typename S >
void	scale (const Vec3< S > &sv)
void	rotateX (T radian_angle)
	Rotate the transformation by an angle (in radians) about the X axis.
void	rotateY (T radian_angle)
	Rotate the transformation by an angle (in radians) about the Y axis.
void	rotateZ (T radian_angle)
	Rotate the transformation by an angle (in radians) about the Z axis.
void	rotateInOrder (fdk::RotateOrder order, T radian_x_angle, T radian_y_angle, T radian_z_angle)
	Apply rotations in each axis (in radians) in specific order.
template<typename S >
void	rotateInOrder (fdk::RotateOrder order, const Vec3< S > &radian_angles)
template<typename S >
void	rotateAboutVector (T radian_angle, const Vec3< S > &v)
	Rotate the transformation by an angle (in radians) about the vector x,y,z.
void	rotateAboutVector (T radian_angle, T x, T y, T z)
void	translate (T x, T y, T z=static_cast< T >(0))
	Translate the transformation by an x,y,z offset.
template<typename S >
void	translate (const Vec3< S > &v)
void	skew (T d)
	Skew the transformation by a (X positions have a*Y added to them).
template<typename S >
void	skew (const Vec3< S > &skewv)
void	skewXY (T x, T y)
void	skewYX (T x, T y)
Mat4 &	add (const Mat4 &b)
	Component-wise add all the elements.
void	add (T t)
	Add a constant to all the elements.
void	addDiagonal (T t)
	Add a constant to all the diagonal elements.
template<typename S >
Mat4	lookAt (fdk::AxisDirection axis, const fdk::Vec3< S > &lookAtPos, T strength=T(1), bool rotateX=true, bool rotateY=true, bool rotateZ=true)
template<typename S >
void	interpolate (const Mat4< T > &m0, const Mat4< T > &m1, S t)
void	setToProjection (double lens, double minz, double maxz, bool persp=true)
void	setToTranslationOnly ()
	Modify the transformation matrix to represent the translation component only.
void	setToRotationOnly ()
	Modify the transformation matrix to represent the rotation component only.
void	setToScaleOnly ()
	Modify the transformation matrix to represent the scale component only.
void	setToScaleAndRotationOnly ()
	Modify the transformation matrix to represent the scale and rotation component only.
bool	extractScalingAndShear (Vec3< T > &scale, Vec3< T > &shear) const
	Adapted from ilmbase ImathMatrixAlgo.
bool	extractAndRemoveScalingAndShear (Vec3< T > &scale, Vec3< T > &shear)
	Adapted from ilmbase ImathMatrixAlgo.
bool	extractSHRT (Vec3< T > &scaling, Vec3< T > &shearing, Vec3< T > &rotationsInDegrees, Vec3< T > &translation, fdk::RotateOrder order=fdk::RotateOrder::ZXY) const
	Rotations are in degrees. Adapted from ilmbase ImathMatrixAlgo.
template<typename S >
Mat4< T > &	setToRotation (T radian_angle, const Vec3< S > &v)
template<typename S >
Mat4< T >	lookAt (fdk::AxisDirection axis, const fdk::Vec3< S > &lookAtPos, T strength, bool rotateX, bool rotateY, bool rotateZ)

Static Public Member Functions
static const Mat4 &	getIdentity ()
	Return the identity matrix object.
template<typename S , typename R >
static bool	vectorToRotations (const Vec3< S > &dir_vec, fdk::AxisDirection align_axis, bool do_rx, bool do_ry, bool do_rz, Vec3< R > &rotations, fdk::RotateOrder &rotation_order)

Public Attributes
T	a00
T	a10
T	a20
T	a30
T	a01
T	a11
T	a21
T	a31
T	a02
T	a12
T	a22
T	a32
T	a03
T	a13
T	a23
T	a33

Static Public Attributes
static constexpr uint8_t	kNumElements = 16

Detailed Description

template<typename T>
class fdk::Mat4< T >

A 4x4 transformation matrix. You multiply a Vec4 by one of these to go from a transformed space to normal space.

The data is stored packed together in OpenGL order, which is transposed from the way used in most modern graphics literature. This affects how the array() and [] operator work. You can directly access the entries with the aRC members, where R is the row and C is the column.

For instance matrix.a03 is the top-right corner of the matrix in most literature. It is multiplied by the W of a vector to produce part of the X of the output vector, and can be considered the X translation of the matrix.

However matrix.a03 is matrix[3][0], and is matrix.array()[12].

a00, a10, a20, a30, a01, a11, a21, a31, a02, a12, a22, a32, a03, a13, a23, a33

Constructor & Destructor Documentation

Mat4() [1/2]

template<typename T >

template<typename S >

fdk::Mat4< T >::Mat4 ( const Mat4< S > &  b, bool  transpose = false  )

inlineexplicit

Copy constructor supports conversion from another type with optional transpose-on-copy.

References fdk::Mat4< T >::array(), fdk::Mat4< T >::setToArray(), and fdk::Mat4< T >::transpose().

Mat4() [2/2]

template<typename T >

template<typename S >

fdk::Mat4< T >::Mat4 ( const S *  src, bool  transpose = false  )

inlineexplicit

Copy from array constructor supports conversion from another type with optional transpose-on-copy.

References fdk::Mat4< T >::setToArray(), and fdk::Mat4< T >::transpose().

Member Function Documentation

getRotations()

template<typename T >

Vec3< T > fdk::Mat4< T >::getRotations

(

fdk::RotateOrder

order

)

const

Extract the rotation angles (in radians) from the matrix. The matrix is assumed to have no shear, non-uniform scaling is handled.

setToArray()

template<typename T >

template<typename S >

void fdk::Mat4< T >::setToArray ( const S *  src, bool  transpose = false  )

inline

Set all components from a like-sized array with per-element type conversion and optional transpose-on-copy.

Referenced by fdk::Mat4< T >::Mat4().

operator*()

template<typename T >

Mat4 fdk::Mat4< T >::operator*

(

T

d

)

const

Multiplies every location by d. For transforms this is not a scale, because it scales the W parameter as well, producing no change.

transform()

template<typename T >

template<typename S , typename R >

Box3< R > & fdk::Mat4< T >::transform ( const Box3< S > &  in, Box3< R > &  out  ) const

inline

Faster implementation from Graphics Gems I, page 785 - "Transforming Axis-Aligned Bounding Boxes"

References fdk::Box3< T >::max, and fdk::Box3< T >::min.

invert() [1/2]

template<typename T >

void fdk::Mat4< T >::invert ( Mat4< T > &  out, T  determinant  ) const

inline

Replace the contents of out with the inverse of this, where det is the already-calculated determinant of this and must be non-zero. &out must be a different matrix than this!

invert() [2/2]

template<typename T >

T fdk::Mat4< T >::invert ( Mat4< T > &  out ) const

inline

Replace the contents of out with the inverse of this and return the determinant. If this cannot be inverted to is unchanged and zero is returned. &out must be a different matrix than this!

vectorToRotations()

template<typename T >

template<typename S , typename R >

bool fdk::Mat4< T >::vectorToRotations ( const Vec3< S > &  dir_vec, fdk::AxisDirection  align_axis, bool  do_rx, bool  do_ry, bool  do_rz, Vec3< R > &  rotations, fdk::RotateOrder &  rotation_order  )

inlinestatic

Calculate the x,y & z rotation angles, in radians, to align the align_axis direction with dir_vector, and the suggested rotation order to apply them in to best avoid gimbal lock. Return true if rotations have been affected.

References fdk::Vec3< T >::set(), and fdk::Vec3< T >::z.

lookAt()

template<typename T >

template<typename S >

Mat4 fdk::Mat4< T >::lookAt	(	fdk::AxisDirection	axis,
		const fdk::Vec3< S > &	lookAtPos,
		T	strength = T(1),
		bool	rotateX = true,
		bool	rotateY = true,
		bool	rotateZ = true
	)

Returns a matrix that is equivalent to this matrix rotated so that its axis is oriented towards lookAtPos. Can interpolate between the two matrices by setting strength to a value between 0 and 1, where 0 simply returns sourceMatrix and 1 returns lookAtMatrix. It can also prevent the rotation around any axis by setting rotateX, rotateY or rotateZ to false.

interpolate()

template<typename T >

template<typename S >

void fdk::Mat4< T >::interpolate ( const Mat4< T > &  m0, const Mat4< T > &  m1, S  t  )

inline

Linear interpolate two matrices at offset 't' which is between 0.0 and 1.0. This only interpolates position and rotation, and rotation is only valid within a certain range since it's a linear interpolation of the xyz axes!

setToProjection()

template<typename T >

void fdk::Mat4< T >::setToProjection	(	double	lens,
		double	minz,
		double	maxz,
		bool	persp = true
	)

Replace the contents with a camera projection. The camera is sitting at 0,0,0 and pointing along the Z axis, and the ratio of it's focal length to the width of the film is lens. The area that will appear on the film is transformed to be in a square with X and Y ranging from -1 to 1. The plane Z=minz is transformed to be at Z=-1 and the plane Z=maxz is transformed to Z=1.