com.jme3.texture

Class FrameBuffer

java.lang.Object

com.jme3.util.NativeObject

com.jme3.texture.FrameBuffer

All Implemented Interfaces:

java.lang.Cloneable

public class FrameBuffer
extends NativeObject

FrameBuffers are rendering surfaces allowing off-screen rendering and render-to-texture functionality. Instead of the scene rendering to the screen, it is rendered into the FrameBuffer, the result can be either a texture or a buffer.

A FrameBuffer supports two methods of rendering, using a Texture or using a buffer. When using a texture, the result of the rendering will be rendered onto the texture, after which the texture can be placed on an object and rendered as if the texture was uploaded from disk. When using a buffer, the result is rendered onto a buffer located on the GPU, the data of this buffer is not accessible to the user. buffers are useful if one wishes to retrieve only the color content of the scene, but still desires depth testing (which requires a depth buffer). Buffers can be copied to other framebuffers including the main screen, by using Renderer.copyFrameBuffer(com.jme3.texture.FrameBuffer, com.jme3.texture.FrameBuffer, boolean, boolean). The content of a FrameBuffer.RenderBuffer can be retrieved by using Renderer.readFrameBuffer(com.jme3.texture.FrameBuffer, java.nio.ByteBuffer).

FrameBuffers have several attachment points, there are several color attachment points and a single depth attachment point. The color attachment points support image formats such as Image.Format.RGBA8, allowing rendering the color content of the scene. The depth attachment point requires a depth image format.

See Also:

Renderer.setFrameBuffer(com.jme3.texture.FrameBuffer)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FrameBuffer.FrameBufferBufferTarget
static class	FrameBuffer.FrameBufferTarget
static class	FrameBuffer.FrameBufferTextureTarget
static class	FrameBuffer.RenderBuffer RenderBuffer represents either a texture or a buffer that will be rendered to.

Field Summary

Fields

Modifier and Type	Field and Description
static int	SLOT_DEPTH
static int	SLOT_DEPTH_STENCIL
static int	SLOT_UNDEF

Fields inherited from class com.jme3.util.NativeObject

handleRef, id, INVALID_ID, objectManager, OBJTYPE_AUDIOBUFFER, OBJTYPE_AUDIOSTREAM, OBJTYPE_BO, OBJTYPE_FILTER, OBJTYPE_FRAMEBUFFER, OBJTYPE_SHADER, OBJTYPE_SHADERSOURCE, OBJTYPE_TEXTURE, OBJTYPE_VERTEXBUFFER, updateNeeded

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FrameBuffer(FrameBuffer src)
	FrameBuffer(int width, int height, int samples) Creates a new FrameBuffer with the given width, height, and number of samples.

Method Summary

Modifier and Type	Method and Description
void	addColorBuffer(Image.Format format) Deprecated. Use addColorTarget
void	addColorTarget(FrameBuffer.FrameBufferBufferTarget colorBuf)
void	addColorTarget(FrameBuffer.FrameBufferTextureTarget colorBuf)
void	addColorTexture(Texture2D tex) Deprecated. Use addColorTarget
void	addColorTexture(TextureArray tex, int layer) Deprecated. Use addColorTarget
void	addColorTexture(TextureCubeMap tex, TextureCubeMap.Face face) Deprecated. Use addColorTarget
void	clearColorTargets() Clears all color targets that were set or added previously.
NativeObject	createDestructableClone() Creates a shallow clone of this GL Object.
void	deleteObject(java.lang.Object rendererObject) Deletes the GL object from the GPU when it is no longer used.
FrameBuffer.RenderBuffer	getColorBuffer() Deprecated. Use getColorTarget()
FrameBuffer.RenderBuffer	getColorBuffer(int index) Deprecated. Use getColorTarget(int)
FrameBuffer.RenderBuffer	getColorTarget()
FrameBuffer.RenderBuffer	getColorTarget(int index)
FrameBuffer.RenderBuffer	getDepthBuffer() Deprecated. Use getDepthTarget()
FrameBuffer.RenderBuffer	getDepthTarget()
int	getHeight()
int	getNumColorBuffers() Deprecated. Use getNumColorTargets
int	getNumColorTargets()
int	getSamples()
int	getTargetIndex()
long	getUniqueId() Returns a unique ID for this NativeObject.
int	getWidth()
boolean	isMultiTarget()
boolean	isSrgb() Determines if this framebuffer contains SRGB data.
void	resetObject() Called when the GL context is restarted to reset all IDs.
void	setColorBuffer(Image.Format format) Deprecated. Use addColorTarget
void	setColorTexture(Texture2D tex) Deprecated. Use addColorTarget
void	setColorTexture(TextureArray tex, int layer) Deprecated. Use addColorTarget
void	setColorTexture(TextureCubeMap tex, TextureCubeMap.Face face) Deprecated. Use addColorTarget
void	setDepthBuffer(Image.Format format) Deprecated. Use setDepthTarget
void	setDepthTarget(FrameBuffer.FrameBufferBufferTarget depthBuf)
void	setDepthTarget(FrameBuffer.FrameBufferTextureTarget depthBuf)
void	setDepthTexture(Texture2D tex) Deprecated. Use setDepthTarget
void	setDepthTexture(TextureArray tex, int layer) Deprecated. Use setDepthTarget
void	setMultiTarget(boolean enabled) If enabled, any shaders rendering into this FrameBuffer will be able to write several results into the renderbuffers by using the gl_FragData array.
void	setSrgb(boolean srgb) Specifies that the color values stored in this framebuffer are in SRGB format.
void	setTargetIndex(int index) If MRT is not enabled (setMultiTarget(boolean) is false) then this specifies the color target to which the scene should be rendered.
java.lang.String	toString()

Methods inherited from class com.jme3.util.NativeObject

clearUpdateNeeded, clone, deleteNativeBuffers, dispose, getId, getWeakRef, isUpdateNeeded, setId, setUpdateNeeded

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SLOT_UNDEF

public static final int SLOT_UNDEF

See Also:

Constant Field Values

SLOT_DEPTH

public static final int SLOT_DEPTH

See Also:

Constant Field Values

SLOT_DEPTH_STENCIL

public static final int SLOT_DEPTH_STENCIL

See Also:

Constant Field Values

Constructor Detail

FrameBuffer

public FrameBuffer(int width,
                   int height,
                   int samples)

Creates a new FrameBuffer with the given width, height, and number of samples. If any textures are attached to this FrameBuffer, then they must have the same number of samples as given in this constructor.

Note that if the Renderer does not expose the Caps.NonPowerOfTwoTextures, then an exception will be thrown if the width and height arguments are not power of two.

Parameters:

width - The width to use

height - The height to use

samples - The number of samples to use for a multisampled framebuffer, or 1 if the framebuffer should be singlesampled.

Throws:

java.lang.IllegalArgumentException - If width or height are not positive.

FrameBuffer

protected FrameBuffer(FrameBuffer src)

Method Detail

addColorTarget

public void addColorTarget(FrameBuffer.FrameBufferBufferTarget colorBuf)

addColorTarget

public void addColorTarget(FrameBuffer.FrameBufferTextureTarget colorBuf)

setDepthTarget

public void setDepthTarget(FrameBuffer.FrameBufferBufferTarget depthBuf)

setDepthTarget

public void setDepthTarget(FrameBuffer.FrameBufferTextureTarget depthBuf)

getNumColorTargets

public int getNumColorTargets()

getColorTarget

public FrameBuffer.RenderBuffer getColorTarget(int index)

getColorTarget

public FrameBuffer.RenderBuffer getColorTarget()

getDepthTarget

public FrameBuffer.RenderBuffer getDepthTarget()

setDepthBuffer

@Deprecated
public void setDepthBuffer(Image.Format format)

Deprecated. Use setDepthTarget

Enables the use of a depth buffer for this FrameBuffer.

Parameters:

format - The format to use for the depth buffer.

Throws:

java.lang.IllegalArgumentException - If format is not a depth format.

setColorBuffer

@Deprecated
public void setColorBuffer(Image.Format format)

Deprecated. Use addColorTarget

Enables the use of a color buffer for this FrameBuffer.

Parameters:

format - The format to use for the color buffer.

Throws:

java.lang.IllegalArgumentException - If format is not a color format.

setMultiTarget

public void setMultiTarget(boolean enabled)

If enabled, any shaders rendering into this FrameBuffer will be able to write several results into the renderbuffers by using the gl_FragData array. Every slot in that array maps into a color buffer attached to this framebuffer.

Parameters:

enabled - True to enable MRT (multiple rendering targets).

isMultiTarget

public boolean isMultiTarget()

Returns:

True if MRT (multiple rendering targets) is enabled.

See Also:

setMultiTarget(boolean)

setTargetIndex

public void setTargetIndex(int index)

If MRT is not enabled (setMultiTarget(boolean) is false) then this specifies the color target to which the scene should be rendered.

By default the value is 0.

Parameters:

index - The color attachment index.

Throws:

java.lang.IllegalArgumentException - If index is negative or doesn't map to any attachment on this framebuffer.

getTargetIndex

public int getTargetIndex()

Returns:

The color target to which the scene should be rendered.

See Also:

setTargetIndex(int)

setColorTexture

@Deprecated
public void setColorTexture(Texture2D tex)

Deprecated. Use addColorTarget

Set the color texture to use for this framebuffer. This automatically clears all existing textures added previously with addColorTexture(com.jme3.texture.Texture2D) and adds this texture as the only target.

Parameters:

tex - The color texture to set.

setColorTexture

@Deprecated
public void setColorTexture(TextureArray tex,
                                        int layer)

Deprecated. Use addColorTarget

Set the color texture array to use for this framebuffer. This automatically clears all existing textures added previously with addColorTexture(com.jme3.texture.Texture2D) and adds this texture as the only target.

Parameters:

tex - The color texture array to set.

setColorTexture

@Deprecated
public void setColorTexture(TextureCubeMap tex,
                                        TextureCubeMap.Face face)

Deprecated. Use addColorTarget

Set the color texture to use for this framebuffer. This automatically clears all existing textures added previously with addColorTexture(com.jme3.texture.Texture2D) and adds this texture as the only target.

Parameters:

tex - The cube-map texture to set.

face - The face of the cube-map to render to.

clearColorTargets

public void clearColorTargets()

Clears all color targets that were set or added previously.

addColorBuffer

@Deprecated
public void addColorBuffer(Image.Format format)

Deprecated. Use addColorTarget

Add a color buffer without a texture bound to it. If MRT is enabled, then each subsequently added texture or buffer can be rendered to through a shader that writes to the array gl_FragData. If MRT is not enabled, then the index set with setTargetIndex(int) is rendered to by the shader.

Parameters:

format - the format of the color buffer

See Also:

addColorTexture(com.jme3.texture.Texture2D)

addColorTexture

@Deprecated
public void addColorTexture(Texture2D tex)

Deprecated. Use addColorTarget

Add a color texture to use for this framebuffer. If MRT is enabled, then each subsequently added texture can be rendered to through a shader that writes to the array gl_FragData. If MRT is not enabled, then the index set with setTargetIndex(int) is rendered to by the shader.

Parameters:

tex - The texture to add.

See Also:

addColorBuffer(com.jme3.texture.Image.Format)

addColorTexture

@Deprecated
public void addColorTexture(TextureArray tex,
                                        int layer)

Deprecated. Use addColorTarget

Add a color texture array to use for this framebuffer. If MRT is enabled, then each subsequently added texture can be rendered to through a shader that writes to the array gl_FragData. If MRT is not enabled, then the index set with setTargetIndex(int) is rendered to by the shader.

Parameters:

tex - The texture array to add.

addColorTexture

