DD::Image::Matrix4 Class Reference

A 4x4 transformation matrix. More...

List of all members.

Public Types
enum	TransformOrder {   eSRT, eSTR, eRST, eRTS,   eTSR, eTRS }
enum	RotationOrder {   eXYZ, eXZY, eYXZ, eYZX,   eZXY, eZYX }
Public Member Functions
float *	operator[] (int i)
const float *	operator[] (int i) const
const float *	array () const
	Matrix4 (const float array[DD_IMAGE_MATRXI4_SIZE])
	Matrix4 (float a, float b, float c, float d, float e, float f, float g, float h, float i, float j, float k, float l, float m, float n, float o, float p)
void	set (float a, float b, float c, float d, float e, float f, float g, float h, float i, float j, float k, float l, float m, float n, float o, float p)
Matrix4	operator* (const Matrix4 &) const
Matrix4 &	operator*= (const Matrix4 &)
Matrix4	operator+ (const Matrix4 &) const
Matrix4 &	operator+= (const Matrix4 &)
Matrix4	operator- (const Matrix4 &) const
Matrix4 &	operator-= (const Matrix4 &)
Matrix4	operator* (float) const
Matrix4 &	operator*= (float)
Matrix4	operator/ (float d) const
Matrix4 &	operator/= (float d)
Vector4	operator* (const Vector4 &v) const
Vector4	transform (const Vector4 &v) const
Vector3	transform (const Vector3 &v) const
Vector2	transform (const Vector2 &v) const
Vector3	vtransform (const Vector3 &v) const
Vector3	ntransform (const Vector3 &v) const
Vector4	transform (const Vector3 &v, float w) const
bool	operator!= (const Matrix4 &b) const
bool	operator== (const Matrix4 &b) const
float	determinant (void) const
Matrix4	inverse (float det) const
Matrix4	inverse () const
bool	isIdentity () const
void	makeIdentity ()
void	scaling (float)
void	scaling (float, float, float)
void	scaling (const Vector3 &v)
void	translation (float, float, float=0.0f)
void	translation (const Vector3 &v)
void	rotationX (float)
void	rotationY (float)
void	rotationZ (float)
void	rotation (float a)
void	rotation (float a, float x, float y, float z)
void	rotation (float a, const Vector3 &v)
void	projection (float lens, float minz, float maxz, bool persp=true)
void	transpose ()
void	scale (float)
void	scale (float, float, float=1)
void	scale (const Vector3 &v)
void	translate (float, float, float=0.0f)
void	translate (const Vector3 &v)
void	rotateX (float)
void	rotateY (float)
void	rotateZ (float)
void	rotate (float a)
void	rotate (float a, float x, float y, float z)
void	rotate (float a, const Vector4 &v)
void	rotate (RotationOrder order, const Vector3 &rot)
void	skew (float a)
void	skewXY (float x, float y)
void	skewYX (float x, float y)
void	skewVec (const Vector3 &skew)
Vector3	x_axis () const
Vector3	y_axis () const
Vector3	z_axis () const
Vector3	translation () const
void	setXAxis (const Vector3 &axis)
void	setYAxis (const Vector3 &axis)
void	setZAxis (const Vector3 &axis)
Vector3	scale () const
void	scaleOnly ()
void	rotationOnly ()
void	translationOnly ()
void	scaleAndRotationOnly ()
void	rotationsXYZ (float &rx, float &ry, float &rz) const
void	rotationsXZY (float &rx, float &ry, float &rz) const
void	rotationsYXZ (float &rx, float &ry, float &rz) const
void	rotationsYZX (float &rx, float &ry, float &rz) const
void	rotationsZXY (float &rx, float &ry, float &rz) const
void	rotationsZYX (float &rx, float &ry, float &rz) const
void	getRotations (RotationOrder order, float &rx, float &ry, float &rz) const
bool	extractAndRemoveScalingAndShear (DD::Image::Vector3 &scaleOut, DD::Image::Vector3 &shearOut)
bool	decompose (DD::Image::Vector3 &rotationOut, DD::Image::Vector3 &translationOut, DD::Image::Vector3 &scaleOut, DD::Image::Vector3 &shearOut, const DD::Image::Matrix4::RotationOrder rOrder) const
void	mapUnitSquareToQuad (float x0, float y0, float x1, float y1, float x2, float y2, float x3, float y3)
	Corner pinning: map 0,0,1,1 square to the four corners (anticlockwise from bottom left)
