org.xith3d.ui.swingui
Class UIOverlay

java.lang.Object
  org.xith3d.ui.swingui.UIOverlay

public class UIOverlay
extends java.lang.Object

An overlay is 3d geometry which is aligned with the image plate. This is designed to be as simple as possible for the developer to use. All that is needed is to extend this class and override the paint function to update the image which will be written displayed on the screen. As a note: Displaying large overlays can use a *huge* amount of texture memory. If you created a pane which was 1024x768 you would consume over 3 mb of texture memory. Another thing to realize is that textures have to be a power of two. Because of this an overlay which was 513 x 257 would normally have to be generated using 1024 x 512. Unlike most textures, overlays cannot tolerate stretching and interpolation because of the fuzzyness which would result. So what the Xith overlay system attempts to do is break the overlay up into small pieces so that extra texture memory is not wasted. You are given a canvas which represents the entire overlay. After you finish updating it, the image is ripped apart and written to the underlying textures. Each of these underlying textures are double-buffered, so that switching them to the Xith3d engine is quick and does not involve having to continuously allocate and free large BufferedImages. This means, of course, that for every overlay you use 3 times (width * height * 4bytes) of system memory. So a chatbox which was 512 x 200 would use 3 * ( 512 * 200 *4) bytes or 1.2 MB of system memory. 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.

Originally Coded by David Yazel on Oct 4, 2003 at 9:59:54 PM.

Field Summary

static int	BACKGROUND_COPY
static int	BACKGROUND_NONE
protected Group	consoleBG
protected static java.lang.Boolean	DEBUG
protected int	height
protected int	width

Constructor Summary

UIOverlay(int width, int height, boolean clipAlpha, boolean blendAlpha)

UIOverlay(int width, int height, boolean clipAlpha, boolean blendAlpha, boolean owned)

UIOverlay(int width, int height, boolean clipAlpha, boolean blendAlpha, boolean owned, float offset, boolean readDepthBuffer)
Constructs an overlay window.

Method Summary

protected void	attachNode(Node node) Allows an derived class to add a behavior or object to the same transform group that the sub-overlays use
java.awt.image.BufferedImage	getBackgroundImage()
boolean	getBlendAlpha()
boolean	getClipAlpha()
int	getImageType()
PolygonAttributes	getPolygonAttributes() Return the polygon attributes shared by all the sub-overlays
protected java.awt.Graphics2D	getPreppedCanvas() Prepares the canvas to be painted.
RenderingAttributes	getRenderingAttributes() Return the rendering attributes shared by all sub-overlays
Node	getRoot() Return the root of the overlay and its sub-overlays so it can be added to the scenegraph
void	getSize(java.awt.Dimension dim)
TextureAttributes	getTextureAttributes() Return the texture attributes shared by all the sub-overlays
TransparencyAttributes	getTransparencyAttributes() Return the transparency attributes
protected View	getView() Protected method to get the view which this overlay is matching
protected void	initialize() This should be overwritten if you want to add any additional objects or behaviors or initialization before the overlay goes live
boolean	isOpaque()
boolean	isOwned()
protected void	moveToBackbuffer() Move the contents of the drawing canvas into the various backbuffers.
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.
void	repaint(java.awt.image.BufferedImage image)
void	repaintChanged(java.awt.image.BufferedImage image, java.util.ArrayList<?> dirtyAreas) Moves the contents of the buffered image to the canvas and then updates the back buffers that have changed.
void	setBackgroundColor(java.awt.Color c) Sets the background to a solid color.
void	setBackgroundImage(java.awt.image.BufferedImage bi) Sets the background image to the one specified.
void	setBackgroundMode(int mode) Sets the background mode.
void	setPosition(int x, int y) This sets the position of the overlay in screen coordinates. 0,0 is the upper left of the screen
void	setVisible(boolean yes) Changes the visibility of the overlay.
void	update() This method is ONLY called from the behavior.

Methods inherited from class java.lang.Object

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

Field Detail

DEBUG

protected static final java.lang.Boolean DEBUG

BACKGROUND_NONE

public static final int BACKGROUND_NONE

See Also:

Constant Field Values

BACKGROUND_COPY

public static final int BACKGROUND_COPY

See Also:

Constant Field Values

width

protected int width

height

