com.jme3.texture
Class FrameBuffer

java.lang.Object
  extended by com.jme3.util.NativeObject
      extended by 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). 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
 class FrameBuffer.RenderBuffer
          RenderBuffer represents either a texture or a buffer that will be rendered to.
 
Field Summary
 
Fields inherited from class com.jme3.util.NativeObject
handleRef, id, type, updateNeeded
 
Constructor Summary
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
 void addColorTexture(Texture2D tex)
          Add a color texture to use for this framebuffer.
 void addColorTexture(TextureCubeMap tex, TextureCubeMap.Face face)
          Add a color texture to use for this framebuffer.
 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()
           
 FrameBuffer.RenderBuffer getColorBuffer(int index)
           
 FrameBuffer.RenderBuffer getDepthBuffer()
           
 int getHeight()
           
 int getNumColorBuffers()
           
 int getSamples()
           
 int getTargetIndex()
           
 int getWidth()
           
 boolean isMultiTarget()
           
 void resetObject()
          Called when the GL context is restarted to reset all IDs.
 void setColorBuffer(Image.Format format)
          Enables the use of a color buffer for this FrameBuffer.
 void setColorTexture(Texture2D tex)
          Set the color texture to use for this framebuffer.
 void setColorTexture(TextureCubeMap tex, TextureCubeMap.Face face)
          Set the color texture to use for this framebuffer.
 void setDepthBuffer(Image.Format format)
          Enables the use of a depth buffer for this FrameBuffer.
 void setDepthTexture(Texture2D tex)
          Set the depth texture to use for this framebuffer.
 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 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, getId, isUpdateNeeded, setId, setUpdateNeeded
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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

setDepthBuffer

public void setDepthBuffer(Image.Format format)
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

public void setColorBuffer(Image.Format format)
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

public void setColorTexture(Texture2D tex)
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

public void setColorTexture(TextureCubeMap tex,
                            TextureCubeMap.Face face)
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.


addColorTexture

public void addColorTexture(Texture2D tex)
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.

addColorTexture

public void addColorTexture(TextureCubeMap tex,
                            TextureCubeMap.Face face)
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

public void setDepthTexture(Texture2D tex)
Set the depth texture to use for this framebuffer.

Parameters:
tex - The color texture to set.

getNumColorBuffers

public int getNumColorBuffers()
Returns:
The number of color buffers attached to this texture.

getColorBuffer

public FrameBuffer.RenderBuffer getColorBuffer(int index)
Parameters:
index -
Returns:
The color buffer at the given index.

getColorBuffer

public FrameBuffer.RenderBuffer getColorBuffer()
Returns:
The first color buffer attached to this FrameBuffer, or null if no color buffers are attached.

getDepthBuffer

public FrameBuffer.RenderBuffer getDepthBuffer()
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