Package com.jme3.math

Class Matrix3f

java.lang.Object

com.jme3.math.Matrix3f

All Implemented Interfaces:

Savable, Serializable, Cloneable

public final class Matrix3f
extends Object
implements Savable, Cloneable, Serializable

A 3x3 matrix composed of 9 single-precision elements, used to represent linear transformations of 3-D coordinates, such as rotations, reflections, and scaling.

Element numbering is (row, column), so m01 is the element in row 0, column 1.

For pure rotations, the Quaternion class provides a more efficient representation.

With one exception, the methods with names ending in "Local" modify the current instance. They are used to avoid creating garbage.

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final Matrix3f	IDENTITY	Shared instance of the identity matrix (diagonals = 1, other elements = 0).
protected float	m00	The element in row 0, column 0.
protected float	m01	The element in row 0, column 1.
protected float	m02	The element in row 0, column 2.
protected float	m10	The element in row 1, column 0.
protected float	m11	The element in row 1, column 1.
protected float	m12	The element in row 1, column 2.
protected float	m20	The element in row 2, column 0.
protected float	m21	The element in row 2, column 1.
protected float	m22	The element in row 2, column 2.
static final Matrix3f	ZERO	Shared instance of the all-zero matrix.

Constructor Summary

Constructors

Constructor	Description
Matrix3f()	Instantiates an identity matrix (diagonals = 1, other elements = 0).
Matrix3f(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22)	Instantiates a matrix with specified elements.
Matrix3f(Matrix3f mat)	Instantiates a copy of the matrix argument.

Method Summary

Modifier and Type	Method	Description
void	absoluteLocal()	Replaces all 9 elements with their absolute values.
Matrix3f	adjoint()	Returns the adjoint as a new matrix.
Matrix3f	adjoint(Matrix3f store)	Returns the adjoint in the specified storage.
Matrix3f	clone()	Creates a copy.
float	determinant()	Returns the determinant.
boolean	equals(Object o)	Tests for exact equality with the argument, distinguishing -0 from 0.
void	fillFloatArray(float[] f, boolean columnMajor)	Copies the matrix to the 1st 9 elements of the specified array.
FloatBuffer	fillFloatBuffer(FloatBuffer fb, boolean columnMajor)	Copies the matrix to the specified FloatBuffer, starting at its current position.
void	fromAngleAxis(float angle, Vector3f axis)	Sets all 9 elements to form a pure rotation matrix with the specified rotation angle and axis of rotation.
void	fromAngleNormalAxis(float angle, Vector3f axis)	Sets all 9 elements to form a rotation matrix with the specified rotation angle and normalized axis of rotation.
void	fromAxes(Vector3f uAxis, Vector3f vAxis, Vector3f wAxis)	Configures from the specified column vectors.
void	fromStartEndVectors(Vector3f start, Vector3f end)	Configures a rotation matrix that rotates the specified start direction to the specified end direction.
void	get(float[] data, boolean rowMajor)	Copies the matrix to the specified array.
float	get(int i, int j)	Returns the element at the specified position.
Vector3f	getColumn(int i)	Returns the specified column.
Vector3f	getColumn(int i, Vector3f store)	Returns the specified column.
Vector3f	getRow(int i)	Returns the specified row.
Vector3f	getRow(int i, Vector3f store)	Returns the specified row.
int	hashCode()	Returns a hash code.
Matrix3f	invert()	Returns the multiplicative inverse as a new matrix.
Matrix3f	invert(Matrix3f store)	Returns the multiplicative inverse in the specified storage.
Matrix3f	invertLocal()	Inverts the matrix and returns the (modified) current instance.
boolean	isIdentity()	Tests for exact identity.
void	loadIdentity()	Configures as an identity matrix (diagonals = 1, other elements = 0).
Matrix3f	mult(Matrix3f mat)	Multiplies with the argument matrix and returns the product as a new instance.
Matrix3f	mult(Matrix3f mat, Matrix3f product)	Multiplies with the specified matrix and returns the product in a 3rd matrix.
Vector3f	mult(Vector3f vec)	Applies the linear transformation to the vector argument and returns the result as a new vector.
Vector3f	mult(Vector3f vec, Vector3f product)	Applies the linear transformation to specified vector and stores the result in another vector.
Matrix3f	multLocal(float scale)	Multiplies by the scalar argument and returns the (modified) current instance.
Matrix3f	multLocal(Matrix3f mat)	Multiplies by the matrix argument and returns the (modified) current instance.
Vector3f	multLocal(Vector3f vec)	Applies the linear transformation to the vector argument and returns the (modified) argument.
Matrix3f	normalize(Matrix3f store)	Normalizes the matrix and returns the result in the argument.
Matrix3f	normalizeLocal()	Normalizes the matrix and returns the (modified) current instance.
void	read(JmeImporter importer)	De-serializes from the specified importer, for example when loading from a J3O file.
void	scale(Vector3f scale)	Scales each column by the corresponding element of the argument.
Matrix3f	set(float[] matrix)	Copies all 9 elements from the array argument, in row-major order.
Matrix3f	set(float[][] matrix)	Copies all 9 elements from the specified 2-dimensional array.
Matrix3f	set(float[] matrix, boolean rowMajor)	Copies all 9 elements from the specified array.
Matrix3f	set(int i, int j, float value)	Sets the specified element.
Matrix3f	set(Matrix3f matrix)	Copies the matrix argument.
Matrix3f	set(Quaternion quaternion)	Configures as a rotation matrix equivalent to the argument.
Matrix3f	setColumn(int i, Vector3f column)	Sets the specified column.
Matrix3f	setRow(int i, Vector3f row)	Sets the specified row.
FloatBuffer	toFloatBuffer()	Copies the matrix to a new FloatBuffer.
String	toString()	Returns a string representation of the matrix, which is unaffected.
Matrix3f	transpose()	Transposes the matrix and returns the (modified) current instance.
Matrix3f	transposeLocal()	Transposes the matrix and returns the (modified) current instance.
Matrix3f	transposeNew()	Returns the transpose as a new instance.
void	write(JmeExporter e)	Serializes to the specified exporter, for example when saving to a J3O file.
Matrix3f	zero()	Sets all elements to zero.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

