org.j3d.renderer.java3d.overlay
Class OverlayBase

java.lang.Object
  org.j3d.renderer.java3d.overlay.OverlayBase

All Implemented Interfaces:

java.awt.event.ComponentListener, java.util.EventListener, Overlay, ScreenComponent, UpdatableEntity

Direct Known Subclasses:

ImageOverlay, InteractiveOverlayBase, LabelOverlay

public abstract class OverlayBase

extends java.lang.Object

implements Overlay, ScreenComponent, java.awt.event.ComponentListener

An implementation of the overlay and screen component interfaces to provide a ready-made overlay system.

The implementation uses textured objects that are mapped to screen space coordinates. This can be both good and bad. The overlay can operate in one of two modes - fixed size, dynamic size according to the canvas.

Fixed Size Overlays

The size should be set to a value that is a power of two for the best performance. The code divides the supplied area into smaller sections, with a maximum size of 256 pixels in either direction. Left over pieces are then subdivided into lots that are power of two. The minimum size of one of these pieces is 16 pixels. If you have an odd size, sich as 55 pixels, then you get weird artifacts appearing on screen.

A fixed size overlay may operate without being given a canvas to work with. This would be used when you are using an overlay manager to work with the overlay instance.

Resizable Overlays

A resizable overlay is created when the bounds are set to null in the constructor. In this case the overlay then listens for resizing information from the component and resizes the internal subsections to accomodate this. For this system, in order to remain visually accurate, we subdivide down to shapes that are 1 pixel across. Obviously this impacts performance quite dramatically to have so many tiny objects.

The class implements the AWT component listener interface so that it can automatically resize the overlay's base image in response to the canvas changing size. This will ensure that everything is correctly located on the screen after the resize.

All overlays start at the origin of 0,0 and have some form of width associated with them. This code does not look after any layout requirements. It is expected the application will take care of the layout management of the overlays.

Version:

$Revision: 1.4 $

Author:

David Yazel, Justin Couch

Field Summary

protected int	activeBuffer The currently active buffer index
protected java.awt.Color	backgroundColor Background colour of the overlay
protected int	backgroundMode The current background mode.
protected int	bottomInset Inset (border spacing) for the bottom edge
protected java.awt.image.BufferedImage	canvas Drawing area that we scribble our stuff on
protected java.awt.Dimension	componentSize The bounds of the Canvas3D this overlay is rendered in
protected javax.media.j3d.BranchGroup	consoleBG Root branchgroup for the entire overlay system
protected javax.media.j3d.TransformGroup	consoleTG Transformation to make the raster become screen coords as well
protected static int	DEFAULT_INSET Default amount of inset that this overlay uses
protected static int	DIRTY_ACTIVE_BUFFER Mark the active buffer as dirty and needing swapping
protected static int	DIRTY_POSITION Mark the position as dirty and needing correction
protected static int	DIRTY_SIZE Mark the size as dirty and needing correction
protected static int	DIRTY_VISIBLE Mark the visible flag as dirty
protected double	fieldOfView The field of view for the canvas
protected boolean	fixedSize Flag indicating whether this is a fixed size or resizable overlay.
protected int	leftInset Inset (border spacing) for the left edge
protected java.awt.Rectangle	overlayBounds Canvas bounds occupied by this overlay.
protected javax.media.j3d.BranchGroup	overlayTexGrp Contains the texture objects from the suboverlays.
protected int	rightInset Inset (border spacing) for the right edge
protected org.j3d.renderer.java3d.overlay.SubOverlay[]	subOverlay The list of sub-overlay areas.
protected int	topInset Inset (border spacing) for the top edge

Fields inherited from interface org.j3d.renderer.java3d.overlay.Overlay

BACKGROUND_COPY, BACKGROUND_NONE

Constructor Summary

protected	OverlayBase(javax.media.j3d.Canvas3D canvas, java.awt.Dimension size) Creates a new overlay covering the given canvas bounds.
protected	OverlayBase(javax.media.j3d.Canvas3D canvas, java.awt.Dimension size, boolean clipAlpha, boolean blendAlpha) Constructs an overlay window that can have alpha capabilities.
protected	OverlayBase(javax.media.j3d.Canvas3D canvas, java.awt.Dimension size, boolean clipAlpha, boolean blendAlpha, UpdateManager updateManager) Constructs an overlay window.
protected	OverlayBase(javax.media.j3d.Canvas3D canvas, java.awt.Dimension size, boolean clipAlpha, boolean blendAlpha, UpdateManager updateManager, int numBuffers) Constructs an overlay window.
protected	OverlayBase(javax.media.j3d.Canvas3D canvas, java.awt.Dimension size, UpdateManager manager) Constructs an overlay window with an update manager.

Method Summary

void	componentHidden(java.awt.event.ComponentEvent e) Notification that the component has been hidden.
void	componentMoved(java.awt.event.ComponentEvent e) Notification that the component has been moved.
void	componentResized(java.awt.event.ComponentEvent e) Notification that the component has been resized.
void	componentShown(java.awt.event.ComponentEvent e) Notification that the component has been shown.
boolean	contains(java.awt.Point p) Check to see if the point passed in is contained within the bounds of the overlay.
protected void	dirty(int property) Mark a specific property as being dirty and needing to be rechecked.
java.awt.image.BufferedImage	getBackgroundImage() Returns the background for the overlay.
java.awt.Rectangle	getBounds() Get the bounds of the visible object in screen space coordinates.
protected java.awt.Graphics2D	getGraphics() Prepares the canvas to be painted.
javax.media.j3d.BranchGroup	getRoot() Return the root of the overlay and its sub-overlays so it can be added to the scene graph.
UpdateManager	getUpdateManager() Returns the UpdateManager responsible for seeing that updates to the Overlay only take place between frames.
void	initialize() Empty method that can be used to provide post construction initialisation.
boolean	isAntialiased() Check to see whether this overlay is currently antialiased.
boolean	isVisible() Returns the visiblity of the Overlay.
void	paint(java.awt.Graphics2D g) This is where the actualy drawing of the window takes place.
void	repaint() This is called to trigger a repaint of the overlay.
protected void	setActiveBuffer(int bufferIndex) Set the active buffer to the new index.
void	setAntialiased(boolean antialiased) Sets whether drawing onto this Overlay is anialiased.
void	setBackgroundColor(java.awt.Color color) Sets the background to a solid color.
void	setBackgroundImage(java.awt.image.BufferedImage img) Sets the background image to the one specified.
void	setBackgroundMode(int mode) Sets the background mode.
void	setComponentDetails(java.awt.Dimension size, double fov) Update the canvas component details of size and field of view settings.
void	setInsets(java.awt.Insets insets) Set the insets for this overlay.
void	setInsets(int left, int top, int right, int bottom) Set the insets for this overlay.
void	setLocation(int x, int y) Sets the location of the top-left corner of the overlay.
void	setSize(int w, int h) Change the size of the texture to the new size.
void	setUpdateManager(UpdateManager mgr) Set the UpdateManager to the new value.
void	setVisible(boolean visible) Changes the visibility of the overlay.
void	update() Notification from the update manager that something has changed and we should fix up the appropriate bits.
protected void	updateBuffer(java.awt.image.BufferedImage image, int bufferIndex) Force an update of the nominated buffer with the contents of the given image.

Methods inherited from class java.lang.Object

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

Field Detail

DIRTY_VISIBLE

protected static final int DIRTY_VISIBLE

Mark the visible flag as dirty

See Also:

Constant Field Values

DIRTY_POSITION

protected static final int DIRTY_POSITION

Mark the position as dirty and needing correction

See Also:

Constant Field Values

DIRTY_ACTIVE_BUFFER

protected static final int DIRTY_ACTIVE_BUFFER

Mark the active buffer as dirty and needing swapping

See Also:

Constant Field Values

DIRTY_SIZE

protected static final int DIRTY_SIZE

Mark the size as dirty and needing correction

See Also:

Constant Field Values

DEFAULT_INSET

protected static final int DEFAULT_INSET

Default amount of inset that this overlay uses

See Also:

Constant Field Values

leftInset

protected int leftInset

Inset (border spacing) for the left edge

rightInset

protected int rightInset

Inset (border spacing) for the right edge

topInset

protected int topInset

Inset (border spacing) for the top edge

bottomInset

protected int bottomInset

Inset (border spacing) for the bottom edge

backgroundMode

protected int backgroundMode

The current background mode. Defaults to copy

overlayBounds

protected java.awt.Rectangle overlayBounds

Canvas bounds occupied by this overlay.

componentSize

protected java.awt.Dimension componentSize

The bounds of the Canvas3D this overlay is rendered in

fieldOfView

protected double fieldOfView

The field of view for the canvas

canvas

protected java.awt.image.BufferedImage canvas

Drawing area that we scribble our stuff on

backgroundColor

protected java.awt.Color backgroundColor

Background colour of the overlay

subOverlay

protected org.j3d.renderer.java3d.overlay.SubOverlay[] subOverlay

The list of sub-overlay areas. Starts pre-created with a zero length array. Blocking is performed using this so it can't be null.

activeBuffer

protected int activeBuffer

The currently active buffer index

consoleBG

protected javax.media.j3d.BranchGroup consoleBG

Root branchgroup for the entire overlay system

overlayTexGrp

protected javax.media.j3d.BranchGroup overlayTexGrp

Contains the texture objects from the suboverlays. Each time the window size changes, this instance is thrown away and replaced with a new one. Ensures that we can change over the raster objects. Always set as child 0 of the consoleBG.

consoleTG

protected javax.media.j3d.TransformGroup consoleTG

Transformation to make the raster become screen coords as well

fixedSize

protected final boolean fixedSize

Flag indicating whether this is a fixed size or resizable overlay. Fixed size is when the user gives us bounds. Resizable when they don't and we track the canvas.

Constructor Detail

OverlayBase

protected OverlayBase(javax.media.j3d.Canvas3D canvas,
                      java.awt.Dimension size)

Creates a new overlay covering the given canvas bounds. It has two buffers. Updates are managed automatically. This Overlay is not usable until you attach it to the view platform transform. If the bounds are null, then resize the overlay to fit the canvas and then track the size of the canvas.

Parameters:

canvas - Canvas being drawn onto

size - The size of the overlay in pixels

Throws:

java.lang.IllegalArgumentException - Both the canvas and bounds are null

OverlayBase

protected OverlayBase(javax.media.j3d.Canvas3D canvas,
                      java.awt.Dimension size,
                      UpdateManager manager)

Constructs an overlay window with an update manager. It has two buffers. This window will not be visible unless it is added to the scene under the view platform transform. If the bounds are null, then resize the overlay to fit the canvas and then track the size of the canvas.

Parameters:

canvas - The canvas the overlay is drawn on

size - The size of the overlay in pixels

Throws:

java.lang.IllegalArgumentException - Both the canvas and bounds are null

OverlayBase

protected OverlayBase(javax.media.j3d.Canvas3D canvas,
                      java.awt.Dimension size,
                      boolean clipAlpha,
                      boolean blendAlpha)

Constructs an overlay window that can have alpha capabilities. This window will not be visible unless it is added to the scene under the view platform transform. If the bounds are null, then resize the overlay to fit the canvas and then track the size of the canvas.

Parameters:

canvas - The canvas the overlay is drawn on

size - The size of the overlay in pixels

clipAlpha - Should the polygon clip where alpha is zero

blendAlpha - Should we blend to background where alpha is < 1

Throws:

java.lang.IllegalArgumentException - Both the canvas and bounds are null

OverlayBase

protected OverlayBase(javax.media.j3d.Canvas3D canvas,
                      java.awt.Dimension size,
                      boolean clipAlpha,
                      boolean blendAlpha,
                      UpdateManager updateManager)

Constructs an overlay window. This window will not be visible unless it is added to the scene under the view platform transform If the bounds are null, then resize the overlay to fit the canvas and then track the size of the canvas.

Parameters:

canvas - The canvas the overlay is drawn on

size - The size of the overlay in pixels

clipAlpha - Should the polygon clip where alpha is zero

blendAlpha - Should we blend to background where alpha is < 1

updateManager - Responsible for allowing the Overlay to update between renders. If this is null a default manager is created

Throws:

java.lang.IllegalArgumentException - Both the canvas and bounds are null

OverlayBase

protected OverlayBase(javax.media.j3d.Canvas3D canvas,
                      java.awt.Dimension size,
                      boolean clipAlpha,
                      boolean blendAlpha,
                      UpdateManager updateManager,
                      int numBuffers)

Constructs an overlay window. This window will not be visible unless it is added to the scene under the view platform transform If the bounds are null, then resize the overlay to fit the canvas and then track the size of the canvas.

Parameters:

canvas - The canvas the overlay is drawn on

size - The size of the overlay in pixels

clipAlpha - Should the polygon clip where alpha is zero

blendAlpha - Should we blend to background where alpha is < 1

updateManager - Responsible for allowing the Overlay to update between renders. If this is null a default manager is created

numBuffers - The number of buffers to generate, the default is two

Method Detail

initialize

public void initialize()

Empty method that can be used to provide post construction initialisation.

Specified by:

initialize in interface Overlay

setComponentDetails

public void setComponentDetails(java.awt.Dimension size,
                                double fov)

Update the canvas component details of size and field of view settings. This is mainly called when the overlay is part of a larger management system and it needs to inform the overlay of new screen information.

Specified by:

setComponentDetails in interface Overlay

Parameters:

size - The new dimensions of the component

fov - The new field of view for the current view

setLocation

public void setLocation(int x,
                        int y)

Sets the location of the top-left corner of the overlay. It will move the overlay to that position on the next update cycle.

Specified by:

setLocation in interface Overlay

Parameters:

x - The x coordinate of the location

y - The y coordinate of the location

setSize

public void setSize(int w,
                    int h)

Change the size of the texture to the new size. The new size will be in pixels and must be valid >= 0.

Specified by:

setSize in interface Overlay

Parameters:

w - The new width of the overlay

h - The new height of the overlay

setInsets

public void setInsets(java.awt.Insets insets)

Set the insets for this overlay. Note that this will not force a dirty condition. A derived class will need to override the other setInsets() method (this one calls it directly) and make any size recalculations and dirty bit handling if this is needed.

Parameters:

insets - The new set of values to use for insets

setInsets

public void setInsets(int left,
                      int top,
                      int right,
                      int bottom)

Set the insets for this overlay. Note that this will not force a dirty condition. A derived class will need to override this method and make any size recalculations and dirty bit handling if this is needed.

getRoot

public javax.media.j3d.BranchGroup getRoot()

Return the root of the overlay and its sub-overlays so it can be added to the scene graph. This should be added to the view transform group of the parent application.

Specified by:

getRoot in interface Overlay

Returns:

The J3D branch group that holds the overlay

setAntialiased

public void setAntialiased(boolean antialiased)

Sets whether drawing onto this Overlay is anialiased.

Specified by:

setAntialiased in interface Overlay

Parameters:

antialiased - The new setting for anti-aliasing.

isAntialiased

public boolean isAntialiased()

Check to see whether this overlay is currently antialiased.

Specified by:

isAntialiased in interface Overlay

Returns:

true if this overlay is antialiased

setVisible

public void setVisible(boolean visible)

Changes the visibility of the overlay.

Specified by:

setVisible in interface Overlay

Parameters:

visible - The new visibility state

isVisible

public boolean isVisible()

Returns the visiblity of the Overlay.

Specified by:

isVisible in interface Overlay

Returns:

true if the overlay is currently visible

setBackgroundMode

public void setBackgroundMode(int mode)

Sets the background mode. BACKGROUND_COPY will copy the raster data from the background into the canvas before paint()is called. BACKGROUND_NONE will cause the background to be disabled and not used.

Parameters:

mode - The new mode to use for the background

getUpdateManager

public UpdateManager getUpdateManager()

