Package javax.media.j3d

# Class SceneGraphPath

java.lang.Object
javax.media.j3d.SceneGraphPath

public class SceneGraphPath extends Object
A SceneGraphPath object represents the path from a Locale to a terminal node in the scene graph. This path consists of a Locale, a terminal node, and an array of internal nodes that are in the path from the Locale to the terminal node. The terminal node may be either a Leaf node or a Group node. A valid SceneGraphPath must uniquely identify a specific instance of the terminal node. For nodes that are not under a SharedGroup, the minimal SceneGraphPath consists of the Locale and the terminal node itself. For nodes that are under a SharedGroup, the minimal SceneGraphPath consists of the Locale, the terminal node, and a list of all Link nodes in the path from the Locale to the terminal node. A SceneGraphPath may optionally contain other interior nodes that are in the path. A SceneGraphPath is verified for correctness and uniqueness when it is sent as an argument to other methods of Java 3D.

In the array of internal nodes, the node at index 0 is the node closest to the Locale. The indices increase along the path to the terminal node, with the node at index length-1 being the node closest to the terminal node. The array of nodes does not contain either the Locale (which is not a node) or the terminal node.

When a SceneGraphPath is returned from the picking or collision methods of Java 3D, it will also contain the value of the LocalToVworld transform of the terminal node that was in effect at the time the pick or collision occurred. Note that ENABLE_PICK_REPORTING and ENABLE_COLLISION_REPORTING are disabled by default. This means that the picking and collision methods will return the minimal SceneGraphPath by default.

See Also:
  - `Node.ENABLE_PICK_REPORTING`
  - `Node.ENABLE_COLLISION_REPORTING`
  - `BranchGroup.pickAll(javax.media.j3d.PickShape)`
  - `BranchGroup.pickAllSorted(javax.media.j3d.PickShape)`
  - `BranchGroup.pickClosest(javax.media.j3d.PickShape)`
  - `BranchGroup.pickAny(javax.media.j3d.PickShape)`

## Constructor Summary

Constructors
Constructor
Description
`SceneGraphPath()`
Constructs a SceneGraphPath object with default parameters.
`SceneGraphPath(Locale root, Node object)`
Constructs a new SceneGraphPath object.
`SceneGraphPath(Locale root, Node[] nodes, Node object)`
Constructs a new SceneGraphPath object.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`equals(Object o1)`
Returns true if the Object o1 is of type SceneGraphPath and all of the data members of o1 are equal to the corresponding data members in this SceneGraphPath and if the values of the transforms is equal.
`boolean`
`equals(SceneGraphPath testPath)`
Returns true if all of the data members of path testPath are equal to the corresponding data members in this SceneGraphPath and if the values of the transforms is equal.
`final Locale`
`getLocale()`
Retrieves the path's Locale
`final Node`
`getNode(int index)`
Retrieves the node at the specified index.
`final Node`
`getObject()`
Retrieves the path's terminal node object.
`final Transform3D`
`getTransform()`
Returns a copy of the transform associated with this SceneGraphPath; returns null if there is no transform associated.
`int`
`hashCode()`
Returns a hash number based on the data values in this object.
`final boolean`
`isSamePath(SceneGraphPath testPath)`
Determines whether two SceneGraphPath objects represent the same path in the scene graph; either object might include a different subset of internal nodes; only the internal link nodes, the Locale, and the Node itself are compared.
`final int`
`nodeCount()`
Retrieves the number of nodes in this path.
`final void`
`set(SceneGraphPath newPath)`
Sets this path's values to that of the specified path.
`final void`
`setLocale(Locale newLocale)`
Sets this path's Locale to the specified Locale.
`final void`
`setNode(int index, Node newNode)`
Replaces the node at the specified index with newNode.
`final void`
`setNodes(Node[] nodes)`
Sets this path's node objects to the specified node objects.
`final void`
`setObject(Node object)`
Sets this path's terminal node to the specified node object.
`final void`
`setTransform(Transform3D trans)`
Sets the transform component of this SceneGraphPath to the value of the passed transform.
`String`
`toString()`
Returns a string representation of this object; the string contains the class names of all Nodes in the SceneGraphPath, the toString() method of any associated user data provided by SceneGraphObject.getUserData(), and also prints out the transform, if it is not null.

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

## Constructor Details

### SceneGraphPath

