org.j3d.aviatrix3d
Class Group

java.lang.Object
  org.j3d.aviatrix3d.SceneGraphObject
      org.j3d.aviatrix3d.Node
          org.j3d.aviatrix3d.Group

All Implemented Interfaces:

GroupPickTarget, PickableObject, PickTarget, Cullable, GroupCullable, TransformHierarchy

Direct Known Subclasses:

Axis, MaskedSwitch, PixelTransform, SharedGroup, SwitchGroup, TransformGroup

public class Group
extends Node
implements TransformHierarchy, PickableObject, GroupPickTarget, GroupCullable

The Group node object is a generic container of other nodes in the scene.

Group nodes have exactly one parent and an arbitrary number of children. The children are rendered in an unspecified order. Null children are allowed but no operation is performed on a null child.

Lights are automatically scoped and culled to the parent group unless the global flag is set to true on them.

Picking is enabled by default.

Internationalisation Resource Names

• invalidChildIndexMsg: Error message when the user provides an index for a child that is < 0 or > the number of children.
• pickTimingMsg: Error message when attempting to pick outside the app update observer callback.
• notPickableMsg: Error message when the user has set the pickmask to zero and then requested a pick directly on this object.

Version:

$Revision: 1.55 $

Author:

Alan Hudson, Justin Couch

Field Summary

protected Node[]	childList The list of children nodes
protected Cullable[]	cullList The list of children nodes represented as cullable
protected int	dirtyBoundsCount Number of currently known dirty child bounds
protected int	lastChild Index to the next place to add items in the nodeList
protected PickTarget[]	pickableList The list of children nodes that are pickable targets
protected int	pickFlags Flag indicating if this object is pickable currently
protected float[]	wkVec1 Temp array for fetching bounds from the children.
protected float[]	wkVec2 Temp array for fetching bounds from the children.

Fields inherited from class org.j3d.aviatrix3d.Node

bounds, implicitBounds, INVALID_BOUNDS, parent

Fields inherited from class org.j3d.aviatrix3d.SceneGraphObject

alive, LISTENER_SET_TIMING_ERR_PROP, updateHandler

Fields inherited from interface org.j3d.aviatrix3d.picking.PickableObject

COLLIDABLE_OBJECT, GENERAL_OBJECT, PROXIMITY_OBJECT, VISIBLE_OBJECT

Fields inherited from interface org.j3d.aviatrix3d.picking.PickTarget

CUSTOM_PICK_TYPE, GROUP_PICK_TYPE, LEAF_PICK_TYPE, SINGLE_PICK_TYPE

Constructor Summary

Group()
The default constructor

Method Summary

void	addChild(Node newChild) Appends the specified child node to this group node's list of children
protected void	checkForCyclicChild(SceneGraphObject parent) Check to see if this node is the same reference as the passed node that is a parent of this node.
boolean	checkPickMask(int mask) Check the given pick mask against the node's internal pick mask representation.
Node[]	getAllChildren() Return an array containing all of this group's children.
Node	getChild(int idx) Retrieves the child node at the specified index in this group node's list of children.
Cullable[]	getCullableChildren() Get the list of children that are valid to be rendered according to the rules of the grouping node.
Cullable	getCullableParent() Get the parent cullable of this instance.
BoundingVolume	getPickableBounds() Get the bounds of this picking target so that testing can be performed on the object.
PickTarget	getPickableChild(int idx) Return the pickable target instance at the given index.
PickTarget[]	getPickableChildren() Return an array containing all of this group's pickable children.
int	getPickMask() Get the current pickable state mask of this object.
int	getPickTargetType() Return the type constant that represents the type of pick target this is.
boolean	hasMultipleParents() Check to see if this cullable is mulitparented.
int	indexOfChild(Node child) Retrieves the index of the specified child node in this group node's list of children.
protected void	markBoundsDirty() Mark this node as having dirty bounds due to one of it's children having their bounds changed.
int	numChildren() Returns the number of children this group contains.
int	numCullableChildren() Returns the number of valid renderable children to process.
int	numPickableChildren() Returns the number of valid pickable child targets to process.
void	pickBatch(PickRequest[] reqs, int numRequests) Check for all intersections against this geometry and it's children to see if there is an intersection with the given set of requests.
void	pickSingle(PickRequest req) Check for all intersections against this geometry and it's children to see if there is an intersection with the given set of requests.
protected void	recomputeBounds() Internal method to recalculate the implicit bounds of this Node.
void	removeAllChildren() Removes all children from the group.
void	removeChild(int idx) Remove the child at the specified index from the group.
void	removeChild(Node child) Removes the specified child from the group.
void	requestBoundsUpdate() Request a recomputation of the bounds of this object.
void	setBounds(BoundingVolume b) Set the bounds to the given explicit value.
void	setChild(Node newChild, int idx) Replaces the child node at the specified index in this group node's list of children with the specified child.
protected void	setLive(boolean state) Notification that this object is live now.
void	setPickMask(int state) Set the node as being pickable currently using the given bit mask.
protected void	setUpdateHandler(NodeUpdateHandler handler) Set the scenegraph update handler for this node.
protected void	updateBounds() Update this node's bounds and then call the parent to update it's bounds.

