edu.umd.cs.jazz.scenegraph
Class ZSurface

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

public class ZSurface

extends java.lang.Object

implements java.awt.print.Printable

ZSurface represents the surface on which a camera can project. A surface can be mapped to a Java Component (AWT or Swing), a back buffer or image, or a printer - actually, anything that can generate a Graphics2D - the Java2D render context. The surface is primarily responsible for performing region management. It manages the "dirty" areas of the scenegraph that have to be repainted.

See Also:

ZNode

Field Summary

protected ZCamera	camera
protected javax.swing.JComponent	component
protected ZArea	damagedArea
static int	DEFAULT_HALO
protected boolean	interacting
protected int	nonInteractingRenderQuality
static int	RENDER_QUALITY_HIGH
static int	RENDER_QUALITY_LOW
protected int	renderQuality
protected boolean	repaintRequest

Constructor Summary

ZSurface()
Constructs a new Surface.

ZSurface(ZCamera camera)
Constructs a new Surface.

ZSurface(ZCamera camera, javax.swing.JComponent aComponent)
Constructs a new Surface.

Method Summary

void	damage(ZBounds bounds) Notifies this surface that the specified bounds have changed, and that portion of the surface should be repainted at the next restore.
void	endInteraction() Applications should call endInteraction when the user finishes a graphical interaction.
ZCamera	getCamera() Get the camera this surface is associated with.
boolean	isInteracting() Determine if the user interacting with the surface
void	paint(java.awt.Graphics g) Paints the camera this surface sees.
ZNode	pick(int x, int y) Returns the first object intersecting the specified rectangle within DEFAULT_HALO pixels as searched in reverse (front-to-back) order, or null if no objects satisfy criteria.
ZNode	pick(int x, int y, int halo) Returns the first object intersecting the specified rectangle within halo pixels as searched in reverse (front-to-back) order, or null if no objects satisfy criteria.
int	print(java.awt.Graphics graphics, java.awt.print.PageFormat pageFormat, int pageIndex) Prints the surface into the specified Graphics context in the specified format.
void	printSurface() Constructs a new PrinterJob, allows the user to select which printer to print to, and prints the surface.
void	repaint() A utility function to repaint the entire component.
void	restore() This queues a request to restore (i.e.
void	restore(boolean restoreImmediately) This causes a restore (i.e.
void	setCamera(ZCamera cam) Sets the component (i.e., window) that this camera is rendered within.
void	setComponent(javax.swing.JComponent aComponent) Set the component that this surface is attached to, or null if none.
void	setInteracting(boolean v) Specifies that the user is interacting with the surface.
protected void	setRenderingHints(java.awt.Graphics2D g2, int quality) Sets the rendering hints of the specified graphics to either or high or low.
void	setRenderQuality(int qualityRequested) Specify that future rendering should occur at the specified quality.
void	startInteraction() Applications should call startInteraction when the user is starting a graphical interaction, so Jazz can properly monitor rendering speed.
java.lang.String	toString() Generate a string that represents this object for debugging.

Methods inherited from class java.lang.Object

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

Field Detail

RENDER_QUALITY_LOW

public static final int RENDER_QUALITY_LOW

RENDER_QUALITY_HIGH

public static final int RENDER_QUALITY_HIGH

DEFAULT_HALO

public static final int DEFAULT_HALO

damagedArea

protected transient ZArea damagedArea

repaintRequest

protected boolean repaintRequest

renderQuality

protected int renderQuality

nonInteractingRenderQuality

protected int nonInteractingRenderQuality

camera

protected transient ZCamera camera

interacting

protected boolean interacting

component

protected javax.swing.JComponent component

Constructor Detail

ZSurface

public ZSurface()

Constructs a new Surface. Surfaces are associated with a top-level camera and serves as the surface onto which the camera projects.

ZSurface

public ZSurface(ZCamera camera)

Constructs a new Surface. Surfaces are always associated with a scenegraph, but are not attached to any output device (such as a window or a portal) to start. If this surface is attached to a window, then its component must be set with setComponent(javax.swing.JComponent)

Parameters:

node - The part of the scenegraph this camera sees.

ZSurface

public ZSurface(ZCamera camera,
                javax.swing.JComponent aComponent)

Constructs a new Surface. Surfaces 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.

aComponent - The component this surface is connected to

Method Detail

setComponent

public void setComponent(javax.swing.JComponent aComponent)

Set the component that this surface is attached to, or null if none.

Parameters:

aComponent - The component this surface is attached to, or null if none.

setCamera

public void setCamera(ZCamera cam)

Sets the component (i.e., window) that this camera is rendered within.

getCamera

public ZCamera getCamera()

Get the camera this surface is associated with.

Returns:

the camera this surface is associated with.

startInteraction

public void startInteraction()

Applications should call startInteraction when the user is starting a graphical interaction, so Jazz can properly monitor rendering speed. If the system slows down during an interaction, rendering quality may be reduced to try and improve speed. Note that it is necessary for the application to notify the system when interaction is occurring. If Jazz tried to balance load completely on its own, it might decide that an interaction had finished and that it was ok to re-render in full high-quality while the user was still interacting in which case the user may well have to wait for the render to reach a point where it could be interrupted.

See Also:

endInteraction()

endInteraction

public void endInteraction()

Applications should call endInteraction when the user finishes a graphical interaction. This is necessary as Jazz may have rendered some things at low quality in which case they will have to be re-rendered at full quality.

See Also:

startInteraction()

isInteracting

public boolean isInteracting()

Determine if the user interacting with the surface

Returns:

Value of interacting.

setInteracting

public void setInteracting(boolean v)

Specifies that the user is interacting with the surface.

Parameters:

v - Value to assign to interacting.

setRenderQuality

public void setRenderQuality(int qualityRequested)

Specify that future rendering should occur at the specified quality. Normally, an application should not have to call this method directly, although it can.

Parameters:

qualityRequested - Can be RENDER_QUALITY_LOW or RENDER_QUALITY_HIGH.

setRenderingHints

protected void setRenderingHints(java.awt.Graphics2D g2,
                                 int quality)

Sets the rendering hints of the specified graphics to either or high or low. This gets called whenever the surface is painted, and specifies how high and low quality are defined.

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

damage

public void damage(ZBounds bounds)

Notifies this surface that the specified bounds have changed, and that portion of the surface should be repainted at the next restore. Damaged area is accumulated in global coordinates.

Parameters:

bounds - The bounds that need to be redrawn (in global coordinates).

repaint

public void repaint()

A utility function to repaint the entire component. This results in request being queued for the entire component to be painted. The paint does not happen immediately, but instead occurs when the queued request comes to the head of the Swing event queue and is fired.

restore

public void restore()

This queues a request to restore (i.e. repaint) the damaged area of the scenegraph. Only the portion of the scene that has changed (as specified by calls to damage) will be repainted. The paint does not happen immediately, but instead occurs when the queued request comes to the head of the Swing event queue and is fired. In this case, multiple queued restore commands are automatically combined and result in a single paint call.

See Also:

damage(ZBounds)

restore

public void restore(boolean restoreImmediately)

This causes a restore (i.e. repaint) of the damaged area of the scenegraph. Only the portion of the scene that has changed (as specified by calls to damage) will be repainted. The caller can specify whether the restoration happens immediately, or if a request is queued. If the request is queued, then the paint does not happen immediately, but instead occurs when the queued request comes to the head of the Swing event queue and is fired. In this case, multiple queued restore commands are automatically combined and result in a single paint call.

Parameters:

restoreImmediately - True to specify that the restoration happens immediately, or false to queue a request.

See Also:

damage(ZBounds)

paint

public void paint(java.awt.Graphics g)

Paints the camera this surface sees.

Parameters:

renderContext - The graphics context to use for rendering.

pick

public ZNode pick(int x,
                  int y)

Returns the first object intersecting the specified rectangle within DEFAULT_HALO pixels as searched in reverse (front-to-back) order, or null if no objects satisfy criteria.

Parameters:

x - X-coord of pick point in window coordinates.

y - Y-coord of pick point in window coordinates.

Returns:

The picked object.

pick

public ZNode pick(int x,
                  int y,
                  int halo)

Returns the first object intersecting the specified rectangle within halo pixels as searched in reverse (front-to-back) order, or null if no objects satisfy criteria.

Parameters:

x - X-coord of pick point in window coordinates.

y - Y-coord of pick point in window coordinates.

halo - The amount the point can miss an object and still pick it

Returns:

The picked object.

printSurface

public void printSurface()

Constructs a new PrinterJob, allows the user to select which printer to print to, and prints the surface.

print

public int print(java.awt.Graphics graphics,
                 java.awt.print.PageFormat pageFormat,
                 int pageIndex)

Prints the surface into the specified Graphics context in the specified format. A PrinterJob calls the printable interface to request that a surface be rendered into the context specified by the graphics. The format of the page to be drawn is specified by PageFormat. The zero based index of the requested page is specified by pageIndex. If the requested page does not exist then this method returns NO_SUCH_PAGE; otherwise PAGE_EXISTS is returned. If the printable object aborts the print job then it throws a PrinterException

Specified by:

print in interface java.awt.print.Printable

Parameters:

graphics - the context into which the page is drawn

pageFormat - the size and orientation of the page being drawn

pageIndex - the zero based index of the page to be drawn