edu.umd.cs.jazz
Class ZCamera

java.lang.Object
  |
  +--edu.umd.cs.jazz.ZSceneGraphObject
        |
        +--edu.umd.cs.jazz.ZVisualComponent
              |
              +--edu.umd.cs.jazz.ZCamera
All Implemented Interfaces:
java.lang.Cloneable, java.io.Serializable, ZAppearance, ZFillColor, ZSerializable, ZTransformable

public class ZCamera
extends ZVisualComponent
implements ZFillColor, ZTransformable, java.io.Serializable

ZCamera represents a viewport onto a list of nodes. A camera can look at any number of ZLayerGroups, and can specify where in space it looks as specified by an arbitrary affine transformation.

When a ZCanvas is created, it automatically creates a top-level camera attached to that canvas that is the same size as the canvas. Thus, the whole scenegraph is rendered within that canvas.

It is also possible to create an "internal camera" that acts as a portal, or internal window. That is, it is an object within the scene that looks onto the scene. To do this, create a scenegraph where the top-level camera sees both the regular layer, and a new layer that contains the internal camera. Then, make the new internal camera look at the regular layer. The following code demonstrates this:

      ZCamera portal = new ZCamera();
      portal.setBounds(100, 100, 200, 200);
      portal.setFillColor(Color.red);
      ZVisualLeaf leaf = new ZVisualLeaf(portal);
      leaf.setFindable(false);
      ZVisualGroup border = new ZVisualGroup(leaf);
      ZRectangle rect = new ZRectangle(100, 100, 200, 200);
      rect.setPenColor(Color.blue);
      rect.setFillColor(null);
      rect.setPenWidth(5.0);
      border.setFrontVisualComponent(rect);
      ZLayerGroup layer = new ZLayerGroup(border);
      canvas.getRoot().addChild(layer);
      canvas.getCamera().addLayer(layer);
      portal.addLayer(canvas.getLayer());
 

Context-sensitive rendering

It is possible to create visual components that appear differently in different cameras, or are dependent on camera paramters (or other context). An example of such context-sensitive rendering is a polyline with a constant-thickness pen. As the camera view zooms in and out, the position of the points changes, but the pen thickness does not.

At first glance, it might seem that all that is necessary for these special objects is to make the render method depend on camera parameters. However, it is a bit more complex because the effective bounds of the object changes if the pen width of the object changes. Thus, the bounds of the object must be computed depending on the properties of the camera it is being rendered within.

In order to compute bounds for different camera views, two things must be done specially. First, the object must be set to have 'volatile bounds' (with the setVolatileBounds() method) which tells Jazz not to cache the bounds of the object, but to recompute them every time they are needed. The second thing is that the relevant camera must be consulted to get the camera state (such as view magnification). This can be done through the 'current render context' which is maintained in the root of the scenegraph. This can be found with getRoot().getCurrentRenderContext(). Finally, certain objects may want to also redefine the pick method using the render context if the picking is dependent on some context-sensitive attribute that is used for rendering.

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:
Benjamin B. Bederson
, Britt McAlister , Maria E. Jump
See Also:
Serialized Form

Field Summary
static java.awt.Color fillColor_DEFAULT
          The default fill color.
 
Fields inherited from class edu.umd.cs.jazz.ZSceneGraphObject
bounds, inTransaction, invalidBounds, invalidVolatileBounds, listenerList, volatileBounds, volatileBounds_DEFAULT
 
Constructor Summary
ZCamera()
          Constructs a new ZCamera.
ZCamera(ZLayerGroup layer, ZDrawingSurface aSurface)
          Constructs a new ZCamera.
 
Method Summary
 void addCameraListener(ZCameraListener l)
          Adds the specified camera listener to receive camera events from this camera
 void addLayer(ZLayerGroup layer)
          Add a portion of the scenegraph that what this camera sees.
 void animate(java.awt.geom.AffineTransform at, int millis, ZDrawingSurface surface)
          Set the transform of this camera to the specified transform, and animate the change from its current transformation over the specified number of milliseconds using a slow-in slow-out animation.
 double cameraToLocal(java.awt.geom.Dimension2D aDimension, ZNode node)
          Transform a dimension in the camera's coordinate system through the camera down the tree to the specified node's local coordinate system.
 double cameraToLocal(java.awt.geom.Point2D pt, ZNode node)
          Transform a point in the camera's coordinate system through the camera down the tree to the specified node's local coordinate system.
 double cameraToLocal(java.awt.geom.Rectangle2D rect, ZNode node)
          Transform a rectangle in the camera's coordinate system through the camera down the tree to the specified node's local coordinate system.
 void center(java.awt.geom.Rectangle2D refBounds, int millis, ZDrawingSurface aSurface)
          Animates the camera view so that the specified bounds (in global coordinates) is centered within the view of the camera.
 void center(java.awt.geom.Rectangle2D srcBounds, java.awt.geom.Rectangle2D destBounds, int millis, ZDrawingSurface surface)
          Animates the camera view so that a given global bounds appear within a specified screen bounds given in camera coordinates.
 void centerWithAspectChange(java.awt.geom.Rectangle2D refBounds, int millis, ZDrawingSurface aSurface)
          Animates the camera view so that the camera view will match the given bounds exactly.
 void centerWithAspectChange(java.awt.geom.Rectangle2D srcBounds, java.awt.geom.Rectangle2D destBounds, int millis, ZDrawingSurface surface)
          Animates the given camera view so that a given global bounds appear within a specified screen bounds given in camera coordinates.
