javax.microedition.m3d
Class Node

java.lang.Object
  |
  +--javax.microedition.m3d.Object3D
        |
        +--javax.microedition.m3d.Node

Direct Known Subclasses:

Camera, Group, Light, Mesh, Sprite

public abstract class Node

extends Object3D

An abstract base class for scene graph nodes, that is, instances of objects in a scene graph. There are five different types of Nodes:

• Camera defines the projection from 3D to 2D, as well as the position of the viewer in the World.
• Mesh defines a 3D object, consisting of triangles with associated material properties.
• Sprite defines a screen-aligned 2D image with a position in 3D space.
• Light defines a light source: its position, direction, color, intensity, and other attributes.
• Group serves as a root for scene graph branches. All other nodes except Groups are leaf nodes.

Node transformation

Each node defines a local coordinate system that can be transformed relative to the coordinate system of the parent node. In the rest of this documentation, we refer to the transformation from the local coordinate system of a node to the coordinate system of its parent as the node transformation.

The node transformation can be set in two ways: either as a generic 3x4 matrix or as a component-based scale-orientation-translation transformation. If the transformation has been set as a 3x4 matrix, the methods to set and get the individual components are not available. Setting the 3x4 transform to null switches from generic form to component form, but does not restore the previous values of the components.

Given a homogeneous vector p = (x, y, z, 1) representing a 3-dimensional point in the local coordinate system and a transformation in component form, p is transformed into point p' = (x', y', z', 1) in the parent coordinate system in the following manner. In matrix transformation notation, where T (translation), R (rotation or orientation), and S (scale) are the equivalent transformation matrices,

p' = T × R × S × p.

Node transformations may also be animated. If a generic node transformation is animated, the animated transformation replaces the generic transformation. Denoting the animated transformation by M', the point p is transformed as follows:

p' = M' × p.

If the node transformation is in component form, only the animated components are replaced, while the others stay unmodified. For instance, if the translation and rotation components are animated, but the scale is not, the transformation from local coordinates to parent coordinates is as follows:

p' = T' × R' × S × p,

where T' and R' denote the animated translation and orientation components, respectively.

Additionally, a node may be aligned with respect to another node, the current camera, or a pick ray. In this case, an alignment matrix A is computed and applied to the vertex positions before the node transformation. The alignment matrix is computed at the time of rendering or picking, and the computation is based on the node transformation that is in effect at the time. Therefore, the alignment is applied in the correct manner regardless of whether the node transformation is an animation target or not.

For an aligned node with the node transformation in component form, the transformation from the local coordinate system to the parent coordinate system is as follows:

p' = T × R × S × A × p

For an aligned node with the node transformation in generic form, denoting the generic transformation by M, the transformation from local coordinates to parent coordinates is:

p' = M × A × p.

Alpha factor

The alpha factor, a scalar value between [0,1], is an inheritable property similar to the node transformation. The effective alpha factor of a Mesh node is obtained by multiplying its own alpha factor with the alpha factor of each of its ancestors. When rendering or picking, the effective alpha factor is multiplied with the alpha component of the diffuse color in each of the Material objects associated with that Mesh. The alpha factor is ignored for Light, Camera, and Sprite nodes, because they do not have a Material.

Instantiation

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

parent node : null
enabled : true
scope ID : 1
alpha factor : 1.0
transformation mode : component
alignment : null
scale : (1,1,1)
translation : (0,0,0)
orientation : angle = 0, axis = (0,0,1)

See Also:

Binary format

Field Summary

static int	NONE Specifies for the setAlignment method that no alignment should be done for the specified axis.
static int	ORIGIN Specifies the origin of the reference node as an orientation reference for the setAlignment method.
static int	X_AXIS Specifies the X axis of the reference node as an orientation reference for the setAlignment method.
static int	Y_AXIS Specifies the Y axis of the reference node as an orientation reference for the setAlignment method.
static int	Z_AXIS Specifies the Z axis of the reference node as an orientation reference for the setAlignment method.

Fields inherited from class javax.microedition.m3d.Object3D

userObject

Method Summary

