Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

net.rim.device.api.math
Class Matrix4f

java.lang.Object
  extended by net.rim.device.api.math.Matrix4f

public class Matrix4f
extends Object

Defines a 4 x 4 floating point matrix representing a 3D transformation.

Vectors are treated as columns, resulting in a matrix that is represented as follows, where x, y and z are the translation components of the matrix: 

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

This matrix class is directly compatible with OpenGL since its elements are laid out in memory exactly as they are expected by OpenGL. The matrix uses column-major format such that array indices increase down column first.

Since matrix multiplication is not commutative, multiplication must be done in the correct order when combining transformations. Suppose we have a translation matrix T and a rotation matrix R. To first rotate an object around the origin and then translate it, you would multiply the two matrices as TR. Likewise, to first translate the object and then rotate it you would do RT. So generally, matrices must be multiplied in the reverse order in which you want the transformations to take place (this also applies to the scale, rotate, and translate methods below; these methods are convenience methods for post-multiplying by a matrix representing a scale, rotation, or translation).

Passing a matrix to OpenGL is a simple and efficient operation since the underlying array for the matrix is stored in a format that is directly compatible with OpenGL. 

   // Create a matrix to translate by (10, 2, -20)
   Matrix4f translation = new Matrix4f();
   translation.set(1, 0, 0, 10,
                   0, 1, 0, 2,
                   0, 0, 1, -20,
                   0, 0, 0, 1 );
   
   // Pass our matrix to OpenGL
   gl.glLoadMatrixf(translation.getArray());

Note: In the case of repeated local transformations (i.e. rotate around the Z-axis by 0.76 radians, then translate by 2.1 along the X-axis, then ...), it is better to use Transform3D (which is optimized for that kind of usage).

See Also:
Transform3D
Since:
BlackBerry API 5.0.0

Constructor Summary
Matrix4f()
          Constructs a matrix initialized to the identity matrix.
Matrix4f(float m00, float m01, float m02, float m03, float m10, float m11, float m12, float m13, float m20, float m21, float m22, float m23, float m30, float m31, float m32, float m33)
          Constructs a matrix initialized to the specified values.
Matrix4f(float[] m)
          Constructs a matrix initialized to the specified column-major array.
Matrix4f(float[] m, int offset)
          Constructs a matrix initialized to the specified column-major array.
Matrix4f(Matrix4f m)
          Constructs a new matrix by copying the values from the specified matrix.
 
Method Summary
 void add(float scalar)
          Adds a scalar value to each component of this matrix.
 void add(float scalar, Matrix4f dst)
          Adds a scalar value to this matrix and stores the result in dst.
 void add(Matrix4f m)
          Adds the specified matrix to this matrix.
static void add(Matrix4f m1, Matrix4f m2, Matrix4f dst)
          Adds the specified matrices and stores the result in dst.
static void createBillboard(Vector3f object, Vector3f cameraPos, Vector3f cameraUpVector, Vector3f cameraForwardVector, Matrix4f dst)
          Creates a spherical billboard that rotates around a specified object position.
static void createLookAt(float eyeX, float eyeY, float eyeZ, float centerX, float centerY, float centerZ, float upX, float upY, float upZ, float[] dst)
          Creates a view matrix based on the specified input parameters.
static void createLookAt(Vector3f cameraPos, Vector3f cameraTarget, Vector3f cameraUpVector, Matrix4f dst)
          Creates a view matrix based on the specified input parameters.
static void createOrthographic(float left, float right, float bottom, float top, float near, float far, Matrix4f dst)
          Creates an orthographic projection matrix.
static void createPerspective(float fovy, float aspect, float zNear, float zFar, Matrix4f dst)
          Creates a perspective projection matrix.
static void createReflection(Plane plane, Matrix4f dst)
          Creates a matrix that reflects the coordinate system about a plane.
static void createRotation(Quaternion4f quat, Matrix4f dst)
          Creates a rotation matrix from the specified quaternion.
static void createRotation(Vector3f axis, float angle, Matrix4f dst)
          Creates a rotation matrix from the specified axis and angle.
static void createRotationX(float angle, Matrix4f dst)
          Creates a matrix describing a rotation around the x-axis.
static void createRotationY(float angle, Matrix4f dst)
          Creates a matrix describing a rotation around the y-axis.
static void createRotationZ(float angle, Matrix4f dst)
          Creates a matrix describing a rotation around the z-axis.
static void createScale(float xScale, float yScale, float zScale, Matrix4f dst)
          Creates a scale matrix.
static void createTranslation(float xTrans, float yTrans, float zTrans, Matrix4f dst)
          Creates a translation matrix.
 boolean decompose(Vector3f scale, Quaternion4f rotation, Vector3f translation)
          Decomposes the scale, rotation and translation components of this matrix.
 float determinant()
          Computes the determinant of this matrix.
 boolean equals(Object obj)
          Determines if this matrix is equal to the specified object.
 boolean equals(Matrix4f m)
          Determines if this matrix is equal to the specified one.
 void get(float[] m)
          Copies the values of this matrix into the given array in column-major order.
 float get(int index)
          Gets the matrix element at the specified position.
 float get(int row, int column)
          Gets the matrix element at the specified row and column.
 float[] getArray()
          Returns the underlying array for this matrix in column-major order.
 void getColumn(int column, float[] v)
          Gets the four elements of the specified column into v.
 void getColumn(int column, Vector3f v)
          Gets the first three elements of the specified column into v.
 boolean getRotation(Quaternion4f rotation)
          Gets the rotational component of this matrix in the specified quaternion.
 void getRow(int row, float[] v)
          Gets the four elements of the specified row into v.
 void getRow(int row, Vector3f v)
          Gets the first three elements of the specified row into v.
 void getScale(Vector3f scale)
          Gets the scalar component of this matrix in the specified vector.
 void getTranslation(Vector3f translation)
          Gets the translational component of this matrix in the specified vector.
 int hashCode()
          Returns the hash code of the matrix, based on the values stored in it.
 boolean invert()
          Inverts this matrix.
 boolean invert(Matrix4f dst)
          Inverts this matrix and stores the result in dst.
 boolean isIdentity()
          Determines if this matrix is equal to the identity matrix.
 void multiply(float scalar)
          Multiplies the components of this matrix by the specified scalar.
 void multiply(float scalar, Matrix4f dst)
          Multiplies the components of this matrix by a scalar and stores the result in dst.
 void multiply(Matrix4f m)
          Multiplies this matrix by the specified one.
static void multiply(Matrix4f m1, Matrix4f m2, Matrix4f dst)
          Multiplies m1 by m2 and stores the result in dst.
 void negate()
          Negates this matrix.
 void negate(Matrix4f dst)
          Gets the negate of this matrix in dst.
 void rotate(Quaternion4f q)
          Post-multiplies this matrix by the matrix corresponding to the specified quaternion rotation.
 void rotate(Quaternion4f q, Matrix4f dst)
          Post-multiplies this matrix by the matrix corresponding to the specified quaternion rotation and stores the result in dst.
 void rotate(Vector3f axis, float angle)
          Post-multiplies this matrix by the matrix corresponding to the specified rotation about the specified axis.
 void rotate(Vector3f axis, float angle, Matrix4f dst)
          Post-multiplies this matrix by the matrix corresponding to the specified rotation about the specified axis and stores the result in dst.
 void rotateX(float angle)
          Post-multiplies this matrix by the matrix corresponding to the specified rotation around the x-axis.
 void rotateX(float angle, Matrix4f dst)
          Post-multiplies this matrix by the matrix corresponding to the specified rotation around the x-axis and stores the result in dst.
 void rotateY(float angle)
          Post-multiplies this matrix by the matrix corresponding to the specified rotation around the y-axis.
 void rotateY(float angle, Matrix4f dst)
          Post-multiplies this matrix by the matrix corresponding to the specified rotation around the y-axis and stores the result in dst.
 void rotateZ(float angle)
          Post-multiplies this matrix by the matrix corresponding to the specified rotation around the z-axis.
 void rotateZ(float angle, Matrix4f dst)
          Post-multiplies this matrix by the matrix corresponding to the specified rotation around the z-axis and stores the result in dst.
 void scale(float value)
          Post-multiplies this matrix by the matrix corresponding to the specified scale transformation.
 void scale(float xScale, float yScale, float zScale)
          Post-multiplies this matrix by the matrix corresponding to the specified scale transformation.
 void scale(float xScale, float yScale, float zScale, Matrix4f dst)
          Post-multiplies this matrix by the matrix corresponding to the specified scale transformation and stores the result in dst.
 void scale(float value, Matrix4f dst)
          Post-multiplies this matrix by the matrix corresponding to the specified scale transformation and stores the result in dst.
 void set(float m00, float m01, float m02, float m03, float m10, float m11, float m12, float m13, float m20, float m21, float m22, float m23, float m30, float m31, float m32, float m33)
          Sets the values of this matrix.
 void set(float[] m)
          Sets the values of this matrix to those in the specified column-major array.
 void set(float[] m, int offset)
          Sets the values of this matrix to those in the specified column-major array.
 void set(int index, float value)
          Sets the specified element of this matrix to the specified value.
 void set(int row, int column, float value)
          Sets the specified element of this matrix to the specified value.
 void set(Matrix4f m)
          Sets the values of this matrix to those of the specified matrix.
 void setIdentity()
          Sets this matrix to the identity matrix.
 void setZero()
          Sets all elements of the current matrix to zero.
 void subtract(Matrix4f m)
          Subtracts the specified matrix from the current matrix.
