javax.microedition.m3g
Class Transformable

java.lang.Object
  javax.microedition.m3g.Object3D
      javax.microedition.m3g.Transformable

Direct Known Subclasses:

Node, Texture2D

public abstract class Transformable

extends Object3D

An abstract base class for Node and Texture2D, defining common methods for manipulating node and texture transformations.

Node transformations and texture transformations consist of four individual components: translation (T), orientation (R), scale (S) and a generic 4x4 matrix (M). Formally, a homogeneous vector p = (x, y, z, w), representing vertex coordinates (in Node) or texture coordinates (in Texture2D), is transformed into p' = (x', y', z', w') as follows:

p' = T R S M p

See the Node and Texture2D class descriptions for more information on node transformations and texture transformations.

Instantiation

Transformable is an abstract class, and therefore has no public constructor. When a class derived from Transformable is instantiated, the attributes inherited from it will have the following default values:

• scale : (1,1,1)
• translation : (0,0,0)
• orientation : angle = 0, axis = undefined
• matrix : identity

The transformation components are initially set to identity so that they do not affect the texture coordinates or vertex coordinates in any way. Note that the orientation axis can be left undefined because the angle is zero.

See Also:

Binary format

Method Summary

void	getCompositeTransform(Transform transform) Retrieves the composite transformation matrix of this Transformable.
void	getOrientation(float[] angleAxis) Retrieves the orientation component of this Transformable.
void	getScale(float[] xyz) Retrieves the scale component of this Transformable.
void	getTransform(Transform transform) Retrieves the matrix component of this Transformable.
void	getTranslation(float[] xyz) Retrieves the translation component of this Transformable.
void	postRotate(float angle, float ax, float ay, float az) Multiplies the current orientation component from the right by the given orientation.
void	preRotate(float angle, float ax, float ay, float az) Multiplies the current orientation component from the left by the given orientation.
void	scale(float sx, float sy, float sz) Multiplies the current scale component by the given scale factors.
void	setOrientation(float angle, float ax, float ay, float az) Sets the orientation component of this Transformable.
void	setScale(float sx, float sy, float sz) Sets the scale component of this Transformable.
void	setTransform(Transform transform) Sets the matrix component of this Transformable by copying in the given Transform.
void	setTranslation(float tx, float ty, float tz) Sets the translation component of this Transformable.
void	translate(float tx, float ty, float tz) Adds the given offset to the current translation component.

Methods inherited from class javax.microedition.m3g.Object3D

addAnimationTrack, animate, duplicate, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, getUserObject, removeAnimationTrack, setUserID, setUserObject

Method Detail

setOrientation

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

Sets the orientation component of this Transformable. The orientation is specified such that looking along the rotation axis, the rotation is angle degrees clockwise. 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 and angle is nonzero

See Also:

getOrientation, preRotate, postRotate

preRotate

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

Multiplies the current orientation component from the left by the given orientation. The orientation is given in axis-angle format, as in setOrientation.

Denoting the given orientation by R' and the current orientation by R, the new orientation is computed as follows:

R'' = R' R

Depending on the internal representation of orientations, the multiplication may be done with quaternions, matrices, or something else, as long as the resulting orientation is the same as it would be if matrices or quaternions were used.

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

See Also:

setOrientation, postRotate

postRotate

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

Multiplies the current orientation component from the right by the given orientation. Except for the multiplication order, this method is equivalent to preRotate.

Denoting the given orientation by R' and the current orientation by R, the new orientation is computed as follows:

R'' = R R'

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

See Also:

setOrientation, preRotate

getOrientation

public void getOrientation(float[] angleAxis)

Retrieves the orientation component of this Transformable.

The returned axis and angle values are not necessarily the same that were last written to the orientation component. Instead, they may be any values that produce an equivalent result. For example, a 90 degree rotation about the positive Z axis is equivalent to a 270 degree rotation about the negative Z axis. In particular, if the rotation angle is zero, the returned rotation axis is undefined and may also be the zero vector.

