Package com.jme3.texture

Class FrameBuffer

java.lang.Object
com.jme3.util.NativeObject
com.jme3.texture.FrameBuffer
All Implemented Interfaces:
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:

  • Field Details

  • Constructor Details

    • 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 single-sampled.
      Throws:
      IllegalArgumentException - If width or height are not positive.

    • FrameBuffer

      protected FrameBuffer(FrameBuffer src)

  • Method Details

    • addColorTarget

      public void addColorTarget(FrameBuffer.FrameBufferBufferTarget colorBuf)

    • addColorTarget

      public void addColorTarget(FrameBuffer.FrameBufferTextureTarget colorBuf)

    • addColorTarget

      public void addColorTarget(FrameBuffer.FrameBufferTextureTarget colorBuf, TextureCubeMap.Face face)
      Adds a texture to one of the color Buffers Array. It uses TextureCubeMap ordinal number for the position in the color buffer ArrayList.
      Parameters:
      colorBuf - texture to add to the color Buffer
      face - position to add to the color buffer

    • 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:
      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:
      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:

    • 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:
      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:

    • 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.
      layer - (default=-1)

    • 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

      @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:

    • 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.
      layer - (default=-1)

    • 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 - the TextureArray to apply
      layer - (default=-1)

    • 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 - the zero-base index (≥0)
      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 single-sampled framebuffer.

    • toString

      public 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(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
      Returns:
      a new instance

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

    • getName

      public String getName()

    • setName

      public void setName(String name)

    • setMipMapsGenerationHint

      public void setMipMapsGenerationHint(Boolean v)
      Hints the renderer to generate mipmaps for this framebuffer if necessary
      Parameters:
      v - true to enable, null to use the default value for the renderer (default to null)

    • getMipMapsGenerationHint

      public Boolean getMipMapsGenerationHint()