com.xith.java3d.overlay
Class OverlayScroller

java.lang.Object
  |
  +--com.xith.java3d.overlay.OverlayScroller

All Implemented Interfaces:

Overlay, UpdatableEntity, UpdateManager

public class OverlayScroller

extends java.lang.Object

implements Overlay, UpdateManager

A scrolling overlay is built on top of the overlay system. It maintains optional overlays for the borders of the overlay area and an array of equal size overlays to represent the lines. This is designed to be fast enough to support fast scrolling text and implementations like a chat box or debug window. A single scroll will effectively swap textures on geometry and stream one overlay's worth of data to the 3d card, so it should be maximally efficient. The design of this implementation is to keep an array of overlays one per virtual line from top to bottom inside the overlay. Because the position swaps (for scrolling) has to happen within a single behavior to guarentee its transactional status, a single repaint() of the OverlayScroller must set the re-order for the lines, even though the actual re-order won't happen until the behavior triggers (on next frame). We also have to handle the case where several repaints happen between one frame. In order to facilitate this, we keep an array of double-indirection, mapping overlay-lines to virtual lines, then unwind them when we commit the transaction to the card. So when we first start, or after a commit to the card, you would have a one-to-one mapping of virutal lines to overlays. If you issue a scroll-up or scroll-down directive, we just adjust the virtual pointers, mapping the first virtual line to the bottom overlay and adjusting from there. This means you can do multiple scrolls between frames and the buffer maintains consistancy. If you want a line repaint and a scroll action to be handled atomically, then you should call update() on the scroller. This will in-turn lock the overlay for update and call the paint() method, which you implement. This is a bit different than the paint method used at the overlay level since you are not given a graphics context. But from within this method you can call the scroll() and scrollDown() methods and request a graphics context for any virtual line. You will be writing to the backBuffer of the individual overlay's so it is safe, also none of the line-overlays will commit until you exit the paint() method. Copyright: Copyright (c) 2000,2001 Company: Teseract Software, LLP

Author:

David Yazel

Field Summary

static int	BORDER_BOTTOM
static int	BORDER_LEFT
static int	BORDER_RIGHT
static int	BORDER_TOP

Fields inherited from interface com.xith.java3d.overlay.Overlay

BACKGROUND_COPY, BACKGROUND_NONE, PLACE_BOTTOM, PLACE_CENTER, PLACE_LEFT, PLACE_RIGHT, PLACE_TOP, X_PLACEMENT, Y_PLACEMENT

Constructor Summary

OverlayScroller(javax.media.j3d.Canvas3D canvas3D, boolean clipAlpha, boolean blendAlpha, java.awt.Dimension offset, UpdateManager manager, Overlay[] line, java.awt.Insets margin)

OverlayScroller(javax.media.j3d.Canvas3D canvas3D, java.awt.Dimension offset, Overlay[] line, java.awt.Insets margin)

OverlayScroller(javax.media.j3d.Canvas3D canvas3D, java.awt.Dimension offset, UpdateManager manager, Overlay[] line, java.awt.Insets margin)

OverlayScroller(javax.media.j3d.Canvas3D canvas3D, Overlay[] line, java.awt.Insets margin)

OverlayScroller(javax.media.j3d.Canvas3D canvas3D, UpdateManager manager, Overlay[] line, java.awt.Insets margin)

Method Summary

void	addScrollEventListener(ScrollEventListener listener)
void	clean(int property)
void	dirty(int property)
void	fireItemScrolled(ScrollEvent e)
OverlayBase	getBorder(int index)
java.awt.Rectangle	getBounds() Returns the rectangular portion of the canvas that this overlay covers.
javax.media.j3d.Canvas3D	getCanvas() Returns the canvas being drawn on
Overlay	getLine(int index)
int	getNumLines() Returns the number of lines
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() Implement this to do extra initialization before the node goes live
boolean	isAntialiased() Returns whether drawing on this overlay is anti-aliased
boolean	isUpdating()
boolean	isVisible() Returns the visiblity of the Overlay.
void	removeScrollEventListener(ScrollEventListener listener)
void	scroll(int startLine, int scrollDistance) This will scroll lines starting at startLine the scrollDistance.
void	setAntialiased(boolean antialiased) Sets whether drawing onto this Overlay is anialiased.
void	setOffset(java.awt.Dimension offset) Sets the position of the window.
void	setOffset(int width, int height) Sets the position of the window.
void	setRelativePosition(int[] relativePositon) Sets the relative position of the overlay on the screen using a 2 dimensional array.
void	setRelativePosition(int xType, int yType) This will set the relative position of the scroller elements.
void	setUpdateManager(UpdateManager updateManager) Sets the UpdateManager
void	setUpdating(boolean updating)
void	setVisible(boolean visible) Sets the visibility of the overlay.
void	update() This will commit any changes that have been made in the overlay.
void	updateRequested()

Methods inherited from class java.lang.Object

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

Field Detail

BORDER_LEFT

public static final int BORDER_LEFT

BORDER_RIGHT

public static final int BORDER_RIGHT

BORDER_TOP

public static final int BORDER_TOP

BORDER_BOTTOM

public static final int BORDER_BOTTOM

Constructor Detail

OverlayScroller

public OverlayScroller(javax.media.j3d.Canvas3D canvas3D,
                       Overlay[] line,
                       java.awt.Insets margin)

OverlayScroller

public OverlayScroller(javax.media.j3d.Canvas3D canvas3D,
                       java.awt.Dimension offset,
                       Overlay[] line,
                       java.awt.Insets margin)

OverlayScroller

public OverlayScroller(javax.media.j3d.Canvas3D canvas3D,
                       UpdateManager manager,
                       Overlay[] line,
                       java.awt.Insets margin)

OverlayScroller

public OverlayScroller(javax.media.j3d.Canvas3D canvas3D,
                       java.awt.Dimension offset,
                       UpdateManager manager,
                       Overlay[] line,
                       java.awt.Insets margin)

OverlayScroller

public OverlayScroller(javax.media.j3d.Canvas3D canvas3D,
                       boolean clipAlpha,
                       boolean blendAlpha,
                       java.awt.Dimension offset,
                       UpdateManager manager,
                       Overlay[] line,
                       java.awt.Insets margin)

Method Detail

initialize

public void initialize()

Implement this to do extra initialization before the node goes live

getBounds

public java.awt.Rectangle getBounds()

Description copied from interface: Overlay

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

Specified by:

getBounds in interface Overlay

getCanvas

public javax.media.j3d.Canvas3D getCanvas()

Description copied from interface: Overlay

Returns the canvas being drawn on

Specified by:

getCanvas in interface Overlay

getRoot

public javax.media.j3d.BranchGroup getRoot()

Description copied from interface: Overlay

Return the root of the Overlay so it can be added to the scene graph.

Specified by:

getRoot in interface Overlay

getBorder

public OverlayBase getBorder(int index)

setAntialiased

public void setAntialiased(boolean antialiased)

Description copied from interface: Overlay

Sets whether drawing onto this Overlay is anialiased.

Specified by:

setAntialiased in interface Overlay

isAntialiased

public boolean isAntialiased()

Description copied from interface: Overlay

Returns whether drawing on this overlay is anti-aliased

Specified by:

isAntialiased in interface Overlay

getUpdateManager

public UpdateManager getUpdateManager()

Description copied from interface: Overlay

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 updateManager)

Description copied from interface: Overlay

Sets the UpdateManager

Specified by:

setUpdateManager in interface Overlay

isUpdating

public boolean isUpdating()

Specified by:

isUpdating in interface UpdateManager

setUpdating

public void setUpdating(boolean updating)

Specified by:

setUpdating in interface UpdateManager

getNumLines

public int getNumLines()

Returns the number of lines

getLine

public Overlay getLine(int index)

setVisible

public void setVisible(boolean visible)

Sets the visibility of the overlay. This will be updated in the next frame TODO: Make thread safe

Specified by:

setVisible in interface Overlay

isVisible

public boolean isVisible()

Description copied from interface: Overlay

Returns the visiblity of the Overlay.

Specified by:

isVisible in interface Overlay

scroll

public void scroll(int startLine,
                   int scrollDistance)

This will scroll lines starting at startLine the scrollDistance. If the scroll distance is positive then items will be pushed off the top if it is negative then they will be pushed off the bottom. To scroll all the lines up one do scroll(0, 1); To scroll all the lines down two do scroll(getNumLines() - 1, -2); This will be updated in the next frame

setRelativePosition

public void setRelativePosition(int[] relativePositon)

Sets the relative position of the overlay on the screen using a 2 dimensional array.

Specified by:

setRelativePosition in interface Overlay

Parameters:

relativePosition[X_PLACEMENT] - May be PLACE_LEFT, PLACE_RIGHT, or PLACE_CENTER

relativePosition[Y_PLACEMENT] - May be PLACE_TOP, PLACE_BOTTOM, or PLACE_CENTER

setRelativePosition

public void setRelativePosition(int xType,
                                int yType)

This will set the relative position of the scroller elements. TODO: Make it work! It needs to change the offsets of the subelements otherwise they flip over when put on the bottom and mess up completely in the center.

Specified by:

setRelativePosition in interface Overlay

Following copied from interface: com.xith.java3d.overlay.Overlay

Parameters:

xType - May be PLACE_LEFT, PLACE_RIGHT, or PLACE_CENTER

yType - May be PLACE_TOP, PLACE_BOTTOM, or PLACE_CENTER

setOffset

public void setOffset(java.awt.Dimension offset)

Sets the position of the window. This will be updated in the next frame

Specified by:

setOffset in interface Overlay

setOffset

public void setOffset(int width,
                      int height)

Sets the position of the window. This will be updated in the next frame

Specified by:

setOffset in interface Overlay

dirty

public void dirty(int property)

clean

public void clean(int property)

updateRequested

public void updateRequested()

Specified by:

updateRequested in interface UpdateManager

update

public void update()

This will commit any changes that have been made in the overlay. Calling this from within a behavior guarantees that all changes will happen in one frame.

Specified by:

update in interface Overlay

addScrollEventListener

public void addScrollEventListener(ScrollEventListener listener)

removeScrollEventListener

public void removeScrollEventListener(ScrollEventListener listener)

fireItemScrolled

public void fireItemScrolled(ScrollEvent e)