libgdx API

com.badlogic.gdx.math
Class Matrix4

java.lang.Object
  extended by com.badlogic.gdx.math.Matrix4
All Implemented Interfaces:
java.io.Serializable

public class Matrix4
extends java.lang.Object
implements java.io.Serializable

Encapsulates a column major 4 by 4 matrix. You can access the linear array for use with OpenGL via the public val member. Like the Vector3 class it allows to chain methods by returning a reference to itself.

Author:
badlogicgames@gmail.com
See Also:
Serialized Form

Field Summary
static int M00
           
static int M01
           
static int M02
           
static int M03
           
static int M10
           
static int M11
           
static int M12
           
static int M13
           
static int M20
           
static int M21
           
static int M22
           
static int M23
           
static int M30
           
static int M31
           
static int M32
           
static int M33
           
 float[] tmp
           
 float[] val
           
 
Constructor Summary
Matrix4()
          Constructs an identity matrix
Matrix4(float[] values)
          Constructs a matrix from the given float array.
Matrix4(Matrix4 matrix)
          Constructs a matrix from the given matrix
Matrix4(Quaternion quaternion)
          Constructs a rotation matrix from the given Quaternion
 
Method Summary
 Matrix4 cpy()
           
 float det()
           
static float det(float[] values)
          Computes the determinante of the given matrix.
 void getRotation(Quaternion rotation)
           
 void getTranslation(Vector3 position)
           
 float[] getValues()
           
 Matrix4 idt()
          Sets the matrix to an identity matrix
 Matrix4 inv()
          Inverts the matrix.
static boolean inv(float[] values)
          Computes the inverse of the given matrix.
 void lerp(Matrix4 matrix, float alpha)
          Linearly interpolates between this matrix and the given matrix mixing by alpha
static void mul(float[] mata, float[] matb)
          Multiplies the matrix mata with matrix matb, storing the result in mata.
 Matrix4 mul(Matrix4 matrix)
          Multiplies this matrix with the given matrix, storing the result in this matrix.
static void mulVec(float[] mat, float[] vec)
          Multiplies the vector with the given matrix.
static void mulVec(float[] mat, float[] vecs, int offset, int numVecs, int stride)
          Multiplies the vectors with the given matrix.
static void prj(float[] mat, float[] vec)
          Multiplies the vector with the given matrix, performing a division by w.
static void prj(float[] mat, float[] vecs, int offset, int numVecs, int stride)
          Multiplies the vectors with the given matrix, , performing a division by w.
static void rot(float[] mat, float[] vec)
          Multiplies the vector with the top most 3x3 sub-matrix of the given matrix.
static void rot(float[] mat, float[] vecs, int offset, int numVecs, int stride)
          Multiplies the vectors with the top most 3x3 sub-matrix of the given matrix.
 Matrix4 rotate(float axisX, float axisY, float axisZ, float angle)
          Postmultiplies this matrix with a (counter-clockwise) rotation matrix.
 Matrix4 rotate(Quaternion rotation)
          Postmultiplies this matrix with a (counter-clockwise) rotation matrix.
 Matrix4 rotate(Vector3 axis, float angle)
          Postmultiplies this matrix with a (counter-clockwise) rotation matrix.
 Matrix4 scale(float scaleX, float scaleY, float scaleZ)
          Postmultiplies this matrix with a scale matrix.
 Matrix4 scl(float scale)
           
 Matrix4 scl(Vector3 scale)
           
 Matrix4 set(float[] values)
          Sets the matrix to the given matrix as a float array.
 Matrix4 set(Matrix3 mat)
          Sets this matrix to the given 3x3 matrix.
 Matrix4 set(Matrix4 matrix)
          Sets the matrix to the given matrix.
 Matrix4 set(Quaternion quaternion)
          Sets the matrix to a rotation matrix representing the quaternion.
 void set(Vector3 xAxis, Vector3 yAxis, Vector3 zAxis, Vector3 pos)
          Sets the four columns of the matrix which correspond to the x-, y- and z-axis of the vector space this matrix creates as well as the 4th column representing the translation of any point that is multiplied by this matrix.
 Matrix4 setFromEulerAngles(float yaw, float pitch, float roll)
          Sets this matrix to a rotation matrix from the given euler angles.
 Matrix4 setToLookAt(Vector3 direction, Vector3 up)
          Sets the matrix to a look at matrix with a direction and an up vector.
 Matrix4 setToLookAt(Vector3 position, Vector3 target, Vector3 up)
          Sets this matrix to a look at matrix with the given position, target and up vector.
 Matrix4 setToOrtho(float left, float right, float bottom, float top, float near, float far)
          Sets the matrix to an orthographic projection like glOrtho (http://www.opengl.org/sdk/docs/man/xhtml/glOrtho.xml) following the OpenGL equivalent
 Matrix4 setToOrtho2D(float x, float y, float width, float height)
          Sets this matrix to an orthographic projection matrix with the origin at (x,y) extending by width and height.
 Matrix4 setToOrtho2D(float x, float y, float width, float height, float near, float far)
          Sets this matrix to an orthographic projection matrix with the origin at (x,y) extending by width and height, having a near and far plane.
 Matrix4 setToProjection(float near, float far, float fov, float aspectRatio)
          Sets the matrix to a projection matrix with a near- and far plane, a field of view in degrees and an aspect ratio.
 Matrix4 setToRotation(float axisX, float axisY, float axisZ, float angle)
          Sets the matrix to a rotation matrix around the given axis.
 Matrix4 setToRotation(Vector3 axis, float angle)
          Sets the matrix to a rotation matrix around the given axis.
 Matrix4 setToScaling(float x, float y, float z)
          Sets this matrix to a scaling matrix
 Matrix4 setToScaling(Vector3 vector)
          Sets this matrix to a scaling matrix
 Matrix4 setToTranslation(float x, float y, float z)
          Sets this matrix to a translation matrix, overwriting it first by an identity matrix and then setting the 4th column to the translation vector.
 Matrix4 setToTranslation(Vector3 vector)
          Sets this matrix to a translation matrix, overwriting it first by an identity matrix and then setting the 4th column to the translation vector.
 Matrix4 setToTranslationAndScaling(float translationX, float translationY, float translationZ, float scalingX, float scalingY, float scalingZ)
          Sets this matrix to a translation and scaling matrix by first overwritting it with an identity and then setting the translation vector in the 4th column and the scaling vector in the diagonal.
 Matrix4 setToTranslationAndScaling(Vector3 translation, Vector3 scaling)
          Sets this matrix to a translation and scaling matrix by first overwritting it with an identity and then setting the translation vector in the 4th column and the scaling vector in the diagonal.
 Matrix4 setToWorld(Vector3 position, Vector3 forward, Vector3 up)
           
 Matrix4 toNormalMatrix()
          removes the translational part and transposes the matrix.
 java.lang.String toString()
          
 Matrix4 tra()
          Transposes the matrix
 Matrix4 translate(float x, float y, float z)
          Postmultiplies this matrix by a translation matrix.
 Matrix4 translate(Vector3 translation)
          Postmultiplies this matrix by a translation matrix.
 Matrix4 trn(float x, float y, float z)
          Adds a translational component to the matrix in the 4th column.
 Matrix4 trn(Vector3 vector)
          Adds a translational component to the matrix in the 4th column.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

M00

public static final int M00
See Also:
Constant Field Values

M01

public static final int M01
See Also:
Constant Field Values

M02

public static final int M02
See Also:
Constant Field Values

M03

public static final int M03
See Also:
Constant Field Values

M10

public static final int M10
See Also:
Constant Field Values

M11

public static final int M11
See Also:
Constant Field Values

M12

public static final int M12
See Also:
Constant Field Values

M13

public static final int M13
See Also:
Constant Field Values

M20

public static final int M20
See Also:
Constant Field Values

M21

public static final int M21
See Also:
Constant Field Values

M22

public static final int M22
See Also:
Constant Field Values

M23

public static final int M23
See Also:
Constant Field Values

M30

public static final int M30
See Also:
Constant Field Values

M31

public static final int M31
See Also:
Constant Field Values

M32

public static final int M32
See Also:
Constant Field Values

M33

public static final int M33
See Also:
Constant Field Values

tmp

public final float[] tmp

val

public final float[] val
Constructor Detail

Matrix4

public Matrix4()
Constructs an identity matrix


Matrix4

public Matrix4(Matrix4 matrix)
Constructs a matrix from the given matrix

Parameters:
matrix - The matrix

Matrix4

public Matrix4(float[] values)
Constructs a matrix from the given float array. The array must have at least 16 elements

Parameters:
values - The float array

Matrix4

public Matrix4(Quaternion quaternion)
Constructs a rotation matrix from the given Quaternion

Parameters:
quaternion - The quaternion
Method Detail

set

public Matrix4 set(Matrix4 matrix)
Sets the matrix to the given matrix.

Parameters:
matrix - The matrix
Returns:
This matrix for chaining

set

public Matrix4 set(float[] values)
Sets the matrix to the given matrix as a float array. The float array must have at least 16 elements.

Parameters:
values - The matrix
Returns:
This matrix for chaining

set

public Matrix4 set(Quaternion quaternion)
Sets the matrix to a rotation matrix representing the quaternion.

Parameters:
quaternion - The quaternion
Returns:
This matrix for chaining

set

public void set(Vector3 xAxis,
                Vector3 yAxis,
                Vector3 zAxis,
                Vector3 pos)
Sets the four columns of the matrix which correspond to the x-, y- and z-axis of the vector space this matrix creates as well as the 4th column representing the translation of any point that is multiplied by this matrix.

Parameters:
xAxis - The x-axis
yAxis - The y-axis
zAxis - The z-axis
pos - The translation vector

cpy

public Matrix4 cpy()
Returns:
a copy of this matrix

trn

public Matrix4 trn(Vector3 vector)
Adds a translational component to the matrix in the 4th column. The other columns are untouched.

Parameters:
vector - The translation vector
Returns:
This matrix for chaining

trn

public Matrix4 trn(float x,
                   float y,
                   float z)
Adds a translational component to the matrix in the 4th column. The other columns are untouched.

Parameters:
x - The x-component of the translation vector
y - The y-component of the translation vector
z - The z-component of the translation vector
Returns:
This matrix for chaining

getValues

public float[] getValues()
Returns:
the backing float array

mul

public Matrix4 mul(Matrix4 matrix)
Multiplies this matrix with the given matrix, storing the result in this matrix.

Parameters:
matrix - The other matrix
Returns:
This matrix for chaining.

tra

public Matrix4 tra()
Transposes the matrix

Returns:
This matrix for chaining

idt

public Matrix4 idt()
Sets the matrix to an identity matrix

Returns:
This matrix for chaining

inv

public Matrix4 inv()
Inverts the matrix. Throws a RuntimeException in case the matrix is not invertible. Stores the result in this matrix

Returns:
This matrix for chaining

det

public float det()
Returns:
The determinant of this matrix

setToProjection

public Matrix4 setToProjection(float near,
                               float far,
                               float fov,
                               float aspectRatio)
Sets the matrix to a projection matrix with a near- and far plane, a field of view in degrees and an aspect ratio.

Parameters:
near - The near plane
far - The far plane
fov - The field of view in degrees
aspectRatio - The aspect ratio
Returns:
This matrix for chaining

setToOrtho2D

public Matrix4 setToOrtho2D(float x,
                            float y,
                            float width,
                            float height)
Sets this matrix to an orthographic projection matrix with the origin at (x,y) extending by width and height. The near plane is set to 0, the far plane is set to 1.

Parameters:
x - The x-coordinate of the origin
y - The y-coordinate of the origin
width - The width
height - The height
Returns:
This matrix for chaining

setToOrtho2D

public Matrix4 setToOrtho2D(float x,
                            float y,
                            float width,
                            float height,
                            float near,
                            float far)
Sets this matrix to an orthographic projection matrix with the origin at (x,y) extending by width and height, having a near and far plane.

Parameters:
x - The x-coordinate of the origin
y - The y-coordinate of the origin
width - The width
height - The height
near - The near plane
far - The far plane
Returns:
This matrix for chaining

setToOrtho

public Matrix4 setToOrtho(float left,
                          float right,
                          float bottom,
                          float top,
                          float near,
                          float far)
Sets the matrix to an orthographic projection like glOrtho (http://www.opengl.org/sdk/docs/man/xhtml/glOrtho.xml) following the OpenGL equivalent

Parameters:
left - The left clipping plane
right - The right clipping plane
bottom - The bottom clipping plane
top - The top clipping plane
near - The near clipping plane
far - The far clipping plane
Returns:
This matrix for chaining

setToTranslation

public Matrix4 setToTranslation(Vector3 vector)
Sets this matrix to a translation matrix, overwriting it first by an identity matrix and then setting the 4th column to the translation vector.

Parameters:
vector - The translation vector
Returns:
This matrix for chaining

setToTranslation

public Matrix4 setToTranslation(float x,
                                float y,
                                float z)
Sets this matrix to a translation matrix, overwriting it first by an identity matrix and then setting the 4th column to the translation vector.

Parameters:
x - The x-component of the translation vector
y - The y-component of the translation vector
z - The z-component of the translation vector
Returns:
This matrix for chaining

setToTranslationAndScaling

public Matrix4 setToTranslationAndScaling(Vector3 translation,
                                          Vector3 scaling)
Sets this matrix to a translation and scaling matrix by first overwritting it with an identity and then setting the translation vector in the 4th column and the scaling vector in the diagonal.

Parameters:
translation - The translation vector
scaling - The scaling vector
Returns:
This matrix for chaining

setToTranslationAndScaling

public Matrix4 setToTranslationAndScaling(float translationX,
                                          float translationY,
                                          float translationZ,
                                          float scalingX,
                                          float scalingY,
                                          float scalingZ)
Sets this matrix to a translation and scaling matrix by first overwritting it with an identity and then setting the translation vector in the 4th column and the scaling vector in the diagonal.

Parameters:
translationX - The x-component of the translation vector
translationY - The y-component of the translation vector
translationZ - The z-component of the translation vector
scalingX - The x-component of the scaling vector
scalingY - The x-component of the scaling vector
scalingZ - The x-component of the scaling vector
Returns:
This matrix for chaining

setToRotation

public Matrix4 setToRotation(Vector3 axis,
                             float angle)
Sets the matrix to a rotation matrix around the given axis.

Parameters:
axis - The axis
angle - The angle in degrees
Returns:
This matrix for chaining

setToRotation

public Matrix4 setToRotation(float axisX,
                             float axisY,
                             float axisZ,
                             float angle)
Sets the matrix to a rotation matrix around the given axis.

Parameters:
axisX - The x-component of the axis
axisY - The y-component of the axis
axisZ - The z-component of the axis
angle - The angle in degrees
Returns:
This matrix for chaining

setFromEulerAngles

public Matrix4 setFromEulerAngles(float yaw,
                                  float pitch,
                                  float roll)
Sets this matrix to a rotation matrix from the given euler angles.

Parameters:
yaw - the yaw in degrees
pitch - the pitch in degress
roll - the roll in degrees
Returns:
this matrix

setToScaling

public Matrix4 setToScaling(Vector3 vector)
Sets this matrix to a scaling matrix

Parameters:
vector - The scaling vector
Returns:
This matrix for chaining.

setToScaling

public Matrix4 setToScaling(float x,
                            float y,
                            float z)
Sets this matrix to a scaling matrix

Parameters:
x - The x-component of the scaling vector
y - The y-component of the scaling vector
z - The z-component of the scaling vector
Returns:
This matrix for chaining.

setToLookAt

public Matrix4 setToLookAt(Vector3 direction,
                           Vector3 up)
Sets the matrix to a look at matrix with a direction and an up vector. Multiply with a translation matrix to get a camera model view matrix.

Parameters:
direction - The direction vector
up - The up vector
Returns:
This matrix for chaining

setToLookAt

public Matrix4 setToLookAt(Vector3 position,
                           Vector3 target,
                           Vector3 up)
Sets this matrix to a look at matrix with the given position, target and up vector.

Parameters:
position - the position
target - the target
up - the up vector
Returns:
this matrix

setToWorld

public Matrix4 setToWorld(Vector3 position,
                          Vector3 forward,
                          Vector3 up)

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object

lerp

public void lerp(Matrix4 matrix,
                 float alpha)
Linearly interpolates between this matrix and the given matrix mixing by alpha

Parameters:
matrix - the matrix
alpha - the alpha value in the range [0,1]

set

public Matrix4 set(Matrix3 mat)
Sets this matrix to the given 3x3 matrix. The third column of this matrix is set to (0,0,1,0).

Parameters:
mat - the matrix

scl

public Matrix4 scl(Vector3 scale)

scl

public Matrix4 scl(float scale)

getTranslation

public void getTranslation(Vector3 position)

getRotation

public void getRotation(Quaternion rotation)

toNormalMatrix

public Matrix4 toNormalMatrix()
removes the translational part and transposes the matrix.


mul

public static void mul(float[] mata,
                       float[] matb)
Multiplies the matrix mata with matrix matb, storing the result in mata. The arrays are assumed to hold 4x4 column major matrices as you can get from val. This is the same as mul(Matrix4).

Parameters:
mata - the first matrix.
matb - the second matrix.

mulVec

public static void mulVec(float[] mat,
                          float[] vec)
Multiplies the vector with the given matrix. The matrix array is assumed to hold a 4x4 column major matrix as you can get from val. The vector array is assumed to hold a 3-component vector, with x being the first element, y being the second and z being the last component. The result is stored in the vector array. This is the same as Vector3.mul(Matrix4).

Parameters:
mat - the matrix
vec - the vector.

mulVec

public static void mulVec(float[] mat,
                          float[] vecs,
                          int offset,
                          int numVecs,
                          int stride)
Multiplies the vectors with the given matrix. The matrix array is assumed to hold a 4x4 column major matrix as you can get from val. The vectors array is assumed to hold 3-component vectors. Offset specifies the offset into the array where the x-component of the first vector is located. The numVecs parameter specifies the number of vectors stored in the vectors array. The stride parameter specifies the number of floats between subsequent vectors and must be >= 3. This is the same as Vector3.mul(Matrix4) applied to multiple vectors.

Parameters:
mat - the matrix
vecs - the vectors
offset - the offset into the vectors array
numVecs - the number of vectors
stride - the stride between vectors in floats

prj

public static void prj(float[] mat,
                       float[] vec)
Multiplies the vector with the given matrix, performing a division by w. The matrix array is assumed to hold a 4x4 column major matrix as you can get from val. The vector array is assumed to hold a 3-component vector, with x being the first element, y being the second and z being the last component. The result is stored in the vector array. This is the same as Vector3.prj(Matrix4).

Parameters:
mat - the matrix
vec - the vector.

prj

public static void prj(float[] mat,
                       float[] vecs,
                       int offset,
                       int numVecs,
                       int stride)
Multiplies the vectors with the given matrix, , performing a division by w. The matrix array is assumed to hold a 4x4 column major matrix as you can get from val. The vectors array is assumed to hold 3-component vectors. Offset specifies the offset into the array where the x-component of the first vector is located. The numVecs parameter specifies the number of vectors stored in the vectors array. The stride parameter specifies the number of floats between subsequent vectors and must be >= 3. This is the same as Vector3.prj(Matrix4) applied to multiple vectors.

Parameters:
mat - the matrix
vecs - the vectors
offset - the offset into the vectors array
numVecs - the number of vectors
stride - the stride between vectors in floats

rot

public static void rot(float[] mat,
                       float[] vec)
Multiplies the vector with the top most 3x3 sub-matrix of the given matrix. The matrix array is assumed to hold a 4x4 column major matrix as you can get from val. The vector array is assumed to hold a 3-component vector, with x being the first element, y being the second and z being the last component. The result is stored in the vector array. This is the same as Vector3.rot(Matrix4).

Parameters:
mat - the matrix
vec - the vector.

rot

public static void rot(float[] mat,
                       float[] vecs,
                       int offset,
                       int numVecs,
                       int stride)
Multiplies the vectors with the top most 3x3 sub-matrix of the given matrix. The matrix array is assumed to hold a 4x4 column major matrix as you can get from val. The vectors array is assumed to hold 3-component vectors. Offset specifies the offset into the array where the x-component of the first vector is located. The numVecs parameter specifies the number of vectors stored in the vectors array. The stride parameter specifies the number of floats between subsequent vectors and must be >= 3. This is the same as Vector3.rot(Matrix4) applied to multiple vectors.

Parameters:
mat - the matrix
vecs - the vectors
offset - the offset into the vectors array
numVecs - the number of vectors
stride - the stride between vectors in floats

inv

public static boolean inv(float[] values)
Computes the inverse of the given matrix. The matrix array is assumed to hold a 4x4 column major matrix as you can get from val.

Parameters:
values - the matrix values.
Returns:
false in case the inverse could not be calculated, true otherwise.

det

public static float det(float[] values)
Computes the determinante of the given matrix. The matrix array is assumed to hold a 4x4 column major matrix as you can get from val.

Parameters:
values - the matrix values.
Returns:
the determinante.

translate

public Matrix4 translate(Vector3 translation)
Postmultiplies this matrix by a translation matrix. Postmultiplication is also used by OpenGL ES' glTranslate/glRotate/glScale

Parameters:
translation -
Returns:
this matrix for chaining

translate

public Matrix4 translate(float x,
                         float y,
                         float z)
Postmultiplies this matrix by a translation matrix. Postmultiplication is also used by OpenGL ES' glTranslate/glRotate/glScale

Parameters:
x -
y -
z -
Returns:
this matrix for chaining

rotate

public Matrix4 rotate(Vector3 axis,
                      float angle)
Postmultiplies this matrix with a (counter-clockwise) rotation matrix. Postmultiplication is also used by OpenGL ES' glTranslate/glRotate/glScale

Parameters:
axis -
angle - the angle in degrees
Returns:
this matrix for chaining

rotate

public Matrix4 rotate(float axisX,
                      float axisY,
                      float axisZ,
                      float angle)
Postmultiplies this matrix with a (counter-clockwise) rotation matrix. Postmultiplication is also used by OpenGL ES' glTranslate/glRotate/glScale

Parameters:
axisX -
axisY -
axisZ -
angle - the angle in degrees
Returns:
this matrix for chaining

rotate

public Matrix4 rotate(Quaternion rotation)
Postmultiplies this matrix with a (counter-clockwise) rotation matrix. Postmultiplication is also used by OpenGL ES' glTranslate/glRotate/glScale

Parameters:
rotation -
Returns:
this matrix for chaining

scale

public Matrix4 scale(float scaleX,
                     float scaleY,
                     float scaleZ)
Postmultiplies this matrix with a scale matrix. Postmultiplication is also used by OpenGL ES' glTranslate/glRotate/glScale.

Parameters:
scaleX -
scaleY -
scaleZ -
Returns:
this matrix for chaining

libgdx API

Copyright 2010 Mario Zechner (contact@badlogicgames.com), Nathan Sweet (admin@esotericsoftware.com)