org.jrabbit.base.graphics.image
Class ImagePainter

java.lang.Object
  extended by org.jrabbit.base.graphics.image.ImagePainter

public class ImagePainter
extends java.lang.Object

A class that manages creating and rendering to images. This allows for much more control and utilization of Images. This functionality is quite useful in a variety of situations. For example, say your game has some brick walls. If a bullet hits a wall, you can render a hole where you want to show the impact. Other options are useful, too - rendering a complex, computationally expensive object (like a large paragraph of text) to an image lets you "cache" the resulting render and use it far more quickly in the future. NOTE: This class can render to ANY texture, not just those created by Images.

Author:
Chris Molini

Field Summary
private static java.util.Stack<java.lang.Integer> activeFBOs
          Rendering to texture is designed to work in a "recursive" manner - that is, starting to render to another texture while already rendering to another will not cause the engine to crash.
 
Constructor Summary
ImagePainter()
           
 
Method Summary
static void bindFBO(int fBOID, int target)
          Binds the target FBO, rendering to the indicated target.
static void checkFBO(int FBOID)
          Determines whether or not a particular FBO is "intact" (is working properly).
static Image copy(Image source, java.lang.String reference)
          Creates a copy of the target image under the indicated name.
static Image copyAtScale(Image src, java.lang.String name, double scaleX, double scaleY)
          Same as copy(), but the returned image is scaled across both its width and its height.
static Image copyAtScale(Image source, java.lang.String name, float scale)
          Same as copy(), but the returned image is a scaled copy.
static org.newdawn.slick.opengl.Texture createTexture(int width, int height)
          Loads a blank (completely transparent) image into memory that has the required dimensions.
static void deleteFBO(int fBOID)
          Destroys the indicated FBO.
static boolean drawTo(Image image)
          Begins drawing to the supplied Image.
static boolean drawTo(int target, int width, int height)
          Begins drawing to the OpenGL texture referenced by the ID, bounded by the indicated width and height.
static boolean drawTo(org.newdawn.slick.opengl.Texture texture)
          Begins drawing to the supplied texture.
static void escapeDrawing()
          Continuously exits from rendering to texture, resolving each one until rendering is once again pointed to the Display.
static boolean finishDrawing()
          Finishes the current render-to-texture if there is one.
static int genFBO()
          Attempts to create an FBO and return its ID.
static boolean renderingToTexture()
          Checks whether or not OpenGL is rendering to texture.
static boolean renderToTextureCapable()
          Checks whether or not the graphics card and driver support FrameBuffers.
static void unbindFBO()
          Escapes drawing from an FBO and simply renders to the regular Display.
static void wipe()
          Clears the current render target to transparent black.
static void wipe(Color color)
          Clears the current render target to that indicated color.
static void wipe(float red, float green, float blue)
          Wipes the current render target to that indicated solid color.
static void wipe(float red, float green, float blue, float alpha)
          Wipes the current render target to that indicated solid color.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

activeFBOs

private static java.util.Stack<java.lang.Integer> activeFBOs
Rendering to texture is designed to work in a "recursive" manner - that is, starting to render to another texture while already rendering to another will not cause the engine to crash. This Stack keeps track of all rendering implemented through this class.

Constructor Detail

ImagePainter

public ImagePainter()
Method Detail

createTexture

public static org.newdawn.slick.opengl.Texture createTexture(int width,
                                                             int height)
Loads a blank (completely transparent) image into memory that has the required dimensions.

Parameters:
width - The requested width of the texture.
height - The requested height of the texture.
Returns:
A blank texture that contains the indicated dimensions. The resulting texture is actually Power-Of-Two, so it may be significantly larger than is needed.

copy

public static Image copy(Image source,
                         java.lang.String reference)
Creates a copy of the target image under the indicated name. This is done by creating a blank image of the same dimensions, and rendering the source image to it.

Parameters:
source - The image to copy.
reference - The identifier of the copied image.
Returns:
An Image that is a copy of the one specified.

copyAtScale

public static Image copyAtScale(Image source,
                                java.lang.String name,
                                float scale)
Same as copy(), but the returned image is a scaled copy.

Parameters:
source - The image to copy.
name - The identifier of the copied image.
scale - How much to multiply the width and height of the image.
Returns:
An image that is a copy of the one specified, but at a scaled width and height.
See Also:
copy

copyAtScale

public static Image copyAtScale(Image src,
                                java.lang.String name,
                                double scaleX,
                                double scaleY)
Same as copy(), but the returned image is scaled across both its width and its height.

Parameters:
source - The image to copy.
name - The identifier of the copied image.
scaleX - How much to multiply the width of the image.
scaleY - How much to multiply the height of the image.
Returns:
An image that is a copy of the one specified, but at a scaled width and height.
See Also:
copy(Image, String)

renderToTextureCapable

public static boolean renderToTextureCapable()
Checks whether or not the graphics card and driver support FrameBuffers.

Returns:
True if rendering to texture is possible, false if not.

drawTo

public static boolean drawTo(Image image)
Begins drawing to the supplied Image.

Parameters:
image - The image to draw to.
Returns:
True if the target is being rendered to, false if not.

drawTo

public static boolean drawTo(org.newdawn.slick.opengl.Texture texture)
Begins drawing to the supplied texture.

Parameters:
texture - The texture to draw to.
Returns:
True if the target is being rendered to, false if not.

drawTo

public static boolean drawTo(int target,
                             int width,
                             int height)
Begins drawing to the OpenGL texture referenced by the ID, bounded by the indicated width and height. This stores the current Modelview Matrix, Color information (the color bound, blending function, etc) and the Viewport settings on the stack so that they can be restored after rendering has finished. After this call is finished, the viewport is set to the window dimensions, the bound color is opaque white, and the Blend setting defaults to Normal blending. NOTE: The indicated dimensions should be less than or equal to those of the actual texture.

Parameters:
target - The ID of the texture on the graphics card.
width - The width of the area to render to.
Returns:
True if the target is being rendered to, false if not.

genFBO

public static int genFBO()
Attempts to create an FBO and return its ID.

Returns:
If the FBO creation completed successfully, returns the ID. If not, returns 0.

deleteFBO

public static void deleteFBO(int fBOID)
Destroys the indicated FBO.

Parameters:
fBOID - The ID of the FBO to destroy.

bindFBO

public static void bindFBO(int fBOID,
                           int target)
Binds the target FBO, rendering to the indicated target.

Parameters:
fBO - The FBO ID to use.
target - The ID of the render target.

unbindFBO

public static void unbindFBO()
Escapes drawing from an FBO and simply renders to the regular Display. NOTE: This should be avoided unless the FBOs that are active are not managed by ImagePainter. Using this command while ImagePainter has its own active FBOs will result in undefined behavior.


finishDrawing

public static boolean finishDrawing()
Finishes the current render-to-texture if there is one. Restores the ModelView matrix, the viewport, and the color settings (including the blending function) to what they were before render-to-texture began.

Returns:
True if a render-to-texture finished, false if not.

escapeDrawing

public static void escapeDrawing()
Continuously exits from rendering to texture, resolving each one until rendering is once again pointed to the Display.


wipe

public static void wipe(Color color)
Clears the current render target to that indicated color.

Parameters:
color - The color to wipe the screen to.

wipe

public static void wipe(float red,
                        float green,
                        float blue)
Wipes the current render target to that indicated solid color.

Parameters:
red - The red value to clear the screen to.
green - The green value to clear the screen to.
blue - The blue value to clear the screen to.

wipe

public static void wipe(float red,
                        float green,
                        float blue,
                        float alpha)
Wipes the current render target to that indicated solid color.

Parameters:
red - The red value to clear the screen to.
green - The green value to clear the screen to.
blue - The blue value to clear the screen to.
alpha - The alpha value to clear the screen to.

wipe

public static void wipe()
Clears the current render target to transparent black.


renderingToTexture

public static boolean renderingToTexture()
Checks whether or not OpenGL is rendering to texture. NOTE: This method only checks values within this class - it doesn't interface with OpenGL to determine the render target. As such, the developer can conceivably use external means to render to texture, and this method will not register that.

Returns:
True if a texture is being rendered to, false if not.

checkFBO

public static void checkFBO(int FBOID)
Determines whether or not a particular FBO is "intact" (is working properly). If not, a RuntimeException is thrown.

Parameters:
FBOID - The ID of the FrameBuffer to check.