float	getAlphaFactor() Retrieves the alpha factor of this Node.
void	getOrientation(float[] angleAxis) Retrieves the orientation component of the node transformation.
Node	getParent() Returns the parent of this node.
void	getScale(float[] xyz) Retrieves the scaling factors of the node transformation.
int	getScopeID() Gets the scope membership ID of this node.
void	getTransform(Transform transform) Retrieves the node transformation.
boolean	getTransformTo(Node target, Transform transform) Gets the transformation from this node to another node, along the shortest scene graph path between the two.
void	getTranslation(float[] xyz) Retrieves the translation components of the node transformation.
boolean	isEnabled() Determines whether this node is enabled or disabled.
void	setAlignment(Node zReference, int zTarget, Node yReference, int yTarget) Sets this node to automatically align with a given other node, or disables automatic alignment.
void	setAlphaFactor(float alphaFactor) Sets the alpha factor for this Node.
void	setEnable(boolean enable) Enables or disables this Node.
void	setOrientation(float angle, float ax, float ay, float az) Sets the orientation component of the node transformation.
void	setScale(float sx, float sy, float sz) Sets the scale of this node transformation.
void	setScopeID(int scopeID) Sets the scope membership ID for this node.
void	setTransform(Transform transform) Sets the node transformation by copying the contents of the given Transform.
void	setTranslation(float tx, float ty, float tz) Sets the translation of the node transformation.

Methods inherited from class javax.microedition.m3d.Object3D

addAnimationTrack, animate, clone, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, removeAnimationTrack, setUserID

Methods inherited from class java.lang.Object

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

Field Detail

NONE

public static final int NONE

Specifies for the setAlignment method that no alignment should be done for the specified axis.

See Also:

Constant Field Values

X_AXIS

public static final int X_AXIS

Specifies the X axis of the reference node as an orientation reference for the setAlignment method.

See Also:

Constant Field Values

Y_AXIS

public static final int Y_AXIS

Specifies the Y axis of the reference node as an orientation reference for the setAlignment method.

See Also:

Constant Field Values

Z_AXIS

public static final int Z_AXIS

Specifies the Z axis of the reference node as an orientation reference for the setAlignment method.

See Also:

Constant Field Values

ORIGIN

public static final int ORIGIN

Specifies the origin of the reference node as an orientation reference for the setAlignment method. The origin can only be set as an orientation reference for the Z axis.

See Also:

Constant Field Values

Method Detail

setEnable

public void setEnable(boolean enable)

Enables or disables this Node. A disabled node and its children (if any) are ignored when rendering and picking.

Parameters:

enable - true to enable this node; false to disable

isEnabled

public boolean isEnabled()

Determines whether this node is enabled or disabled.

Returns:

true if this Node is enabled; false if it is disabled

setScopeID

public void setScopeID(int scopeID)

Sets the scope membership ID for this node.

Parameters:

scopeID - the scope membership ID to set

See Also:

getScopeID

getScopeID

public int getScopeID()

Gets the scope membership ID of this node.

Returns:

the current scope membership ID

See Also:

setScopeID

getParent

public Node getParent()

Returns the parent of this node.

Returns:

reference to the parent node, or null if there is no parent

setOrientation

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

Sets the orientation component of the node transformation. The orientation 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 and rotating angle degrees counterclockwise). Note that the axis does not have to be a unit vector.

This method takes effect only if the node transformation is in component based form. See the class description for discussion on generic and component based transform representations.

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

java.lang.IllegalStateException - if the node transformation is not in component based form

See Also:

getOrientation

getOrientation

public void getOrientation(float[] angleAxis)

Retrieves the orientation component of the node transformation. If the orientation is being animated, the animated values are returned instead of the values that were in effect before the animation started.

This method is only available if the node transformation is in component based form. See the class description for discussion on generic and component based transform representations.

Parameters:

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

Throws:

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

java.lang.IllegalStateException - if the node transformation is not in component based form

See Also:

setOrientation

setScale

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

Sets the scale of this node transformation. If any of the scale factors are zero, some operations may later produce undefined results.

Parameters:

sx - scale along the X axis

sy - scale along the Y axis

sz - scale along the Z axis

Throws:

java.lang.IllegalStateException - if the node transformation is not in component based form

See Also:

getScale

getScale

public void getScale(float[] xyz)

Retrieves the scaling factors of the node transformation. If the scale is being animated, the animated values are returned instead of the values that were in effect before the animation started.

Parameters:

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

Throws:

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

java.lang.IllegalStateException - if the node transformation is not in component based form

See Also:

setScale

setTranslation

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

Sets the translation of the node transformation.

Parameters:

tx - translation along the X axis

ty - translation along the Y axis

tz - translation along the Z axis

Throws:

java.lang.IllegalStateException - if the node transformation is not in component based form

See Also:

getTranslation

getTranslation

public void getTranslation(float[] xyz)

Retrieves the translation components of the node transformation. If the translation is being animated, the animated values are returned instead of the values that were in effect before the animation started.

Parameters:

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

Throws:

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

java.lang.IllegalStateException - if the node transformation is not in component based form

See Also:

setTranslation

setTransform

