ch.aplu.jgamegrid
Class GGBackground

java.lang.Object
  extended by ch.aplu.jgamegrid.GGBackground
Direct Known Subclasses:
GGPanel

public class GGBackground
extends java.lang.Object

Class for drawing into the GameGrid background using Java Graphics2D methods. The size of the drawing area is determined by the number and size of the cells when constructing the GameGrid: In pixel units, e.g. distance between adjacent pixel, the width of the background is nbHorzCells * cellSize horizontally and the height is nbVertCells * cellSize vertically. Thus the background contains width + 1 pixels horizontally and height + 1 pixels vertically, and the pixel coordinates are 0 <= i <= width (inclusive), 0 <= k <= height (inclusive) respectively.
Example: Constructing new GameGrid(600, 400, 1) will give a background with 601x401 pixels. x-pixel coordinates are in the range 0 <= x <= 600, y-pixel coordinates in the range 0 <=y <= 400. The center is exactly at coordinate (300, 200).

Defaults:
- paint color: white
- line width: 1 pixel
- background color: black
- font: SansSerif, Font.PLAIN, 24 pixel

GGBackground uses an won offscreen buffer that may contain a background image, the grid lines and any background graphics. The current content of the buffer may be saved and restored in an extra buffer using save() and restore().

All drawing methods draw into the buffer that is automatically rendered to the screen in every simulation cycle when the actor's act() methods are called. If act() is not active, an explicit call to GameGrid.refresh() may be necessary to render the buffer. Because actor sprite images are drawn in the foreground, use text as sprite image to display it in the foreground.


Method Summary
 void clear()
          Clears the background buffer by painting it with the current background color.
 void clear(java.awt.Color color)
          Clears the background buffer by painting it with the given background color.
 void drawArc(java.awt.Point pt, int radius, double startAngle, double extentAngle)
          Draws an arc with given center, radius, start angle and angle extent.
 void drawCircle(java.awt.Point center, int radius)
          Draws a circle with given center and given radius.
 void drawGeneralPath(java.awt.geom.GeneralPath gp)
          Draws a figure defined by the given GeneralPath.
 void drawGridLines(java.awt.Color color)
          Draws the grid lines using the given color.
 void drawImage(java.awt.image.BufferedImage bi)
          Draws the given image at position (0, 0) into the background buffer.
 void drawImage(java.awt.image.BufferedImage bi, int x, int y)
          Draws the given image into the background buffer.
 void drawImage(java.lang.String imagePath, int x, int y)
          Retrieves the image either from the jar resource, from local drive or from a internet server and draws it into the background buffer.
 void drawLine(int x1, int y1, int x2, int y2)
          Draws a line from one coordinate pair to another coordinate pair.
 void drawLine(java.awt.Point pt1, java.awt.Point pt2)
          Draws a line from one coordinate pair to another coordinate pair.
 void drawPoint(java.awt.Point pt)
          Draws a single point.
 void drawPolygon(java.awt.Point[] vertexes)
          Draws a polygon with given vertexes.
 void drawRectangle(java.awt.Point pt1, java.awt.Point pt2)
          Draws a rectangle with given opposite corners.
 void drawText(java.lang.String text, java.awt.Point pt)
          Displays the given text at the given position using the current font.
 void fillArc(java.awt.Point pt, int radius, double startAngle, double extentAngle)
          Fills an arc with given center, radius, start angle and angle extent.
 void fillCell(Location location, java.awt.Color fillColor)
          Fills a cell with given color.
 void fillCell(Location location, java.awt.Color fillColor, boolean boundary)
          Fills a cell with given color.
 void fillCircle(java.awt.Point center, int radius)
          Draws a filled circle with given center and given radius.
 void fillGeneralPath(java.awt.geom.GeneralPath gp)
          Fills a figure defined by the given GeneralPath.
 void fillPolygon(java.awt.Point[] vertexes)
          Draws a filled polygon with given vertexes.
 void fillRectangle(java.awt.Point pt1, java.awt.Point pt2)
          Draws a filled rectangle with given opposite corners.
