edu.umd.cs.jazz.scenegraph
Class ZTransform

java.lang.Object
  |
  +--edu.umd.cs.jazz.scenegraph.ZTransform

public class ZTransform

extends java.lang.Object

implements ZSerializable, java.lang.Cloneable

ZTransform provides the capabilities of the AffineTransform plus some extra manipulators on the transform. ZTransform is also aware of the fact that it is a composite part of a scenegraph object and notifies the associated object via a damage call whenever the transform changes state. A ZTransform is not obligated to have a parent object.

Where Operation is one of (translate, scale, or rotate) ZTransform provides the following matrix of manipulators (the methods with mils as an arg will animate to the final state):

 operation(args)		operationTo(args)
 operation(args, mils)        operationTo(args, mils)
 

ZTransform also provides a getOperation for each Operation that returns the relevant portion of of the transform.

In order to use ZTransform effectively, it is important to have a solid understanding of affine transforms, matrix multiplication, and the standard use of matrices for graphics coordinate systems. The best place to start is by reading the documentation on AffineTransform. After that, a good next bit is to read a standard 3D graphics text such as "Interactive Computer Graphics: a Top-Down Approach with OpenGL" 2nd Edition by Angel (Addison-Wesley), or "Computer Graphics: Principles and Practice, Second Edition in C" by Foley, van Dam, Feiner, Hughes, and Phillips (Addison-Wesley).

Here is a very short lesson on matrices and graphics. An 2D affine transform is typically represented by a 3x3 matrix which we typically call M, and sometimes denote [M]. An affine transform can represent any 2D translation, scale, rotation, shear or any combination of these 4 operators. Matrices which are pure translations, scales, and rotations are typically denoted T, S, or R ([T], [S], or [R]), respectively. The identity matrix is typically denoted I or [I].

The reason these transforms are so powerful is because they can be combined in a semantically straightforward way by simply concatenating the matrices. Creating a ZTransform creates I. Calling one of the transformation methods on a transform is exactly equivalent to concatenating the transform with a new transform that specifies the transformation. Thus, transform.translate(dx, dy) is equivalent to [M][T] where M represents the original transform, and T represents the translation matrix of dx, dy. Similarly, transform.scale(ds) is equivalent to [M][S]. And, these build up, so

    ZTransform t = new ZTransform();
    t.scale(ds);
    t.translate(dx, dy);
    t.rotate(Math.PI * 0.5f);
 

is equivalent to these four matrices concatenated together with standard matrix multiplication [I][S][T][R]

However, a crucial place for confusion with these transforms is that the transforms get applied in the reverse order of how you placed the calls to the transforms in your code. To understand this, you must realize that the object paint methods get called after the transformations are applied. Your paint methods specify geometry (such as points) which get transformed by the current transformation before being painted. For a simple example, think of a point P. Well, the point post-multiplies the current transformation. In the example above, that works out to a new point P' being computed as P' = [S][T][R]P. You can think about this as the original point P first getting multiplied (on the left) by R, then the result gets multipled (on the left) by T, and that gets multiplied (on the left) by S.

Let's go through a simple example with actual numbers. Suppose you want to take a rectangle at (0, 0) with width 50 and height 50, and first translate it 50 units to the right, and then scale the whole thing by 2 about the origin. The result should be that the rectangle actually gets rendered at (100, 0) with dimensions of (100x100). The following code in Jazz implements this example.

    ZRectangle rect = new ZRectangle(0, 0, 50, 50);
    ZNode node = new ZNode(rect);
    drawingLayer.addChild(node);

				// Note how we call scale first even though
				// the translation will actually be applied before the scale.
    node.getTransform().scale(2);
    node.getTransform().translate(50, 0);
 

Sometimes it is useful to transform an object in global coordinates - even though that object has a transform of its own. For instance, suppose you are implementing an event handler for selection, and want to move an object so that it follows the pointer. In order to do this, you need to translate the object in global coordinates. Since the node you want to move may have a transform already (for instance, it may be scaled), if you simply translate the object, that transform will be applied after the scale, and thus the translation will be modified by the scale. That is, the object may have the matrix [M]. Calling translate will generate [M][T]. If M represents a scale of 2, then the translation will actually translate twice as much as you intended.

