vmm.core
Class Transform

java.lang.Object
  vmm.core.Transform

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

Transform3D

public class Transform
extends java.lang.Object
implements java.lang.Cloneable

The transform that should be applied when an Exhibit is drawn. This class represents a 2D "Window-to-Viewport" transformation. (A 3D transform subclass will also include the projection transformation from 3D to 2D.) For example, an object of this type is used as a parmeter to Exhibit.doDraw(Graphics2D, View, Transform).

An object of this class represents a rectangular "window" in the xy-plane and possibly a corresponding rectagular "viewport" of pixels. (The viewport is only valid during actual drawing operations, where the destination of the drawing is known; however, the transform is only likely to be used when this is true.) The window-to-viewport transformation is the one that is applied to xy-coordinates to transform them to pixel coordinates -- this transformation can be applied either automatically (when the apply2DTransform parameter to the setUpDrawInfo(java.awt.Graphics2D, int, int, int, int, boolean, boolean) method is set to true), or it can be performed by hand using information contained in the Transform object.

The rectangle in the xy-plane is represented by four numbers xmin, xmax, ymin, and ymax. The pixel area is represented by the coordinates of its upper left corner (x and y) and by its width and height. The values of x, y, width, and height can be set only by calling the setUpDrawInfo method. Otherwise, they are 0. Note that this class does NOT enforce xmax greater than xmin or ymax greater than ymin. It does enforce that width and height are greater than 0. Note that the xmin, xmax, ymin, ymax might be adjusted from the values requested when setUpDrawInfo is called with preserveAspect set to true.

A Transform emits a ChangeEvent when the requested window (xmin,xmax,ymin,ymax) changes; it does not emit a ChangeEvent when the viewport (pixel rectangle to which the window is mapped) changes. A Transform3D also emits a ChangeEvent when the 3D view changes.

Field Summary

protected java.awt.Graphics2D	g The graphics context that this transorm has been set up for drawing to.
protected java.awt.Graphics2D	untransformedGraphics The untransformed graphics context (see getUntransformedGraphics()).

Constructor Summary

Transform()
Create a Transform object with a default window with range -5 to 5 in both the horizontal and vertical direction in the xy-plane.

Transform(double nominalGraphicScale)
Sets the limits on the x- and y-axis so that the number of pixels per unit along the x- and y-axis is given by the parameter nominalGraphicScale, assuming that the viewport has a "normal size".

Transform(double xmin, double xmax, double ymin, double ymax)
Create a Transform object representing a specified window in the xy-plane.

Transform(Transform tr)
Constructs a Transform by copying the requested xmin, xmax, ymin, and ymax from a specified transform.

Method Summary

void	addChangeListener(javax.swing.event.ChangeListener listener) Add a ChangeListener to this Transform.
boolean	appliedTransform2D() This can be called during drawing to determine whether a 2D transform was already applied to the Graphics2D drawing context.
java.lang.Object	clone() Returns a copy of this Transform.
boolean	equals(java.lang.Object obj) This object equals obj if obj is a non-null object of type Transform with the same window and viewport limits as this object.
void	finishDrawing() This is called by View, and is not meant to be called directly.
protected void	fireTransformChangeEvent() Sends a ChangeEvent to registered ChangeListeners.
float	getDefaultStrokeSize() This can be called during drawing to determine the width of the default stroke in the graphics context.
java.awt.Graphics2D	getGraphics() Returns the regular graphics context used during the current drawing operation, or returns null if no drawing operation is in progress.
int	getHeight() Get the height, in pixels of the drawing area.
double	getPixelHeight() This can be called during drawing to determine the actual height of a pixel in the drawing area.
double	getPixelWidth() This can be called during drawing to determine the actual width of a pixel in the drawing area.
java.awt.Graphics2D	getUntransformedGraphics() This can be called during drawing to get a graphics context to which no transform was applied.
int	getWidth() Get the width, in pixels of the drawing area.
int	getX() Get the x-coordinate, measured in pixels, of the upper left corner of the drawing area.
double	getXmax() Get the xmax value.
double	getXmaxRequested() Returns the xmax value specified in the constructor or in the setLimits method.
double	getXmin() Get the xmin value.
double	getXminRequested() Returns the xmin value specified in the constructor or inthe setLimits method.
int	getY() Get the y-coordinate, measured in pixels, of the upper left corner of the drawing area.
double	getYmax() Get the ymax value.
double	getYmaxRequested() Returns the ymax value specified in the constructor or in the setLimits method.
double	getYmin() Get the ymin value.
double	getYminRequested() Returns the ymin value specified in the constructor or in the setLimits method.
boolean	hasSameViewTransform(Transform tr)
void	removeChangeListener(javax.swing.event.ChangeListener listener) Remove a ChangeListener from this Transform.
protected void	resetLimits(double xmin, double xmax, double ymin, double ymax) Resets the x- and y-limits to specified values; for very limited use in subclasses.
void	setLimits(double xmin, double xmax, double ymin, double ymax) Set the window in the xy-plane for this Transform.
void	setUpDrawInfo(java.awt.Graphics2D g, int x, int y, int width, int height, boolean preserveAspect, boolean applyTransform2D) Sets up this Transform for drawing in a given graphics context.
void	viewportToWindow(java.awt.geom.Point2D pt) This can be called during drawing to convert a point given in terms of pixels to xy-coordinates.
void	windowToDrawingCoords(java.awt.geom.Point2D pt) Transforms a point that is in window xy-coordinates to a point that can be used in this transform's regular drawing context.
void	windowToViewport(java.awt.geom.Point2D pt) This can be called during drawing to convert a point given in terms of xy-coordinates to the corresponding pixel coordinates.

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

