Wt::WMatrix4x4 Class Reference

A value class that describes a 3D affine transformation matrix. More...

#include <Wt/WMatrix4x4.h>

Inheritance diagram for Wt::WMatrix4x4:

Public Member Functions
	WMatrix4x4 ()
	Default constructor. More...
	WMatrix4x4 (const WMatrix4x4 &other)
	Copy constructor.
WMatrix4x4 &	operator= (const WMatrix4x4 &other)
	Copy assignment operator.
	WMatrix4x4 (const WGenericMatrix< double, 4, 4 > &other)
	Construct for a WGenericMatrix. More...
	WMatrix4x4 (double *d)
	Constructs a matrix from an array of elements. More...
	WMatrix4x4 (double m11, double m12, double m13, double m14, double m21, double m22, double m23, double m24, double m31, double m32, double m33, double m34, double m41, double m42, double m43, double m44)
	Construct a custom matrix by specifying the parameters. More...
	~WMatrix4x4 ()=default
	Destructor.
double	determinant () const
	Returns the determinant.
void	flipCoordinates ()
	Switch between left-hand and right-hand side coordinate systems. More...
void	frustum (double left, double right, double bottom, double top, double nearPlane, double farPlane)
	Construct a perspective projection matrix. More...
WMatrix4x4	inverted (bool *invertible=nullptr) const
	Returns the inversion of this matrix, if invertible. More...
void	lookAt (double eyeX, double eyeY, double eyeZ, double centerX, double centerY, double centerZ, double upX, double upY, double upZ)
	Apply a transformation to position a camera. More...
void	ortho (double left, double right, double bottom, double top, double nearPlane, double farPlane)
	Create an orhtographic projection matrix for use in OpenGL. More...
void	perspective (double angle, double aspect, double nearPlane, double farPlane)
	Construct a perspective projection matrix for use in OpenGL. More...
void	rotate (double angle, double x, double y, double z)
	Rotates the transformation around a random axis. More...
void	scale (double xFactor, double yFactor)
	Scales the transformation. More...
void	scale (double x, double y, double z)
	Scales the transformation. More...
void	scale (double factor)
	Scales the transformation. More...
void	translate (double x, double y)
	Translates the transformation. More...
void	translate (double x, double y, double z)
	Translates the transformation. More...
WMatrix4x4	operator* (const WGenericMatrix< double, 4, 4 > &r) const
	Multiply two matrices.
Public Member Functions inherited from Wt::WGenericMatrix< double, 4, 4 >
	WGenericMatrix ()
	Construct a identity matrix. More...
	WGenericMatrix (const WGenericMatrix< double, Rows, Cols > &other)
	Copy Constructor.
	WGenericMatrix (const double *elements)
	Constructs a matrix from an array of elements. More...
virtual	~WGenericMatrix ()=default
	Destructor.
const ArrayType &	constData () const
	Returns a const pointer to the internal data store. More...
void	copyDataTo (double *data)
	Export the matrix data. More...
ArrayType &	data ()
	Returns a reference to the internal data store. More...
const ArrayType &	data () const
	Returns a const reference to the internal data store. More...
void	fill (double value)
	Fills every element of the matrix with the given value.
bool	isIdentity () const
	Identity check. More...
void	setToIdentity ()
	Set this matrix to the identity matrix. More...
WGenericMatrix< double, Cols, Rows >	transposed () const
	Returns the transposed of the matrix.
bool	operator== (const WGenericMatrix< double, Rows, Cols > &rhs) const
	Equality operator. More...
bool	operator!= (const WGenericMatrix< double, Rows, Cols > &rhs) const
	Inequality operator. More...
const double &	operator() (int row, int column) const
	Returns the element at the given position.
double &	operator() (int row, int column)
	Returns the element at the given position.
const double &	at (int row, int column) const
	Returns the element at the given position.
double &	at (int row, int column)
	Returns the element at the given position.
WGenericMatrix< double, Rows, Cols > &	operator*= (const double &factor)
	Multiply every element of the matrix with the given factor.
WGenericMatrix< double, Rows, Cols > &	operator/= (const double &factor)
	Divide every element of the matrix by the given factor.
WGenericMatrix< double, Rows, Cols > &	operator+= (const WGenericMatrix< double, Rows, Cols > &rhs)
	Add the given matrix to this matrix.
WGenericMatrix< double, Rows, Cols > &	operator-= (const WGenericMatrix< double, Rows, Cols > &rhs)
	Substract the given matrix from this matrix.

Detailed Description

A value class that describes a 3D affine transformation matrix.

The matrix is a 4x4 matrix encoded using 16 parameters. The matrix stores its data internally in row order.

Normally, a transformation matrix (composed translation/rotation/scale, but without perspective) is of this form:

m00 m01 m02 dx
m10 m11 m12 dy
m20 m21 m22 dz
0   0   0   1

In this representation, dx, dy and dz (= m(0, 3), m(1, 3) and m(2, 3)) represent the translation components, and m(x, y) represent a 3D matrix that contains the scale, rotation (and skew) components. The matrix is also capable of representing perspective projections. In that case, the matrix will not match the form depicted above.

In order to calculate the transformed vector w of a 3D vector v by the transformation contained in matrix T, v will be left-multiplied by T:

w = T * v;

In the formula above, v and w are homogenous 3D column vectors (x, y, z, w), equal to (x/w, y/w, z/w, 1). In normal use cases w is 1, except for vectors that were transformed by a perspective projection matrix.

The transformation is used to represent a tansformed coordinate system, and provides methods to rotate(), scale() or translate() this coordinate system.

This matrix class is matched to OpenGL's coordinate system and matrix notation. The rotate, translate, scale, lookAt, perspective, frustum and ortho methods of this class behave exactly like their OpenGL equivalents. The only difference is that the storage of this matrix is row-major, while OpenGL uses column-major. This should only be a concern if you need to access the raw data of the matrix, in which case you should use transposed().data() instead. When WWebGL uses this class, it sends the data in the correct order to the client.

Constructor & Destructor Documentation

WMatrix4x4() [1/4]

WMatrix4x4::WMatrix4x4

(

)

Default constructor.

Creates the identity transformation matrix.

WMatrix4x4() [2/4]

WMatrix4x4::WMatrix4x4

(

const WGenericMatrix< double, 4, 4 > &

other

)

Construct for a WGenericMatrix.

Creates the identity transformation matrix. As we inherit from WGenericMatrix, most overloaded operators create a WGenericMatrix. This implicit constructor ensures that you will not notice this.

WMatrix4x4() [3/4]

WMatrix4x4::WMatrix4x4 ( double *  d )

explicit

Constructs a matrix from an array of elements.

The input array is assumed to be in row-major order. If elements is 0, the matrix is not initialized.

WMatrix4x4() [4/4]

WMatrix4x4::WMatrix4x4	(	double	m11,
		double	m12,
		double	m13,
		double	m14,
		double	m21,
		double	m22,
		double	m23,
		double	m24,
		double	m31,
		double	m32,
		double	m33,
		double	m34,
		double	m41,
		double	m42,
		double	m43,
		double	m44
	)

Construct a custom matrix by specifying the parameters.

Creates a matrix from the specified parameters.

Member Function Documentation

flipCoordinates()

void WMatrix4x4::flipCoordinates

(

)

Switch between left-hand and right-hand side coordinate systems.

Equivalent to scale(1, -1, -1)

frustum()

void WMatrix4x4::frustum	(	double	left,
		double	right,
		double	bottom,
		double	top,
		double	nearPlane,
		double	farPlane
	)

Construct a perspective projection matrix.

This function constructs a perspective projection where the camera is located in the origin. The visible volume is determined by whatever that is visible when looking from the origin through the rectangular 'window' defined by the coordinates (l, b, n) and (r, t, n) (parallel to the XY plane). The zone is further delimited by the near and the far clipping planes.

The perspective matrix (P) is right-multiplied with the current transformation matrix (M): M * P. Usually, you will want M to be the identity matrix when using this method.

inverted()