static void subtract(Matrix4f m1, Matrix4f m2, Matrix4f dst)
          Subtracts the specified matrices and stores the result in dst.
 String toString()
          Returns a string representation of this matrix.
 void transformNormal(Vector3f normal)
          Transforms the specified normal vector by this matrix by treating the fourth (w) coordinate as zero.
 void transformNormal(Vector3f normal, Vector3f dst)
          Transforms the specified normal vector by this matrix by treating the fourth (w) coordinate as zero, and stores the result in dst.
 void transformPoint(Vector3f point)
          Transforms the specified point by this matrix.
 void transformPoint(Vector3f point, Vector3f dst)
          Transforms the specified point by this matrix, and stores the result in dst.
 void transformVector(Vector3f vector)
          Transforms the specified vector by this matrix.
 void transformVector(Vector3f vector, Vector3f dst)
          Transforms the specified vector by this matrix, and stores the result in dst.
 void translate(float x, float y, float z)
          Post-multiplies this matrix by the matrix corresponding to the specified translation.
 void translate(float x, float y, float z, Matrix4f dst)
          Post-multiplies this matrix by the matrix corresponding to the specified translation and stores the result in dst.
 void transpose()
          Transposes this matrix.
 void transpose(Matrix4f dst)
          Gets the transpose of this matrix in dst.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 



Constructor Detail

Matrix4f

public Matrix4f()
Constructs a matrix initialized to the identity matrix.

Since:
BlackBerry API 5.0.0

Matrix4f

public Matrix4f(float[] m)
Constructs a matrix initialized to the specified column-major array.

The passed in array is in column-major order, so the memory layout of the array is as follows: 

   0   4   8   12
   1   5   9   13
   2   6   10  14
   3   7   11  15

Parameters:
m - a 16-element array, stored in column-major order
Throws:
IllegalArgumentException - If m.length is less than 16.
NullPointerException - If m is null.
Since:
BlackBerry API 5.0.0

Matrix4f

public Matrix4f(float[] m,
                int offset)
Constructs a matrix initialized to the specified column-major array.

The passed in array is in column-major order, so the memory layout of the array is as follows: 

   0   4   8   12
   1   5   9   13
   2   6   10  14
   3   7   11  15

Parameters:
m - An array containing 16 elements in column-major order.
offset - The offset into the array to begin reading at.
Throws:
IllegalArgumentException - If offset is less than zero or offset + 15 is greater than or equal to m.length.
NullPointerException - If m is null.
Since:
BlackBerry API 6.0.0

Matrix4f

public Matrix4f(float m00,
                float m01,
                float m02,
                float m03,
                float m10,
                float m11,
                float m12,
                float m13,
                float m20,
                float m21,
                float m22,
                float m23,
                float m30,
                float m31,
                float m32,
                float m33)
Constructs a matrix initialized to the specified values.

Parameters:
m00 - the first element of the first row
m01 - the second element of the first row
m02 - the third element of the first row
m03 - the fourth element of the first row
m10 - the first element of the second row
m11 - the second element of the second row
m12 - the third element of the second row
m13 - the fourth element of the second row
m20 - the first element of the third row
m21 - the second element of the third row
m22 - the third element of the third row
m23 - the fourth element of the third row
m30 - the first element of the fourth row
m31 - the second element of the fourth row
m32 - the third element of the fourth row
m33 - the fourth element of the fourth row
Since:
BlackBerry API 5.0.0

Matrix4f

public Matrix4f(Matrix4f m)
Constructs a new matrix by copying the values from the specified matrix.

Parameters:
m - the source matrix
Throws:
NullPointerException - If m is null.
Since:
BlackBerry API 5.0.0


Method Detail

add

public final void add(float scalar)
Adds a scalar value to each component of this matrix.

Parameters:
scalar - the scalar to add
Since:
BlackBerry API 5.0.0

add

public final void add(float scalar,
                      Matrix4f dst)
Adds a scalar value to this matrix and stores the result in dst.

Parameters:
scalar - the scalar value to add
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

add

public final void add(Matrix4f m)
Adds the specified matrix to this matrix.

Parameters:
m - the matrix to add
Throws:
NullPointerException - If m is null.
Since:
BlackBerry API 5.0.0

add

public static void add(Matrix4f m1,
                       Matrix4f m2,
                       Matrix4f dst)
Adds the specified matrices and stores the result in dst.

Parameters:
m1 - the first matrix
m2 - the second matrix
dst - a matrix to store the result in
Throws:
NullPointerException - If m1, m2, or dst is null.
Since:
BlackBerry API 5.0.0

decompose

public final boolean decompose(Vector3f scale,
                               Quaternion4f rotation,
                               Vector3f translation)
Decomposes the scale, rotation and translation components of this matrix.

Parameters:
scale - a vector to store the decomposed scale values in
rotation - a quaternion to store the decomposed rotation in
translation - a vector to store the decomposed translation in
Returns:
true if the the matrix can be decomposed, false otherwise
Throws:
NullPointerException - If scale, rotation, or translation is null.
Since:
BlackBerry API 5.0.0

determinant

public final float determinant()
Computes the determinant of this matrix.

Returns:
the determinant
Since:
BlackBerry API 5.0.0

get

public final void get(float[] m)
Copies the values of this matrix into the given array in column-major order.

Parameters:
m - a 16-element array to populate with the values from this matrix
Throws:
IllegalArgumentException - If m.length is less than 16.
NullPointerException - If m is null.
Since:
BlackBerry API 5.0.0

get

public final float get(int index)
Gets the matrix element at the specified position.

This method indexes the internal array in column-major order. See the description of this class for more information on this topic.

Parameters:
index - the zero-based index of the element to retrieve
Returns:
the value of the specified element.
Throws:
IllegalArgumentException - If index is less than zero or greater than 15.
Since:
BlackBerry API 5.0.0

get

public final float get(int row,
                       int column)
Gets the matrix element at the specified row and column.

Parameters:
row - the zero-based row of the element to retrieve
column - the zero-based column of the element to retrieve
Returns:
the value of the specified element.
Throws:
IllegalArgumentException - If row or column is less than zero or greater than 3.
Since:
BlackBerry API 5.0.0

getArray

public final float[] getArray()
Returns the underlying array for this matrix in column-major order.

The returned array is in column-major order and therefore compatible with systems such as OpenGL that expect data in this order. The memory layout of the array is therefore as follows: 

   0  4  8   12
   1  5  9   13
   2  6  10  14
   3  7  11  15

Note that modifying the elements of the returned array will modify the matrix itself.

Returns:
the internal array in column-major order
Since:
BlackBerry API 5.0.0

getColumn

public final void getColumn(int column,
                            float[] v)
Gets the four elements of the specified column into v.

Parameters:
column - the index of the column to retrieve (zero-based)
v - a four-element array to store the column in
Throws:
IllegalArgumentException - If column is less than zero or greater than 3.
IllegalArgumentException - If v.length is less than 4.
NullPointerException - If v is null.
Since:
BlackBerry API 5.0.0

getColumn

public final void getColumn(int column,
                            Vector3f v)
Gets the first three elements of the specified column into v.

Parameters:
column - the index of the column to retrieve (zero-based)
v - a vector to store the column in
Throws:
IllegalArgumentException - If column is less than zero or greater than 3.
NullPointerException - If v is null.
Since:
BlackBerry API 5.0.0

getRow

public final void getRow(int row,
                         float[] v)
Gets the four elements of the specified row into v.

Parameters:
row - the index of the row to retrieve (zero-based)
v - a four-element array to store the row in
Throws:
IllegalArgumentException - If row is less than zero or greater than 3.
IllegalArgumentException - If v.length is less than 4.
NullPointerException - If v is null.
Since:
BlackBerry API 5.0.0

getRow

public final void getRow(int row,
                         Vector3f v)
Gets the first three elements of the specified row into v.

Parameters:
row - the index of the row to retrieve (zero-based)
v - a vector to store the row in
Throws:
IllegalArgumentException - If row is less than zero or greater than 3.
NullPointerException - If v is null.
Since:
BlackBerry API 5.0.0

getScale

public final void getScale(Vector3f scale)
Gets the scalar component of this matrix in the specified vector.

Note: If the scalar component of this matrix has negative parts, it is not possible to always extract the exact scalar component; instead, a scale vector that is mathematically equivalent to the original scale vector is extracted and returned.

Parameters:
scale - a vector to receive the scale
Throws:
NullPointerException - If scale is null.
Since:
BlackBerry API 5.0.0

getRotation

