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, 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.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.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	repaint(ZSceneGraphObject obj, java.awt.geom.AffineTransform at, ZBounds clipBounds) 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, updateParentBounds, updateVolatility

Methods inherited from class edu.umd.cs.jazz.ZSceneGraphObject

addMouseListener, addMouseMotionListener, clone, computeBounds, fireEvent, fireMouseEvent, getBounds, getBoundsReference, getListenerList, getVolatileBounds, hasLisenerOfType, hasMouseListener, processMouseEvent, removeEventListener, removeMouseListener, removeMouseMotionListener, reshape, setBounds, setVolatileBounds

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.

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.

Parameters:

node - The part of the scenegraph this camera sees.

surf - The surface this top-level camera projects onto

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.

Parameters:

v - Value to assign to 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.

Specified by:

setFillColor in interface ZFillColor

Parameters:

v - Value to assign to fillColor.

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.

Parameters:

x,y,w,h - The new 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

Following copied from class: edu.umd.cs.jazz.ZSceneGraphObject

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)

repaint

public void repaint(ZSceneGraphObject obj,
                    java.awt.geom.AffineTransform at,
                    ZBounds clipBounds)

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 transform and clipBounds parameters may be modified as a result of this call.

Parameters:

obj - The object to repaint

at - The affine transform

clipBounds - The bounds to clip to when repainting

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.

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.

Parameters:

m00, m01, m02, m10, m11, m12 - the 6 values that compose the 3x3 transformation matrix

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.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.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.

Parameters:

refBounds - The bounds (in global coordinates) to be centered.

millis - The time in milliseconds to perform the animation

surface - The surface to be updated during the animation

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.

surface - The surface to be updated during 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

Parameters:

the - new scale

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.

Overrides:

writeObject in class ZVisualComponent

Parameters:

out - The stream that this object writes into

writeObjectRecurse

public void writeObjectRecurse(ZObjectOutputStream out)
                        throws java.io.IOException

Specify which objects this object references in order to write out the scenegraph properly

Overrides:

writeObjectRecurse in class ZVisualComponent

Parameters:

out - The stream that this object writes into

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.

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.