Methods inherited from class org.j3d.aviatrix3d.Node

boundsChanged, checkForCyclicParent, getBounds, getParent, removeParent, setParent, updateParentBounds

Methods inherited from class org.j3d.aviatrix3d.SceneGraphObject

dataChanged, getAppUpdateWriteTimingMessage, getBoundsWriteTimingMessage, getDataWriteTimingMessage, getUserData, isLive, setUserData

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.j3d.aviatrix3d.rendering.GroupCullable

getBounds

Field Detail

childList

protected Node[] childList

The list of children nodes

lastChild

protected int lastChild

Index to the next place to add items in the nodeList

dirtyBoundsCount

protected int dirtyBoundsCount

Number of currently known dirty child bounds

wkVec1

protected float[] wkVec1

Temp array for fetching bounds from the children.

wkVec2

protected float[] wkVec2

Temp array for fetching bounds from the children.

pickFlags

protected int pickFlags

Flag indicating if this object is pickable currently

pickableList

protected PickTarget[] pickableList

The list of children nodes that are pickable targets

cullList

protected Cullable[] cullList

The list of children nodes represented as cullable

Constructor Detail

Group

public Group()

The default constructor

Method Detail

getCullableChildren

public Cullable[] getCullableChildren()

Get the list of children that are valid to be rendered according to the rules of the grouping node.

Specified by:

getCullableChildren in interface GroupCullable

Returns:

an array of nodes

numCullableChildren

public int numCullableChildren()

Returns the number of valid renderable children to process. If there are no valid renderable children return -1.

Specified by:

numCullableChildren in interface GroupCullable

Returns:

A number greater than or equal to zero or -1

hasMultipleParents

public boolean hasMultipleParents()

Check to see if this cullable is mulitparented. If it is, then that will cause problems for code that needs to know information like the transformation to the root of the scene graph.

Specified by:

hasMultipleParents in interface GroupCullable

Returns:

true if there are multiple parents

getCullableParent

public Cullable getCullableParent()

Get the parent cullable of this instance. If this node has multiple direct parents, then this should return null.

Specified by:

getCullableParent in interface GroupCullable

Returns:

The parent instance or null if none

setBounds

public void setBounds(BoundingVolume b)

Set the bounds to the given explicit value. When set, auto computation of the bounds of this node is turned off. A value of null can be used to clear the current explicit bounds and return to auto computation.

Overrides:

setBounds in class Node

Parameters:

b - The new bounds to use or null to clear

markBoundsDirty

protected void markBoundsDirty()

Mark this node as having dirty bounds due to one of it's children having their bounds changed.

Overrides:

markBoundsDirty in class Node

updateBounds

protected void updateBounds()

Update this node's bounds and then call the parent to update it's bounds. Used to propogate bounds changes from the leaves of the tree to the root. A node implementation may decide when and where to tell the parent(s)s that updates are ready.

Overrides:

updateBounds in class Node

recomputeBounds

protected void recomputeBounds()

Internal method to recalculate the implicit bounds of this Node. By default the bounds are a point sphere, so derived classes should override this method with something better.

Overrides:

recomputeBounds in class Node

requestBoundsUpdate

public void requestBoundsUpdate()

Request a recomputation of the bounds of this object. If this object is not currently live, you can request a recompute of the bounds to get the most current values. If this node is currently live, then the request is ignored.

This will recurse down the children asking all of them to recompute the bounds. If a child is found to be during this process, that branch will not update, and thus the value used will be the last updated (ie from the previous frame it was processed).

Overrides:

requestBoundsUpdate in class Node

checkForCyclicChild

protected void checkForCyclicChild(SceneGraphObject parent)
                            throws CyclicSceneGraphStructureException

Check to see if this node is the same reference as the passed node that is a parent of this node. This is the downwards check to ensure that there is no cyclic scene graph structures at the point where someone adds a node to the scenegraph. When the reference and this are the same, an exception is generated. Since each class may have different lists of child node setups, this should be overriden by any class that can take children, and have the call passed along to the children.

Overrides:

checkForCyclicChild in class SceneGraphObject

Parameters:

parent - The reference to check against this class

Throws:

CyclicSceneGraphStructureException - Equal parent and child

setUpdateHandler

protected void setUpdateHandler(NodeUpdateHandler handler)

Set the scenegraph update handler for this node. It will notify all its children of the value. A null value will clear the current handler.

Overrides:

setUpdateHandler in class SceneGraphObject

Parameters:

handler - The instance to use as a handler

setLive

protected void setLive(boolean state)

Notification that this object is live now.

Overrides:

setLive in class SceneGraphObject

Parameters:

state - true if this should be marked as live now

setPickMask

public void setPickMask(int state)

Set the node as being pickable currently using the given bit mask. A mask of 0 will completely disable picking.

Specified by:

setPickMask in interface PickableObject

Parameters:

state - A bit mask of available options to pick for

