com.jogamp.opengl

## Class GLEventListenerState

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

-     public class GLEventListenerState
      extends Object

  GLEventListenerState is holding `GLAutoDrawable` components crucial to relocating all its `GLEventListener` w/ their operating `GLContext`, etc. The components are:
  - `GLContext`
  - All `GLEventListener`, incl. their init state
  - `GLAnimatorControl`
  - `AbstractGraphicsDevice` for compatibility check and preserving the native device handle incl. ownership

  A GLEventListenerState instance can be created while components are `moved from` a `GLAutoDrawable` to the new instance, which gains `ownership` of the moved components.

  A GLEventListenerState instance's components can be `moved to` a `GLAutoDrawable`, while loosing `ownership` of the moved components.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `GLAnimatorControl` | `anim`
    `boolean` | `animStarted`
    `GLCapabilitiesImmutable` | `caps`
    `GLContext` | `context`
    `AbstractGraphicsDevice` | `device`
    `GLEventListener[]` | `listeners`
    `boolean[]` | `listenersInit`
    `boolean` | `proxyOwnsUpstreamDevice`
    `AbstractGraphicsDevice` | `upstreamDevice`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` Last resort to destroy and loose ownership
    `Runnable` | `getUnlockSurfaceOp()` Returns a `Runnable` `unlocking` an eventually locked `NativeSurface`, see `moveFrom(GLAutoDrawable, boolean)` and `moveTo(GLAutoDrawable, Runnable)`.
    `boolean` | `isOwner()` Returns `true`, if this instance is the current owner of the components, otherwise `false`.
    `int` | `listenerCount()`
    `static GLEventListenerState` | `moveFrom(GLAutoDrawable src)` Moves all GLEventListenerState components from the given `GLAutoDrawable` to a newly created instance.
    `static GLEventListenerState` | `moveFrom(GLAutoDrawable src, boolean keepLocked)` Moves all GLEventListenerState components from the given `GLAutoDrawable` to a newly created instance.
    `void` | `moveTo(GLAutoDrawable dest)` Moves all GLEventListenerState components to the given `GLAutoDrawable` from this instance, while loosing `ownership`.
    `void` | `moveTo(GLAutoDrawable dest, Runnable destUnlockOperation)` Moves all GLEventListenerState components to the given `GLAutoDrawable` from this instance, while loosing `ownership`.

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

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

- - ### Field Detail

    - #### upstreamDevice

          public final AbstractGraphicsDevice upstreamDevice

    - #### proxyOwnsUpstreamDevice

          public final boolean proxyOwnsUpstreamDevice

    - #### device

          public final AbstractGraphicsDevice device

    - #### caps

          public final GLCapabilitiesImmutable caps

    - #### context

          public final GLContext context

    - #### listeners

          public final GLEventListener[] listeners

    - #### listenersInit

          public final boolean[] listenersInit

    - #### anim

          public final GLAnimatorControl anim

    - #### animStarted

          public final boolean animStarted

  - ### Method Detail

    - #### isOwner

          public final boolean isOwner()

      Returns `true`, if this instance is the current owner of the components, otherwise `false`.

      Ownership is lost if `moveTo(GLAutoDrawable)` is being called successfully and all components are transferred to the new `GLAutoDrawable`.

    - #### listenerCount

          public final int listenerCount()

    - #### getUnlockSurfaceOp

          public Runnable getUnlockSurfaceOp()

      Returns a `Runnable` `unlocking` an eventually locked `NativeSurface`, see `moveFrom(GLAutoDrawable, boolean)` and `moveTo(GLAutoDrawable, Runnable)`.

    - #### destroy

          public void destroy()

      Last resort to destroy and loose ownership

    - #### moveFrom

          public static GLEventListenerState moveFrom(GLAutoDrawable src)

      Moves all GLEventListenerState components from the given `GLAutoDrawable` to a newly created instance.

      Note that all components are removed from the `GLAutoDrawable`, i.e. the `GLContext`, all `GLEventListener`.

      If the `GLAutoDrawable` was added to a `GLAnimatorControl`, it is removed and the `GLAnimatorControl` added to the GLEventListenerState.

      The returned GLEventListenerState instance is the `owner of the components`.

      Locking is performed on the `auto-drawable's` `upstream-lock` and `surface`. See GLAutoDrawable Locking.

Parameters:
  `src` - `GLAutoDrawable` source to move components from
Returns:
  new GLEventListenerState instance `owning` moved components.
See Also:
  `moveTo(GLAutoDrawable)`

- #### moveFrom

      public static GLEventListenerState moveFrom(GLAutoDrawable src,
                                  boolean keepLocked)

  Moves all GLEventListenerState components from the given `GLAutoDrawable` to a newly created instance.

  Note that all components are removed from the `GLAutoDrawable`, i.e. the `GLContext`, all `GLEventListener`.

  If the `GLAutoDrawable` was added to a `GLAnimatorControl`, it is removed and the `GLAnimatorControl` added to the GLEventListenerState.

  The returned GLEventListenerState instance is the `owner of the components`.

  Locking is performed on the `auto-drawable's` `upstream-lock` and `surface`, which is not released if `keepLocked` is `true`. See GLAutoDrawable Locking.

`keepLocked` may be utilized if swapping a context between drawables and to ensure atomicity of operation. Here, the `getUnlockSurfaceOp()` shall be passed to `moveTo(GLAutoDrawable, Runnable)`. See `GLDrawableUtil.swapGLContextAndAllGLEventListener(GLAutoDrawable, GLAutoDrawable)`.

Parameters:
  `src` - `GLAutoDrawable` source to move components from
  `keepLocked` - keep `upstream-lock` and `surface` locked, see above
Returns:
  new GLEventListenerState instance `owning` moved components.
See Also:
  `moveTo(GLAutoDrawable, Runnable)`

- #### moveTo

      public final void moveTo(GLAutoDrawable dest)
                        throws GLException

  Moves all GLEventListenerState components to the given `GLAutoDrawable` from this instance, while loosing `ownership`.

  If the previous `GLAutoDrawable` was removed from a `GLAnimatorControl` by previous `moveFrom(GLAutoDrawable)`, the given `GLAutoDrawable` is added to the cached `GLAnimatorControl`. This operation is skipped, if the given `GLAutoDrawable` is already added to a `GLAnimatorControl` instance.

  Locking is performed on the `auto-drawable's` `upstream-lock` and `surface`. See GLAutoDrawable Locking.

Note: After this operation, the GLEventListenerState reference should be released.

Parameters:
  `dest` - `GLAutoDrawable` destination to move GLEventListenerState components to
Throws:
  `GLException` - if a realized surface could not be locked.
  `GLException` - if this preserved `AbstractGraphicsDevice` is incompatible w/ the given destination one.
See Also:
  `moveFrom(GLAutoDrawable)`, `isOwner()`

- #### moveTo

      public final void moveTo(GLAutoDrawable dest,
                Runnable destUnlockOperation)
                        throws GLException

  Moves all GLEventListenerState components to the given `GLAutoDrawable` from this instance, while loosing `ownership`.

  If the previous `GLAutoDrawable` was removed from a `GLAnimatorControl` by previous `moveFrom(GLAutoDrawable, boolean)`, the given `GLAutoDrawable` is added to the cached `GLAnimatorControl`. This operation is skipped, if the given `GLAutoDrawable` is already added to a `GLAnimatorControl` instance.

  Locking is performed on the `auto-drawable's` `upstream-lock` and `surface`. See GLAutoDrawable Locking.

If the `GLAutoDrawable` `dest` has been kept locked by `moveFrom(GLAutoDrawable, boolean)`, it's `getUnlockSurfaceOp()` shall be passed here to `destUnlockOperation` to be unlocked.

Note: After this operation, the GLEventListenerState reference should be released.

Parameters:
  `dest` - `GLAutoDrawable` destination to move GLEventListenerState components to
  `destUnlockOperation` - optional unlock operation for `dest`, see `moveFrom(GLAutoDrawable, boolean)`.
Throws:
  `GLException` - if a realized surface could not be locked.
  `GLException` - if this preserved `AbstractGraphicsDevice` is incompatible w/ the given destination one.
See Also:
  `moveFrom(GLAutoDrawable, boolean)`, `isOwner()`

Copyright 2010 JogAmp Community.