javax.media.opengl.awt

## Class GLCanvas

- java.lang.Object
- - java.awt.Component
  - - java.awt.Canvas
    - - javax.media.opengl.awt.GLCanvas

- All Implemented Interfaces:
    AWTPrintLifecycle, ImageObserver, MenuContainer, Serializable, Accessible, NativeSurfaceHolder, OffscreenLayerOption, ScalableSurface, WindowClosingProtocol, AWTGLAutoDrawable, ComponentEvents, GLAutoDrawable, GLDrawable, GLSharedContextSetter

      public class GLCanvas
      extends Canvas
      implements AWTGLAutoDrawable, WindowClosingProtocol, OffscreenLayerOption, AWTPrintLifecycle, GLSharedContextSetter, ScalableSurface

  A heavyweight AWT component which provides OpenGL rendering support. This is the primary implementation of an AWT `GLDrawable`; `GLJPanel` is provided for compatibility with Swing user interfaces when adding a heavyweight doesn't work either because of Z-ordering or LayoutManager problems.

  ##### Offscreen Layer Remarks

  `setShallUseOffscreenLayer(true)` maybe called to use an offscreen drawable (FBO or PBuffer) allowing the underlying JAWT mechanism to composite the image, if supported.

  `setShallUseOffscreenLayer(true)` is being called if `CapabilitiesImmutable.isOnscreen()` is `false`.

  ##### Java2D OpenGL Remarks

  To avoid any conflicts with a potential Java2D OpenGL context,
  you shall consider setting the following JVM properties:

  -     sun.java2d.opengl=false

  -     sun.java2d.noddraw=true

  This is especially true in case you want to utilize a GLProfile other than `GLProfile.GL2`, eg. using `GLProfile#getMaxFixedFunc()`.
  On the other hand, if you like to experiment with GLJPanel's utilization of Java2D's OpenGL pipeline, you have to set them to

  -     sun.java2d.opengl=true

  -     sun.java2d.noddraw=true

  ##### Disable Background Erase

  GLCanvas tries to disable background erase for the AWT Canvas before native peer creation (X11) and after it (Windows),
  utilizing the optional `Toolkit` method `disableBeackgroundErase(java.awt.Canvas)`.
  However if this does not give you the desired results, you may want to disable AWT background erase in general:

  -     sun.awt.noerasebackground=true

  ##### OpenGL Context Sharing

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

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class java.awt.Component

      `Component.BaselineResizeBehavior`

    - ### Nested classes/interfaces inherited from interface javax.media.nativewindow.WindowClosingProtocol

      `WindowClosingProtocol.WindowClosingMode`

    - ### Nested classes/interfaces inherited from interface com.jogamp.nativewindow.awt.AWTPrintLifecycle

      `AWTPrintLifecycle.Context`

  - ### Field Summary

    - ### Fields inherited from class java.awt.Component

      `BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT`

    - ### Fields inherited from interface com.jogamp.nativewindow.awt.AWTPrintLifecycle

      `DEFAULT_PRINT_TILE_SIZE`

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

      `SCREEN_CHANGE_ACTION_ENABLED`

    - ### Fields inherited from interface javax.media.nativewindow.ScalableSurface

      `AUTOMAX_PIXELSCALE, IDENTITY_PIXELSCALE`

    - ### Fields inherited from interface java.awt.image.ImageObserver

      `ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GLCanvas()` Creates a new GLCanvas component with a default set of OpenGL capabilities, using the default OpenGL capabilities selection mechanism, on the default screen device.
    `GLCanvas(GLCapabilitiesImmutable capsReqUser)` Creates a new GLCanvas component with the requested set of OpenGL capabilities, using the default OpenGL capabilities selection mechanism, on the default screen device.
    `GLCanvas(GLCapabilitiesImmutable capsReqUser, GLCapabilitiesChooser chooser, GraphicsDevice device)` Creates a new GLCanvas component.

  - ### 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.
    `void` | `addNotify()` Overridden to track when this component is added to a container.
    `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.
    `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()`
    `int[]` | `getCurrentSurfaceScale(int[] result)` Returns the current pixel scale of the associated `NativeSurface`.
    `WindowClosingProtocol.WindowClosingMode` | `getDefaultCloseOperation()`
    `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.
    `GraphicsConfiguration` | `getGraphicsConfiguration()` Overridden to choose a GraphicsConfiguration on a parent container's GraphicsDevice because both devices
    `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`.
    `int[]` | `getNativeSurfaceScale(int[] result)` Returns the native pixel scale of the associated `NativeSurface` reflecting it's currently bound monitor surface resolution in pixels.
    `GLCapabilitiesImmutable` | `getRequestedGLCapabilities()` Fetches the `GLCapabilitiesImmutable` corresponding to the user requested OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.
    `int[]` | `getRequestedSurfaceScale(int[] result)` Returns the requested pixel scale of the associated `NativeSurface`.
    `boolean` | `getShallUseOffscreenLayer()` Returns the property set by `OffscreenLayerOption.setShallUseOffscreenLayer(boolean)`.
    `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 glRunnable)` 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> glRunnables)` 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` | `isOffscreenLayerSurfaceEnabled()` Returns true if this instance uses an offscreen layer, otherwise false.
    `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)` A most simple JOGL AWT test entry
    `void` | `paint(Graphics g)` Overridden to cause OpenGL rendering to be performed during repaint cycles.
    `void` | `print(Graphics graphics)`
    `void` | `releasePrint()` Shall be called after `PrinterJob.print()`.
    `GLEventListener` | `removeGLEventListener(GLEventListener listener)` Removes the given `listener` from this drawable queue.
    `void` | `removeNotify()` Overridden to track when this component is removed from a container.
    `void` | `reshape(int x, int y, int width, int height)` Overridden to cause `GLDrawableHelper.reshape(javax.media.opengl.GLEventListener, javax.media.opengl.GLAutoDrawable, int, int, int, int, boolean, boolean)` to be called on all registered `GLEventListener`s.
    `void` | `setAnimator(GLAnimatorControl animatorControl)` Registers the usage of an animator, an `GLAnimatorControl` implementation.
    `void` | `setAutoSwapBufferMode(boolean onOrOff)` 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)`
    `WindowClosingProtocol.WindowClosingMode` | `setDefaultCloseOperation(WindowClosingProtocol.WindowClosingMode op)`
    `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 gl)` Sets the `GL` pipeline object this GLAutoDrawable uses.
    `void` | `setGLEventListenerInitState(GLEventListener listener, boolean initialized)` Sets the given `listener's` initialized state.
    `void` | `setRealized(boolean realized)` Indicates to GLDrawable implementations whether the underlying `surface` has been created and can be drawn into.
    `void` | `setShallUseOffscreenLayer(boolean v)` Request an offscreen layer, if supported.
    `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` | `setSurfaceScale(int[] pixelScale)` Request a pixel scale in x- and y-direction for the associated `NativeSurface`.
    `void` | `setupPrint(double scaleMatX, double scaleMatY, int numSamples, int tileWidth, int tileHeight)` Shall be called before `PrinterJob.print()`.
    `void` | `swapBuffers()` Swaps the front and back buffers of this drawable.
    `String` | `toString()`
    `void` | `update(Graphics g)` Overridden from Canvas to prevent the AWT's clearing of the canvas from interfering with the OpenGL rendering.

    - ### Methods inherited from class java.awt.Canvas

      `createBufferStrategy, createBufferStrategy, getAccessibleContext, getBufferStrategy`

    - ### Methods inherited from class java.awt.Component

      `action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, dispatchEvent, doLayout, enable, enable, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMinimumSize, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, preferredSize, prepareImage, prepareImage, printAll, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocusInWindow, resize, resize, revalidate, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, transferFocus, transferFocusBackward, transferFocusUpCycle, validate`

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

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

    - ### Methods inherited from interface javax.media.opengl.awt.AWTGLAutoDrawable

      `repaint, setSize`

    - ### Methods inherited from interface javax.media.opengl.awt.ComponentEvents

      `addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener`