protected  void computeInverseViewTransform()
          Internal method to compute the inverse camera transform based on the camera transform.
 ZRenderContext createRenderContext(java.awt.Graphics2D aG2, ZBounds visibleBounds, ZDrawingSurface aSurface, int qualityRequested)
          This returns a new instance of a ZRenderContext for this node.
 ZRenderContext createRenderContext(ZCamera camera)
          This returns a new instance of a ZRenderContext for this node.
 java.lang.String dump()
          Generate a string that represents this object for debugging.
protected  java.lang.Object duplicateObject()
          Clones this object.
 java.util.ArrayList findNodes(ZFindFilter filter)
          Return the list of nodes that are accepted by the specified filter in the portion of the scenegraph visible through this camera.
protected  ZLayerGroup getAncestorLayerFor(ZNode node)
          Return the camera layer associated with this camera that is the ancestor of the supplied node.
 ZDrawingSurface getDrawingSurface()
          Get the value of surface.
 java.awt.Color getFillColor()
          Get the value of fillColor.
 java.awt.geom.AffineTransform getInverseViewTransform()
          Returns a copy of the inverse view transform associated with this camera.
 java.awt.geom.AffineTransform getInverseViewTransformReference()
          Returns a reference to the inverse view transform associated with this camera.
 ZLayerGroup[] getLayers()
          Returns a copy of the list of layers that this camera looks onto.
 ZLayerGroup[] getLayersReference()
          Returns a reference to the actual layers array of this camera.
 double getMagnification()
          Returns the current magnification of this camera.
 void getMatrix(double[] matrix)
          Returns the view transform matrix.
 int getNumLayers()
          Returns the number of layers of this camera.
 ZRoot getRoot()
          Returns the root of the scene graph that this camera is looking at.
 double getScale()
          Returns the current scale of this transform.
 double getTranslateX()
          Returns the current X translation of this object
 double getTranslateY()
          Returns the current Y translation of this object
 java.awt.geom.Point2D getTranslation()
          Returns the current translation of this object
 ZBounds getViewBounds()
          Returns the bounds that this Camera sees in global scene coordinates.
 java.awt.geom.AffineTransform getViewTransform()
          Returns a copy of the view transform that specifes where in space this camera looks.
 double localToCamera(java.awt.geom.Dimension2D aDimension, ZNode node)
          Transform a dimension in a node's local coordinate system up the scenegraph backwards through the camera to the camera's coordinate system.
 double localToCamera(java.awt.geom.Point2D pt, ZNode node)
          Transform a point in a node's local coordinate system up the scenegraph backwards through the camera to the camera's coordinate system.
 double localToCamera(java.awt.geom.Rectangle2D rect, ZNode node)
          Transform a rectangle in a node's local coordinate system up the scenegraph backwards through the camera to the camera's coordinate system.
 boolean pick(java.awt.geom.Rectangle2D rect, ZSceneGraphPath path)
          Picks the first object under the specified rectangle (if there is one) as searched in reverse (front-to-back) order.
 void removeCameraListener(ZCameraListener l)
          Removes the specified camera listener so that it no longer receives camera events from this camera.
 void removeLayer(ZLayerGroup layer)
          Removes a portion of the scenegrpah from what this camera sees
 void render(ZRenderContext renderContext)
          Renders the view this camera sees.
 void repaint()
          Repaint causes the portions of the surfaces that this object appears in to be marked as needing painting, and queues events to cause those areas to be painted.
 void repaint(ZBounds repaintBounds)
          This is an internal form of repaint that is only intended to be used by calls from within Jazz.
 void replaceLayer(ZLayerGroup original, ZLayerGroup replacement)
          Replaces the specified node out of the list of layers of this camera, and replaces it with the specified node.
 void scale(double dz)
          Scale the object from its current scale to the scale specified by muliplying the current scale and dz.
 void scale(double dz, double x, double y)
          Scale the object around the specified point (x, y) from its current scale to the scale specified by muliplying the current scale and dz.
 void scale(double dz, double x, double y, int millis, ZDrawingSurface surface)
          Animate the object around the specified point (x, y) from its current scale to the scale specified by muliplying the current scale and dz
 void scale(double dz, int millis, ZDrawingSurface surface)
          Animate the object from its current scale to the scale specified by muliplying the current scale and deltaZ
 void setBounds(int x, int y, int w, int h)
          Sets the bounds of this camera.
 void setBounds(java.awt.geom.Rectangle2D newBounds)
          Sets the bounds of this camera.
 void setDrawingSurface(ZDrawingSurface aSurface)
          Set the value of surface.
 void setFillColor(java.awt.Color aColor)
          Set the value of fillColor.
static void setRenderContextFactory(ZRenderContextFactory factory)
          Define how render contexts should be created.
 void setScale(double finalz)
          Sets the scale of the view transform
 void setScale(double finalz, double x, double y)
          Set the scale of the object to the specified target scale, scaling the object around the specified point (x, y).
 void setScale(double finalz, double x, double y, int millis, ZDrawingSurface surface)
          Animate the object around the specified point (x, y) to the specified target scale.
 void setScale(double finalz, int millis, ZDrawingSurface surface)
          Animate the object from its current scale to the specified target scale.
 void setState(java.lang.String fieldType, java.lang.String fieldName, java.lang.Object fieldValue)
          Set some state of this object as it gets read back in.
 void setTransform(double m00, double m10, double m01, double m11, double m02, double m12)
          Sets the view transform via the matrix values.
 void setTranslateX(double x)
          Sets the current X translation of this object
 void setTranslateY(double y)
          Sets the current Y translation of this object
 void setTranslation(double x, double y)
          Translate the object to the specified position
 void setTranslation(double x, double y, int millis, ZDrawingSurface surface)
          Animate the object from its current position to the position specified by x, y
 void setViewTransform(java.awt.geom.AffineTransform transform)
          Sets the view transform associated with this camera.
 void setViewTransform(double m00, double m10, double m01, double m11, double m02, double m12)
          Sets the view transform associated with this camera.
 void translate(double dx, double dy)
          Translate the object by the specified deltaX and deltaY
 void translate(double dx, double dy, int millis, ZDrawingSurface surface)
          Animate the object from its current position by the specified deltaX and deltaY
 void trimToSize()
          Trims the capacity of the array that stores the layers list points to the actual number of points.
protected  void updateObjectReferences(ZObjectReferenceTable objRefTable)
          Called to update internal object references after a clone operation by ZSceneGraphObject.clone().
 void writeObject(ZObjectOutputStream out)
          Write out all of this object's state.
 void writeObjectRecurse(ZObjectOutputStream out)
          Specify which objects this object references in order to write out the scenegraph properly
 
Methods inherited from class edu.umd.cs.jazz.ZVisualComponent
addParent, getNumParents, getParents, getParentsReference, paint, pickBounds, removeParent, updateBounds, updateVolatility
 
Methods inherited from class edu.umd.cs.jazz.ZSceneGraphObject
addClientProperty, addMouseListener, addMouseMotionListener, clone, computeBounds, computeVolatileBounds, endTransaction, fireEvent, fireMouseEvent, getBounds, getBoundsReference, getClientProperty, getHandles, getListenerList, getVolatileBounds, hasLisenerOfType, hasListenerOfType, hasMouseListener, markInTransaction, markNotInTransaction, processMouseEvent, putClientProperty, removeEventListener, removeMouseListener, removeMouseMotionListener, reshape, setBounds, setVolatileBounds, startTransaction
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

fillColor_DEFAULT

public static final java.awt.Color fillColor_DEFAULT
The default fill color. For top level cameras the preferred way of setting the ZCanvas background color is to set it directly with ZCanvas.setBackground(). This is why the default fill for cameras is set to null.

Constructor Detail

ZCamera

public ZCamera()
Constructs a new ZCamera. Cameras are always associated with a scenegraph, but are not attached to any output device (such as a window or a portal) to start.


ZCamera

public ZCamera(ZLayerGroup layer,
               ZDrawingSurface aSurface)
Constructs a new ZCamera. Cameras are always associated with a scenegraph, but are not attached to any output device (such as a window or a portal) to start.

Method Detail

duplicateObject

protected java.lang.Object duplicateObject()
Clones this object.

The cloned camera will continue to see the same layers in the original scenegraph (the layers that the camera looks at are not cloned).

The cloned camera will not be attached to any surface, and must be made visible by attaching to a new surface (or by being visible through another camera.)

Overrides:
duplicateObject in class ZVisualComponent
See Also:
ZSceneGraphObject.duplicateObject()

updateObjectReferences

protected void updateObjectReferences(ZObjectReferenceTable objRefTable)
Called to update internal object references after a clone operation by ZSceneGraphObject.clone().

Overrides:
updateObjectReferences in class ZVisualComponent
See Also:
ZSceneGraphObject.updateObjectReferences(edu.umd.cs.jazz.util.ZObjectReferenceTable)

setRenderContextFactory

public static void setRenderContextFactory(ZRenderContextFactory factory)
Define how render contexts should be created. This specifies a factory that is used whenever a render context needs to be created.

Parameters:
factory - The new factory to create render contexts with.
See Also:
createRenderContext(edu.umd.cs.jazz.ZCamera)

createRenderContext

public ZRenderContext createRenderContext(ZCamera camera)
This returns a new instance of a ZRenderContext for this node.

See Also:
setRenderContextFactory(edu.umd.cs.jazz.util.ZRenderContextFactory)

createRenderContext

public ZRenderContext createRenderContext(java.awt.Graphics2D aG2,
                                          ZBounds visibleBounds,
                                          ZDrawingSurface aSurface,
                                          int qualityRequested)
This returns a new instance of a ZRenderContext for this node.

See Also:
setRenderContextFactory(edu.umd.cs.jazz.util.ZRenderContextFactory)

trimToSize

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

Overrides:
trimToSize in class ZVisualComponent

addLayer

public void addLayer(ZLayerGroup layer)
Add a portion of the scenegraph that what this camera sees. If the layer is already visible by this camera, then nothing happens.

Parameters:
layer - The part of the scenegraph added to what this camera sees.

removeLayer

public void removeLayer(ZLayerGroup layer)
Removes a portion of the scenegrpah from what this camera sees

Parameters:
layer - The part of the scenegraph removed from what this camera sees.

replaceLayer

public void replaceLayer(ZLayerGroup original,
                         ZLayerGroup replacement)
Replaces the specified node out of the list of layers of this camera, and replaces it with the specified node. The replacement node will be added to layer list in the same position as the original was.

Parameters:
original - is the old node that is being swapped out as a layer
replacement - is the new node that is being swapped in as a layer

getLayers

public ZLayerGroup[] getLayers()
Returns a copy of the list of layers that this camera looks onto.

Returns:
Portion of scenegraph that is visible from this camera.

getLayersReference

public ZLayerGroup[] getLayersReference()
Returns a reference to the actual layers array of this camera. It should not be modified by the caller. Note that the actual number of layers could be less than the size of the array. Determine the actual number of layers with getNumLayers().

Warning: This method returns a reference to an internal array. Any modification of this array will result in undefined behavior.

Returns:
the children of this node.

getNumLayers

public int getNumLayers()
Returns the number of layers of this camera.

Returns:
the number of layers.

getDrawingSurface

public ZDrawingSurface getDrawingSurface()
Get the value of surface.

Returns:
Value of surface.

setDrawingSurface

public void setDrawingSurface(ZDrawingSurface aSurface)
Set the value of surface.


getFillColor

public java.awt.Color getFillColor()
Get the value of fillColor.

Specified by:
getFillColor in interface ZFillColor
Returns:
Value of fillColor.

setFillColor

public void setFillColor(java.awt.Color aColor)
Set the value of fillColor. For top level cameras the preferred way of setting the ZCanvas background color is to set it directly with ZCanvas.setBackground() instead of setting the ZCameras fill color.

Specified by:
setFillColor in interface ZFillColor
Parameters:
aColor - the fill color, or null if none.

getViewBounds

public ZBounds getViewBounds()
Returns the bounds that this Camera sees in global scene coordinates.

Returns:
The bounds.

setBounds

public void setBounds(int x,
                      int y,
                      int w,
                      int h)
Sets the bounds of this camera.


setBounds

public void setBounds(java.awt.geom.Rectangle2D newBounds)
Sets the bounds of this camera.

Parameters:
newBounds - The new bounds of this camera

getMagnification

public double getMagnification()
Returns the current magnification of this camera.

Returns:
The magnification factor.

repaint

public void repaint()
Description copied from class: ZSceneGraphObject
Repaint causes the portions of the surfaces that this object appears in to be marked as needing painting, and queues events to cause those areas to be painted. The painting does not actually occur until those events are handled. If this object is visible in multiple places because more than one camera can see this object, then all of those places are marked as needing painting.

Scenegraph objects should call repaint when their internal state has changed and they need to be redrawn on the screen.

