com.threed.jpct
Class FrameBuffer

java.lang.Object
  extended by com.threed.jpct.FrameBuffer
All Implemented Interfaces:
java.io.Serializable

public class FrameBuffer
extends java.lang.Object
implements java.io.Serializable

The FrameBuffer class provides a buffer into which jPCT renders the scene. The result is basically an Image which could be displayed or modified even further using some post-processing.

See Also:
Serialized Form

Field Summary
static boolean OPAQUE_BLITTING
          2D texture-blitting into the framebuffer is done by copying the source 1-to-1 into the destination bitmap
static boolean TRANSPARENT_BLITTING
          2D texture-blitting into the framebuffer is done by copying the source into the destination bitmap only at places where the sources bitmap has none-zero color-values.
 
Constructor Summary
FrameBuffer(GL10 glContext, int x, int y)
          Creates a new framebuffer with a width of x and a height of y.
 
Method Summary
 void addPostProcessor(IPostProcessor proc)
          Adds an IPostProcessor to run a post processing on the framebuffer.
 void blit(int[] src, int srcWidth, int srcHeight, int srcX, int srcY, int destX, int destY, int width, int height, boolean transparent)
          Copies a part of a bitmap (taken from an int[] containing pixels in RGB-format and with no alpha) into the framebuffer.
 void blit(Texture src, int srcX, int srcY, int destX, int destY, int width, int height, boolean transparent)
          Copies a part of a bitmap (taken from a Texture in this case) into the framebuffer.
 void blit(Texture src, int srcX, int srcY, int destX, int destY, int sourceWidth, int sourceHeight, int destWidth, int destHeight, int transValue, boolean additive, RGBColor addColor)
          Special version of blit() that allows for scaling, i.e. it doesn't make 1-to-1 copies but can up- or down-scale.
 void clear()
          Clears the framebuffer and the z-buffer.
 void clear(RGBColor col)
          Clears the framebuffer with the given color.
 void clearZBufferOnly()
          Clears only the ZBuffer, not the color buffer.
 void display()
          Displays the rendered image.
 void dispose()
          Should be called before this FrameBuffer won't be used anymore to do some clean up work.
 void freeMemory()
          Frees some native memory used by the gl context.
 float getCenterX()
          Returns the x-coord of the midpoint of the framebuffer.
 float getCenterY()
          Returns the y-coord of the midpoint of the framebuffer.
 int getHeight()
          Returns the height of the framebuffer.
 java.lang.Long getID()
          Returns a unique ID for this FrameBuffer.
 int[] getPixels()
          Returns the raw pixel-data.
 int getWidth()
          Returns the width of the framebuffer.
 boolean isInitialized()
          Checks if the FrameBuffer and the renderer have been initialized correctly.
 void removeAllPostProcessors()
          Removes all post processors from the framebuffer.
 void removePostProcessor(IPostProcessor proc)
          Removes a post processor from the framebuffer.
 void removeRenderTarget()
          Removes the render target from the framebuffer.
 void runPostProcessors()
          Runs all post processors that have been added to this framebuffer.
 void setPaintListener(IPaintListener listener)
          Adds a listener to the renderer.
 void setRenderTarget(int texID)
          Sets the render target of the framebuffer to a texture.
 void setRenderTarget(int texID, int left, int top, int right, int bottom, boolean clearAll)
          Sets the render target of the framebuffer to a texture.
 void setRenderTarget(Texture tex)
          Sets the render target of the framebuffer to a texture.
 void setRenderTarget(Texture tex, int left, int top, int right, int bottom, boolean clearAll)
          Sets the render target of the framebuffer to a texture.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

OPAQUE_BLITTING

public static final boolean OPAQUE_BLITTING
2D texture-blitting into the framebuffer is done by copying the source 1-to-1 into the destination bitmap

See Also:
Constant Field Values

TRANSPARENT_BLITTING

public static final boolean TRANSPARENT_BLITTING
2D texture-blitting into the framebuffer is done by copying the source into the destination bitmap only at places where the sources bitmap has none-zero color-values.

See Also:
Constant Field Values
Constructor Detail

FrameBuffer

public FrameBuffer(GL10 glContext,
                   int x,
                   int y)
Creates a new framebuffer with a width of x and a height of y.

Parameters:
glContext - a valid gl context
x - the width of the framebuffer
y - the height of the framebuffer
Method Detail

getID

public java.lang.Long getID()
Returns a unique ID for this FrameBuffer.

Returns:
Long the ID

isInitialized

public boolean isInitialized()
Checks if the FrameBuffer and the renderer have been initialized correctly.

Returns:
true, if the FrameBuffer is fine. Otherwise false.

setRenderTarget

public void setRenderTarget(int texID)
Sets the render target of the framebuffer to a texture. From here on, all rendering is done into that texture instead of the actual framebuffer. The texture has to be smaller or equal to the framebuffer.

Parameters:
texID - the ID of the texture to render into.

setRenderTarget

