com.jogamp.opengl

## Class GLAutoDrawableDelegate

- java.lang.Object
- - jogamp.opengl.GLAutoDrawableBase
  - - com.jogamp.opengl.GLAutoDrawableDelegate

- All Implemented Interfaces:
    GLStateKeeper, NativeSurfaceHolder, FPSCounter, GLAutoDrawable, GLDrawable, GLSharedContextSetter

      public class GLAutoDrawableDelegate
      extends jogamp.opengl.GLAutoDrawableBase
      implements GLAutoDrawable

  Fully functional `GLAutoDrawable` implementation utilizing already created `GLDrawable` and `GLContext` instances.

  Since no native windowing system events are being processed, it is recommended to handle at least the `window events`:

  - `repaint` using `windowRepaintOp()`
  - `resize` using `#windowResizedOp()`
  and setup a `custom toolkit destruction` issuing `windowDestroyNotifyOp()`.

  See example `TestGLAutoDrawableDelegateNEWT`.

  ##### OpenGL Context Sharing

  To share a `GLContext` see the following note in the documentation overview: context sharing as well as `GLSharedContextSetter`.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface com.jogamp.opengl.GLStateKeeper

      `GLStateKeeper.Listener`

  - ### Field Summary

    - ### Fields inherited from class jogamp.opengl.GLAutoDrawableBase

      `DEBUG`

    - ### Fields inherited from interface javax.media.opengl.GLAutoDrawable

      `SCREEN_CHANGE_ACTION_ENABLED`

    - ### Fields inherited from interface javax.media.opengl.FPSCounter

      `DEFAULT_FRAMES_PER_INTERVAL`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GLAutoDrawableDelegate(GLDrawable drawable, GLContext context, Object upstreamWidget, boolean ownDevice, RecursiveLock lock)` The `GLContext` can be assigned later manually via `setContext(ctx)` or it will be created lazily at the 1st `display()` method call. Lazy `GLContext` creation will take a shared `GLContext` into account which has been set `directly` or `via another GLAutoDrawable`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `GLDrawableFactory` | `getFactory()` Return the `GLDrawableFactory` being used to create this instance.
    `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.
    `void` | `setUpstreamWidget(Object newUpstreamWidget)` Set the upstream UI toolkit object.
    `void` | `swapBuffers()` Swaps the front and back buffers of this drawable.
    `String` | `toString()`
    `void` | `windowDestroyNotifyOp()` Implementation to handle destroy notifications from the windowing system.
    `void` | `windowRepaintOp()` Default implementation to handle repaint events from the windowing system
    `void` | `windowResizedOp(int newWidth, int newHeight)` Handling resize events from the windowing system.

    - ### Methods inherited from class jogamp.opengl.GLAutoDrawableBase

      `addGLEventListener, addGLEventListener, areAllGLEventListenerInitialized, clearPreservedGLState, createContext, defaultSwapBuffers, disposeGLEventListener, flushGLRunnables, getAnimator, getAutoSwapBufferMode, getChosenGLCapabilities, getContext, getContextCreationFlags, getDelegatedDrawable, getExclusiveContextThread, getFPSStartTime, getGL, getGLEventListener, getGLEventListenerCount, getGLEventListenerInitState, getGLProfile, getHandle, getLastFPS, getLastFPSPeriod, getLastFPSUpdateTime, getNativeSurface, getPreservedGLState, getRequestedGLCapabilities, getSurfaceHeight, getSurfaceWidth, getTotalFPS, getTotalFPSDuration, getTotalFPSFrames, getUpdateFPSFrames, invoke, invoke, isGLOriented, isGLStatePreservationSupported, isRealized, isThreadGLCapable, preserveGLStateAtDestroy, removeGLEventListener, resetFPSCounter, setAnimator, setAutoSwapBufferMode, setContext, setContextCreationFlags, setExclusiveContextThread, setGL, setGLEventListenerInitState, setGLStateKeeperListener, setRealized, setSharedAutoDrawable, setSharedContext, setUpdateFPSFrames`

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

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

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

      `addGLEventListener, addGLEventListener, areAllGLEventListenerInitialized, createContext, disposeGLEventListener, flushGLRunnables, getAnimator, getAutoSwapBufferMode, getContext, getContextCreationFlags, getDelegatedDrawable, getExclusiveContextThread, getGL, getGLEventListener, getGLEventListenerCount, getGLEventListenerInitState, invoke, invoke, isThreadGLCapable, removeGLEventListener, setAnimator, setAutoSwapBufferMode, setContext, setContextCreationFlags, setExclusiveContextThread, setGL, setGLEventListenerInitState`

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

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

- - ### Constructor Detail

    - #### GLAutoDrawableDelegate

          public GLAutoDrawableDelegate(GLDrawable drawable,
                                GLContext context,
                                Object upstreamWidget,
                                boolean ownDevice,
                                RecursiveLock lock)

      The `GLContext` can be assigned later manually via `setContext(ctx)` or it will be created lazily at the 1st `display()` method call.
      Lazy `GLContext` creation will take a shared `GLContext` into account which has been set `directly` or `via another GLAutoDrawable`.

      Parameters:
        `drawable` - a valid `GLDrawable`, may not be `realized` yet.
        `context` - a valid `GLContext`, may not have been made current (created) yet, may not be associated w/ `drawable`yet, may be `null` for lazy initialization at 1st `display()`.``
        `upstreamWidget` - optional UI element holding this instance, see `getUpstreamWidget()`.
        `ownDevice` - pass `true` if `AbstractGraphicsDevice.close()` shall be issued, otherwise pass `false`. Closing the device is required in case the drawable is created w/ it's own new instance, e.g. offscreen drawables, and no further lifecycle handling is applied.
        `lock` - optional custom `RecursiveLock`.

  - ### Method Detail

    - #### windowRepaintOp

          public final void windowRepaintOp()

      Default implementation to handle repaint events from the windowing system

    - #### windowResizedOp

          public final void windowResizedOp(int newWidth,
                             int newHeight)

      Handling resize events from the windowing system.

      Implementation:

      - resizes `the GLDrawable`, if offscreen,
      - triggers a pending `reshape events`, and
      - issues a `display()` call, if no animator is present.

      All required locks are being claimed.

      Parameters:
        `newWidth` - new width in pixel units
        `newWidth` - new height in pixel units

    - #### windowDestroyNotifyOp

          public final void windowDestroyNotifyOp()

      Implementation to handle destroy notifications from the windowing system.

      If the `NativeSurface` does not implement `WindowClosingProtocol` or `WindowClosingProtocol.WindowClosingMode.DISPOSE_ON_CLOSE` is enabled (default), a thread safe destruction is being induced.

    - #### getUpstreamLock

          public final RecursiveLock getUpstreamLock()

      Description copied from interface: `GLAutoDrawable`
      Returns the recursive lock object of the `upstream widget` to synchronize multithreaded access on top of `NativeSurface.lockSurface()`.

      See GLAutoDrawable Locking.

      Specified by:
        `getUpstreamLock` in interface `GLAutoDrawable`

    - #### getUpstreamWidget

          public final Object getUpstreamWidget()

      Description copied from interface: `GLAutoDrawable`
      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 | `GLWindow` | has a | `Window`
      SWT | `GLCanvas` | is a | `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.

      Specified by:
        `getUpstreamWidget` in interface `GLAutoDrawable`

    - #### setUpstreamWidget

          public final void setUpstreamWidget(Object newUpstreamWidget)

      Set the upstream UI toolkit object.
      See Also:
        `getUpstreamWidget()`

    - #### destroy

          public final 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.

      This implementation calls `GLAutoDrawableBase.defaultDestroy()`.

      User still needs to destroy the upstream window, which details are hidden from this aspect. This can be performed by overriding `destroyImplInLock()`.

      Specified by:
        `destroy` in interface `GLAutoDrawable`

    - #### display

          public void display()

      Description copied from interface: `GLAutoDrawable`

      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 `GLAutoDrawable.invoke(boolean, GLRunnable)`.

      May be called periodically by a running `GLAnimatorControl` implementation,
      which must register itself with `GLAutoDrawable.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.

      Specified by:
        `display` in interface `GLAutoDrawable`
      See Also:
        `GLAutoDrawable.setAnimator(javax.media.opengl.GLAnimatorControl)`

    - #### getFactory

          public final GLDrawableFactory getFactory()

      Description copied from interface: `GLDrawable`
      Return the `GLDrawableFactory` being used to create this instance.
      Specified by:
        `getFactory` in interface `GLDrawable`

    - #### swapBuffers

          public final void swapBuffers()
                                 throws GLException

      Description copied from interface: `GLDrawable`
      Swaps the front and back buffers of this drawable. For `GLAutoDrawable` implementations, when automatic buffer swapping is enabled (as is the default), this method is called automatically and should not be called by the end user.
      Specified by:
        `swapBuffers` in interface `GLDrawable`
      Throws:
        `GLException`

    - #### toString

          public String toString()

      Specified by:
        `toString` in interface `GLDrawable`
      Overrides:
        `toString` in class `jogamp.opengl.GLAutoDrawableBase`

Copyright 2010 JogAmp Community.