public final boolean getRotation(Quaternion4f rotation)
Gets the rotational component of this matrix in the specified quaternion.

Parameters:
rotation - a quaternion to receive the rotation
Returns:
true if the rotation is successfully extracted, false otherwise
Throws:
NullPointerException - If rotation is null.
Since:
BlackBerry API 5.0.0

getTranslation

public final void getTranslation(Vector3f translation)
Gets the translational component of this matrix in the specified vector.

Parameters:
translation - a vector to receive the translation
Throws:
NullPointerException - If translation is null.
Since:
BlackBerry API 5.0.0

invert

public final boolean invert()
Inverts this matrix.

Returns:
true if the the matrix can be inverted, false otherwise
Since:
BlackBerry API 5.0.0

invert

public final boolean invert(Matrix4f dst)
Inverts this matrix and stores the result in dst.

Parameters:
dst - a matrix to store the invert of this matrix in
Returns:
true if the the matrix can be inverted, false otherwise
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

isIdentity

public final boolean isIdentity()
Determines if this matrix is equal to the identity matrix.

Returns:
true or false
Since:
BlackBerry API 5.0.0

multiply

public final void multiply(float scalar)
Multiplies the components of this matrix by the specified scalar.

Parameters:
scalar - the scalar value
Since:
BlackBerry API 5.0.0

multiply

public final void multiply(float scalar,
                           Matrix4f dst)
Multiplies the components of this matrix by a scalar and stores the result in dst.

Parameters:
scalar - the scalar value
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

multiply

public final void multiply(Matrix4f m)
Multiplies this matrix by the specified one.

Parameters:
m - the matrix to multiply
Throws:
NullPointerException - If m is null.
Since:
BlackBerry API 5.0.0

multiply

public static void multiply(Matrix4f m1,
                            Matrix4f m2,
                            Matrix4f dst)
Multiplies m1 by m2 and stores the result in dst.

Parameters:
m1 - the first matrix to multiply
m2 - the second matrix to multiply
dst - a matrix to store the result in
Throws:
NullPointerException - If m1, m2, or dst is null.
Since:
BlackBerry API 5.0.0

negate

public final void negate()
Negates this matrix.

Since:
BlackBerry API 5.0.0

negate

public final void negate(Matrix4f dst)
Gets the negate of this matrix in dst.

Parameters:
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

rotate

public final void rotate(Quaternion4f q)
Post-multiplies this matrix by the matrix corresponding to the specified quaternion rotation.

Parameters:
q - the quaternion to rotate by
Throws:
NullPointerException - If q is null.
Since:
BlackBerry API 5.0.0

rotate

public final void rotate(Quaternion4f q,
                         Matrix4f dst)
Post-multiplies this matrix by the matrix corresponding to the specified quaternion rotation and stores the result in dst.

Parameters:
q - the quaternion to rotate by
dst - a matrix to store the result in
Throws:
NullPointerException - If q or dst is null.
Since:
BlackBerry API 5.0.0

rotate

public final void rotate(Vector3f axis,
                         float angle)
Post-multiplies this matrix by the matrix corresponding to the specified rotation about the specified axis.

Parameters:
axis - the axis to rotate about
angle - the angle, in radians
Throws:
NullPointerException - If axis is null.
Since:
BlackBerry API 5.0.0

rotate

public final void rotate(Vector3f axis,
                         float angle,
                         Matrix4f dst)
Post-multiplies this matrix by the matrix corresponding to the specified rotation about the specified axis and stores the result in dst.

Parameters:
axis - the axis to rotate about
angle - the angle, in radians
dst - a matrix to store the result in
Throws:
NullPointerException - If axis or dst is null.
Since:
BlackBerry API 5.0.0

rotateX

public final void rotateX(float angle)
Post-multiplies this matrix by the matrix corresponding to the specified rotation around the x-axis.

Parameters:
angle - the angle to rotate by, in radians
Since:
BlackBerry API 5.0.0

rotateX

public final void rotateX(float angle,
                          Matrix4f dst)
Post-multiplies this matrix by the matrix corresponding to the specified rotation around the x-axis and stores the result in dst.

Parameters:
angle - the angle to rotate by, in radians
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

rotateY

public final void rotateY(float angle)
Post-multiplies this matrix by the matrix corresponding to the specified rotation around the y-axis.

Parameters:
angle - the angle to rotate by, in radians
Since:
BlackBerry API 5.0.0

rotateY

public final void rotateY(float angle,
                          Matrix4f dst)
Post-multiplies this matrix by the matrix corresponding to the specified rotation around the y-axis and stores the result in dst.

Parameters:
angle - the angle to rotate by, in radians
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

rotateZ

public final void rotateZ(float angle)
Post-multiplies this matrix by the matrix corresponding to the specified rotation around the z-axis.

Parameters:
angle - the angle to rotate by, in radians
Since:
BlackBerry API 5.0.0

rotateZ

public final void rotateZ(float angle,
                          Matrix4f dst)
Post-multiplies this matrix by the matrix corresponding to the specified rotation around the z-axis and stores the result in dst.

Parameters:
angle - the angle to rotate by, in radians
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

scale

public final void scale(float value)
Post-multiplies this matrix by the matrix corresponding to the specified scale transformation.

Parameters:
value - the amount to scale along all axes
Since:
BlackBerry API 5.0.0

scale

public final void scale(float value,
                        Matrix4f dst)
Post-multiplies this matrix by the matrix corresponding to the specified scale transformation and stores the result in dst.

Parameters:
value - the amount to scale along all axes
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

scale

public final void scale(float xScale,
                        float yScale,
                        float zScale)
Post-multiplies this matrix by the matrix corresponding to the specified scale transformation.

Parameters:
xScale - the amount to scale along the x-axis
yScale - the amount to scale along the y-axis
zScale - the amount to scale along the z-axis
Since:
BlackBerry API 5.0.0

scale

public final void scale(float xScale,
                        float yScale,
                        float zScale,
                        Matrix4f dst)
Post-multiplies this matrix by the matrix corresponding to the specified scale transformation and stores the result in dst.

Parameters:
xScale - the amount to scale along the x-axis
yScale - the amount to scale along the y-axis
zScale - the amount to scale along the z-axis
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

set

public final void set(float[] m)
Sets the values of this matrix to those in the specified column-major array.

Parameters:
m - a 16-element array, stored in column-major format
Throws:
IllegalArgumentException - If m.length is less than 16.
NullPointerException - If m is null.
Since:
BlackBerry API 5.0.0

set

public final void set(float[] m,
                      int offset)
Sets the values of this matrix to those in the specified column-major array.

Parameters:
m - An array containing 16 elements in column-major format.
offset - The offset into the array to begin reading at.
Throws:
IllegalArgumentException - If offset is less than zero or offset + 15 is greater than or equal to m.length.
NullPointerException - If m is null.
Since:
BlackBerry API 6.0.0

set

public final void set(float m00,
                      float m01,
                      float m02,
                      float m03,
                      float m10,
                      float m11,
                      float m12,
                      float m13,
                      float m20,
                      float m21,
                      float m22,
                      float m23,
                      float m30,
                      float m31,
                      float m32,
                      float m33)
Sets the values of this matrix.

Parameters:
m00 - the first element of the first row
m01 - the second element of the first row
m02 - the third element of the first row
m03 - the fourth element of the first row
m10 - the first element of the second row
m11 - the second element of the second row
m12 - the third element of the second row
m13 - the fourth element of the second row
m20 - the first element of the third row
m21 - the second element of the third row
m22 - the third element of the third row
m23 - the fourth element of the third row
m30 - the first element of the fourth row
m31 - the second element of the fourth row
m32 - the third element of the fourth row
m33 - the fourth element of the fourth row
Since:
BlackBerry API 5.0.0

set

public final void set(Matrix4f m)
Sets the values of this matrix to those of the specified matrix.

Parameters:
m - the source matrix
Throws:
NullPointerException - If m is null.
Since:
BlackBerry API 5.0.0

set

public final void set(int index,
                      float value)
Sets the specified element of this matrix to the specified value.

Parameters:
index - the index of the element to set (0-15)
value - the value to set
Throws:
IllegalArgumentException - If index is less than zero or greater than 15.
Since:
BlackBerry API 5.0.0

set

public final void set(int row,
                      int column,
                      float value)
Sets the specified element of this matrix to the specified value.

Parameters:
row - the row of the element (0-3)
column - the column of the element (0-3)
value - the value to set
Throws:
IllegalArgumentException - If row or column is less than zero or greater than 3.
Since:
BlackBerry API 5.0.0

setIdentity

public final void setIdentity()
Sets this matrix to the identity matrix.

Since:
BlackBerry API 5.0.0

setZero

public final void setZero()
Sets all elements of the current matrix to zero.

Since:
BlackBerry API 5.0.0

subtract

public final void subtract(Matrix4f m)
Subtracts the specified matrix from the current matrix.

Parameters:
m - the matrix to subtract
Throws:
NullPointerException - If m is null.
Since:
BlackBerry API 5.0.0

