com.jogamp.opengl

## Class FBObject

- java.lang.Object
- - com.jogamp.opengl.FBObject

-     public class FBObject
      extends Object

  Core utility class simplifying usage of framebuffer objects (FBO) with all `GLProfile`s.

  Supports on-the-fly reconfiguration of dimension and multisample buffers via `reset(GL, int, int, int, boolean)` while preserving the `FBObject.Attachment` references.

  Integrates default read/write framebuffers via `GLContext.getDefaultReadFramebuffer()` and `GLContext.getDefaultReadFramebuffer()`, which is being hooked at `GL.glBindFramebuffer(int, int)` when the default (`zero`) framebuffer is selected.

  FIXME: Implement support for `FBObject.Attachment.Type.DEPTH_TEXTURE`, `FBObject.Attachment.Type.STENCIL_TEXTURE` .

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `FBObject.Attachment` Common super class of all FBO attachments
    `static class` | `FBObject.ColorAttachment` Color render buffer FBO attachment
    `static interface` | `FBObject.Colorbuffer` Generic color buffer FBO attachment, either of type `FBObject.ColorAttachment` or `FBObject.TextureAttachment`.
    `static class` | `FBObject.RenderAttachment` Other renderbuffer attachment which maybe a colorbuffer, depth or stencil.
    `static class` | `FBObject.TextureAttachment` Texture FBO attachment

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FBObject()` Creates an uninitialized FBObject instance.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `FBObject.ColorAttachment` | `attachColorbuffer(GL gl, int attachmentPoint, boolean alpha)` Attaches a `FBObject.Colorbuffer`, i.e.
    `FBObject.Colorbuffer` | `attachColorbuffer(GL gl, int attachmentPoint, FBObject.Colorbuffer colbuf)` Attaches a `FBObject.Colorbuffer`, i.e.
    `FBObject.ColorAttachment` | `attachColorbuffer(GL gl, int attachmentPoint, int internalFormat)` Attaches a `FBObject.Colorbuffer`, i.e.
    `void` | `attachRenderbuffer(GL gl, FBObject.Attachment.Type atype, int reqBits)` Attaches one depth, stencil or packed-depth-stencil buffer to this FBO's instance, selecting the internalFormat automatically.
    `void` | `attachRenderbuffer(GL gl, int internalFormat)` Attaches one depth, stencil or packed-depth-stencil buffer to this FBO's instance, depending on the `internalFormat`.
    `FBObject.TextureAttachment` | `attachTexture2D(GL gl, int attachmentPoint, boolean alpha)` Attaches a `FBObject.Colorbuffer`, i.e.
    `FBObject.TextureAttachment` | `attachTexture2D(GL gl, int attachmentPoint, boolean alpha, int magFilter, int minFilter, int wrapS, int wrapT)` Attaches a `FBObject.Colorbuffer`, i.e.
    `FBObject.TextureAttachment` | `attachTexture2D(GL gl, int attachmentPoint, int internalFormat, int dataFormat, int dataType, int magFilter, int minFilter, int wrapS, int wrapT)` Attaches a `FBObject.Colorbuffer`, i.e.
    `void` | `bind(GL gl)` Bind this FBO, i.e.
    `FBObject.ColorAttachment` | `createColorAttachment(boolean alpha)` Creates a `FBObject.ColorAttachment`, selecting the format automatically.
    `static FBObject.ColorAttachment` | `createColorAttachment(int internalFormat, int samples, int width, int height)` Creates a `FBObject.ColorAttachment`, selecting the format automatically.
    `static FBObject.TextureAttachment` | `createColorTextureAttachment(GL gl, boolean alpha, int width, int height)` Creates a color `FBObject.TextureAttachment`, i.e.
    `static FBObject.TextureAttachment` | `createColorTextureAttachment(GL gl, boolean alpha, int width, int height, int magFilter, int minFilter, int wrapS, int wrapT)` Creates a color `FBObject.TextureAttachment`, i.e.
    `static FBObject.TextureAttachment` | `createColorTextureAttachment(int internalFormat, int width, int height, int dataFormat, int dataType, int magFilter, int minFilter, int wrapS, int wrapT)` Creates a color `FBObject.TextureAttachment`, i.e.
    `static FBObject.RenderAttachment` | `createRenderAttachment(FBObject.Attachment.Type type, int internalFormat, int samples, int width, int height)`
    `void` | `destroy(GL gl)`
    `void` | `detachAll(GL gl)` Detaches all `FBObject.ColorAttachment`s, `FBObject.TextureAttachment`s and `FBObject.RenderAttachment`s and disposes them.
    `void` | `detachAllColorbuffer(GL gl)` Detaches all `FBObject.ColorAttachment`s and `FBObject.TextureAttachment`s and disposes them.
    `void` | `detachAllRenderbuffer(GL gl)`
    `void` | `detachAllTexturebuffer(GL gl)` Detaches all `FBObject.TextureAttachment`s and disposes them.
    `FBObject.Colorbuffer` | `detachColorbuffer(GL gl, int attachmentPoint, boolean dispose)` Detaches a `FBObject.Colorbuffer`, i.e.
    `void` | `detachRenderbuffer(GL gl, FBObject.Attachment.Type atype, boolean dispose)`
    `void` | `formatToGLCapabilities(GLCapabilities caps)` Writes the internal format of the attachments to the given GLCapabilities object.
    `FBObject.Colorbuffer` | `getColorbuffer(FBObject.Colorbuffer ca)` Returns the passed `FBObject.Colorbuffer` if it is attached to this FBO, otherwise null.
    `FBObject.Colorbuffer` | `getColorbuffer(int attachmentPoint)` Return the `FBObject.Colorbuffer` attachment at `attachmentPoint` if it is attached to this FBO, otherwise null.
    `int` | `getColorbufferAttachmentPoint(FBObject.Colorbuffer ca)` Finds the passed `FBObject.Colorbuffer` within the valid range of attachment points using reference comparison only.
    `int` | `getColorbufferCount()` Return the number of attached `FBObject.Colorbuffer`s
    `int` | `getDefaultReadBuffer()`
    `FBObject.RenderAttachment` | `getDepthAttachment()` Return the depth `FBObject.RenderAttachment` attachment.
    `int` | `getHeight()` Returns the height
    `int` | `getMaxColorAttachments()` Returns the maximum number of colorbuffer attachments.
    `int` | `getMaxRenderbufferSize()`
    `int` | `getMaxSamples()`
    `int` | `getMaxTextureSize()`
    `int` | `getNumSamples()` Returns the number of samples for multisampling (MSAA).
    `int` | `getReadFramebuffer()` Returns the framebuffer name to read from.
    `FBObject.Colorbuffer` | `getSamplingSink()` Return the multisampling `FBObject.Colorbuffer` sink, if using multisampling.
    `FBObject` | `getSamplingSinkFBO()` Return the complete multisampling `FBObject` sink, if using multisampling.
    `int` | `getStatus()` Note that the status may reflect an incomplete state during transition of attachments.
    `String` | `getStatusString()` return the `getStatus()` as a string.
    `static String` | `getStatusString(int fbStatus)`
    `FBObject.RenderAttachment` | `getStencilAttachment()` Return the stencil `FBObject.RenderAttachment` attachment, if exist.
    `int` | `getTextureAttachmentCount()` Return the number of attached `FBObject.TextureAttachment`s
    `int` | `getWidth()` Returns the width
    `int` | `getWriteFramebuffer()` Returns the framebuffer name to render to.
    `boolean` | `hasAttachmentUsingAlpha()` Returns true if any attached `FBObject.Colorbuffer` uses alpha, otherwise false.
    `boolean` | `hasFullFBOSupport()`
    `boolean` | `isBound()` Returns `true` if framebuffer object is bound via `bind(GL)`, otherwise `false`.
    `boolean` | `isBound(GL gl)` Returns `true` if framebuffer object is bound via `bind(GL)`, otherwise `false`.
    `boolean` | `isDepthStencilPackedFormat()`
    `boolean` | `isInitialized()` Returns `true` if this instance has been initialized with `reset(GL, int, int)` or `reset(GL, int, int, int, boolean)`, otherwise `false`
    `boolean` | `isSamplingBufferDirty()` Returns `true` if the multisampling colorbuffer (msaa-buffer) has been flagged dirty by a previous call of `bind(GL)`, otherwise `false`.
    `boolean` | `isStatusValid()` The status may even be valid if incomplete during transition of attachments.
    `void` | `markUnbound()` Method simply marks this FBO unbound w/o interfering w/ the bound framebuffer as perfomed by `unbind(GL)`.
    `void` | `reset(GL gl, int newWidth, int newHeight)` Initializes or resets this FBO's instance.
    `void` | `reset(GL gl, int newWidth, int newHeight, int newSamples, boolean resetSamplingSink)` Initializes or resets this FBO's instance.
    `void` | `resetSamplingSink(GL gl)` Manually reset the MSAA sampling sink, if used.
    `FBObject` | `setSamplingSink(FBObject newSamplingSink)` Setting this FBO sampling sink.
    `boolean` | `supportsDepth(int bits)` Returns `true` if `GL.GL_DEPTH_COMPONENT16`, `GL.GL_DEPTH_COMPONENT24` or `GL.GL_DEPTH_COMPONENT32` is supported, otherwise `false`.
    `boolean` | `supportsPackedDepthStencil()` Returns `true` if `GL.GL_DEPTH24_STENCIL8` is supported, otherwise `false`.
    `boolean` | `supportsRGBA8()` Returns `true` if renderbuffer accepts internal format `GL.GL_RGB8` and `GL.GL_RGBA8`, otherwise `false`.
    `boolean` | `supportsStencil(int bits)` Returns `true` if `GL.GL_STENCIL_INDEX1`, `GL.GL_STENCIL_INDEX4`, `GL.GL_STENCIL_INDEX8` or `GL2GL3.GL_STENCIL_INDEX16` is supported, otherwise `false`.
    `void` | `syncSamplingSink(GL gl)` If multisampling is being used and flagged dirty by a previous call of `bind(GL)` or after initialization, the msaa-buffers are sampled to it's sink `#getSamplingTextureSink()`.
    `String` | `toString()`
    `void` | `unbind(GL gl)` Unbind this FBO, i.e.
    `void` | `unuse(GL gl)` Unbind texture, ie bind 'non' texture 0
    `void` | `use(GL gl, FBObject.TextureAttachment ta)` `Synchronize the sampling sink` and bind the given `FBObject.TextureAttachment`, if not `null`.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### FBObject

          public FBObject()

      Creates an uninitialized FBObject instance.

      Call `init(GL, int, int, int)` .. etc to use it.

  - ### Method Detail

    - #### createColorTextureAttachment

          public static final FBObject.TextureAttachment createColorTextureAttachment(GL gl,
                                                                boolean alpha,
                                                                int width,
                                                                int height)

      Creates a color `FBObject.TextureAttachment`, i.e. type `FBObject.Attachment.Type.COLOR_TEXTURE`, selecting the texture data type and format automatically.

      Using default min/mag filter `GL.GL_NEAREST` and default wrapS/wrapT `GL.GL_CLAMP_TO_EDGE`.

      Parameters:
        `gl` - the used `GLContext`'s `GL` object
        `alpha` - set to `true` if you request alpha channel, otherwise `false`;
        `width` - texture width
        `height` - texture height
      Returns:
        the created and uninitialized color `FBObject.TextureAttachment`

    - #### createColorTextureAttachment

          public static final FBObject.TextureAttachment createColorTextureAttachment(GL gl,
                                                                boolean alpha,
                                                                int width,
                                                                int height,
                                                                int magFilter,
                                                                int minFilter,
                                                                int wrapS,
                                                                int wrapT)

      Creates a color `FBObject.TextureAttachment`, i.e. type `FBObject.Attachment.Type.COLOR_TEXTURE`, selecting the texture data type and format automatically.

      For GLES3, sampling-sink format must be equal w/ the sampling-source `FBObject.Colorbuffer`, see details below. Implementation aligns w/ `createColorAttachment(boolean)` and is enforced via `sampleSinkFormatMismatch(GL)`.

      ES3 BlitFramebuffer Requirements: OpenGL ES 3.0.2 p194: 4.3.2 Copying Pixels

           If SAMPLE_BUFFERS for the read framebuffer is greater than zero, no copy
           is performed and an INVALID_OPERATION error is generated if the formats of
           the read and draw framebuffers are not identical or if the source and destination
           rectangles are not defined with the same (X0, Y 0) and (X1, Y 1) bounds.

      Texture and Renderbuffer format details:

           ES2 Base iFormat: OpenGL ES 2.0.24 p66: 3.7.1 Texture Image Specification, Table 3.8
             ALPHA, LUMINANCE, LUMINANCE_ALPHA, RGB, RGBA

           ES3 Base iFormat: OpenGL ES 3.0.2 p125: 3.8.3 Texture Image Specification, Table 3.11
             ALPHA, LUMINANCE, LUMINANCE_ALPHA, RGB, RGBA
             DEPTH_COMPONENT, STENCIL_COMPONENT, RED, RG

           ES3 Required Texture and Renderbuffer iFormat: OpenGL ES 3.0.2 p126: 3.8.3 Texture Image Specification
             - RGBA32I, RGBA32UI, RGBA16I, RGBA16UI, RGBA8, RGBA8I,
               RGBA8UI, SRGB8_ALPHA8, RGB10_A2, RGB10_A2UI, RGBA4, and
               RGB5_A1.
             - RGB8 and RGB565.
             - RG32I, RG32UI, RG16I, RG16UI, RG8, RG8I, and RG8UI.
             - R32I, R32UI, R16I, R16UI, R8, R8I, and R8UI.

      Parameters:
        `gl` - the used `GLContext`'s `GL` object
        `alpha` - set to `true` if you request alpha channel, otherwise `false`;
        `width` - texture width
        `height` - texture height
        `magFilter` - if > 0 value for `GL.GL_TEXTURE_MAG_FILTER`
        `minFilter` - if > 0 value for `GL.GL_TEXTURE_MIN_FILTER`
        `wrapS` - if > 0 value for `GL.GL_TEXTURE_WRAP_S`
        `wrapT` - if > 0 value for `GL.GL_TEXTURE_WRAP_T`
      Returns:
        the created and uninitialized color `FBObject.TextureAttachment`

    - #### createColorTextureAttachment

          public static final FBObject.TextureAttachment createColorTextureAttachment(int internalFormat,
                                                                int width,
                                                                int height,
                                                                int dataFormat,
                                                                int dataType,
                                                                int magFilter,
                                                                int minFilter,
                                                                int wrapS,
                                                                int wrapT)

      Creates a color `FBObject.TextureAttachment`, i.e. type `FBObject.Attachment.Type.COLOR_TEXTURE`.
      Parameters:
        `internalFormat` - internalFormat parameter to `GL.glTexImage2D(int, int, int, int, int, int, int, int, long)`
        `width` - texture width
        `height` - texture height
        `dataFormat` - format parameter to `GL.glTexImage2D(int, int, int, int, int, int, int, int, long)`
        `dataType` - type parameter to `GL.glTexImage2D(int, int, int, int, int, int, int, int, long)`
        `magFilter` - if > 0 value for `GL.GL_TEXTURE_MAG_FILTER`
        `minFilter` - if > 0 value for `GL.GL_TEXTURE_MIN_FILTER`
        `wrapS` - if > 0 value for `GL.GL_TEXTURE_WRAP_S`
        `wrapT` - if > 0 value for `GL.GL_TEXTURE_WRAP_T`
      Returns:
        the created and uninitialized color `FBObject.TextureAttachment`

    - #### getColorbuffer

          public final FBObject.Colorbuffer getColorbuffer(int attachmentPoint)

      Return the `FBObject.Colorbuffer` attachment at `attachmentPoint` if it is attached to this FBO, otherwise null.
      See Also:
        `#attachColorbuffer(GL, boolean)`, `#attachColorbuffer(GL, boolean)`, `attachTexture2D(GL, int, boolean, int, int, int, int)`, `attachTexture2D(GL, int, int, int, int, int, int, int, int)`

    - #### getColorbufferAttachmentPoint

          public final int getColorbufferAttachmentPoint(FBObject.Colorbuffer ca)

      Finds the passed `FBObject.Colorbuffer` within the valid range of attachment points using reference comparison only.

      Note: Slow. Implementation uses a logN array search to save resources, i.e. not using a HashMap.

      Parameters:
        `ca` - the `FBObject.Colorbuffer` to look for.
      Returns:
        -1 if the `FBObject.Colorbuffer` could not be found, otherwise [0..`getMaxColorAttachments()`-1]

    - #### getColorbuffer

          public final FBObject.Colorbuffer getColorbuffer(FBObject.Colorbuffer ca)

      Returns the passed `FBObject.Colorbuffer` if it is attached to this FBO, otherwise null. Implementation compares the reference only.

      Note: Slow. Uses `getColorbufferAttachmentPoint(Colorbuffer)` to determine it's attachment point to be used for `getColorbuffer(int)`

      See Also:
        `#attachColorbuffer(GL, boolean)`, `#attachColorbuffer(GL, boolean)`, `attachTexture2D(GL, int, boolean, int, int, int, int)`, `attachTexture2D(GL, int, int, int, int, int, int, int, int)`

    - #### hasAttachmentUsingAlpha

          public final boolean hasAttachmentUsingAlpha()

      Returns true if any attached `FBObject.Colorbuffer` uses alpha, otherwise false.

    - #### reset

          public final void reset(GL gl,
                   int newWidth,
                   int newHeight)

      Initializes or resets this FBO's instance.

      In case the new parameters are compatible with the current ones no action will be performed. Otherwise all attachments will be recreated to match the new given parameters.

      Incompatibility and hence recreation is forced if the size or sample count doesn't match for subsequent calls.

      Leaves the FBO bound state untouched

      Parameters:
        `gl` - the current GL context
        `newWidth` -
        `newHeight` -
      Throws:
        `GLException` - in case of an error

    - #### reset

          public final void reset(GL gl,
                   int newWidth,
                   int newHeight,
                   int newSamples,
                   boolean resetSamplingSink)

      Initializes or resets this FBO's instance.

      In case the new parameters are compatible with the current ones no action will be performed. Otherwise all attachments will be recreated to match the new given parameters.

      Currently incompatibility and hence recreation of the attachments will be performed if the size or sample count doesn't match for subsequent calls.

      Leaves the FBO bound state untouched

      Parameters:
        `gl` - the current GL context
        `newWidth` - the new width, it's minimum is capped to 1
        `newHeight` - the new height, it's minimum is capped to 1
        `newSamples` - if > 0, MSAA will be used, otherwise no multisampling. Will be capped to `getMaxSamples()`.
        `resetSamplingSink` - `true` calls `resetSamplingSink(GL)` immediatly. `false` postpones resetting the sampling sink until `use(GL, TextureAttachment)` or `syncSamplingSink(GL)`, allowing to use the samples sink's FBO and texture until then. The latter is useful to benefit from implicit double buffering while resetting the sink just before it's being used, eg. at swap-buffer.
      Throws:
        `GLException` - in case of an error, i.e. size too big, etc ..

    - #### formatToGLCapabilities

          public final void formatToGLCapabilities(GLCapabilities caps)

      Writes the internal format of the attachments to the given GLCapabilities object.
      Parameters:
        `caps` - the destination for format bits

    - #### getStatus

          public final int getStatus()

      Note that the status may reflect an incomplete state during transition of attachments.
      Returns:
        The FB status. `GL.GL_FRAMEBUFFER_COMPLETE` if ok, otherwise return GL FBO error state or -1
      See Also:
        `#validateStatus()`

    - #### getStatusString

          public final String getStatusString()

      return the `getStatus()` as a string.

    - #### getStatusString

          public static final String getStatusString(int fbStatus)

    - #### isStatusValid

          public final boolean isStatusValid()

      The status may even be valid if incomplete during transition of attachments.
      See Also:
        `getStatus()`

    - #### attachTexture2D

          public final FBObject.TextureAttachment attachTexture2D(GL gl,
                                                   int attachmentPoint,
                                                   boolean alpha)
                                                           throws GLException

      Attaches a `FBObject.Colorbuffer`, i.e. `FBObject.TextureAttachment`, to this FBO's instance at the given attachment point, selecting the texture data type and format automatically.

      Using default min/mag filter `GL.GL_NEAREST` and default wrapS/wrapT `GL.GL_CLAMP_TO_EDGE`.

      Leaves the FBO bound.

      Parameters:
        `gl` - the current GL context
        `attachmentPoint` - the color attachment point ranging from [0..`getMaxColorAttachments()`-1]
        `alpha` - set to `true` if you request alpha channel, otherwise `false`;
      Returns:
        TextureAttachment instance describing the new attached texture colorbuffer if bound and configured successfully, otherwise GLException is thrown
      Throws:
        `GLException` - in case the texture colorbuffer couldn't be allocated or MSAA has been chosen
      See Also:
        `#createColorTextureAttachment(GLProfile, boolean, int, int)`

    - #### attachTexture2D

          public final FBObject.TextureAttachment attachTexture2D(GL gl,
                                                   int attachmentPoint,
                                                   boolean alpha,
                                                   int magFilter,
                                                   int minFilter,
                                                   int wrapS,
                                                   int wrapT)
                                                           throws GLException

      Attaches a `FBObject.Colorbuffer`, i.e. `FBObject.TextureAttachment`, to this FBO's instance at the given attachment point, selecting the texture data type and format automatically.

      Leaves the FBO bound.

      Parameters:
        `gl` - the current GL context
        `attachmentPoint` - the color attachment point ranging from [0..`getMaxColorAttachments()`-1]
        `alpha` - set to `true` if you request alpha channel, otherwise `false`;
        `magFilter` - if > 0 value for `GL.GL_TEXTURE_MAG_FILTER`
        `minFilter` - if > 0 value for `GL.GL_TEXTURE_MIN_FILTER`
        `wrapS` - if > 0 value for `GL.GL_TEXTURE_WRAP_S`
        `wrapT` - if > 0 value for `GL.GL_TEXTURE_WRAP_T`
      Returns:
        TextureAttachment instance describing the new attached texture colorbuffer if bound and configured successfully, otherwise GLException is thrown
      Throws:
        `GLException` - in case the texture colorbuffer couldn't be allocated or MSAA has been chosen
      See Also:
        `#createColorTextureAttachment(GLProfile, boolean, int, int, int, int, int, int)`

    - #### attachTexture2D

          public final FBObject.TextureAttachment attachTexture2D(GL gl,
                                                   int attachmentPoint,
                                                   int internalFormat,
                                                   int dataFormat,
                                                   int dataType,
                                                   int magFilter,
                                                   int minFilter,
                                                   int wrapS,
                                                   int wrapT)
                                                           throws GLException

      Attaches a `FBObject.Colorbuffer`, i.e. `FBObject.TextureAttachment`, to this FBO's instance at the given attachment point.

      Leaves the FBO bound.

      Parameters:
        `gl` - the current GL context
        `attachmentPoint` - the color attachment point ranging from [0..`getMaxColorAttachments()`-1]
        `internalFormat` - internalFormat parameter to `GL.glTexImage2D(int, int, int, int, int, int, int, int, long)`
        `dataFormat` - format parameter to `GL.glTexImage2D(int, int, int, int, int, int, int, int, long)`
        `dataType` - type parameter to `GL.glTexImage2D(int, int, int, int, int, int, int, int, long)`
        `magFilter` - if > 0 value for `GL.GL_TEXTURE_MAG_FILTER`
        `minFilter` - if > 0 value for `GL.GL_TEXTURE_MIN_FILTER`
        `wrapS` - if > 0 value for `GL.GL_TEXTURE_WRAP_S`
        `wrapT` - if > 0 value for `GL.GL_TEXTURE_WRAP_T`
      Returns:
        TextureAttachment instance describing the new attached texture colorbuffer if bound and configured successfully, otherwise GLException is thrown
      Throws:
        `GLException` - in case the texture colorbuffer couldn't be allocated or MSAA has been chosen
      See Also:
        `createColorTextureAttachment(int, int, int, int, int, int, int, int, int)`

    - #### createColorAttachment

          public final FBObject.ColorAttachment createColorAttachment(boolean alpha)

      Creates a `FBObject.ColorAttachment`, selecting the format automatically.

      For GLES3, sampling-sink `FBObject.Colorbuffer` format must be equal w/ the sampling-source `FBObject.Colorbuffer`. Implementation aligns w/ `#createColorTextureAttachment(GLProfile, boolean, int, int, int, int, int, int)` and is enforced via `sampleSinkFormatMismatch(GL)`.

      Parameters:
        `alpha` - set to `true` if you request alpha channel, otherwise `false`;
      Returns:
        uninitialized ColorAttachment instance describing the new attached colorbuffer

    - #### createColorAttachment

          public static final FBObject.ColorAttachment createColorAttachment(int internalFormat,
                                                       int samples,
                                                       int width,
                                                       int height)

      Creates a `FBObject.ColorAttachment`, selecting the format automatically.

      For GLES3, sampling-sink `FBObject.Colorbuffer` format must be equal w/ the sampling-source `FBObject.Colorbuffer`. Implementation aligns w/ `#createColorTextureAttachment(GLProfile, boolean, int, int, int, int, int, int)` and is enforced via `sampleSinkFormatMismatch(GL)`.

      Parameters:
        `alpha` - set to `true` if you request alpha channel, otherwise `false`;
      Returns:
        uninitialized ColorAttachment instance describing the new attached colorbuffer

    - #### createRenderAttachment

          public static final FBObject.RenderAttachment createRenderAttachment(FBObject.Attachment.Type type,
                                                         int internalFormat,
                                                         int samples,
                                                         int width,
                                                         int height)

    - #### attachColorbuffer

          public final FBObject.ColorAttachment attachColorbuffer(GL gl,
                                                   int attachmentPoint,
                                                   boolean alpha)
                                                           throws GLException

      Attaches a `FBObject.Colorbuffer`, i.e. `FBObject.ColorAttachment`, to this FBO's instance at the given attachment point, selecting the format automatically.

      Leaves the FBO bound.

      Parameters:
        `gl` - the current GL context
        `attachmentPoint` - the color attachment point ranging from [0..`getMaxColorAttachments()`-1]
        `alpha` - set to `true` if you request alpha channel, otherwise `false`;
      Returns:
        ColorAttachment instance describing the new attached colorbuffer if bound and configured successfully, otherwise GLException is thrown
      Throws:
        `GLException` - in case the colorbuffer couldn't be allocated
      See Also:
        `createColorAttachment(boolean)`

    - #### attachColorbuffer

          public final FBObject.ColorAttachment attachColorbuffer(GL gl,
                                                   int attachmentPoint,
                                                   int internalFormat)
                                                           throws GLException,
                                                                  IllegalArgumentException

      Attaches a `FBObject.Colorbuffer`, i.e. `FBObject.ColorAttachment`, to this FBO's instance at the given attachment point.

      Leaves the FBO bound.

      Parameters:
        `gl` - the current GL context
        `attachmentPoint` - the color attachment point ranging from [0..`getMaxColorAttachments()`-1]
        `internalFormat` - usually `GL.GL_RGBA4`, `GL.GL_RGB5_A1`, `GL.GL_RGB565`, `GL.GL_RGB8` or `GL.GL_RGBA8`
      Returns:
        ColorAttachment instance describing the new attached colorbuffer if bound and configured successfully, otherwise GLException is thrown
      Throws:
        `GLException` - in case the colorbuffer couldn't be allocated
        `IllegalArgumentException` - if `internalFormat` doesn't reflect a colorbuffer

    - #### attachColorbuffer

          public final FBObject.Colorbuffer attachColorbuffer(GL gl,
                                               int attachmentPoint,
                                               FBObject.Colorbuffer colbuf)
                                                       throws GLException

      Attaches a `FBObject.Colorbuffer`, i.e. `FBObject.ColorAttachment` or `FBObject.TextureAttachment`, to this FBO's instance at the given attachment point.

      If `FBObject.Colorbuffer` is a `FBObject.TextureAttachment` and is uninitialized, i.e. it's texture name is `zero`, a new texture name is generated and setup w/ the texture parameter.
      Otherwise, i.e. texture name is not `zero`, the passed TextureAttachment `texA` is considered complete and assumed matching this FBO requirement. A GL error may occur is the latter is untrue.

      Leaves the FBO bound.

      Parameters:
        `gl` -
        `attachmentPoint` - the color attachment point ranging from [0..`getMaxColorAttachments()`-1]
        `colbuf` - the to be attached `FBObject.Colorbuffer`
      Returns:
        newly attached `FBObject.Colorbuffer` instance if bound and configured successfully, otherwise GLException is thrown
      Throws:
        `GLException` - in case the colorbuffer couldn't be allocated or MSAA has been chosen in case of a `FBObject.TextureAttachment`

    - #### attachRenderbuffer

          public final void attachRenderbuffer(GL gl,
                                FBObject.Attachment.Type atype,
                                int reqBits)
                                        throws GLException,
                                               IllegalArgumentException

      Attaches one depth, stencil or packed-depth-stencil buffer to this FBO's instance, selecting the internalFormat automatically.

      Stencil and depth buffer can be attached only once.

      In case the desired type or bit-number is not supported, the next available one is chosen.

      Use `getDepthAttachment()` and/or `getStencilAttachment()` to retrieve details about the attached buffer. The details cannot be returned, since it's possible 2 buffers are being created, depth and stencil.

      Leaves the FBO bound.

      Parameters:
        `gl` -
        `atype` - either `FBObject.Attachment.Type.DEPTH`, `FBObject.Attachment.Type.STENCIL` or `FBObject.Attachment.Type.DEPTH_STENCIL`
        `reqBits` - desired bits for depth or -1 for default (24 bits)
      Throws:
        `GLException` - in case the renderbuffer couldn't be allocated or one is already attached.
        `IllegalArgumentException`
      See Also:
        `getDepthAttachment()`, `getStencilAttachment()`

    - #### attachRenderbuffer

          public final void attachRenderbuffer(GL gl,
                                int internalFormat)
                                        throws GLException,
                                               IllegalArgumentException

      Attaches one depth, stencil or packed-depth-stencil buffer to this FBO's instance, depending on the `internalFormat`.

      Stencil and depth buffer can be attached only once.

      Use `getDepthAttachment()` and/or `getStencilAttachment()` to retrieve details about the attached buffer. The details cannot be returned, since it's possible 2 buffers are being created, depth and stencil.

      Leaves the FBO bound.

      Parameters:
        `gl` - the current GL context
        `internalFormat` - `GL.GL_DEPTH_COMPONENT16`, `GL.GL_DEPTH_COMPONENT24`, `GL.GL_DEPTH_COMPONENT32`, `GL.GL_STENCIL_INDEX1`, `GL.GL_STENCIL_INDEX4`, `GL.GL_STENCIL_INDEX8` or `GL.GL_DEPTH24_STENCIL8`
      Throws:
        `GLException` - in case the renderbuffer couldn't be allocated or one is already attached.
        `IllegalArgumentException`
      See Also:
        `getDepthAttachment()`, `getStencilAttachment()`

    - #### detachColorbuffer

          public final FBObject.Colorbuffer detachColorbuffer(GL gl,
                                               int attachmentPoint,
                                               boolean dispose)
                                                       throws IllegalArgumentException

      Detaches a `FBObject.Colorbuffer`, i.e. `FBObject.ColorAttachment` or `FBObject.TextureAttachment`.

      Leaves the FBO bound!

      Parameters:
        `gl` -
        `attachmentPoint` -
        `dispose` - true if the Colorbuffer shall be disposed
      Returns:
        the detached Colorbuffer
      Throws:
        `IllegalArgumentException`

    - #### detachRenderbuffer

          public final void detachRenderbuffer(GL gl,
                                FBObject.Attachment.Type atype,
                                boolean dispose)
                                        throws IllegalArgumentException

      Parameters:
        `gl` -
        `dispose` - true if the Colorbuffer shall be disposed
        `reqAType` - `FBObject.Attachment.Type.DEPTH`, `FBObject.Attachment.Type.DEPTH` or `FBObject.Attachment.Type.DEPTH_STENCIL`
      Throws:
        `IllegalArgumentException`

    - #### isDepthStencilPackedFormat

          public final boolean isDepthStencilPackedFormat()

    - #### detachAll

          public final void detachAll(GL gl)

      Detaches all `FBObject.ColorAttachment`s, `FBObject.TextureAttachment`s and `FBObject.RenderAttachment`s and disposes them.

      Leaves the FBO bound, if initialized!

      An attached sampling sink texture will be detached as well, see `#getSamplingTextureSink()`.

      Parameters:
        `gl` - the current GL context

    - #### detachAllColorbuffer

          public final void detachAllColorbuffer(GL gl)

      Detaches all `FBObject.ColorAttachment`s and `FBObject.TextureAttachment`s and disposes them.

      Leaves the FBO bound, if initialized!

      An attached sampling sink texture will be detached as well, see `#getSamplingTextureSink()`.

      Parameters:
        `gl` - the current GL context

    - #### detachAllTexturebuffer

          public final void detachAllTexturebuffer(GL gl)

      Detaches all `FBObject.TextureAttachment`s and disposes them.

      Leaves the FBO bound, if initialized!

      An attached sampling sink texture will be detached as well, see `#getSamplingTextureSink()`.

      Parameters:
        `gl` - the current GL context

    - #### detachAllRenderbuffer

          public final void detachAllRenderbuffer(GL gl)

    - #### destroy

          public final void destroy(GL gl)

      Parameters:
        `gl` - the current GL context

    - #### resetSamplingSink

          public final void resetSamplingSink(GL gl)
                                       throws GLException

      Manually reset the MSAA sampling sink, if used.

      If MSAA is being used and no sampling sink is attached via `setSamplingSink(FBObject)` a new sampling sink is being created.

      Automatically called by `reset(GL, int, int, int, boolean)` and `syncSamplingSink(GL)`.

      It is recommended to call this method after initializing the FBO and attaching renderbuffer etc for the 1st time if access to sampling sink resources is required.

      Parameters:
        `gl` - the current GL context
      Throws:
        `GLException` - in case of an error, i.e. size too big, etc ..

    - #### setSamplingSink

          public FBObject setSamplingSink(FBObject newSamplingSink)
                                   throws GLException

      Setting this FBO sampling sink.
      Parameters:
        `newSamplingSink` - the new FBO sampling sink to use, or null to remove current sampling sink
      Returns:
        the previous sampling sink or null if none was attached
      Throws:
        `GLException` - if this FBO doesn't use MSAA or the given sink uses MSAA itself

    - #### bind

          public final void bind(GL gl)
                          throws GLException

      Bind this FBO, i.e. bind write framebuffer to `getWriteFramebuffer()`.

      If multisampling is used, it sets the read framebuffer to the sampling sink `getWriteFramebuffer()`.

      In case you have attached more than one color buffer, you may want to setup `GL2ES3.glDrawBuffers(int, int[], int)`.

      Parameters:
        `gl` - the current GL context
      Throws:
        `GLException`

    - #### unbind

          public final void unbind(GL gl)
                            throws GLException

      Unbind this FBO, i.e. bind read and write framebuffer to default, see `GLBase.getDefaultDrawFramebuffer()`.

      If full FBO is supported, sets the read and write framebuffer individually to default, hence not disturbing an optional operating MSAA FBO, see `GLBase.getDefaultReadFramebuffer()` and `GLBase.getDefaultDrawFramebuffer()`

      Parameters:
        `gl` - the current GL context
      Throws:
        `GLException`

    - #### markUnbound

          public final void markUnbound()

      Method simply marks this FBO unbound w/o interfering w/ the bound framebuffer as perfomed by `unbind(GL)`.

      Only use this method if a subsequent `unbind(GL)`, `use(GL, TextureAttachment)` or `bind(GL)` follows on any FBO.

    - #### isBound

          public final boolean isBound(GL gl)

      Returns `true` if framebuffer object is bound via `bind(GL)`, otherwise `false`.

      Method verifies the bound state via `GLBase.getBoundFramebuffer(int)`.

      Parameters:
        `gl` - the current GL context

    - #### isBound

          public final boolean isBound()

      Returns `true` if framebuffer object is bound via `bind(GL)`, otherwise `false`.

    - #### syncSamplingSink

          public final void syncSamplingSink(GL gl)

      If multisampling is being used and flagged dirty by a previous call of `bind(GL)` or after initialization, the msaa-buffers are sampled to it's sink `#getSamplingTextureSink()`.

      Method also resets the sampling sink configuration via `resetSamplingSink(GL)` if used and required.

      Method is called automatically by `use(GL, TextureAttachment)`.

      Method always resets the framebuffer binding to default in the end. If full FBO is supported, sets the read and write framebuffer individually to default after sampling, hence not disturbing an optional operating MSAA FBO, see `GLBase.getDefaultReadFramebuffer()` and `GLBase.getDefaultDrawFramebuffer()`

      In case you use this FBO w/o the `GLFBODrawable` and intend to employ `glReadPixels(..)` you may want to call `glBindFramebuffer`(`GL2ES3.GL_READ_FRAMEBUFFER`, `getReadFramebuffer()`);

      Leaves the FBO unbound.

      Parameters:
        `gl` - the current GL context
        `ta` - `FBObject.TextureAttachment` to use, prev. attached w/ `attachTexture2D(..)`
      Throws:
        `IllegalArgumentException`

    - #### use

          public final void use(GL gl,
                 FBObject.TextureAttachment ta)
                         throws IllegalArgumentException

      `Synchronize the sampling sink` and bind the given `FBObject.TextureAttachment`, if not `null`.

      If using a `FBObject.TextureAttachment` and multiple texture units, ensure you call `GL.glActiveTexture(int)` first!

      `syncSamplingSink(GL)` is being called

      Leaves the FBO unbound!

      Parameters:
        `gl` - the current GL context
        `ta` - `FBObject.TextureAttachment` to use, prev. attached w/ `attachTexture2D(..)`, may be `null` in case no `FBObject.TextureAttachment` is used.
      Throws:
        `IllegalArgumentException`

    - #### unuse

          public final void unuse(GL gl)

      Unbind texture, ie bind 'non' texture 0

      Leaves the FBO unbound.

    - #### hasFullFBOSupport

          public final boolean hasFullFBOSupport()
                                          throws GLException

      Throws:
        `GLException`
      See Also:
        `GLBase.hasFullFBOSupport()`

    - #### supportsRGBA8

          public final boolean supportsRGBA8()
                                      throws GLException

      Returns `true` if renderbuffer accepts internal format `GL.GL_RGB8` and `GL.GL_RGBA8`, otherwise `false`.
      Throws:
        `GLException` - if `#init(GL)` hasn't been called.

    - #### supportsDepth

          public final boolean supportsDepth(int bits)
                                      throws GLException

      Returns `true` if `GL.GL_DEPTH_COMPONENT16`, `GL.GL_DEPTH_COMPONENT24` or `GL.GL_DEPTH_COMPONENT32` is supported, otherwise `false`.
      Parameters:
        `bits` - 16, 24 or 32 bits
      Throws:
        `GLException` - if `#init(GL)` hasn't been called.

    - #### supportsStencil

          public final boolean supportsStencil(int bits)
                                        throws GLException

      Returns `true` if `GL.GL_STENCIL_INDEX1`, `GL.GL_STENCIL_INDEX4`, `GL.GL_STENCIL_INDEX8` or `GL2GL3.GL_STENCIL_INDEX16` is supported, otherwise `false`.
      Parameters:
        `bits` - 1, 4, 8 or 16 bits
      Throws:
        `GLException` - if `#init(GL)` hasn't been called.

    - #### supportsPackedDepthStencil

          public final boolean supportsPackedDepthStencil()
                                                   throws GLException

      Returns `true` if `GL.GL_DEPTH24_STENCIL8` is supported, otherwise `false`.
      Throws:
        `GLException` - if `#init(GL)` hasn't been called.

    - #### getMaxColorAttachments

          public final int getMaxColorAttachments()
                                           throws GLException

      Returns the maximum number of colorbuffer attachments.
      Throws:
        `GLException` - if `#init(GL)` hasn't been called.

    - #### getMaxTextureSize

          public final int getMaxTextureSize()
                                      throws GLException

      Throws:
        `GLException`

    - #### getMaxRenderbufferSize

          public final int getMaxRenderbufferSize()
                                           throws GLException

      Throws:
        `GLException`

    - #### getMaxSamples

          public final int getMaxSamples()
                                  throws GLException

      Throws:
        `GLException`
      See Also:
        `GLBase.getMaxRenderbufferSamples()`

    - #### isInitialized

          public final boolean isInitialized()

      Returns `true` if this instance has been initialized with `reset(GL, int, int)` or `reset(GL, int, int, int, boolean)`, otherwise `false`

    - #### getWidth

          public final int getWidth()

      Returns the width

    - #### getHeight

          public final int getHeight()

      Returns the height

    - #### getNumSamples

          public final int getNumSamples()

      Returns the number of samples for multisampling (MSAA). zero if no multisampling is used.

    - #### getWriteFramebuffer

          public final int getWriteFramebuffer()

      Returns the framebuffer name to render to.

    - #### getReadFramebuffer

          public final int getReadFramebuffer()

      Returns the framebuffer name to read from. Depending on multisampling, this may be a different framebuffer.

    - #### getDefaultReadBuffer

          public final int getDefaultReadBuffer()

    - #### getColorbufferCount

          public final int getColorbufferCount()

      Return the number of attached `FBObject.Colorbuffer`s

    - #### getTextureAttachmentCount

          public final int getTextureAttachmentCount()

      Return the number of attached `FBObject.TextureAttachment`s

    - #### getStencilAttachment

          public final FBObject.RenderAttachment getStencilAttachment()

      Return the stencil `FBObject.RenderAttachment` attachment, if exist. Maybe share the same `FBObject.Attachment.getName()` as `getDepthAttachment()`, if packed depth-stencil is being used.

    - #### getDepthAttachment

          public final FBObject.RenderAttachment getDepthAttachment()

      Return the depth `FBObject.RenderAttachment` attachment. Maybe share the same `FBObject.Attachment.getName()` as `getStencilAttachment()`, if packed depth-stencil is being used.

    - #### getSamplingSinkFBO

          public final FBObject getSamplingSinkFBO()

      Return the complete multisampling `FBObject` sink, if using multisampling.

    - #### getSamplingSink

          public final FBObject.Colorbuffer getSamplingSink()

      Return the multisampling `FBObject.Colorbuffer` sink, if using multisampling.

    - #### isSamplingBufferDirty

          public final boolean isSamplingBufferDirty()

      Returns `true` if the multisampling colorbuffer (msaa-buffer) has been flagged dirty by a previous call of `bind(GL)`, otherwise `false`.

    - #### toString

          public final String toString()

      Overrides:
        `toString` in class `Object`

Copyright 2010 JogAmp Community.