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 could be displayed or modified even further using some post-processing. The FrameBuffer's constructor automatically distinguishes between JAVA2 and earlier versions. JAVA2 and higher will use a BufferedImage as FrameBuffer while JAVA1.1 will use a MemoryImageSource. When using support for OpenGL hardware rendering only, the image is not rendered into the FrameBuffer's internal pixel-array but directly into the video-RAM of the graphics card. Therefor, some methods within this class will execute quite slow if they have to access the VRAM. This will be mentioned in these methods.

See Also:

Serialized Form

Field Summary

static int	BLITTING_TARGET_BACK Blitting is done into the back buffer.
static int	BLITTING_TARGET_FRONT Blitting is done into the front buffer.
static boolean	BOUNDINGBOX_NOT_USED Don't use a 2D bounding box.
static boolean	BOUNDINGBOX_USED Use a 2D bounding box for speeding up blitting (only useful when the rendered scene doesn't cover the whole framebuffer)
static int	BUFFER_ACCESS_COMBINED Access the framebuffer in one way (default)...
static int	BUFFER_ACCESS_SPLITTED Access the framebuffer in another way)...
static int	BUFFEREDIMAGE The type of this FrameBuffer is a BufferedImage (JAVA2)
static int	MEMORYIMAGESOURCE The type of this FrameBuffer is a MemoryImageSource (JAVA1.1)
static boolean	OPAQUE_BLITTING 2D texture-blitting into the framebuffer is done by copying the source 1-to-1 into the destination bitmap
static int	SAMPLINGMODE_GL_AA_2X Use 2x anti aliasing when using the OpenGL renderer.
static int	SAMPLINGMODE_GL_AA_4X Use 4x anti aliasing when using the OpenGL renderer.
static int	SAMPLINGMODE_HARDWARE_ONLY A special sampling mode that indicates, that no software rendering will be used on this framebuffer.
static int	SAMPLINGMODE_NORMAL Normal sampling mode (1-to-1)
static int	SAMPLINGMODE_OGSS Use 2x2 oriented grid oversampling (FSAA using supersampling) for the software renderer.
static int	SAMPLINGMODE_OGSS_FAST Use 1.5x1.5 oriented grid oversampling (FSAA using supersampling) for the software renderer.
static int	SAMPLINGMODE_OGUS Use 0.5x0.5 oriented grid undersampling (to upsample an image rendered at a lower resolution)
static java.lang.String	SUPPORT_FOR_RGB_SCALING Use this to check if all the currently enabled renderers support RGB-scaling
static java.lang.String	SUPPORT_FOR_SHADOW_MAPPING Use this to check if all the currently enabled renderers support shadow mapping
static java.lang.Object	SYNCHRONIZER An Object to which jPCT synchronizes all critical calls to Display, Mouse and Keyboard from LWJGL to.
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(int x, int y, int oversample)
Creates a new framebuffer with a width of x and a height of y using the given samplingmode.

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, float srcX, float srcY, float destX, float destY, float width, float 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, float srcX, float srcY, float destX, float destY, float width, float height, boolean transparent) Copies a part of a bitmap (taken from a Texture in this case) into the framebuffer.
void	blit(Texture src, float srcX, float srcY, float destX, float destY, float sourceWidth, float sourceHeight, float destWidth, float 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, float srcX, float srcY, float destX, float destY, float sourceWidth, float sourceHeight, float destWidth, float destHeight, int transValue, boolean additive, java.awt.Color 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	blit(Texture src, float srcX, float srcY, float destX, float destY, float sourceWidth, float sourceHeight, float destWidth, float destHeight, int transValue, boolean additive, RGBColor addColor) Method to maintain compatibility with jPCT-AE.
void	clear() Clears the framebuffer, the optiZ-buffer, the hsr-buffer and the regular z-buffer if required.
void	clear(java.awt.Color col) Clears the framebuffer, the optiZ-buffer, the hsr-buffer and the regular z-buffer if required.
void	clear(int rgb) The same as clear(<Color>) but with an int-value instead of a color instance.
void	clearColorBufferOnly(java.awt.Color col) Clears only the color bufferr, not the depth buffer.
void	clearZBufferOnly() Clears only the ZBuffer, not the color buffer.
void	disableRenderer(int renderer) Disables a renderer for this framebuffer.
void	display() The same as displayGLOnly.
void	display(java.awt.Graphics g) Displays the output Image onto the component with the given Graphics context.
void	display(java.awt.Graphics g, int yOffset) Displays the output Image onto the component with the given Graphics context.
void	display(java.awt.Graphics g, int xOffset, int yOffset) Displays the output Image onto the component with the given Graphics context.
void	displayGLOnly() Displays the output image produced by OpenGL compatible hardware if OpenGL rendering is in use.
void	dispose() Has to be called before this FrameBuffer won't be used anymore to do some clean up work.
java.awt.Canvas	enableGLCanvasRenderer() Enables an OpenGL renderer that will render into a canvas.
void	enableRenderer(int renderer) Enables a renderer (OpenGL or software) in OpenGL-lighting mode.
void	enableRenderer(int renderer, int mode) Enables a renderer (OpenGL or software) in the desired mode.
void	flush() Does nothing.
void	flushBlittingPipeline() Flushes the blitting pipeline by executing the buffered blits.
java.awt.Graphics	getGraphics() Returns the Graphics object of the output buffer to allow the use of JAVA's standard graphic methods on the rendered image (like drawString).
int	getHeight() The same as getOutputHeight().
java.lang.Long	getID() Returns a unique ID for this FrameBuffer.
java.lang.Object	getLock() Returns the lock object for the frame buffer.
int	getMaxTextureSize() Gets the maximum texture size that the current renderers support.
float	getMiddleX() Returns the x-coord of the midpoint of the framebuffer.
float	getMiddleY() Returns the y-coord of the midpoint of the framebuffer.
java.awt.Image	getOutputBuffer() Returns the Image that represents the output-buffer of the framebuffer.
int	getOutputHeight() Returns the height of the framebuffer.
int	getOutputWidth() Returns the width of the framebuffer.
int[]	getPixels() Returns the raw pixel-data.
int	getSamplingMode() Returns the used sampling mode for this framebuffer.
int	getType() Returns the type of this FrameBuffer.
static VideoMode[]	getVideoModes(int renderer) Static method to get the video modes a renderer (i.e. the hardware it's running on) supports.
int	getWidth() The same as getOutputWidth().
boolean	isInitialized() Checks if the FrameBuffer and all its enabled renderers have been initialized correctly.
void	optimizeBufferAccess() This method tries to pick the most optimal buffer access mode for the system jPCT is currently running on.
void	refresh() Forces the framebuffer to update its content with what's in the pixels-array.
void	removeAllPostProcessors() Removes all post processors from the framebuffer.
void	removeClippingPlane(int number) Removes an additional clipping plane.
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	setBlittingTarget(int target) Sets the blitting target to either the front (default) or the back buffer.
void	setBoundingBoxMode(boolean bmode) Sets the bounding box mode for the framebuffer.
void	setBufferAccess(int mode) When using the software renderer, the framebuffer can be accessed in different ways.
void	setClippingPlane(int number, Plane plane) Sets an additional clipping plane.
void	setPaintListener(IPaintListener listener) Adds a listener to all currently used renderers.
void	setPaintListenerState(boolean isActive) Sets the state of the paint listener.
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.
boolean	supports(java.lang.String feature) Checks if a feature is supported by all the renderers of this framebuffer.
void	sync() Does nothing.
void	update() Updates the output buffer of the framebuffer with the new data from the backbuffer.
boolean	usesRenderer(int renderer) Tests if the given renderer is used by this framebuffer.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MEMORYIMAGESOURCE

public static final int MEMORYIMAGESOURCE

The type of this FrameBuffer is a MemoryImageSource (JAVA1.1)

See Also:

Constant Field Values

BUFFEREDIMAGE

public static final int BUFFEREDIMAGE

The type of this FrameBuffer is a BufferedImage (JAVA2)

See Also:

Constant Field Values

SAMPLINGMODE_GL_AA_4X

public static final int SAMPLINGMODE_GL_AA_4X

Use 4x anti aliasing when using the OpenGL renderer. Don't use this on a framebuffer that's supposed to be used by the software renderer.

See Also:

Constant Field Values

SAMPLINGMODE_GL_AA_2X

public static final int SAMPLINGMODE_GL_AA_2X

Use 2x anti aliasing when using the OpenGL renderer. Don't use this on a framebuffer that's supposed to be used by the software renderer.

See Also:

Constant Field Values

SAMPLINGMODE_OGSS

public static final int SAMPLINGMODE_OGSS

Use 2x2 oriented grid oversampling (FSAA using supersampling) for the software renderer. This mode shouldn't be used for the OpenGL renderer.

See Also:

Constant Field Values

SAMPLINGMODE_OGSS_FAST

public static final int SAMPLINGMODE_OGSS_FAST

Use 1.5x1.5 oriented grid oversampling (FSAA using supersampling) for the software renderer. This mode shouldn't be used for the OpenGL renderer. This mode is faster then "normal" 2x2 oversampling, but image quality is a bit lower.

See Also:

Constant Field Values

SAMPLINGMODE_OGUS

public static final int SAMPLINGMODE_OGUS

Use 0.5x0.5 oriented grid undersampling (to upsample an image rendered at a lower resolution)

See Also:

Constant Field Values

SAMPLINGMODE_NORMAL

public static final int SAMPLINGMODE_NORMAL

Normal sampling mode (1-to-1)

See Also:

Constant Field Values

SAMPLINGMODE_HARDWARE_ONLY

public static final int SAMPLINGMODE_HARDWARE_ONLY

A special sampling mode that indicates, that no software rendering will be used on this framebuffer. OpenGL support will work with any other sampling mode though (but the sampling modes may not affect the OpenGL output).

See Also:

Constant Field Values

BOUNDINGBOX_USED

public static final boolean BOUNDINGBOX_USED

Use a 2D bounding box for speeding up blitting (only useful when the rendered scene doesn't cover the whole framebuffer)

See Also:

Constant Field Values

BOUNDINGBOX_NOT_USED

public static final boolean BOUNDINGBOX_NOT_USED

Don't use a 2D bounding box. This mode should be used for indoor rendering.

See Also:

Constant Field Values

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

SUPPORT_FOR_RGB_SCALING

public static final java.lang.String SUPPORT_FOR_RGB_SCALING

Use this to check if all the currently enabled renderers support RGB-scaling

See Also:

Lights.setRGBScale(int), supports(java.lang.String), Constant Field Values

SUPPORT_FOR_SHADOW_MAPPING

public static final java.lang.String SUPPORT_FOR_SHADOW_MAPPING

Use this to check if all the currently enabled renderers support shadow mapping

See Also:

supports(java.lang.String), Constant Field Values

BUFFER_ACCESS_COMBINED

public static final int BUFFER_ACCESS_COMBINED

Access the framebuffer in one way (default)...

See Also:

setBufferAccess(int), Constant Field Values

BUFFER_ACCESS_SPLITTED

public static final int BUFFER_ACCESS_SPLITTED

Access the framebuffer in another way)...

See Also:

setBufferAccess(int), Constant Field Values

BLITTING_TARGET_FRONT

public static final int BLITTING_TARGET_FRONT

Blitting is done into the front buffer. This is default

See Also:

Constant Field Values

BLITTING_TARGET_BACK

public static final int BLITTING_TARGET_BACK

Blitting is done into the back buffer. This only affects blitting when the software renderer is used with over-/undersampling. For any other configuration, is the same as BLITTING_TARGET_FRONT.

See Also:

Constant Field Values

SYNCHRONIZER

public static final java.lang.Object SYNCHRONIZER

An Object to which jPCT synchronizes all critical calls to Display, Mouse and Keyboard from LWJGL to. These classes are not thread safe, therefor it's required to avoid creating the Keyboard while creating the display (for example). If you ever do such things from other threads or are using jPCT's AWTGLRenderer or its build-in multithreading support, make sure to synchronize to this object when you are calling critical Keyboard-, Mouse- or Diplay-methods.
Of course, all this only applies to the hardware renderers.

Constructor Detail

FrameBuffer

public FrameBuffer(int x,
                   int y,
                   int oversample)

Creates a new framebuffer with a width of x and a height of y using the given samplingmode. For software rendering, the framebuffer can be of any size. For OpenGL, a size supported by the OpenGL compatible hardware one is using is required.

Parameters:

x - the width of the framebuffer

y - the height of the framebuffer

oversample - the samplingmode

See Also:

SAMPLINGMODE_OGSS, SAMPLINGMODE_OGSS_FAST, SAMPLINGMODE_OGUS, SAMPLINGMODE_NORMAL, SAMPLINGMODE_HARDWARE_ONLY, SAMPLINGMODE_GL_AA_2X, SAMPLINGMODE_GL_AA_4X, getVideoModes(int)

Method Detail

getID

public java.lang.Long getID()

Returns a unique ID for this FrameBuffer.

Returns:

Long the ID

getVideoModes

public static VideoMode[] getVideoModes(int renderer)

Static method to get the video modes a renderer (i.e. the hardware it's running on) supports. This is useful for initializing the OpenGL renderer and the FrameBuffer. The z-buffer depth of the returned modes is taken from the z-buffer setting in Config and NOT from the driver of the video card, because the used OpenGL binding doesn't return this value anymore...so it's basically 'guessing' here... The software renderer doesn't have video modes, so it will return an empty array.

Parameters:

renderer - the renderer (only IRenderer.RENDERER_OPENGL makes sense at the moment)

Returns:

the supported video modes

See Also:

IRenderer, Config.glColorDepth, Config.glZBufferDepth, Config.glRefresh

isInitialized

public boolean isInitialized()

Checks if the FrameBuffer and all its enabled renderers have been initialized correctly. This is useful to check if OpenGL support has been enabled succesfully and if the desired videomode has been set.
When using the AWTGLRenderer, this method will return false until the first drawing (attempt) took place.

Returns:

true, if the FrameBuffer is fine. Otherwise false.

setBlittingTarget

public void setBlittingTarget(int target)

Sets the blitting target to either the front (default) or the back buffer. This is required to allow blitting into the background of an over- or undersampled frame buffer. Any other configuration doesn't need this.

Parameters:

target - the blitting target

See Also:

BLITTING_TARGET_FRONT, BLITTING_TARGET_BACK

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

enableRenderer

public void enableRenderer(int renderer)

Enables a renderer (OpenGL or software) in OpenGL-lighting mode. OpenGL-lighting mode is the recommended mode for the software as well as for the hardware renderer. However, jPCT constructs every new FrameBuffer as software/legacy for compatibility reasons. It is possible to use the software renderer as well as the OpenGL renderer on a single framebuffer at the same time, but it's not advised to do so, because this will disable some optimizations that are else made in case OpenGL is used (like T&L optimizations and triangle strips). To enable OpenGL without supporting the software renderer, the software renderer has to be disabled after enabling OpenGL.

Important: NEVER change the renderer from outside the thread that is doing the rendering if you intend to use the OpenGL renderer, because this will cause your application to crash. This is a "feature" of LWJGL, so there's nothing jPCT can do about it.

Parameters:

renderer - the renderer that should be used to render this framebuffer

See Also:

disableRenderer(int), enableRenderer(int, int), IRenderer

enableGLCanvasRenderer

public java.awt.Canvas enableGLCanvasRenderer()

Enables an OpenGL renderer that will render into a canvas. For compatibility reasons, jPCT constructs every new FrameBuffer as software/legacy. It is possible to use the software renderer as well as the OpenGL renderer on a single framebuffer at the same time, but it's not advised to do so, because this will disable some optimizations that are else made in case OpenGL is used (like T&L optimizations and triangle strips). To enable OpenGL without supporting the software renderer, the software renderer has to be disabled after enabling OpenGL.
Using this renderer affects the behaviour of getPixels() and supports(), which will only return after the Canvas has been repainted. If this never happens for whatever reason, they'll never return!

Returns:

the Canvas

See Also:

disableRenderer(int), enableRenderer(int), enableGLCanvasRenderer(), AWTGLRenderer

enableRenderer

public void enableRenderer(int renderer,
                           int mode)

Enables a renderer (OpenGL or software) in the desired mode. For compatibility reasons, jPCT constructs every new FrameBuffer as software/opengl-alike. It is possible to use the software renderer as well as the OpenGL renderer on a single framebuffer at the same time, but it's not advised to do so, because this will disable some optimizations that are else made in case OpenGL is used (like T&L optimizations and triangle strips). To enable OpenGL without supporting the software renderer, the software renderer has to be disabled after enabling OpenGL.

Important: NEVER change the renderer from outside the thread that is doing the rendering if you intend to use the OpenGL renderer, because this will cause your application to crash. This is a "feature" of LWJGL, so there's nothing jPCT can do about it.

Parameters:

renderer - the renderer that should be used to render this framebuffer

mode - the mode the renderer should use

See Also:

disableRenderer(int), enableRenderer(int), IRenderer

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, when FBO are not used/available. Rendering into a texture can be slow on some hardware like Intel onboard chipsets.
While the software renderer do support render targets, it can't run a post processor on them.
Make sure that the texture you are using as render target doesn't use mip mapping.
While possible, it's not recommended to blit into a render target.

Parameters:

texID - the ID of the texture to render into.

See Also:

Config.glUseFBO, Config.glFlipRenderTargets

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. The software renderer doesn't support this border and ignores it.
Make sure that the texture you are using as render target doesn't use mip mapping.
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.

See Also:

Config.glUseFBO, Config.glFlipRenderTargets

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, when FBO are not used/available. Rendering into a texture can be slow on some hardware like Intel onboard chipsets. While the software renderer do support render targets, it can't run a post processor on them.
Make sure that the texture you are using as render target doesn't use mip mapping.
While possible, it's not recommended to blit into a render target.

Parameters:

tex - the texture to render into

See Also:

Config.glUseFBO, Config.glFlipRenderTargets

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, when FBO are not used/available. Rendering into a texture can be slow on some hardware like Intel onboard chipsets. While the software renderer do support render targets, it can't run a post processor on them. A texture assigned as a render target will automatically treated as non-mipmapped. This is a special purpose version of this method that allows to define a border that isn't affected by the rendering. The software renderer doesn't support this border and ignores it.

While possible, it's not recommended to blit into a render target.

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.

See Also:

Config.glUseFBO, Config.glFlipRenderTargets

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 and may or may not support hardware and software renderer. 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 all currently used renderers. 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

setPaintListenerState

public void setPaintListenerState(boolean isActive)

Sets the state of the paint listener. If set to false, it won't be called even if assigned. The setting applies to all paint listeners on the currently acitve renderers. If you change a renderer, the new one will start with an active state regardless of this setting.

Parameters:

isActive - is it active or sleeping?

disableRenderer

public void disableRenderer(int renderer)

Disables a renderer for this framebuffer. Disabling all renderers doesn't make much sense, so usually one will disable the renderer that is not in use at the moment (software if OpenGL is used and vice versa). After enabling OpenGL, it is advised to disable the software renderer. While it is possible to enable both, the software renderer will disable some optimization that may be used in case of "OpenGL only" (like T&L optimizations and triangle strips).

Parameters:

renderer - the renderer

See Also:

IRenderer

dispose

public void dispose()

Has to 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. Java2 would allow to use a weak reference to handle this better, but jPCT is 1.1 compatible, so...

usesRenderer

public boolean usesRenderer(int renderer)

Tests if the given renderer is used by this framebuffer.

Parameters:

renderer - the renderer to test

Returns:

true if it's in use, otherwise false

See Also:

IRenderer

getMaxTextureSize

public int getMaxTextureSize()

Gets the maximum texture size that the current renderers support.

Returns:

the size

supports

public boolean supports(java.lang.String feature)

Checks if a feature is supported by all the renderers of this framebuffer.

Parameters:

feature - the feature that may be supported

Returns:

is the feature supported

See Also:

SUPPORT_FOR_RGB_SCALING, SUPPORT_FOR_SHADOW_MAPPING

getSamplingMode

public int getSamplingMode()

Returns the used sampling mode for this framebuffer.

Returns:

the sampling mode

See Also:

SAMPLINGMODE_NORMAL, SAMPLINGMODE_OGSS, SAMPLINGMODE_OGSS_FAST, SAMPLINGMODE_OGUS, SAMPLINGMODE_HARDWARE_ONLY, SAMPLINGMODE_GL_AA_2X, SAMPLINGMODE_GL_AA_4X

getOutputWidth

public int getOutputWidth()

Returns the width of the framebuffer. This method is called getOutputWidth(), because it returns the actual width used for output which is not always the internally used width.

Returns:

the width of the framebuffer

getOutputHeight

public int getOutputHeight()

Returns the height of the framebuffer. This method is called getOutputHeight(), because it returns the height actual used for output which is not always the internally used height.

Returns:

the height of the framebuffer

getHeight

public int getHeight()

The same as getOutputHeight(). Mainly here to increase compatibility with jPCT-AE.

Returns:

the height

getWidth

public int getWidth()

The same as getOutputWidth(). Mainly here to increase compatibility with jPCT-AE.

Returns:

the width

getMiddleX

public float getMiddleX()

Returns the x-coord of the midpoint of the framebuffer. This value represents the internally used width/2.

Returns:

the x-coord

getMiddleY

public float getMiddleY()

Returns the y-coord of the midpoint of the framebuffer. This value represents the internally used height/2.

Returns:

the y-coord

setBoundingBoxMode

public void setBoundingBoxMode(boolean bmode)

Sets the bounding box mode for the framebuffer. This has nothing to do with 3d bounding boxes. The framebuffer's bounding box may help to speed up blitting when parts of the framebuffer remain empty in a scene. It's rather useless when doing indoor rendering. Default is BOUNDINGBOX_USED. The bounding box is (apart from this setting) only used if the framebuffer works with an MemoryImageSource. If it uses BufferedImage (for JAVA2 or higher) and/or OpenGL support, the bounding box won't be used at all.

Parameters:

bmode - the bounding box mode

See Also:

BOUNDINGBOX_NOT_USED, BOUNDINGBOX_USED

clear

public void clear()

Clears the framebuffer, the optiZ-buffer, the hsr-buffer and the regular z-buffer if required. Depending on the used configuration, not all of these steps are required.

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.

clearColorBufferOnly

public void clearColorBufferOnly(java.awt.Color col)

Clears only the color bufferr, not the depth buffer.

Parameters:

col - the fill color

clear

public void clear(java.awt.Color col)

Clears the framebuffer, the optiZ-buffer, the hsr-buffer and the regular z-buffer if required. Depending on the used configuration, not all of these steps are required. Addionally, the framebuffer is filled with the given color.

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

update

public void update()

Updates the output buffer of the framebuffer with the new data from the backbuffer. This method should be called before actually displaying the rendered image to make sure that the latest changes to the image are recognized. Depending on the configuration, some post-processing may take place here too.

setBufferAccess

public void setBufferAccess(int mode)

When using the software renderer, the framebuffer can be accessed in different ways. One is faster on one cpu/VM while the other may be faster on another one. You may want to play around with this setting to get the best possible performance on your system.

Parameters:

mode - the buffer access mode

See Also:

optimizeBufferAccess(), BUFFER_ACCESS_COMBINED, BUFFER_ACCESS_SPLITTED

optimizeBufferAccess

public void optimizeBufferAccess()

This method tries to pick the most optimal buffer access mode for the system jPCT is currently running on. This method will run for a second and sets the buffer mode to the fastest possible based on that measurement.
There are two problems with this: Hotspot may interfere and renders the measurement useless and some VMs on some machines (like the 1.4.2 on a P4HT) will start fast with method A but performance will drop after some seconds (for whatever reason) and suddenly, method B would be (much!) faster. This bug in some VMs (i assume that it is one) is the reason why this method exists at all.
This method is useful for software rendering only.

See Also:

setBufferAccess(int)

getOutputBuffer

public java.awt.Image getOutputBuffer()

Returns the Image that represents the output-buffer of the framebuffer. This could be used for further processing, displaying etc. It is meant as an alternative to display(). One don't have to get this image from the framebuffer every frame as it remains the same instance as long as the framebuffer instance exists.
When using OpenGL only, this method is very slow because it requires reads from VRAM. When using OpenGL and software rendering together (this is not advised, but it's possible), this method returns the software rendered buffer as if OpenGL wouldn't be used.

Returns:

the output image

See Also:

display(java.awt.Graphics g)

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. If you want to modify this array directly in your code (to apply some post-processing for example) keep two things in mind: This is ugly (but who cares...) and make sure to call refresh() afterwards. The returned array contains the pixel-data in RGB-format and with no alpha information.
When using OpenGL only, 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. When using OpenGL and software rendering together (this is not advised, but it's possible), this method returns the software rendered pixel-data as if OpenGL wouldn't be used.

Returns:

the pixels-array

See Also:

update(), refresh(), #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)

refresh

public void refresh()

Forces the framebuffer to update its content with what's in the pixels-array. This can be used to modify the framebuffer's content "from the outside". If you are not modifying the pixels-array in your code, there's no need to call this method.
Currently, this method works only when software rendering is being used.

See Also:

getPixels()

resize

public void resize(int width,
                   int height)

Does a resize of the FrameBuffer in case that the output window's size has changed. This isn't supported by the software renderer ATM and will be silently ignored if called for it.

Parameters:

width - the new width

height - the new height

getLock

public java.lang.Object getLock()

Returns the lock object for the frame buffer. When using a multi threaded renderer (like the AWTGLRenderer) in combination with dynamically compiled objects, it is advised to synchronize changes to the object's mesh data and/or texture data to this object to avoid to render inbetween states of the changes.
If this is called on a frame buffer using a single threaded renderer, it will return an Object too and you can still synchronize on it...just no other code inside jPCT will.

Returns:

the lock object

getGraphics

public java.awt.Graphics getGraphics()

Returns the Graphics object of the output buffer to allow the use of JAVA's standard graphic methods on the rendered image (like drawString). This works only for BufferedImage (using JAVA1.2 or higher) but not for the MemoryImageSource that is used for JAVA1.1. In this case, null will be returned. When using OpenGL support, this value is rather meaningless (but still valid).

Returns:

the Graphics object (or null for MemoryImageSource)

getType

public int getType()

Returns the type of this FrameBuffer. This value doesn't reflect the fact that OpenGL is used or not.

Returns:

the type

See Also:

MEMORYIMAGESOURCE, BUFFEREDIMAGE

blit

public void blit(Texture src,
                 float srcX,
                 float srcY,
                 float destX,
                 float destY,
                 float width,
                 float 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 in OpenGL mode 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. When using OpenGL, 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.
Some graphics cards/drivers are having problems when blitting using a 16bit z-buffer (albeit the z-buffer is not used for blitting). Have a look at Config.glFixedBlitting for a workaround.

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.

See Also:

TRANSPARENT_BLITTING, OPAQUE_BLITTING, Config.glFixedBlitting

blit

public void blit(Texture src,
                 float srcX,
                 float srcY,
                 float destX,
                 float destY,
                 float sourceWidth,
                 float sourceHeight,
                 float destWidth,
                 float 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. 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 in OpenGL mode 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. In fact, using this method on a software rendered framebuffer results in an Overlay being used internally. The difference is, that Overlay takes care of itself and that it has a real depth.
Some graphics cards/drivers are having problems when blitting using a 16bit z-buffer (albeit the z-buffer is not used for blitting). Have a look at Config.glFixedBlitting for a workaround.

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

See Also:

Config.glFixedBlitting

blit

public void blit(Texture src,
                 float srcX,
                 float srcY,
                 float destX,
                 float destY,
                 float sourceWidth,
                 float sourceHeight,
                 float destWidth,
                 float destHeight,
                 int transValue,
                 boolean additive,
                 java.awt.Color 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 in OpenGL mode 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. In fact, using this method on a software rendered framebuffer results in an Overlay being used internally. The difference is, that Overlay takes care of itself and that it has a real depth.
Some graphics cards/drivers are having problems when blitting using a 16bit z-buffer (albeit the z-buffer is not used for blitting). Have a look at Config.glFixedBlitting for a workaround.

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

See Also:

Config.glFixedBlitting

blit

public void blit(Texture src,
                 float srcX,
                 float srcY,
                 float destX,
                 float destY,
                 float sourceWidth,
                 float sourceHeight,
                 float destWidth,
                 float destHeight,
                 int transValue,
                 boolean additive,
                 RGBColor addColor)

Method to maintain compatibility with jPCT-AE. Functional identical to the variant that takes java.awt.Color instead of RGBColor.

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, RGBColor.WHITE is taken instead

blit

public void blit(int[] src,
                 int srcWidth,
                 int srcHeight,
                 float srcX,
                 float srcY,
                 float destX,
                 float destY,
                 float width,
                 float 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 in OpenGL mode 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. When in OpenGL-mode, this method is very slow, because the int[] has to be converted and uploaded to the graphics card 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!
Some graphics cards/drivers are having problems when blitting using a 16bit z-buffer (albeit the z-buffer is not used for blitting). Have a look at Config.glFixedBlitting for a workaround.

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, Config.glFixedBlitting

display

public void display(java.awt.Graphics g)

Displays the output Image onto the component with the given Graphics context. If one wants to have further control about the drawing, getOutputBuffer() can be used instead.

Parameters:

g - the Graphics context of the compontent onto which the Image should be drawn (ignored when using OpenGL only)

See Also:

getOutputBuffer()

display

public void display(java.awt.Graphics g,
                    int yOffset)

Displays the output Image onto the component with the given Graphics context. If one wants to have further control about the drawing, getOutputBuffer() can be used instead.

Parameters:

g - the Graphics context of the compontent onto which the Image should be drawn (ignored when using OpenGL only)

yOffset - the offset in y-direction (ignored when using OpenGL)

See Also:

getOutputBuffer()

display

public void display(java.awt.Graphics g,
                    int xOffset,
                    int yOffset)

Displays the output Image onto the component with the given Graphics context. If one wants to have further control about the drawing, getOutputBuffer() can be used instead.

Parameters:

g - the Graphics context of the compontent onto which the Image should be drawn (ignored when using OpenGL only)

xOffset - the offset in x-direction (ignored when using OpenGL)

yOffset - the offset in y-direction (ignored when using OpenGL)

See Also:

getOutputBuffer()

displayGLOnly

public void displayGLOnly()

Displays the output image produced by OpenGL compatible hardware if OpenGL rendering is in use. If a software renderer is enabled, this method will print out a warning message only. It's not required to display the OpenGL rendered image by using this method, the normal display()-method will work too, but the Graphics parameter will be ignored in this case (can even be null).

display

public void display()

The same as displayGLOnly. This method exists for compatibility with jPCT-AE.

setClippingPlane

public void setClippingPlane(int number,
                             Plane plane)

Sets an additional clipping plane. This will show an effect only if a hardware renderer has been enabled. The plane has to be defined in camera space.

Parameters:

number - the number of the clipping plane (0..5)

plane - the plane

removeClippingPlane

public void removeClippingPlane(int number)

Removes an additional clipping plane.

Parameters:

number - the number of the plane

sync

public void sync()

Does nothing. This method exists only for increased compatibility with jPCT-AE.

flush

public void flush()

Does nothing. This method exists only for increased compatibility with jPCT-AE.

flushBlittingPipeline

public void flushBlittingPipeline()

Flushes the blitting pipeline by executing the buffered blits. This also resets the blitting shader in case one has been set.