javax.media.opengl

## Interface GLAutoDrawable

- All Superinterfaces:
    GLDrawable, NativeSurfaceHolder
  All Known Subinterfaces:
    AWTGLAutoDrawable, GLOffscreenAutoDrawable, GLOffscreenAutoDrawable.FBO, GLSharedContextSetter
  All Known Implementing Classes:
    GLCanvas, GLJPanel

      public interface GLAutoDrawable
      extends GLDrawable

  A higher-level abstraction than `GLDrawable` which supplies an event based mechanism (`GLEventListener`) for performing OpenGL rendering. A GLAutoDrawable automatically creates a primary rendering context which is associated with the GLAutoDrawable for the lifetime of the object.

  Since the `GLContext` `makeCurrent` implementation is synchronized, i.e. blocks if the context is current on another thread, the internal `GLContext` for the GLAutoDrawable can be used for the event based rendering mechanism and by end users directly.

  ##### GLAutoDrawable Initialization

  The implementation shall initialize itself as soon as possible, which is only possible after the attached `NativeSurface` becomes visible and and is realized.
  The following initialization sequence should be implemented:

  - Create the `GLDrawable` with the requested `GLCapabilities`
  - Notify `GLDrawable` to validate the `GLCapabilities` by calling `setRealized(true)`.
  - Create the new `GLContext`.
  - Initialize all OpenGL resources by calling `init(..)` for all registered `GLEventListener`s. This can be done immediately, or with the followup `display(..)` call.
  - Send a reshape event by calling `reshape(..)` for all registered `GLEventListener`s. This shall be done after the `init(..)` calls.
  Note: The last to `GLEventListener` actions shall be also performed, when `adding` a new one to an already initialized `GLAutoDrawable`.

  ##### GLAutoDrawable Reconfiguration

  Another implementation detail is the `GLDrawable` reconfiguration. One use case is where a window is being dragged to another screen with a different pixel configuration, ie `GLCapabilities`. The implementation shall be able to detect such cases in conjunction with the associated `NativeSurface`.
  For example, AWT's `Canvas` 's `getGraphicsConfiguration()` is capable to determine a display device change. This is demonstrated within `GLCanvas`'s and NEWT's `AWTCanvas` `getGraphicsConfiguration()` specialization. Another demonstration is NEWT's `NativeWindow` implementation on the Windows platform, which utilizes the native platform's MonitorFromWindow(HWND) function.
  All OpenGL resources shall be regenerated, while the drawable's `GLCapabilities` has to be chosen again. The following protocol shall be satisfied.

  - Controlled disposal:
  - Dispose all OpenGL resources by calling `dispose(..)` for all registered `GLEventListener`s.
  - Destroy the `GLContext`.
  - Notify `GLDrawable` of the invalid state by calling `setRealized(false)`.
  - Controlled regeneration:
  - Create the new `GLDrawable` with the requested `GLCapabilities`
  - Notify `GLDrawable` to revalidate the `GLCapabilities` by calling `setRealized(true)`.
  - Create the new `GLContext`.
  - Initialize all OpenGL resources by calling `init(..)` for all registered `GLEventListener`s. This can be done immediatly, or with the followup `display(..)` call.
  - Send a reshape event by calling `reshape(..)` for all registered `GLEventListener`s. This shall be done after the `init(..)` calls.
  Note: Current graphics driver keep the surface configuration for a given window, even if the window is moved to a monitor with a different pixel configuration, ie 32bpp to 16bpp. However, it is best to not assume such behavior and make your application comply with the above protocol.

  Avoiding breakage with older applications and because of the situation mentioned above, the `boolean` system property `jogl.screenchange.action` will control the screen change action as follows:

          -Djogl.screenchange.action=false Disable the GLDrawable reconfiguration (the default)
          -Djogl.screenchange.action=true  Enable  the GLDrawable reconfiguration

  ##### GLAutoDrawable Locking

  GLAutoDrawable implementations perform locking in the following order:
  1. `getUpstreamLock()`.`lock()`
  2. `GLDrawable.getNativeSurface()`.`lockSurface()`
  and releases the locks accordingly:
  1. `GLDrawable.getNativeSurface()`.`unlockSurface()`
  2. `getUpstreamLock()`.`unlock()`
  Above locking order is mandatory to guarantee atomicity of operation and to avoid race-conditions. A custom implementation or user applications requiring exclusive access shall follow the locking order. See:
  - `getUpstreamLock()`
  - `invoke(boolean, GLRunnable)`
  - `invoke(boolean, List)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `SCREEN_CHANGE_ACTION_ENABLED` Flag reflecting whether the `GLDrawable` reconfiguration will be issued in case a screen device change occurred, e.g.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addGLEventListener(GLEventListener listener)` Adds the given `listener` to the end of this drawable queue.
    `void` | `addGLEventListener(int index, GLEventListener listener)` Adds the given `listener` at the given index of this drawable queue.
    `boolean` | `areAllGLEventListenerInitialized()` Returns true if all added `GLEventListener` are initialized, otherwise false.
    `GLContext` | `createContext(GLContext shareWith)` Creates a new context for drawing to this drawable that will optionally share buffer objects, textures and other server-side OpenGL objects with the specified GLContext.
    `void` | `destroy()` Destroys all resources associated with this GLAutoDrawable, inclusive the GLContext.
    `void` | `display()` Causes OpenGL rendering to be performed for this GLAutoDrawable in the following order: Calling `display(..)` for all registered `GLEventListener`s.
    `GLEventListener` | `disposeGLEventListener(GLEventListener listener, boolean remove)` Disposes the given `listener` via `dispose(..)` if it has been initialized and added to this queue.
    `void` | `flushGLRunnables()` Flushes all `enqueued` `GLRunnable` of this `GLAutoDrawable` including notifying waiting executor.
    `GLAnimatorControl` | `getAnimator()`
    `boolean` | `getAutoSwapBufferMode()` Indicates whether automatic buffer swapping is enabled for this drawable.
    `GLContext` | `getContext()` Returns the context associated with this drawable.
    `int` | `getContextCreationFlags()`
    `GLDrawable` | `getDelegatedDrawable()` If the implementation uses delegation, return the delegated `GLDrawable` instance, otherwise return `this` instance.
    `Thread` | `getExclusiveContextThread()`
    `GL` | `getGL()` Returns the `GL` pipeline object this GLAutoDrawable uses.
    `GLEventListener` | `getGLEventListener(int index)` Returns the `GLEventListener` at the given index of this drawable queue.
    `int` | `getGLEventListenerCount()` Returns the number of `GLEventListener` of this drawable queue.
    `boolean` | `getGLEventListenerInitState(GLEventListener listener)` Retrieves whether the given `listener` is initialized or not.
    `RecursiveLock` | `getUpstreamLock()` Returns the recursive lock object of the `upstream widget` to synchronize multithreaded access on top of `NativeSurface.lockSurface()`.
    `Object` | `getUpstreamWidget()` Method may return the upstream UI toolkit object holding this `GLAutoDrawable` instance, if exist.
    `boolean` | `invoke(boolean wait, GLRunnable glRunnable)` Enqueues a one-shot `GLRunnable`, which will be executed within the next `display()` call after all registered `GLEventListener`s `display(GLAutoDrawable)` methods have been called.
    `boolean` | `invoke(boolean wait, List<GLRunnable> glRunnables)` Extends `invoke(boolean, GLRunnable)` functionality allowing to inject a list of `GLRunnable`s.
    `boolean` | `isThreadGLCapable()` Indicates whether the current thread is capable of performing OpenGL-related work.
    `GLEventListener` | `removeGLEventListener(GLEventListener listener)` Removes the given `listener` from this drawable queue.
    `void` | `setAnimator(GLAnimatorControl animatorControl)` Registers the usage of an animator, an `GLAnimatorControl` implementation.
    `void` | `setAutoSwapBufferMode(boolean enable)` Enables or disables automatic buffer swapping for this drawable.
    `GLContext` | `setContext(GLContext newCtx, boolean destroyPrevCtx)` Associate the new context, `newtCtx`, to this auto-drawable.
    `void` | `setContextCreationFlags(int flags)`
    `Thread` | `setExclusiveContextThread(Thread t)` Dedicates this instance's `GLContext` to the given thread. The thread will exclusively claim the `GLContext` via `display()` and not release it until `destroy()` or `setExclusiveContextThread(null)` has been called.
    `GL` | `setGL(GL gl)` Sets the `GL` pipeline object this GLAutoDrawable uses.
    `void` | `setGLEventListenerInitState(GLEventListener listener, boolean initialized)` Sets the given `listener's` initialized state.

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

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

- - ### Field Detail

    - #### SCREEN_CHANGE_ACTION_ENABLED

          static final boolean SCREEN_CHANGE_ACTION_ENABLED

      Flag reflecting whether the `GLDrawable` reconfiguration will be issued in case a screen device change occurred, e.g. in a multihead environment, where you drag the window to another monitor.

  - ### Method Detail

    - #### getDelegatedDrawable

          GLDrawable getDelegatedDrawable()

      If the implementation uses delegation, return the delegated `GLDrawable` instance, otherwise return `this` instance.

    - #### getContext

          GLContext getContext()

      Returns the context associated with this drawable. The returned context will be synchronized. Don't rely on it's identity, the context may change.

    - #### setContext

          GLContext setContext(GLContext newCtx,
                             boolean destroyPrevCtx)

      Associate the new context, `newtCtx`, to this auto-drawable.

      Remarks:

      - The currently associated context will be destroyed if `destroyPrevCtx` is `true`, otherwise it will be disassociated from this auto-drawable via `setGLDrawable(null, true);` including `glFinish()`.
      - The new context will be associated with this auto-drawable via `newCtx.setGLDrawable(drawable, true);`.
      - If the old context was current on this thread, it is being released after disassociating this auto-drawable.
      - If the new context was current on this thread, it is being released before associating this auto-drawable and made current afterwards.
      - Implementation may issue `#makeCurrent()` and `#release()` while drawable reassociation.
      - The user shall take extra care of thread synchronization, i.e. lock the involved `auto-drawable's` `upstream-locks` and `surfaces` to avoid a race condition. See GLAutoDrawable Locking.
      Parameters:
        `newCtx` - the new context, maybe `null` for dis-association.
        `destroyPrevCtx` - if `true`, destroy the previous context if exists
      Returns:
        the previous GLContext, maybe `null`
      See Also:
        `GLContext.setGLDrawable(GLDrawable, boolean)`, `GLContext.setGLReadDrawable(GLDrawable)`, `GLDrawableHelper.switchContext(GLDrawable, GLContext, boolean, GLContext, int)`

    - #### addGLEventListener

          void addGLEventListener(GLEventListener listener)

      Adds the given `listener` to the end of this drawable queue. The `listeners` are notified of events in the order of the queue.

      The newly added listener's `init(..)` method will be called once before any other of it's callback methods. See `getGLEventListenerInitState(GLEventListener)` for details.

      Parameters:
        `listener` - The GLEventListener object to be inserted

    - #### addGLEventListener

          void addGLEventListener(int index,
                                GLEventListener listener)
                                  throws IndexOutOfBoundsException

      Adds the given `listener` at the given index of this drawable queue. The `listeners` are notified of events in the order of the queue.

      The newly added listener's `init(..)` method will be called once before any other of it's callback methods. See `getGLEventListenerInitState(GLEventListener)` for details.

      Parameters:
        `index` - Position where the listener will be inserted. Should be within (0 <= index && index <= size()). An index value of -1 is interpreted as the end of the list, size().
        `listener` - The GLEventListener object to be inserted
      Throws:
        `IndexOutOfBoundsException` - If the index is not within (0 <= index && index <= size()), or -1

    - #### getGLEventListenerCount

          int getGLEventListenerCount()

      Returns the number of `GLEventListener` of this drawable queue.
      Returns:
        The number of GLEventListener objects of this drawable queue.

    - #### areAllGLEventListenerInitialized

          boolean areAllGLEventListenerInitialized()

      Returns true if all added `GLEventListener` are initialized, otherwise false.
      Since:
        2.2

    - #### getGLEventListener

          GLEventListener getGLEventListener(int index)
                                             throws IndexOutOfBoundsException

      Returns the `GLEventListener` at the given index of this drawable queue.
      Parameters:
        `index` - Position of the listener to be returned. Should be within (0 <= index && index < size()). An index value of -1 is interpreted as last listener, size()-1.
      Returns:
        The GLEventListener object at the given index.
      Throws:
        `IndexOutOfBoundsException` - If the index is not within (0 <= index && index < size()), or -1

    - #### getGLEventListenerInitState

          boolean getGLEventListenerInitState(GLEventListener listener)

      Retrieves whether the given `listener` is initialized or not.

      After `adding` a `GLEventListener` it is marked uninitialized and added to a list of to be initialized `GLEventListener`. If such uninitialized `GLEventListener`'s handler methods (reshape, display) are about to be invoked, it's `init(..)` method is invoked first. Afterwards the `GLEventListener` is marked initialized and removed from the list of to be initialized `GLEventListener`.

      This methods returns the `GLEventListener` initialized state, i.e. returns `false` if it is included in the list of to be initialized `GLEventListener`, otherwise `true`.

      Parameters:
        `listener` - the GLEventListener object to query it's initialized state.

    - #### setGLEventListenerInitState

          void setGLEventListenerInitState(GLEventListener listener,
                                         boolean initialized)

      Sets the given `listener's` initialized state.

      This methods allows manually setting the `GLEventListener` initialized state, i.e. adding it to, or removing it from the list of to be initialized `GLEventListener`. See `getGLEventListenerInitState(GLEventListener)` for details.

      Warning: This method does not validate whether the given `listener's` is member of this drawable queue, i.e. `added`.

      This method is only exposed to allow users full control over the `GLEventListener`'s state and is usually not recommended to change.

      One use case is moving a `GLContext` and their initialized `GLEventListener` from one `GLAutoDrawable` to another, where a subsequent `init(..)` call after adding it to the new owner is neither required nor desired. See `swapGLContextAndAllGLEventListener(..)`.

      Parameters:
        `listener` - the GLEventListener object to perform a state change.
        `initialized` - if `true`, mark the listener initialized, otherwise uninitialized.

    - #### disposeGLEventListener

          GLEventListener disposeGLEventListener(GLEventListener listener,
                                               boolean remove)

      Disposes the given `listener` via `dispose(..)` if it has been initialized and added to this queue.

      If `remove` is `true`, the `GLEventListener` is removed from this drawable queue before disposal, otherwise marked uninitialized.

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

      Note that this is an expensive operation, since `dispose(..)` is decorated by `GLContext.makeCurrent()` and `GLContext.release()`.

      Use `removeGLEventListener(listener)` instead if you just want to remove the `listener` and don't care about the disposal of the it's (OpenGL) resources.

      Also note that this is done from within a particular drawable's `GLEventListener` handler (reshape, display, etc.), that it is not guaranteed that all other listeners will be evaluated properly during this update cycle.

      Parameters:
        `listener` - The GLEventListener object to be disposed and removed if `remove` is `true`
        `remove` - pass `true` to have the `listener` removed from this drawable queue, otherwise pass `false`
      Returns:
        the disposed and/or removed GLEventListener, or null if no action was performed, i.e. listener was not added

    - #### removeGLEventListener

          GLEventListener removeGLEventListener(GLEventListener listener)

      Removes the given `listener` from this drawable queue.

      This is an inexpensive operation, since the removed listener's `dispose(..)` method will not be called.

      Use `disposeGLEventListener(listener, true)` instead to ensure disposal of the `listener`'s (OpenGL) resources.

      Note that if this is done from within a particular drawable's `GLEventListener` handler (reshape, display, etc.), that it is not guaranteed that all other listeners will be evaluated properly during this update cycle.

      Parameters:
        `listener` - The GLEventListener object to be removed
      Returns:
        the removed GLEventListener, or null if listener was not added

    - #### setAnimator

          void setAnimator(GLAnimatorControl animatorControl)
                           throws GLException

      Registers the usage of an animator, an `GLAnimatorControl` implementation. The animator will be queried whether it's animating, ie periodically issuing `display()` calls or not.

      This method shall be called by an animator implementation only,
      e.g. `AnimatorBase.add(javax.media.opengl.GLAutoDrawable)`, passing it's control implementation,
      and `AnimatorBase.remove(javax.media.opengl.GLAutoDrawable)`, passing `null`.

      Impacts `display()` and `invoke(boolean, GLRunnable)` semantics.

      Parameters:
        `animatorControl` - `null` reference indicates no animator is using this `GLAutoDrawable`,
        a valid reference indicates an animator is using this `GLAutoDrawable`.
      Throws:
        `GLException` - if an animator is already registered.
      See Also:
        `display()`, `invoke(boolean, GLRunnable)`, `GLAnimatorControl`

    - #### getAnimator

          GLAnimatorControl getAnimator()

      Returns:
        the registered `GLAnimatorControl` implementation, using this `GLAutoDrawable`.
      See Also:
        `setAnimator(javax.media.opengl.GLAnimatorControl)`, `GLAnimatorControl`

    - #### setExclusiveContextThread

          Thread setExclusiveContextThread(Thread t)
                                           throws GLException

      Dedicates this instance's `GLContext` to the given thread.
      The thread will exclusively claim the `GLContext` via `display()` and not release it until `destroy()` or `setExclusiveContextThread(null)` has been called.

      Default non-exclusive behavior is requested via `setExclusiveContextThread(null)`, which will cause the next call of `display()` on the exclusive thread to release the `GLContext`. Only after it's async release, `getExclusiveContextThread()` will return `null`.

      To release a previous made exclusive thread, a user issues `setExclusiveContextThread(null)` and may poll `getExclusiveContextThread()` until it returns `null`, while the exclusive thread is still running.

      Note: Setting a new exclusive thread without properly releasing a previous one will throw an GLException.

      Note: Utilizing this feature w/ AWT could lead to an AWT-EDT deadlock, depending on the AWT implementation. Hence it is advised not to use it with native AWT GLAutoDrawable like GLCanvas.

      One scenario could be to dedicate the context to the `animator thread` and spare redundant context switches, see `AnimatorBase.setExclusiveContext(boolean)`.

      Parameters:
        `t` - the exclusive thread to claim the context, or `null` for default operation.
      Returns:
        previous exclusive context thread
      Throws:
        `GLException` - If an exclusive thread is still active but a new one is attempted to be set
      See Also:
        `AnimatorBase.setExclusiveContext(boolean)`

    - #### getExclusiveContextThread

          Thread getExclusiveContextThread()

      See Also:
        `setExclusiveContextThread(Thread)`

    - #### invoke

          boolean invoke(boolean wait,
                       GLRunnable glRunnable)
                         throws IllegalStateException

      Enqueues a one-shot `GLRunnable`, which will be executed within the next `display()` call after all registered `GLEventListener`s `display(GLAutoDrawable)` methods have been called.

      If no `GLAnimatorControl` is animating (default),
      or if the current thread is the animator thread,
      a `display()` call is issued after enqueue the `GLRunnable`, hence the `GLRunnable` will be executed right away.

      If an `animator` is running,
      no explicit `display()` call is issued, allowing the `animator` to perform at due time.

      If `wait` is `true` the call blocks until the `glRunnable` has been executed by the `animator`, otherwise the method returns immediately.

      If `wait` is `true` and `GLDrawable.isRealized()` returns `false` or `getContext()` returns `null`, the call is ignored and returns `false`.
      This helps avoiding deadlocking the caller.

      The internal queue of `GLRunnable`'s is being flushed with `destroy()` where all blocked callers are being notified.

      To avoid a deadlock situation which causes an `IllegalStateException` one should avoid issuing `invoke` while this GLAutoDrawable is being locked.
      Detected deadlock situations throwing an `IllegalStateException` are:

      - `Animator` is running on another thread and waiting and is locked on current thread, but is not `GL-Thread`
      - No `Animator` is running on another thread and is locked on current thread, but is not `GL-Thread`
      Parameters:
        `wait` - if `true` block until execution of `glRunnable` is finished, otherwise return immediately w/o waiting
        `glRunnable` - the `GLRunnable` to execute within `display()`
      Returns:
        `true` if the `GLRunnable` has been processed or queued, otherwise `false`.
      Throws:
        `IllegalStateException` - in case of a detected deadlock situation ahead, see above.
      See Also:
        `setAnimator(GLAnimatorControl)`, `display()`, `GLRunnable`, `invoke(boolean, List)`, `flushGLRunnables()`

    - #### invoke

          boolean invoke(boolean wait,
                       List<GLRunnable> glRunnables)
                         throws IllegalStateException

      Extends `invoke(boolean, GLRunnable)` functionality allowing to inject a list of `GLRunnable`s.
      Parameters:
        `wait` - if `true` block until execution of the last `glRunnable` is finished, otherwise return immediately w/o waiting
        `glRunnables` - the `GLRunnable`s to execute within `display()`
      Returns:
        `true` if the `GLRunnable`s has been processed or queued, otherwise `false`.
      Throws:
        `IllegalStateException` - in case of a detected deadlock situation ahead, see `invoke(boolean, GLRunnable)`.
      See Also:
        `invoke(boolean, GLRunnable)`, `flushGLRunnables()`

    - #### flushGLRunnables

          void flushGLRunnables()

      Flushes all `enqueued` `GLRunnable` of this `GLAutoDrawable` including notifying waiting executor.

      The executor which might have been blocked until notified will be unblocked and all tasks removed from the queue.

      Since:
        2.2
      See Also:
        `invoke(boolean, GLRunnable)`

    - #### destroy

          void destroy()

      Destroys all resources associated with this GLAutoDrawable, inclusive the GLContext. If a window is attached to it's implementation, it shall be closed. Causes disposing of all OpenGL resources by calling `dispose(..)` for all registered `GLEventListener`s. Called automatically by the window system toolkit upon receiving a destroy notification. This routine may be called manually.

    - #### display

          void display()

      Causes OpenGL rendering to be performed for this GLAutoDrawable in the following order:

      - Calling `display(..)` for all registered `GLEventListener`s.
      - Executes all one-shot `GLRunnable`, enqueued via `invoke(boolean, GLRunnable)`.

      May be called periodically by a running `GLAnimatorControl` implementation,
      which must register itself with `setAnimator(javax.media.opengl.GLAnimatorControl)`.

      Called automatically by the window system toolkit upon receiving a repaint() request,
      except an `GLAnimatorControl` implementation `GLAnimatorControl.isAnimating()`.

      This routine may also be called manually for better control over the rendering process. It is legal to call another GLAutoDrawable's display method from within the `display(..)` callback.

      In case of a new generated OpenGL context, the implementation shall call `init(..)` for all registered `GLEventListener`s before making the actual `display(..)` calls, in case this has not been done yet.

      See Also:
        `setAnimator(javax.media.opengl.GLAnimatorControl)`

    - #### setAutoSwapBufferMode

          void setAutoSwapBufferMode(boolean enable)

      Enables or disables automatic buffer swapping for this drawable. By default this property is set to true; when true, after all GLEventListeners have been called for a display() event, the front and back buffers are swapped, displaying the results of the render. When disabled, the user is responsible for calling `GLDrawable.swapBuffers(..)` manually.

    - #### getAutoSwapBufferMode

          boolean getAutoSwapBufferMode()

      Indicates whether automatic buffer swapping is enabled for this drawable. See `setAutoSwapBufferMode(boolean)`.

    - #### setContextCreationFlags

          void setContextCreationFlags(int flags)

      Parameters:
        `flags` - Additional context creation flags.
      See Also:
        `GLContext.setContextCreationFlags(int)`, `GLContext.enableGLDebugMessage(boolean)`

    - #### getContextCreationFlags

          int getContextCreationFlags()

      Returns:
        Additional context creation flags

    - #### createContext

          GLContext createContext(GLContext shareWith)

      Creates a new context for drawing to this drawable that will optionally share buffer objects, textures and other server-side OpenGL objects with the specified GLContext.

      The GLContext `share` need not be associated with this GLDrawable and may be null if sharing of display lists and other objects is not desired. See the note in the overview documentation context sharing as well as `GLSharedContextSetter`.

      This GLAutoDrawable implementation holds it's own GLContext reference, thus created a GLContext using this methods won't replace it implicitly. To replace or set this GLAutoDrawable's GLContext you need to call `setContext(GLContext, boolean)`.

      The GLAutoDrawable implementation shall also set the context creation flags as customized w/ `setContextCreationFlags(int)`.

      Specified by:
        `createContext` in interface `GLDrawable`

    - #### getGL

          GL getGL()

      Returns the `GL` pipeline object this GLAutoDrawable uses. If this method is called outside of the `GLEventListener`'s callback methods (init, display, etc.) it may return null. Users should not rely on the identity of the returned GL object; for example, users should not maintain a hash table with the GL object as the key. Additionally, the GL object should not be cached in client code, but should be re-fetched from the GLAutoDrawable at the beginning of each call to init, display, etc.

    - #### setGL

          GL setGL(GL gl)

      Sets the `GL` pipeline object this GLAutoDrawable uses. This should only be called from within the GLEventListener's callback methods, and usually only from within the init() method, in order to install a composable pipeline. See the JOGL demos for examples.
      Returns:
        the set GL pipeline or null if not successful

    - #### getUpstreamWidget

          Object getUpstreamWidget()

      Method may return the upstream UI toolkit object holding this `GLAutoDrawable` instance, if exist.

      Currently known Java UI toolkits and it's known return types are:

      Toolkit | GLAutoDrawable Implementation | ~ | Return Type of getUpstreamWidget()
      NEWT | `com.jogamp.newt.opengl.GLWindow` | has a | `com.jogamp.newt.Window`
      SWT | `com.jogamp.opengl.swt.GLCanvas` | is a | `org.eclipse.swt.widgets.Canvas`
      AWT | `GLCanvas` | is a | `Canvas`
      AWT | `GLJPanel` | is a | `JPanel`

      However, the result may be other object types than the listed above due to new supported toolkits.

      This method may also return `null` if no UI toolkit is being used, as common for offscreen rendering.

    - #### getUpstreamLock

          RecursiveLock getUpstreamLock()

      Returns the recursive lock object of the `upstream widget` to synchronize multithreaded access on top of `NativeSurface.lockSurface()`.

      See GLAutoDrawable Locking.

      Since:
        2.2

    - #### isThreadGLCapable

          boolean isThreadGLCapable()

      Indicates whether the current thread is capable of performing OpenGL-related work.

      Implementation utilizes this knowledge to determine whether `display()` performs the OpenGL commands on the current thread directly or spawns them on the dedicated OpenGL thread.

      Since:
        2.2

Copyright 2010 JogAmp Community.