WMatrix4x4 WMatrix4x4::inverted

(

bool *

invertible = nullptr

)

const

Returns the inversion of this matrix, if invertible.

If invertible is not 0, it will contain a bool that indicates if the operation succeeded and the inverse matrix is returned. Else, this method returns the unit matrix.

lookAt()

void WMatrix4x4::lookAt	(	double	eyeX,
		double	eyeY,
		double	eyeZ,
		double	centerX,
		double	centerY,
		double	centerZ,
		double	upX,
		double	upY,
		double	upZ
	)

Apply a transformation to position a camera.

(eyeX, eyeY, eyeZ) is the position of the camera.

The camera looks at (centerX, centerY, centerZ).

(upX, upY, upZ) is a vector that is the direction of the up vector.

This method applies a rotation and translation transformation to the current matrix so that the given eye becomes (0, 0, 0), the center point is on the negative Z axis, and the up vector lies in the X=0 plane, with its Y component in the positive Y axis direction.

The up vector must not be parallel to the line between eye and center. The vectors will be normalized and are not required to be perpendicular.

If the lookat transformation matrix is M, and the current value of the Matrix4x4 matrix is T, the resulting matrix after lookAt returns will be T * M.

This matrix is often used in conjunction with the perspective() method:

// First, apply the lookAt transformation
projectionMatrix.lookAt(1, 1, 1, 0, 0, 0, 0, 1, 0);
// Then apply some perspective
projectionMatrix.perspective(90, aspect, 0.1, 10);

ortho()

void WMatrix4x4::ortho	(	double	left,
		double	right,
		double	bottom,
		double	top,
		double	nearPlane,
		double	farPlane
	)

Create an orhtographic projection matrix for use in OpenGL.

Create an orthographic projection matrix. The given left, right, bottom, top, near and far points will be linearly mapped to the OpenGL unit cube ((1,1,1) to (-1,-1,-1)).

The orthographic matrix (O) is right-multiplied with the current transformation matrix (M): M * O. Usually, you will want M to be the identity matrix when using this method.

perspective()

void WMatrix4x4::perspective	(	double	angle,
		double	aspect,
		double	nearPlane,
		double	farPlane
	)

Construct a perspective projection matrix for use in OpenGL.

The camera is located in the origin and look in the direction of the negative Z axis.

Angle is the vertical view angle, in degrees. Aspect is the aspect ratio of the viewport, and near and far are the distances of the front and rear clipping plane from the camera.

The perspective matrix (P) is right-multiplied with the current transformation matrix (M): M * P. Usually, you will want M to be the identity matrix when using this method.

rotate()

void WMatrix4x4::rotate	(	double	angle,
		double	x,
		double	y,
		double	z
	)

Rotates the transformation around a random axis.

Applies a rotation to the current transformation matrix, over angle degrees. The current matrix (M) is right-multiplied by the rotation matrix: M = M * R

scale() [1/3]

void Wt::WMatrix4x4::scale

(

double

factor

)

Scales the transformation.

Equivalent to scale(factor, factor, factor);

See also

scale(double, double, double)

scale() [2/3]

void Wt::WMatrix4x4::scale	(	double	x,
		double	y,
		double	z
	)

Scales the transformation.

Equivalent to M * S where M is the current transformation and S is

x 0 0 0
0 y 0 0
0 0 z 0
0 0 0 1

scale() [3/3]

void Wt::WMatrix4x4::scale	(	double	xFactor,
		double	yFactor
	)

Scales the transformation.

Equivalent to scale(xFactor, yFactor, 1);

See also

scale(double, double, double)

translate() [1/2]

void Wt::WMatrix4x4::translate	(	double	x,
		double	y
	)

Translates the transformation.

Equivalent to translate(x, y, 0)

translate() [2/2]

void WMatrix4x4::translate	(	double	x,
		double	y,
		double	z
	)

Translates the transformation.

Translates the current transformation.

Equivalent to M * T where M is the current transformation matrix and T is:

1 0 0 x
0 1 0 y
0 0 1 z
0 0 0 1