The solution is to pre-concatenate the translation so you end up with [T][M]. With ZTransform, you can preconcatenate an affine transform onto the current transform. So, the code for this translation problem would like:

    AffineTransform tx = AffineTransform.getTranslateInstance(dx, dy);
    node.getTransform().preConcatenate(tx);
 

See Also:

AffineTransform

Field Summary

protected ZScenegraphObject	parent
protected java.awt.geom.AffineTransform	transform

Constructor Summary

ZTransform()
Create an ZTransform based on an identity AffineTransform

ZTransform(java.awt.geom.AffineTransform at)
Create an ZTransform based on AffineTransform parameter

ZTransform(ZTransform xf)
Constructs a new ZTransform that is a copy of the specified ZTransform (i.e., a "copy constructor").

Method Summary

void	animate(java.awt.geom.AffineTransform tx, int millis, ZSurface surface) Set the transform of this object 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.
void	animate(java.awt.geom.AffineTransform tx, int millis, ZSurface surface, ZLerp lerpTimeFunction) Set the transform of this object to the specified transform, and animate the change from its current transformation over the specified number of milliseconds.
static void	animate(ZNode[] nodes, java.awt.geom.AffineTransform[] txs, int millis, ZSurface surface) Set the transforms of the specified array of nodes to the specified array of transforms, and animate the change over the specified number of milliseconds using a slow-in slow-out animation.
static void	animate(ZNode[] nodes, java.awt.geom.AffineTransform[] txs, int millis, ZSurface surface, ZLerp lerpTimeFunction) Set the transforms of the specified array of nodes to the specified array of transforms, and animate the change over the specified number of milliseconds.
java.lang.Object	clone() Duplicates the current ZTransform by using the copy constructor.
void	concatenate(java.awt.geom.AffineTransform tx) Concatenates an AffineTransform tx to this AffineTransform Cx in the most commonly useful way to provide a new user space that is mapped to the former user space by Tx.
ZTransform	createInverse() Create inverse ZTransform.
java.awt.geom.AffineTransform	createInverseAffineTransform() Create inverse affine transform stored in the ZTransform.
java.awt.geom.AffineTransform	getAffineTransform() Get copy of affine transform stored in the ZTransform.
void	getMatrix(double[] flatmatrix) Retrieves the 6 specifiable values in the 3x3 affine transformation matrix that this ZTransform wraps, and places them into an array of double precisions values.
ZScenegraphObject	getParent()
float	getRotation() Returns the current rotation (Z-axis) of this object Not currently immplemented BDMREV
float	getScale() Returns the current scale of this transform.
java.awt.geom.Point2D	getTranslation() Returns the current translation of this object
int	getType() Return the type of transform as specified by AffineTransform.
void	inverseTransform(java.awt.geom.Area area)
void	inverseTransform(java.awt.geom.Point2D srcPt, java.awt.geom.Point2D destPt)
void	inverseTransform(java.awt.geom.Rectangle2D srcRect, java.awt.geom.Rectangle2D destRect)
void	position(java.awt.geom.Point2D srcPt, java.awt.geom.Point2D destPt, java.awt.geom.Rectangle2D destBounds, int millis, ZSurface surface) This will calculate the necessary transform in order to make this transform's corresponding node appear at a particular position relative to the specified bounding box.
void	position(java.awt.geom.Point2D srcPt, java.awt.geom.Point2D destPt, ZNode refNode, int millis, ZSurface surface) This will calculate the necessary transform in order to make this transform's corresponding node appear at a particular position relative to the specified node.
void	preConcatenate(java.awt.geom.AffineTransform tx) Concatenates an AffineTransform Tx to this AffineTransform Cx in a less commonly used way such that Tx modifies the coordinate transformation relative to the absolute pixel space rather than relative to the existing user space.
void	rotate(float theta) Rotate the object by the specified amount
void	rotate(float theta, float xctr, float yctr) Rotate the object by the specified amount around the specified anchor point
void	rotate(float theta, float xctr, float yctr, int millis, ZSurface surface) Rotate the object, via animation, theta radians about the specified anchor point
void	rotate(float theta, int millis, ZSurface surface) Rotate the object, via animation, theta radians
void	scale(float dz) Scale the object from its current scale to the scale specified by muliplying the current scale and dz.
void	scale(float dz, float x, float 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(float dz, float x, float y, int millis, ZSurface 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(float dz, int millis, ZSurface surface) Animate the object from its current scale to the scale specified by muliplying the current scale and deltaZ
void	scaleTo(float finalz) Set the scale of the object to the specified target scale.
void	scaleTo(float finalz, float x, float y) Set the scale of the object to the specified target scale, scaling the object around the specified point (x, y).
void	scaleTo(float finalz, float x, float y, int millis, ZSurface surface) Animate the object around the specified point (x, y) to the specified target scale.
void	scaleTo(float finalz, int millis, ZSurface surface) Animate the object from its current scale to the specified target scale.
void	setAffineTransform(java.awt.geom.AffineTransform tx) Set the underlying affine transform that this ZTransform wraps.
void	setAffineTransform(double m00, double m10, double m01, double m11, double m02, double m12) Set the underlying affine transform that this ZTransform wraps.
void	setParent(ZScenegraphObject aParent)
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.
java.lang.String	toString() Generate a string that represents this object for debugging.
void	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) Transforms an array of double precision coordinates by this transform.
void	transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) Transforms an array of double precision coordinates by this transform and stores the results into an array of floats.
void	transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) Transforms an array of floating point coordinates by this transform and stores the results into an array of doubles.
void	transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) Transforms an array of floating point coordinates by this transform.
void	transform(java.awt.geom.Point2D[] ptSrc, int srcOff, java.awt.geom.Point2D[] ptDst, int dstOff, int numPts) Transforms an array of point objects by this transform.
java.awt.geom.Point2D	transform(java.awt.geom.Point2D ptSrc, java.awt.geom.Point2D ptDst) Transforms the specified ptSrc and stores the result in ptDst.
java.awt.geom.Rectangle2D	transform(java.awt.geom.Rectangle2D rectSrc, java.awt.geom.Rectangle2D rectDst) Transforms the specified rectSrc and stores the result in rectDst.
void	translate(float dx, float dy) Translate the object by the specified deltaX and deltaY
void	translate(float dx, float dy, int millis, ZSurface surface) Animate the object from its current position by the specified deltaX and deltaY
void	translateTo(float x, float y) Translate the object to the specified position
void	translateTo(float x, float y, int millis, ZSurface surface) Animate the object from its current position to the positino specified by x, y
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 java.lang.Object

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

Field Detail

transform

protected java.awt.geom.AffineTransform transform

parent

protected ZScenegraphObject parent

Constructor Detail

ZTransform

public ZTransform()

Create an ZTransform based on an identity AffineTransform

ZTransform

public ZTransform(java.awt.geom.AffineTransform at)

Create an ZTransform based on AffineTransform parameter

Parameters:

at -

ZTransform

public ZTransform(ZTransform xf)

Constructs a new ZTransform that is a copy of the specified ZTransform (i.e., a "copy constructor"). The portion of the reference ZTransform that is duplicated is that necessary to reuse the ZTransform elsewhere, and so the new transform does not have a parent,

Method Detail

clone

public java.lang.Object clone()

Duplicates the current ZTransform by using the copy constructor. See the copy constructor comments for complete information about what is duplicated.

Overrides:

clone in class java.lang.Object

See Also:

ZTransform(ZTransform)

getAffineTransform

public java.awt.geom.AffineTransform getAffineTransform()

Get copy of affine transform stored in the ZTransform.

getType

public int getType()

Return the type of transform as specified by AffineTransform.

See Also:

AffineTransform.getType()

createInverse

public ZTransform createInverse()

Create inverse ZTransform.

createInverseAffineTransform

public java.awt.geom.AffineTransform createInverseAffineTransform()

Create inverse affine transform stored in the ZTransform.

setAffineTransform

public void setAffineTransform(java.awt.geom.AffineTransform tx)