m00

protected float m00

The element in row 0, column 0.

m01

protected float m01

The element in row 0, column 1.

m02

protected float m02

The element in row 0, column 2.

m10

protected float m10

The element in row 1, column 0.

m11

protected float m11

The element in row 1, column 1.

m12

protected float m12

The element in row 1, column 2.

m20

protected float m20

The element in row 2, column 0.

m21

protected float m21

The element in row 2, column 1.

m22

protected float m22

The element in row 2, column 2.

ZERO

public static final Matrix3f ZERO

Shared instance of the all-zero matrix. Do not modify!

IDENTITY

public static final Matrix3f IDENTITY

Shared instance of the identity matrix (diagonals = 1, other elements = 0). Do not modify!

Constructor Details

Matrix3f

public Matrix3f()

Instantiates an identity matrix (diagonals = 1, other elements = 0).

Matrix3f

public Matrix3f(float m00,
 float m01,
 float m02,
 float m10,
 float m11,
 float m12,
 float m20,
 float m21,
 float m22)

Instantiates a matrix with specified elements.

Parameters:

m00 - the desired value for row 0, column 0

m01 - the desired value for row 0, column 1

m02 - the desired value for row 0, column 2

m10 - the desired value for row 1, column 0

m11 - the desired value for row 1, column 1

m12 - the desired value for row 1, column 2

m20 - the desired value for row 2, column 0

m21 - the desired value for row 2, column 1

m22 - the desired value for row 2, column 2

Matrix3f

public Matrix3f(Matrix3f mat)

Instantiates a copy of the matrix argument. If the argument is null, an identity matrix is produced.

Parameters:

mat - the matrix to copy (unaffected) or null for identity

Method Details

absoluteLocal

public void absoluteLocal()

Replaces all 9 elements with their absolute values.

set

public Matrix3f set(Matrix3f matrix)

Copies the matrix argument. If the argument is null, the current instance is set to identity (diagonals = 1, other elements = 0).

Parameters:

matrix - the matrix to copy (unaffected) or null for identity

Returns:

the (modified) current instance (for chaining)

get

public float get(int i,
 int j)

Returns the element at the specified position. The matrix is unaffected.

Parameters:

i - the row index (0, 1, or 2)

j - the column index (0, 1, or 2)

Returns:

the value of the element at (i, j)

Throws:

IllegalArgumentException - if either index isn't 0, 1, or 2

get

public void get(float[] data,
 boolean rowMajor)

Copies the matrix to the specified array. The matrix is unaffected.

If the array has 16 elements, then the matrix is treated as if it contained the 1st 3 rows and 1st 3 columns of a 4x4 matrix.

Parameters:

data - storage for the elements (not null, length=9 or 16)

rowMajor - true to store the elements in row-major order (m00, m01, ...) or false to store them in column-major order (m00, m10, ...)

Throws:

IndexOutOfBoundsException - if data doesn't have 9 or 16 elements

See Also:

• fillFloatArray(float[], boolean)

normalize

public Matrix3f normalize(Matrix3f store)

Normalizes the matrix and returns the result in the argument. The current instance is unaffected, unless it's store.

Parameters:

store - storage for the result, or null for a new Matrix3f

Returns:

either store or a new Matrix3f

normalizeLocal

public Matrix3f normalizeLocal()

Normalizes the matrix and returns the (modified) current instance.

Returns:

the (modified) current instance (for chaining)

getColumn

public Vector3f getColumn(int i)

Returns the specified column. The matrix is unaffected.

If the matrix is a pure rotation, each column contains one of the basis vectors.

Parameters:

i - the column index (0, 1, or 2)

Returns:

a new Vector3f

Throws:

IllegalArgumentException - if i isn't 0, 1, or 2

See Also:

• Quaternion.getRotationColumn(int)

getColumn

public Vector3f getColumn(int i,
 Vector3f store)

Returns the specified column. The matrix is unaffected.

If the matrix is a pure rotation, each column contains one of the basis vectors.

Parameters:

i - the column index (0, 1, or 2)

store - storage for the result, or null for a new Vector3f

Returns:

either store or a new Vector3f

Throws:

IllegalArgumentException - if i isn't 0, 1, or 2

See Also:

• Quaternion.getRotationColumn(int, com.jme3.math.Vector3f)

getRow

public Vector3f getRow(int i)

Returns the specified row. The matrix is unaffected.

Parameters:

i - the row index (0, 1, or 2)

Returns:

a new Vector3f

Throws:

IllegalArgumentException - if i isn't 0, 1, or 2

getRow

public Vector3f getRow(int i,
 Vector3f store)

Returns the specified row. The matrix is unaffected.

Parameters:

i - the row index (0, 1, or 2)

store - storage for the result, or null for a new Vector3f

Returns:

either store or a new Vector3f

Throws:

IllegalArgumentException - if i isn't 0, 1, or 2

toFloatBuffer

public FloatBuffer toFloatBuffer()

Copies the matrix to a new FloatBuffer. The matrix is unaffected.

Returns:

a new, rewound FloatBuffer containing all 9 elements in row-major order (m00, m01, ...)

fillFloatBuffer

public FloatBuffer fillFloatBuffer(FloatBuffer fb,
 boolean columnMajor)

Copies the matrix to the specified FloatBuffer, starting at its current position. The matrix is unaffected.

Parameters:

fb - storage for the elements (not null, must have space to put 9 more floats)

columnMajor - true to store the elements in column-major order (m00, m10, ...) or false to store them in row-major order (m00, m01, ...)

Returns:

fb, its position advanced by 9

fillFloatArray

public void fillFloatArray(float[] f,
 boolean columnMajor)

Copies the matrix to the 1st 9 elements of the specified array. The matrix is unaffected.

Parameters:

f - storage for the elements (not null, length≥9)

columnMajor - true to store the elements in column-major order (m00, m10, ...) or false to store them in row-major order (m00, m01, ...)

See Also:

• get(float[], boolean)

setColumn

public Matrix3f setColumn(int i,
 Vector3f column)

Sets the specified column.

Parameters:

i - which column to set (0, 1, or 2)

column - the desired element values (unaffected) or null for none

Returns:

the (modified) current instance (for chaining)

Throws:

IllegalArgumentException - if i isn't 0, 1, or 2

setRow

public Matrix3f setRow(int i,
 Vector3f row)

Sets the specified row.

Parameters:

i - which row to set (0, 1, or 2)

row - the desired element values (unaffected) or null for none

Returns:

the (modified) current instance (for chaining)

Throws:

IllegalArgumentException - if i isn't 0, 1, or 2

set

public Matrix3f set(int i,
 int j,
 float value)

Sets the specified element.

Parameters:

i - the row index (0, 1, or 2)

j - the column index (0, 1, or 2)

value - desired value for the element at (i, j)

Returns:

the (modified) current instance (for chaining)

Throws:

IllegalArgumentException - if either index isn't 0, 1, or 2

set

public Matrix3f set(float[][] matrix)

Copies all 9 elements from the specified 2-dimensional array.

Parameters:

matrix - the input array (not null, length=3, the first element having length=3, the other elements having length≥3, unaffected)

Returns:

the (modified) current instance (for chaining)

Throws:

IllegalArgumentException - if the array is the wrong size

fromAxes

public void fromAxes(Vector3f uAxis,
 Vector3f vAxis,
 Vector3f wAxis)

