javax.microedition.m3d
Class Group

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

Direct Known Subclasses:

World

public class Group

extends Node

The Group node stores an unordered set of nodes as its children in the scene graph. If a node is added to this Group, the getParent method of that node will thereafter return this Group.

A node can belong to at most one group at a time, and cycles are prohibited. Furthermore, a World node cannot belong to any group. These rules are enforced by the addChild method.

See Also:

Binary format

Field Summary

Fields inherited from class javax.microedition.m3d.Node

NONE, ORIGIN, X_AXIS, Y_AXIS, Z_AXIS

Fields inherited from class javax.microedition.m3d.Object3D

userObject

Constructor Summary

Group()
Constructs a new Group node and initializes it with an empty list of children.

Method Summary

void	addChild(Node child) Adds the given node to this Group, potentially changing the order and indices of the previously added children.
Node	getChild(int index) Gets a child by index.
int	getChildCount() Gets the number of children in this Group.
boolean	pick(int mask, float ox, float oy, float oz, float dx, float dy, float dz, Node alignTo, RayIntersection ri) Picks the first enabled Mesh or Sprite in this Group that is intercepted by the given pick ray and is in the specified scope.
void	removeChild(Node child) Removes the given node from this Group, potentially changing the order and indices of the remaining children.

Methods inherited from class javax.microedition.m3d.Node

getAlphaFactor, getOrientation, getParent, getScale, getScopeID, getTransform, getTransformTo, getTranslation, isEnabled, setAlignment, setAlphaFactor, setEnable, setOrientation, setScale, setScopeID, setTransform, setTranslation

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

Constructor Detail

Group

public Group()

Constructs a new Group node and initializes it with an empty list of children. Properties inherited from Object3D and Node will have the default values as specified in their respective class descriptions.

Method Detail

addChild

public void addChild(Node child)

Adds the given node to this Group, potentially changing the order and indices of the previously added children. The position at which the node is inserted among the existing children is deliberately left undefined. This gives implementations the freedom to select a data structure that best fits their needs, instead of mandating a particular kind of data structure.

Parameters:

child - the node to add; must not form a loop in the scene graph

Throws:

java.lang.IllegalArgumentException - if child is this Group

java.lang.IllegalArgumentException - if child is a World node

java.lang.IllegalArgumentException - if child already has a parent

java.lang.IllegalArgumentException - if child is an ancestor of this Group

removeChild

public void removeChild(Node child)

Removes the given node from this Group, potentially changing the order and indices of the remaining children. If the given node is not a child of this Group, the request to remove it is silently ignored.

Parameters:

child - the node to remove

getChildCount

public int getChildCount()

Gets the number of children in this Group.

Returns:

the number of children directly attached to this group

getChild

public Node getChild(int index)

Gets a child by index. Valid indices range from zero up to the number of children minus one. Note that the index of any child may change whenever a node is added to or removed from this Group. See addChild for more information.

Parameters:

index - index of the child node to get

Returns:

the child node at the given index

Throws:

java.lang.IndexOutOfBoundsException - if index is not in [0, N-1], where N is the number of children returned by getChildCount

pick

public boolean pick(int mask,
                    float ox,
                    float oy,
                    float oz,
                    float dx,
                    float dy,
                    float dz,
                    Node alignTo,
                    RayIntersection ri)

Picks the first enabled Mesh or Sprite in this Group that is intercepted by the given pick ray and is in the specified scope. Nodes that are disabled or out scope are ignored. Any ancestors of this Group, as well as any properties inherited from them, are also ignored. Information about the picked object, if any, is filled in to the given RayIntersection object. If no intersection occurs, the RayIntersection object is left unmodified.

The pick ray is cast in the given direction from the given location in the coordinate system of this Group. The direction vector of the ray does not need to be unit length.

A node whose scope membership ID does not match with the given scope mask is not picked, even if it would intersect the pick ray. A scope ID is defined to match with a mask if and only if scopeID & mask != 0, where & denotes bitwise AND.

Sprites and other nodes that are aligned to the current camera when rendering are here aligned in the same way to the alignTo node that is given as a parameter. The reference node must be supplied explicitly, because otherwise the implementation has no way of knowing which camera the application wishes to use. In the typical case, the application would pass in the active camera of the World that this Group belongs to.

Parameters:

mask - a bitmask specifying which Nodes to test for intersection

ox - X coordinate of the ray origin

oy - Y coordinate of the ray origin

oz - Z coordinate of the ray origin

dx - X component of the ray direction

dy - Y component of the ray direction

dz - Z component of the ray direction

alignTo - a reference node to serve as the "current camera" for sprites and other aligned nodes, or null to use the coordinate system of this Group instead

ri - a RayIntersection object to fill in with information about the intersected Mesh or Sprite, or null to just find out whether the ray intersected something or not

Returns:

true if the ray intersected a visible Node; false otherwise

Throws:

java.lang.IllegalArgumentException - if dx = dy = dz = 0

java.lang.IllegalStateException - if any Mesh that is tested for intersection violates the constraints defined in Mesh, MorphingMesh, SkinnedMesh, VertexBuffer, or IndexBuffer

java.lang.IllegalStateException - if there is no transformation between alignTo and this Group (see also Node.getTransformTo(javax.microedition.m3d.Node, javax.microedition.m3d.Transform)).

See Also:

Camera.pick