@Deprecated
public void addColorTexture(TextureCubeMap tex,
                                        TextureCubeMap.Face face)

Deprecated. Use addColorTarget

Add a color texture to use for this framebuffer. If MRT is enabled, then each subsequently added texture can be rendered to through a shader that writes to the array gl_FragData. If MRT is not enabled, then the index set with setTargetIndex(int) is rendered to by the shader.

Parameters:

tex - The cube-map texture to add.

face - The face of the cube-map to render to.

setDepthTexture

@Deprecated
public void setDepthTexture(Texture2D tex)

Deprecated. Use setDepthTarget

Set the depth texture to use for this framebuffer.

Parameters:

tex - The color texture to set.

setDepthTexture

@Deprecated
public void setDepthTexture(TextureArray tex,
                                        int layer)

Deprecated. Use setDepthTarget

Parameters:

tex -

layer -

getNumColorBuffers

@Deprecated
public int getNumColorBuffers()

Deprecated. Use getNumColorTargets

Returns:

The number of color buffers attached to this texture.

getColorBuffer

@Deprecated
public FrameBuffer.RenderBuffer getColorBuffer(int index)

Deprecated. Use getColorTarget(int)

Parameters:

index -

Returns:

The color buffer at the given index.

getColorBuffer

@Deprecated
public FrameBuffer.RenderBuffer getColorBuffer()

Deprecated. Use getColorTarget()

Returns:

The color buffer with the index set by setTargetIndex(int), or null if no color buffers are attached. If MRT is disabled, the first color buffer is returned.

getDepthBuffer

@Deprecated
public FrameBuffer.RenderBuffer getDepthBuffer()

Deprecated. Use getDepthTarget()

Returns:

The depth buffer attached to this FrameBuffer, or null if no depth buffer is attached

getHeight

public int getHeight()

Returns:

The height in pixels of this framebuffer.

getWidth

public int getWidth()

Returns:

The width in pixels of this framebuffer.

getSamples

public int getSamples()

Returns:

The number of samples when using a multisample framebuffer, or 1 if this is a singlesampled framebuffer.

toString

public java.lang.String toString()

Overrides:

toString in class NativeObject

resetObject

public void resetObject()

Description copied from class: NativeObject

Called when the GL context is restarted to reset all IDs. Prevents "white textures" on display restart.

Specified by:

resetObject in class NativeObject

deleteObject

public void deleteObject(java.lang.Object rendererObject)

Description copied from class: NativeObject

Deletes the GL object from the GPU when it is no longer used. Called automatically by the GL object manager.

Specified by:

deleteObject in class NativeObject

Parameters:

rendererObject - The renderer to be used to delete the object

createDestructableClone

public NativeObject createDestructableClone()

Description copied from class: NativeObject

Creates a shallow clone of this GL Object. The deleteObject method should be functional for this object.

Specified by:

createDestructableClone in class NativeObject

getUniqueId

public long getUniqueId()

Description copied from class: NativeObject

Returns a unique ID for this NativeObject. No other NativeObject shall have the same ID.

Specified by:

getUniqueId in class NativeObject

Returns:

unique ID for this NativeObject.

setSrgb

public void setSrgb(boolean srgb)

Specifies that the color values stored in this framebuffer are in SRGB format. The FrameBuffer must have an SRGB texture attached. The Renderer must expose the sRGB pipeline capability for this option to take any effect. Rendering operations performed on this framebuffer shall undergo a linear -> sRGB color space conversion when this flag is enabled. If blending is enabled, it will be performed in linear space by first decoding the stored sRGB pixel values into linear, combining with the shader result, and then converted back to sRGB upon being written into the framebuffer.

Parameters:

srgb - If the framebuffer color values should be stored in sRGB color space.

Throws:

java.lang.IllegalStateException - If the texture attached to this framebuffer is not sRGB.

isSrgb

public boolean isSrgb()

Determines if this framebuffer contains SRGB data.

Returns:

True if the framebuffer color values are in SRGB space, false if in linear space.