|
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.Object3D | +--javax.microedition.m3d.Node
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.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.
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.
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:
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 |
public static final int NONE
Specifies for the setAlignment
method that no
alignment should be done for the specified axis.
public static final int X_AXIS
Specifies the X axis of the reference node as an orientation
reference for the setAlignment
method.
public static final int Y_AXIS
Specifies the Y axis of the reference node as an orientation
reference for the setAlignment
method.
public static final int Z_AXIS
Specifies the Z axis of the reference node as an orientation
reference for the setAlignment
method.
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.
Method Detail |
public void setEnable(boolean enable)
Enables or disables this Node. A disabled node and its children (if any) are ignored when rendering and picking.
enable
- true to enable this node; false to disablepublic boolean isEnabled()
Determines whether this node is enabled or disabled.
public void setScopeID(int scopeID)
Sets the scope membership ID for this node.
scopeID
- the scope membership ID to setgetScopeID
public int getScopeID()
Gets the scope membership ID of this node.
setScopeID
public Node getParent()
Returns the parent of this node.
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.
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 zero
java.lang.IllegalStateException
- if the node transformation is not in component based formgetOrientation
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.
angleAxis
- float array to fill in with (angle, ax, ay, az)
java.lang.IllegalArgumentException
- if angleAxis.length < 4
java.lang.IllegalStateException
- if the node transformation is not in component based formsetOrientation
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.
sx
- scale along the X axissy
- scale along the Y axissz
- scale along the Z axis
java.lang.IllegalStateException
- if the node transformation is not in component based formgetScale
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.
xyz
- float array to fill in with (sx, sy, sz)
java.lang.IllegalArgumentException
- if xyz.length < 3
java.lang.IllegalStateException
- if the node transformation is not in component based formsetScale
public void setTranslation(float tx, float ty, float tz)
Sets the translation of the node transformation.
tx
- translation along the X axisty
- translation along the Y axistz
- translation along the Z axis
java.lang.IllegalStateException
- if the node transformation is not in component based formgetTranslation
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.
xyz
- float array to fill in with (tx, ty, tz)
java.lang.IllegalArgumentException
- if xyz.length < 3
java.lang.IllegalStateException
- if the node transformation is not in component based formsetTranslation
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.
transform
- the transform to copy as the new node transformation, or null
java.lang.IllegalArgumentException
- if the bottom row of transform
is not (0 0 0 1)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.
transform
- transform object to receive the node transformationsetTransform
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.
target
- transformation target nodetransform
- transform object to receive the transformation; if
there is no transformation, the contents of the object are undefined
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.
zReference
- the node to use as reference for aligning the
Z axis of this node, or null to align to the current camerazTarget
- 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 allyReference
- the node to use as reference for aligning the
Y axis of this node, or null to align to the current camerayTarget
- 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
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 Nodepublic 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.
alphaFactor
- the new alpha factor for this node; must be [0,1]
java.lang.IllegalArgumentException
- if alphaFactor
is
negative or greater than 1.0getAlphaFactor
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.
setAlphaFactor
|
JSR-184 Public Review Draft - Apr. 30, 2003. | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |