## org.j3d.geom.overlay
Class OverlayBase

public abstract class OverlayBase
implements org.j3d.geom.overlay.Overlay, org.j3d.geom.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.14 $
Author:
  David Yazel, Justin Couch

Field Detail

### CONSOLE_Z

    private static final double CONSOLE_Z

  I do not undersand what this is for

### DIRTY_VISIBLE

    protected static final int DIRTY_VISIBLE

  Mark the visible flag as dirty

### DIRTY_POSITION

    protected static final int DIRTY_POSITION

  Mark the position as dirty and needing correction

### DIRTY_ACTIVE_BUFFER

    protected static final int DIRTY_ACTIVE_BUFFER

  Mark the active buffer as dirty and needing swapping

### DIRTY_SIZE

    protected static final int DIRTY_SIZE

  Mark the size as dirty and needing correction

### backgroundMode

    protected int backgroundMode

  The current background mode. Defaults to copy

### backgroundImage

    private java.awt.image.BufferedImage backgroundImage

  The image that sits in the background of the overlay

### hasAlpha

    private boolean hasAlpha

  Flag indicating the image(s) have an alpha component to them

### visible

    private boolean visible

  Flag holding current visibility state

### antialiased

    private boolean antialiased

  Flag to say if the drawing should be anti-aliased

### numBuffers

    private int numBuffers

  The number of fore/back buffers in use

### minDivSize

    private final int minDivSize

  The smallest number of pixels per sub-overlay size

### 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

### updateManager

    private org.j3d.geom.overlay.UpdateManager updateManager

  The update manager for keeping us in sync

### canvas3D

    private javax.media.j3d.Canvas3D canvas3D

  Canvas we are displayed on

### 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.geom.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

### dirtyCheck

    private boolean[] dirtyCheck

  List of the dirty flag settings

### fixedSize

    private 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.

### painting

    private boolean painting

  Used to avoid calls to repaint backing up

### initComplete

    private boolean initComplete

  Flag to say whether initialisation has been completed yet

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:
  `IllegalArgumentException` - Both the canvas and bounds are null

### OverlayBase

    protected OverlayBase(javax.media.j3d.Canvas3D canvas,
                          java.awt.Dimension size,
                          org.j3d.geom.overlay.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
  `updateManager` - Responsible for allowing the Overlay to update between renders. If this is null a default manager is created
Throws:
  `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 <
Throws:
  `IllegalArgumentException` - Both the canvas and bounds are null

### OverlayBase

    protected OverlayBase(javax.media.j3d.Canvas3D canvas,
                          java.awt.Dimension size,
                          boolean clipAlpha,
                          boolean blendAlpha,
                          org.j3d.geom.overlay.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 <
  `updateManager` - Responsible for allowing the Overlay to update between renders. If this is null a default manager is created
Throws:
  `IllegalArgumentException` - Both the canvas and bounds are null

### OverlayBase

    protected OverlayBase(javax.media.j3d.Canvas3D canvas,
                          java.awt.Dimension size,
                          boolean clipAlpha,
                          boolean blendAlpha,
                          org.j3d.geom.overlay.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 <
  `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
Throws:
  `IllegalArgumentException` - Both the canvas and bounds are null

Method Detail

### initialize

    public void initialize()

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

### 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

### 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

### 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.

Returns:
  The J3D branch group that holds the overlay

### setAntialiased

    public void setAntialiased(boolean antialiased)

  Sets whether drawing onto this Overlay is anialiased.

Parameters:
  `antialiased` - The new setting for anti-aliasing.

### isAntialiased

    public boolean isAntialiased()

  Check to see whether this overlay is currently antialiased.

Returns:
  true if this overlay is antialiased

### setVisible

    public void setVisible(boolean visible)

  Changes the visibility of the overlay.

Parameters:
  `visible` - The new visibility state

### isVisible

    public boolean isVisible()

  Returns the visiblity of the 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 org.j3d.geom.overlay.UpdateManager getUpdateManager()

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

Parameters:
  `The` - update manage instance for this overlay

### setUpdateManager

    public void setUpdateManager(org.j3d.geom.overlay.UpdateManager mgr)

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

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.

### getBounds

    public java.awt.Rectangle getBounds()

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

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.

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.

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.

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.

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.

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

### updateBackgroundColor

    private void updateBackgroundColor()

  Update the background colour on the drawn image now.

### syncVisible

    private void syncVisible()

  Update the visibility state to either turn on or off the overlay.

### syncActiveBuffer

    private void syncActiveBuffer()

  Update the active buffer to be the new index. Means that someone has requested an update and this is making it happen.

### syncPosition

    private void syncPosition()

  Update the position of the overlay in the overall window. Note that it does not change the size of the overlay, just re-adjusts the transforms in the scene graph so that the overlay maintains the correct position relative the canvas.

### syncSize

    private void syncSize()

  Fixup the size of the overlay textures. Resizes and clears the texture to fit the new size. Current implementation is really dumb - just tosses everything and starts again. A more intelligent one would only replace the border parts.