Configures from the specified column vectors. If the vectors form an orthonormal basis, the result will be a pure rotation matrix.

Parameters:

uAxis - the desired value for column 0 (not null, unaffected)

vAxis - the desired value for column 1 (not null, unaffected)

wAxis - the desired value for column 2 (not null, unaffected)

See Also:

• Quaternion.fromAxes(com.jme3.math.Vector3f[])

set

public Matrix3f set(float[] matrix)

Copies all 9 elements from the array argument, in row-major order.

Parameters:

matrix - the input array (not null, length=9, unaffected)

Returns:

the (modified) current instance (for chaining)

Throws:

IllegalArgumentException - if the array has length != 9

set

public Matrix3f set(float[] matrix,
 boolean rowMajor)

Copies all 9 elements from the specified array.

Parameters:

matrix - the input array (not null, length=9, unaffected)

rowMajor - true to read the elements in row-major order (m00, m01, ...) or false to read them in column-major order (m00, m10, ...)

Returns:

the (modified) current instance (for chaining)

Throws:

IllegalArgumentException - if the array has length != 9

set

public Matrix3f set(Quaternion quaternion)

Configures as a rotation matrix equivalent to the argument.

Parameters:

quaternion - the input quaternion (not null, unaffected)

Returns:

the (modified) current instance (for chaining)

loadIdentity

public void loadIdentity()

Configures as an identity matrix (diagonals = 1, other elements = 0).

isIdentity

public boolean isIdentity()

Tests for exact identity. The matrix is unaffected.

Returns:

true if all diagonals = 1 and all other elements = 0 or -0, otherwise false

fromAngleAxis

public void fromAngleAxis(float angle,
 Vector3f axis)

Sets all 9 elements to form a pure rotation matrix with the specified rotation angle and axis of rotation. This method creates garbage, so use fromAngleNormalAxis(float, com.jme3.math.Vector3f) if the axis is known to be normalized.

Parameters:

angle - the desired rotation angle (in radians)

axis - the desired axis of rotation (not null, unaffected)

fromAngleNormalAxis

public void fromAngleNormalAxis(float angle,
 Vector3f axis)

Sets all 9 elements to form a rotation matrix with the specified rotation angle and normalized axis of rotation. If the axis might not be normalized, use fromAngleAxis(float, com.jme3.math.Vector3f) instead.

Parameters:

angle - the desired rotation angle (in radians)

axis - the desired axis of rotation (not null, length=1, unaffected)

mult

public Matrix3f mult(Matrix3f mat)

Multiplies with the argument matrix and returns the product as a new instance. The current instance is unaffected.

Note that matrix multiplication is noncommutative, so generally q * p != p * q.

Parameters:

mat - the right factor (not null, unaffected)

Returns:

this times mat (a new Matrix3f)

mult

public Matrix3f mult(Matrix3f mat,
 Matrix3f product)

Multiplies with the specified matrix and returns the product in a 3rd matrix. The current instance is unaffected unless it's product.

Note that matrix multiplication is noncommutative, so generally q * p != p * q.

It is safe for mat and product to be the same object.

Parameters:

