javax.microedition.m3g
Class Transform

java.lang.Object
  javax.microedition.m3g.Transform

public class Transform

extends java.lang.Object

A generic 4x4 floating point matrix, representing a transformation. By default, all methods dealing with Transform objects operate on arbitrary 4x4 matrices. Any exceptions to this rule are documented explicitly at the method level.

Even though arbitrary 4x4 matrices are generally allowed, using non-invertible (singular) matrices may produce undefined results or an arithmetic exception in some situations. Specifically, if the modelview matrix of an object is non-invertible, the results of normal vector transformation and fogging are undefined for that object.

Constructor Summary

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

Transform(Transform transform)
Constructs a new Transform object and initializes it by copying in the contents of the given Transform.

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	postMultiply(Transform transform) Multiplies this transformation from the right by the given transformation.
void	postRotate(float angle, float ax, float ay, float az) Multiplies this transformation from the right by the given rotation matrix, specified in axis-angle form.
void	postRotateQuat(float qx, float qy, float qz, float qw) Multiplies this transformation from the right by the given rotation matrix, specified in quaternion form.
void	postScale(float sx, float sy, float sz) Multiplies this transformation from the right by the given scale matrix.
void	postTranslate(float tx, float ty, float tz) Multiplies this transformation from the right by the given translation 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 the contents of the given Transform.
void	setIdentity() Replaces this transformation with the 4x4 identity matrix.
void	transform(float[] vectors) Multiplies the given array of 4D vectors with this matrix.
void	transform(VertexArray in, float[] out, boolean W) Multiplies the elements of the given VertexArray with this matrix, storing the transformed values in a float array.
void	transpose() Transposes this matrix.

Constructor Detail

Transform

public Transform()

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

Transform

public Transform(Transform transform)

Constructs a new Transform object and initializes it by copying in the contents of the given Transform.

Parameters:

transform - the Transform object to copy the contents of

Throws:

java.lang.NullPointerException - if transform is null

Method Detail

setIdentity

public void setIdentity()

Replaces this transformation with the 4x4 identity matrix.

set

public void set(Transform transform)

Sets this transformation by copying the contents of the given Transform. The pre-existing contents of this transformation are discarded.

Parameters:

transform - the new transformation

Throws:

java.lang.NullPointerException - if transform is null

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. 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.NullPointerException - if matrix is null

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.NullPointerException - if matrix is null

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.ArithmeticException - if this transformation is not invertible

transpose

public void transpose()

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

postMultiply

public void postMultiply(Transform transform)

Multiplies this transformation from the right by the given transformation. The contents of this transformation are replaced with the result. Denoting this transformation by M and the given transformation by T, the new value for this transformation is computed as follows:

M' = M T

Parameters:

transform - the right-hand-side matrix multiplicant

Throws:

java.lang.NullPointerException - if transform is null

postScale

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

Multiplies this transformation from the right by the given scale matrix. The contents of this transformation are replaced with the result. Denoting this transformation by M and the scale matrix by S, the new value for this transformation is computed as follows:

M' = M S

The scaling factors may be non-uniform, and negative scale factors (mirroring transforms) are also allowed. The scale matrix S is constructed from the given scale factors (sx sy sz) follows:

sx  0   0   0
0   sy  0   0
0   0   sz  0
0   0   0   1

Parameters:

sx - scaling factor along the X axis

sy - scaling factor along the Y axis

sz - scaling factor along the Z axis

postRotate

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

Multiplies this transformation from the right by the given rotation matrix, specified in axis-angle form. The contents of this transformation are replaced with the result. Denoting this transformation by M and the rotation matrix by R, the new value for this transformation is computed as follows:

M' = M R

The rotation is specified such that looking along the positive 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).

The rotation matrix R is constructed from the given angle and axis (x y z) as follows:

xx(1-c)+c    xy(1-c)-zs   xz(1-c)+ys   0
yx(1-c)+zs   yy(1-c)+c    yz(1-c)-xs   0
xz(1-c)-ys   yz(1-c)+xs   zz(1-c)+c    0
     0            0            0       1

where c = cos(angle) and s = sin(angle). If the axis (x y z) is not unit-length, it will be normalized automatically before constructing the matrix.

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 and angle is nonzero

postRotateQuat

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