Set the underlying affine transform that this ZTransform wraps. This call results in the scenegraph object associated with this transform to be damaged, and it and its children's bounds to be updated. The transform passed in is copied, and thus can be used by the caller afterwards without affecting this ZTransform.

Parameters:

tx - The new affine transform

setAffineTransform

public void setAffineTransform(double m00,
                               double m10,
                               double m01,
                               double m11,
                               double m02,
                               double m12)

Set the underlying affine transform that this ZTransform wraps. This call results in the scenegraph object associated with this transform to be damaged, and it and its children's bounds to be updated. The transform passed in is copied, and thus can be used by the caller afterwards without affecting this ZTransform.

Parameters:

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

concatenate

public void concatenate(java.awt.geom.AffineTransform tx)

Concatenates an AffineTransform tx to this AffineTransform Cx in the most commonly useful way to provide a new user space that is mapped to the former user space by Tx. Cx is updated to perform the combined transformation. Transforming a point p by the updated transform Cx' is equivalent to first transforming p by Tx and then transforming the result by the original transform Cx like this: Cx'(p) = Cx(Tx(p)) In matrix notation, if this transform Cx is represented by the matrix [this] and Tx is represented by the matrix [Tx] then this method does the following:

		[this] = [this] x [Tx]
 

Parameters:

Tx - the AffineTransform object to be concatenated with this AffineTransform object.

See Also:

preConcatenate(java.awt.geom.AffineTransform)

preConcatenate

public void preConcatenate(java.awt.geom.AffineTransform tx)

Concatenates an AffineTransform Tx to this AffineTransform Cx in a less commonly used way such that Tx modifies the coordinate transformation relative to the absolute pixel space rather than relative to the existing user space. Cx is updated to perform the combined transformation. Transforming a point p by the updated transform Cx' is equivalent to first transforming p by the original transform Cx and then transforming the result by Tx like this: Cx'(p) = Tx(Cx(p)) In matrix notation, if this transform Cx is represented by the matrix [this] and Tx is represented by the matrix [Tx] then this method does the following:

		[this] = [Tx] x [this]
 

Parameters:

Tx - the AffineTransform object to be concatenated with this AffineTransform object.

See Also:

concatenate(java.awt.geom.AffineTransform)

getMatrix

public void getMatrix(double[] flatmatrix)

Retrieves the 6 specifiable values in the 3x3 affine transformation matrix that this ZTransform wraps, and places them into an array of double precisions values. The values are stored in the array as { m00 m10 m01 m11 m02 m12 }. An array of 4 doubles can also be specified, in which case only the first four elements representing the non-transform parts of the array are retrieved and the values are stored into the array as { m00 m10 m01 m11 }

Parameters:

flatmatrix - the double array used to store the returned values.

getParent

public ZScenegraphObject getParent()

setParent

public void setParent(ZScenegraphObject aParent)

transform

public java.awt.geom.Point2D transform(java.awt.geom.Point2D ptSrc,
                                       java.awt.geom.Point2D ptDst)

Transforms the specified ptSrc and stores the result in ptDst. If ptDst is null, a new Point2D object is allocated and then the result of the transformation is stored in this object. In either case, ptDst, which contains the transformed point, is returned for convenience. If ptSrc and ptDst are the same object, the input point is correctly overwritten with the transformed point.

Parameters:

ptSrc - the specified Point2D to be transformed

ptDst - the specified Point2D that stores the result of transforming ptSrc

Returns:

the ptDst after transforming ptSrc and storing the result in ptDst.

transform

public void transform(java.awt.geom.Point2D[] ptSrc,
                      int srcOff,
                      java.awt.geom.Point2D[] ptDst,
                      int dstOff,
                      int numPts)

Transforms an array of point objects by this transform. If any element of the ptDst array is null, a new Point2D object is allocated and stored into that element before storing the results of the transformation.

Note that this method does not take any precautions to avoid problems caused by storing results into Point2D objects that will be used as the source for calculations further down the source array. This method does guarantee that if a specified Point2D object is both the source and destination for the same single point transform operation then the results will not be stored until the calculations are complete to avoid storing the results on top of the operands. If, however, the destination Point2D object for one operation is the same object as the source Point2D object for another operation further down the source array then the original coordinates in that point are overwritten before they can be converted.

