com.jogamp.opengl.util

## Class GLDrawableUtil

- java.lang.Object
- - com.jogamp.opengl.util.GLDrawableUtil

-     public class GLDrawableUtil
      extends Object

  Providing utility functions dealing w/ `GLDrawable`s, `GLAutoDrawable` and their `GLEventListener`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `GLDrawableUtil.ReshapeGLEventListener` `GLRunnable` to issue `GLEventListener.reshape(GLAutoDrawable, int, int, int, int)`, returning `true` on `GLRunnable.run(GLAutoDrawable)`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GLDrawableUtil()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `isAnimatorAnimating(GLAnimatorControl animatorCtrl)`
    `static boolean` | `isAnimatorAnimatingOnOtherThread(GLAnimatorControl animatorCtrl)`
    `static boolean` | `isAnimatorStarted(GLAnimatorControl animatorCtrl)`
    `static boolean` | `isAnimatorStartedOnOtherThread(GLAnimatorControl animatorCtrl)`
    `static boolean` | `isSwapGLContextSafe(GLCapabilitiesImmutable requestedCaps, GLCapabilitiesImmutable chosenCapsA, GLCapabilitiesImmutable chosenCapsB)` Return a heuristic value whether switching the `GLContext` is safe between s, i.e.
    `static void` | `moveAllGLEventListener(GLAutoDrawable src, GLAutoDrawable dest, boolean preserveInitState)` Moves all `GLEventListener` from `GLAutoDrawable` `src` to `dest`.
    `static void` | `moveGLEventListener(GLAutoDrawable src, GLAutoDrawable dest, GLEventListener listener, boolean preserveInitState)` Moves the designated `GLEventListener` from `GLAutoDrawable` `src` to `dest`.
    `static boolean` | `swapBuffersBeforeRead(GLCapabilitiesImmutable chosenCaps)` Determines whether the chosen `GLCapabilitiesImmutable` requires a `swap-buffers` before reading pixels.
    `static void` | `swapGLContext(GLAutoDrawable a, GLAutoDrawable b)` Swaps the `GLContext` of given `GLAutoDrawable` and `disposes` each `GLEventListener` w/o removing it.
    `static void` | `swapGLContextAndAllGLEventListener(GLAutoDrawable a, GLAutoDrawable b)` Swaps the `GLContext` and all `GLEventListener` between `GLAutoDrawable` `a` and `b`, while preserving it's initialized state, resets the GL-Viewport and issuing `reshape(..)`.

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

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

- - ### Constructor Detail

    - #### GLDrawableUtil

          public GLDrawableUtil()

  - ### Method Detail

    - #### isAnimatorStartedOnOtherThread

          public static final boolean isAnimatorStartedOnOtherThread(GLAnimatorControl animatorCtrl)

    - #### isAnimatorStarted

          public static final boolean isAnimatorStarted(GLAnimatorControl animatorCtrl)

    - #### isAnimatorAnimatingOnOtherThread

          public static final boolean isAnimatorAnimatingOnOtherThread(GLAnimatorControl animatorCtrl)

    - #### isAnimatorAnimating

          public static final boolean isAnimatorAnimating(GLAnimatorControl animatorCtrl)

    - #### moveGLEventListener

          public static final void moveGLEventListener(GLAutoDrawable src,
                                 GLAutoDrawable dest,
                                 GLEventListener listener,
                                 boolean preserveInitState)

      Moves the designated `GLEventListener` from `GLAutoDrawable` `src` to `dest`. If `preserveInitState` is `true`, it's initialized state is preserved and `reshape(..)` issued w/ the next `GLAutoDrawable.display()` call.

      Note that it is only legal to pass `preserveInitState := true`, if the `GLContext` of both `src` and `dest` are shared, or has itself moved from `src` to `dest`.

      Also note that the caller is encouraged to pause an attached `GLAnimatorControl`.

      Parameters:
        `src` -
        `dest` -
        `listener` -
        `preserveInitState` -

    - #### moveAllGLEventListener

          public static final void moveAllGLEventListener(GLAutoDrawable src,
                                    GLAutoDrawable dest,
                                    boolean preserveInitState)

      Moves all `GLEventListener` from `GLAutoDrawable` `src` to `dest`. If `preserveInitState` is `true`, it's initialized state is preserved and `reshape(..)` issued w/ the next `GLAutoDrawable.display()` call.

      Note that it is only legal to pass `preserveInitState := true`, if the `GLContext` of both `src` and `dest` are shared, or has itself moved from `src` to `dest`.

      Also note that the caller is encouraged to pause an attached `GLAnimatorControl`.

      Parameters:
        `src` -
        `dest` -
        `listener` -
        `preserveInitState` -

    - #### isSwapGLContextSafe

          public static boolean isSwapGLContextSafe(GLCapabilitiesImmutable requestedCaps,
                                    GLCapabilitiesImmutable chosenCapsA,
                                    GLCapabilitiesImmutable chosenCapsB)

      Return a heuristic value whether switching the `GLContext` is safe between s, i.e. via `swapGLContext(GLAutoDrawable, GLAutoDrawable)` or `swapGLContextAndAllGLEventListener(GLAutoDrawable, GLAutoDrawable)`.

      Method currently returns `false` if:

      - Switching between on- and offscreen and one of the following is `true`:
        - `MSAA is used` [1] in `chosenCapsA` or `chosenCapsB`
        - `Stereo is used` in `chosenCapsA` or `chosenCapsB`
        - `Accumulator Buffer is requested` [2] in `requestedCaps`
      Otherwise method returns `true`

           [1] See Bug 830: swapGLContextAndAllGLEventListener and onscreen MSAA w/ NV/GLX
               On NVidia GPUs w/ it's proprietary driver context swapping does not work if MSAA is involved
               and when swapping on- to offscreen.

           [2] On AMD GPUs w/ it's proprietary driver, requesting an accumulator buffer leads to receive an accumulator buffer configuration,
               for which context swapping does not work when swapping on- to offscreen and vice-versa, i.e. cannot make context current.
               With AMD and Mesa drivers we only receive an accumulator buffer if requested,
               where on NVidia drivers all configurations contain the accumulator buffer.
               On both drivers, NVidia and Mesa, context swapping with accumulator buffer works.

      Parameters:
        `requestedCaps` - requested `GLCapabilitiesImmutable` which are intended for usage by both `GLAutoDrawable`s A and B
        `chosenCapsA` - chosen `GLCapabilitiesImmutable` of `GLAutoDrawable` A, which `GLContext` is intended to be swapped
        `chosenCapsB` - chosen `GLCapabilitiesImmutable` of `GLAutoDrawable` B, which `GLContext` is intended to be swapped
      See Also:
        `swapGLContext(GLAutoDrawable, GLAutoDrawable)`, `swapGLContextAndAllGLEventListener(GLAutoDrawable, GLAutoDrawable)`

    - #### swapGLContextAndAllGLEventListener

          public static final void swapGLContextAndAllGLEventListener(GLAutoDrawable a,
                                                GLAutoDrawable b)

      Swaps the `GLContext` and all `GLEventListener` between `GLAutoDrawable` `a` and `b`, while preserving it's initialized state, resets the GL-Viewport and issuing `reshape(..)`.

      The `GLAutoDrawable` to `GLAnimatorControl` association is also swapped.

      If an `GLAnimatorControl` is being attached to `GLAutoDrawable` `a` or `b` and the current thread is different than `the animator's thread`, it is paused during the operation.

      During operation, both `auto-drawable's` `upstream-locks` and `surfaces` are locked, hence atomicity of operation is guaranteed, see GLAutoDrawable Locking.

      Because of above mentioned locking, if this method is not performed on `a OpenGL capable thread` of both `GLAutoDrawable`s, it must be invoked on such an OpenGL capable thread, e.g. via `Threading.invokeOnOpenGLThread(boolean, Runnable)`.

      Throws:
        `GLException` - if the `AbstractGraphicsDevice` are incompatible w/ each other.
      See Also:
        `isSwapGLContextSafe(GLCapabilitiesImmutable, GLCapabilitiesImmutable, GLCapabilitiesImmutable)`

    - #### swapGLContext

          public static final void swapGLContext(GLAutoDrawable a,
                           GLAutoDrawable b)

      Swaps the `GLContext` of given `GLAutoDrawable` and `disposes` each `GLEventListener` w/o removing it.

      The GL-Viewport is reset and `reshape(..)` issued implicit.

      If an `GLAnimatorControl` is being attached to GLAutoDrawable src or dest and the current thread is different than `the animator's thread`, it is paused during the operation.

      During operation, both `auto-drawable's` `upstream-locks` and `surfaces` are locked, hence atomicity of operation is guaranteed, see GLAutoDrawable Locking.

      Because of above mentioned locking, if this method is not performed on `a OpenGL capable thread` of both `GLAutoDrawable`s, it must be invoked on such an OpenGL capable thread, e.g. via `Threading.invokeOnOpenGLThread(boolean, Runnable)`.

      Parameters:
        `a` -
        `b` -
      See Also:
        `isSwapGLContextSafe(GLCapabilitiesImmutable, GLCapabilitiesImmutable, GLCapabilitiesImmutable)`

    - #### swapBuffersBeforeRead

          public static final boolean swapBuffersBeforeRead(GLCapabilitiesImmutable chosenCaps)

      Determines whether the chosen `GLCapabilitiesImmutable` requires a `swap-buffers` before reading pixels.

      Usually one uses the `default-read-buffer` in which case `swap-buffers` shall happen after calling reading pixels, the default.

      However, multisampling offscreen `GLFBODrawable`s utilize `swap-buffers` to downsample the multisamples into the readable sampling sink. In this case, we require `swap-buffers` before reading pixels.

      Returns:
        chosenCaps.isFBO() && chosenCaps.getSampleBuffers()

Copyright 2010 JogAmp Community.