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 ZDrawingSurface.pick(int, int). 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).

NOTE: As of Jazz 1.1 getNode() does not return null but instead returns the bottom camera node on the picked path when no object is picked. getObject() should be used instead to determine if an object has been picked. Consequently, getObject() returns null when no object has been picked. Because getObject() returns a ZSceneGraphObject, applications can use getNode() to obtain the lowest picked node once the application has determined that an object has been picked. Note also that screenToGlobal(java.awt.geom.Point2D) and screenToGlobal(java.awt.geom.Rectangle2D) now convert to global coordinates in the lowest camera. However, this is only likely to affect an application if it uses internal cameras.

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.

Author:

Jonathan Meyer, Aug 99

, Ben Bederson , Lance Good

See Also:

ZDrawingSurface.pick(int, int), Serialized Form

ZSceneGraphPath

public ZSceneGraphPath()

Constructs a new ZSceneGraphPath.

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. If no object is picked, this returns the bottom camera node on the path. NOTE: As of Jazz 1.1 this method does not return null but instead returns the bottom camera node on the picked path when no object is picked. getObject() should be used instead to determine if an object has been picked.

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.

Parameters:

tm - The new transform

getCameraTransform

public java.awt.geom.AffineTransform getCameraTransform()

Returns the camera transform for this path. This is formed by compositing all the tranforms of the scene graph objects in this path up to the lowest camera. This resulting transform represents the local coordinate system of the last camera in this path. If the path is empty, then the transform contains the concatenated transforms of the cameras the mouse pointer is over, minus the final camera view transform (for pick operations).

getCameraTransform

public java.awt.geom.AffineTransform getCameraTransform(ZCamera camera)

Returns the camera transform for this camera in this path. This is formed by compositing all the tranforms of the scene graph objects in this path up to the specified camera. This resulting transform represents the local coordinate system of the specified camera in this path. If the camera does not appear in the current path, the transform for the terminal object is returned.

setCameraTransform

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

Sets the camera transform of the bottom camera for this path.

Parameters:

tm - The new camera transform

screenToGlobal

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

Converts the specified point from screen coordinates to global coordinates through the bottom camera, ie. camera closest to the picked object, of this path.

Parameters:

pt - The pt to be transformed

screenToGlobal

public void screenToGlobal(java.awt.geom.Dimension2D aDimension)

Converts the specified dimension from screen coordinates to global coordinates through the bottom camera, ie. camera closest to the picked object, of this path. The input dimension is modified by this method.

NOTE: Dimension2D's are abstract. When creating a new Dimension2D for use with Jazz we recoment that you use edu.umd.cs.util.ZDimension instead of java.awt.Dimension. ZDimension uses doubles internally, while java.awt.Dimension uses integers.

Parameters:

aDimension - The dimension to be transformed

screenToGlobal

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

Converts the specified point from screen coordinates to global coordinates through the bottom camera, ie. camera closest to the picked object, of this path.

Parameters:

rect - The rect to be transformed

screenToCamera

public double screenToCamera(java.awt.geom.Point2D pt)

Converts the specified point from screen coordinates to the local coordinate system of the bottom camera in this path.

Parameters:

pt - The point to be transformed

screenToCamera

public void screenToCamera(java.awt.geom.Dimension2D aDimension)

Converts the specified dimension from screen coordinates to the coordinate system of the bottom camera. The input dimension is modified by this method.

NOTE: Dimension2D's are abstract. When creating a new Dimension2D for use with Jazz we recoment that you use edu.umd.cs.util.ZDimension instead of java.awt.Dimension. ZDimension uses doubles internally, while java.awt.Dimension uses integers.

Parameters:

aDimension - The dimension to be transformed

screenToCamera

public double screenToCamera(java.awt.geom.Rectangle2D rect)

Converts the specified point from screen coordinates to the local coordinate system of the bottom camera in this path.

Parameters:

rect - The rect to be transformed

screenToCamera

public double screenToCamera(java.awt.geom.Point2D pt,
                             ZCamera camera)

Converts the specified point from screen coordinates to the local coordinate system of the specified camera, if the camera appears on the current path. If the camera does not appear in the current path, the point is transformed to local coordinates for the terminal object.

Parameters:

pt - The point to be transformed

camera - The camera for which the point is transformed

screenToCamera

public void screenToCamera(java.awt.geom.Dimension2D aDimension,
                           ZCamera aCamera)

Converts the specified dimension from screen coordinates to the coordinate system of the specified camera. The input dimension is modified by this method.

NOTE: Dimension2D's are abstract. When creating a new Dimension2D for use with Jazz we recoment that you use edu.umd.cs.util.ZDimension instead of java.awt.Dimension. ZDimension uses doubles internally, while java.awt.Dimension uses integers.

Parameters:

aDimension - The dimension to be transformed

aCamera - The camera for which the point is transformed

screenToCamera

public double screenToCamera(java.awt.geom.Rectangle2D rect,
                             ZCamera camera)

Converts the specified point from screen coordinates to the local coordinate system of the specified camera, if the camera appears on the current path. If the camera does not appear in the current path, the rectangle is transformed to local coordinates for the terminal object.

Parameters:

rect - The rect to be transformed

camera - The camera for which the point is transformed

cameraToScreen

public double cameraToScreen(java.awt.geom.Point2D pt,
                             ZCamera camera)

Converts the specified point from camera coordinates to the coordinate system of the screen, if the camera appears on the current path. If the camera does not appear in the current path, the point is transformed from the local coordinates for the terminal object.

Parameters:

pt - The point to be transformed

camera - The camera for which the point is transformed

cameraToScreen

public double cameraToScreen(java.awt.geom.Dimension2D dimension,
                             ZCamera camera)

Converts the specified dimension from camera coordinates to the coordinate system of the screen, if the camera appears on the current path. If the camera does not appear in the current path, the dimension is transformed from the local coordinates for the terminal object.

Parameters:

dimension - The dimension to be transformed

camera - The camera for which the point is transformed

cameraToScreen

public double cameraToScreen(java.awt.geom.Rectangle2D rect,
                             ZCamera camera)

Converts the specified rectangle from camera coordinates to the coordinate system of the screen, if the camera appears on the current path. If the camera does not appear in the current path, the rectangle is transformed from the local coordinates for the terminal object.

Parameters:

rect - The rectangle to be transformed

camera - The camera for which the point is 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.Dimension2D aDimension)

Converts the specified dimension from screen coordinates to the local coordinate system of the terminal scene graph object in this path. The input dimension is modified by this method.

NOTE: Dimension2D's are abstract. When creating a new Dimension2D for use with Jazz we recoment that you use edu.umd.cs.util.ZDimension instead of java.awt.Dimension. ZDimension uses doubles internally, while java.awt.Dimension uses integers.

Parameters:

aDimension - The dimension 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(ZTransformable 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(ZTransformable 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

processMouseEvent

public void processMouseEvent(ZMouseEvent e)

Percolate this mouse event up the scene graph path until the event is consumed or the top of the path is reached

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