g

protected java.awt.Graphics2D g

The graphics context that this transorm has been set up for drawing to. This was forced to be protected to support stereo drawing, which requires that graphics contexts be swapped in and out as drawing switches between left and right eye view.

untransformedGraphics

protected java.awt.Graphics2D untransformedGraphics

The untransformed graphics context (see getUntransformedGraphics()). This was forced to be protected to support stereo drawing, which requires that graphics contexts be swapped in and out as drawing switches between left and right eye view.

Constructor Detail

Transform

public Transform()

Create a Transform object with a default window with range -5 to 5 in both the horizontal and vertical direction in the xy-plane.

Transform

public Transform(double xmin,
                 double xmax,
                 double ymin,
                 double ymax)

Create a Transform object representing a specified window in the xy-plane. The values specified here might be modified later in order to preserve aspect ratio.

Parameters:

xmin - The left limit of the horizontal range of the window.

xmax - The right limit of the horizontal range of the window. It is not enforced that xmax is greater than xmin. (In fact, xmax less than xmin should probalby be OK, while xmax equal to xmin will probably not work.)

ymin - The bottom limit of the vertical range of the window.

ymax - The top limit of the vertical range of the window. It is not enforced that ymax is greater than ymin. (In fact, ymax less than ymin should probalby be OK, while ymax equal to ymin will probably not work.)

Transform

public Transform(double nominalGraphicScale)

Sets the limits on the x- and y-axis so that the number of pixels per unit along the x- and y-axis is given by the parameter nominalGraphicScale, assuming that the viewport has a "normal size".

Parameters:

nominalGraphicScale - number of pixels per unit along the x- and y-axes, assuming that the size of the window is "normal". The normal size is given by a private constant NORMAL_SIZE, which is set to 600 at the time this comment was written.

Transform

public Transform(Transform tr)

Constructs a Transform by copying the requested xmin, xmax, ymin, and ymax from a specified transform.

Parameters:

tr - the non-null transoform to be copied.

Method Detail

setLimits

public void setLimits(double xmin,
                      double xmax,
                      double ymin,
                      double ymax)

Set the window in the xy-plane for this Transform. The values specified here might be modified later in order to preserve aspect ratio. (This method also sets the x, y, width, and height properties of the viewport to zero, but the values of these properties are generally not used until a drawing operation is initiated by calling setUpDrawInfo.)

Parameters:

xmin - The left limit of the horizontal range of the window.

xmax - The right limit of the horizontal range of the window. It is not enforced that xmax is greater than xmin. (In fact, xmax less than xmin should probalby be OK, while xmax equal to xmin will probably not work.)

ymin - The bottom limit of the vertical range of the window.

ymax - The top limit of the vertical range of the window. It is not enforced that ymax is greater than ymin. (In fact, ymax less than ymin should probalby be OK, while ymax equal to ymin will probably not work.)

See Also:

setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean).

resetLimits

protected void resetLimits(double xmin,
                           double xmax,
                           double ymin,
                           double ymax)

Resets the x- and y-limits to specified values; for very limited use in subclasses. This method does nothing except store the specified limits in the corresponding member variables. It could be used to reset the limits during drawing, but only in a View that has the preserveAspect and applyTransform2D properties turned off. (See the nested ProjectedOrbitView class in ODE_2D for an example.)

Parameters:

xmin -

xmax -

ymin -

ymax -

getXmaxRequested

public double getXmaxRequested()

Returns the xmax value specified in the constructor or in the setLimits method. This can differ from the value returned by getXmax(), which can return a value that has been modified in order to preserve the aspect ratio.

getXminRequested

public double getXminRequested()

Returns the xmin value specified in the constructor or inthe setLimits method. This can differ from the value returned by getXmin, which can return a value that has been modified in order to preserve the aspect ratio.

getYmaxRequested

public double getYmaxRequested()

Returns the ymax value specified in the constructor or in the setLimits method. This can differ from the value returned by getYmax, which can return a value that has been modified in order to preserve the aspect ratio.

getYminRequested

public double getYminRequested()

Returns the ymin value specified in the constructor or in the setLimits method. This can differ from the value returned by getYmin, which can return a value that has been modified in order to preserve the aspect ratio.

getXmax

public double getXmax()

Get the xmax value. Note that this might be different from the value specified in the constructor or in setLimits, if the values have been modified to preserve the aspect ratio in setUpDrawInfo.

See Also:

getXmaxRequested()

getXmin

public double getXmin()

Get the xmin value. Note that this might be different from the value specified in the constructor or in setLimits, if the values have been modified to preserve the aspect ratio in setUpDrawInfo. Before a drawing operation is initiated, this returns the same value as the getXminRequested method.

See Also:

getXminRequested()

getYmax

public double getYmax()

Get the ymax value. Note that this might be different from the value specified in the constructor or in setLimits, if the values have been modified to preserve the aspect ratio in setUpDrawInfo.

See Also:

getYmaxRequested()

getYmin

public double getYmin()

Get the ymin value. Note that this might be different from the value specified in the constructor or in setLimits, if the values have been modified to preserve the aspect ratio in setUpDrawInfo.

See Also:

getYminRequested()

getHeight

public int getHeight()

Get the height, in pixels of the drawing area. This is guaranteed to be valid only during drawing of an Exhibit (after it has been set by setUpDrawInfo).

See Also:

setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean)

getWidth

public int getWidth()

Get the width, in pixels of the drawing area. This is guaranteed to be valid only during drawing of an Exhibit (after it has been set by setUpDrawInfo).

See Also:

setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean)

getX

public int getX()

Get the x-coordinate, measured in pixels, of the upper left corner of the drawing area. This is guaranteed to be valid only during drawing of an Exhibit (after it has been set by setUpDrawInfo). In the VMM core, this value is always 0.

See Also:

setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean)

getY

public int getY()

Get the y-coordinate, measured in pixels, of the upper left corner of the drawing area. This is guaranteed to be valid only during drawing of an Exihbit (after it has been set by setUpDrawInfo). In the VMM core, this value is always 0.

See Also:

setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean)

equals

public boolean equals(java.lang.Object obj)

This object equals obj if obj is a non-null object of type Transform with the same window and viewport limits as this object.

Overrides:

equals in class java.lang.Object

hasSameViewTransform

public boolean hasSameViewTransform(Transform tr)

clone

public java.lang.Object clone()

Returns a copy of this Transform. (Note that the list of ChangeListeners that are registered with the transform is NOT copied.)

Overrides:

clone in class java.lang.Object

setUpDrawInfo

public void setUpDrawInfo(java.awt.Graphics2D g,
                          int x,
                          int y,
                          int width,
                          int height,
                          boolean preserveAspect,
                          boolean applyTransform2D)

Sets up this Transform for drawing in a given graphics context. When this method is called, it sets up the values that are returned by other methods in this class, such as getPixelWidth. These values can be used by the Exhibit during drawing, but they do not return useful values at other times. This is called automatically by a View before it draws its Exhibit, and ordinary programmers will generally not have to call it directly. Note that width and height must be positive. If they are not, then nothing is done by this method.

If the applyTransform2D parameter is true, then in addition to applying the transform, the size of the graphic context's stroke is adjusted. The stroke width is multiplied by the pixel size (or, if preserverAspect is false, by the minimum of the pixel width and the pixel height). The result should be that -- provided preserveAspect is true -- the transformation will not affect the apparent width of the stroke.

Parameters:

g - If applyTransform is true (and if g is non-null), then a 2D window-to-viewport transform is set up in this graphics context. If applyTransform is false, this parameter is ignored. (See View.setApplyGraphics2DTransform(boolean) and View.setPreserveAspect(boolean).)

x - The left edge of the viewport (the rectangular drawing area, in pixel coords). At least in the VMM core, this is always zero.

y - The top edge of the viewport (the rectangular drawing area, in pixel coords). At least in the VMM core, this is always zero.

width - The width of the viewport (the rectangular drawing area, in pixel coords).

height - The height of the viewport (the rectangular drawing area, in pixel coords).

preserveAspect - If this is true, then the values of xmin, xmax, ymin, ymax will be modified, if necessary, so that the aspect ratio of the "window" in the xy-plan matches the aspect ratio of the "viewport" in the display area. (See getXmin() and getXminRequested().)

applyTransform2D - If this is true, then the window-to-viewport transformtion will be set up in the Graphics2D drawing context. This will allow drawing to be done using world (real x,y) coordinates directly, rather than using viewport (pixel) coordinates.

finishDrawing