Parameters:

angleAxis - a float array to fill in with (angle ax ay az)

Throws:

java.lang.NullPointerException - if angleAxis is null

java.lang.IllegalArgumentException - if angleAxis.length < 4

See Also:

setOrientation

setScale

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

Sets the scale component of this Transformable.

Note that if any of the scale factors are set to zero, this transformation becomes uninvertible. That, in turn, may cause certain operations to produce undefined results or to fail with an ArithmeticException.

Parameters:

sx - scale along the X axis

sy - scale along the Y axis

sz - scale along the Z axis

See Also:

getScale, scale

scale

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

Multiplies the current scale component by the given scale factors. Denoting the current scale by (sx sy sz) and the given scale by (sx' sy' sz'), the new scale factors are computed as follows:

sx'' = sx * sx'
sy'' = sy * sy'
sz'' = sz * sz'

Since this is an operation on scalar values, the order of multiplication makes no difference. Unlike with the rotation component, separate methods for left and right multiplication are therefore not needed.

Parameters:

sx - scale along the X axis

sy - scale along the Y axis

sz - scale along the Z axis

See Also:

setScale

getScale

public void getScale(float[] xyz)

Retrieves the scale component of this Transformable.

Parameters:

xyz - a float array to fill in with (sx sy sz)

Throws:

java.lang.NullPointerException - if xyz is null

java.lang.IllegalArgumentException - if xyz.length < 3

See Also:

setScale

setTranslation

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

Sets the translation component of this Transformable.

Parameters:

tx - translation along the X axis

ty - translation along the Y axis

tz - translation along the Z axis

See Also:

getTranslation, translate

translate

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

Adds the given offset to the current translation component. Denoting the current translation component by (tx ty tz) and the given offset by (tx' ty' tz'), the new translation component is computed as follows:

tx'' = tx + tx'
ty'' = ty + ty'
tz'' = tz + tz'

Parameters:

tx - translation along the X axis

ty - translation along the Y axis

tz - translation along the Z axis

See Also:

setTranslation

getTranslation

public void getTranslation(float[] xyz)

Retrieves the translation component of this Transformable.

Parameters:

xyz - a float array to fill in with (tx ty tz)

Throws:

java.lang.NullPointerException - if xyz is null

java.lang.IllegalArgumentException - if xyz.length < 3

See Also:

setTranslation

setTransform

public void setTransform(Transform transform)

Sets the matrix component of this Transformable by copying in the given Transform. This does not affect the separate translation, orientation and scale components.

A generic matrix component is required for transformations that can not be expressed in the component form efficiently, or at all. These include, for example, pivot transforms and non-axis-aligned scales.

If this Transformable is a Node object, the bottom row of the given matrix must be (0 0 0 1). Projective transformations are not supported in the scene graph so as to reduce run-time memory consumption and to accelerate rendering. Note, however, that arbitrary 4x4 modelview matrices are supported in the immediate mode.

Parameters:

transform - the Transform object to copy in, or null to indicate the identity matrix

Throws:

java.lang.IllegalArgumentException - if this Transformable is a Node and the bottom row of transform is not (0 0 0 1)

See Also:

getTransform

getTransform

public void getTransform(Transform transform)

Retrieves the matrix component of this Transformable. This does not include the separate translation, orientation and scale components. The transformation is copied into the given Transform object.

Parameters:

transform - the Transform object to receive the transformation matrix

Throws:

java.lang.NullPointerException - if transform is null

See Also:

setTransform

getCompositeTransform

public void getCompositeTransform(Transform transform)

Retrieves the composite transformation matrix of this Transformable. The composite transformation matrix is the concatenation of the translation, rotation, scale and generic matrix components. Formally, C = T R S M. The composite transformation is copied into the given Transform object.

Parameters:

transform - the Transform object to receive the composite transformation matrix

Throws:

java.lang.NullPointerException - if transform is null