Important note : Scenegraph objects should call reshape() instead of repaint() if the internal state change effects the bounds of the shape in any way (e.g. changing penwidth, selection, transform, adding points to a line, etc.)

Overrides:
repaint in class ZVisualComponent
See Also:
ZSceneGraphObject.reshape()

repaint

public void repaint(ZBounds repaintBounds)
This is an internal form of repaint that is only intended to be used by calls from within Jazz. It passes repaint requests up through the camera to other interested camera, and the surface (if there is one). Note that the input parameter may be modified as a result of this call.

Overrides:
repaint in class ZVisualComponent
Parameters:
repaintBounds - The bounds that need to be repainted (in global coordinates)
See Also:
ZVisualComponent.repaint()

render

public void render(ZRenderContext renderContext)
Renders the view this camera sees.

The transform, clip, and composite will be set appropriately when this object is rendered. It is up to this object to restore the transform, clip, and composite of the Graphics2D if this node changes any of them. However, the color, font, and stroke are unspecified by Jazz. This object should set those things if they are used, but they do not need to be restored.

Overrides:
render in class ZVisualComponent
Parameters:
renderContext - The graphics context to use for rendering.
See Also:
ZVisualComponent.paint(Graphics2D)

getRoot

public ZRoot getRoot()
Returns the root of the scene graph that this camera is looking at. Actually returns the root of the first layer this camera sees.

Overrides:
getRoot in class ZVisualComponent

pick

public boolean pick(java.awt.geom.Rectangle2D rect,
                    ZSceneGraphPath path)
Picks the first object under the specified rectangle (if there is one) as searched in reverse (front-to-back) order. The picked object is returned via the ZSceneGraphPath. Only nodes with "pickable" visual components are returned.

Overrides:
pick in class ZVisualComponent
Parameters:
rect - Coordinates of pick rectangle in camera coordinates.
path - The path through the scenegraph to the picked node. Modified by this call.
Returns:
true if pick succeeds.
See Also:
ZDrawingSurface.pick(int, int)

findNodes

public java.util.ArrayList findNodes(ZFindFilter filter)
Return the list of nodes that are accepted by the specified filter in the portion of the scenegraph visible through this camera. If a node is not "findable", then neither that node, nor any of its descendants will be included. The filter specifies whether or not a given node should be accepted by this search, and whether the children of a node should be searched.

Parameters:
filter - The filter that decides whether or not to include individual nodes in the find list
Returns:
The nodes found
See Also:
ZNode.isFindable(), ZFindFilter

dump

public java.lang.String dump()
Generate a string that represents this object for debugging.

Overrides:
dump in class ZSceneGraphObject
Returns:
the string that represents this object for debugging
See Also:
ZDebug.dump(edu.umd.cs.jazz.ZNode)

addCameraListener

public void addCameraListener(ZCameraListener l)
Adds the specified camera listener to receive camera events from this camera

Parameters:
l - the camera listener

removeCameraListener

public void removeCameraListener(ZCameraListener l)
Removes the specified camera listener so that it no longer receives camera events from this camera.

Parameters:
l - the camera listener

getMatrix

public void getMatrix(double[] matrix)
Returns the view transform matrix. This is necessary to implement the ZTransformable interface.

Specified by:
getMatrix in interface ZTransformable
Parameters:
matrix - The matrix which needs to be set

setTransform

public void setTransform(double m00,
                         double m10,
                         double m01,
                         double m11,
                         double m02,
                         double m12)
Sets the view transform via the matrix values. This is necessary to implement the ZTransformable interface

Specified by:
setTransform in interface ZTransformable
Parameters:
m00 - The 00 element of the matrix
m10 - The 10 element of the matrix
m01 - The 01 element of the matrix
m11 - The 11 element of the matrix
m02 - The 02 element of the matrix
m12 - The 12 element of the matrix

getViewTransform

public java.awt.geom.AffineTransform getViewTransform()
Returns a copy of the view transform that specifes where in space this camera looks.

Returns:
The current camera view transform.

computeInverseViewTransform

protected void computeInverseViewTransform()
Internal method to compute the inverse camera transform based on the camera transform. This gets called from within ZCamera whenever the inverse camera transform cache has been invalidated, and it is needed.


getInverseViewTransform

public java.awt.geom.AffineTransform getInverseViewTransform()
Returns a copy of the inverse view transform associated with this camera.

Returns:
The current inverse camera transform.

getInverseViewTransformReference

public java.awt.geom.AffineTransform getInverseViewTransformReference()
Returns a reference to the inverse view transform associated with this camera.

Returns:
The current inverse camera transform.

setViewTransform

public void setViewTransform(java.awt.geom.AffineTransform transform)
Sets the view transform associated with this camera. This controls where in space this camera looks.

Parameters:
transform - the new transform.

setViewTransform

public void setViewTransform(double m00,
                             double m10,
                             double m01,
                             double m11,
                             double m02,
                             double m12)
Sets the view transform associated with this camera. This controls where in space this camera looks.


cameraToLocal

public double cameraToLocal(java.awt.geom.Point2D pt,
                            ZNode node)
Transform a point in the camera's coordinate system through the camera down the tree to the specified node's local coordinate system. In the typical case where this is a top-level camera, and the point is in screen coordinates, this will transform the point to the local coordinate system of the specified node. The input point is modified by this method. It also returns the change in scale from the camera coordinate system to the node coordinate system.

If the node is specified as null, then the point is transformed through the camera, but no further - thus transforming the point from window to global coordinates.

If the specified node is not on the portion of the scenegraph that is visible through the camera, then a ZNodeNotFoundException is thrown.

Parameters:
pt - The point to be transformed
node - The node to transform to
Returns:
dz The change in scale from the camera coordinate system to the node coordinate system.
Throws:
ZNodeNotFoundException - if the node is not in the subtree of the scenegraph under one of the camera's layers.
See Also:
localToCamera(Point2D, ZNode)

cameraToLocal

public double cameraToLocal(java.awt.geom.Dimension2D aDimension,
                            ZNode node)
Transform a dimension in the camera's coordinate system through the camera down the tree to the specified node's local coordinate system. In the typical case where this is a top-level camera, and the dimension is in screen coordinates, this will transform the dimension to the local coordinate system of the specified node. The input dimension is modified by this method.

If the node is specified as null, then the dimension is transformed through the camera, but no further - thus transforming the point from window to global coordinates.

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.

If the specified node is not on the portion of the scenegraph that is visible through the camera, then a ZNodeNotFoundException is thrown.

Parameters:
aDimension - The dimension to be transformed
node - The node to transform to
Returns:
dz The change in scale from the camera coordinate system to the node coordinate system.
Throws:
ZNodeNotFoundException - if the node is not in the subtree of the scenegraph under one of the camera's layers.
See Also:
localToCamera(Dimension2D, ZNode)

cameraToLocal

public double cameraToLocal(java.awt.geom.Rectangle2D rect,
                            ZNode node)
Transform a rectangle in the camera's coordinate system through the camera down the tree to the specified node's local coordinate system. In the typical case where this is a top-level camera, and the rectangle is in screen coordinates, this will transform the rectangle to the local coordinate system of the specified node. The input rectangle is modified by this method. It also returns the change in scale from the camera coordinate system to the node coordinate system.

If the node is specified as null, then the rectangle is transformed through the camera, but no further - thus transforming the rectangle from window to global coordinates.

If the specified node is not on the portion of the scenegraph that is visible through the camera, then a ZNodeNotFoundException is thrown.

Parameters:
rect - The rectangle to be transformed
node - The node to transform to
Returns:
dz The change in scale from the camera coordinate system to the node coordinate system.
Throws:
ZNodeNotFoundException - if the node is not in the subtree of the scenegraph under one of the camera's layers.
See Also:
localToCamera(Rectangle2D, ZNode)

localToCamera

public double localToCamera(java.awt.geom.Point2D pt,
                            ZNode node)
Transform a point in a node's local coordinate system up the scenegraph backwards through the camera to the camera's coordinate system. In the typical case where this is a top-level camera, and the point represents a coordinate in the local coordinate system of a node, this will transform the point to screen coordinates. The input point is modified by this method. It also returns the change in scale from the node coordinate system to the camera coordinate system.

If the node is specified as null, then the point is transformed from global coordinates through the camera, thus transforming the point from global to window coordinates.

If the specified node is not on the portion of the scenegraph that is visible through the camera, then a ZNodeNotFoundException is thrown.

Parameters:
pt - The point to be transformed
node - The node that represents the local coordinates to transform from
Returns:
dz The change in scale from the node coordinate system to the camera coordinate system.
Throws:
ZNodeNotFoundException - if the node is not in the subtree of the scenegraph under one of the camera's layers.
See Also:
cameraToLocal(Point2D, ZNode)

localToCamera

public double localToCamera(java.awt.geom.Dimension2D aDimension,
                            ZNode node)
Transform a dimension in a node's local coordinate system up the scenegraph backwards through the camera to the camera's coordinate system. In the typical case where this is a top-level camera, and the dimension represents a dimension in the local coordinate system of a node, this will transform the dimension to screen coordinates. The input dimension is modified by this method.

If the node is specified as null, then the dimension is transformed from global coordinates through the camera, thus transforming the size from global to window coordinates.

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.

If the specified node is not on the portion of the scenegraph that is visible through the camera, then a ZNodeNotFoundException is thrown.

Parameters:
aDimension - The dimension to be transformed
node - The node that represents the local coordinates to transform from
Returns:
dz The change in scale from the node coordinate system to the camera coordinate system.
Throws:
ZNodeNotFoundException - if the node is not in the subtree of the scenegraph under one of the camera's layers.
See Also:
cameraToLocal(Dimension2D, ZNode)

localToCamera

public double localToCamera(java.awt.geom.Rectangle2D rect,
                            ZNode node)
Transform a rectangle in a node's local coordinate system up the scenegraph backwards through the camera to the camera's coordinate system. In the typical case where this is a top-level camera, and the rectangle is in the local coordinate system of a node, this will transform the rectangle to screen coordinates. The input rectangle is modified by this method. It also returns the change in scale from the node coordinate system to the camera coordinate system.

If the node is specified as null, then the rectangle is transformed from global coordinates through the camera, thus transforming the rectangle from global to window coordinates.

If the specified node is not on the portion of the scenegraph that is visible through the camera, then a ZNodeNotFoundException is thrown.

Parameters:
rect - The rectangle to be transformed
node - The node that represents the local coordinates to transform from
Returns:
dz The change in scale from the node coordinate system to the camera coordinate system.
Throws:
ZNodeNotFoundException - if the node is not in the subtree of the scenegraph under one of the camera's layers.
See Also:
cameraToLocal(Rectangle2D, ZNode)

center

public void center(java.awt.geom.Rectangle2D refBounds,
                   int millis,
                   ZDrawingSurface aSurface)
Animates the camera view so that the specified bounds (in global coordinates) is centered within the view of the camera.


center

public void center(java.awt.geom.Rectangle2D srcBounds,
                   java.awt.geom.Rectangle2D destBounds,
                   int millis,
                   ZDrawingSurface surface)
Animates the camera view so that a given global bounds appear within a specified screen bounds given in camera coordinates. The transformation is made in such a way that the width/height ratio of the source bounds is kept.

Parameters:
millis - Number of milliseconds over which to perform the animation.
surface - The surface to be updated during animation.
srcBounds - A bounds in global coordinates.
destBounds - Bounds of the region in camera coordinates that bounds should apperar in.

centerWithAspectChange

public void centerWithAspectChange(java.awt.geom.Rectangle2D srcBounds,
                                   java.awt.geom.Rectangle2D destBounds,
                                   int millis,
                                   ZDrawingSurface surface)
Animates the given camera view so that a given global bounds appear within a specified screen bounds given in camera coordinates. The source bounds is made to fit exactly inside the destination bounds, which may result in a change in width/height ratio.

Parameters:
millis - Number of milliseconds over which to perform the animation.
surface - The surface to be updated during animation.
srcBounds - A bounds in global coordinates.
destBounds - Bounds of the region in camera coordinates that bounds should apperar in.

centerWithAspectChange

public void centerWithAspectChange(java.awt.geom.Rectangle2D refBounds,
                                   int millis,
                                   ZDrawingSurface aSurface)
Animates the camera view so that the camera view will match the given bounds exactly. This may result in a change in width/height ratio.

Parameters:
millis - Number of milliseconds over which to perform the animation.
refBounds - A bounds in global coordinates.

getTranslation

public java.awt.geom.Point2D getTranslation()
Returns the current translation of this object

Returns:
the translation

getTranslateX

public double getTranslateX()
Returns the current X translation of this object

Returns:
the X translation

setTranslateX

public void setTranslateX(double x)
Sets the current X translation of this object


getTranslateY

public double getTranslateY()
Returns the current Y translation of this object

Returns:
the Y translation

setTranslateY

public void setTranslateY(double y)
Sets the current Y translation of this object


translate

public void translate(double dx,
                      double dy)
Translate the object by the specified deltaX and deltaY

Parameters:
dx - X-coord of translation
dy - Y-coord of translation

translate

public void translate(double dx,
                      double dy,
                      int millis,
                      ZDrawingSurface surface)
Animate the object from its current position by the specified deltaX and deltaY

Parameters:
dx - X-coord of translation
dy - Y-coord of translation
millis - Number of milliseconds over which to perform the animation
surface - The surface to updated during animation.

setTranslation

public void setTranslation(double x,
                           double y)
Translate the object to the specified position

Parameters:
x - X-coord of translation
y - Y-coord of translation

setTranslation

public void setTranslation(double x,
                           double y,
                           int millis,
                           ZDrawingSurface surface)
Animate the object from its current position to the position specified by x, y

Parameters:
x - X-coord of translation
y - Y-coord of translation
millis - Number of milliseconds over which to perform the animation
surface - The surface to updated during animation.

getScale

public double getScale()
Returns the current scale of this transform. Note that this is implemented by applying the transform to a diagonal line and returning the length of the resulting line. If the transform is sheared, or has a non-uniform scaling in X and Y, the results of this method will be ill-defined.

Returns:
the scale

scale

public void scale(double dz)
Scale the object from its current scale to the scale specified by muliplying the current scale and dz.

Parameters:
dz - scale factor

scale

public void scale(double dz,
                  double x,
                  double y)
Scale the object around the specified point (x, y) from its current scale to the scale specified by muliplying the current scale and dz.

Parameters:
dz - scale factor
x - X coordinate of the point to scale around
y - Y coordinate of the point to scale around

scale

public void scale(double dz,
                  int millis,
                  ZDrawingSurface surface)
Animate the object from its current scale to the scale specified by muliplying the current scale and deltaZ

Parameters:
dz - scale factor
millis - Number of milliseconds over which to perform the animation
surface - The surface to updated during animation.

scale

public void scale(double dz,
                  double x,
                  double y,
                  int millis,
                  ZDrawingSurface surface)
Animate the object around the specified point (x, y) from its current scale to the scale specified by muliplying the current scale and dz

Parameters:
dz - scale factor
x - X coordinate of the point to scale around
y - Y coordinate of the point to scale around
millis - Number of milliseconds over which to perform the animation
surface - The surface to updated during animation.

setScale

public void setScale(double finalz)
Sets the scale of the view transform


setScale

public void setScale(double finalz,
                     double x,
                     double y)
Set the scale of the object to the specified target scale, scaling the object around the specified point (x, y).

Parameters:
finalz - scale factor
x - X coordinate of the point to scale around
y - Y coordinate of the point to scale around

setScale

public void setScale(double finalz,
                     int millis,
                     ZDrawingSurface surface)
Animate the object from its current scale to the specified target scale.

Parameters:
finalz - scale factor
millis - Number of milliseconds over which to perform the animation
surface - The surface to updated during animation.

setScale

public void setScale(double finalz,
                     double x,
                     double y,
                     int millis,
                     ZDrawingSurface surface)
Animate the object around the specified point (x, y) to the specified target scale.

Parameters:
finalz - scale factor
x - X coordinate of the point to scale around
y - Y coordinate of the point to scale around
millis - Number of milliseconds over which to perform the animation
surface - The surface to updated during animation.

animate

public void animate(java.awt.geom.AffineTransform at,
                    int millis,
                    ZDrawingSurface surface)
Set the transform of this camera to the specified transform, and animate the change from its current transformation over the specified number of milliseconds using a slow-in slow-out animation. The surface specifies which surface should be updated during the animation.

If millis is 0, then the transform is updated once, and the scene is not repainted immediately, but rather a repaint request is queued, and will be processed by an event handler.

Parameters:
at - Final transformation
millis - Number of milliseconds over which to perform the animation
surface - The surface to updated during animation.

writeObject

public void writeObject(ZObjectOutputStream out)
                 throws java.io.IOException
Write out all of this object's state.

Specified by:
writeObject in interface ZSerializable
Overrides:
writeObject in class ZVisualComponent
Parameters:
out - The stream that this object writes into
java.io.IOException

writeObjectRecurse

public void writeObjectRecurse(ZObjectOutputStream out)
                        throws java.io.IOException
Specify which objects this object references in order to write out the scenegraph properly

Specified by:
writeObjectRecurse in interface ZSerializable
Overrides:
writeObjectRecurse in class ZVisualComponent
Parameters:
out - The stream that this object writes into
java.io.IOException

setState

public void setState(java.lang.String fieldType,
                     java.lang.String fieldName,
                     java.lang.Object fieldValue)
Set some state of this object as it gets read back in. After the object is created with its default no-arg constructor, this method will be called on the object once for each bit of state that was written out through calls to ZObjectOutputStream.writeState() within the writeObject method.

Specified by:
setState in interface ZSerializable
Overrides:
setState in class ZVisualComponent
Parameters:
fieldType - The fully qualified type of the field
fieldName - The name of the field
fieldValue - The value of the field

getAncestorLayerFor

protected ZLayerGroup getAncestorLayerFor(ZNode node)
Return the camera layer associated with this camera that is the ancestor of the supplied node.

Parameters:
node - The node whos layer ancestor is needed.
Returns:
The ancenstor ZLayerGroup or null if no ancestor was found.


Copyright 2003 by University of Maryland, College Park, MD 20742, USA All rights reserved.