Package edu.cornell.gdiac.graphics

Class RenderTarget

java.lang.Object
edu.cornell.gdiac.graphics.RenderTarget
public class RenderTarget extends Object
This is a class representing an offscreen render target.

A render target allows the user to draw to a texture before drawing to a screen. This allows for the potential for post-processing effects. To draw to a render target simply call the begin() method before drawing. From that point on all drawing commands will be sent to the associated texture instead of the screen. Call end() to resume drawing to the screen. Frame buffers should not be stacked. It is not safe to call a begin/end pair of one render target inside of another begin/end pair. Control to the screen should be resumed before using another render target.

While frame buffers must have at least one output texture, they can support multiple textures as long as the active fragment shader has multiple output variables. The locations of these outputs should be set explicitly and sequentially with the layout keyword (GL30 only).

Note that the textures produced by this class are upside down, in that the origin is in the top right corner and y axis is down. This can be fixed by either adjusting the camera at the time the RenderTarget is used, or by adjusting the texture coordinates afterwards.

This class greatly simplifies OpenGL framebuffers at the cost of some flexibility. The only support for depth and stencil is a combined 24/8 depth and stencil buffer. In addition, output textures must have one of the simplified formats defined by Texture2D.PixelFormat. Finally, all output textures are bound sequentially to output locations 0..#outputs-1. With that said, we find that still allows us to handle the vast majority of applications with a framebuffer.