Returns the UpdateManager responsible for seeing that updates to the Overlay only take place between frames.

Specified by:

getUpdateManager in interface Overlay

setUpdateManager

public void setUpdateManager(UpdateManager mgr)

Set the UpdateManager to the new value. If the reference is null, it will clear the current manager.

Specified by:

setUpdateManager in interface Overlay

Parameters:

mgr - A reference to the new manage instance to use

update

public void update()

Notification from the update manager that something has changed and we should fix up the appropriate bits.

Specified by:

update in interface UpdatableEntity

getBounds

public java.awt.Rectangle getBounds()

Get the bounds of the visible object in screen space coordinates.

Specified by:

getBounds in interface Overlay

Returns:

A rectangle representing the bounds in screen coordinates

contains

public boolean contains(java.awt.Point p)

Check to see if the point passed in is contained within the bounds of the overlay.

Specified by:

contains in interface Overlay

Parameters:

p - The point to check if it is contained

Returns:

true if the point is contained within the bounds of this overlay

componentResized

public void componentResized(java.awt.event.ComponentEvent e)

Notification that the component has been resized.

Specified by:

componentResized in interface java.awt.event.ComponentListener

Parameters:

e - The event that caused this method to be called

componentMoved

public void componentMoved(java.awt.event.ComponentEvent e)

Notification that the component has been moved.

Specified by:

componentMoved in interface java.awt.event.ComponentListener

Parameters:

e - The event that caused this method to be called

componentShown

public void componentShown(java.awt.event.ComponentEvent e)

Notification that the component has been shown. This is the component being shown, not the window that it is contained in.

Specified by:

componentShown in interface java.awt.event.ComponentListener

Parameters:

e - The event that caused this method to be called

componentHidden

public void componentHidden(java.awt.event.ComponentEvent e)

Notification that the component has been hidden.

Specified by:

componentHidden in interface java.awt.event.ComponentListener

Parameters:

e - The event that caused this method to be called

setBackgroundColor

public void setBackgroundColor(java.awt.Color color)

Sets the background to a solid color. If a background image already exists then it will be overwritten with this solid color. It is completely appropriate to have an alpha component in the color if this is a alpha capable overlay. In general you should only use background images if this is an overlay that is called frequently, since you could always paint it inside the paint()method. BackgroundMode must be in BACKGROUND_COPY for the background to be shown.

Parameters:

color - The new color to use

getBackgroundImage

public java.awt.image.BufferedImage getBackgroundImage()

Returns the background for the overlay. Updates to this image will not be shown in the overlay until repaint()is called. BackgroundMode must be in BACKGROUND_COPY for the background to be shown.

Returns:

The image used as the background

setBackgroundImage

public void setBackgroundImage(java.awt.image.BufferedImage img)

Sets the background image to the one specified. It does not have to be the same size as the overlay but the it should be at least as big. BackgroundMode must be in BACKGROUND_COPY for the background to be shown.

dirty

protected void dirty(int property)

Mark a specific property as being dirty and needing to be rechecked.

Parameters:

property - The index of the property to be updated

setActiveBuffer

protected void setActiveBuffer(int bufferIndex)

Set the active buffer to the new index.

Parameters:

bufferIndex - The index of the buffer to use

getGraphics

protected java.awt.Graphics2D getGraphics()

Prepares the canvas to be painted. This should only be called internally or from an owner like the ScrollingOverlay class. paint(Graphics2D g) should be used to paint the OverlayBase.

Returns:

The current graphics context to work with

paint

public void paint(java.awt.Graphics2D g)

This is where the actualy drawing of the window takes place. Override this to alter the contents of what is shown in the window.

Parameters:

g - The graphics context to paint with

repaint

public void repaint()

This is called to trigger a repaint of the overlay. This will return once the back buffer has been built, but before the swap.

updateBuffer

protected void updateBuffer(java.awt.image.BufferedImage image,
                            int bufferIndex)

Force an update of the nominated buffer with the contents of the given image.

Parameters:

image - The contents to display as the image

bufferIndex - The buffer to update