Package de.vatrasoft.vatralib.gfx

Interface GfxBinding

All Superinterfaces:

Binding

public interface GfxBinding
extends Binding

A GfxBinding (Graphics Binding) is a component that translates abstract graphics operations to concrete, framework-specific operations in order to manipulate the screen. Examples for such operations are "create a window with a certain title and a certain size" and "draw the pixels of a certain image at a certain position within the window".

This interface describes these abstract graphics operations, i.e. it contains all methods that a concrete GfxBinding must implement.

Apart from graphics operations, a GfxBinding also deals with handling user input.

Field Summary

Fields

Modifier and Type	Field	Description
static int	MAX_OPACITY	The maximum allowed opacity (i.e. all objects will be fully opaque)
static int	MIN_OPACITY	The minimum allowed opacity (i.e. all objects will be fully transparent)

Method Summary

Modifier and Type	Method	Description
void	beginFrame()	Prepares for the next frame to be drawn, e.g. clears the screen or internal buffer.
void	clear()	Clears the screen and ensures that no previously cached objects (i.e. images) are subsequently displayed (i.e.
void	createWindow(java.lang.String windowTitle, int width, int height, Color backgroundColor, boolean fullscreen)	Creates a window with the given title and dimensions, using the given color as background.
void	drawFilledArea(long id, java.lang.String filepath, int x, int y, int z, int width, int height, int opacity)	Draws the pixels of the given image file repeatedly onto the screen (starting at the specified position within the active window) until the rectangular area denoted by width and height is covered.
void	drawImage(long id, java.lang.String filepath, int x, int y, int z, int opacity)	Draws the pixels of the given image file onto the screen (at the specified position within the active window).
void	drawImageSection(long id, java.lang.String filepath, Rectangle imageSection, int x, int y, int z, int opacity, boolean flipX, boolean flipY)	Draws the pixels of the given rectangular section of the given image file onto the screen (at the specified position within the active window).
void	finishFrame()	Finalizes the frame that is currently being drawn, e.g. copies buffer contents onto the screen.
boolean	isAnyKeyPressed()	Indicates if any key is currently being pressed on the keyboard.
boolean	isKeyPressed(Key key)	Indicates if the given Key is currently being pressed on the keyboard.
void	removeObject(long id)	Removes the object with the given ID from the screen and ensures that it will not be displayed until a new call to drawImage(long, String, int, int, int, int), drawImageSection(long, String, Rectangle, int, int, int, int, boolean, boolean) or drawFilledArea(long, String, int, int, int, int, int, int) is made for the same object ID.
Dimensions	retrieveImageDimensions(java.lang.String filepath)	Retrieves the dimensions, i.e. width and height, of the image denoted by the given filepath.
void	setBackgroundColor(Color color)	Sets the desired background color for the active window.
void	setFullscreen(boolean fullscreenMode)	Enables or disables fullscreen mode.
void	setTotalOpacity(int opacity)	Sets the desired opacity for all objects.
boolean	supportsZOrdering()	Indicates if this GfxBinding can take care of drawing some objects on top of others depending on their z coordinate.

Methods inherited from interface de.vatrasoft.vatralib.Binding

getSupportedFileFormats, isFileFormatSupported

Field Detail

MIN_OPACITY

static final int MIN_OPACITY

The minimum allowed opacity (i.e. all objects will be fully transparent)

See Also:

Constant Field Values

MAX_OPACITY

static final int MAX_OPACITY

The maximum allowed opacity (i.e. all objects will be fully opaque)

See Also:

Constant Field Values

Method Detail

createWindow

void createWindow(java.lang.String windowTitle,
                  int width,
                  int height,
                  Color backgroundColor,
                  boolean fullscreen)

Creates a window with the given title and dimensions, using the given color as background.

Parameters:

windowTitle - the desired window title

width - the desired width in pixels

height - the desired height in pixels

backgroundColor - the Color to use as background

fullscreen - true means that the application should start in fullscreen mode

setBackgroundColor

void setBackgroundColor(Color color)

Sets the desired background color for the active window.

Parameters:

color - the desired Color

setFullscreen

void setFullscreen(boolean fullscreenMode)

Enables or disables fullscreen mode.

Parameters:

fullscreenMode - true means fullscreen mode, false means windowed mode

setTotalOpacity

void setTotalOpacity(int opacity)

Sets the desired opacity for all objects. An opacity of MIN_OPACITY means that all objects are fully transparent (i.e. invisible) and that only the background color (see setBackgroundColor(Color)) will be shown, an opacity of MAX_OPACITY means that all objects are fully opaque (i.e. visible).

Values outside the allowed range are clipped.

Parameters:

opacity - the desired opacity

beginFrame

void beginFrame()

Prepares for the next frame to be drawn, e.g. clears the screen or internal buffer. This method will be called by the Engine at the beginning of each iteration over the objects that are to be drawn.

Note that a concrete GfxBinding might not need to do anything in this method, depending on the technology it uses for drawing onto the screen.

finishFrame

void finishFrame()

Finalizes the frame that is currently being drawn, e.g. copies buffer contents onto the screen. This method will be called by the Engine at the end of each iteration over the objects that are to be drawn.

Note that a concrete GfxBinding might not need to do anything in this method, depending on the technology it uses for drawing onto the screen.

retrieveImageDimensions

Dimensions retrieveImageDimensions(java.lang.String filepath)

Retrieves the dimensions, i.e. width and height, of the image denoted by the given filepath.

Parameters:

filepath - the path to the image file (use prefix "file:" for file system paths; otherwise, file is expected to be on the classpath)

Returns:

the dimensions of the image, encapsulated in a Dimensions object

drawImage

void drawImage(long id,
               java.lang.String filepath,
               int x,
               int y,
               int z,
               int opacity)

Draws the pixels of the given image file onto the screen (at the specified position within the active window). The width and height of the data in the image file are retained, i.e. no scaling is performed.

Parameters:

id - the unique ID of the underlying object; can be used by the GfxBinding for internal caching (useful especially when the same object is drawn again and again, and/or when the same image is being used by several objects)

filepath - the path to the image file (use prefix "file:" for file system paths; otherwise, file is expected to be on the classpath)

x - the desired horizontal position (zero means left border of window)

y - the desired vertical position (zero means top border of window)

z - the desired z coordinate (higher means in the front, lower means in the back)

opacity - the desired opacity (zero means fully transparent, 100 means fully opaque)

drawFilledArea

void drawFilledArea(long id,
                    java.lang.String filepath,
                    int x,
                    int y,
                    int z,
                    int width,
                    int height,
                    int opacity)

Draws the pixels of the given image file repeatedly onto the screen (starting at the specified position within the active window) until the rectangular area denoted by width and height is covered.

Parameters:

id - the unique ID of the underlying object; can be used by the GfxBinding for internal caching (useful especially when the same object is drawn again and again, and/or when the same image is being used by several objects)

filepath - the path to the image file (use prefix "file:" for file system paths; otherwise, file is expected to be on the classpath)

x - the desired horizontal position of the area (zero means left border of window)

y - the desired vertical position of the area (zero means top border of window)

z - the desired z coordinate (higher means in the front, lower means in the back)

width - the desired width of the area

height - the desired height of the area

opacity - the desired opacity (zero means fully transparent, 100 means fully opaque)

drawImageSection

void drawImageSection(long id,
                      java.lang.String filepath,
                      Rectangle imageSection,
                      int x,
                      int y,
                      int z,
                      int opacity,
                      boolean flipX,
                      boolean flipY)

Draws the pixels of the given rectangular section of the given image file onto the screen (at the specified position within the active window).

Parameters:

id - the unique ID of the underlying object; can be used by the GfxBinding for internal caching (useful especially when the same object is drawn again and again, and/or when the same image is being used by several objects)

filepath - the path to the image file (use prefix "file:" for file system paths; otherwise, file is expected to be on the classpath)

imageSection - the rectangular section of the image that should be drawn onto the screen

x - the desired horizontal position (zero means left border of window)

y - the desired vertical position (zero means top border of window)

z - the desired z coordinate (higher means in the front, lower means in the back)

opacity - the desired opacity (zero means fully transparent, 100 means fully opaque)

flipX - true means that the image section should be flipped horizontally

flipY - true means that the image section should be flipped vertically

removeObject

void removeObject(long id)

Removes the object with the given ID from the screen and ensures that it will not be displayed until a new call to drawImage(long, String, int, int, int, int), drawImageSection(long, String, Rectangle, int, int, int, int, boolean, boolean) or drawFilledArea(long, String, int, int, int, int, int, int) is made for the same object ID.

Parameters:

id - the unique ID of the underlying object; see draw* methods

Throws:

java.lang.IllegalArgumentException - if the given ID is not found in the GfxBindings internal storage

supportsZOrdering

boolean supportsZOrdering()

Indicates if this GfxBinding can take care of drawing some objects on top of others depending on their z coordinate. If it does not support it, the Engine will sort its objects according to their z coordinate so that the GfxBinding receives them in the right order.

Returns:

true if this GfxBinding supports z-ordering by itself

clear

void clear()

Clears the screen and ensures that no previously cached objects (i.e. images) are subsequently displayed (i.e. clears any caches).

isKeyPressed

boolean isKeyPressed(Key key)

Indicates if the given Key is currently being pressed on the keyboard.

Parameters:

key - the key to check

Returns:

true if the given key is currently being pressed down, false otherwise

isAnyKeyPressed

boolean isAnyKeyPressed()

Indicates if any key is currently being pressed on the keyboard.

Returns:

true if at least one key is currently being pressed down, false otherwise