public void setRenderTarget(int texID,
                            int left,
                            int top,
                            int right,
                            int bottom,
                            boolean clearAll)
Sets the render target of the framebuffer to a texture. From here on, all rendering is done into that texture instead of the actual framebuffer. The texture has to be smaller or equal to the framebuffer, when FBO are not used/available. Rendering into a texture can be slow on some hardware like Intel onboard chipsets.
This is a special purpose version of this method that allows to define a border that isn't affected by the rendering.

Parameters:
texID - the ID of the texture to render into.
left - the width of the left border
top - the width of the upper border
right - the width of the right border
bottom - the width of the lower border
clearAll - if true, the border won't affect the clearing of texture. If set to false, it will.

setRenderTarget

public void setRenderTarget(Texture tex)
Sets the render target of the framebuffer to a texture. From here on, all rendering is done into that texture instead of the actual framebuffer. The texture has to be smaller or equal to the framebuffer.

Parameters:
tex - the texture to render into

setRenderTarget

public void setRenderTarget(Texture tex,
                            int left,
                            int top,
                            int right,
                            int bottom,
                            boolean clearAll)
Sets the render target of the framebuffer to a texture. From here on, all rendering is done into that texture instead of the actual framebuffer. The texture has to be smaller or equal to the framebuffer.
This is a special purpose version of this method that allows to define a border that isn't affected by the rendering.

Parameters:
tex - the texture to render into
left - the width of the left border
top - the width of the upper border
right - the width of the right border
bottom - the width of the lower border
clearAll - if true, the border won't affect the clearing of texture. If set to false, it will.

removeRenderTarget

public void removeRenderTarget()
Removes the render target from the framebuffer. After this, all rendering is done into the framebuffer again. If no render target has been set, this method does nothing.


addPostProcessor

public void addPostProcessor(IPostProcessor proc)
Adds an IPostProcessor to run a post processing on the framebuffer. This isn't done automatically but has to be triggered by the application by calling runPostProcessors() on this framebuffer. Enabling or disabling renderers on this framebuffer causes all post processors to be disposed and then removed from this framebuffer.

Parameters:
proc - the post processor
See Also:
runPostProcessors(), IPostProcessor

removePostProcessor

public void removePostProcessor(IPostProcessor proc)
Removes a post processor from the framebuffer. The processor will be disposed and then removed.

Parameters:
proc - The post processor to be removed
See Also:
IPostProcessor

removeAllPostProcessors

public void removeAllPostProcessors()
Removes all post processors from the framebuffer. The processors will be disposed and then removed.

See Also:
IPostProcessor

runPostProcessors

public void runPostProcessors()
Runs all post processors that have been added to this framebuffer. A post processor is an implementation of the IPostProcessor interface. The processing is done on the framebuffer's back buffer in its current state, i.e. if you run it before blitting, the blitting won't be affected. If you run it afterwards, it will.

See Also:
IPostProcessor

setPaintListener

public void setPaintListener(IPaintListener listener)
Adds a listener to the renderer. The listener will be notified before the renderer starts to paint polygons and after it has finished.

Parameters:
listener - IPaintListener the listener or null to clear it

dispose

public void dispose()
Should be called before this FrameBuffer won't be used anymore to do some clean up work. For example, if you are reusing a buffer variable to assign a new FrameBuffer for it, dispose the former one before doing so.


freeMemory

public void freeMemory()
Frees some native memory used by the gl context. Might be helpful to use this on a framebuffer, before the context is about to get lost, i.e. before the gl context becomes invalid.


getWidth

public int getWidth()
Returns the width of the framebuffer.

Returns:
the width of the framebuffer

getHeight

public int getHeight()
Returns the height of the framebuffer.

Returns:
the height of the framebuffer

getCenterX

public float getCenterX()
Returns the x-coord of the midpoint of the framebuffer. This value represents the internally used width/2.

Returns:
the x-coord

getCenterY

public float getCenterY()
Returns the y-coord of the midpoint of the framebuffer. This value represents the internally used height/2.

Returns:
the y-coord

clear

public void clear()
Clears the framebuffer and the z-buffer. If you are not doing this every frame, it will lead to strange results on some devices...


clearZBufferOnly

public void clearZBufferOnly()
Clears only the ZBuffer, not the color buffer. Can be useful for special effects like rendering two worlds into one frame buffer. Using this method may cause strange renderings on some devices, because they seem to rely on a cleared framebuffer each frame for an unknown reason.


clear

public void clear(RGBColor col)
Clears the framebuffer with the given color. If you are not doing this every frame, it will lead to strange results on some devices...

Parameters:
col - the color the framebuffer is filled with

getPixels

public int[] getPixels()
Returns the raw pixel-data. This can be useful, if one wants to copy parts of the FrameBuffer into an Image out of jPCT's focus. getPixels() should be called after calling update(), because otherwise it is not guaranteed that the returned array contains the most current pixels. The returned array contains the pixel-data in RGB-format and with no alpha information.
This method is very slow, because it has to read all the pixels out of the VRAM and write them into the FrameBuffer's internal pixel-buffer.

Returns:
the pixels-array
See Also:
blit(com.threed.jpct.Texture src, int srcX, int srcY, int destX, int destY, int width, int height, boolean transparent), blit(int[] src, int srcWidth, int srcHeight, int srcX, int srcY, int destX, int destY, int width, int height, boolean transparent)

blit

public void blit(Texture src,
                 int srcX,
                 int srcY,
                 int destX,
                 int destY,
                 int width,
                 int height,
                 boolean transparent)
Copies a part of a bitmap (taken from a Texture in this case) into the framebuffer. If you want your blitted content to lay on top of the rendered image, it has to be applied after calling update() on the buffer. This method is useful to copy 2D-GUI elements into the rendered image (or for similar tasks). Blitting requires that the current world has been rendered at least once into the framebuffer where the blitting should be applied to (for doing some intialization work). Usually, that shouldn't be a problem unless you are abusing jPCT as a "blitting engine" only. Be sure that the texture's height is 2^x. Everything else might produce unpredictable results. This method should be prefered over the int[]-array-blit whenever possible.

Parameters:
src - the texture that contains the source bitmap
srcX - the starting x-position in the source bitmap
srcY - the starting y-position in the source bitmap
destX - the starting x-position in the destination bitmap
destY - the starting y-position in the destination bitmap
width - the width of the region to copy
height - the height of the region to copy
transparent - black (or at least almost black) pixels won't be copied if this is set to TRANSPARENT_BLITTING. Any color-value which leads to a result of zero when "anded" with #f0f0f0 will be taken as black unless your texture specifies its own alpha channel.
See Also:
TRANSPARENT_BLITTING, OPAQUE_BLITTING

blit

public void blit(Texture src,
                 int srcX,
                 int srcY,
                 int destX,
                 int destY,
                 int sourceWidth,
                 int sourceHeight,
                 int destWidth,
                 int destHeight,
                 int transValue,
                 boolean additive,
                 RGBColor addColor)
Special version of blit() that allows for scaling, i.e. it doesn't make 1-to-1 copies but can up- or down-scale. In addition, it offers support for transparency, a different blending mode and an additional color. If you want your blitted content to lay on top of the rendered image, it has to be applied after calling update() on the buffer. This method is useful to copy 2D-GUI elements into the rendered image (or for similar tasks). Blitting requires that the current world has been rendered at least once into the framebuffer where the blitting should be applied to (for doing some intialization work). Usually, that shouldn't be a problem unless you are abusing jPCT as a "blitting engine" only. There is no int[]-array-version of this method.
Using this method is quite to similar to using the Overlay-class. The difference is, that Overlay takes care of itself and that it has a real depth.

Parameters:
src - the texture that contains the source bitmap
srcX - the starting x-position in the source bitmap
srcY - the starting y-position in the source bitmap
destX - the starting x-position in the destination bitmap
destY - the starting y-position in the destination bitmap
sourceWidth - the width of the source region to copy
sourceHeight - the height of the source region to copy
destWidth - the width of the copied region in the destination bitmap
destHeight - the height of the copied region in the destination bitmap
transValue - the transparency value, -1 is none, 0 is highest transparency. Higher values mean less transparency.
additive - if true, the blending is additive, otherwise default
addColor - an additional color. If null, Color.WHITE is taken instead

blit

public void blit(int[] src,
                 int srcWidth,
                 int srcHeight,
                 int srcX,
                 int srcY,
                 int destX,
                 int destY,
                 int width,
                 int height,
                 boolean transparent)
Copies a part of a bitmap (taken from an int[] containing pixels in RGB-format and with no alpha) into the framebuffer. If you want your blitted content to lay on top of the rendered image, it has to be applied after calling update() on the buffer. Can be combined with getPixels() to achieve some special effects with the framebuffer.
Blitting requires that the current world has been rendered at least once into the framebuffer where the blitting should be applied to (for doing some intialization work). Usually, that shouldn't be a problem unless you are abusing jPCT as a "blitting engine" only. This method is very slow, because the int[] has to be converted and uploaded to the GPU every time. To avoid this in some cases, Config.glUseIgnorantBlits can be set to true...but one should be aware of the consequences. As a rule of thumb: If it's possible to avoid this method and use a texture-based-blit instead...do it!

Parameters:
src - the int-array that contains the source bitmap
srcWidth - the width of the source bitmap
srcHeight - the height of the source bitmap
srcX - the starting x-position in the source bitmap
srcY - the starting y-position in the source bitmap
destX - the starting x-position in the destination bitmap
destY - the starting y-position in the destination bitmap
width - the width of the region to copy
height - the height of the region to copy
transparent - black (or at least almost black) pixels won't be copied if this is set to TRANSPARENT_BLITTING. Any color-value which leads to a result of zero when "anded" with #f0f0f0 will be taken as black.
See Also:
getPixels(), TRANSPARENT_BLITTING, OPAQUE_BLITTING, Config.glUseIgnorantBlits

display

public void display()
Displays the rendered image.