protected int height

consoleBG

protected Group consoleBG

Constructor Detail

UIOverlay

public UIOverlay(int width,
                 int height,
                 boolean clipAlpha,
                 boolean blendAlpha,
                 boolean owned,
                 float offset,
                 boolean readDepthBuffer)

Constructs an overlay window.

Parameters:

width - The width of the window in screen space

height - The height of the window in screen space

clipAlpha - Should we apply a polygon clip where alpha is zero

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

owned - If this overlay is "owned" then no behavior will be built to update it since it is assumed that the owner will handle the repaints. Also it will not be attached to the view transform since it is assumed the owner will do that.

UIOverlay

public UIOverlay(int width,
                 int height,
                 boolean clipAlpha,
                 boolean blendAlpha,
                 boolean owned)

UIOverlay

public UIOverlay(int width,
                 int height,
                 boolean clipAlpha,
                 boolean blendAlpha)

Method Detail

isOwned

public boolean isOwned()

isOpaque

public boolean isOpaque()

initialize

protected void initialize()

This should be overwritten if you want to add any additional objects or behaviors or initialization before the overlay goes live

setPosition

public void setPosition(int x,
                        int y)

This sets the position of the overlay in screen coordinates. 0,0 is the upper left of the screen

getRoot

public Node getRoot()

Return the root of the overlay and its sub-overlays so it can be added to the scenegraph

getClipAlpha

public boolean getClipAlpha()

Returns:

true if the overlay is clipping when alpha is zero

getBlendAlpha

public boolean getBlendAlpha()

Returns:

true if the overlay is blending alpha.

getImageType

public int getImageType()

Returns:

the image type used for the buffered image

getRenderingAttributes

public RenderingAttributes getRenderingAttributes()

Return the rendering attributes shared by all sub-overlays

getPolygonAttributes

public PolygonAttributes getPolygonAttributes()

Return the polygon attributes shared by all the sub-overlays

getTextureAttributes

public TextureAttributes getTextureAttributes()

Return the texture attributes shared by all the sub-overlays

getTransparencyAttributes

public TransparencyAttributes getTransparencyAttributes()

Return the transparency attributes

moveToBackbuffer

protected void moveToBackbuffer()

Move the contents of the drawing canvas into the various backbuffers.

getPreppedCanvas

protected java.awt.Graphics2D getPreppedCanvas()

Prepares the canvas to be painted. This should only be called internally or from an owner like the ScrollingOverlay class

repaintChanged

public void repaintChanged(java.awt.image.BufferedImage image,
                           java.util.ArrayList<?> dirtyAreas)

Moves the contents of the buffered image to the canvas and then updates the back buffers that have changed.

Parameters:

image -

dirtyAreas -

repaint

public void repaint(java.awt.image.BufferedImage image)

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.

getSize

public void getSize(java.awt.Dimension dim)

update

public void update()

This method is ONLY called from the behavior. This checks to see if it needs to swap the buffers. If so, it locks the mutex and swaps all the sub-overlay buffers at once. If this isn't called from a behavior then the sub-buffer swaps might happen in seperate frames.

setVisible

public void setVisible(boolean yes)

Changes the visibility of the overlay.

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 show in the window.

getView

protected View getView()

Protected method to get the view which this overlay is matching

attachNode

protected void attachNode(Node node)

Allows an derived class to add a behavior or object to the same transform group that the sub-overlays use

getBackgroundImage

public java.awt.image.BufferedImage getBackgroundImage()

Returns:

a BufferedImage appropriate for using as a background. It will be the same size as the overlay with an appropriate format. If one has already been assigned to this overlay then that is what will be returned, otherwise one is built and returned. If a new one is built it is NOT assigned as a background image. To do that call setBackgroundImage()

setBackgroundColor

public void setBackgroundColor(java.awt.Color c)

Sets the background to a solid color. This will be set before every call to paint() to set the drawing surface. This actually builds a background image matching the size and format of the overlay and then initializes it to the color. If a background image already exists then it will be initialized to to the 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 your paint() method. This is also designed to support the same background image used for multiple overlays, like in a scrolling overlay.

setBackgroundImage

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

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 big enough is the backgroundMode is BACKGROUND_COPY, since that is a straight raster copy. Setting this to null will remove the background image.

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.