mat - the right factor (not null, unaffected unless it's product)

product - storage for the product, or null for a new Matrix3f

Returns:

this times mat (either product or a new Matrix3f)

mult

public Vector3f mult(Vector3f vec)

Applies the linear transformation to the vector argument and returns the result as a new vector. The matrix is unaffected.

This can also be described as multiplying the matrix by a column vector.

Parameters:

vec - the coordinates to transform (not null, unaffected)

Returns:

a new Vector3f

mult

public Vector3f mult(Vector3f vec,
 Vector3f product)

Applies the linear transformation to specified vector and stores the result in another vector. The matrix is unaffected.

This can also be described as multiplying the matrix by a column vector.

It is safe for vec and product to be the same object.

Parameters:

vec - the coordinates to transform (not null, unaffected unless it's product)

product - storage for the result, or null for a new Vector3f

Returns:

either product or a new Vector3f

multLocal

public Matrix3f multLocal(float scale)

Multiplies by the scalar argument and returns the (modified) current instance.

Parameters:

scale - the scaling factor

Returns:

the (modified) current instance (for chaining)

multLocal

public Vector3f multLocal(Vector3f vec)

Applies the linear transformation to the vector argument and returns the (modified) argument. If the argument is null, null is returned.

Despite the name, the current instance is unaffected.

Parameters:

vec - the vector to transform (modified if not null)

Returns:

vec or null

multLocal

public Matrix3f multLocal(Matrix3f mat)

Multiplies by the matrix argument and returns the (modified) current instance.

Note that matrix multiplication is noncommutative, so generally q * p != p * q.

Parameters:

mat - the right factor (not null, unaffected unless it's this)

Returns:

the (modified) current instance

transposeLocal

public Matrix3f transposeLocal()

Transposes the matrix and returns the (modified) current instance.

Returns:

the (modified) current instance

invert

public Matrix3f invert()

Returns the multiplicative inverse as a new matrix. If the current instance is singular, an all-zero matrix is returned. In either case, the current instance is unaffected.

Returns:

a new Matrix3f

invert

public Matrix3f invert(Matrix3f store)

Returns the multiplicative inverse in the specified storage. If the current instance is singular, an all-zero matrix is returned. In either case, the current instance is unaffected.

If this and store are the same object, the result is undefined. Use invertLocal() instead.

Parameters:

store - storage for the result, or null for a new Matrix3f

Returns:

either store or a new Matrix3f

invertLocal

public Matrix3f invertLocal()

Inverts the matrix and returns the (modified) current instance. If the current instance is singular, all elements will be set to zero.

Returns:

the (modified) current instance (for chaining)

adjoint

public Matrix3f adjoint()

Returns the adjoint as a new matrix. The current instance is unaffected.

Returns:

a new Matrix3f

adjoint

public Matrix3f adjoint(Matrix3f store)

Returns the adjoint in the specified storage. The current instance is unaffected.

If this and store are the same object, the result is undefined.

Parameters:

store - storage for the result, or null for a new Matrix3f

Returns:

either store or a new Matrix3f

determinant

public float determinant()

Returns the determinant. The matrix is unaffected.

Returns:

the determinant

zero

public Matrix3f zero()

Sets all elements to zero.

Returns:

the (modified) current instance (for chaining)

transpose

public Matrix3f transpose()

Transposes the matrix and returns the (modified) current instance.

This method is inconsistent with JME naming conventions, but has been preserved for backwards compatibility. To preserve the current instance, transposeNew().

TODO deprecate in favor of transposeLocal()

Returns:

the (modified) current instance (for chaining)

transposeNew

public Matrix3f transposeNew()

Returns the transpose as a new instance. The current instance is unaffected.

Returns:

a new Matrix3f

toString

public String toString()

Returns a string representation of the matrix, which is unaffected. For example, the identity matrix is represented by:

 Matrix3f
 [
  1.0  0.0  0.0
  0.0  1.0  0.0
  0.0  0.0  1.0
 ]
 

Overrides:

toString in class Object

Returns:

the string representation (not null, not empty)

hashCode

public int hashCode()

Returns a hash code. If two matrices have identical values, they will have the same hash code. The matrix is unaffected.

Overrides:

hashCode in class Object

Returns:

a 32-bit value for use in hashing

See Also:

• Object.hashCode()

equals

public boolean equals(Object o)

Tests for exact equality with the argument, distinguishing -0 from 0. If o is null, false is returned. Either way, the current instance is unaffected.

Overrides:

equals in class Object

Parameters:

o - the object to compare (may be null, unaffected)

Returns:

true if this and o have identical values, otherwise false

write

public void write(JmeExporter e)
           throws IOException

Serializes to the specified exporter, for example when saving to a J3O file. The current instance is unaffected.

Specified by:

write in interface Savable

Parameters:

e - the exporter to use (not null)

Throws:

IOException - from the exporter

read

public void read(JmeImporter importer)
          throws IOException

De-serializes from the specified importer, for example when loading from a J3O file.

Specified by:

read in interface Savable

Parameters:

importer - the importer to use (not null)

Throws:

IOException - from the importer

fromStartEndVectors

public void fromStartEndVectors(Vector3f start,
 Vector3f end)

Configures a rotation matrix that rotates the specified start direction to the specified end direction.

See Tomas Möller, John F. Hughes "Efficiently Building a Matrix to Rotate One Vector to Another" Journal of Graphics Tools, 4(4):1-4, 1999.

Parameters:

start - the start direction (not null, length=1, unaffected)

end - the end direction (not null, length=1, unaffected)

scale

public void scale(Vector3f scale)

Scales each column by the corresponding element of the argument.

Parameters:

scale - the scale factors: X scales column 0, Y scales column 1, Z scales column 2 (not null, unaffected)

clone

public Matrix3f clone()

Creates a copy. The current instance is unaffected.

Overrides:

clone in class Object

Returns:

a new instance, equivalent to the current one