org.j3d.renderer.java3d.overlay
Interface Overlay

All Superinterfaces:

UpdatableEntity

All Known Subinterfaces:

InteractiveOverlay

All Known Implementing Classes:

InteractiveOverlayBase, InteractiveTextureOverlay, OverlayBase, TextureOverlay

public interface Overlay

extends UpdatableEntity

An overlay is rectangular texture which is aligned with the image plate giving the illusion of an image drawn onto the canvas rather than in the scene.

In an accelerated environment the scene is drawn on the card and goes directly from there onto the screen. In order to draw directly over the scene it must be rendered, then transfered to the system memory, drawn on, then tranfered back. Each of these transfers take place on the bus between the card and the system which is already busy with the normal operations of displaying everything not 3d on the screen. Using a texture that is placed in front of the image plate is a much cheaper operation. It just requires transering the data to the card once (as oppoased to the whole scene back and forth across the bus for each frame.) Also OverlayBase which is the default implementation of this interface is double buffered so the transfer takes place in the background and once the entire texture make it onto the card it is made active.

Creating a new Overlay is very simple. Simply override paint(Graphics2D g) in OverlayBase. If you have an overlay that is changing with time calling repaint() will update it.

As a note: Displaying large overlays use a *huge* amount of texture memory. Every pixel in the overlay is represented by a set of integers (3 or 4 depending on if the overlay has a transparency value (RGB vs RGBA.) For a 512x128 alpha capable overlay that is (4 * 512 * 128) / 1024 = 256Kb of memory. Each texture has 3 buffers though, one in system memory and two on the card so the actual memory used is 256Kb * 3 = 768Kb. A 512x512 overlay would take 3072Kb or 3Mb.

Another thing to realize is that textures have to have dimesions that are powers of two for optimization purposes. This means a 513x257 texture would require 1024x512 of bounds to be allocated. Unlike most textures, overlays cannot tolerate stretching and interpolation because of the fuzzyness that results. The overlay system breaks the requested overlaysize up into smaller pieces so that extra texture memory is not wasted. This is hidden from the user who simply sees a graphics context for the entire overlay. When the entire buffer has been drawn though it is divided appropriately onto the SubOverlay's which are positioned so as to look like one solid rectangle.

Updates to the actual textures are done within a behavior within a frame. This is very fast because all that is happening is that the buffers are getting swapped. We have to be certain that we are not in the process of copying the big buffer into the back buffer at the same time the behavior attempts to do a buffer swap. This is handled by the overlay by not updating texture if we are in the middle of drawing a new one. The drawback to this is that numerous updates per second to the overlay could result in several updates not get immediately reflected. But since the area is always completely redrawn this should not prove to be an issue. Soon as we hit a frame where we are not updating the buffer then it will be swapped.

Remember, all you have to do to make translucent or non-square overlays is to use the alpha channel.

Version:

$Revision: 1.1 $

Author:

David Yazel, Will Holcomb

Field Summary

static int	BACKGROUND_COPY This mode copies the background image to the canvas before it is drawn
static int	BACKGROUND_NONE This mode prevents the background from being drawn

Method Summary

boolean	contains(java.awt.Point p) Check to see if the point passed in is contained within the bounds of the overlay.
java.awt.Rectangle	getBounds() Returns the rectangular portion of the canvas that this overlay covers.
javax.media.j3d.BranchGroup	getRoot() Return the root of the Overlay 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() Post construction initialisation before turning the overlay live.
boolean	isAntialiased() Returns whether drawing on this overlay is anti-aliased.
boolean	isVisible() Returns the visiblity of the Overlay.
void	setAntialiased(boolean isAntialiased) Sets whether drawing onto this Overlay is anialiased.
void	setComponentDetails(java.awt.Dimension size, double fov) Update the canvas component details of size and field of view settings.
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 updateManager) Set the UpdateManager to the new value.
void	setVisible(boolean visible) Changes the visibility of the Overlay.

Methods inherited from interface org.j3d.renderer.java3d.overlay.UpdatableEntity

update

Field Detail

BACKGROUND_NONE

public static final int BACKGROUND_NONE

This mode prevents the background from being drawn

See Also:

Constant Field Values

BACKGROUND_COPY

public static final int BACKGROUND_COPY

This mode copies the background image to the canvas before it is drawn

See Also:

Constant Field Values

Method Detail

initialize

public void initialize()

Post construction initialisation before turning the overlay live. Should always be called by the end user before starting to make use of this overlay instance.

getRoot

public javax.media.j3d.BranchGroup getRoot()

Return the root of the Overlay so it can be added to the scene graph. This should be added to the view transform group of the parent application. A branch group representing the overlay

getBounds

public java.awt.Rectangle getBounds()

Returns the rectangular portion of the canvas that this overlay covers.

Returns:

A rectangle representing the bounds

contains

public boolean contains(java.awt.Point p)

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

Parameters:

p - The point to check if it is contained

Returns:

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

getUpdateManager

public UpdateManager getUpdateManager()

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

setUpdateManager

public void setUpdateManager(UpdateManager updateManager)

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

Parameters:

updateManager - A reference to the new manage instance to use

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.

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.

Parameters:

w - The new width of the overlay

h - The new height of the overlay

setAntialiased

public void setAntialiased(boolean isAntialiased)

Sets whether drawing onto this Overlay is anialiased. If called after the overlay has gone live, it will have no effect.

Parameters:

isAntialiased - true if this overlay should antialias the lines

isAntialiased

public boolean isAntialiased()

Returns whether drawing on this overlay is anti-aliased.

Returns:

true if the overlay is antialiased

setVisible

public void setVisible(boolean visible)

Changes the visibility of the Overlay.

Parameters:

visible - true to make the overlay visible

isVisible

public boolean isVisible()

Returns the visiblity of the Overlay.

Returns:

true if the overlay is currently visible

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.

Parameters:

size - The new dimensions of the component

fov - The new field of view for the current view