javax.media.j3d
Class Locale

java.lang.Object
  |
  +--javax.media.j3d.Locale

public class Locale

extends java.lang.Object

A Locale object defines a high-resolution position within a VirtualUniverse, and serves as a container for a collection of BranchGroup-rooted subgraphs (branch graphs), at that position. Objects within a Locale are defined using standard double-precision coordinates, relative to the origin of the Locale. This origin defines the Virtual World coordinate system for that Locale.

A Locale object defines methods to set and get its high-resolution coordinates, and methods to add, remove, and enumerate the branch graphs.

See Also:

VirtualUniverse, HiResCoord, BranchGroup

Constructor Summary

Locale(VirtualUniverse universe)
Constructs and initializes a new high resolution Locale object located at (0, 0, 0).

Locale(VirtualUniverse universe, HiResCoord hiRes)
Constructs and initializes a new high resolution Locale object at the location specified by the HiResCoord argument.

Locale(VirtualUniverse universe, int[] x, int[] y, int[] z)
Constructs and initializes a new high resolution Locale object from the parameters provided.

Method Summary

void	addBranchGraph(BranchGroup branchGroup) Add a new branch graph rooted at BranchGroup to the list of branch graphs.
protected void	finalize() Cleans up resources associated with this Locale
java.util.Enumeration	getAllBranchGraphs() Gets an Enumeration object of all branch graphs in this Locale.
void	getHiRes(HiResCoord hiRes) Returns this node's HiResCoord.
VirtualUniverse	getVirtualUniverse() Retrieves the virtual universe within which this Locale object is contained.
int	numBranchGraphs() Get number of branch graphs in this Locale.
SceneGraphPath[]	pickAll(PickShape pickShape) Returns an array referencing all the items that are pickable below this Locale that intersect with PickShape.
SceneGraphPath[]	pickAllSorted(PickShape pickShape) Returns a sorted array of references to all the Pickable items that intersect with the pickShape.
SceneGraphPath	pickAny(PickShape pickShape) Returns a reference to any item that is Pickable below this Locale which intersects with pickShape.
SceneGraphPath	pickClosest(PickShape pickShape) Returns a SceneGraphPath which references the pickable item which is closest to the origin of pickShape.
void	removeBranchGraph(BranchGroup branchGroup) Removes a branch graph rooted at BranchGroup from the list of branch graphs.
void	replaceBranchGraph(BranchGroup oldGroup, BranchGroup newGroup) Replaces the branch graph rooted at oldGroup in the list of branch graphs with the branch graph rooted at newGroup.
void	setHiRes(HiResCoord hiRes) Sets the HiRes coordinate of this Locale to the location specified by the HiRes argument.
void	setHiRes(int[] x, int[] y, int[] z) Sets the HiRes coordinate of this Locale to the location specified by the parameters provided.

Methods inherited from class java.lang.Object

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

Constructor Detail

Locale

public Locale(VirtualUniverse universe)

Constructs and initializes a new high resolution Locale object located at (0, 0, 0).

Parameters:

universe - the virtual universe that will contain this Locale object

Locale

public Locale(VirtualUniverse universe,
              int[] x,
              int[] y,
              int[] z)

Constructs and initializes a new high resolution Locale object from the parameters provided.

Parameters:

universe - the virtual universe that will contain this Locale object

x - an eight element array specifying the x position

y - an eight element array specifying the y position

z - an eight element array specifying the z position

Locale

public Locale(VirtualUniverse universe,
              HiResCoord hiRes)

Constructs and initializes a new high resolution Locale object at the location specified by the HiResCoord argument.

Parameters:

universe - the virtual universe that will contain this Locale object

hiRes - the HiRes coordinate to use in creating this Locale

Method Detail

getVirtualUniverse

public VirtualUniverse getVirtualUniverse()

Retrieves the virtual universe within which this Locale object is contained. A null reference indicates that this Locale has been removed from its VirtualUniverse.

Returns:

the virtual universe within which this Locale object is contained.

setHiRes

public void setHiRes(int[] x,
                     int[] y,
                     int[] z)

Sets the HiRes coordinate of this Locale to the location specified by the parameters provided.

Parameters:

x - an eight element array specifying the x position

y - an eight element array specifying the y position

z - an eight element array specifying the z position

setHiRes

public void setHiRes(HiResCoord hiRes)

Sets the HiRes coordinate of this Locale to the location specified by the HiRes argument.

Parameters:

hiRes - the HiRes coordinate specifying this node's new location

getHiRes

public void getHiRes(HiResCoord hiRes)

Returns this node's HiResCoord.

Parameters:

hiRes - a HiResCoord object that will receive the HiRes coordinate of this Locale node

addBranchGraph

public void addBranchGraph(BranchGroup branchGroup)

Add a new branch graph rooted at BranchGroup to the list of branch graphs.

Parameters:

branchGroup - root of the branch graph to be added

Throws:

java.lang.IllegalStateException - if this Locale has been removed from its VirtualUniverse.

MultipleParentException - if the specified BranchGroup node is already live.

removeBranchGraph

public void removeBranchGraph(BranchGroup branchGroup)

Removes a branch graph rooted at BranchGroup from the list of branch graphs.

Parameters:

branchGroup - root of the branch graph to be removed

Throws:

java.lang.IllegalStateException - if this Locale has been removed from its VirtualUniverse.

CapabilityNotSetException - if the ALLOW_DETACH capability is not set in the specified BranchGroup node.

replaceBranchGraph

public void replaceBranchGraph(BranchGroup oldGroup,
                               BranchGroup newGroup)

Replaces the branch graph rooted at oldGroup in the list of branch graphs with the branch graph rooted at newGroup.

Parameters:

oldGroup - root of the branch graph to be replaced.

newGroup - root of the branch graph that will replace the old branch graph.

Throws:

java.lang.IllegalStateException - if this Locale has been removed from its VirtualUniverse.

CapabilityNotSetException - if the ALLOW_DETACH capability is not set in the old BranchGroup node.

MultipleParentException - if the new BranchGroup node is already live.

numBranchGraphs

public int numBranchGraphs()

Get number of branch graphs in this Locale.

Returns:

number of branch graphs in this Locale.

getAllBranchGraphs

public java.util.Enumeration getAllBranchGraphs()

Gets an Enumeration object of all branch graphs in this Locale.

Returns:

an Enumeration object of all branch graphs.

Throws:

java.lang.IllegalStateException - if this Locale has been removed from its VirtualUniverse.

pickAll

public SceneGraphPath[] pickAll(PickShape pickShape)

Returns an array referencing all the items that are pickable below this Locale that intersect with PickShape. The resultant array is unordered.

Parameters:

pickShape - the description of this picking volume or area.

Throws:

java.lang.IllegalStateException - if this Locale has been removed from its VirtualUniverse.

See Also:

BranchGroup.pickAll(javax.media.j3d.PickShape)

pickAllSorted

public SceneGraphPath[] pickAllSorted(PickShape pickShape)

Returns a sorted array of references to all the Pickable items that intersect with the pickShape. Element [0] references the item closest to origin of PickShape successive array elements are further from the origin
NOTE: If pickShape is of type PickBounds, the resulting array is unordered.

Parameters:

pickShape - the description of this picking volume or area.

Throws:

java.lang.IllegalStateException - if this Locale has been removed from its VirtualUniverse.

See Also:

BranchGroup.pickAllSorted(javax.media.j3d.PickShape)

pickClosest

public SceneGraphPath pickClosest(PickShape pickShape)

Returns a SceneGraphPath which references the pickable item which is closest to the origin of pickShape.
NOTE: If pickShape is of type PickBounds, the return is any pickable node below this Locale.

Parameters:

pickShape - the description of this picking volume or area.

Throws:

java.lang.IllegalStateException - if this Locale has been removed from its VirtualUniverse.

See Also:

BranchGroup.pickClosest(javax.media.j3d.PickShape)

pickAny

public SceneGraphPath pickAny(PickShape pickShape)

Returns a reference to any item that is Pickable below this Locale which intersects with pickShape.

Parameters:

pickShape - the description of this picking volume or area.

Throws:

java.lang.IllegalStateException - if this Locale has been removed from its VirtualUniverse.

See Also:

BranchGroup.pickAny(javax.media.j3d.PickShape)

finalize

protected void finalize()

Cleans up resources associated with this Locale

Overrides:

finalize in class java.lang.Object