Multiplies this transformation from the right by the given rotation matrix, specified in quaternion form. The contents of this transformation are replaced with the result. Denoting this transformation by M and the rotation matrix by R, the new value for this transformation is computed as follows:

M' = M R

The rotation matrix R is constructed from the given quaternion (x y z w) as follows:

1-(2yy+2zz)   2xy-2zw      2xz+2yw      0
  2xy+2zw   1-(2xx+2zz)    2yz-2xw      0
  2xz-2yw     2yz+2xw    1-(2xx+2yy)    0
     0           0            0         1

The input quaternion is normalized to a 4-dimensional unit vector prior to constructing the rotation matrix. 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

postTranslate

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

Multiplies this transformation from the right by the given translation matrix. The contents of this transformation are replaced with the result. Denoting this transformation by M and the translation matrix by T, the new value for this transformation is computed as follows:

M' = M T

The translation matrix T is constructed from the given translation vector (tx ty tz) as follows:

1   0   0   tx
0   1   0   ty
0   0   1   tz
0   0   0   1

Parameters:

tx - X component of the translation vector

ty - Y component of the translation vector

tz - Z component of the translation vector

transform

public void transform(VertexArray in,
                      float[] out,
                      boolean W)

Multiplies the elements of the given VertexArray with this matrix, storing the transformed values in a float array.

The input VertexArray may have any number of elements (E), two or three components per element (C), and any component size (8 or 16 bit). The float array is filled in with E elements, each having four components. The multiplication is always done with a full 4x4 matrix and all four components of the result are returned.

The implied value of the missing fourth component (W) of each input element depends on the boolean parameter. If the parameter is set to true, the W components of all vectors are set to 1.0 prior to multiplication. If the parameter is false, the W components are set to 0.0. If the elements of the input array have only two components, the missing third component is always set to zero.

This method does not take into account the scale and bias that may be associated with vertex positions and texture coordinates. (This is simply because the scale and bias values are defined in VertexBuffer, not VertexArray.) If the application wishes to use this method for transforming the vertex positions in a specific VertexBuffer, for example, the scale and bias can be applied to this Transform directly. See the code fragment below for how to do that.

Note that this is a simple matrix-by-vector multiplication; no division by W or other operations are implied. The interpretation of the input and output values is up to each application.

Parameters:

in - a VertexArray of 2D or 3D vectors to multiply with this matrix

out - a 4D float array to populate with the transformed vectors

W - true to set the W component of each input vector implicitly to 1.0; false to set them to 0.0

Throws:

java.lang.NullPointerException - if in is null

java.lang.NullPointerException - if out is null

java.lang.IllegalArgumentException - if in.numComponents == 4

java.lang.IllegalArgumentException - if out.length < 4*E, where E is the number of elements in the input VertexArray

Example:

A method for transforming a vertex coordinate array.

void transformPoints(Transform t, VertexBuffer vb, float[] out)
 {
     // Make a copy of the given Transform so that we can restore
     // its original contents at the end.
  
     Transform tmp = new Transform(t);
     
     // Retrieve the vertex coordinate array and its associated
     // scale and bias. In real applications, the float array
     // and the temporary Transform object should both be class
     // variables to avoid garbage collection.
  
     float[] scaleBias = new float[4];
     VertexArray points = vb.getPositions(scaleBias);
     
     // Note the order of constructing the transformation matrix.
     // The coordinates must be scaled first, then biased:
     //   v' = T S v
  
     t.postTranslate(scaleBias[1], scaleBias[2], scaleBias[3]);
     t.postScale(scaleBias[0], scaleBias[0], scaleBias[0]);
     t.transform(points, out, true);
  
     // Restore the original Transform.
     
     t.set(tmp);
 }

transform

public void transform(float[] vectors)

Multiplies the given array of 4D vectors with this matrix. The transformation is done in place, that is, the original vectors are overwritten with the transformed vectors.

The vectors are given as a flat array of (x y z w) quadruplets. The length of the array divided by 4 gives the number of vectors to transform.

Note that this is a simple matrix-by-vector multiplication; no division by W or other operations are implied. The interpretation of the input and output values is up to each application.

Parameters:

vectors - the vectors to transform, in (xyzw xyzw xyzw ...) order

Throws:

java.lang.NullPointerException - if vectors is null

java.lang.IllegalArgumentException - if vectors.length % 4 != 0