subtract

public static void subtract(Matrix4f m1,
                            Matrix4f m2,
                            Matrix4f dst)
Subtracts the specified matrices and stores the result in dst.

Parameters:
m1 - the first matrix
m2 - the second matrix
dst - a matrix to store the result in
Throws:
NullPointerException - If m1, m2, or dst is null.
Since:
BlackBerry API 5.0.0

transformNormal

public final void transformNormal(Vector3f normal)
Transforms the specified normal vector by this matrix by treating the fourth (w) coordinate as zero.

The result of the transformation is stored directly into normal.

Parameters:
normal - the normal vector to transform
Throws:
NullPointerException - If normal is null.
Since:
BlackBerry API 5.0.0

transformNormal

public final void transformNormal(Vector3f normal,
                                  Vector3f dst)
Transforms the specified normal vector by this matrix by treating the fourth (w) coordinate as zero, and stores the result in dst.

Parameters:
normal - the normal vector to transform
dst - a vector to store the transformed normal in
Throws:
NullPointerException - If normal or dst is null.
Since:
BlackBerry API 5.0.0

transformPoint

public final void transformPoint(Vector3f point)
Transforms the specified point by this matrix.

The result of the transformation is stored directly into point.

Parameters:
point - the point to transform
Throws:
NullPointerException - If point is null.
Since:
BlackBerry API 5.0.0

transformPoint

public final void transformPoint(Vector3f point,
                                 Vector3f dst)
Transforms the specified point by this matrix, and stores the result in dst.

Parameters:
point - the point to transform
dst - a point to store the transformed point in
Throws:
NullPointerException - If point or dst is null.
Since:
BlackBerry API 5.0.0

transformVector

public final void transformVector(Vector3f vector)
Transforms the specified vector by this matrix.

The result of the transformation is stored directly into point.

Parameters:
vector - the vector to transform
Throws:
NullPointerException - If vector is null.
Since:
BlackBerry API 6.0.0

transformVector

public final void transformVector(Vector3f vector,
                                  Vector3f dst)
Transforms the specified vector by this matrix, and stores the result in dst.

Parameters:
vector - the vector to transform
dst - a vector to store the transformed vector in
Throws:
NullPointerException - If vector or dst is null.
Since:
BlackBerry API 6.0.0

translate

public final void translate(float x,
                            float y,
                            float z)
Post-multiplies this matrix by the matrix corresponding to the specified translation.

Parameters:
x - amount to translate along the x-axis
y - amount to translate along the y-axis
z - amount to translate along the z-axis
Since:
BlackBerry API 5.0.0

translate

public final void translate(float x,
                            float y,
                            float z,
                            Matrix4f dst)
Post-multiplies this matrix by the matrix corresponding to the specified translation and stores the result in dst.

Parameters:
x - amount to translate along the x-axis
y - amount to translate along the y-axis
z - amount to translate along the z-axis
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

transpose

public final void transpose()
Transposes this matrix.

Since:
BlackBerry API 5.0.0

transpose

public final void transpose(Matrix4f dst)
Gets the transpose of this matrix in dst.

Parameters:
dst - a matrix to store the transpose in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

createBillboard

public static void createBillboard(Vector3f object,
                                   Vector3f cameraPos,
                                   Vector3f cameraUpVector,
                                   Vector3f cameraForwardVector,
                                   Matrix4f dst)
Creates a spherical billboard that rotates around a specified object position.

Parameters:
object - The position of the object
cameraPos - The position of the camera
cameraUpVector - The vector describing the "up" direction of the camera
cameraForwardVector - The optional forward vector of the camera. May be null.
dst - A matrix to store the result in
Throws:
NullPointerException - If object, cameraPos, cameraUpVector or dst is null.
Since:
BlackBerry API 7.0.0

createScale

public static void createScale(float xScale,
                               float yScale,
                               float zScale,
                               Matrix4f dst)
Creates a scale matrix.

Parameters:
xScale - the scale on the x-axis
yScale - the scale on the y-axis
zScale - the scale on the z-axis
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

createTranslation

public static void createTranslation(float xTrans,
                                     float yTrans,
                                     float zTrans,
                                     Matrix4f dst)
Creates a translation matrix.

Parameters:
xTrans - the translation on the x-axis
yTrans - the translation on the y-axis
zTrans - the translation on the z-axis
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

createRotation

public static void createRotation(Quaternion4f quat,
                                  Matrix4f dst)
Creates a rotation matrix from the specified quaternion.

Parameters:
quat - a quaternion describing a 3D orientation
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

createRotation

public static void createRotation(Vector3f axis,
                                  float angle,
                                  Matrix4f dst)
Creates a rotation matrix from the specified axis and angle.

Parameters:
axis - a vector describing the axis to rotate about
angle - the angle, in radians
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

createRotationX

public static void createRotationX(float angle,
                                   Matrix4f dst)
Creates a matrix describing a rotation around the x-axis.

Parameters:
angle - the angle of rotation, in radians
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

createRotationY

public static void createRotationY(float angle,
                                   Matrix4f dst)
Creates a matrix describing a rotation around the y-axis.

Parameters:
angle - the angle of rotation, in radians
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

createRotationZ

public static void createRotationZ(float angle,
                                   Matrix4f dst)
Creates a matrix describing a rotation around the z-axis.

Parameters:
angle - the angle of rotation, in radians
dst - a matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 5.0.0

createLookAt

public static void createLookAt(Vector3f cameraPos,
                                Vector3f cameraTarget,
                                Vector3f cameraUpVector,
                                Matrix4f dst)
Creates a view matrix based on the specified input parameters.

Parameters:
cameraPos - the position of the camera
cameraTarget - the position of the target that the camera is pointing at
cameraUpVector - a vector describing the "up" direction of the camera
dst - a matrix to store the result in
Throws:
NullPointerException - If cameraPos, cameraTarget, cameraUpVector, or dst is null.
Since:
BlackBerry API 5.0.0

createLookAt

public static void createLookAt(float eyeX,
                                float eyeY,
                                float eyeZ,
                                float centerX,
                                float centerY,
                                float centerZ,
                                float upX,
                                float upY,
                                float upZ,
                                float[] dst)
Creates a view matrix based on the specified input parameters.

Parameters:
eyeX - Eye X coordinate
eyeY - Eye Y coordinate
eyeZ - Eye Z coordinate
centerX - Center X coordinate
centerY - Center Y coordinate
centerZ - Center Z coordinate
upX - Up vector X value
upY - Up vector Y value
upZ - Up vector Z value
dst - A matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 7.0.0

createOrthographic

public static void createOrthographic(float left,
                                      float right,
                                      float bottom,
                                      float top,
                                      float near,
                                      float far,
                                      Matrix4f dst)
Creates an orthographic projection matrix.

Parameters:
left - The coordinate for the left vertical clipping plane
right - The coordinate for the right vertical clipping plane
bottom - The coordinate for the bottom horizontal clipping plane
top - The coordinate for the top horizontal clipping plane
near - The distance to the near clipping plane
far - The distance to the far clipping plane
dst - A matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 7.0.0

createPerspective

public static void createPerspective(float fovy,
                                     float aspect,
                                     float zNear,
                                     float zFar,
                                     Matrix4f dst)
Creates a perspective projection matrix.

Parameters:
fovy - Field of view angle in the y direction, in degrees
aspect - Aspect ratio that determines the field of view in the x direction (usually width/height)
zNear - Distance to the near clipping plane
zFar - Distance to the far clipping plane
dst - A matrix to store the result in
Throws:
NullPointerException - If dst is null.
Since:
BlackBerry API 7.0.0

createReflection

public static void createReflection(Plane plane,
                                    Matrix4f dst)
Creates a matrix that reflects the coordinate system about a plane.

Parameters:
plane - The plane to reflect about
dst - A matrix to store the result in
Throws:
NullPointerException - If plane or dst is null.
Since:
BlackBerry API 7.0.0

equals

public boolean equals(Object obj)
Determines if this matrix is equal to the specified object.

Overrides:
equals in class Object
Parameters:
obj - the matrix to compare
Returns:
true if the specified object is of type Matrix4f and if all members of it are equal those of this matrix
Throws:
NullPointerException - If obj is null.
See Also:
Boolean.hashCode(), Hashtable
Since:
BlackBerry API 5.0.0

equals

public boolean equals(Matrix4f m)
Determines if this matrix is equal to the specified one.

Parameters:
m - the matrix to compare
Returns:
true if all components of the specified matrix are equal to those of this matrix
Throws:
NullPointerException - If m is null.
Since:
BlackBerry API 5.0.0

hashCode

public int hashCode()
Returns the hash code of the matrix, based on the values stored in it.

Overrides:
hashCode in class Object
Returns:
the hash code
See Also:
Object.equals(java.lang.Object), Hashtable
Since:
BlackBerry API 5.0.0

toString

public String toString()
Returns a string representation of this matrix.

Overrides:
toString in class Object
Returns:
a string containing the elements of the matrix
Since:
BlackBerry API 5.0.0



Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal