|
JSR-184 Public Review Draft - Apr. 30, 2003. | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.microedition.m3d.Transform
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 |
public Transform()
Constructs a new Transform object and initializes it to the 4x4 identity matrix.
Method Detail |
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.
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.
transform
- the new transformationpublic 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.
matrix
- the new transformation matrix as a flat float array
java.lang.IllegalArgumentException
- if matrix.length < 16
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.
matrix
- a flat float array to populate with the matrix contents
java.lang.IllegalArgumentException
- if matrix.length < 16
public void invert()
Inverts this matrix, if possible. The contents of this transformation are replaced with the result.
java.lang.IllegalStateException
- if this transformation is not invertiblepublic void transpose()
Transposes this matrix. The contents of this transformation are replaced with the result.
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.
transform
- the righ-hand-side matrix multiplicantpublic 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.
sx
- scaling factor along the X axissy
- scaling factor along the Y axissz
- scaling factor along the Z axispublic 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.
angle
- angle of rotation about the axis, in degreesax
- X component of the rotation axisay
- Y component of the rotation axisaz
- Z component of the rotation axis
java.lang.IllegalArgumentException
- if the rotation axis (ax, ay, az)
is zeropublic 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.
qx
- X component of the quaternion's vector partqy
- Y component of the quaternion's vector partqz
- Z component of the quaternion's vector partqw
- scalar component of the quaternion
java.lang.IllegalArgumentException
- if all quaternion components are zeropublic 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.
tx
- X component of the translation vectorty
- Y component of the translation vectortz
- Z component of the translation vectorpublic 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:
b0, b1, ..., bN-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.
in
- a VertexArray of 2D, 3D or 4D vectors to transform with this matrixout
- a VertexArray to populate with the transformed vectorsscale
- a uniform scale factor to apply to all vectors before transformationbias
- an array storing the bias values both for the original (on input) and
the transformed (on output) VertexArray objects
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
|
JSR-184 Public Review Draft - Apr. 30, 2003. | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |