GF4J 0.9.4 Beta

gameframe.graphics
Interface GraphicsEngine


public interface GraphicsEngine

Defines an interface to a graphics engine that can be thought to be a "display device". The graphics engine uses double buffering and offers a few methods for loading a bitmap in Windows BMP (8-bit, 16-bit or 24-bit) format, handling the double buffering, converting text strings to bitmap representations and drawing text strings directly.

Note: The actual implementation is recommended to use double buffering if such is available, if no such feature is available backbuffering can be omitted. In the case double buffering is not available all operations affect the one and only displayed buffer and the flip() method does nothing.

Note2: The graphics engine will not create bitmaps larger than the currently used resolution. If you try to create larger bitmaps they are allways automatically clipped to have the maximum width and/or height. This is due to limitations in some platforms and those limitations must be forced to every implementation to make the library work uniformly in all platforms. Writing code to handle this internally by the GameFrame library (by dividing the bitmaps to smaller ones) is too big of a task (at least for the time being).

Since:
GameFrame for Java 0.9
Version:
GameFrame for Java 0.9.4
Author:
Pasi Keränen 16. May 1999
See Also:
Bitmap, DrawableBitmap

Field Summary
static int[] ALL_COLOURDEPTHS
          All supported colour depths.
static int COLOURDEPTH_16BITS
          Constant for 16-bits colour depth.
static int COLOURDEPTH_24BITS
          Constant for 24-bits colour depth.
static int COLOURDEPTH_32BITS
          Constant for 32-bits colour depth.
static int DEFAULT_COLOURDEPTH
          Constant for default colour depth when none is set by the user.
static java.lang.String DEFAULT_TITLE
          Constant that is set as the default title for all graphics engine windows.
static int NO_PREFERRED_REFRESHRATE
          Constant for refreshrate when there is no preferred refresh rate.
 
Method Summary
 void clearBackbuffer()
          Paints the current backbuffer with the current backround color.
 void drawTextAt(byte[] aByteText, int x, int y)
          Prints the given string to the screen so that the uppermost and leftmost coordinate of the text is at the given location.
 void drawTextAt(java.lang.String strText, int x, int y)
          Draws the given string to the screen so that the uppermost and leftmost coordinate of the text is at the given location.
 void flip()
          Switches the backbuffer and the currently displayed buffer.
 DrawableBitmap getAsBitmap(byte[] aByteText)
          Returns the given one line of text as an bitmap that is painted using the current font.
 DrawableBitmap getAsBitmap(java.lang.String strText)
          Returns the given one line of text as an bitmap that is painted using the current font.
 java.lang.String getDataDirectory()
          Returns the data directory wherefrom the bitmaps are loaded.
 java.lang.String getDescription()
          Returns the (possibly multiline) description of the implementation.
 DrawableBitmap getDrawableBitmap(int width, int height)
          Creates a non-transparent bitmap (the color is set to the current background color) that can be drawn into with other bitmaps.
 int getFontHeight()
          Returns the current font height.
 int getFontWidth()
          Returns the current font width.
 java.lang.String getName()
          Returns the short name (max 8 characters) of the implementation e.g.
 java.awt.Dimension getSize()
          Returns the size of the display area that this engine uses.
 int getTextWidth(byte[] aByteText)
          Returns the given one line of text's width when we are using the current font bitmap.
 int getTextWidth(java.lang.String strText)
          Returns the given one line of text's width when we are using the current font bitmap.
 boolean isInFullscreenMode()
          Returns true if the engine is in fullscreen mode, false if in windowed mode.
 Bitmap loadAlphaBitmap(java.lang.String fileName)
          Loads and returns a transparent bitmap (used bitmap format is Windows BMP 8-bit, 16-bit or 24-bit) from the given filename.
 Bitmap loadAlphaBitmap(java.lang.String fileName, byte red, byte green, byte blue)
          Loads and returns a transparent bitmap (used bitmap format is Windows BMP 8-bit, 16-bit or 24-bit) from the given filename.
 Bitmap loadBitmap(java.lang.String fileName)
          Loads and returns a non-transparent bitmap (used bitmap format is Windows BMP 8-bit, 16-bit or 24-bit) from the given filename.
 void loadDefaultFontBitmap()
          Loads the default font bitmap that is used when printing text on the screen.
 void loadFontBitmap(java.lang.String filename)
          Loads and sets the used font set to be loaded from the given filename using a calculated fixed size for every letter.
 void setBackgroundColor(java.awt.Color color)
          Sets the currently used background color (which defaults to Color.black).
 void setDataDirectory(java.lang.String strDirectoryName)
          Sets the data directory wherefrom the bitmaps are loaded.
 

Field Detail

DEFAULT_TITLE

public static final java.lang.String DEFAULT_TITLE
Constant that is set as the default title for all graphics engine windows.

NO_PREFERRED_REFRESHRATE

public static final int NO_PREFERRED_REFRESHRATE
Constant for refreshrate when there is no preferred refresh rate.

COLOURDEPTH_16BITS

public static final int COLOURDEPTH_16BITS
Constant for 16-bits colour depth.

COLOURDEPTH_24BITS

public static final int COLOURDEPTH_24BITS
Constant for 24-bits colour depth.

COLOURDEPTH_32BITS

public static final int COLOURDEPTH_32BITS
Constant for 32-bits colour depth.

ALL_COLOURDEPTHS

public static final int[] ALL_COLOURDEPTHS
All supported colour depths.

DEFAULT_COLOURDEPTH

public static final int DEFAULT_COLOURDEPTH
Constant for default colour depth when none is set by the user.
Method Detail

setDataDirectory

public void setDataDirectory(java.lang.String strDirectoryName)
                      throws java.io.FileNotFoundException
Sets the data directory wherefrom the bitmaps are loaded. The source directory defaults to the current directory. Note: Remember to use the java.io.File.separator as the separator of directories.
Parameters:
strDirectoryName - The name of the directory that contains the bitmaps.
Throws:
java.io.FileNotFoundException - Thrown if the given directory doesn't exist.
Since:
GameFrame for Java 0.9
See Also:
loadBitmap(java.lang.String), loadAlphaBitmap(java.lang.String)

getDataDirectory

public java.lang.String getDataDirectory()
Returns the data directory wherefrom the bitmaps are loaded. The source directory defaults to the current directory. Note: The returned path will have the path separator as the last character.
Returns:
The name of the directory that wherefrom the bitmaps are loaded.
Since:
GameFrame for Java 0.9.3
See Also:
loadBitmap(java.lang.String), loadAlphaBitmap(java.lang.String)

loadBitmap

public Bitmap loadBitmap(java.lang.String fileName)
                  throws java.io.FileNotFoundException,
                         GameFrameException
Loads and returns a non-transparent bitmap (used bitmap format is Windows BMP 8-bit, 16-bit or 24-bit) from the given filename. Bitmaps are loaded by default from the current directory, the directory that is used to load the bitmaps can be set with the setDataDirectory() method. If the bitmap is larger than current resolution it will be clipped to the dimensions of the current resolution.
Parameters:
fileName - The name of the file to be loaded (without the file extension).
Returns:
Bitmap object that represents the loaded bitmap image or null if the loading failed.
Throws:
java.io.FileNotFoundException - Thrown if the given file doesn't exist.
GameFrameException - Thrown if other error occur while loading the file.
Since:
GameFrame for Java 0.9
See Also:
setDataDirectory(java.lang.String), loadAlphaBitmap(java.lang.String), Bitmap

loadAlphaBitmap

public Bitmap loadAlphaBitmap(java.lang.String fileName)
                       throws java.io.FileNotFoundException,
                              GameFrameException
Loads and returns a transparent bitmap (used bitmap format is Windows BMP 8-bit, 16-bit or 24-bit) from the given filename. Bitmap is loaded by default from the current directory, the directory that is used to load the bitmaps can be set with the setDataDirectory() method. Alpha keycolor (the color that is interpreted as the transparent color) is set to the pixel color at bitmap location 0,0 which is the pixel at upper left corner of the bitmap).If the bitmap is larger than current resolution it will be clipped to the dimensions of the current resolution.
Parameters:
fileName - The name of the file to be loaded (without the file extension).
Returns:
Bitmap object that represents the loaded bitmap image or null if the loading failed.
Throws:
java.io.FileNotFoundException - Thrown if the given file doesn't exist.
GameFrameException - Thrown if other error occur while loading the file.
Since:
GameFrame for Java 0.9
See Also:
setDataDirectory(java.lang.String), loadBitmap(java.lang.String), loadAlphaBitmap(java.lang.String, byte, byte, byte), Bitmap

loadAlphaBitmap

public Bitmap loadAlphaBitmap(java.lang.String fileName,
                              byte red,
                              byte green,
                              byte blue)
                       throws java.io.FileNotFoundException,
                              GameFrameException
Loads and returns a transparent bitmap (used bitmap format is Windows BMP 8-bit, 16-bit or 24-bit) from the given filename. Bitmap is loaded by default from the current data directory, the directory that is used to load the bitmaps can be set with the setDataDirectory() method. Alpha keycolor (the color that is interpreted as the transparent color) is taken from the given red, green and blue values. If the bitmap is larger than current resolution it will be clipped to the dimensions of the current resolution.
Parameters:
fileName - The name of the file to be loaded (without the file extension).
red - The red intensity value of the key color (in range 0x00-0xFF).
green - The green intensity value of the key color (in range 0x00-0xFF).
blue - The blue intensity value of the key color (in range 0x00-0xFF).
Returns:
Bitmap object that represents the loaded bitmap image or null if the loading failed.
Throws:
java.io.FileNotFoundException - Thrown if the given file doesn't exist.
GameFrameException - Thrown if other error occur while loading the file.
Since:
GameFrame for Java 0.9.4
See Also:
setDataDirectory(java.lang.String), loadBitmap(java.lang.String), loadAlphaBitmap(java.lang.String), Bitmap

getDrawableBitmap

public DrawableBitmap getDrawableBitmap(int width,
                                        int height)
                                 throws GameFrameException
Creates a non-transparent bitmap (the color is set to the current background color) that can be drawn into with other bitmaps. If the bitmap is larger than current resolution it will be clipped to the dimensions of the current resolution.
Parameters:
width - The width of the created bitmap.
height - The height of the created bitmap
Returns:
The created bitmap or null if creation failed.
Throws:
GameFrameException - Thrown if errors occur while creating the bitmap.
Since:
GameFrame for Java 0.9

flip

public void flip()
Switches the backbuffer and the currently displayed buffer. After this operation returns the old backbuffer is visible on the screen and the old front buffer is now the backbuffer that is affected by the drawing operations.
Since:
GameFrame for Java 0.9

setBackgroundColor

public void setBackgroundColor(java.awt.Color color)
Sets the currently used background color (which defaults to Color.black). The background color is the color that is used to clear the backbuffer and set to be the background color of created drawable bitmaps.
Since:
GameFrame for Java 0.9
See Also:
clearBackbuffer()

clearBackbuffer

public void clearBackbuffer()
Paints the current backbuffer with the current backround color.
Since:
GameFrame for Java 0.9
See Also:
setBackgroundColor(java.awt.Color)

loadDefaultFontBitmap

public void loadDefaultFontBitmap()
                           throws java.io.FileNotFoundException,
                                  GameFrameException
Loads the default font bitmap that is used when printing text on the screen. Either this method or the setFontBitmap() method must be invoked before using any of the getAsString() or drawTextAt() methods. If the font bitmap is larger than current resolution it will be clipped to the dimensions of the current resolution.
Throws:
java.io.FileNotFoundException - Thrown if the default font bitmap can't be found.
GameFrameException - Thrown if other errors occur while loading the default font bitmap.
Since:
GameFrame for Java 0.9.1
See Also:
loadFontBitmap(java.lang.String), getAsBitmap(java.lang.String), getAsBitmap(byte[]), drawTextAt(java.lang.String, int, int), drawTextAt(byte[], int, int)

loadFontBitmap

public void loadFontBitmap(java.lang.String filename)
                    throws java.io.FileNotFoundException,
                           GameFrameException
Loads and sets the used font set to be loaded from the given filename using a calculated fixed size for every letter. The filename must specify a Windows BMP formatted bitmap (8-bit, 16-bit or 24-bit colour) that is then loaded as transparent (alpha) bitmap. The order in the bitmap must use the standard ASCII letter order (order can be obtained by running the FontOrder class included with the GameFrame examples) and it must contain 16 columns of letters in 16 rows (that is a 16x16 matrix of letters = 256 letters in whole). If a nonexisting bitmap or fontbitmap of invalid size is used, the method will do nothing. Either this method or the setDefaultFontBitmap() method must be called before using any of the getAsString() or drawTextAt() methods.If the font bitmap is larger than current resolution it will be clipped to the dimensions of the current resolution.
Parameters:
filename - Name of the bitmap file that contains the letters.
Throws:
java.io.FileNotFoundException - Thrown if the given font bitmap can't be found.
GameFrameException - Thrown if other error occur while loading the font bitmap.
Since:
GameFrame for Java 0.9.1
See Also:
loadDefaultFontBitmap(), getAsBitmap(java.lang.String), getAsBitmap(byte[]), drawTextAt(java.lang.String, int, int), drawTextAt(byte[], int, int)

getTextWidth

public int getTextWidth(java.lang.String strText)
Returns the given one line of text's width when we are using the current font bitmap. The method doesn't take into account possible clipping to current screen size.
Parameters:
strText - The text that is written using the current font.
Returns:
The width of the given text.
Since:
GameFrame for Java 0.9.3
See Also:
loadDefaultFontBitmap(), loadFontBitmap(java.lang.String)

getTextWidth

public int getTextWidth(byte[] aByteText)
Returns the given one line of text's width when we are using the current font bitmap.
Parameters:
aByteText - The byte array containing the text to be measured.
Returns:
The width of the given text.
Since:
GameFrame for Java 0.9.3
See Also:
loadDefaultFontBitmap(), loadFontBitmap(java.lang.String)

getFontWidth

public int getFontWidth()
Returns the current font width.
Since:
GameFrame for Java 0.9.3
See Also:
loadDefaultFontBitmap(), loadFontBitmap(java.lang.String)

getFontHeight

public int getFontHeight()
Returns the current font height.
Since:
GameFrame for Java 0.9.3
See Also:
loadDefaultFontBitmap(), loadFontBitmap(java.lang.String)

getAsBitmap

public DrawableBitmap getAsBitmap(java.lang.String strText)
                           throws GameFrameException
Returns the given one line of text as an bitmap that is painted using the current font. The returned bitmap will have the background color set to the current background color of the graphics engine. This means also that the returned bitmap is never transparent (due to limitations on some platforms). If the resulting bitmap is larger than current resolution it will be clipped to the dimensions of the current resolution.
Parameters:
strText - The text that is written using the current font.
Returns:
The text as bitmap or null if not successfull. Textual description of the error can be gotten with getLastError().
Throws:
GameFrameException - Thrown if errors occur.
Since:
GameFrame for Java 0.9
See Also:
loadDefaultFontBitmap(), loadFontBitmap(java.lang.String)

getAsBitmap

public DrawableBitmap getAsBitmap(byte[] aByteText)
                           throws GameFrameException
Returns the given one line of text as an bitmap that is painted using the current font. The returned bitmap will have the background color set to the current background color of the graphics engine. This means also that the returned bitmap is never transparent (due to limitations on some platforms). If the resulting bitmap is larger than current resolution it will be clipped to the dimensions of the current resolution.
Parameters:
aByteText - The byte array containing the text to be printed.
Returns:
The text as bitmap or null if not successfull. Textual description of the error can be gotten with getLastError().
Throws:
GameFrameException - Thrown if errors occur.
Since:
GameFrame for Java 0.9
See Also:
loadDefaultFontBitmap(), loadFontBitmap(java.lang.String)

drawTextAt

public void drawTextAt(java.lang.String strText,
                       int x,
                       int y)
                throws GameFrameException
Draws the given string to the screen so that the uppermost and leftmost coordinate of the text is at the given location.
Parameters:
strText - The text that is written using the current font.
x - The leftmost x-coordinate for the text.
y - The topmost y-coordinate for the text.
Throws:
GameFrameException - Thrown if the font bitmap is not set correctly or other errors occur.
Since:
GameFrame for Java 0.9
See Also:
loadDefaultFontBitmap(), loadFontBitmap(java.lang.String)

drawTextAt

public void drawTextAt(byte[] aByteText,
                       int x,
                       int y)
                throws GameFrameException
Prints the given string to the screen so that the uppermost and leftmost coordinate of the text is at the given location.
Parameters:
aByteText - The byte array containing the text to be printed.
x - The leftmost x-coordinate for the text.
y - The topmost y-coordinate for the text.
Throws:
GameFrameException - Thrown if the font bitmap is not set correctly or other errors occur.
Since:
GameFrame for Java 0.9
See Also:
loadDefaultFontBitmap(), loadFontBitmap(java.lang.String)

isInFullscreenMode

public boolean isInFullscreenMode()
Returns true if the engine is in fullscreen mode, false if in windowed mode. Note: Window that is exactly the same size as the desktop resolution is still considered to be in windowed mode.
Returns:
True if the engine is in fullscreen mode, false if in windowed mode.
Since:
GameFrame for Java 0.9

getSize

public java.awt.Dimension getSize()
Returns the size of the display area that this engine uses. For fullscreen modes it is the size of the fullscreen mode. For windowed modes the size is size of the window.
Returns:
The size of the display area.
Since:
GameFrame for Java 0.9.2

getName

public java.lang.String getName()
Returns the short name (max 8 characters) of the implementation e.g. "Java11" or "DDraw".
Returns:
The short name of the graphics engine.
Since:
GameFrame for Java 0.9.3

getDescription

public java.lang.String getDescription()
Returns the (possibly multiline) description of the implementation.
Returns:
A description of the graphics engine.
Since:
GameFrame for Java 0.9.3

GF4J 0.9.4 Beta