Parameters:

ptSrc - the array containing the source point objects

ptDst - the array into which the transform point objects are returned

srcOff - the offset to the first point object to be transformed in the source array

dstOff - the offset to the location of the first transformed point object that is stored in the destination array

numPts - the number of point objects to be transformed

transform

public void transform(float[] srcPts,
                      int srcOff,
                      float[] dstPts,
                      int dstOff,
                      int numPts)

Transforms an array of floating point coordinates by this transform. The two coordinate array sections can be exactly the same or can be overlapping sections of the same array without affecting the validity of the results. This method ensures that no source coordinates are overwritten by a previous operation before they can be transformed. The coordinates are stored in the arrays starting at the specified offset in the order [x0, y0, x1, y1, ..., xn, yn].

Parameters:

ptSrc - the array containing the source point coordinates. Each point is stored as a pair of x, y coordinates.

ptDst - the array into which the transformed point coordinates are returned. Each point is stored as a pair of x, y coordinates.

srcOff - the offset to the first point to be transformed in the source array

dstOff - the offset to the location of the first transformed point that is stored in the destination array

numPts - the number of points to be transformed

transform

public void transform(double[] srcPts,
                      int srcOff,
                      double[] dstPts,
                      int dstOff,
                      int numPts)

Transforms an array of double precision coordinates by this transform. The two coordinate array sections can be exactly the same or can be overlapping sections of the same array without affecting the validity of the results. This method ensures that no source coordinates are overwritten by a previous operation before they can be transformed. The coordinates are stored in the arrays starting at the indicated offset in the order [x0, y0, x1, y1, ..., xn, yn].

Parameters:

srcPts - the array containing the source point coordinates. Each point is stored as a pair of x, y coordinates.

dstPts - the array into which the transformed point coordinates are returned. Each point is stored as a pair of x, y coordinates.

srcOff - the offset to the first point to be transformed in the source array

dstOff - the offset to the location of the first transformed point that is stored in the destination array

numPts - the number of point objects to be transformed

transform

public void transform(float[] srcPts,
                      int srcOff,
                      double[] dstPts,
                      int dstOff,
                      int numPts)

Transforms an array of floating point coordinates by this transform and stores the results into an array of doubles. The coordinates are stored in the arrays starting at the specified offset in the order [x0, y0, x1, y1, ..., xn, yn].

Parameters:

ptSrc - the array containing the source point coordinates. Each point is stored as a pair of x, y coordinates.

ptDst - the array into which the transformed point coordinates are returned. Each point is stored as a pair of x, y coordinates.

srcOff - the offset to the first point to be transformed in the source array

dstOff - the offset to the location of the first transformed point that is stored in the destination array

numPts - the number of points to be transformed

transform

public void transform(double[] srcPts,
                      int srcOff,
                      float[] dstPts,
                      int dstOff,
                      int numPts)

Transforms an array of double precision coordinates by this transform and stores the results into an array of floats. The coordinates are stored in the arrays starting at the specified offset in the order [x0, y0, x1, y1, ..., xn, yn].

Parameters:

srcPts - the array containing the source point coordinates. Each point is stored as a pair of x, y coordinates.

dstPts - the array into which the transformed point coordinates are returned. Each point is stored as a pair of x, y coordinates.

srcOff - the offset to the first point to be transformed in the source array

dstOff - the offset to the location of the first transformed point that is stored in the destination array

numPts - the number of point objects to be transformed

transform

public java.awt.geom.Rectangle2D transform(java.awt.geom.Rectangle2D rectSrc,
                                           java.awt.geom.Rectangle2D rectDst)

Transforms the specified rectSrc and stores the result in rectDst. If rectDst is null, a new Rectangle2D object is allocated and then the result of the transformation is stored in this object. In either case, rectDst, which contains the transformed point, is returned for convenience. If rectSrc and rectDst are the same object, the input rectangle is correctly overwritten with the transformed rectangle.

Parameters:

rectSrc - the specified Rectangle2D to be transformed