public void finishDrawing()

This is called by View, and is not meant to be called directly. It is called after a drawing action initiated by setUpDrawInfo is complete, to give the Transform object a chance to do any necessary post-drawing cleanup.

See Also:

setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean)

getGraphics

public java.awt.Graphics2D getGraphics()

Returns the regular graphics context used during the current drawing operation, or returns null if no drawing operation is in progress. This is the drawing context passed as the first parameter to setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean). That context is saved during a drawing operation and is reset to null when finishDrawing() is called.

Returns:

The regular graphics context for this Transform. The value is null if no drawing operation is in progress.

See Also:

getUntransformedGraphics()

getUntransformedGraphics

public java.awt.Graphics2D getUntransformedGraphics()

This can be called during drawing to get a graphics context to which no transform was applied. If the applyTransform2D parameter in setUpDrawInfo was false, the return value is just a pointer to the same drawing context that is being used for drawing. Otherwise, it is a graphics context that draws to the same location but to which the 2D transform has not been applied. (However, the color and font of the transformed graphics context have been copied to the untransformed graphics context.)

See Also:

setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean), getGraphics()

viewportToWindow

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

This can be called during drawing to convert a point given in terms of pixels to xy-coordinates. This is also valid after drawing, applying the same transform that was used in the recent drawing operation.

Parameters:

pt - A non-null point containing coords given in pixel coordinates that will be replaced by the corresponding coords in the xy-plane.

windowToViewport

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

This can be called during drawing to convert a point given in terms of xy-coordinates to the corresponding pixel coordinates. This is also valid after drawing, applying the same transform that was used in the recent drawing operation. The point returned by this method can be used for drawing in the untransformed graphics context that is returned by getUntransformedGraphics(). If appliedTransform2D() returns false, then the point can also be used for drawing in the normal graphics context of the transform, since that graphics context is itself untransformed.

Parameters:

pt - A non-null point containing coords in the xy-plane that will be replaced by the corresponding pixel coordinates.

windowToDrawingCoords

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

Transforms a point that is in window xy-coordinates to a point that can be used in this transform's regular drawing context. If appliedTransform2D() is true, then this method has no effect, since the transform is applied automatically in the drawing context and so the window coordinates should be used directly for drawing. However, if appliedTransform2D() is false, then the transform is not being applied automatically in the drawing context, and this method will apply the transformation to the point, so that it becomes appropriate for drawing. (In fact, this method has the same effect as calling windowToViewport(Point2D) in the case where appliedTransform2D is false, and does nothing in the true case.)

Parameters:

pt - A non-null point whose coordinates are modified, if necessary, so they are appropriate for drawing in this transform's normal drawing context.

getPixelWidth

public double getPixelWidth()

This can be called during drawing to determine the actual width of a pixel in the drawing area. If the applyTransform2D parameter in setUpDrawInfo was false, the value that is returned will be 1. If that parameter was true, the return value will be the height of a pixel in the transformed graphics system.

See Also:

View.setApplyGraphics2DTransform(boolean), setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean)

getPixelHeight

public double getPixelHeight()

This can be called during drawing to determine the actual height of a pixel in the drawing area. If the applyTransform2D parameter in setUpDrawInfo was false, the value that is returned will be 1. If that parameter was true, the return value will be the height of a pixel in the transformed graphics system.

See Also:

View.setApplyGraphics2DTransform(boolean), setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean)

getDefaultStrokeSize

public float getDefaultStrokeSize()

This can be called during drawing to determine the width of the default stroke in the graphics context. You can make thicker stokes by using multiples of the value returned by this method.

See Also:

View.setStrokeSizeMultiplier(int)

appliedTransform2D

public boolean appliedTransform2D()

This can be called during drawing to determine whether a 2D transform was already applied to the Graphics2D drawing context. This returns the value of the applyTransform2D parameter when setUpDrawInfo was called.

See Also:

setUpDrawInfo(Graphics2D, int, int, int, int, boolean, boolean)

addChangeListener

public void addChangeListener(javax.swing.event.ChangeListener listener)

Add a ChangeListener to this Transform. Change events are sent when the window (xmin,xmax,ymin,ymax) is changed. It should not be necessary for ordinary programmers to call or to override this method. Views are automatically set up as ChangeListeners for their transforms.

Parameters:

listener - The listener to be added. If the value is null, nothing is done.

removeChangeListener

public void removeChangeListener(javax.swing.event.ChangeListener listener)

Remove a ChangeListener from this Transform.

Parameters:

listener - The listener to be removed. If it is not currently registered with the Transform, then nothing is done.

See Also:

addChangeListener(ChangeListener)

fireTransformChangeEvent

protected void fireTransformChangeEvent()

Sends a ChangeEvent to registered ChangeListeners.