void	mapQuadToUnitSquare (float x0, float y0, float x1, float y1, float x2, float y2, float x3, float y3)
void	append (Hash &) const
bool	isValid () const
void	set (TransformOrder tOrder, RotationOrder rOrder, const Vector3 &pivot, const Vector3 &translation, const Vector3 &rotation, const Vector3 &vScale, const Vector3 &vSkew)
Static Public Member Functions
static const Matrix4 &	identity ()
Public Attributes
float	a00
float	a10
float	a20
float	a30
float	a01
float	a11
float	a21
float	a31
float	a02
float	a12
float	a22
float	a32
float	a03
float	a13
float	a23
float	a33
Friends
std::ostream &	operator<< (std::ostream &o, const Matrix4 &matrix)

---

Detailed Description

A 4x4 transformation matrix.

Used to represent perspective transforms. Also because this is the only form OpenGL accepts, this is often used for affine transforms that could in fact be stored in a Matrix3.

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, these are all equal:

• matrix.a12
• matrix[2][1]
• matrix.array()[1+4*2]

---

Constructor & Destructor Documentation

DD::Image::Matrix4::Matrix4	(	float	a,
		float	b,
		float	c,
		float	d,
		float	e,
		float	f,
		float	g,
		float	h,
		float	i,
		float	j,
		float	k,
		float	l,
		float	m,
		float	n,
		float	o,
		float	p
	)		[inline]

Initialize with a00=a, a01=b, a02=c, etc, ie the arguments are given as rows.

---

Member Function Documentation

float * DD::Image::Matrix4::operator[]

(

int

i

)

[inline]

Return a pointer to the column number i.

const float * DD::Image::Matrix4::operator[]

(

int

i

)

const [inline]

Return a pointer to the column number i.

const float * DD::Image::Matrix4::array

(

)

const [inline]

Return a pointer to a00. This array is in the correct order to send it to OpenGL (column order).

Referenced by DD::Image::LightOp::draw_handle(), DD::Image::ComplexLightOp::draw_handle(), DD::Image::CameraOp::draw_handle(), DD::Image::ReadGeo::get_geometry_hash(), and DD::Image::Transform::set_texturemap().

Matrix4 Matrix4::operator*

(

const Matrix4 &

B

)

const

Does matrix multiplication.

Matrix4 & Matrix4::operator*=

(

const Matrix4 &

B

)

Does matrix multiplication.

Matrix4 Matrix4::operator+

(

const Matrix4 &

B

)

const

Add each matching locations.

Matrix4 & Matrix4::operator+=

(

const Matrix4 &

B

)

Add each matching locations.

Matrix4 Matrix4::operator-

(

const Matrix4 &

B

)

const

Subtract each matching locations.

Matrix4 & Matrix4::operator-=

(

const Matrix4 &

B

)

Subtract each matching locations.

Matrix4 Matrix4::operator*

(

float

f

)

const

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

Matrix4 & Matrix4::operator*=

(

float

f

)

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

Vector4 DD::Image::Matrix4::transform

(

const Vector4 &

v

)

const [inline]

Same as this*v.

Referenced by DD::Image::rPoint::add_to_render(), DD::Image::CameraOp::draw_handle(), DD::Image::Primitive::draw_normal(), DD::Image::ComplexLightOp::shade_GL(), DD::Image::GeoOp::transform_points(), and DD::Image::Iop::vertex_shader().

Vector3 DD::Image::Matrix4::transform

(

const Vector3 &

v

)

const [inline]

Same as the xyz of transform(v,1). This will transform a point in space but only if this is not a perspective matrix, meaning the last row is 0,0,0,1.

Vector2 DD::Image::Matrix4::transform

(

const Vector2 &

v

)

const [inline]

Will transform a Vector2 assuming z = 0.0

Vector3 DD::Image::Matrix4::vtransform

(

const Vector3 &

v

)

const [inline]

Same as the xyz of transform(v,0). This will transform a vector in space but only if this is not a perspective matrix, meaning the last row is 0,0,0,1.

Referenced by DD::Image::Box3::transform().

Vector3 DD::Image::Matrix4::ntransform

