javax.media.opengl

## Interface GLFBODrawable

- All Superinterfaces:
    GLDrawable, NativeSurfaceHolder
  All Known Subinterfaces:
    GLFBODrawable.Resizeable, GLOffscreenAutoDrawable.FBO

      public interface GLFBODrawable
      extends GLDrawable

  Platform-independent `GLDrawable` specialization, exposing `FBObject` functionality.

  A `GLFBODrawable` is uninitialized until a `GLContext` is bound and made current the first time, hence only then it's capabilities fully reflect expectations, i.e. color, depth, stencil and MSAA bits will be valid only after the first `makeCurrent()` call. On-/offscreen bits are valid after `setRealized(true)`.

  MSAA is used if `requested`.

  Double buffering is used if `requested`.

  In MSAA mode, it always uses the implicit 2nd `framebuffer` `sink`. Hence double buffering is always the case w/ MSAA.

  In non MSAA a second explicit `framebuffer` is being used. This method allows compliance w/ the spec, i.e. read and draw framebuffer selection and double buffer usage for e.g. `glReadPixels(..)`. This method also allows usage of both textures seperately.

  It would be possible to implement double buffering simply using `FBObject.Colorbuffer`s with one `framebuffer`. This would require mode selection and hence complicate the API. Besides, it would not support differentiation of read and write framebuffer and hence not be spec compliant.

  Actual swapping of the `FBObject.Colorbuffer`s and/or `framebuffer` is performed either in the `context current hook` or when `swapping buffers`, whatever comes first.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `GLFBODrawable.Resizeable` Resizeable `GLFBODrawable` specialization

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `FBOMODE_DEFAULT` FBO Default Mode Bit: `FBOMODE_USE_TEXTURE` | `FBOMODE_USE_DEPTH`.
    `static int` | `FBOMODE_USE_DEPTH` FBO Mode Bit: Use a depth renderbuffer (`default`), see `setFBOMode(int)`.
    `static int` | `FBOMODE_USE_TEXTURE` FBO Mode Bit: Use a `FBObject.TextureAttachment` for the `render colorbuffer` (`default`), see `setFBOMode(int)`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `FBObject.Colorbuffer` | `getColorbuffer(int bufferName)` Returns the named `FBObject.Colorbuffer` instance.
    `FBObject` | `getFBObject(int bufferName)` If MSAA is being used and `GL.GL_FRONT` is requested, the internal `FBObject` `sample sink` is being returned.
    `int` | `getFBOMode()`
    `int` | `getNumBuffers()`
    `int` | `getNumSamples()`
    `int` | `getTextureUnit()`
    `boolean` | `isInitialized()`
    `void` | `resetSize(GL gl)` Notify this instance about upstream size change to reconfigure the `FBObject`.
    `void` | `setFBOMode(int modeBits)` Set the FBO mode bits used for FBO creation.
    `int` | `setNumBuffers(int bufferCount)` Sets the number of buffers (FBO) being used if using `double buffering`.
    `void` | `setNumSamples(GL gl, int newSamples)` Set the number of sample buffers if using MSAA
    `void` | `setTextureUnit(int unit)`

    - ### Methods inherited from interface javax.media.opengl.GLDrawable

      `createContext, getChosenGLCapabilities, getFactory, getGLProfile, getHandle, getNativeSurface, getRequestedGLCapabilities, getSurfaceHeight, getSurfaceWidth, isGLOriented, isRealized, setRealized, swapBuffers, toString`

