edu.umd.cs.jazz.util
Class ZSceneGraphPath

java.lang.Object
  |
  +--edu.umd.cs.jazz.util.ZSceneGraphPath

All Implemented Interfaces:

java.io.Serializable

public final class ZSceneGraphPath

extends java.lang.Object

implements java.io.Serializable

ZSceneGraphPath represents a unique path in a scene graph from a top-level camera to a terminal node. The path is typically used in event handlers to determine what object is under the mouse pointer, and what camera(s) that object was rendered within. The path is typically generated by @link(ZDrawingSurface#pick). The terminal node can be a node or visual component, but is typically a visual component, or null. One exception to this is that if a group's children are not pickable than the group itself will be the terminal object if one if its children was actually picked. Also, cameras are not picked as objects, and thus do not typically appear as a terminal object.

The path also encapsulates a transform, indicating the composited transform from the top-level camera to the terminal object, possibly going through zero or more internal cameras. Even when the terminal object is null, the transform contains the complete transform through all the cameras that the mouse pointer is over (for pick operations).

The path also holds a list of the cameras traversed by the path. As with the transform, even if the terminal object is null, the camea list contains all the cameras the mouse pointer is over (for pick operations).

Warning: Serialized and ZSerialized objects of this class will not be compatible with future Jazz releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Jazz. A future release of Jazz will provide support for long term persistence.

See Also:

ZDrawingSurface.pick(int, int), Serialized Form

Constructor Summary

ZSceneGraphPath()
Constructs a new ZSceneGraphPath.

Method Summary

ZCamera	getCamera() Returns the nearest ZCamera to the picked object.
ZCamera	getCamera(int i) Returns the i'th camera between the root and the terminal object.
boolean	getCameraFound() Internal method.
ZNode	getNode() Returns the nearest ZNode to the picked object.
int	getNumCameras() Returns the number of internal cameras between the root and the terminal object.
int	getNumParents() Returns the number of internal ZSceneGraphObjects between the root and the terminal object.
ZSceneGraphObject	getObject() Returns the terminal object in the path.
ZSceneGraphObject	getParent(int i) Returns the i'th scene graph object between the root and the terminal object.
ZRoot	getRoot() Returns the root node for this path.
ZCamera	getTopCamera() Returns the top-level camera in the path.
ZNode	getTopCameraNode() Returns the node associated with the top-level camera in the path.
java.awt.geom.AffineTransform	getTransform() Returns the transform for this path.
void	pop(ZSceneGraphObject sgo) Removes a node (and any nodes after it) from the list of parent nodes.
void	popCamera(ZCamera camera) Removes a camera (and any cameras after it) from the list of camera nodes.
void	popTransformer(ZSceneGraphObject transformer) Removes a transformer (and any transformers after it) from the list of transformer nodes.
void	push(ZSceneGraphObject sgo) Adds a node to the end of the list of parent nodes.
void	pushCamera(ZCamera camera) Adds a node to the end of the list of camera nodes.
void	pushTransformer(ZSceneGraphObject transformer) Internal method.
void	screenToGlobal(java.awt.geom.Point2D pt) Converts the specified point from screen coordinates to global coordinates through the top-level camera of this path.
void	screenToGlobal(java.awt.geom.Rectangle2D rect) Converts the specified rectangle from screen coordinates to global coordinates through the top-level camera of this path.
void	screenToLocal(java.awt.geom.Point2D pt) Converts the specified point from screen coordinates to the local coordinate system of the terminal scene graph object in this path.
void	screenToLocal(java.awt.geom.Rectangle2D rect) Converts the specified rectangle from screen coordinates to the local coordinate system of the terminal scene graph object in this path.
void	setCameraFound(boolean cf) Internal method.
void	setObject(ZSceneGraphObject object) Sets the terminal object in the path.
void	setRoot(ZRoot root) Sets the root node for this path.
void	setTopCamera(ZCamera camera) Sets the top-level camera in the path.
void	setTopCameraNode(ZNode node) Sets the node associated with the top-level camera in the path.
void	setTransform(java.awt.geom.AffineTransform tm) Sets the transform for this path.
java.lang.String	toString() Returns a string description of this path useful for debugging.
void	trimCamerasToSize() Trims the capacity of the array that stores the cameras to the actual number of points.
void	trimToSize() Trims the capacity of the array that stores the parents list points to the actual number of points.
void	trimTransformersToSize() Trims the capacity of the array that stores the transformers to the actual number of points.
void	updateTransform() Update the path's transform.

Methods inherited from class java.lang.Object

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

Constructor Detail

ZSceneGraphPath

public ZSceneGraphPath()

Constructs a new ZSceneGraphPath.

Method Detail

getObject

public ZSceneGraphObject getObject()

Returns the terminal object in the path. This is either a ZVisualComponent or a ZNode.

setObject

public void setObject(ZSceneGraphObject object)

Sets the terminal object in the path.

getTopCameraNode

public ZNode getTopCameraNode()

Returns the node associated with the top-level camera in the path. Even if the path is empty, this node is guaranteed to be set.

setTopCameraNode

public void setTopCameraNode(ZNode node)

Sets the node associated with the top-level camera in the path.

getTopCamera

public ZCamera getTopCamera()

Returns the top-level camera in the path. This is the first camera that the object was picked within. Even if the path is empty, this camera is guaranteed to be set.

setTopCamera

public void setTopCamera(ZCamera camera)

Sets the top-level camera in the path.

getNode

public ZNode getNode()

Returns the nearest ZNode to the picked object. If the picked object is a ZNode, this simply returns that object. If the picked object is a ZVisualComponent, this returns the first ZNode parent of the component.

Returns:

the node.

getCamera

public ZCamera getCamera()

Returns the nearest ZCamera to the picked object. That is, this returns the last camera on the path. If the path is empty, it returns the top-level camera.

Returns:

the camera.

getRoot

public ZRoot getRoot()

Returns the root node for this path.

setRoot

public void setRoot(ZRoot root)

Sets the root node for this path.

getTransform

public java.awt.geom.AffineTransform getTransform()

Returns the transform for this path. This is formed by compositing the all the transforms of the scene graph objects in this path. This resulting transform represents the local coordinate system of the terminal element of this path. If the path is empty, then the transform contains the concatenated transforms of the cameras the mouse pointer is over (for pick operations).

setTransform

public void setTransform(java.awt.geom.AffineTransform tm)

Sets the transform for this path.

screenToGlobal

public void screenToGlobal(java.awt.geom.Point2D pt)

Converts the specified point from screen coordinates to global coordinates through the top-level camera of this path.

Parameters:

pt - The pt to be transformed

screenToGlobal

public void screenToGlobal(java.awt.geom.Rectangle2D rect)

Converts the specified rectangle from screen coordinates to global coordinates through the top-level camera of this path.

Parameters:

rect - The rect to be transformed

screenToLocal

public void screenToLocal(java.awt.geom.Point2D pt)

Converts the specified point from screen coordinates to the local coordinate system of the terminal scene graph object in this path.

Parameters:

pt - The pt to be transformed

screenToLocal

public void screenToLocal(java.awt.geom.Rectangle2D rect)

Converts the specified rectangle from screen coordinates to the local coordinate system of the terminal scene graph object in this path.

Parameters:

rect - The rect to be transformed

getNumParents

public int getNumParents()

Returns the number of internal ZSceneGraphObjects between the root and the terminal object.

getParent

public ZSceneGraphObject getParent(int i)

Returns the i'th scene graph object between the root and the terminal object. The parent at position 0 is closest to the root, and the parent at the last position is closest to the terminal object.

Parameters:

i - The index of the path element to return

Returns:

The scene graph object

push

public void push(ZSceneGraphObject sgo)

Adds a node to the end of the list of parent nodes. This is used during picking to construct a path from the root to the picked object.

Parameters:

sgo - The scene graph object to be added to the path

pop

public void pop(ZSceneGraphObject sgo)

Removes a node (and any nodes after it) from the list of parent nodes. This is used during picking to construct a path from the root to the picked object.

Parameters:

sgo - The scene graph object to be removed from the path

trimToSize

public void trimToSize()

Trims the capacity of the array that stores the parents list points to the actual number of points. Normally, the parents list arrays can be slightly larger than the number of points in the parents list. An application can use this operation to minimize the storage of a parents list.

getNumCameras

public int getNumCameras()

Returns the number of internal cameras between the root and the terminal object.

getCamera

public ZCamera getCamera(int i)

Returns the i'th camera between the root and the terminal object. The camera at position 0 is closest to the root, and the camera at the last position is closest to the terminal object.

Parameters:

i - The index of the camera to return

Returns:

The camera

pushCamera

public void pushCamera(ZCamera camera)

Adds a node to the end of the list of camera nodes. This is used during picking to construct a path from the root to the picked object.

Parameters:

camera - The camera to be added to the path

popCamera

public void popCamera(ZCamera camera)

Removes a camera (and any cameras after it) from the list of camera nodes. This is used to construct a path from the root to the picked object.

Parameters:

camera - The camera to be removed from the path

trimCamerasToSize

public void trimCamerasToSize()

Trims the capacity of the array that stores the cameras to the actual number of points. Normally, the cameras array can be slightly larger than the number of cameras in the list. An application can use this operation to minimize the storage of the camera list.

pushTransformer

public void pushTransformer(ZSceneGraphObject transformer)

Internal method. Adds a transformer to the end of the list of transformer nodes. This is used to support updateTransform().

Parameters:

transformer - The transformer to be added to the path

popTransformer

public void popTransformer(ZSceneGraphObject transformer)

Removes a transformer (and any transformers after it) from the list of transformer nodes. This is used to support updateTransform().

Parameters:

transformer - The transformer to be removed from the path

trimTransformersToSize

public void trimTransformersToSize()

Trims the capacity of the array that stores the transformers to the actual number of points. Normally, the transformers array can be slightly larger than the number of transformers in the list. An application can use this operation to minimize the storage of the transformer list.

setCameraFound

public void setCameraFound(boolean cf)

Internal method. This is used by pick on the way back up the recursive pick checking to say that a camera has been gone through, and thus transforms should be kept from this point up.

getCameraFound

public boolean getCameraFound()

Internal method. This is used by pick on the way back up the recursive pick checking to say that a camera has been gone through, and thus transforms should be kept from this point up.

updateTransform

public void updateTransform()

Update the path's transform. This will modify the transform by going through the path and rebuilding the transform based on current values of ZCamera and ZTransformGroup objects.

toString

public java.lang.String toString()

Returns a string description of this path useful for debugging.

Overrides:

toString in class java.lang.Object

Returns:

the string