com.jogamp.opengl.swt

## Class GLCanvas

- java.lang.Object
- - org.eclipse.swt.widgets.Widget
  - - org.eclipse.swt.widgets.Control
    - - org.eclipse.swt.widgets.Scrollable
      - - org.eclipse.swt.widgets.Composite
        - - org.eclipse.swt.widgets.Canvas
          - - com.jogamp.opengl.swt.GLCanvas

- All Implemented Interfaces:
    NativeSurfaceHolder, GLAutoDrawable, GLDrawable, GLSharedContextSetter, org.eclipse.swt.graphics.Drawable

      public class GLCanvas
      extends org.eclipse.swt.widgets.Canvas
      implements GLAutoDrawable, GLSharedContextSetter

  Native SWT Canvas implementing GLAutoDrawable

  Implementation allows use of custom `GLCapabilities`.

  ##### OpenGL Context Sharing

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

- - ### Field Summary

    - ### Fields inherited from class org.eclipse.swt.widgets.Composite

      `embeddedHandle`

    - ### Fields inherited from class org.eclipse.swt.widgets.Widget

      `handle`

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

      `SCREEN_CHANGE_ACTION_ENABLED`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GLCanvas(org.eclipse.swt.widgets.Composite parent, int style, GLCapabilitiesImmutable capsReqUser, GLCapabilitiesChooser capsChooser)` Creates a new SWT GLCanvas.

  - ### 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 idx, 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.
    `static GLCanvas` | `create(org.eclipse.swt.widgets.Composite parent, int style, GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser)` Creates an instance using `GLCanvas(Composite, int, GLCapabilitiesImmutable, GLCapabilitiesChooser)` on the SWT thread.
    `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.
    `void` | `dispose()`
    `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.
    `GLCapabilitiesImmutable` | `getChosenGLCapabilities()` Fetches the `GLCapabilitiesImmutable` corresponding to the chosen OpenGL capabilities (pixel format / visual / GLProfile) 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()`
    `GLDrawableFactory` | `getFactory()` Return the `GLDrawableFactory` being used to create this instance.
    `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.
    `GLProfile` | `getGLProfile()` Fetches the `GLProfile` for this drawable.
    `long` | `getHandle()` Returns the GL drawable handle, guaranteed to be valid after `realization` and while it's `surface` is being `locked`.
    `NativeSurface` | `getNativeSurface()` Returns the associated `NativeSurface` of this `NativeSurfaceHolder`.
    `GLCapabilitiesImmutable` | `getRequestedGLCapabilities()` Fetches the `GLCapabilitiesImmutable` corresponding to the user requested OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.
    `int` | `getSurfaceHeight()` Returns the height of this `GLDrawable`'s `surface` client area in pixel units.
    `int` | `getSurfaceWidth()` Returns the width of this `GLDrawable`'s `surface` client area in pixel units.
    `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 runnable)` Enqueues a one-shot `GLRunnable`, which will be executed within the next `GLAutoDrawable.display()` call after all registered `GLEventListener`s `display(GLAutoDrawable)` methods have been called.
    `boolean` | `invoke(boolean wait, List<GLRunnable> runnables)` Extends `GLAutoDrawable.invoke(boolean, GLRunnable)` functionality allowing to inject a list of `GLRunnable`s.
    `boolean` | `isGLOriented()` Returns `true` if the drawable is rendered in OpenGL's coordinate system, origin at bottom left.
    `boolean` | `isRealized()` Returns `true` if this drawable is realized, otherwise `true`.
    `boolean` | `isThreadGLCapable()` Indicates whether the current thread is capable of performing OpenGL-related work.
    `static void` | `main(String[] args)`
    `GLEventListener` | `removeGLEventListener(GLEventListener listener)` Removes the given `listener` from this drawable queue.
    `void` | `setAnimator(GLAnimatorControl arg0)` Registers the usage of an animator, an `GLAnimatorControl` implementation.
    `void` | `setAutoSwapBufferMode(boolean arg0)` 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 arg0)`
    `Thread` | `setExclusiveContextThread(Thread t)` Dedicates this instance's `GLContext` to the given thread. The thread will exclusively claim the `GLContext` via `GLAutoDrawable.display()` and not release it until `GLAutoDrawable.destroy()` or `setExclusiveContextThread(null)` has been called.
    `GL` | `setGL(GL arg0)` Sets the `GL` pipeline object this GLAutoDrawable uses.
    `void` | `setGLEventListenerInitState(GLEventListener listener, boolean initialized)` Sets the given `listener's` initialized state.
    `void` | `setRealized(boolean arg0)` Indicates to GLDrawable implementations whether the underlying `surface` has been created and can be drawn into.
    `void` | `setSharedAutoDrawable(GLAutoDrawable sharedAutoDrawable)` Specifies an `GLAutoDrawable`, which `OpenGL context` shall be shared by this `GLAutoDrawable`'s `GLContext`.
    `void` | `setSharedContext(GLContext sharedContext)` Specifies an `OpenGL context`, which shall be shared by this `GLAutoDrawable`'s `GLContext`.
    `void` | `swapBuffers()` Swaps the front and back buffers of this drawable.
    `String` | `toString()`
    `void` | `update()`

    - ### Methods inherited from class org.eclipse.swt.widgets.Canvas

      `drawBackground, getCaret, getIME, scroll, setCaret, setFont, setIME`

    - ### Methods inherited from class org.eclipse.swt.widgets.Composite

      `changed, computeSize, drawBackground, getBackgroundMode, getChildren, getClientArea, getLayout, getLayoutDeferred, getTabList, isLayoutDeferred, layout, layout, layout, layout, layout, setBackgroundMode, setFocus, setLayout, setLayoutDeferred, setTabList`

    - ### Methods inherited from class org.eclipse.swt.widgets.Scrollable

      `computeTrim, getBorderWidth, getHorizontalBar, getScrollbarsMode, getVerticalBar`

    - ### Methods inherited from class org.eclipse.swt.widgets.Control

      `addControlListener, addDragDetectListener, addFocusListener, addGestureListener, addHelpListener, addKeyListener, addMenuDetectListener, addMouseListener, addMouseMoveListener, addMouseTrackListener, addMouseWheelListener, addPaintListener, addTouchListener, addTraverseListener, computeSize, dragDetect, dragDetect, forceFocus, getAccessible, getBackground, getBackgroundImage, getBounds, getCursor, getDragDetect, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getMonitor, getOrientation, getParent, getRegion, getShell, getSize, getToolTipText, getTouchEnabled, getVisible, internal_dispose_GC, internal_new_GC, isEnabled, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, print, redraw, redraw, removeControlListener, removeDragDetectListener, removeFocusListener, removeGestureListener, removeHelpListener, removeKeyListener, removeMenuDetectListener, removeMouseListener, removeMouseMoveListener, removeMouseTrackListener, removeMouseWheelListener, removePaintListener, removeTouchListener, removeTraverseListener, setBackground, setBackgroundImage, setBounds, setBounds, setCapture, setCursor, setDragDetect, setEnabled, setForeground, setLayoutData, setLocation, setLocation, setMenu, setOrientation, setParent, setRedraw, setRegion, setSize, setSize, setToolTipText, setTouchEnabled, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, traverse, traverse`

    - ### Methods inherited from class org.eclipse.swt.widgets.Widget

      `addDisposeListener, addListener, getData, getData, getDisplay, getListeners, getStyle, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, reskin, setData, setData`

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

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

- - ### Constructor Detail

    - #### GLCanvas

          public GLCanvas(org.eclipse.swt.widgets.Composite parent,
                  int style,
                  GLCapabilitiesImmutable capsReqUser,
                  GLCapabilitiesChooser capsChooser)

      Creates a new SWT GLCanvas.
      Parameters:
        `parent` - Required (non-null) parent Composite.
        `style` - Optional SWT style bit-field. The `SWT.NO_BACKGROUND` bit is set before passing this up to the Canvas constructor, so OpenGL handles the background.
        `capsReqUser` - Optional GLCapabilities. If not provided, the default capabilities for the default GLProfile for the graphics device determined by the parent Composite are used. Note that the GLCapabilities that are actually used may differ based on the capabilities of the graphics device.
        `capsChooser` - Optional GLCapabilitiesChooser to customize the selection of the used GLCapabilities based on the requested GLCapabilities, and the available capabilities of the graphics device.

  - ### Method Detail

    - #### create

          public static GLCanvas create(org.eclipse.swt.widgets.Composite parent,
                        int style,
                        GLCapabilitiesImmutable caps,
                        GLCapabilitiesChooser chooser)

      Creates an instance using `GLCanvas(Composite, int, GLCapabilitiesImmutable, GLCapabilitiesChooser)` on the SWT thread.
      Parameters:
        `parent` - Required (non-null) parent Composite.
        `style` - Optional SWT style bit-field. The `SWT.NO_BACKGROUND` bit is set before passing this up to the Canvas constructor, so OpenGL handles the background.
        `caps` - Optional GLCapabilities. If not provided, the default capabilities for the default GLProfile for the graphics device determined by the parent Composite are used. Note that the GLCapabilities that are actually used may differ based on the capabilities of the graphics device.
        `chooser` - Optional GLCapabilitiesChooser to customize the selection of the used GLCapabilities based on the requested GLCapabilities, and the available capabilities of the graphics device.
      Returns:
        a new instance

    - #### setSharedContext

          public final void setSharedContext(GLContext sharedContext)
                                      throws IllegalStateException

      Description copied from interface: `GLSharedContextSetter`
      Specifies an `OpenGL context`, which shall be shared by this `GLAutoDrawable`'s `GLContext`.

      Since the `drawable` and `context` is created at `GLAutoDrawable initialization` this method shall be called beforehand to have any effect.

      A set sharedContext will block context creation, i.e. `GLAutoDrawable initialization`, as long it is not `created natively`.

      The preferred method of assigning a shared context is to `set the shared GLAutoDrawable`, since this method also takes the `GLEventListener` `initialization into account`.

      See Lifecycle Considerations.

      Specified by:
        `setSharedContext` in interface `GLSharedContextSetter`
      Parameters:
        `sharedContext` - The OpenGL context to be shared by this `GLAutoDrawable`'s `GLContext`.
      Throws:
        `IllegalStateException` - if a `shared GLContext` or `shared GLAutoDrawable` is already set, the given sharedContext is null or equal to this `GLAutoDrawable`'s context.
      See Also:
        `GLSharedContextSetter.setSharedAutoDrawable(GLAutoDrawable)`

    - #### setSharedAutoDrawable

          public final void setSharedAutoDrawable(GLAutoDrawable sharedAutoDrawable)
                                           throws IllegalStateException

      Description copied from interface: `GLSharedContextSetter`
      Specifies an `GLAutoDrawable`, which `OpenGL context` shall be shared by this `GLAutoDrawable`'s `GLContext`.

      Since the `drawable` and `context` is created at `GLAutoDrawable initialization` this method shall be called beforehand to have any effect.

      A set sharedAutoDrawable will block context creation, i.e. initialization as long it's

      - `GLContext` is `null`, or
      - `GLContext` has not been `created natively`, or
      - `GLEventListener` are not `completely initialized`

      See Lifecycle Considerations.

      Specified by:
        `setSharedAutoDrawable` in interface `GLSharedContextSetter`
      Throws:
        `IllegalStateException` - if a `shared GLContext` or `shared GLAutoDrawable` is already set, the given sharedAutoDrawable is null or equal to this GLAutoDrawable.
      See Also:
        `GLSharedContextSetter.setSharedContext(GLContext)`

    - #### update

          public void update()

      Overrides:
        `update` in class `org.eclipse.swt.widgets.Control`

    - #### dispose

          public void dispose()

      Overrides:
        `dispose` in class `org.eclipse.swt.widgets.Widget`

    - #### 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)`

    - #### 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`

    - #### 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`

    - #### getSurfaceWidth

          public int getSurfaceWidth()

      Description copied from interface: `GLDrawable`
      Returns the width of this `GLDrawable`'s `surface` client area in pixel units.
      Specified by:
        `getSurfaceWidth` in interface `GLDrawable`
      See Also:
        `NativeSurface.getSurfaceWidth()`

    - #### getSurfaceHeight

          public int getSurfaceHeight()

      Description copied from interface: `GLDrawable`
      Returns the height of this `GLDrawable`'s `surface` client area in pixel units.
      Specified by:
        `getSurfaceHeight` in interface `GLDrawable`
      See Also:
        `NativeSurface.getSurfaceHeight()`

    - #### isGLOriented

          public boolean isGLOriented()

      Description copied from interface: `GLDrawable`
      Returns `true` if the drawable is rendered in OpenGL's coordinate system, origin at bottom left. Otherwise returns `false`, i.e. origin at top left.

      Default impl. is `true`, i.e. OpenGL coordinate system.

      Currently only MS-Windows bitmap offscreen drawable uses a non OpenGL orientation and hence returns `false`.
      This removes the need of a vertical flip when used in AWT or Windows applications.

      Specified by:
        `isGLOriented` in interface `GLDrawable`

    - #### addGLEventListener

          public void addGLEventListener(GLEventListener listener)

      Description copied from interface: `GLAutoDrawable`
      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 `GLAutoDrawable.getGLEventListenerInitState(GLEventListener)` for details.

      Specified by:
        `addGLEventListener` in interface `GLAutoDrawable`
      Parameters:
        `listener` - The GLEventListener object to be inserted

    - #### addGLEventListener

          public void addGLEventListener(int idx,
                                GLEventListener listener)
                                  throws IndexOutOfBoundsException

      Description copied from interface: `GLAutoDrawable`
      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 `GLAutoDrawable.getGLEventListenerInitState(GLEventListener)` for details.

      Specified by:
        `addGLEventListener` in interface `GLAutoDrawable`
      Parameters:
        `idx` - 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

          public int getGLEventListenerCount()

      Description copied from interface: `GLAutoDrawable`
      Returns the number of `GLEventListener` of this drawable queue.
      Specified by:
        `getGLEventListenerCount` in interface `GLAutoDrawable`
      Returns:
        The number of GLEventListener objects of this drawable queue.

    - #### getGLEventListener

          public GLEventListener getGLEventListener(int index)
                                             throws IndexOutOfBoundsException

      Description copied from interface: `GLAutoDrawable`
      Returns the `GLEventListener` at the given index of this drawable queue.
      Specified by:
        `getGLEventListener` in interface `GLAutoDrawable`
      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

    - #### areAllGLEventListenerInitialized

          public boolean areAllGLEventListenerInitialized()

      Description copied from interface: `GLAutoDrawable`
      Returns true if all added `GLEventListener` are initialized, otherwise false.
      Specified by:
        `areAllGLEventListenerInitialized` in interface `GLAutoDrawable`

    - #### getGLEventListenerInitState

          public boolean getGLEventListenerInitState(GLEventListener listener)

      Description copied from interface: `GLAutoDrawable`
      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`.

      Specified by:
        `getGLEventListenerInitState` in interface `GLAutoDrawable`
      Parameters:
        `listener` - the GLEventListener object to query it's initialized state.

    - #### setGLEventListenerInitState

          public void setGLEventListenerInitState(GLEventListener listener,
                                         boolean initialized)

      Description copied from interface: `GLAutoDrawable`
      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 `GLAutoDrawable.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(..)`.

      Specified by:
        `setGLEventListenerInitState` in interface `GLAutoDrawable`
      Parameters:
        `listener` - the GLEventListener object to perform a state change.
        `initialized` - if `true`, mark the listener initialized, otherwise uninitialized.

    - #### disposeGLEventListener

          public GLEventListener disposeGLEventListener(GLEventListener listener,
                                               boolean remove)

      Description copied from interface: `GLAutoDrawable`
      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.

      Specified by:
        `disposeGLEventListener` in interface `GLAutoDrawable`
      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

          public GLEventListener removeGLEventListener(GLEventListener listener)

      Description copied from interface: `GLAutoDrawable`
      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.

      Specified by:
        `removeGLEventListener` in interface `GLAutoDrawable`
      Parameters:
        `listener` - The GLEventListener object to be removed
      Returns:
        the removed GLEventListener, or null if listener was not added

    - #### destroy

          public 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 impl. calls this class's `dispose()` SWT override, where the actual implementation resides.

      Specified by:
        `destroy` in interface `GLAutoDrawable`

    - #### getAnimator

          public GLAnimatorControl getAnimator()

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

    - #### setExclusiveContextThread

          public final Thread setExclusiveContextThread(Thread t)
                                                 throws GLException

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

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

      To release a previous made exclusive thread, a user issues `setExclusiveContextThread(null)` and may poll `GLAutoDrawable.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)`.

      Specified by:
        `setExclusiveContextThread` in interface `GLAutoDrawable`
      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

          public final Thread getExclusiveContextThread()

      Specified by:
        `getExclusiveContextThread` in interface `GLAutoDrawable`
      See Also:
        `GLAutoDrawable.setExclusiveContextThread(Thread)`

    - #### getAutoSwapBufferMode

          public boolean getAutoSwapBufferMode()

      Description copied from interface: `GLAutoDrawable`
      Indicates whether automatic buffer swapping is enabled for this drawable. See `GLAutoDrawable.setAutoSwapBufferMode(boolean)`.
      Specified by:
        `getAutoSwapBufferMode` in interface `GLAutoDrawable`

    - #### getDelegatedDrawable

          public final GLDrawable getDelegatedDrawable()

      Description copied from interface: `GLAutoDrawable`
      If the implementation uses delegation, return the delegated `GLDrawable` instance, otherwise return `this` instance.
      Specified by:
        `getDelegatedDrawable` in interface `GLAutoDrawable`

    - #### getContext

          public GLContext getContext()

      Description copied from interface: `GLAutoDrawable`
      Returns the context associated with this drawable. The returned context will be synchronized. Don't rely on it's identity, the context may change.
      Specified by:
        `getContext` in interface `GLAutoDrawable`

    - #### getContextCreationFlags

          public int getContextCreationFlags()

      Specified by:
        `getContextCreationFlags` in interface `GLAutoDrawable`
      Returns:
        Additional context creation flags

    - #### getGL

          public GL getGL()

      Description copied from interface: `GLAutoDrawable`
      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.
      Specified by:
        `getGL` in interface `GLAutoDrawable`

    - #### invoke

          public boolean invoke(boolean wait,
                       GLRunnable runnable)
                         throws IllegalStateException

      Description copied from interface: `GLAutoDrawable`
      Enqueues a one-shot `GLRunnable`, which will be executed within the next `GLAutoDrawable.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 `GLAutoDrawable.display()` call is issued after enqueue the `GLRunnable`, hence the `GLRunnable` will be executed right away.

      If an `animator` is running,
      no explicit `GLAutoDrawable.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 `GLAutoDrawable.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 `GLAutoDrawable.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`
      Specified by:
        `invoke` in interface `GLAutoDrawable`
      Parameters:
        `wait` - if `true` block until execution of `glRunnable` is finished, otherwise return immediately w/o waiting
        `runnable` - the `GLRunnable` to execute within `GLAutoDrawable.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:
        `GLAutoDrawable.setAnimator(GLAnimatorControl)`, `GLAutoDrawable.display()`, `GLRunnable`, `GLAutoDrawable.invoke(boolean, List)`, `GLAutoDrawable.flushGLRunnables()`

    - #### invoke

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

      Description copied from interface: `GLAutoDrawable`
      Extends `GLAutoDrawable.invoke(boolean, GLRunnable)` functionality allowing to inject a list of `GLRunnable`s.
      Specified by:
        `invoke` in interface `GLAutoDrawable`
      Parameters:
        `wait` - if `true` block until execution of the last `glRunnable` is finished, otherwise return immediately w/o waiting
        `runnables` - the `GLRunnable`s to execute within `GLAutoDrawable.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 `GLAutoDrawable.invoke(boolean, GLRunnable)`.
      See Also:
        `GLAutoDrawable.invoke(boolean, GLRunnable)`, `GLAutoDrawable.flushGLRunnables()`

    - #### flushGLRunnables

          public void flushGLRunnables()

      Description copied from interface: `GLAutoDrawable`
      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.

      Specified by:
        `flushGLRunnables` in interface `GLAutoDrawable`
      See Also:
        `GLAutoDrawable.invoke(boolean, GLRunnable)`

    - #### setAnimator

          public void setAnimator(GLAnimatorControl arg0)
                           throws GLException

      Description copied from interface: `GLAutoDrawable`
      Registers the usage of an animator, an `GLAnimatorControl` implementation. The animator will be queried whether it's animating, ie periodically issuing `GLAutoDrawable.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 `GLAutoDrawable.display()` and `GLAutoDrawable.invoke(boolean, GLRunnable)` semantics.

      Specified by:
        `setAnimator` in interface `GLAutoDrawable`
      Parameters:
        `arg0` - `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:
        `GLAutoDrawable.display()`, `GLAutoDrawable.invoke(boolean, GLRunnable)`, `GLAnimatorControl`

    - #### setAutoSwapBufferMode

          public void setAutoSwapBufferMode(boolean arg0)

      Description copied from interface: `GLAutoDrawable`
      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.
      Specified by:
        `setAutoSwapBufferMode` in interface `GLAutoDrawable`

    - #### setContext

          public GLContext setContext(GLContext newCtx,
                             boolean destroyPrevCtx)

      Description copied from interface: `GLAutoDrawable`
      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.
      Specified by:
        `setContext` in interface `GLAutoDrawable`
      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)`

    - #### setContextCreationFlags

          public void setContextCreationFlags(int arg0)

      Specified by:
        `setContextCreationFlags` in interface `GLAutoDrawable`
      Parameters:
        `arg0` - Additional context creation flags.
      See Also:
        `GLContext.setContextCreationFlags(int)`, `GLContext.enableGLDebugMessage(boolean)`

    - #### setGL

          public GL setGL(GL arg0)

      Description copied from interface: `GLAutoDrawable`
      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.
      Specified by:
        `setGL` in interface `GLAutoDrawable`
      Returns:
        the set GL pipeline or null if not successful

    - #### createContext

          public GLContext createContext(GLContext shareWith)

      Description copied from interface: `GLAutoDrawable`
      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 `GLAutoDrawable.setContext(GLContext, boolean)`.

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

      Specified by:
        `createContext` in interface `GLAutoDrawable`
      Specified by:
        `createContext` in interface `GLDrawable`

    - #### getChosenGLCapabilities

          public GLCapabilitiesImmutable getChosenGLCapabilities()

      Description copied from interface: `GLDrawable`
      Fetches the `GLCapabilitiesImmutable` corresponding to the chosen OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.

      This query only returns the chosen capabilities if `GLDrawable.isRealized()`.

      On some platforms, the pixel format is not directly associated with the drawable; a best attempt is made to return a reasonable value in this case.

      This object shall be directly associated to the attached `NativeSurface`'s `AbstractGraphicsConfiguration`, and if changes are necessary, they should reflect those as well.

      Specified by:
        `getChosenGLCapabilities` in interface `GLDrawable`
      Returns:
        The immutable queried instance.
      See Also:
        `GLDrawable.getRequestedGLCapabilities()`

    - #### getRequestedGLCapabilities

          public GLCapabilitiesImmutable getRequestedGLCapabilities()

      Description copied from interface: `GLDrawable`
      Fetches the `GLCapabilitiesImmutable` corresponding to the user requested OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.

      If `realized`, `the chosen capabilities` reflect the actual selected OpenGL capabilities.

      Specified by:
        `getRequestedGLCapabilities` in interface `GLDrawable`
      Returns:
        The immutable queried instance.
      See Also:
        `GLDrawable.getChosenGLCapabilities()`

    - #### getFactory

          public GLDrawableFactory getFactory()

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

    - #### getGLProfile

          public GLProfile getGLProfile()

      Description copied from interface: `GLDrawable`
      Fetches the `GLProfile` for this drawable. Returns the GLProfile object, no copy.
      Specified by:
        `getGLProfile` in interface `GLDrawable`

    - #### getHandle

          public long getHandle()

      Description copied from interface: `GLDrawable`
      Returns the GL drawable handle, guaranteed to be valid after `realization` and while it's `surface` is being `locked`.

      It is usually identical to the underlying windowing toolkit `surface`'s `handle` or an intermediate layer to suite GL, e.g. an EGL surface.

      On EGL it is represented by the EGLSurface.
      On X11/GLX it is represented by either the Window XID, GLXPixmap, or GLXPbuffer.
      On Windows it is represented by the HDC, which may change with each `NativeSurface.lockSurface()`.

      Specified by:
        `getHandle` in interface `GLDrawable`
      See Also:
        `GLDrawable.setRealized(boolean)`, `NativeSurface.lockSurface()`, `NativeSurface.unlockSurface()`

    - #### getNativeSurface

          public NativeSurface getNativeSurface()

      Description copied from interface: `GLDrawable`
      Returns the associated `NativeSurface` of this `NativeSurfaceHolder`.

      Returns the underlying `NativeSurface` which `native handle` represents this OpenGL drawable's native resource.

      Specified by:
        `getNativeSurface` in interface `NativeSurfaceHolder`
      Specified by:
        `getNativeSurface` in interface `GLDrawable`
      See Also:
        `GLDrawable.getHandle()`

    - #### isRealized

          public boolean isRealized()

      Description copied from interface: `GLDrawable`
      Returns `true` if this drawable is realized, otherwise `true`.

      A drawable can be realized and unrealized via `GLDrawable.setRealized(boolean)`.

      Specified by:
        `isRealized` in interface `GLDrawable`
      See Also:
        `GLDrawable.setRealized(boolean)`

    - #### setRealized

          public void setRealized(boolean arg0)

      Description copied from interface: `GLDrawable`
      Indicates to GLDrawable implementations whether the underlying `surface` has been created and can be drawn into.

      If realized, the `drawable handle` may become valid while it's `surface` is being `locked`.

      End users do not need to call this method; it is not necessary to call `setRealized` on a `GLAutoDrawable` as these perform the appropriate calls on their underlying GLDrawables internally.

      Developers implementing new OpenGL components for various window toolkits need to call this method against GLDrawables obtained from the GLDrawableFactory via the `GLDrawableFactory.createGLDrawable(NativeSurface)` method. It must typically be called with an argument of `true` when the component associated with the GLDrawable is realized and with an argument of `false` just before the component is unrealized. For the AWT, this means calling `setRealized(true)` in the `addNotify` method and with an argument of `false` in the `removeNotify` method.

      `GLDrawable` implementations should handle multiple cycles of `setRealized(true)` / `setRealized(false)` calls. Most, if not all, Java window toolkits have a persistent object associated with a given component, regardless of whether that component is currently realized. The `GLDrawable` object associated with a particular component is intended to be similarly persistent. A `GLDrawable` is intended to be created for a given component when it is constructed and live as long as that component. `setRealized` allows the `GLDrawable` to re-initialize and destroy any associated resources as the component becomes realized and unrealized, respectively.

      With an argument of `true`, the minimum implementation shall call `NativeSurface's lockSurface()` and if successful:

      - Update the `GLCapabilities`, which are associated with the attached `NativeSurface`'s `AbstractGraphicsConfiguration`.
      - Release the lock with `NativeSurface's unlockSurface()`.
      This is important since `NativeSurface's lockSurface()` ensures resolving the window/surface handles, and the drawable's `GLCapabilities` might have changed.

      Calling this method has no other effects. For example, if `removeNotify` is called on a Canvas implementation for which a GLDrawable has been created, it is also necessary to destroy all OpenGL contexts associated with that GLDrawable. This is not done automatically by the implementation.

      Specified by:
        `setRealized` in interface `GLDrawable`
      See Also:
        `GLDrawable.isRealized()`, `GLDrawable.getHandle()`, `NativeSurface.lockSurface()`

    - #### swapBuffers

          public 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`

    - #### isThreadGLCapable

          public final boolean isThreadGLCapable()

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

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

      Implementation always supports multithreading, hence method always returns `true`.

      Specified by:
        `isThreadGLCapable` in interface `GLAutoDrawable`

    - #### toString

          public String toString()

      Specified by:
        `toString` in interface `GLDrawable`
      Overrides:
        `toString` in class `org.eclipse.swt.widgets.Widget`

    - #### main

          public static void main(String[] args)

Copyright 2010 JogAmp Community.