rectDst - the specified Rectangle2D that stores the result of transforming rectSrc

Returns:

the rectDst after transforming rectSrc and storing the result in recttDst.

inverseTransform

public void inverseTransform(java.awt.geom.Point2D srcPt,
                             java.awt.geom.Point2D destPt)

inverseTransform

public void inverseTransform(java.awt.geom.Rectangle2D srcRect,
                             java.awt.geom.Rectangle2D destRect)

inverseTransform

public void inverseTransform(java.awt.geom.Area area)

getTranslation

public java.awt.geom.Point2D getTranslation()

Returns the current translation of this object

Returns:

the translation

translate

public void translate(float dx,
                      float 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(float dx,
                      float dy,
                      int millis,
                      ZSurface 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.

translateTo

public void translateTo(float x,
                        float y)

Translate the object to the specified position

Parameters:

x - X-coord of translation

y - Y-coord of translation

translateTo

public void translateTo(float x,
                        float y,
                        int millis,
                        ZSurface surface)

Animate the object from its current position to the positino 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 float 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(float 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(float dz,
                  float x,
                  float 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(float dz,
                  int millis,
                  ZSurface 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(float dz,
                  float x,
                  float y,
                  int millis,
                  ZSurface 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.

scaleTo

public void scaleTo(float finalz)

Set the scale of the object to the specified target scale.

Parameters:

finalz - final scale factor

scaleTo

public void scaleTo(float finalz,
                    float x,
                    float 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

scaleTo

public void scaleTo(float finalz,
                    int millis,
                    ZSurface 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.

scaleTo

public void scaleTo(float finalz,
                    float x,
                    float y,
                    int millis,
                    ZSurface 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.

getRotation

public float getRotation()

Returns the current rotation (Z-axis) of this object Not currently immplemented BDMREV

Returns:

the scale

rotate

public void rotate(float theta)

Rotate the object by the specified amount

Parameters:

theta - angle to rotate (in radians)

rotate

public void rotate(float theta,
                   float xctr,
                   float yctr)

Rotate the object by the specified amount around the specified anchor point

Parameters:

theta - angle to rotate (in radians)

xctr - X-coord of anchor point

yctr - Y-coord of anchor point

rotate

public void rotate(float theta,
                   int millis,
                   ZSurface surface)

Rotate the object, via animation, theta radians

Parameters:

theta - angle to rotate (in radians)

millis - Time to animate scale in milliseconds

surface - The surface to updated during animation.

rotate

public void rotate(float theta,
                   float xctr,
                   float yctr,
                   int millis,
                   ZSurface surface)

Rotate the object, via animation, theta radians about the specified anchor point

Parameters:

theta - angle to rotate (in radians)

millis - Number of milliseconds over which to perform the animation

surface - The surface to updated during animation.

position

public void position(java.awt.geom.Point2D srcPt,
                     java.awt.geom.Point2D destPt,
                     ZNode refNode,
                     int millis,
                     ZSurface surface)

This will calculate the necessary transform in order to make this transform's corresponding node appear at a particular position relative to the specified node. The source point specifies a point in the unit square (0, 0) - (1, 1) that represents an anchor point on the corresponding node to this transform. The destination point specifies an anchor point on the reference node. The position method then computes the transform that results in transforming this node so that the source anchor point coincides with the reference anchor point. This can be useful for layout algorithms as it is straightforward to position one object relative to another.

For example, If you have two nodes, A and B, and you call

 Point2D srcPt = new Point2D.Float(1.0f, 0.0f);
 Point2D destPt = new Point2D.Float(0.0f, 0.0f);
 A.position(srcPt, destPt, B, 750);
 

The result is that A will move so that its upper-right corner is at the same place as the upper-left corner of B, and the transition will be smoothly animated over a period of 750 milliseconds.

Parameters:

srcPt - The anchor point on this transform's node (normalized to a unit square)

destPt - The anchor point on destination bounds (normalized to a unit square)

destBounds - The bounds used to calculate this transform's node

millis - Number of milliseconds over which to perform the animation

surface - The surface to updated during animation.

position

public void position(java.awt.geom.Point2D srcPt,
                     java.awt.geom.Point2D destPt,
                     java.awt.geom.Rectangle2D destBounds,
                     int millis,
                     ZSurface surface)

This will calculate the necessary transform in order to make this transform's corresponding node appear at a particular position relative to the specified bounding box. The source point specifies a point in the unit square (0, 0) - (1, 1) that represents an anchor point on the corresponding node to this transform. The destination point specifies an anchor point on the reference node. The position method then computes the transform that results in transforming this node so that the source anchor point coincides with the reference anchor point. This can be useful for layout algorithms as it is straightforward to position one object relative to another.

For example, If you have two nodes, A and B, and you call

 Point2D srcPt = new Point2D.Float(1.0f, 0.0f);
 Point2D destPt = new Point2D.Float(0.0f, 0.0f);
 A.position(srcPt, destPt, B.getGlobalBounds(), 750);
 

The result is that A will move so that its upper-right corner is at the same place as the upper-left corner of B, and the transition will be smoothly animated over a period of 750 milliseconds.

Parameters:

srcPt - The anchor point on this transform's node (normalized to a unit square)

destPt - The anchor point on destination bounds (normalized to a unit square)

destBounds - The bounds used to calculate this transform's node

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 tx,
                    int millis,
                    ZSurface surface)

Set the transform of this object 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. (Note that another version of animate lets you specify the timing of the animation so you can avoid the slow-in slow-out animation if you prefer.)

If millis is 0, then the transform is updated once, and the scene is damaged, but not restored - and thus there are no visible changes on any surface. The caller must call surface.restore(). In this case, the surface is not used, and can be specified as null.

If this transform's parent is null, then there is nothing to animate, and so the transform will just be set directly to the specified transform without any animation.

Parameters:

tx - Final transformation

millis - Number of milliseconds over which to perform the animation

surface - The surface to updated during animation.

See Also:

animate(AffineTransform, int, ZSurface, ZLerp)

animate

public void animate(java.awt.geom.AffineTransform tx,
                    int millis,
                    ZSurface surface,
                    ZLerp lerpTimeFunction)

Set the transform of this object to the specified transform, and animate the change from its current transformation over the specified number of milliseconds. 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 damaged, but not restored - and thus there are no visible changes on any surface. The caller must call surface.restore(). In this case, the surface is not used, and can be specified as null.

The timing of the animation is controlled by the lerpTimeFunction. This is used to specify the rate the animation occurs over time. If this parameter is specified as null, then a standard linear interpolation is used, and the animation goes at a constant speed from beginning to end. The caller can specify alternate functions, however, which can do things like perform a slow-in, slow-out animation.

If this transform's parent is null, then there is nothing to animate, and so the transform will just be set directly to the specified transform without any animation.

Parameters:

tx - Final transformation

millis - Number of milliseconds over which to perform the animation

surface - The surface to updated during animation.

lerpTimeFunction - The function that determines how the timing of the animation should be calculated

See Also:

animate(AffineTransform, int, ZSurface)

animate

public static void animate(ZNode[] nodes,
                           java.awt.geom.AffineTransform[] txs,
                           int millis,
                           ZSurface surface)

Set the transforms of the specified array of nodes to the specified array of transforms, and animate the change over the specified number of milliseconds using a slow-in slow-out animation. The surface specifies which surface should be updated during the animation. (Note that another version of animate lets you specify the timing of the animation so you can avoid the slow-in slow-out animation if you prefer.)

If the size of the nodes and txs arrays are not equal, then only those nodes for which transforms are specified will be animated. That is, the smaller of the two array sizes will be used.

If millis is 0, then the transforms are updated once, and the scene is damaged, but not restored - and thus there are no visible changes on any surface. The caller must call surface.restore(). In this case, the surface is not used, and can be specified as null.

The following code fragment demonstrates the use of this animate method. It creates three rectangles, and animates two of them simultaneously.

     ZRectangle rect1, rect2, rect3;
     ZNode node1, node2, node3;

     rect1 = new ZRectangle(0, 0, 50, 50);
     rect1.setFillColor(Color.red);
     node1 = new ZNode(rect1);
     drawingLayer.addChild(node1);

     rect2 = new ZRectangle(25, 25, 50, 50);
     rect2.setFillColor(Color.blue);
     node2 = new ZNode(rect2);
     drawingLayer.addChild(node2);

     rect3 = new ZRectangle(100, 100, 50, 50);
     rect3.setFillColor(Color.orange);
     node3 = new ZNode(rect3);
     drawingLayer.addChild(node3);

     ZNode[] nodes = new ZNode[2];
     nodes[0] = node1;
     nodes[1] = node2;
     AffineTransform[] txs = new AffineTransform[2];
     txs[0] = new AffineTransform();
     txs[0].scale(2.0f, 2.0f);
     txs[1] = new AffineTransform();
     txs[1].translate(100.0f, 25.0f);
     txs[1].scale(0.5f, 0.5f);

     ZTransform.animate(nodes, txs, 1000, surface);
 

Parameters:

nodes - The array of nodes to be animated

txs - The array of final transformations of the nodes

millis - Number of milliseconds over which to perform the animation

surface - The surface to updated during animation.

See Also:

animate(ZNode[], AffineTransform[], int, ZSurface, ZLerp)

animate

public static void animate(ZNode[] nodes,
                           java.awt.geom.AffineTransform[] txs,
                           int millis,
                           ZSurface surface,
                           ZLerp lerpTimeFunction)

Set the transforms of the specified array of nodes to the specified array of transforms, and animate the change over the specified number of milliseconds. The surface specifies which surface should be updated during the animation.

If the size of the nodes and txs arrays are not equal, then only those nodes for which transforms are specified will be animated. That is, the smaller of the two array sizes will be used.

If millis is 0, then the transforms are updated once, and the scene is damaged, but not restored - and thus there are no visible changes on any surface. The caller must call surface.restore(). In this case, the surface is not used, and can be specified as null.

The timing of the animation is controlled by the lerpTimeFunction. This is used to specify the rate the animation occurs over time. If this parameter is specified as null, then a standard linear interpolation is used, and the animation goes at a constant speed from beginning to end. The caller can specify alternate functions, however, which can do things like perform a slow-in, slow-out animation.

The following code fragment demonstrates the use of this animate method. It creates three rectangles, and animates two of them simultaneously.

     ZRectangle rect1, rect2, rect3;
     ZNode node1, node2, node3;

     rect1 = new ZRectangle(0, 0, 50, 50);
     rect1.setFillColor(Color.red);
     node1 = new ZNode(rect1);
     drawingLayer.addChild(node1);

     rect2 = new ZRectangle(25, 25, 50, 50);
     rect2.setFillColor(Color.blue);
     node2 = new ZNode(rect2);
     drawingLayer.addChild(node2);

     rect3 = new ZRectangle(100, 100, 50, 50);
     rect3.setFillColor(Color.orange);
     node3 = new ZNode(rect3);
     drawingLayer.addChild(node3);

     ZNode[] nodes = new ZNode[2];
     nodes[0] = node1;
     nodes[1] = node2;
     AffineTransform[] txs = new AffineTransform[2];
     txs[0] = new AffineTransform();
     txs[0].scale(2.0f, 2.0f);
     txs[1] = new AffineTransform();
     txs[1].translate(100.0f, 25.0f);
     txs[1].scale(0.5f, 0.5f);

     ZTransform.animate(nodes, txs, 1000, surface);
 

Parameters:

nodes - The array of nodes to be animated

txs - The array of final transformations of the nodes

millis - Number of milliseconds over which to perform the animation

surface - The surface to updated during animation.

lerpTimeFunction - The function that determines how the timing of the animation should be calculated

toString

public java.lang.String toString()

Generate a string that represents this object for debugging.

Returns:

the string that represents this object for debugging

Overrides:

toString in class java.lang.Object

writeObject

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

Write out all of this object's state.

Specified by:

writeObject in interface ZSerializable

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

Specified by:

writeObjectRecurse in interface ZSerializable

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.

Specified by:

setState in interface ZSerializable

Parameters:

fieldType - The fully qualified type of the field

fieldName - The name of the field

fieldValue - The value of the field