org.j3d.aviatrix3d
Class BaseGroup

java.lang.Object
  org.j3d.aviatrix3d.SceneGraphObject
      org.j3d.aviatrix3d.Node
          org.j3d.aviatrix3d.BaseNode
              org.j3d.aviatrix3d.BaseGroup

All Implemented Interfaces:

TransformHierarchy

Direct Known Subclasses:

Billboard, LODGroup, MarkerGroup

public abstract class BaseGroup
extends BaseNode
implements TransformHierarchy

Abstracted verson of the Group node designed for extension by 3rd-party node implementors.

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. Picking is enabled by default.

Implementors notes

This class only provides the grouping structure management. It does not label itself as part of the culling or picking systems. It is up to the drive

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.6 $

Author:

Alan Hudson, Justin Couch

Field Summary

protected Node[]	childList The list of children nodes
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 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

Constructor Summary

protected

BaseGroup() 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.
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.
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.
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.
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.BaseNode

checkForCyclicChild, checkForCyclicParent, clearUpdateHandler, removeParent, setLive, setParent, setUpdateHandler

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

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.

Constructor Detail

BaseGroup

protected BaseGroup()

The default constructor

Method Detail

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

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

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