gamingtools
Class FrameBuilder

java.lang.Object
  |
  +--gamingtools.FrameBuilder

All Implemented Interfaces:

RenderListener

public abstract class FrameBuilder

extends Object

implements RenderListener

A class that desires to generate animation frames extends this class. The abstract methods are invoked in the following order:

1. init() -- Called once prior to frame generation on a different thread than the one for the animation loop. It is used to load images and sounds, and for configuration.
2. updateState() -- Used to update the state of the game. It will occasionally be invoked more often than the render methods to maintain the apparent frame rate.
3. isBackgroundSame() -- Returns true when the background has not changed. It is used to determine which renderBackground() method to call.
4. renderBackground() -- Two overloads, the first draws the complete background, the second a sub-region of it. If the background has not changed and the contents of the buffers have not been lost, then the latter overload is used repeatedly to restore the dirty regions created by sprite drawing. Otherwise, the former version is used.
5. renderForeground() -- Draws the sprites and other foreground graphics. It should use drawSprite() and markDirtyRegion() appropriately.

Avoid creating temporary objects in these methods because the incremental garbage collection that occurs to clean up those objects will introduce noticeable pauses.

See Also:

GraphicsSource

Nested Class Summary

protected class	FrameBuilder.FrameInfo Description of an animation frame.
protected class	FrameBuilder.Region Rectangular dirty region.

Field Summary

protected int	backgroundNumber Index that is incremented only if the background changes.
protected int	bufferHeight Height of the buffers.
protected int	bufferWidth Width of the buffers.
static int	DEFAULT_MAX_DIRTY_REGIONS Default maximum dirty regions stored in the history per buffer.
protected FrameBuilder.FrameInfo[]	frameInfoHistory Stored frame descriptions.
protected int	historyIndex Alternates between 0 and 1, or remains at 0.
protected int	historySize Equal to the number of buffers.
int	MAX_DIRTY_REGIONS Maximum number of dirty regions stored in the history per buffer.
protected FrameBuilder.Region[][]	regionHistory Stored dirty regions: [history index][region index]

Constructor Summary

FrameBuilder()
Constructs this class with a dirty region history size equal to 64.

FrameBuilder(int maxDirtyRegions)
Constructs this class with dirty region history size equal to the specified value.

Method Summary

void	drawSprite(Graphics g, Image image, int x, int y) Draws an image at the specified coordinates and marks the region it occupies as dirty.
abstract void	init() This method is used to load images and sounds, and for configuration.
void	init(boolean isPageFlipping, int bufferWidth, int bufferHeight) This method is automatically invoked by GraphicsSource.
abstract boolean	isBackgroundSame() Returns true if and only if the background has not changed.
void	markDirtyRegion(int x, int y, int width, int height) Records a dirty region.
void	render(Graphics g, boolean isBufferCleared, int bufferIndex) This method is automatically invoked by GraphicsSource.
abstract void	renderBackground(Graphics g) Draws the complete background.
abstract void	renderBackground(Graphics g, int x, int y, int width, int height) Draws a rectangular sub-region of the background.
abstract void	renderForeground(Graphics g) Draws the sprites and other foreground graphics.
void	updateModel() This method is automatically invoked by GraphicsSource.
abstract void	updateState() This method is used to update the state of the game.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MAX_DIRTY_REGIONS

public static final int DEFAULT_MAX_DIRTY_REGIONS

Default maximum dirty regions stored in the history per buffer.

See Also:

Constant Field Values

MAX_DIRTY_REGIONS

public final int MAX_DIRTY_REGIONS

Maximum number of dirty regions stored in the history per buffer.

historySize

protected int historySize

Equal to the number of buffers.

regionHistory

protected FrameBuilder.Region[][] regionHistory

Stored dirty regions: [history index][region index]

frameInfoHistory

protected FrameBuilder.FrameInfo[] frameInfoHistory

Stored frame descriptions.

historyIndex

protected int historyIndex

Alternates between 0 and 1, or remains at 0.

backgroundNumber

protected int backgroundNumber

Index that is incremented only if the background changes.

bufferWidth

protected int bufferWidth

Width of the buffers.

bufferHeight

protected int bufferHeight

Height of the buffers.

Constructor Detail

FrameBuilder

public FrameBuilder(int maxDirtyRegions)

Constructs this class with dirty region history size equal to the specified value.

Parameters:

maxDirtyRegions - Maximum number of dirty regions that can be recorded for each buffer.

FrameBuilder

public FrameBuilder()

Constructs this class with a dirty region history size equal to 64. If more than 64 dirty regions are required, use the alternate constructor.

