JSR-184 Public Review Draft - Apr. 30, 2003.

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:

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:

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

JSR-184 Public Review Draft - Apr. 30, 2003.

Copyright © 2003 Nokia Corporation. See the Copyright Notice for details.