- - ### Constructor Detail

    - #### GLCanvas

          public GLCanvas()
                   throws GLException

      Creates a new GLCanvas component with a default set of OpenGL capabilities, using the default OpenGL capabilities selection mechanism, on the default screen device.

      See details about OpenGL context sharing.

      Throws:
        `GLException` - if no default profile is available for the default desktop device.

    - #### GLCanvas

          public GLCanvas(GLCapabilitiesImmutable capsReqUser)
                   throws GLException

      Creates a new GLCanvas component with the requested set of OpenGL capabilities, using the default OpenGL capabilities selection mechanism, on the default screen device.

      See details about OpenGL context sharing.

      Throws:
        `GLException` - if no GLCapabilities are given and no default profile is available for the default desktop device.
      See Also:
        `GLCanvas#GLCanvas(javax.media.opengl.GLCapabilitiesImmutable, javax.media.opengl.GLCapabilitiesChooser, javax.media.opengl.GLContext, java.awt.GraphicsDevice)`

    - #### GLCanvas

          public GLCanvas(GLCapabilitiesImmutable capsReqUser,
                  GLCapabilitiesChooser chooser,
                  GraphicsDevice device)
                   throws GLException

      Creates a new GLCanvas component. The passed GLCapabilities specifies the OpenGL capabilities for the component; if null, a default set of capabilities is used. The GLCapabilitiesChooser specifies the algorithm for selecting one of the available GLCapabilities for the component; a DefaultGLCapabilitesChooser is used if null is passed for this argument. The passed GraphicsDevice indicates the screen on which to create the GLCanvas; the GLDrawableFactory uses the default screen device of the local GraphicsEnvironment if null is passed for this argument.

      See details about OpenGL context sharing.

      Throws:
        `GLException` - if no GLCapabilities are given and no default profile is available for the default desktop device.

  - ### Method Detail

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

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

    - #### isThreadGLCapable

          public final boolean isThreadGLCapable()

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

      Specified by:
        `isThreadGLCapable` in interface `GLAutoDrawable`

    - #### setShallUseOffscreenLayer

          public void setShallUseOffscreenLayer(boolean v)

      Description copied from interface: `OffscreenLayerOption`
      Request an offscreen layer, if supported.

      Shall be called before the first `NativeSurface.lockSurface()`, and hence before realization.

      Specified by:
        `setShallUseOffscreenLayer` in interface `OffscreenLayerOption`
      See Also:
        `OffscreenLayerOption.getShallUseOffscreenLayer()`, `OffscreenLayerOption.isOffscreenLayerSurfaceEnabled()`

    - #### getShallUseOffscreenLayer

          public final boolean getShallUseOffscreenLayer()

      Description copied from interface: `OffscreenLayerOption`
      Returns the property set by `OffscreenLayerOption.setShallUseOffscreenLayer(boolean)`.
      Specified by:
        `getShallUseOffscreenLayer` in interface `OffscreenLayerOption`

    - #### isOffscreenLayerSurfaceEnabled

          public final boolean isOffscreenLayerSurfaceEnabled()

      Description copied from interface: `OffscreenLayerOption`
      Returns true if this instance uses an offscreen layer, otherwise false.

      This instance is an offscreen layer, if `setShallUseOffscreenLayer(true)` has been called before it's realization and first lock and the underlying implementation supports it.

      The return value is undefined before issuing the first `NativeSurface.lockSurface()`.
      Specified by:
        `isOffscreenLayerSurfaceEnabled` in interface `OffscreenLayerOption`
      See Also:
        `OffscreenLayerOption.setShallUseOffscreenLayer(boolean)`

    - #### getGraphicsConfiguration

          public GraphicsConfiguration getGraphicsConfiguration()

      Overridden to choose a GraphicsConfiguration on a parent container's GraphicsDevice because both devices
      Overrides:
        `getGraphicsConfiguration` in class `Component`

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

    - #### setRealized

          public final void setRealized(boolean realized)

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

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

    - #### getDefaultCloseOperation

          public WindowClosingProtocol.WindowClosingMode getDefaultCloseOperation()

      Specified by:
        `getDefaultCloseOperation` in interface `WindowClosingProtocol`
      Returns:
        the current close operation value
      See Also:
        `WindowClosingProtocol.WindowClosingMode.DISPOSE_ON_CLOSE`, `WindowClosingProtocol.WindowClosingMode.DO_NOTHING_ON_CLOSE`

    - #### setDefaultCloseOperation

          public WindowClosingProtocol.WindowClosingMode setDefaultCloseOperation(WindowClosingProtocol.WindowClosingMode op)

      Specified by:
        `setDefaultCloseOperation` in interface `WindowClosingProtocol`
      Parameters:
        `op` - the new close operation value
      Returns:
        the previous close operation value
      See Also:
        `WindowClosingProtocol.WindowClosingMode.DISPOSE_ON_CLOSE`, `WindowClosingProtocol.WindowClosingMode.DO_NOTHING_ON_CLOSE`

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

    - #### 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. only destroys all GL related resources.

      This impl. does not remove the GLCanvas from it's parent AWT container so this class's `removeNotify()` AWT override won't get called. To do so, remove this component from it's parent AWT container.

      Specified by:
        `destroy` in interface `GLAutoDrawable`

    - #### paint

          public void paint(Graphics g)

      Overridden to cause OpenGL rendering to be performed during repaint cycles. Subclasses which override this method must call super.paint() in their paint() method in order to function properly.
      Overrides:
        `paint` in class `Canvas`

    - #### addNotify

          public void addNotify()

      Overridden to track when this component is added to a container. Subclasses which override this method must call super.addNotify() in their addNotify() method in order to function properly.

      Overrides:

        `addNotify` in class `java.awt.Component`
      Overrides:
        `addNotify` in class `Canvas`

    - #### setSurfaceScale

          public final void setSurfaceScale(int[] pixelScale)

      Description copied from interface: `ScalableSurface`
      Request a pixel scale in x- and y-direction for the associated `NativeSurface`.

      Default pixel scale request for both directions is `ScalableSurface.AUTOMAX_PIXELSCALE`.

      In case platform only supports uniform pixel scale, i.e. one scale for both directions, either `ScalableSurface.AUTOMAX_PIXELSCALE` or the maximum requested pixel scale component is used.

      The requested pixel scale will be validated against platform limits before native scale-setup, i.e. clipped to `ScalableSurface.IDENTITY_PIXELSCALE` if not supported or clipped to the platform maximum. It can be queried via `ScalableSurface.getRequestedSurfaceScale(int[])`.

      The actual realized pixel scale values of the `NativeSurface` can be queried via `ScalableSurface.getCurrentSurfaceScale(int[])` or computed via `surface.`convertToPixelUnits`(new int[] { 1, 1 })`

      Specified by:
        `setSurfaceScale` in interface `ScalableSurface`
      Parameters:
        `pixelScale` - requested surface pixel scale int[2] values for x- and y-direction.

    - #### getRequestedSurfaceScale

          public final int[] getRequestedSurfaceScale(int[] result)

      Description copied from interface: `ScalableSurface`
      Returns the requested pixel scale of the associated `NativeSurface`.
      Specified by:
        `getRequestedSurfaceScale` in interface `ScalableSurface`
      Parameters:
        `result` - int[2] storage for the result
      Returns:
        the passed storage containing the requested pixelScale for chaining

    - #### getCurrentSurfaceScale

          public final int[] getCurrentSurfaceScale(int[] result)

      Description copied from interface: `ScalableSurface`
      Returns the current pixel scale of the associated `NativeSurface`.
      Specified by:
        `getCurrentSurfaceScale` in interface `ScalableSurface`
      Parameters:
        `result` - int[2] storage for the result
      Returns:
        the passed storage containing the current pixelScale for chaining

    - #### getNativeSurfaceScale

          public int[] getNativeSurfaceScale(int[] result)

      Description copied from interface: `ScalableSurface`
      Returns the native pixel scale of the associated `NativeSurface` reflecting it's currently bound monitor surface resolution in pixels.

      The native pixel scale maybe used to determine the proper dpi value of this `NativeSurface`:

              surfacePpMM = monitorPpMM * currentSurfaceScale / nativeSurfaceScale,
              with PpMM == pixel per millimeter

      Specified by:
        `getNativeSurfaceScale` in interface `ScalableSurface`
      Parameters:
        `result` - int[2] storage for the result
      Returns:
        the passed storage containing the native pixelScale for chaining

    - #### removeNotify

          public void removeNotify()

      Overridden to track when this component is removed from a container. Subclasses which override this method must call super.removeNotify() in their removeNotify() method in order to function properly.

      User shall not call this method outside of EDT, read the AWT/Swing specs about this.

      Overrides:
        `removeNotify` in class `java.awt.Component`
      Overrides:
        `removeNotify` in class `Component`

    - #### reshape

          public void reshape(int x,
                     int y,
                     int width,
                     int height)

      Overridden to cause `GLDrawableHelper.reshape(javax.media.opengl.GLEventListener, javax.media.opengl.GLAutoDrawable, int, int, int, int, boolean, boolean)` to be called on all registered `GLEventListener`s. Subclasses which override this method must call super.reshape() in their reshape() method in order to function properly.

      Overrides:

        `reshape` in class `java.awt.Component`
      Overrides:
        `reshape` in class `Component`

    - #### update

          public void update(Graphics g)

      Overridden from Canvas to prevent the AWT's clearing of the canvas from interfering with the OpenGL rendering.
      Overrides:
        `update` in class `Canvas`

    - #### setupPrint

          public void setupPrint(double scaleMatX,
                        double scaleMatY,
                        int numSamples,
                        int tileWidth,
                        int tileHeight)

      Description copied from interface: `AWTPrintLifecycle`
      Shall be called before `PrinterJob.print()`.

      See Usage.

      Specified by:
        `setupPrint` in interface `AWTPrintLifecycle`
      Parameters:
        `scaleMatX` - `Graphics2D` `scaling factor`, i.e. rendering 1/scaleMatX * width pixels
        `scaleMatY` - `Graphics2D` `scaling factor`, i.e. rendering 1/scaleMatY * height pixels
        `numSamples` - multisampling value: < 0 turns off, == 0 leaves as-is, > 0 enables using given num samples
        `tileWidth` - custom tile width for `tile renderer`, pass -1 for default.
        `tileHeight` - custom tile height for `tile renderer`, pass -1 for default.

    - #### releasePrint

          public void releasePrint()

      Description copied from interface: `AWTPrintLifecycle`
      Shall be called after `PrinterJob.print()`.

      See Usage.

      Specified by:
        `releasePrint` in interface `AWTPrintLifecycle`

    - #### print

          public void print(Graphics graphics)

      Overrides:
        `print` in class `Component`

    - #### 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 index,
                                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:
        `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

          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

    - #### setAnimator

          public void setAnimator(GLAnimatorControl animatorControl)

      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:
        `animatorControl` - `null` reference indicates no animator is using this `GLAutoDrawable`,
        a valid reference indicates an animator is using this `GLAutoDrawable`.
      See Also:
        `GLAutoDrawable.display()`, `GLAutoDrawable.invoke(boolean, GLRunnable)`, `GLAnimatorControl`

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

    - #### invoke

          public boolean invoke(boolean wait,
                       GLRunnable glRunnable)
                         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
        `glRunnable` - 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> glRunnables)
                         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
        `glRunnables` - 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)`

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

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

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

    - #### setGL

          public GL setGL(GL gl)

      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

    - #### setAutoSwapBufferMode

          public void setAutoSwapBufferMode(boolean onOrOff)

      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`

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

    - #### swapBuffers

          public void swapBuffers()

      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`

    - #### setContextCreationFlags

          public void setContextCreationFlags(int flags)

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

    - #### getContextCreationFlags

          public int getContextCreationFlags()

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

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

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

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

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

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

    - #### getFactory

          public GLDrawableFactory getFactory()

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

    - #### toString

          public String toString()

      Specified by:
        `toString` in interface `GLDrawable`
      Overrides:
        `toString` in class `Component`

    - #### main

          public static void main(String[] args)

      A most simple JOGL AWT test entry

Copyright 2010 JogAmp Community.