Method Detail

init

public final void init(boolean isPageFlipping,
                       int bufferWidth,
                       int bufferHeight)

This method is automatically invoked by GraphicsSource. Do not call it directly.

This method initializes the dirty region history and delegates the call to the abstract method init().

Specified by:

init in interface RenderListener

Parameters:

isPageFlipping - Indicates whether the BufferStrategy within GraphicsSource employs page flipping. If true, then even frames and odd frames are drawn to different offscreen buffers. Otherwise, all frames are drawn to the same buffer. This parameter determines how the buffer must be updated to generate the next frame.

bufferWidth - The width of the buffers.

bufferHeight - The height of the bufrers.

See Also:

init()

updateModel

public final void updateModel()

This method is automatically invoked by GraphicsSource. Do not call it directly.

This method invokes the abstract method updateState() followed by the abstract method isBackgroundSame().

Specified by:

updateModel in interface RenderListener

See Also:

updateState(), isBackgroundSame()

render

public final void render(Graphics g,
                         boolean isBufferCleared,
                         int bufferIndex)

This method is automatically invoked by GraphicsSource. Do not call it directly.

This method invokes one of the abstract renderBackground() methods followed by the abstract renderForeground() method.

Specified by:

render in interface RenderListener

Parameters:

g - The graphics context used to draw the animation frame. Disposal of this graphics context is automatically performed by GraphicsSource.

isBufferCleared - Indicates whether the buffer is in the same state since the last time it was drawn to. Occationally, the buffer may be losted and restored. When this happens, it is effectively erased. If this parameter is true, then the entire buffer needs to be painted. Otherwise, only the portion of the buffer that changes for this frame needs to be updated. Note, after calling GraphicsSource.setRenderListener(), this parameter will be true for the first frame or two depending upon which buffer strategy is employed.

bufferIndex - If page flipping is used, then this parameter will alternate between 0 and 1. Otherwise, it will always be 0.

See Also:

renderBackground(Graphics), renderBackground(Graphics,int,int,int,int), renderForeground(Graphics)

drawSprite

public void drawSprite(Graphics g,
                       Image image,
                       int x,
                       int y)

Draws an image at the specified coordinates and marks the region it occupies as dirty.

Parameters:

g - A graphics context to the back buffer.

image - Sprite to draw.

x - Horizontal position of the upper-left corner.

y - Vertical position of the upper-left corner.

See Also:

markDirtyRegion(int,int,int,int)

markDirtyRegion

public void markDirtyRegion(int x,
                            int y,
                            int width,
                            int height)

Records a dirty region. The region will be restored in a successive frame by invoking the sub-region form of drawBackground().

Parameters:

x - Horizontal position of the upper-left corner.

y - Vertical position of the upper-left corner.

width - Width of the region.

height - Height of the region.

See Also:

drawSprite(Graphics,Image,int,int)

init

public abstract void init()

This method is used to load images and sounds, and for configuration. It is invoked prior to frame generation on a different thread than the one for the animation loop.

updateState

public abstract void updateState()

This method is used to update the state of the game. To sustain the apparent frame rate, this method will occasionally be invoked more often than the render methods.

isBackgroundSame

public abstract boolean isBackgroundSame()

Returns true if and only if the background has not changed. It is used to determine which renderBackground() method to call. This method is invoked as often as updateState(), which is typically more often than the render methods because of frame skipping.

Returns:

true when the background has not changed; false otherwise.

renderBackground

public abstract void renderBackground(Graphics g)

Draws the complete background. Do not invoke g.dispose() since GraphicsSource already takes care of that.

Parameters:

g - A graphics context to the back buffer.

renderBackground

public abstract void renderBackground(Graphics g,
                                      int x,
                                      int y,
                                      int width,
                                      int height)

Draws a rectangular sub-region of the background. This method is intended to restore a dirty region of the background created when a sprite or other foreground graphic was drawn to this buffer in a previous frame. Do not invoke g.dispose() since GraphicsSource already takes care of that. g has a clipping region set to the dirty region.

Parameters:

g - A graphics context to the back buffer.

x - Horizontal position of the upper-left corner.

y - Vertical position of the upper-left corner.

width - Width of the region.

height - Heigh of the region.

renderForeground

public abstract void renderForeground(Graphics g)

Draws the sprites and other foreground graphics. It should use markDirtyRegion(), which records a dirty region for restoration in a successive frame, and drawSprite(), which is a convenience method that invokes g.drawImage() followed by markDirtyRegion().

Parameters:

g - A graphics context to the back buffer.