getPickMask

public int getPickMask()

Get the current pickable state mask of this object. A value of zero means it is completely unpickable.

Specified by:

getPickMask in interface PickableObject

Returns:

A bit mask of available options to pick for

pickBatch

public void pickBatch(PickRequest[] reqs,
                      int numRequests)
               throws NotPickableException,
                      InvalidPickTimingException

Check for all intersections against this geometry and it's children to see if there is an intersection with the given set of requests.

Specified by:

pickBatch in interface PickableObject

Parameters:

reqs - The list of picks to be made, starting at this object

numRequests - The number of valid pick requests to process

Throws:

NotPickableException - This object has been marked as non pickable, but you decided to try to call the method anyway

InvalidPickTimingException - An attempt was made to pick outside of the ApplicationUpdateObserver callback method

pickSingle

public void pickSingle(PickRequest req)
                throws NotPickableException,
                       InvalidPickTimingException

Check for all intersections against this geometry and it's children to see if there is an intersection with the given set of requests.

Specified by:

pickSingle in interface PickableObject

Parameters:

req - The details of the pick to be made

Throws:

NotPickableException - This object has been marked as non pickable, but you decided to try to call the method anyway

InvalidPickTimingException - An attempt was made to pick outside of the ApplicationUpdateObserver callback method

numPickableChildren

public int numPickableChildren()

Returns the number of valid pickable child targets to process. If there are no valid children return -1.

Specified by:

numPickableChildren in interface GroupPickTarget

Returns:

A number greater than or equal to zero or -1

getPickableChildren

public PickTarget[] getPickableChildren()

Return an array containing all of this group's pickable children. This structure is the nodes internal representation. Check the numPickableChildren() call for how many valid objects are part of this array. If there are none, this may return either a null or a valid array, depending on the implementation.

The list may contain null values.

Specified by:

getPickableChildren in interface GroupPickTarget

Returns:

An array of pick targets

getPickableChild

public PickTarget getPickableChild(int idx)

Return the pickable target instance at the given index. If there is nothing at the given index, null will be returned.

Specified by:

getPickableChild in interface GroupPickTarget

Parameters:

idx - The index of the child to get

Returns:

The target object at the given index.

getPickTargetType

public final int getPickTargetType()

Return the type constant that represents the type of pick target this is. Used to provided optimised picking implementations.

Specified by:

getPickTargetType in interface PickTarget

Returns:

One of the _PICK_TYPE constants

checkPickMask

public boolean checkPickMask(int mask)

Check the given pick mask against the node's internal pick mask representation. If there is a match in one or more bitfields then this will return true, allowing picking to continue to process for this target.

Specified by:

checkPickMask in interface PickTarget

Parameters:

mask - The bit mask to check against

Returns:

true if the mask has an overlapping set of bitfields

getPickableBounds

public BoundingVolume getPickableBounds()

Get the bounds of this picking target so that testing can be performed on the object.

Specified by:

getPickableBounds in interface PickTarget

Returns:

A representation of the volume representing the pickable objects

addChild

public void addChild(Node newChild)
              throws AlreadyParentedException,
                     InvalidWriteTimingException

Appends the specified child node to this group node's list of children

Parameters:

newChild - The child to add

Throws:

AlreadyParentedException - There is a valid parent already set

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method

setChild

public void setChild(Node newChild,
                     int idx)
              throws AlreadyParentedException,
                     InvalidWriteTimingException

Replaces the child node at the specified index in this group node's list of children with the specified child.

Parameters:

newChild - The child node to use

idx - The index to replace. Must be greater than 0 and less then numChildren

Throws:

java.lang.IndexOutOfBoundsException - When the idx is invalid

AlreadyParentedException - There is a valid parent already set

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method

removeChild

public void removeChild(int idx)
                 throws InvalidWriteTimingException

Remove the child at the specified index from the group.

Parameters:

idx - The index of the child to remove

Throws:

IndexOfBoundsException - When the idx is invalid

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method

getChild

public Node getChild(int idx)

Retrieves the child node at the specified index in this group node's list of children.

Returns:

The node at the given index

Throws:

java.lang.IndexOutOfBoundsException - If the idx is invalid

getAllChildren

public Node[] getAllChildren()

Return an array containing all of this group's children. This structure is the nodes internal representation. Check the numChildren call to determine how many entries are valid.

Returns:

An array of nodes

numChildren

public int numChildren()

Returns the number of children this group contains.

Returns:

The number of children

indexOfChild

public int indexOfChild(Node child)

Retrieves the index of the specified child node in this group node's list of children.

Parameters:

child - The child to find

Returns:

the index of the child or -1 if not found

removeChild

public void removeChild(Node child)
                 throws InvalidWriteTimingException

Removes the specified child from the group. If the child does not exist its silently ignored.

Parameters:

child - The child to remove

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method

removeAllChildren

public void removeAllChildren()
                       throws InvalidWriteTimingException

Removes all children from the group.

Throws:

InvalidWriteTimingException - An attempt was made to write outside of the NodeUpdateListener bounds callback method