static java.lang.String[] getAvailableFontFamilies()
          Returns the available font families for the current platform.
 java.awt.image.BufferedImage getBackgroundImage()
          Returns the BufferedImage of the current background.
 java.awt.Color getBgColor()
          Returns the current background color.
 java.awt.Color getColor(Location location)
          Returns the color of the pixel of the background at given cell's center.
 java.awt.Color getColor(java.awt.Point pt)
          Returns the color of the pixel of the background at given point.
 java.awt.Graphics2D getContext()
          Returns the graphics device context of the background.
 int getLineWidth()
          Returns the current line width in pixels.
 java.awt.Color getPaintColor()
          Returns the current paint color.
 void restore()
          Restores a previously saved background.
 void save()
          Saves the current background to an extra buffer.
 void setBgColor(java.awt.Color color)
          Sets the given new background color.
 void setFont(java.awt.Font font)
          Sets the current font for displaying text with drawText()
 void setLineWidth(int width)
          Sets the current line width in pixels.
 void setPaintColor(java.awt.Color color)
          Sets the given new paint color (for drawing and filling).
 void setPaintMode()
          Sets the paint mode of the graphics context to overwrite with current color.
 void setXORMode(java.awt.Color c)
          Sets the paint mode to alternate between the current color and the given color.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getBackgroundImage

public java.awt.image.BufferedImage getBackgroundImage()
Returns the BufferedImage of the current background. The size is nbHorzPix x nbVertPix.

Returns:
the background image

save

public void save()
Saves the current background to an extra buffer.


restore

public void restore()
Restores a previously saved background. Returns immediately if no save operation was done yet.


drawImage

public void drawImage(java.lang.String imagePath,
                      int x,
                      int y)
Retrieves the image either from the jar resource, from local drive or from a internet server and draws it into the background buffer. From the given filename the image file is searched in the following order:
- if application is packed into a jar archive, relative to the root of the jar archive
- relative to the directory <userhome>/gamegrid/
- relative or absolute to current application directory
- if filename starts with http://, from the given URL
- add prefix _ and search relative to the root of the jar archive

If the image cannot be loaded, nothing happens.

Parameters:
imagePath - the file name or url
x - x-coordinate of upper left corner
y - y-coordinate of upper left corner

drawImage

public void drawImage(java.awt.image.BufferedImage bi,
                      int x,
                      int y)
Draws the given image into the background buffer.

Parameters:
x - x-coordinate of upper left corner
y - y-coordinate of upper left corner

drawImage

public void drawImage(java.awt.image.BufferedImage bi)
Draws the given image at position (0, 0) into the background buffer.


clear

public void clear(java.awt.Color color)
Clears the background buffer by painting it with the given background color. If necessary, draws an available background image and the grid lines into the background buffer. The background color is set to the given color, but the paint color remains unchanged.

Parameters:
color - the color of the background, alpha channel ignored

clear

public void clear()
Clears the background buffer by painting it with the current background color. If necessary, draw an available background image and the grid lines into the background buffer. The paint color remains unchanged.


drawGridLines

public void drawGridLines(java.awt.Color color)
Draws the grid lines using the given color. The current paint color is unchanged.

Parameters:
color - the color of the grid lines

getLineWidth

public int getLineWidth()
Returns the current line width in pixels.

Returns:
the line width

setLineWidth

public void setLineWidth(int width)
Sets the current line width in pixels.

Parameters:
width - the new line width

getPaintColor

public java.awt.Color getPaintColor()
Returns the current paint color.

Returns:
the paint color

setPaintColor

public void setPaintColor(java.awt.Color color)
Sets the given new paint color (for drawing and filling).

Parameters:
color - the new line color

getBgColor

public java.awt.Color getBgColor()
Returns the current background color.

Returns:
the background color

setBgColor

public void setBgColor(java.awt.Color color)
Sets the given new background color. The background is redrawn by calling clear().

Parameters:
color - the new background color

drawLine

public void drawLine(int x1,
                     int y1,
                     int x2,
                     int y2)
Draws a line from one coordinate pair to another coordinate pair. The line width and color is determined by setLineWidth() and setPaintColor().

Parameters:
x1 - the x-coordinate of the start point
y1 - the y-coordinate of the start point
x2 - the x-coordinate of the endpoint
y2 - the y-coordinate of the endpoint

drawLine

public void drawLine(java.awt.Point pt1,
                     java.awt.Point pt2)
Draws a line from one coordinate pair to another coordinate pair. The line width and color is determined by setLineWidth() and setPaintColor().

Parameters:
pt1 - the start point
pt2 - the endpoint

drawCircle

public void drawCircle(java.awt.Point center,
                       int radius)
Draws a circle with given center and given radius.

Parameters:
radius - the radius of the circle

fillCircle

public void fillCircle(java.awt.Point center,
                       int radius)
Draws a filled circle with given center and given radius.

Parameters:
center - the center of the circle
radius - the radius of the circle

drawRectangle