- - ### Field Detail

    - #### FBOMODE_USE_TEXTURE

          static final int FBOMODE_USE_TEXTURE

      FBO Mode Bit: Use a `FBObject.TextureAttachment` for the `render colorbuffer` (`default`), see `setFBOMode(int)`.
      See Also:
        Constant Field Values

    - #### FBOMODE_USE_DEPTH

          static final int FBOMODE_USE_DEPTH

      FBO Mode Bit: Use a depth renderbuffer (`default`), see `setFBOMode(int)`.
      See Also:
        Constant Field Values

    - #### FBOMODE_DEFAULT

          static final int FBOMODE_DEFAULT

      FBO Default Mode Bit: `FBOMODE_USE_TEXTURE` | `FBOMODE_USE_DEPTH`.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### isInitialized

          boolean isInitialized()

      Returns:
        `true` if initialized, i.e. a `GLContext` is bound and made current once, otherwise `false`.

    - #### setFBOMode

          void setFBOMode(int modeBits)
                          throws IllegalStateException

      Set the FBO mode bits used for FBO creation.

      See `FBOMODE_DEFAULT` values.

      Parameters:
        `modeBits` - custom FBO mode bits like `FBOMODE_USE_TEXTURE` and `FBOMODE_USE_DEPTH`.
      Throws:
        `IllegalStateException` - if the underlying FBO is already `isInitialized()`.

    - #### getFBOMode

          int getFBOMode()

      Returns:
        the used FBO mode bits, mutable via `setFBOMode(int)`

    - #### resetSize

          void resetSize(GL gl)
                         throws GLException

      Notify this instance about upstream size change to reconfigure the `FBObject`.
      Parameters:
        `gl` - GL context object bound to this drawable, will be made current during operation. A prev. current context will be make current after operation.
      Throws:
        `GLException` - if resize operation failed

    - #### getTextureUnit

          int getTextureUnit()

      Returns:
        the used texture unit

    - #### setTextureUnit

          void setTextureUnit(int unit)

      Parameters:
        `unit` - the texture unit to be used

    - #### setNumSamples

          void setNumSamples(GL gl,
                           int newSamples)
                             throws GLException

      Set the number of sample buffers if using MSAA
      Parameters:
        `gl` - GL context object bound to this drawable, will be made current during operation. A prev. current context will be make current after operation.
        `newSamples` - new sample size
      Throws:
        `GLException` - if resetting the FBO failed

    - #### getNumSamples

          int getNumSamples()

      Returns:
        the number of sample buffers if using MSAA, otherwise 0

    - #### setNumBuffers

          int setNumBuffers(int bufferCount)
                            throws GLException

      Sets the number of buffers (FBO) being used if using `double buffering`.

      If `double buffering` is not chosen, this is a NOP.

      Must be called before `initialization`, otherwise an exception is thrown.

      Returns:
        the new number of buffers (FBO) used, maybe different than the requested `bufferCount` (see above)
      Throws:
        `GLException` - if already initialized, see `isInitialized()`.

    - #### getNumBuffers

          int getNumBuffers()

      Returns:
        the number of buffers (FBO) being used. 1 if not using `double buffering`, otherwise ≥ 2, depending on `setNumBuffers(int)`.

    - #### getFBObject

          FBObject getFBObject(int bufferName)
                               throws IllegalArgumentException

      If MSAA is being used and `GL.GL_FRONT` is requested, the internal `FBObject` `sample sink` is being returned.
      Parameters:
        `bufferName` - `GL.GL_FRONT` and `GL.GL_BACK` are valid buffer names
      Returns:
        the named `FBObject`
      Throws:
        `IllegalArgumentException` - if an illegal buffer name is being used

    - #### getColorbuffer

          FBObject.Colorbuffer getColorbuffer(int bufferName)
                                              throws IllegalArgumentException

      Returns the named `FBObject.Colorbuffer` instance.

      If MSAA is being used, only the `GL.GL_FRONT` buffer is accessible and an exception is being thrown if `GL.GL_BACK` is being requested.

      Depending on the `fbo mode` the resulting `FBObject.Colorbuffer` is either a `FBObject.TextureAttachment` (`default`) or a `FBObject.ColorAttachment`, see `FBObject.Colorbuffer.isTextureAttachment()`.

      Parameters:
        `bufferName` - `GL.GL_FRONT` and `GL.GL_BACK` are valid buffer names
      Returns:
        the named `FBObject.Colorbuffer`
      Throws:
        `IllegalArgumentException` - if using MSAA and `GL.GL_BACK` is requested or an illegal buffer name is being used

Copyright 2010 JogAmp Community.