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.

  For more information, see the Introduction to the Java 3D API and Scene Graph Superstructure documents.

  See Also:
    `VirtualUniverse`, `HiResCoord`, `BranchGroup`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addBranchGraph(BranchGroup branchGroup)` Add a new branch graph rooted at BranchGroup to the list of branch graphs.
    `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.
    `PickInfo[]` | `pickAll(int mode, int flags, PickShape pickShape)` Returns an array unsorted references to all the PickInfo objects that are pickable below this `Locale` that intersect with PickShape.
    `SceneGraphPath[]` | `pickAll(PickShape pickShape)` Returns an array referencing all the items that are pickable below this `Locale` that intersect with PickShape.
    `PickInfo[]` | `pickAllSorted(int mode, int flags, PickShape pickShape)` Returns a sorted array of PickInfo references to all the pickable items that intersect with the pickShape.
    `SceneGraphPath[]` | `pickAllSorted(PickShape pickShape)` Returns a sorted array of references to all the pickable items that intersect with the pickShape.
    `PickInfo` | `pickAny(int mode, int flags, PickShape pickShape)` Returns a PickInfo which references the pickable item below this Locale which intersects with `pickShape`.
    `SceneGraphPath` | `pickAny(PickShape pickShape)` Returns a reference to any item that is Pickable below this Locale which intersects with `pickShape`.
    `PickInfo` | `pickClosest(int mode, int flags, PickShape pickShape)` Returns a PickInfo which references the pickable item which is closest to the origin of `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, finalize, 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)`

    - #### pickAll

          public PickInfo[] pickAll(int mode,
                           int flags,
                           PickShape pickShape)

      Returns an array unsorted references to all the PickInfo objects that are pickable below this `Locale` that intersect with PickShape. The accuracy of the pick is set by the pick mode. The mode include : PickInfo.PICK_BOUNDS and PickInfo.PICK_GEOMETRY. The amount of information returned is specified via a masked variable, flags, indicating which components are present in each returned PickInfo object.
      Parameters:
        `mode` - picking mode, one of `PickInfo.PICK_BOUNDS` or `PickInfo.PICK_GEOMETRY`.
        `flags` - a mask indicating which components are present in each PickInfo object. This is specified as one or more individual bits that are bitwise "OR"ed together to describe the PickInfo data. The flags include :
        `PickInfo.SCENEGRAPHPATH` - request for computed SceneGraphPath.
        `PickInfo.NODE` - request for computed intersected Node.
        `PickInfo.LOCAL_TO_VWORLD` - request for computed local to virtual world transform.
        `PickInfo.CLOSEST_INTERSECTION_POINT` - request for closest intersection point.
        `PickInfo.CLOSEST_DISTANCE` - request for the distance of closest intersection.
        `PickInfo.CLOSEST_GEOM_INFO` - request for only the closest intersection geometry information.
        `PickInfo.ALL_GEOM_INFO` - request for all intersection geometry information.
        `pickShape` - the description of this picking volume or area.
      Throws:
        `java.lang.IllegalArgumentException` - if flags contains both CLOSEST_GEOM_INFO and ALL_GEOM_INFO.
        `java.lang.IllegalArgumentException` - if pickShape is a PickPoint and pick mode is set to PICK_GEOMETRY.
        `java.lang.IllegalArgumentException` - if pick mode is neither PICK_BOUNDS nor PICK_GEOMETRY.
        `java.lang.IllegalArgumentException` - if pick mode is PICK_BOUNDS and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
        `java.lang.IllegalArgumentException` - if pickShape is PickBounds and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
        `java.lang.IllegalStateException` - if this Locale has been removed from its VirtualUniverse.
        `CapabilityNotSetException` - if the mode is PICK_GEOMETRY and the Geometry.ALLOW_INTERSECT capability bit is not set in any Geometry objects referred to by any shape node whose bounds intersects the PickShape.
        `CapabilityNotSetException` - if flags contains any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO, and the capability bits that control reading of coordinate data are not set in any GeometryArray object referred to by any shape node that intersects the PickShape. The capability bits that must be set to avoid this exception are as follows :
        - By-copy geometry : GeometryArray.ALLOW_COORDINATE_READ
        - By-reference geometry : GeometryArray.ALLOW_REF_DATA_READ
        - Indexed geometry : IndexedGeometryArray.ALLOW_COORDINATE_INDEX_READ (in addition to one of the above)
      Since:
        Java 3D 1.4
      See Also:
        `BranchGroup.pickAll(int,int,javax.media.j3d.PickShape)`, `PickInfo`

    - #### 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)`

    - #### pickAllSorted

          public PickInfo[] pickAllSorted(int mode,
                                 int flags,
                                 PickShape pickShape)

      Returns a sorted array of PickInfo 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 The accuracy of the pick is set by the pick mode. The mode include : PickInfo.PICK_BOUNDS and PickInfo.PICK_GEOMETRY. The amount of information returned is specified via a masked variable, flags, indicating which components are present in each returned PickInfo object.
      Parameters:
        `mode` - picking mode, one of `PickInfo.PICK_BOUNDS` or `PickInfo.PICK_GEOMETRY`.
        `flags` - a mask indicating which components are present in each PickInfo object. This is specified as one or more individual bits that are bitwise "OR"ed together to describe the PickInfo data. The flags include :
        `PickInfo.SCENEGRAPHPATH` - request for computed SceneGraphPath.
        `PickInfo.NODE` - request for computed intersected Node.
        `PickInfo.LOCAL_TO_VWORLD` - request for computed local to virtual world transform.
        `PickInfo.CLOSEST_INTERSECTION_POINT` - request for closest intersection point.
        `PickInfo.CLOSEST_DISTANCE` - request for the distance of closest intersection.
        `PickInfo.CLOSEST_GEOM_INFO` - request for only the closest intersection geometry information.
        `PickInfo.ALL_GEOM_INFO` - request for all intersection geometry information.
        `pickShape` - the description of this picking volume or area.
      Throws:
        `java.lang.IllegalArgumentException` - if flags contains both CLOSEST_GEOM_INFO and ALL_GEOM_INFO.
        `java.lang.IllegalArgumentException` - if pickShape is a PickPoint and pick mode is set to PICK_GEOMETRY.
        `java.lang.IllegalArgumentException` - if pick mode is neither PICK_BOUNDS nor PICK_GEOMETRY.
        `java.lang.IllegalArgumentException` - if pick mode is PICK_BOUNDS and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
        `java.lang.IllegalArgumentException` - if pickShape is PickBounds and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
        `java.lang.IllegalStateException` - if this Locale has been removed from its VirtualUniverse.
        `CapabilityNotSetException` - if the mode is PICK_GEOMETRY and the Geometry.ALLOW_INTERSECT capability bit is not set in any Geometry objects referred to by any shape node whose bounds intersects the PickShape.
        `CapabilityNotSetException` - if flags contains any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO, and the capability bits that control reading of coordinate data are not set in any GeometryArray object referred to by any shape node that intersects the PickShape. The capability bits that must be set to avoid this exception are as follows :
        - By-copy geometry : GeometryArray.ALLOW_COORDINATE_READ
        - By-reference geometry : GeometryArray.ALLOW_REF_DATA_READ
        - Indexed geometry : IndexedGeometryArray.ALLOW_COORDINATE_INDEX_READ (in addition to one of the above)
      Since:
        Java 3D 1.4
      See Also:
        `BranchGroup.pickAllSorted(int,int,javax.media.j3d.PickShape)`, `PickInfo`

    - #### 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)`

    - #### pickClosest

          public PickInfo pickClosest(int mode,
                             int flags,
                             PickShape pickShape)

      Returns a PickInfo which references the pickable item which is closest to the origin of `pickShape`. The accuracy of the pick is set by the pick mode. The mode include : PickInfo.PICK_BOUNDS and PickInfo.PICK_GEOMETRY. The amount of information returned is specified via a masked variable, flags, indicating which components are present in each returned PickInfo object.
      Parameters:
        `mode` - picking mode, one of `PickInfo.PICK_BOUNDS` or `PickInfo.PICK_GEOMETRY`.
        `flags` - a mask indicating which components are present in each PickInfo object. This is specified as one or more individual bits that are bitwise "OR"ed together to describe the PickInfo data. The flags include :
        `PickInfo.SCENEGRAPHPATH` - request for computed SceneGraphPath.
        `PickInfo.NODE` - request for computed intersected Node.
        `PickInfo.LOCAL_TO_VWORLD` - request for computed local to virtual world transform.
        `PickInfo.CLOSEST_INTERSECTION_POINT` - request for closest intersection point.
        `PickInfo.CLOSEST_DISTANCE` - request for the distance of closest intersection.
        `PickInfo.CLOSEST_GEOM_INFO` - request for only the closest intersection geometry information.
        `PickInfo.ALL_GEOM_INFO` - request for all intersection geometry information.
        `pickShape` - the description of this picking volume or area.
      Throws:
        `java.lang.IllegalArgumentException` - if flags contains both CLOSEST_GEOM_INFO and ALL_GEOM_INFO.
        `java.lang.IllegalArgumentException` - if pickShape is a PickPoint and pick mode is set to PICK_GEOMETRY.
        `java.lang.IllegalArgumentException` - if pick mode is neither PICK_BOUNDS nor PICK_GEOMETRY.
        `java.lang.IllegalArgumentException` - if pick mode is PICK_BOUNDS and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
        `java.lang.IllegalArgumentException` - if pickShape is PickBounds and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
        `java.lang.IllegalStateException` - if this Locale has been removed from its VirtualUniverse.
        `CapabilityNotSetException` - if the mode is PICK_GEOMETRY and the Geometry.ALLOW_INTERSECT capability bit is not set in any Geometry objects referred to by any shape node whose bounds intersects the PickShape.
        `CapabilityNotSetException` - if flags contains any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO, and the capability bits that control reading of coordinate data are not set in any GeometryArray object referred to by any shape node that intersects the PickShape. The capability bits that must be set to avoid this exception are as follows :
        - By-copy geometry : GeometryArray.ALLOW_COORDINATE_READ
        - By-reference geometry : GeometryArray.ALLOW_REF_DATA_READ
        - Indexed geometry : IndexedGeometryArray.ALLOW_COORDINATE_INDEX_READ (in addition to one of the above)
      Since:
        Java 3D 1.4
      See Also:
        `BranchGroup.pickClosest(int,int,javax.media.j3d.PickShape)`, `PickInfo`

    - #### 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)`

    - #### pickAny

          public PickInfo pickAny(int mode,
                         int flags,
                         PickShape pickShape)

      Returns a PickInfo which references the pickable item below this Locale which intersects with `pickShape`. The accuracy of the pick is set by the pick mode. The mode include : PickInfo.PICK_BOUNDS and PickInfo.PICK_GEOMETRY. The amount of information returned is specified via a masked variable, flags, indicating which components are present in each returned PickInfo object.
      Parameters:
        `mode` - picking mode, one of `PickInfo.PICK_BOUNDS` or `PickInfo.PICK_GEOMETRY`.
        `flags` - a mask indicating which components are present in each PickInfo object. This is specified as one or more individual bits that are bitwise "OR"ed together to describe the PickInfo data. The flags include :
        `PickInfo.SCENEGRAPHPATH` - request for computed SceneGraphPath.
        `PickInfo.NODE` - request for computed intersected Node.
        `PickInfo.LOCAL_TO_VWORLD` - request for computed local to virtual world transform.
        `PickInfo.CLOSEST_INTERSECTION_POINT` - request for closest intersection point.
        `PickInfo.CLOSEST_DISTANCE` - request for the distance of closest intersection.
        `PickInfo.CLOSEST_GEOM_INFO` - request for only the closest intersection geometry information.
        `PickInfo.ALL_GEOM_INFO` - request for all intersection geometry information.
        `pickShape` - the description of this picking volume or area.
      Throws:
        `java.lang.IllegalArgumentException` - if flags contains both CLOSEST_GEOM_INFO and ALL_GEOM_INFO.
        `java.lang.IllegalArgumentException` - if pickShape is a PickPoint and pick mode is set to PICK_GEOMETRY.
        `java.lang.IllegalArgumentException` - if pick mode is neither PICK_BOUNDS nor PICK_GEOMETRY.
        `java.lang.IllegalArgumentException` - if pick mode is PICK_BOUNDS and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
        `java.lang.IllegalArgumentException` - if pickShape is PickBounds and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
        `java.lang.IllegalStateException` - if this Locale has been removed from its VirtualUniverse.
        `CapabilityNotSetException` - if the mode is PICK_GEOMETRY and the Geometry.ALLOW_INTERSECT capability bit is not set in any Geometry objects referred to by any shape node whose bounds intersects the PickShape.
        `CapabilityNotSetException` - if flags contains any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO, and the capability bits that control reading of coordinate data are not set in any GeometryArray object referred to by any shape node that intersects the PickShape. The capability bits that must be set to avoid this exception are as follows :
        - By-copy geometry : GeometryArray.ALLOW_COORDINATE_READ
        - By-reference geometry : GeometryArray.ALLOW_REF_DATA_READ
        - Indexed geometry : IndexedGeometryArray.ALLOW_COORDINATE_INDEX_READ (in addition to one of the above)
      Since:
        Java 3D 1.4
      See Also:
        `BranchGroup.pickAny(int,int,javax.media.j3d.PickShape)`, `PickInfo`

Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.