(

const Vector3 &

v

)

const [inline]

Same as transpose().transform(v,0). If this is the inverse of a transform matrix, this will transform normals.

Referenced by DD::Image::Primitive::draw_normal(), and DD::Image::GeoOp::evaluate_transform().

Vector4 DD::Image::Matrix4::transform	(	const Vector3 &	v,
		float	w
	)		const [inline]

Same as this*Vector4(v.x,v.y,v.z,w). Useful for doing transforms when w is stored in a different location than the xyz.

bool DD::Image::Matrix4::operator!=

(

const Matrix4 &

b

)

const [inline]

Returns true if any of all 16 locations are different.

bool DD::Image::Matrix4::operator==

(

const Matrix4 &

b

)

const [inline]

Returns true if all 16 locations are equal.

float DD::Image::Matrix4::determinant

(

void

)

const [inline]

Return the determinant. Non-zero means the transformation can be inverted.

Referenced by DD::Image::AxisOp::imatrix().

Matrix4 Matrix4::inverse

(

float

det

)

const

Returns the inverse of this matrix where det is the precomputed determinant. This is useful if you already computed the determinant in order to see if you can invert the matrix.

Referenced by DD::Image::CameraOp::draw_handle(), DD::Image::GeoOp::evaluate_transform(), and DD::Image::AxisOp::imatrix().

Matrix4 DD::Image::Matrix4::inverse

(

)

const [inline]

Returns the inverse of this matrix. If determinant() is zero this will replace all the items with +/- infinity or zero.

References inverse().

Referenced by inverse().

void DD::Image::Matrix4::makeIdentity

(

)

[inline]

Replace the contents with the identity.

Referenced by DD::Image::GeoOp::add_draw_geometry(), DD::Image::Render::camera_matrix(), DD::Image::GeoOp::evaluate_transform(), DD::Image::Render::get_format_matrix(), DD::Image::AxisOp::imatrix(), DD::Image::SourceGeo::init_geoinfo_parms(), mapUnitSquareToQuad(), and DD::Image::Transform::Transform().

void Matrix4::scaling

(

float

x

)

Replace the contents with a uniform scale by x.

Referenced by DD::Image::Render::projection_matrix(), and scaleOnly().

void Matrix4::scaling	(	float	x,
		float	y,
		float	z
	)

Replace the contents with a scale by x,y,z.

void DD::Image::Matrix4::scaling

(

const Vector3 &

v

)

[inline]

Replace the contents with a scale by the x,y,z of the vector

References scaling().

Referenced by scaling().

void Matrix4::translation	(	float	x,
		float	y,
		float	z = 0.0f
	)

Replace the contents with a translation by x,y,z.

Matrix4 & DD::Image::Matrix4::translation

(

const Vector3 &

v

)

[inline]

Replace the contents with a translation by the x,y,z of the vector

Translate the transformation by the x,y,z of the vector.

References translation().

Referenced by translation().

void Matrix4::rotationX

(

float

angle

)

Replace the contents with a rotation by angle (in radians) around the X axis.

Referenced by rotateX().

void Matrix4::rotationY

(

float

angle

)

Replace the contents with a rotation by angle (in radians) around the Y axis.

Referenced by rotateY().

void Matrix4::rotationZ

(

float

angle

)

Replace the contents with a rotation by angle (in radians) around the Z axis.

Referenced by rotateZ().

Matrix4 & DD::Image::Matrix4::rotation

(

float

angle

)

[inline]

Same as rotationZ(angle).

Referenced by rotate().

void Matrix4::rotation	(	float	a,
		float	x,
		float	y,
		float	z
	)

Replace the contents with a rotation by angle (in radians) around the vector x,y,z.

void DD::Image::Matrix4::rotation	(	float	angle,
		const Vector3 &	v
	)		[inline]

Replace the contents with a rotation by angle (in radians) around the vector.

References rotation().

Referenced by rotation().

void Matrix4::projection	(	float	lens,
		float	minz,
		float	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.

Referenced by DD::Image::CameraOp::projection(), and DD::Image::Render::projection_matrix().

void Matrix4::transpose

(

)

Replace the contents with the transposition (reflect through diagonal)

Referenced by DD::Image::Quaternion::matrix().

void Matrix4::scale

(

float

s

)

Scale the transformation by s.

Referenced by DD::Image::GeoOp::build_matrix_handles(), DD::Image::CameraOp::from_format(), DD::Image::ProxyContext::from_proxy(), DD::Image::Render::get_format_matrix(), DD::Image::CameraOp::projection(), DD::Image::CameraOp::to_format(), and DD::Image::ProxyContext::to_proxy().

void Matrix4::scale	(	float	x,
		float	y,
		float	z = 1
	)

Scale the transformation by x,y,z.

void DD::Image::Matrix4::scale

(

const Vector3 &

v

)

[inline]

Scale the transformation by the x,y,z of the vector

References scale().

Referenced by scale().

void Matrix4::translate	(	float	x,
		float	y,
		float	z = 0.0f
	)

Translate the transformation by x,y,z.

Referenced by DD::Image::Render::camera_matrix(), DD::Image::CameraOp::from_format(), DD::Image::ProxyContext::from_proxy(), DD::Image::Render::get_format_matrix(), DD::Image::CameraOp::projection(), DD::Image::CameraOp::to_format(), and DD::Image::ProxyContext::to_proxy().

void Matrix4::rotateX

(

float

a

)

Rotate the transformation by a radians about the X axis.

References rotationX().

void Matrix4::rotateY

(

float

a

)

Rotate the transformation by a radians about the Y axis.

References rotationY().

void Matrix4::rotateZ

(

float

a

)

Rotate the transformation by a radians about the Z axis.

References rotationZ().

Referenced by DD::Image::CameraOp::projection().

void DD::Image::Matrix4::rotate

(

float

a

)

[inline]

Same as rotateZ(a).

void Matrix4::rotate	(	float	a,
		float	x,
		float	y,
		float	z
	)

Rotate the transformation by a radians about the vector x,y,z.

References rotation().

void DD::Image::Matrix4::rotate	(	float	a,
		const Vector4 &	v
	)		[inline]

Rotate the transformation by a radians about the vector.

References rotate().

Referenced by rotate().

void Matrix4::skew

(

float

a

)

Skew the transformation by a (X positions have a*Y added to them).

Vector3 DD::Image::Matrix4::x_axis

(

)

const [inline]

Return the transformation of a 1 unit vector in x, if this is not a persxpective matrix (ie bottom row must be 0,0,0,1).

Vector3 DD::Image::Matrix4::y_axis

(

)

const [inline]

Return the transformation of a 1 unit vector in y, if this is not a persxpective matrix (ie bottom row must be 0,0,0,1).

Vector3 DD::Image::Matrix4::z_axis

(

)

const [inline]

Return the transformation of a 1 unit vector in z, if this is not a persxpective matrix (ie bottom row must be 0,0,0,1).

Referenced by DD::Image::MBParticleSpriteGenerator::getSprite(), DD::Image::SpriteGenerator::getSprite(), and DD::Image::ParticlesSprite::tessellateSprite().

Vector3 DD::Image::Matrix4::translation

(

)

const [inline]

Return the transformation of the point 0,0,0, if this is not a perspective matrix (ie bottom row is 0,0,0,1).

Vector3 Matrix4::scale

(

)

const

Return the scale of a transformation matrix.

Referenced by rotationOnly(), and scaleOnly().

void Matrix4::scaleOnly

(

)

Modify the transformation matrix to represent the scale component only.

References scale(), and scaling().

void Matrix4::rotationOnly

(

)

Modify the transformation matrix to represent the rotation component only.

References scale(), and scaleAndRotationOnly().

void Matrix4::translationOnly

(

)

Modify the transformation matrix to represent the translation component only.

void Matrix4::scaleAndRotationOnly

(

)

Modify the transformation matrix to represent the scale and rotation component only.

Referenced by rotationOnly().

void Matrix4::rotationsXYZ	(	float &	rx,
		float &	ry,
		float &	rz
	)		const

Given a matrix which is assumed to be the multiplication of any number of rotation matricies (no translations, please) calculate the equivalent rotations around the X, Y and Z axis. You can then recreate this transformation by doing rotatez(x), rotatex(y), rotatey(z).

Referenced by getRotations().

void Matrix4::rotationsXZY	(	float &	rx,
		float &	ry,
		float &	rz
	)		const

Given a matrix which is assumed to be the multiplication of any number of rotation matricies (no translations, please) calculate the equivalent rotations around the X, Y and Z axis. You can then recreate this transformation by doing rotatez(x), rotatex(z), rotatey(y).

Referenced by getRotations().

void Matrix4::rotationsYXZ	(	float &	rx,
		float &	ry,
		float &	rz
	)		const

Given a matrix which is assumed to be the multiplication of any number of rotation matricies (no translations, please) calculate the equivalent rotations around the X, Y and Z axis. You can then recreate this transformation by doing rotatez(y), rotatex(x), rotatey(z).

Referenced by getRotations().

void Matrix4::rotationsYZX	(	float &	rx,
		float &	ry,
		float &	rz
	)		const

Given a matrix which is assumed to be the multiplication of any number of rotation matricies (no translations, please) calculate the equivalent rotations around the X, Y and Z axis. You can then recreate this transformation by doing rotatez(y), rotatex(z), rotatey(x).

Referenced by getRotations().

void Matrix4::rotationsZXY	(	float &	rx,
		float &	ry,
		float &	rz
	)		const

Given a matrix which is assumed to be the multiplication of any number of rotation matricies (no translations, please) calculate the equivalent rotations around the X, Y and Z axis. You can then recreate this transformation by doing rotatez(z), rotatex(x), rotatey(y).

Referenced by getRotations().

void Matrix4::rotationsZYX	(	float &	rx,
		float &	ry,
		float &	rz
	)		const

Given a matrix which is assumed to be the multiplication of any number of rotation matricies (no translations, please) calculate the equivalent rotations around the X, Y and Z axis. You can then recreate this transformation by doing rotatez(z), rotatex(y), rotatey(x).

Referenced by getRotations().

void Matrix4::getRotations	(	RotationOrder	order,
		float &	rx,
		float &	ry,
		float &	rz
	)		const

Given a matrix which is assumed to be the multiplication of any number of rotation matricies (no translations, please) calculate the equivalent rotations around the X, Y and Z axis. You can then recreate this transformation by concatenating individual rotations in the order specified by the RotationOrder parameter

References rotationsXYZ(), rotationsXZY(), rotationsYXZ(), rotationsYZX(), rotationsZXY(), and rotationsZYX().

Referenced by decompose().

bool Matrix4::extractAndRemoveScalingAndShear	(	DD::Image::Vector3 &	scaleOut,
		DD::Image::Vector3 &	shearOut
	)

Get and remove scale and rotation from the matrix.

References DD::Image::Vector3::dot(), and DD::Image::Vector3::length().

Referenced by decompose().

bool Matrix4::decompose	(	DD::Image::Vector3 &	rotationOut,
		DD::Image::Vector3 &	translationOut,
		DD::Image::Vector3 &	scaleOut,
		DD::Image::Vector3 &	shearOut,
		const DD::Image::Matrix4::RotationOrder	rOrder
	)		const

Decompose the matrix into its individual transform components. Returned rotation values are based on the rotation order provided.

References extractAndRemoveScalingAndShear(), and getRotations().

void Matrix4::mapUnitSquareToQuad	(	float	x0,
		float	y0,
		float	x1,
		float	y1,
		float	x2,
		float	y2,
		float	x3,
		float	y3
	)

Corner pinning: map 0,0,1,1 square to the four corners (anticlockwise from bottom left)

map 0,0,1,1 square to the four corners (anticlockwise from bottom left)

References makeIdentity().

Referenced by mapQuadToUnitSquare().

void Matrix4::mapQuadToUnitSquare	(	float	x0,
		float	y0,
		float	x1,
		float	y1,
		float	x2,
		float	y2,
		float	x3,
		float	y3
	)

Corner pinning: map the four corners (anticlockwise from bottom left) to 0,0,1,1 square

References mapUnitSquareToQuad().

void Matrix4::append

(

Hash &

hash

)

const

Add this to the Hash object.

Referenced by DD::Image::Transform::append(), and DD::Image::TransformGeo::get_geometry_hash().

bool DD::Image::Matrix4::isValid

(

)

const [inline]

Return whether all of the components are valid numbers.

---

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	o,
		const Matrix4 &	matrix
	)		[friend]

Writes it in nuke/tcl notation, with nested curly braces