Frame buffer targets may be written to a file for debugging purposes. While we cannot write Texture objects to a file directly (OpenGLES does not permit this), we can always do so when they are the target of a frame buffer.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    int
    framebo
    The framebuffer associated with this render target

  • Constructor Summary

    Constructors
    Constructor
    Description
    RenderTarget(int width, int height)
    Creates a frame buffer with a single RGBA output texture.
    RenderTarget(int width, int height, int outputs)
    Creates a frame buffer with multiple RGBA output textures.
    RenderTarget(int width, int height, com.badlogic.gdx.utils.Array<Texture2D.PixelFormat> outputs)
    Creates a frame buffer with multiple textures of the given format.
    RenderTarget(int width, int height, com.badlogic.gdx.utils.IntMap<Texture2D.PixelFormat> outputs)
    Creates a frame buffer with multiple textures of the given format.
    RenderTarget(int width, int height, Texture2D.PixelFormat[] outputs)
    Creates a frame buffer with with multiple textures of the given format.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    begin()
    Binds this frame buffer so that it can receive draw commands.
    void
    dispose()
    Deletes the frame buffer and resets all attributes.
    void
    end()
    Unbinds this frame buffer so that it no longer receives draw commands.
    protected void
    finalize()
    Cleans up frame buffer on Garbage collection
    com.badlogic.gdx.graphics.Texture
    getDepthStencil()
    Returns the depth/stencil buffer for this render target
    int
    getHeight()
    Returns the height of this render target
    Buffer
    getPixelData()
    Returns the pixel data for the primary output texture.
    Buffer
    getPixelData(int index)
    Returns the pixel data for the given output texture.
    Buffer
    getPixelData(Buffer buffer)
    Returns the pixel data for the given output texture, stored in place
    Buffer
    getPixelData(Buffer buffer, int index)
    Returns the pixel data for the given output texture, stored in place
    com.badlogic.gdx.graphics.Pixmap
    getPixmap()
    Returns the pixmap for the primary output texture.
    com.badlogic.gdx.graphics.Pixmap
    getPixmap(int index)
    Returns the pixmap for the given output texture.
    Texture2D
    getTexture()
    Returns the primary output texture.
    com.badlogic.gdx.graphics.Texture
    getTexture(int index)
    Returns the output texture for the given index.
    int
    getWidth()
    Returns the width of this render target
    boolean
    isBound()
    Returns true if this frame buffer is currently bound.
    void
    setClearColor(com.badlogic.gdx.graphics.Color color)
    Sets the clear color for this render target.
    String
    toString()
    Returns a string representation of this texture for debugging purposes.

    Methods inherited from class java.lang.Object

    clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • framebo

      public int framebo
      The framebuffer associated with this render target

  • Constructor Details

    • RenderTarget

      public RenderTarget(int width, int height)
      Creates a frame buffer with a single RGBA output texture.

      The output texture will have the given width and size.

      Parameters:
      width - The drawing width of this render target
      height - The drawing width of this render target

    • RenderTarget

      public RenderTarget(int width, int height, int outputs)
      Creates a frame buffer with multiple RGBA output textures.

      The output textures will have the given width and size. They will be assigned locations 0..outputs-1. These locations should be bound with the layout keyword in any shader used with this render target. Otherwise the results are not well-defined.

      If outputs is larger than the number of possible shader outputs for this platform, this method will fail. OpenGL only guarantees up to 8 output textures.

      Parameters:
      width - The drawing width of this render target
      height - The drawing width of this render target
      outputs - The number of output textures

    • RenderTarget

      public RenderTarget(int width, int height, com.badlogic.gdx.utils.IntMap<Texture2D.PixelFormat> outputs)
      Creates a frame buffer with multiple textures of the given format.

      The output textures will have the given width and size. They will be assigned the appropriate format as specified in Texture. They will be assigned locations matching the keys of the map outputs. These locations should be bound with the layout keyword in any shader used with this render target. Otherwise the results are not well-defined.

      If the size of the outputs parameter is larger than the number of possible shader outputs for this platform, this method will fail. OpenGL only guarantees up to 8 output textures.

      Parameters:
      width - The drawing width of this render target
      height - The drawing width of this render target
      outputs - The map of desired texture formats for each location

    • RenderTarget

      public RenderTarget(int width, int height, com.badlogic.gdx.utils.Array<Texture2D.PixelFormat> outputs)
      Creates a frame buffer with multiple textures of the given format.

      The output textures will have the given width and size. They will be assigned the appropriate format as specified in Texture. They will be assigned locations 0..#outputs-1. These locations should be bound with the layout keyword in any shader used with this render target. Otherwise the results are not well-defined.

      If the size of the outputs parameter is larger than the number of possible shader outputs for this platform, this method will fail. OpenGL only guarantees up to 8 output textures.

      Parameters:
      width - The drawing width of this render target
      height - The drawing width of this render target
      outputs - The list of desired texture formats

    • RenderTarget

      public RenderTarget(int width, int height, Texture2D.PixelFormat[] outputs)
      Creates a frame buffer with with multiple textures of the given format.

      The output textures will have the given width and size. They will be assigned the appropriate format as specified in Texture. They will be assigned locations 0..outsize-1. These locations should be bound with the layout keyword in any shader used with this render target. Otherwise the results are not well-defined.

      If the size of the outputs parameter is larger than the number of possible shader outputs for this platform, this method will fail. OpenGL only guarantees up to 8 output textures.

      Parameters:
      width - The drawing width of this render target
      height - The drawing width of this render target
      outputs - The list of desired texture formats

  • Method Details

    • finalize

      protected void finalize() throws Throwable
      Cleans up frame buffer on Garbage collection
      Overrides:
      finalize in class Object
      Throws:
      Throwable

    • dispose

      public void dispose()
      Deletes the frame buffer and resets all attributes.

      You must reinitialize the frame buffer to use it.

    • getWidth

      public int getWidth()
      Returns the width of this render target
      Returns:
      the width of this render target

    • getHeight

      public int getHeight()
      Returns the height of this render target
      Returns:
      the height of this render target

    • setClearColor

      public void setClearColor(com.badlogic.gdx.graphics.Color color)
      Sets the clear color for this render target.

      The clear color is used to clear the texture when the method begin() is called.

      Parameters:
      color - The clear color for this render target.

    • getTexture

      public Texture2D getTexture()
      Returns the primary output texture.

      If the frame buffer has multiple output textures, this will be the texture at index 0.

      Returns:
      the output texture for the given index.

    • getTexture

      public com.badlogic.gdx.graphics.Texture getTexture(int index)
      Returns the output texture for the given index.

      The index should be a value between 0..OutputSize-1.

      Parameters:
      index - The output index
      Returns:
      the output texture for the given index.

    • getDepthStencil

      public com.badlogic.gdx.graphics.Texture getDepthStencil()
      Returns the depth/stencil buffer for this render target

      The framebuffer for a render target always uses a combined depth and stencil buffer. It uses 24 bits for the depth and 8 bits for the stencil. This should be sufficient in most applications.

      Returns:
      the depth/stencil buffer for this render target

    • begin

      public void begin()
      Binds this frame buffer so that it can receive draw commands.

      This method ets the viewpoint to match the size of this render target (which may not be the same as the screen). The old viewport is saved and will be restored when end() is called.

      It is NOT safe to call a bind/unbind pair of a render target inside of another render target. Render targets do not keep a stack. They always return control to the default render target (the screen) when done.

    • end

      public void end()
      Unbinds this frame buffer so that it no longer receives draw commands.

      When this method is called, the original viewport will be restored. Future draw commands will be sent directly to the screen.

      It is NOT safe to call a bind/unbind pair of a render target inside of another render target. Render targets do not keep a stack. They always return control to the default render target (the screen) when done.

    • isBound

      public boolean isBound()
      Returns true if this frame buffer is currently bound.
      Returns:
      true if this frame buffer is currently bound.

    • getPixelData

      public Buffer getPixelData()
      Returns the pixel data for the primary output texture.

      If the frame buffer has multiple output textures, this will be the texture at index 0. The frame buffer must be bound for this method to succeed.

      Returns:
      the pixel data for the primary output texture.

    • getPixelData

      public Buffer getPixelData(int index)
      Returns the pixel data for the given output texture.

      The index should be a value between 0..OutputSize-1. The frame buffer must be bound for this method to succeed.

      Parameters:
      index - The output index
      Returns:
      the pixel data for the given output texture.

    • getPixelData

      public Buffer getPixelData(Buffer buffer)
      Returns the pixel data for the given output texture, stored in place

      If the frame buffer has multiple output textures, this will be the texture at index 0. The frame buffer must be bound for this method to succeed.

      Parameters:
      buffer - The buffer to store the pixel data
      Returns:
      the pixel data for the given output texture, stored in place

    • getPixelData

      public Buffer getPixelData(Buffer buffer, int index)
      Returns the pixel data for the given output texture, stored in place

      The index should be a value between 0..OutputSize-1. The frame buffer must be bound for this method to succeed.

      Parameters:
      index - The output index
      buffer - The buffer to store the pixel data
      Returns:
      the pixel data for the given output texture, stored in place

    • getPixmap

      public com.badlogic.gdx.graphics.Pixmap getPixmap()
      Returns the pixmap for the primary output texture.

      The Pixmap will have the y-pixels flipped, so that they agree with the texture when saved to a file.

      If the frame buffer has multiple output textures, this will be the texture at index 0. The frame buffer must be bound for this method to succeed.

      Returns:
      the pixmap for the primary output texture.

    • getPixmap

      public com.badlogic.gdx.graphics.Pixmap getPixmap(int index)
      Returns the pixmap for the given output texture.

      The Pixmap will have the y-pixels flipped, so that they agree with the texture when saved to a file.

      The index should be a value between 0..OutputSize-1. The frame buffer must be bound for this method to succeed.

      Parameters:
      index - The output index
      Returns:
      the pixmap for the given output texture.

    • toString

      public String toString()
      Returns a string representation of this texture for debugging purposes.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this texture for debugging purposes.