public void drawRectangle(java.awt.Point pt1,
                          java.awt.Point pt2)
Draws a rectangle with given opposite corners.

Parameters:
pt1 - upper left vertex of the rectangle
pt2 - lower right vertex of the rectangle

fillRectangle

public void fillRectangle(java.awt.Point pt1,
                          java.awt.Point pt2)
Draws a filled rectangle with given opposite corners. (The filling includes the complete outline of the rectangle.)

Parameters:
pt1 - upper left vertex of the rectangle
pt2 - lower right vertex of the rectangle

drawArc

public void drawArc(java.awt.Point pt,
                    int radius,
                    double startAngle,
                    double extentAngle)
Draws an arc with given center, radius, start angle and angle extent.

Parameters:
pt - the center of the arc
radius - the radius of the arc
startAngle - the start angle in degrees (zero to east, positive counterclockwise)
extentAngle - the angle extent of the arc in degrees

fillArc

public void fillArc(java.awt.Point pt,
                    int radius,
                    double startAngle,
                    double extentAngle)
Fills an arc with given center, radius, start angle and angle extent.

Parameters:
pt - the center of the arc
radius - the radius of the arc
startAngle - the start angle in degrees (zero to east, positive counterclockwise)
extentAngle - the angle extent of the arc in degrees

drawPolygon

public void drawPolygon(java.awt.Point[] vertexes)
Draws a polygon with given vertexes.

Parameters:
vertexes - the vertexes of the polygon

fillPolygon

public void fillPolygon(java.awt.Point[] vertexes)
Draws a filled polygon with given vertexes.

Parameters:
vertexes - the vertexes of the polygon

drawGeneralPath

public void drawGeneralPath(java.awt.geom.GeneralPath gp)
Draws a figure defined by the given GeneralPath.

Parameters:
gp - the GeneralPath that defines the shape

fillGeneralPath

public void fillGeneralPath(java.awt.geom.GeneralPath gp)
Fills a figure defined by the given GeneralPath.

Parameters:
gp - the GeneralPath that defines the shape

drawPoint

public void drawPoint(java.awt.Point pt)
Draws a single point. If the lineWidth is greater than 1, more than one pixel may be involved.

Parameters:
pt - the point to draw

fillCell

public void fillCell(Location location,
                     java.awt.Color fillColor)
Fills a cell with given color. The boundary lines are considered to be part of the cell. The paint color remains unchanged.

Parameters:
location - the cell's location (cell indices).
fillColor - the filling color of the cell

fillCell

public void fillCell(Location location,
                     java.awt.Color fillColor,
                     boolean boundary)
Fills a cell with given color. The paint color remains unchanged.

Parameters:
location - the cell's location (cell indices).
fillColor - the filling color of the cell
boundary - if true the boundary lines are considered to be part of the cell; otherwise the boundary lines are left intact

getColor

public java.awt.Color getColor(java.awt.Point pt)
Returns the color of the pixel of the background at given point. (Be aware that sprite images are not part of the background.)

Parameters:
pt - point, where to pick the color; if pt is outside the grid, returns Color.black.
Returns:
the color at the selected point

getColor

public java.awt.Color getColor(Location location)
Returns the color of the pixel of the background at given cell's center. (Be aware that sprite images are not part of the background.)

Parameters:
location - cell's location where to pick the color; if location is outside the grid, returns Color.black.
Returns:
the color at the selected cell's center

setFont

public void setFont(java.awt.Font font)
Sets the current font for displaying text with drawText()

Parameters:
font - the font to be used

drawText

public void drawText(java.lang.String text,
                     java.awt.Point pt)
Displays the given text at the given position using the current font.

Parameters:
text - the text to display
pt - the start point of the text baseline

getAvailableFontFamilies

public static java.lang.String[] getAvailableFontFamilies()
Returns the available font families for the current platform.

Returns:
a string that describes the available font families

getContext

public java.awt.Graphics2D getContext()
Returns the graphics device context of the background.

Returns:
the Graphics2D of the background

setPaintMode

public void setPaintMode()
Sets the paint mode of the graphics context to overwrite with current color.


setXORMode

public void setXORMode(java.awt.Color c)
Sets the paint mode to alternate between the current color and the given color. This specifies that logical pixel operations are performed in the XOR mode, which alternates pixels between the current color and a specified XOR color. When drawing operations are performed, pixels which are the current color are changed to the specified color, and vice versa. Pixels that are of colors other than those two colors are changed in an unpredictable but reversible manner; if the same figure is drawn twice, then all pixels are restored to their original values.