com.threed.jpct
Class FrameBuffer

java.lang.Object
  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 can 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.

FrameBuffer(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) 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	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(int rgb) The same as clear(<Color>) but with an int-value instead of a color instance.
void	clear(RGBColor col) Clears the framebuffer with the given color.
void	clearColorBufferOnly(RGBColor col) Clears only the color bufferr, not the depth buffer.
void	clearZBufferOnly() Clears only the ZBuffer, not the color buffer.
void	compileShader(GLSLShader shader, java.util.List<VertexAttributes> attribs) Compiles the shader and processes it's additional vertex attributes, if those are used within this shader.
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	flush() Flushes the render pipeline.
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	getMaxTextureSize() Gets the maximum texture size that the hardware supports.
int	getOpenGLMajorVersion() Returns the major version of OpenGL that this FrameBuffer uses.
int[]	getPixels() Returns the raw pixel-data.
int[]	getPixels(int[] toFill) 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	resize(int width, int height) Does a resize of the FrameBuffer in case that the output window's size has changed.
void	runPostProcessors() Runs all post processors that have been added to this framebuffer.
void	setBlittingShader(GLSLShader shader) Sets a shader that should be used for blitting instead of the fixed function pipeline.
void	setDepthMapParameters(float nearPlane, float farPlane, float bias) Sets the parameters that should be used for near and far plane as well as for bias when rendering into a shadow map.
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.
void	setVirtualDimensions(int width, int height) This has a meaning only if a render target has been set.
void	sync() Synchronizes GPU and CPU and flushes the render pipeline..

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. The created buffer will be accessed by OpenGL ES 1.0/1.1. Make sure that your OpenGL context is 1.x before using this.

Parameters:

glContext - a valid gl context

x - the width of the framebuffer

y - the height of the framebuffer

FrameBuffer

public FrameBuffer(int x,
                   int y)

Creates a new framebuffer with a width of x and a height of y. This constructor is for initializing the OpenGL ES2.0 pipeline. Make sure that your OpenGL context is 2.0 before using this.

Parameters:

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

getOpenGLMajorVersion

public int getOpenGLMajorVersion()

Returns the major version of OpenGL that this FrameBuffer uses.

Returns:

1 or 2

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.
While possible, it's not recommended to blit into a render target.

Parameters:

texID - the ID of the texture to render into.

setDepthMapParameters

public void setDepthMapParameters(float nearPlane,
                                  float farPlane,
                                  float bias)

Sets the parameters that should be used for near and far plane as well as for bias when rendering into a shadow map. If you set -1 for one of the planes, the current World's values will be taken instead. If you are using the ShadowHelper class to setup your shadows, there's no need to call this method directly.

Parameters:

nearPlane - the depth of the near plane

farPlane - the depth of the far plane

bias - the bias (i.e. the depth offset, default is 0.0008);

getMaxTextureSize

public int getMaxTextureSize()

Gets the maximum texture size that the hardware supports.

Returns:

the size

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.
While possible, it's not recommended to blit into a render target.

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.
While possible, it's not recommended to blit into a render target.
If possible, use OpenGL ES 2.0 mode when using this, because it's much more compatible.

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.
While possible, it's not recommended to blit into a render target.
If possible, use OpenGL ES 2.0 mode when using this, because it's much more compatible.

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.

setVirtualDimensions

public void setVirtualDimensions(int width,
                                 int height)

This has a meaning only if a render target has been set. By default the fov calculations will use the render target's dimensions. With this, you can set some other dimensions.

Parameters:

width - the virtual width of the render target

height - the virtual height of the render target

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

setBlittingShader

public void setBlittingShader(GLSLShader shader)

Sets a shader that should be used for blitting instead of the fixed function pipeline.

Parameters:

shader - the shader, default is null

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.
You should try to call this method when the gl context with which the FrameBuffer instance has been created is still active. Otherwise, you might not free resources that are bound to another context.

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

resize

public void resize(int width,
                   int height)

Does a resize of the FrameBuffer in case that the output window's size has changed.

Parameters:

width - the new width

height - the new height

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.

clearColorBufferOnly

public void clearColorBufferOnly(RGBColor col)

Clears only the color bufferr, not the depth buffer.

Parameters:

col - the fill color

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

clear

public void clear(int rgb)

The same as clear(<Color>) but with an int-value instead of a color instance.

Parameters:

rgb - 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)

getPixels

public int[] getPixels(int[] toFill)

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.
This method takes an array to fill. The array has to have to proper size (i.e. framebuffer's height*width).

Parameters:

toFill - the array to fill

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. 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. 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(Texture src,
                 int srcX,
                 int srcY,
                 int destX,
                 int destY,
                 int sourceWidth,
                 int sourceHeight,
                 int destWidth,
                 int destHeight,
                 int transValue,
                 boolean additive)

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. 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

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.
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

compileShader

public void compileShader(GLSLShader shader,
                          java.util.List<VertexAttributes> attribs)

Compiles the shader and processes it's additional vertex attributes, if those are used within this shader. By default, this happens at runtime anyway and you don't have to call this method. You can however call it, if you want to compile the shader before the actual rendering starts.
Make sure that this happen in the thread with the current gl context, or your app may crash.

display

public void display()

Displays the rendered image.

sync

public void sync()

Synchronizes GPU and CPU and flushes the render pipeline.. This isn't needed (and not even wanted) in most cases.

flush

public void flush()

Flushes the render pipeline. This isn't needed (and not even wanted) in most cases.