public SceneGraphPath()
Constructs a SceneGraphPath object with default parameters. The default values are as follows:

root : null
object : null
list of (interior) nodes : null
transform : identity

### SceneGraphPath

public SceneGraphPath(Locale root, Node object)
Constructs a new SceneGraphPath object.

Parameters:
  `root` - the Locale object of this path
  `object` - the terminal node of this path

### SceneGraphPath

public SceneGraphPath(Locale root, Node[] nodes, Node object)
Constructs a new SceneGraphPath object.

Parameters:
  `root` - the Locale object of this path
  `nodes` - an array of node objects in the path from the Locale to the terminal node
  `object` - the terminal node of this path

## Method Details

### set

public final void set(SceneGraphPath newPath)
Sets this path's values to that of the specified path.

Parameters:
  `newPath` - the SceneGraphPath to copy

### setLocale

public final void setLocale(Locale newLocale)
Sets this path's Locale to the specified Locale.

Parameters:
  `newLocale` - The new Locale

### setObject

public final void setObject(Node object)
Sets this path's terminal node to the specified node object.

Parameters:
  `object` - the new terminal node

### setNodes

public final void setNodes(Node[] nodes)
Sets this path's node objects to the specified node objects.

Parameters:
  `nodes` - an array of node objects in the path from the Locale to the terminal node

### setNode

public final void setNode(int index, Node newNode)
Replaces the node at the specified index with newNode.

Parameters:
  `index` - the index of the node to replace
  `newNode` - the new node
Throws:
  `NullPointerException` - if the node array pointer is null.

### setTransform

public final void setTransform(Transform3D trans)
Sets the transform component of this SceneGraphPath to the value of the passed transform.

Parameters:
  `trans` - the transform to be copied. trans should be the localToVworld matrix of this SceneGraphPath object.

### getTransform

public final Transform3D getTransform()
Returns a copy of the transform associated with this SceneGraphPath; returns null if there is no transform associated. If this SceneGraphPath was returned by a Java 3D picking or collision method, the local coordinate to virtual world coordinate transform for this scene graph object at the time of the pick or collision is recorded.

Returns:
  the local to VWorld transform

### getLocale

public final Locale getLocale()
Retrieves the path's Locale

Returns:
  this path's Locale

### getObject

public final Node getObject()
Retrieves the path's terminal node object.

Returns:
  the terminal node

### nodeCount

public final int nodeCount()
Retrieves the number of nodes in this path. The number of nodes does not include the Locale or the terminal node object itself.

Returns:
  a count of the number of nodes in this path

### getNode

public final Node getNode(int index)
Retrieves the node at the specified index.

Parameters:
  `index` - the index specifying which node to retrieve
Returns:
  the specified node

### equals

public boolean equals(SceneGraphPath testPath)
Returns true if all of the data members of path testPath are equal to the corresponding data members in this SceneGraphPath and if the values of the transforms is equal.

Parameters:
  `testPath` - the path we will compare this object's path against.
Returns:
  true or false

### equals

public boolean equals(Object o1)
Returns true if the Object o1 is of type SceneGraphPath and all of the data members of o1 are equal to the corresponding data members in this SceneGraphPath and if the values of the transforms is equal.

Overrides:
  `equals` in class `Object`
Parameters:
  `o1` - the object we will compare this SceneGraphPath's path against.
Returns:
  true or false

### hashCode

public int hashCode()
Returns a hash number based on the data values in this object. Two different SceneGraphPath objects with identical data values (ie, returns true for trans.equals(SceneGraphPath) ) will return the same hash number. Two Paths with different data members may return the same hash value, although this is not likely.

Overrides:
  `hashCode` in class `Object`
Returns:
  the integer hash value

### isSamePath

public final boolean isSamePath(SceneGraphPath testPath)
Determines whether two SceneGraphPath objects represent the same path in the scene graph; either object might include a different subset of internal nodes; only the internal link nodes, the Locale, and the Node itself are compared. The paths are not validated for correctness or uniqueness.

Parameters:
  `testPath` - the SceneGraphPath to be compared to this SceneGraphPath
Returns:
  true or false

### toString

public String toString()
Returns a string representation of this object; the string contains the class names of all Nodes in the SceneGraphPath, the toString() method of any associated user data provided by SceneGraphObject.getUserData(), and also prints out the transform, if it is not null.

Overrides:
  `toString` in class `Object`
Returns:
  String representation of this object