javax.microedition.m3d
Class Transform

java.lang.Object
  |
  +--javax.microedition.m3d.Transform

public class Transform

extends java.lang.Object

A generic 4x4 floating point matrix, representing a transformation. Any restrictions to a matrix are subject only to its intended use. All methods in this API that take in a Transform object accept arbitrary 4x4 matrices, but certain features may become unavailable or undefined if a non-invertible matrix is given. For example, a non-invertible transformation in a Light node may yield unexpected results in lighting.

Note that matrices are always multiplied from the right in this class, and that vectors are always column vectors.

Constructor Summary

Transform()
Constructs a new Transform object and initializes it to the 4x4 identity matrix.

Method Summary

void	get(float[] matrix) Retrieves the contents of this transformation as a 16-element float array.
void	invert() Inverts this matrix, if possible.
void	mul(Transform transform) Multiplies this transformation from the right by the given transformation.
void	rotate(float angle, float ax, float ay, float az) Multiplies this transformation from the right by a rotation matrix, specified in axis-angle form.
void	rotateQuat(float qx, float qy, float qz, float qw) Multiplies this transformation from the right by a rotation matrix, specified in quaternion form.
void	scale(float sx, float sy, float sz) Multiplies this transformation from the right by a scale matrix.
void	set(float[] matrix) Sets this transformation by copying from the given 16-element float array.
void	set(Transform transform) Sets this transformation by copying from the given Transform.
void	setIdentity() Replaces this transformation with the 4x4 identity matrix.
float	transform(VertexArray in, VertexArray out, float scale, float[] bias) Transforms the elements of a given VertexArray with this matrix, storing the transformed values into another VertexArray with equal dimensions.
void	translate(float tx, float ty, float tz) Multiplies this transformation from the right by a translation matrix.
void	transpose() Transposes this matrix.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Transform

public Transform()

Constructs a new Transform object and initializes it to the 4x4 identity matrix.

Method Detail

setIdentity

public void setIdentity()

Replaces this transformation with the 4x4 identity matrix. Being able to re-initialize an existing Transform object is useful for minimizing garbage collection.

set

public void set(Transform transform)

Sets this transformation by copying from the given Transform. The pre-existing contents of this transformation are discarded, but the given Transform is not modified.

Parameters:

transform - the new transformation

set

public void set(float[] matrix)

Sets this transformation by copying from the given 16-element float array. The pre-existing contents of this transformation are discarded, but the source array is not modified. The elements in the source array are organized in row-major order:

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

In other words, the second element of the source array is copied to the second element of the first row in the matrix, and so on.

Parameters:

matrix - the new transformation matrix as a flat float array

Throws:

java.lang.IllegalArgumentException - if matrix.length < 16

get

public void get(float[] matrix)

Retrieves the contents of this transformation as a 16-element float array. The matrix elements are copied to the array in row-major order, that is, in the same order as in the set(float[]) method.

Parameters:

matrix - a flat float array to populate with the matrix contents

Throws:

java.lang.IllegalArgumentException - if matrix.length < 16

invert

public void invert()

Inverts this matrix, if possible. The contents of this transformation are replaced with the result.

Throws:

java.lang.IllegalStateException - if this transformation is not invertible

transpose

public void transpose()

Transposes this matrix. The contents of this transformation are replaced with the result.

mul

public void mul(Transform transform)

Multiplies this transformation from the right by the given transformation. The contents of this transformation are replaced with the result. The contents of the given transformation are not modified.

Parameters:

transform - the righ-hand-side matrix multiplicant

scale

public void scale(float sx,
                  float sy,
                  float sz)

Multiplies this transformation from the right by a scale matrix. The contents of this transformation are replaced with the result. The scaling factors may be non-uniform, and negative scale factors (mirroring transforms) are also allowed.

Parameters:

sx - scaling factor along the X axis

sy - scaling factor along the Y axis

sz - scaling factor along the Z axis

rotate

public void rotate(float angle,
                   float ax,
                   float ay,
                   float az)

Multiplies this transformation from the right by a rotation matrix, specified in axis-angle form. The contents of this transformation are replaced with the result.

The rotation is specified such that looking along the rotation axis, the rotation is angle degrees clockwise (or, equivalently, looking on the opposite direction of the rotation axis, the rotation is angle degrees counterclockwise). Note that the axis does not have to be a unit vector.

Parameters:

angle - angle of rotation about the axis, in degrees

ax - X component of the rotation axis

ay - Y component of the rotation axis

az - Z component of the rotation axis

Throws:

java.lang.IllegalArgumentException - if the rotation axis (ax, ay, az) is zero

rotateQuat

public void rotateQuat(float qx,
                       float qy,
                       float qz,
                       float qw)

Multiplies this transformation from the right by a rotation matrix, specified in quaternion form. The contents of this transformation are replaced with the result.

The input quaternion is normalized to a 4-dimensional unit vector prior to multiplication. A quaternion with a vector part of all zeros is therefore normalized to (0,0,0,1), which represents a rotation by 2*pi, that is, no rotation at all. The only illegal input condition occurs when all components of the quaternion are zero.

Parameters:

qx - X component of the quaternion's vector part

qy - Y component of the quaternion's vector part

qz - Z component of the quaternion's vector part

qw - scalar component of the quaternion

Throws:

java.lang.IllegalArgumentException - if all quaternion components are zero

translate

public void translate(float tx,
                      float ty,
                      float tz)

Multiplies this transformation from the right by a translation matrix. The contents of this transformation are replaced with the result.

Parameters:

tx - X component of the translation vector

ty - Y component of the translation vector

tz - Z component of the translation vector

transform

public float transform(VertexArray in,
                       VertexArray out,
                       float scale,
                       float[] bias)

Transforms the elements of a given VertexArray with this matrix, storing the transformed values into another VertexArray with equal dimensions. The given scale and bias are applied to the input vectors before transformation, and potentially changed as a result of the transformation, in order to avoid overflows. The scale of the output VertexArray is returned as the method return value, whereas the output bias is returned by overwriting the input bias array.

Formally, the transformed value v' of a vector v with corresponding scale and bias terms s and b is

v' = M × (sv + b),

where M is this Transform. New scale and bias terms s' and b' are determined for the output VertexArray such that for each transformed vector

v' = s'v'' + b'

where the components of v'' fit without overflowing in the output VertexArray. Implementations should pick the new scale and bias values so that unnecessary loss of precision does not occur.

The input bias terms are given as a float array of the form:

b₀, b₁, ..., b_N-1

where N is the number of components per vector in the input and output VertexArray objects. Upon return, the new bias values are returned in the same float array that was used for input.

If the input VertexArray specifies only 2 components per vector, the third component is assumed to be 0, with unit scale and zero bias. For both 2- and 3-component input vectors, the last component (fourth) is assumed to be 1, with unit scale and zero bias.

Parameters:

in - a VertexArray of 2D, 3D or 4D vectors to transform with this matrix

out - a VertexArray to populate with the transformed vectors

scale - a uniform scale factor to apply to all vectors before transformation

bias - an array storing the bias values both for the original (on input) and the transformed (on output) VertexArray objects

Returns:

the uniform scale factor for the transformed VertexArray

Throws:

java.lang.IllegalArgumentException - if in and out do not have equal dimensions (number of elements, number of components per element, and component size)

java.lang.IllegalArgumentException - if bias.length < numComponents, where numComponents is the number of components per element in the input and output VertexArrays