public void setTransform(Transform transform)

Sets the node transformation by copying the contents of the given Transform. The bottom row of the matrix must be (0 0 0 1). Passing a null Transformation switches from generic transformation form to component based form, and resets the components to their default values specified above.

The generic form is required for transformations that cannot be expressed in the component form at all, or not without introducing additional nodes. These include pivot transforms as well as various skewing and warping transforms. As the bottom row of the matrix is fixed to (0 0 0 1), projective node transforms are not possible. However, projective transforms are supported in the immediate mode, and may be supported as node transforms in a future revision of this API.

Parameters:

transform - the transform to copy as the new node transformation, or null

Throws:

java.lang.IllegalArgumentException - if the bottom row of transform is not (0 0 0 1)

See Also:

getTransform

getTransform

public void getTransform(Transform transform)

Retrieves the node transformation. The node transformation is copied to transform, discarding its previous contents. This method is applicable regardless of whether the node transformation is in component form or generic form. If the node transformation is being animated, the animated transformation is returned instead of the transformation that was in effect before the animation started.

Parameters:

transform - transform object to receive the node transformation

See Also:

setTransform

getTransformTo

public boolean getTransformTo(Node target,
                              Transform transform)

Gets the transformation from this node to another node, along the shortest scene graph path between the two. The transformation is copied into the given Transform object. Note that in some cases there may not exist a valid transformation from this node to the target node; for example, if there is no path from this node to the target, or if there is a non-invertible transformation along the path. This is indicated by the boolean return value.

Parameters:

target - transformation target node

transform - transform object to receive the transformation; if there is no transformation, the contents of the object are undefined

Returns:

true if the returned transformation is valid; false if there is no transformation from this node to the target node

setAlignment

public void setAlignment(Node zReference,
                         int zTarget,
                         Node yReference,
                         int yTarget)

Sets this node to automatically align with a given other node, or disables automatic alignment. This can be used, for example, for automatic "look at" behavior for nodes, or to align "billboards" with the camera space Z axis.

Alignment can be set or disabled for one or both of the Y and Z axes. If it is set for both, the Z alignment is applied first, followed by the Y alignment. The Y alignment is therefore constrained by the Z alignment. On the other hand, if alignment is only set for the Y axis, the alignment is unconstrained.

Node alignment is applied on top of the node transformation, as well as any animation tracks that are targeted to the node transform. Node alignment is applied during rendering, and the resulting transformation is not exposed to the application. Therefore, getTransform always returns the static or animated node transformation, not the aligned transformation.

When picking, a node aligned to the current camera aligns itself with the pick ray. The origin of the pick ray is substituted for the origin of the camera, and the opposite vector of the pick ray is substituted for the Z axis of the camera. Alignment to other camera axes is ignored when picking.

Alignment is applied to nodes in such an order that every node affecting the transformation of a node is aligned prior to the node itself. That is, prior to calculating the alignment of each node, the alignments of its parent and alignment target nodes must be calculated. If this chain of dependencies leads back to the original node (that is, the alignment targets form a cycle), the cycle is terminated at the original node; that is, the alignment for each node is calculated exactly once. Note, however, that the result of cyclic alignment is undefined in that the starting node for alignment calculation is not defined.

Parameters:

zReference - the node to use as reference for aligning the Z axis of this node, or null to align to the current camera

zTarget - the axis of zReference to align the Z axis of this node with, or ORIGIN to have the Z axis point at the origin of zReference, or NONE to not align the Z axis at all

yReference - the node to use as reference for aligning the Y axis of this node, or null to align to the current camera

yTarget - the axis of yReference to align the Y axis of this node with, or NONE to not align the Y axis at all; ORIGIN is not allowed

Throws:

java.lang.IllegalArgumentException - if both zReference and yReference are non-null, and zTarget is the same as yTarget

java.lang.IllegalArgumentException - if yTarget or zTarget is not one of the symbolic constants listed above

java.lang.IllegalArgumentException - if zReference or yReference is a descendant of this Node

setAlphaFactor

public void setAlphaFactor(float alphaFactor)

Sets the alpha factor for this Node. See the class description for discussion on the alpha factor and its inheritance properties.

Parameters:

alphaFactor - the new alpha factor for this node; must be [0,1]

Throws:

java.lang.IllegalArgumentException - if alphaFactor is negative or greater than 1.0

See Also:

getAlphaFactor

getAlphaFactor

public float getAlphaFactor()

Retrieves the alpha factor of this Node. The alpha factors of any ancestors of this Node are not multiplied in to the returned value.

Returns:

the alpha factor of this node; [0,1]

See Also:

setAlphaFactor