FrameBuffer (jMonkeyEngine3)

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

class FrameBuffer.RenderBuffer
RenderBuffer represents either a texture or a buffer that will be rendered to.

Nested Classes
Modifier and Type	Class and Description
`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

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

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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addColorBuffer(Image.Format format)` Add a color buffer without a texture bound to it.
`void`	`addColorTexture(Texture2D tex)` Add a color texture to use for this framebuffer.
`void`	`addColorTexture(TextureArray tex, int layer)` Add a color texture array 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()`
`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)` 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(TextureArray tex, int layer)` Set the color texture array 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`	`setDepthTexture(TextureArray tex, int layer)`
`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, 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
  - 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(TextureArray tex,
                            int layer)
```
    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
```
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.
  - addColorBuffer
```
public void addColorBuffer(Image.Format format)
```
    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
```
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.
    
    See Also:
    
    addColorBuffer(com.jme3.texture.Image.Format)
  - addColorTexture
```
public void addColorTexture(TextureArray tex,
                            int layer)
```
    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
```
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.
  - setDepthTexture
```
public void setDepthTexture(TextureArray tex,
                            int layer)
```
  - 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 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
```
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
  - 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.

Class FrameBuffer

Nested Class Summary

Field Summary

Fields inherited from class com.jme3.util.NativeObject

Constructor Summary

Method Summary

Methods inherited from class com.jme3.util.NativeObject

Methods inherited from class java.lang.Object

Field Detail

SLOT_UNDEF

SLOT_DEPTH

SLOT_DEPTH_STENCIL

Constructor Detail

FrameBuffer

FrameBuffer

Method Detail

setDepthBuffer

setColorBuffer

setMultiTarget

isMultiTarget

setTargetIndex

getTargetIndex

setColorTexture

setColorTexture

setColorTexture

clearColorTargets

addColorBuffer

addColorTexture

addColorTexture

addColorTexture

setDepthTexture

setDepthTexture

getNumColorBuffers

getColorBuffer

getColorBuffer

getDepthBuffer

getHeight

getWidth

getSamples

toString

resetObject

deleteObject

createDestructableClone

getUniqueId

setSrgb

isSrgb