GF4J 0.9.4 Beta

gameframe.graphics
Interface Bitmap

All Known Implementing Classes:
AnimBitmap

public interface Bitmap

Defines an interface to a bitmap image that can blit (draw) or strecth (scale) itself in the graphics engine's backbuffer or into drawable bitmap. The graphics engine in question is allways the graphics engine that loaded the bitmap. The drawable bitmap in question must be a drawable bitmap created by the same graphics engine as this bitmap. If the drawable bitmap was created by different graphics engine the results are unpredictable. Most of the methods offered in this interface are implemented to be as fast as possible. An exception is the method getSubBitmap() that tries to minimize the memory usage to the extent that is possible (maybe even using the same bitmap data as the original bitmap but with different clipping and blitting regions).

Since:
GameFrame for Java 0.9
Version:
GameFrame for Java 0.9.4
Author:
Pasi Keränen 16. May 1999

Method Summary
 void blitTo(DrawableBitmap bitmap, int x, int y)
          Draws the bitmap to the given drawable bitmap at the given location.
 void blitTo(int x, int y)
          Draws the bitmap to the graphics engine that loaded it at the given location.
 void finalize()
          Frees all the resources that are used by the bitmap implementation.
 Bitmap getClone(BitmapEffect effect)
          Returns an effect processed copy of this bitmap.
 int getHeight()
          Returns the height of the bitmap.
 Bitmap getSubBitmap(int srcX, int srcY, int srcWidth, int srcHeight)
          Returns a bitmap that represents a part of this bitmap by using a new control object, but using the old bitmap data.
 Bitmap getSubBitmapClone(int srcX, int srcY, int srcWidth, int srcHeight)
          Returns a bitmap that represents a part of this bitmap by copying the actual part of the bitmap representation to different memory location.
 int getWidth()
          Returns the width of the bitmap.
 void strecthTo(DrawableBitmap bitmap, int x, int y, int width, int height)
          Draws the bitmap to the given drawable bitmap at the given location at the given size.
 void strecthTo(int x, int y, int width, int height)
          Draws the bitmap to the graphics engine that loaded it at the given location and at the given size.
 

Method Detail

blitTo

public void blitTo(int x,
                   int y)
Draws the bitmap to the graphics engine that loaded it at the given location. The location can be outside of the visible screen area in which case the bitmap is clipped accordingly. This method is fast and is usable during the game execution.
Parameters:
x - The x-coordinate of the location where the image is drawn to.
y - The y-coordinate of the location where the image is drawn to.
Since:
GameFrame for Java 0.9

strecthTo

public void strecthTo(int x,
                      int y,
                      int width,
                      int height)
Draws the bitmap to the graphics engine that loaded it at the given location and at the given size. If this bitmap is larger or smaller than the destination size the bitmap will automatically be scaled. Note: This method is usually a bit slow, so it's use is not preferred during interactive periods in game execution.
Parameters:
x - The x-coordinate of the location where the image is drawn to.
y - The y-coordinate of the location where the image is drawn to.
width - The with that is used when drawing the image.
height - The height that is used when drawing the image.
Since:
GameFrame for Java 0.9

blitTo

public void blitTo(DrawableBitmap bitmap,
                   int x,
                   int y)
Draws the bitmap to the given drawable bitmap at the given location. The location can be outside of the visible screen area in which case the bitmap is clipped accordingly. This method is fast and is usable during the game execution.
Parameters:
bitmap - The bitmap that will be drawn to.
x - The x-coordinate of the location where the image is drawn to.
y - The y-coordinate of the location where the image is drawn to.
Since:
GameFrame for Java 0.9

strecthTo

public void strecthTo(DrawableBitmap bitmap,
                      int x,
                      int y,
                      int width,
                      int height)
Draws the bitmap to the given drawable bitmap at the given location at the given size. If this bitmap is larger or smaller than the destination size the bitmap will automatically be scaled. Note: This method is usually quite slow, so it's use is not preferred during interactive periods in game execution.
Parameters:
bitmap - The bitmap that will be drawn to.
x - The x-coordinate of the location where the image is drawn to.
y - The y-coordinate of the location where the image is drawn to.
width - The with that is used when drawing the image.
height - The height that is used when drawing the image.
Since:
GameFrame for Java 0.9

getWidth

public int getWidth()
Returns the width of the bitmap. This method is fast and is usable during the game execution.
Returns:
Width of the bitmap if available.
Since:
GameFrame for Java 0.9

getHeight

public int getHeight()
Returns the height of the bitmap. This method is fast and is usable during the game execution.
Returns:
Height of the bitmap if available.
Since:
GameFrame for Java 0.9

getClone

public Bitmap getClone(BitmapEffect effect)
                throws GameFrameException

Returns an effect processed copy of this bitmap. This operation copies the actual bitmap data to a new memory location in a processed form and thus consumes memory.

Usually used to save graphics drawing time on game graphics as one can generate an animation sequence on the fly using gradual effects.

Parameters:
effect - The bitmap effect to be applied to the clone bitmap, or null if none are to be applied.
Returns:
An effect processed clone of this bitmap.
Throws:
GameFrameException - thrown if any errors occur.

getSubBitmapClone

public Bitmap getSubBitmapClone(int srcX,
                                int srcY,
                                int srcWidth,
                                int srcHeight)
                         throws GameFrameException

Returns a bitmap that represents a part of this bitmap by copying the actual part of the bitmap representation to different memory location. This consumes memory, but the resulting bitmap is as fast to blit as the original bitmap.

Useful for e.g. extracting animation frames from one bitmap. This method is not very fast and should be preferrably called during game initialization. If for any reason the creation of the new bitmap fails (out of memory etc.) this method throws an GameFrameException exception. If the given rectangle is outside of the bitmap area of the original bitmap or even larger than the original bitmap area this method returns throws an GameFrameException exception (the input values are checked for validity). Also if the area of the given dimensions is 0 then this method also throws an GameFrameException exception.

Parameters:
srcX - The leftmost coordinate of the bitmap to be returned as a new bitmap.
srcY - The topmost coordinate of the bitmap to be returned as a new bitmap.
srcWidth - The width of the bitmap to be returned as a new bitmap.
srcHeight - The height of the bitmap to be returned as a new bitmap.
Returns:
A new bitmap representing the requested part of the original bitmap.
Throws:
GameFrameException - Thrown if clone sub-bitmap creation is not successfull.
Since:
GameFrame for Java 0.9

getSubBitmap

public Bitmap getSubBitmap(int srcX,
                           int srcY,
                           int srcWidth,
                           int srcHeight)
                    throws GameFrameException

Returns a bitmap that represents a part of this bitmap by using a new control object, but using the old bitmap data. This saves memory, but the resulting bitmap is not as fast to blit as the original one on many platforms. On the platforms where this approach is really too slow for interactive use the implementation might actually copy the data (as with the getSubBitmapClone() method) to speed things up to an interactive level.

Useful for e.g. extracting animation frames from one bitmap. This method is not very fast and should be preferrably called during game initialization. If for any reason the creation of the new bitmap fails (out of memory etc.) this method throws an GameFrameException exception. If the given rectangle is outside of the bitmap area of the original bitmap or even larger than the original bitmap area this method throws an GameFrameException exception (i.e. the input values are checked for validity). Also if the area of the given dimensions is 0 then this method also throws an GameFrameException exception.

WARNING! If you create a sub-bitmap with this method and then finalize the original bitmap, the sub-bitmap can also be considered as finalized. This is because the original bitmap no longer contains any valid data and the created sub-bitmap control object is dependant on that data.

Parameters:
srcX - The leftmost coordinate of the bitmap to be returned as a new bitmap.
srcY - The topmost coordinate of the bitmap to be returned as a new bitmap.
srcWidth - The width of the bitmap to be returned as a new bitmap.
srcHeight - The height of the bitmap to be returned as a new bitmap.
Returns:
A new bitmap representing the requested part of the original bitmap.
Throws:
GameFrameException - Thrown if sub-bitmap creation is not successfull.
Since:
GameFrame for Java 0.9

finalize

public void finalize()
Frees all the resources that are used by the bitmap implementation. This method is quite slow to execute and should preferrably be called upon exiting the game or between level changes etc.
Since:
GameFrame for Java 0.9

GF4J 0.9.4 Beta