|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.math.Matrix3f
public class Matrix3f
Defines a 3 x 3 floating point matrix representing a 2D transformation.
Vectors are treated as columns, resulting in a matrix that is represented as follows, where x and y are the translation components of the matrix:
1 0 x 0 1 y 0 0 1
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 OpenVG is a simple and efficient operation since the underlying array for the matrix is stored in a format that is directly compatible with OpenVG.
// Create a matrix to translate by (10, -2)
Matrix3f translation =new
Matrix3f(); translation.set(1, 0, 10, 0, 1, -2, 0, 0, 1 );// Pass our matrix to OpenVG
vg.vgLoadMatrix(translation.getArray());
Note: In the case of repeated local transformations (i.e. rotate by 0.76 radians,
then translate by 2.1 along the X-axis, then ...), it is better to use Transform2D
(which is optimized for that kind of usage).
Transform2D
Constructor Summary | ||
---|---|---|
Matrix3f()
Constructs a matrix initialized to the identity matrix. |
||
Matrix3f(float m00,
float m01,
float m02,
float m10,
float m11,
float m12,
float m20,
float m21,
float m22)
Constructs a matrix initialized to the specified values. |
||
Matrix3f(float[] m)
Constructs a matrix initialized to the specified column-major array. |
||
Matrix3f(float[] m,
int offset)
Constructs a matrix initialized to the specified column-major array. |
||
Matrix3f(Matrix3f 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,
Matrix3f dst)
Adds a scalar value to this matrix and stores the result in dst . |
|
void |
add(Matrix3f m)
Adds the specified matrix to this matrix. |
|
static void |
add(Matrix3f m1,
Matrix3f m2,
Matrix3f dst)
Adds the specified matrices and stores the result in dst . |
|
static void |
createRotation(float x,
float y,
float angle,
Matrix3f dst)
Creates a rotation matrix from the specified center of rotation and angle. |
|
static void |
createRotation(float angle,
Matrix3f dst)
Creates a rotation matrix from the specified angle. |
|
static void |
createScale(float xScale,
float yScale,
Matrix3f dst)
Creates a scale matrix. |
|
static void |
createShear(float xAngle,
float yAngle,
Matrix3f dst)
Creates a shear matrix. |
|
static void |
createTranslation(float xTrans,
float yTrans,
Matrix3f dst)
Creates a translation matrix. |
|
boolean |
decompose(Vector2f scale,
Vector2f shear,
Matrix3f rotation,
Vector2f translation)
Decomposes the scale, shear, 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(Matrix3f 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 three elements of the specified column into v . |
|
void |
getColumn(int column,
Vector2f v)
Gets the first two elements of the specified column into v . |
|
boolean |
getRotation(Matrix3f rotation)
Gets the rotational component of this matrix in the specified matrix. |
|
void |
getRow(int row,
float[] v)
Gets the three elements of the specified row into v . |
|
void |
getRow(int row,
Vector2f v)
Gets the first two elements of the specified row into v . |
|
void |
getScale(Vector2f scale)
Gets the scale components of this matrix in a scale Matrix3f. |
|
void |
getShear(Vector2f shear)
Gets the shear component of this matrix in a Vector2f. |
|
void |
getTranslation(Vector2f translation)
Gets the translational component of this matrix in a Vector2f. |
|
int |
hashCode()
Returns the hash code of the matrix, based on the values stored in it. |
|
boolean |
invert()
Inverts this matrix. |
|
boolean |
invert(Matrix3f dst)
Inverts this matrix and stores the result in dst . |
|
boolean |
isIdentity()
Determines if this matrix is the identity matrix. |
|
void |
multiply(float scalar)
Multiplies the components of this matrix by the specified scalar. |
|
void |
multiply(float scalar,
Matrix3f dst)
Multiplies the components of this matrix by a scalar and stores the result in dst . |
|
void |
multiply(Matrix3f m)
Multiplies this matrix by the specified matrix. |
|
static void |
multiply(Matrix3f m1,
Matrix3f m2,
Matrix3f dst)
Multiplies matrix m1 by m2 and stores the result in dst . |
|
void |
negate()
Negates this matrix. |
|
void |
negate(Matrix3f dst)
Gets the negate of this matrix in matrix dst . |
|
void |
rotate(float angle)
Post-multiplies this matrix by the matrix corresponding to the specified rotation about the origin. |
|
void |
rotate(float x,
float y,
float angle)
Post-multiplies this matrix by the matrix corresponding to the specified rotation about the given point. |
|
void |
rotate(float x,
float y,
float angle,
Matrix3f dst)
Post-multiplies this matrix by the matrix corresponding to the specified rotation about the given point, and stores the result in matrix dst . |
|
void |
rotate(float angle,
Matrix3f dst)
Post-multiplies this matrix by the matrix corresponding to the specified rotation about the origin, and stores the result in matrix dst . |
|
void |
scale(float value)
Post-multiplies this matrix by the matrix corresponding to the specified scale transformation. |
|
void |
scale(float xScale,
float yScale)
Post-multiplies this matrix by the matrix corresponding to the specified scale transformation. |
|
void |
scale(float xScale,
float yScale,
Matrix3f dst)
Post-multiplies this matrix by the matrix corresponding to the specified scale transformation and stores the result in matrix dst . |
|
void |
scale(float value,
Matrix3f dst)
Post-multiplies this matrix by the matrix corresponding to the specified scale transformation and stores the result in matrix dst . |
|
void |
set(float m00,
float m01,
float m02,
float m10,
float m11,
float m12,
float m20,
float m21,
float m22)
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(Matrix3f 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(Matrix3f m)
Subtracts the specified matrix from the current matrix. |
|
static void |
subtract(Matrix3f m1,
Matrix3f m2,
Matrix3f dst)
Subtracts the specified matrices, and stores the result in matrix dst . |
|
String |
toString()
Returns a string representation of this matrix. |
|
void |
transformPoint(Vector2f point)
Transforms the specified point by this matrix. |
|
void |
transformPoint(Vector2f point,
Vector2f dst)
Transforms the specified point by this matrix, and stores the result in matrix dst . |
|
void |
transformVector(Vector2f vector)
Transforms the specified vector by this matrix. |
|
void |
transformVector(Vector2f vector,
Vector2f dst)
Transforms the specified vector by this matrix, and stores the result in dst . |
|
void |
translate(float x,
float y)
Post-multiplies this matrix by the matrix corresponding to the specified translation. |
|
void |
translate(float x,
float y,
Matrix3f dst)
Post-multiplies this matrix by the matrix corresponding to the specified translation and stores the result in matrix dst . |
|
void |
transpose()
Transposes this matrix. |
|
void |
transpose(Matrix3f dst)
Gets the transpose of this matrix in dst . |
Methods inherited from class java.lang.Object |
---|
getClass, notify, notifyAll, wait, wait, wait |
Constructor Detail |
---|
public Matrix3f()
public Matrix3f(float[] m)
The passed in array is in column-major order, so the memory layout of the array is as follows:
0 3 6 1 4 7 2 5 8
m
- a 9-element array, stored in column-major order.
IllegalArgumentException
- If m.length is less than 9.
NullPointerException
- If m
is null
.- Since:
- BlackBerry API 6.0.0
public Matrix3f(float[] m, int offset)
The passed in array is in column-major order, so the memory layout of the array is as follows:
0 3 6 1 4 7 2 5 8
m
- An array containing 9 elements in column-major order.offset
- The offset into the array to begin reading at.
IllegalArgumentException
- If offset
is less than zero or
offset + 8
is greater than or equal to m.length
.
NullPointerException
- If m
is null
.public Matrix3f(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22)
m00
- the first element of the first row.m01
- the second element of the first row.m02
- the third 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.m20
- the first element of the third row.m21
- the second element of the third row.m22
- the third element of the third row.public Matrix3f(Matrix3f m)
m
- the source matrix.
NullPointerException
- If m
is null
.Method Detail |
---|
public final void add(float scalar)
scalar
- the scalar to add.public final void add(float scalar, Matrix3f dst)
dst
.
scalar
- the scalar value to add.dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public final void add(Matrix3f m)
m
- the matrix to add.
NullPointerException
- If m
is null
.public static void add(Matrix3f m1, Matrix3f m2, Matrix3f dst)
dst
.
m1
- the first matrix.m2
- the second matrix.dst
- a matrix to store the result in.
NullPointerException
- If m1
, m2
, or dst
is null
.public final boolean decompose(Vector2f scale, Vector2f shear, Matrix3f rotation, Vector2f translation)
scale
- a vector to store the decomposed scale values inshear
- a vector to store the decomposed shear values inrotation
- a matrix to store the decomposed rotation intranslation
- a vector to store the decomposed translation in
NullPointerException
- If scale
, shear
, rotation
, or translation
is null
.public final float determinant()
public final void get(float[] m)
m
- a 9-element array to populate with the values from this matrix
IllegalArgumentException
- If m.length
is less than 9.
NullPointerException
- If m
is null
.public final float get(int index)
This method indexes the internal array in column-major order. See the description of this class for more information on this topic.
index
- the zero-based index of the element to retrieve.
IllegalArgumentException
- If index
is less than zero or greater than 8.public final float get(int row, int column)
row
- the zero-based row of the element to retrieve.column
- the zero-based column of the element to retrieve.
IllegalArgumentException
- If row
or column
is less than zero or greater than 2.public final float[] getArray()
The returned array is in column-major order and therefore compatible with systems such as OpenVG that expect data in this order. The memory layout of the array is therefore as follows:
0 3 6 1 4 7 2 5 8
Note that modifying the elements of the returned array will modify the matrix itself.
public final void getColumn(int column, float[] v)
v
.
column
- the index of the column to retrieve (zero-based).v
- a three-element array to store the column in.
IllegalArgumentException
- If column
is less than zero or greater than 2.
IllegalArgumentException
- If v.length
is less than 3.
NullPointerException
- If v
is null
.public final void getColumn(int column, Vector2f v)
v
.
column
- the index of the column to retrieve (zero-based).v
- a vector to store the column in.
IllegalArgumentException
- If column
is less than zero or greater than 2.
NullPointerException
- If v
is null
.public final void getRow(int row, float[] v)
v
.
row
- the index of the row to retrieve (zero-based).v
- a three-element array to store the row in.
IllegalArgumentException
- If row
is less than zero or greater than 2.
IllegalArgumentException
- If v.length
is less than 3.
NullPointerException
- If v
is null
.public final void getRow(int row, Vector2f v)
v
.
row
- the index of the row to retrieve (zero-based).v
- a vector to store the row in.
IllegalArgumentException
- If row
is less than zero or greater than 2.
NullPointerException
- If v
is null
.public final void getScale(Vector2f scale)
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.
scale
- a Vector2f
storing the scale transformation.
NullPointerException
- If scale
is null
.public final void getShear(Vector2f shear)
shear
- a Vector2f
storing the horizontal and vertical shear.
NullPointerException
- If scale
is null
.public final boolean getRotation(Matrix3f rotation)
rotation
- a matrix to receive the rotation
NullPointerException
- If rotation
is null
.public final void getTranslation(Vector2f translation)
translation
- a Matrix3f storing the translation matrix.
NullPointerException
- If translation
is null
.public final boolean invert()
true
if the this Matrix3f
is invertible, false
otherwise.public final boolean invert(Matrix3f dst)
dst
.
dst
- a matrix to store the invert of this matrix in.
true
if this matrix is invertible; false
otherwise.
NullPointerException
- If dst
is null
.public final boolean isIdentity()
true
if this matrix is the identity matrix; false
otherwise.public final void multiply(float scalar)
scalar
- the scalar value.public final void multiply(float scalar, Matrix3f dst)
dst
.
scalar
- the scalar value.dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public final void multiply(Matrix3f m)
m
- the matrix to multiply.
NullPointerException
- if m
is null
.public static void multiply(Matrix3f m1, Matrix3f m2, Matrix3f dst)
m1
by m2
and stores the result in dst
.
m1
- the first matrix.m2
- the second matrix.dst
- a matrix to store the result of m1 * m2
.
NullPointerException
- If m1
, m2
, or dst
is null
.public final void negate()
public final void negate(Matrix3f dst)
dst
.
dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public final void rotate(float angle)
angle
- the angle, in radians.public final void rotate(float x, float y, float angle)
x
- the x-coordinate of the center of rotation.y
- the y-coordinate of the center of rotation.angle
- the angle, in radians.public final void rotate(float angle, Matrix3f dst)
dst
.
angle
- the angle, in radians.dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public final void rotate(float x, float y, float angle, Matrix3f dst)
dst
.
x
- the x-coordinate of the center of rotation.y
- the y-coordinate of the center of rotation.angle
- the angle, in radians.dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public final void scale(float value)
value
- the amount to scale along all axes.public final void scale(float value, Matrix3f dst)
dst
.
value
- the amount to scale along all axes.dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public final void scale(float xScale, float yScale)
xScale
- the amount to scale along the x-axis.yScale
- the amount to scale along the y-axis.public final void scale(float xScale, float yScale, Matrix3f dst)
dst
.
xScale
- the amount to scale along the x-axis.yScale
- the amount to scale along the y-axis.dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public final void set(float[] m)
m
- a 9-element array, stored in column-major format.
IllegalArgumentException
- If m.length is less than 9.
NullPointerException
- If m
is null
.- Since:
- BlackBerry API 6.0.0
public final void set(float[] m, int offset)
m
- An array containing 9 elements in column-major format.offset
- The offset into the array to begin reading at.
IllegalArgumentException
- If offset
is less than zero or
offset + 8
is greater than or equal to m.length
.
NullPointerException
- If m
is null
.public final void set(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22)
m00
- the first element of the first row.m01
- the second element of the first row.m02
- the third 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.m20
- the first element of the third row.m21
- the second element of the third row.m22
- the third element of the third row.public final void set(Matrix3f m)
m
- the source matrix.
NullPointerException
- If m
is null
.public final void set(int index, float value)
index
- the index of the element to set (0-8).value
- the value to set.
IllegalArgumentException
- If index
is less than zero or greater than 8.public final void set(int row, int column, float value)
row
- the row of the element (0-2).column
- the column of the element (0-2).value
- the value to set
IllegalArgumentException
- If row
or column
is less than zero or greater than 2.public final void setIdentity()
public final void setZero()
public final void subtract(Matrix3f m)
m
- the matrix to subtract.
NullPointerException
- If m
is null
.public static void subtract(Matrix3f m1, Matrix3f m2, Matrix3f dst)
dst
.
m1
- the first matrix.m2
- the second matrix.dst
- a matrix which stores m1 - m2
.
NullPointerException
- If m1
, m2
, or dst
is null
.public final void transformPoint(Vector2f point)
The result of the transformation is stored directly into point
.
point
- the point to transform.
NullPointerException
- If point
is null
.public final void transformPoint(Vector2f point, Vector2f dst)
dst
.
point
- the point to transform.dst
- a point to store the transformed point in.
NullPointerException
- If point
or dst
is null
.public final void transformVector(Vector2f vector)
The result of the transformation is stored directly into vector
.
vector
- the vector to transform.
NullPointerException
- If vector
is null
.public final void transformVector(Vector2f vector, Vector2f dst)
dst
.
vector
- the vector to transform.dst
- a vector to store the transformed vector in.
NullPointerException
- If vector
or dst
is null
.public final void translate(float x, float y)
x
- amount to translate along the x-axis.y
- amount to translate along the y-axis.public final void translate(float x, float y, Matrix3f dst)
dst
.
x
- amount to translate along the x-axis.y
- amount to translate along the y-axis.dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public final void transpose()
public final void transpose(Matrix3f dst)
dst
.
dst
- a matrix to store the transpose in
NullPointerException
- If dst
is null
.public static void createScale(float xScale, float yScale, Matrix3f dst)
xScale
- the scale on the x-axis.yScale
- the scale on the y-axis.dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public static void createShear(float xAngle, float yAngle, Matrix3f dst)
xAngle
- the angle of shear in the x direction, in radians.yAngle
- the angle of shear in the y direction, in radians.dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public static void createTranslation(float xTrans, float yTrans, Matrix3f dst)
xTrans
- the translation on the x-axis.yTrans
- the translation on the y-axis.dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public static void createRotation(float angle, Matrix3f dst)
angle
- the angle, in radians.dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public static void createRotation(float x, float y, float angle, Matrix3f dst)
x
- the x-coordinate of the center of rotation.y
- the y-coordinate of the center of rotation.angle
- the angle, in radians.dst
- a matrix to store the result in.
NullPointerException
- If dst
is null
.public boolean equals(Object obj)
equals
in class Object
obj
- the matrix to compare
true
if the specified object is of type
Matrix3f
and if the elements are pairwise equal.
NullPointerException
- If obj
is null
.Boolean.hashCode()
,
Hashtable
public boolean equals(Matrix3f m)
m
- the matrix to compare.
true
if all components of the specified matrix are equal to those of this matrix.
NullPointerException
- If m
is null
.public int hashCode()
hashCode
in class Object
Object.equals(java.lang.Object)
,
Hashtable
public String toString()
toString
in class Object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.