Home Original page

Matrix  |  API reference  |  Android Developers

public class Matrix
extends Object


Matrix math utilities. These methods operate on OpenGL ES format matrices and vectors stored in float arrays.

Matrices are 4 x 4 column-vector matrices stored in column-major order: 

  m[offset +  0] m[offset +  4] m[offset +  8] m[offset + 12]
  m[offset +  1] m[offset +  5] m[offset +  9] m[offset + 13]
  m[offset +  2] m[offset +  6] m[offset + 10] m[offset + 14]
  m[offset +  3] m[offset +  7] m[offset + 11] m[offset + 15]

Vectors are 4 x 1 column vectors stored in order: 

 v[offset + 0]
 v[offset + 1]
 v[offset + 2]
 v[offset + 3]

Summary

Public constructors

Matrix()

This constructor is deprecated. All methods are static, do not instantiate this class.

Public methods

static void frustumM(float[] m, int offset, float left, float right, float bottom, float top, float near, float far)

Defines a projection matrix in terms of six clip planes.

static boolean invertM(float[] mInv, int mInvOffset, float[] m, int mOffset)

Inverts a 4 x 4 matrix.

static float length(float x, float y, float z)

Computes the length of a vector.

static void multiplyMM(float[] result, int resultOffset, float[] lhs, int lhsOffset, float[] rhs, int rhsOffset)

Multiplies two 4x4 matrices together and stores the result in a third 4x4 matrix.

static void multiplyMV(float[] resultVec, int resultVecOffset, float[] lhsMat, int lhsMatOffset, float[] rhsVec, int rhsVecOffset)

Multiplies a 4 element vector by a 4x4 matrix and stores the result in a 4-element column vector.

static void orthoM(float[] m, int mOffset, float left, float right, float bottom, float top, float near, float far)

Computes an orthographic projection matrix.

static void perspectiveM(float[] m, int offset, float fovy, float aspect, float zNear, float zFar)

Defines a projection matrix in terms of a field of view angle, an aspect ratio, and z clip planes.

static void rotateM(float[] rm, int rmOffset, float[] m, int mOffset, float a, float x, float y, float z)

Rotates matrix m by angle a (in degrees) around the axis (x, y, z).

static void rotateM(float[] m, int mOffset, float a, float x, float y, float z)

Rotates matrix m in place by angle a (in degrees) around the axis (x, y, z).

static void scaleM(float[] m, int mOffset, float x, float y, float z)

Scales matrix m in place by sx, sy, and sz.

static void scaleM(float[] sm, int smOffset, float[] m, int mOffset, float x, float y, float z)

Scales matrix m by x, y, and z, putting the result in sm.

static void setIdentityM(float[] sm, int smOffset)

Sets matrix m to the identity matrix.

static void setLookAtM(float[] rm, int rmOffset, float eyeX, float eyeY, float eyeZ, float centerX, float centerY, float centerZ, float upX, float upY, float upZ)

Defines a viewing transformation in terms of an eye point, a center of view, and an up vector.

static void setRotateEulerM(float[] rm, int rmOffset, float x, float y, float z)

This method was deprecated in API level 34. This method is incorrect around the y axis. This method is deprecated and replaced (below) by setRotateEulerM2 which behaves correctly

static void setRotateEulerM2(float[] rm, int rmOffset, float x, float y, float z)

Converts Euler angles to a rotation matrix.

static void setRotateM(float[] rm, int rmOffset, float a, float x, float y, float z)

Creates a matrix for rotation by angle a (in degrees) around the axis (x, y, z).

static void translateM(float[] m, int mOffset, float x, float y, float z)

Translates matrix m by x, y, and z in place.

static void translateM(float[] tm, int tmOffset, float[] m, int mOffset, float x, float y, float z)

Translates matrix m by x, y, and z, putting the result in tm.

static void transposeM(float[] mTrans, int mTransOffset, float[] m, int mOffset)

Transposes a 4 x 4 matrix.

Inherited methods

From class java.lang.Object

Object clone()

Creates and returns a copy of this object.

boolean equals(Object obj)

Indicates whether some other object is "equal to" this one.

void finalize()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

final Class<?> getClass()

Returns the runtime class of this Object.

int hashCode()

Returns a hash code value for the object.

final void notify()

Wakes up a single thread that is waiting on this object's monitor.

final void notifyAll()

Wakes up all threads that are waiting on this object's monitor.

String toString()

Returns a string representation of the object.

final void wait(long timeoutMillis, int nanos)

Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

final void wait(long timeoutMillis)

Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

final void wait()

Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public constructors

Matrix

public Matrix ()

This constructor is deprecated.
All methods are static, do not instantiate this class.

Public methods

frustumM

public static void frustumM (float[] m, 
                int offset, 
                float left, 
                float right, 
                float bottom, 
                float top, 
                float near, 
                float far)

Defines a projection matrix in terms of six clip planes.

Parameters
m float: the float array that holds the output perspective matrix
offset int: the offset into float array m where the perspective matrix data is written

invertM

public static boolean invertM (float[] mInv, 
                int mInvOffset, 
                float[] m, 
                int mOffset)

Inverts a 4 x 4 matrix.

mInv and m must not overlap.

Parameters
mInv float: the array that holds the output inverted matrix
mInvOffset int: an offset into mInv where the inverted matrix is stored.
m float: the input array
mOffset int: an offset into m where the input matrix is stored.
Returns
boolean true if the matrix could be inverted, false if it could not.

length

public static float length (float x, 
                float y, 
                float z)

Computes the length of a vector.

Parameters
x float: x coordinate of a vector
y float: y coordinate of a vector
z float: z coordinate of a vector
Returns
float the length of a vector

multiplyMM

public static void multiplyMM (float[] result, 
                int resultOffset, 
                float[] lhs, 
                int lhsOffset, 
                float[] rhs, 
                int rhsOffset)

Multiplies two 4x4 matrices together and stores the result in a third 4x4 matrix. In matrix notation: result = lhs x rhs. Due to the way matrix multiplication works, the result matrix will have the same effect as first multiplying by the rhs matrix, then multiplying by the lhs matrix. This is the opposite of what you might expect.

The same float array may be passed for result, lhs, and/or rhs. This operation is expected to do the correct thing if the result elements overlap with either of the lhs or rhs elements.

Parameters
result float: The float array that holds the result.
resultOffset int: The offset into the result array where the result is stored.
lhs float: The float array that holds the left-hand-side matrix.
lhsOffset int: The offset into the lhs array where the lhs is stored
rhs float: The float array that holds the right-hand-side matrix.
rhsOffset int: The offset into the rhs array where the rhs is stored.
Throws
IllegalArgumentException under any of the following conditions: result, lhs, or rhs are null; resultOffset + 16 > result.length or lhsOffset + 16 > lhs.length or rhsOffset + 16 > rhs.length; resultOffset < 0 or lhsOffset < 0 or rhsOffset < 0

multiplyMV

public static void multiplyMV (float[] resultVec, 
                int resultVecOffset, 
                float[] lhsMat, 
                int lhsMatOffset, 
                float[] rhsVec, 
                int rhsVecOffset)

Multiplies a 4 element vector by a 4x4 matrix and stores the result in a 4-element column vector. In matrix notation: result = lhs x rhs

The same float array may be passed for resultVec, lhsMat, and/or rhsVec. This operation is expected to do the correct thing if the result elements overlap with either of the lhs or rhs elements.

Parameters
resultVec float: The float array that holds the result vector.
resultVecOffset int: The offset into the result array where the result vector is stored.
lhsMat float: The float array that holds the left-hand-side matrix.
lhsMatOffset int: The offset into the lhs array where the lhs is stored
rhsVec float: The float array that holds the right-hand-side vector.
rhsVecOffset int: The offset into the rhs vector where the rhs vector is stored.
Throws
IllegalArgumentException under any of the following conditions: resultVec, lhsMat, or rhsVec are null; resultVecOffset + 4 > resultVec.length or lhsMatOffset + 16 > lhsMat.length or rhsVecOffset + 4 > rhsVec.length; resultVecOffset < 0 or lhsMatOffset < 0 or rhsVecOffset < 0

orthoM

public static void orthoM (float[] m, 
                int mOffset, 
                float left, 
                float right, 
                float bottom, 
                float top, 
                float near, 
                float far)

Computes an orthographic projection matrix.

Parameters
m float: returns the result

perspectiveM

public static void perspectiveM (float[] m, 
                int offset, 
                float fovy, 
                float aspect, 
                float zNear, 
                float zFar)

Defines a projection matrix in terms of a field of view angle, an aspect ratio, and z clip planes.

Parameters
m float: the float array that holds the perspective matrix
offset int: the offset into float array m where the perspective matrix data is written
fovy float: field of view in y direction, in degrees
aspect float: width to height aspect ratio of the viewport

rotateM

public static void rotateM (float[] rm, 
                int rmOffset, 
                float[] m, 
                int mOffset, 
                float a, 
                float x, 
                float y, 
                float z)

Rotates matrix m by angle a (in degrees) around the axis (x, y, z).

m and rm must not overlap.

Parameters
rm float: returns the result
rmOffset int: index into rm where the result matrix starts
m float: source matrix
mOffset int: index into m where the source matrix starts
a float: angle to rotate in degrees
x float: X axis component
y float: Y axis component
z float: Z axis component

rotateM

public static void rotateM (float[] m, 
                int mOffset, 
                float a, 
                float x, 
                float y, 
                float z)

Rotates matrix m in place by angle a (in degrees) around the axis (x, y, z).

Parameters
m float: source matrix
mOffset int: index into m where the matrix starts
a float: angle to rotate in degrees
x float: X axis component
y float: Y axis component
z float: Z axis component

scaleM

public static void scaleM (float[] m, 
                int mOffset, 
                float x, 
                float y, 
                float z)

Scales matrix m in place by sx, sy, and sz.

Parameters
m float: matrix to scale
mOffset int: index into m where the matrix starts
x float: scale factor x
y float: scale factor y
z float: scale factor z

scaleM

public static void scaleM (float[] sm, 
                int smOffset, 
                float[] m, 
                int mOffset, 
                float x, 
                float y, 
                float z)

Scales matrix m by x, y, and z, putting the result in sm.

m and sm must not overlap.

Parameters
sm float: returns the result
smOffset int: index into sm where the result matrix starts
m float: source matrix
mOffset int: index into m where the source matrix starts
x float: scale factor x
y float: scale factor y
z float: scale factor z

setIdentityM

public static void setIdentityM (float[] sm, 
                int smOffset)

Sets matrix m to the identity matrix.

Parameters
sm float: returns the result
smOffset int: index into sm where the result matrix starts

setLookAtM

public static void setLookAtM (float[] rm, 
                int rmOffset, 
                float eyeX, 
                float eyeY, 
                float eyeZ, 
                float centerX, 
                float centerY, 
                float centerZ, 
                float upX, 
                float upY, 
                float upZ)

Defines a viewing transformation in terms of an eye point, a center of view, and an up vector.

Parameters
rm float: returns the result
rmOffset int: index into rm where the result matrix starts
eyeX float: eye point X
eyeY float: eye point Y
eyeZ float: eye point Z
centerX float: center of view X
centerY float: center of view Y
centerZ float: center of view Z
upX float: up vector X
upY float: up vector Y
upZ float: up vector Z

setRotateEulerM

public static void setRotateEulerM (float[] rm, 
                int rmOffset, 
                float x, 
                float y, 
                float z)

This method was deprecated in API level 34.
This method is incorrect around the y axis. This method is deprecated and replaced (below) by setRotateEulerM2 which behaves correctly

Converts Euler angles to a rotation matrix.

Parameters
rm float: returns the result
rmOffset int: index into rm where the result matrix starts
x float: angle of rotation, in degrees
y float: is broken, do not use
z float: angle of rotation, in degrees

setRotateEulerM2

public static void setRotateEulerM2 (float[] rm, 
                int rmOffset, 
                float x, 
                float y, 
                float z)

Converts Euler angles to a rotation matrix.

Parameters
rm float: returns the result
rmOffset int: index into rm where the result matrix starts
x float: angle of rotation, in degrees
y float: angle of rotation, in degrees
z float: angle of rotation, in degrees
Throws
IllegalArgumentException if rm is null; or if rmOffset + 16 > rm.length; rmOffset < 0

setRotateM

public static void setRotateM (float[] rm, 
                int rmOffset, 
                float a, 
                float x, 
                float y, 
                float z)

Creates a matrix for rotation by angle a (in degrees) around the axis (x, y, z).

An optimized path will be used for rotation about a major axis (e.g. x=1.0f y=0.0f z=0.0f).

Parameters
rm float: returns the result
rmOffset int: index into rm where the result matrix starts
a float: angle to rotate in degrees
x float: X axis component
y float: Y axis component
z float: Z axis component

translateM

public static void translateM (float[] m, 
                int mOffset, 
                float x, 
                float y, 
                float z)

Translates matrix m by x, y, and z in place.

Parameters
m float: matrix
mOffset int: index into m where the matrix starts
x float: translation factor x
y float: translation factor y
z float: translation factor z

translateM

public static void translateM (float[] tm, 
                int tmOffset, 
                float[] m, 
                int mOffset, 
                float x, 
                float y, 
                float z)

Translates matrix m by x, y, and z, putting the result in tm.

m and tm must not overlap.

Parameters
tm float: returns the result
tmOffset int: index into sm where the result matrix starts
m float: source matrix
mOffset int: index into m where the source matrix starts
x float: translation factor x
y float: translation factor y
z float: translation factor z

transposeM

public static void transposeM (float[] mTrans, 
                int mTransOffset, 
                float[] m, 
                int mOffset)

Transposes a 4 x 4 matrix.

mTrans and m must not overlap.

Parameters
mTrans float: the array that holds the output transposed matrix
mTransOffset int: an offset into mTrans where the transposed matrix is stored.
m float: the input array
mOffset int: an offset into m where the input matrix is stored.