javax.media.opengl

## Class GLDrawableFactory

- java.lang.Object
- - javax.media.opengl.GLDrawableFactory

-     public abstract class GLDrawableFactory
      extends Object

  Provides a virtual machine- and operating system-independent mechanism for creating `GLDrawable`s.

  The `GLCapabilities` objects passed in to the various factory methods are used as a hint for the properties of the returned drawable. The default capabilities selection algorithm (equivalent to passing in a null `GLCapabilitiesChooser`) is described in `DefaultGLCapabilitiesChooser`. Sophisticated applications needing to change the selection algorithm may pass in their own `GLCapabilitiesChooser` which can select from the available pixel formats. The GLCapabilitiesChooser mechanism may not be supported by all implementations or on all platforms, in which case any passed GLCapabilitiesChooser will be ignored.

  Because of the multithreaded nature of the Java platform's Abstract Window Toolkit, it is typically not possible to immediately reject a given `GLCapabilities` as being unsupportable by either returning `null` from the creation routines or raising a `GLException`. The semantics of the rejection process are (unfortunately) left unspecified for now. The current implementation will cause a `GLException` to be raised during the first repaint of the `GLCanvas` or `GLJPanel` if the capabilities can not be met.
  `GLOffscreenAutoDrawable` are created lazily, see `createOffscreenAutoDrawable(..)`.

  The concrete GLDrawableFactory subclass instantiated by `getFactory` can be changed by setting the system property `opengl.factory.class.name` to the fully-qualified name of the desired class.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract boolean` | `canCreateExternalGLDrawable(AbstractGraphicsDevice device)` Returns true if it is possible to create an external GLDrawable object via `createExternalGLDrawable()`.
    `abstract boolean` | `canCreateFBO(AbstractGraphicsDevice device, GLProfile glp)` Returns true if it is possible to create an framebuffer object (FBO).
    `abstract boolean` | `canCreateGLPbuffer(AbstractGraphicsDevice device, GLProfile glp)` Returns true if it is possible to create an pbuffer surface.
    `abstract GLAutoDrawable` | `createDummyAutoDrawable(AbstractGraphicsDevice deviceReq, boolean createNewDevice, GLCapabilitiesImmutable capsRequested, GLCapabilitiesChooser chooser)` Creates a `realized` dummy `GLAutoDrawable` incl it's dummy, invisible `NativeSurface` as created with `createDummyDrawable(AbstractGraphicsDevice, boolean, GLCapabilitiesImmutable, GLCapabilitiesChooser)`.
    `abstract GLDrawable` | `createDummyDrawable(AbstractGraphicsDevice deviceReq, boolean createNewDevice, GLCapabilitiesImmutable capsRequested, GLCapabilitiesChooser chooser)` Creates an `unrealized` dummy `GLDrawable`.
    `abstract GLContext` | `createExternalGLContext()` Creates a GLContext object representing an existing OpenGL context in an external (third-party) OpenGL-based library.
    `abstract GLDrawable` | `createExternalGLDrawable()` Creates a `GLDrawable` object representing an existing OpenGL drawable in an external (third-party) OpenGL-based library.
    `abstract GLDrawable` | `createGLDrawable(NativeSurface target)` Returns an `unrealized` GLDrawable according to it's chosen `GLCapabilitiesImmutable`, which determines pixel format, on- and offscreen incl.
    `abstract GLOffscreenAutoDrawable` | `createOffscreenAutoDrawable(AbstractGraphicsDevice device, GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser, int width, int height)` Creates a `realized` `GLOffscreenAutoDrawable` incl it's offscreen `NativeSurface` with the given capabilites and dimensions.
    `abstract GLDrawable` | `createOffscreenDrawable(AbstractGraphicsDevice device, GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser, int width, int height)` Creates an `unrealized` offscreen `GLDrawable` incl it's offscreen `NativeSurface` with the given capabilites and dimensions.
    `abstract ProxySurface` | `createProxySurface(AbstractGraphicsDevice device, int screenIdx, long windowHandle, GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser, UpstreamSurfaceHook upstream)` Creates a proxy `NativeSurface` w/ defined surface handle, i.e.
    `List<GLCapabilitiesImmutable>` | `getAvailableCapabilities(AbstractGraphicsDevice device)` Returns an array of available GLCapabilities for the device. The list is sorted by the native ID, ascending. The chosen GLProfile statement in the result may not refer to the maximum available profile due to implementation constraints, ie using the shared resource.
    `abstract AbstractGraphicsDevice` | `getDefaultDevice()` Retrieve the default `device` `connection`, `unit ID` and `unique ID name`.
    `static GLDrawableFactory` | `getDesktopFactory()` Returns the sole GLDrawableFactory instance for the desktop (X11, WGL, ..) if exist or null
    `static GLDrawableFactory` | `getEGLFactory()` Returns the sole GLDrawableFactory instance for EGL if exist or null
    `static GLDrawableFactory` | `getFactory(GLProfile glProfile)` Returns the sole GLDrawableFactory instance.
    `abstract boolean` | `getIsDeviceCompatible(AbstractGraphicsDevice device)`
    `abstract GLRendererQuirks` | `getRendererQuirks(AbstractGraphicsDevice device)` Returns the shared resource's context `GLRendererQuirks`.
    `boolean` | `hasRendererQuirk(AbstractGraphicsDevice device, int quirk)` Returns true if the `quirk` exist in the shared resource's context `GLRendererQuirks`.
    `static void` | `initSingleton()` Instantiate singleton factories if available, EGLES1, EGLES2 and the OS native ones.
    `abstract void` | `resetAllDisplayGamma()` Resets the gamma, brightness and contrast values of all modified displays to their original values before `setDisplayGamma` was called the first time.
    `abstract void` | `resetDisplayGamma(NativeSurface surface)` Resets the gamma, brightness and contrast values of the display associated with the given `surface` to its original values before `setDisplayGamma` was called the first time.
    `abstract boolean` | `setDisplayGamma(NativeSurface surface, float gamma, float brightness, float contrast)` Sets the gamma, brightness, and contrast of the display associated with the given `surface`.

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

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

- - ### Method Detail

    - #### initSingleton

          public static final void initSingleton()

      Instantiate singleton factories if available, EGLES1, EGLES2 and the OS native ones.

    - #### setDisplayGamma

          public abstract boolean setDisplayGamma(NativeSurface surface,
                                float gamma,
                                float brightness,
                                float contrast)
                                           throws IllegalArgumentException

      Sets the gamma, brightness, and contrast of the display associated with the given `surface`.

      This functionality is not available on all platforms and graphics hardware. Returns true if the settings were successfully changed, false if not. This method may return false for some values of the incoming arguments even on hardware which does support the underlying functionality.

      If this method returns true, the display settings will automatically be reset to their original values upon JVM exit (assuming the JVM does not crash); if the user wishes to change the display settings back to normal ahead of time, use `resetDisplayGamma(NativeSurface)` or `resetAllDisplayGamma()`.

      It is recommended to call `resetDisplayGamma(NativeSurface)` or `resetAllDisplayGamma()` before calling e.g. `System.exit()` from the application rather than rely on the shutdown hook functionality due to inevitable race conditions and unspecified behavior during JVM teardown.

      This method may be called multiple times during the application's execution, but calling `resetDisplayGamma(NativeSurface)` will only reset the settings to the values before the first call to this method.

      Parameters:
        `surface` - denominates the display device
        `gamma` - The gamma value, typically > 1.0 (default values vary, but typically roughly 1.0)
        `brightness` - The brightness value between -1.0 and 1.0, inclusive (default values vary, but typically 0)
        `contrast` - The contrast, greater than 0.0 (default values vary, but typically 1)
      Returns:
        true if gamma settings were successfully changed, false if not
      Throws:
        `IllegalArgumentException` - if any of the parameters were out-of-bounds
      See Also:
        `resetDisplayGamma(NativeSurface)`, `resetAllDisplayGamma()`

    - #### resetDisplayGamma

          public abstract void resetDisplayGamma(NativeSurface surface)

      Resets the gamma, brightness and contrast values of the display associated with the given `surface` to its original values before `setDisplayGamma` was called the first time.

      While it is not explicitly required that this method be called before exiting manually, calling it is recommended because of the inevitable unspecified behavior during JVM teardown.

    - #### resetAllDisplayGamma

          public abstract void resetAllDisplayGamma()

      Resets the gamma, brightness and contrast values of all modified displays to their original values before `setDisplayGamma` was called the first time.

      While it is not explicitly required that this method be called before exiting manually, calling it is recommended because of the inevitable unspecified behavior during JVM teardown.

    - #### getDefaultDevice

          public abstract AbstractGraphicsDevice getDefaultDevice()

      Retrieve the default `device` `connection`, `unit ID` and `unique ID name`. for this factory
      The implementation must return a non `null` default device, which must not be opened, ie. it's native handle is `null`.

      This method shall return the default device if available even if the GLDrawableFactory is not functional and hence not compatible. The latter situation may happen because no native OpenGL implementation is available for the specific implementation.

      Returns:
        the default shared device for this factory, eg. :0.0 on X11 desktop.
      See Also:
        `getIsDeviceCompatible(AbstractGraphicsDevice)`

    - #### getIsDeviceCompatible

          public abstract boolean getIsDeviceCompatible(AbstractGraphicsDevice device)

      Parameters:
        `device` - which `connection` denotes the shared the target device, may be `null` for the platform's default device.
      Returns:
        true if the device is compatible with this factory, ie. if it can be used for GLDrawable creation. Otherwise false. This implies validation whether the implementation is functional.
      See Also:
        `getDefaultDevice()`

    - #### hasRendererQuirk

          public final boolean hasRendererQuirk(AbstractGraphicsDevice device,
                                 int quirk)

      Returns true if the `quirk` exist in the shared resource's context `GLRendererQuirks`.

      Convenience method for:

                final GLRendererQuirks glrq = factory.getRendererQuirks(device);
                return null != glrq ? glrq.exist(quirk) : false;

      Parameters:
        `device` - which `connection` denotes the shared the target device, may be `null` for the platform's default device.
        `quirk` - the quirk to be tested, e.g. `GLRendererQuirks.NoDoubleBufferedPBuffer`.
      Throws:
        `IllegalArgumentException` - if the quirk is out of range
      See Also:
        `getRendererQuirks(AbstractGraphicsDevice)`, `GLRendererQuirks`

    - #### getRendererQuirks

          public abstract GLRendererQuirks getRendererQuirks(AbstractGraphicsDevice device)

      Returns the shared resource's context `GLRendererQuirks`.

      Implementation calls `GLContext.getRendererQuirks()` on the shared resource context.

      In case no shared device exist yet or the implementation doesn't support tracking quirks, the result is always `null`.

      Parameters:
        `device` - which `connection` denotes the shared the target device, may be `null` for the platform's default device.
      See Also:
        `GLContext.getRendererQuirks()`, `GLRendererQuirks`

    - #### getDesktopFactory

          public static GLDrawableFactory getDesktopFactory()

      Returns the sole GLDrawableFactory instance for the desktop (X11, WGL, ..) if exist or null

    - #### getEGLFactory

          public static GLDrawableFactory getEGLFactory()

      Returns the sole GLDrawableFactory instance for EGL if exist or null

    - #### getFactory

          public static GLDrawableFactory getFactory(GLProfile glProfile)
                                              throws GLException

      Returns the sole GLDrawableFactory instance.
      Parameters:
        `glProfile` - GLProfile to determine the factory type, ie EGLDrawableFactory, or one of the native GLDrawableFactory's, ie X11/GLX, Windows/WGL or MacOSX/CGL.
      Throws:
        `GLException`

    - #### getAvailableCapabilities

          public final List<GLCapabilitiesImmutable> getAvailableCapabilities(AbstractGraphicsDevice device)

      Returns an array of available GLCapabilities for the device.
      The list is sorted by the native ID, ascending.
      The chosen GLProfile statement in the result may not refer to the maximum available profile due to implementation constraints, ie using the shared resource.
      Parameters:
        `device` - which `connection` denotes the shared the target device, may be `null` for the platform's default device.
      Returns:
        A list of `GLCapabilitiesImmutable`'s, maybe empty if none is available.

    - #### createGLDrawable

          public abstract GLDrawable createGLDrawable(NativeSurface target)
                                               throws IllegalArgumentException,
                                                      GLException

      Returns an `unrealized` GLDrawable according to it's chosen `GLCapabilitiesImmutable`,
      which determines pixel format, on- and offscreen incl. PBuffer type.

      The chosen `GLCapabilitiesImmutable` are referenced within the target `NativeSurface`'s `AbstractGraphicsConfiguration`.

      An onscreen GLDrawable is created if `caps.isOnscreen()` is true.

      A FBO drawable is created if both `caps.isFBO()` and `canCreateFBO(device, caps.getGLProfile())` is true.

      A Pbuffer drawable is created if both `caps.isPBuffer()` and `canCreateGLPbuffer(device)` is true.

      If not onscreen and neither FBO nor Pbuffer is available, a simple pixmap/bitmap drawable/surface is created, which is unlikely to be hardware accelerated.

      Throws:
        `IllegalArgumentException` - if the passed target is null
        `GLException` - if any window system-specific errors caused the creation of the GLDrawable to fail.
      See Also:
        `canCreateGLPbuffer(AbstractGraphicsDevice, GLProfile)`, `GLContext.isFBOAvailable(AbstractGraphicsDevice, GLProfile)`, `Capabilities.isOnscreen()`, `GLCapabilities.isFBO()`, `GLCapabilities.isPBuffer()`, `GraphicsConfigurationFactory#chooseGraphicsConfiguration(CapabilitiesImmutable, CapabilitiesImmutable, CapabilitiesChooser, AbstractGraphicsScreen, int)`

    - #### createOffscreenAutoDrawable

          public abstract GLOffscreenAutoDrawable createOffscreenAutoDrawable(AbstractGraphicsDevice device,
                                                            GLCapabilitiesImmutable caps,
                                                            GLCapabilitiesChooser chooser,
                                                            int width,
                                                            int height)
                                                                       throws GLException

      Creates a `realized` `GLOffscreenAutoDrawable` incl it's offscreen `NativeSurface` with the given capabilites and dimensions.

      The `GLOffscreenAutoDrawable`'s `GLDrawable` is `realized` without an assigned `GLContext`, hence not initialized completely.
      The `GLContext` can be assigned later manually via `setContext(ctx)` or it will be created lazily at the 1st `display()` method call.
      Lazy `GLContext` creation will take a shared `GLContext` into account which has been set `directly` or `via another GLAutoDrawable`.

      In case the passed `GLCapabilitiesImmutable` contains default values, i.e. `caps.isOnscreen()` `== true`, it is auto-configured. Auto configuration will set `caps` to offscreen and FBO or Pbuffer, whichever is available in that order.

      A FBO based auto drawable, `GLOffscreenAutoDrawable.FBO`, is created if both `caps.isFBO()` and `canCreateFBO(device, caps.getGLProfile())` is true.

      A Pbuffer based auto drawable is created if both `caps.isPBuffer()` and `canCreateGLPbuffer(device)` is true.

      If neither FBO nor Pbuffer is available, a simple pixmap/bitmap auto drawable is created, which is unlikely to be hardware accelerated.

      The resulting `GLOffscreenAutoDrawable` has it's own independent device instance using `device` details.

      Parameters:
        `device` - which `connection` denotes the shared device to be used, may be `null` for the platform's default device.
        `caps` - the requested GLCapabilties
        `chooser` - the custom chooser, may be null for default
        `width` - the requested offscreen width
        `height` - the requested offscreen height
      Returns:
        the created and realized offscreen `GLOffscreenAutoDrawable` instance
      Throws:
        `GLException` - if any window system-specific errors caused the creation of the Offscreen to fail.
      See Also:
        `createOffscreenDrawable(AbstractGraphicsDevice, GLCapabilitiesImmutable, GLCapabilitiesChooser, int, int)`

    - #### createDummyAutoDrawable

          public abstract GLAutoDrawable createDummyAutoDrawable(AbstractGraphicsDevice deviceReq,
                                               boolean createNewDevice,
                                               GLCapabilitiesImmutable capsRequested,
                                               GLCapabilitiesChooser chooser)

      Creates a `realized` dummy `GLAutoDrawable` incl it's dummy, invisible `NativeSurface` as created with `createDummyDrawable(AbstractGraphicsDevice, boolean, GLCapabilitiesImmutable, GLCapabilitiesChooser)`.

      The dummy `GLAutoDrawable`'s `GLDrawable` is `realized` without an assigned `GLContext`, hence not initialized completely.
      The `GLContext` can be assigned later manually via `setContext(ctx)` or it will be created lazily at the 1st `display()` method call.
      Lazy `GLContext` creation will take a shared `GLContext` into account which has been set `directly` or `via another GLAutoDrawable`.

      Parameters:
        `deviceReq` - which `connection` denotes the shared device to be used, may be `null` for the platform's default device.
        `createNewDevice` - if `true` a new independent device instance is created from the `deviceReq`, otherwise `deviceReq` is used as-is and must be valid!
        `capsRequested` - the desired `GLCapabilitiesImmutable`, incl. it's `GLProfile`. For shared context, same `VisualIDHolder.getVisualID(javax.media.nativewindow.VisualIDHolder.VIDType)` across shared drawables will yield best compatibility.
        `chooser` - the custom chooser, may be null for default
      Returns:
        the created and realized dummy `GLAutoDrawable` instance
      See Also:
        `createDummyDrawable(AbstractGraphicsDevice, boolean, GLCapabilitiesImmutable, GLCapabilitiesChooser)`

    - #### createOffscreenDrawable

          public abstract GLDrawable createOffscreenDrawable(AbstractGraphicsDevice device,
                                           GLCapabilitiesImmutable caps,
                                           GLCapabilitiesChooser chooser,
                                           int width,
                                           int height)
                                                      throws GLException

      Creates an `unrealized` offscreen `GLDrawable` incl it's offscreen `NativeSurface` with the given capabilites and dimensions.

      In case the passed `GLCapabilitiesImmutable` contains default values, i.e. `caps.isOnscreen()` `== true`, it is auto-configured. The latter will set offscreen and also FBO or Pbuffer, whichever is available in that order.

      A resizeable FBO drawable, `GLFBODrawable.Resizeable`, is created if both `caps.isFBO()` and `canCreateFBO(device, caps.getGLProfile())` is true.

      A Pbuffer drawable is created if both `caps.isPBuffer()` and `canCreateGLPbuffer(device)` is true.

      If neither FBO nor Pbuffer is available, a simple pixmap/bitmap drawable is created, which is unlikely to be hardware accelerated.

      The resulting `GLDrawable` has it's own independent device instance using `device` details.

      Parameters:
        `device` - which `connection` denotes the shared device to be used, may be `null` for the platform's default device.
        `caps` - the requested GLCapabilties
        `chooser` - the custom chooser, may be null for default
        `width` - the requested offscreen width
        `height` - the requested offscreen height
      Returns:
        the created unrealized offscreen `GLDrawable`
      Throws:
        `GLException` - if any window system-specific errors caused the creation of the Offscreen to fail.
      See Also:
        `#createOffscreenAutoDrawable(AbstractGraphicsDevice, GLCapabilitiesImmutable, GLCapabilitiesChooser, int, int, GLContext)`

    - #### createDummyDrawable

          public abstract GLDrawable createDummyDrawable(AbstractGraphicsDevice deviceReq,
                                       boolean createNewDevice,
                                       GLCapabilitiesImmutable capsRequested,
                                       GLCapabilitiesChooser chooser)

      Creates an `unrealized` dummy `GLDrawable`. A dummy drawable is not visible on screen and will not be used to render directly to, it maybe on- or offscreen.

      It is used to allow the creation of a `GLContext` to query information. It also allows creation of framebuffer objects which are used for rendering or creating a shared GLContext w/o actually rendering to this dummy drawable's framebuffer.

      Parameters:
        `deviceReq` - which `connection` denotes the shared device to be used, may be `null` for the platform's default device.
        `createNewDevice` - if `true` a new independent device instance is created from the `deviceReq`, otherwise `deviceReq` is used as-is and must be valid!
        `capsRequested` - the desired `GLCapabilitiesImmutable`, incl. it's `GLProfile`. For shared context, same `visual ID` or `caps` across shared drawables will yield best compatibility.
        `chooser` - the custom chooser, may be null for default
      Returns:
        the created unrealized dummy `GLDrawable`

    - #### createProxySurface

          public abstract ProxySurface createProxySurface(AbstractGraphicsDevice device,
                                        int screenIdx,
                                        long windowHandle,
                                        GLCapabilitiesImmutable caps,
                                        GLCapabilitiesChooser chooser,
                                        UpstreamSurfaceHook upstream)

      Creates a proxy `NativeSurface` w/ defined surface handle, i.e. a `WrappedSurface` or `GDISurface` instance.

      It's `AbstractGraphicsConfiguration` is properly set according to the given `windowHandle`'s native visualID if set or the given `GLCapabilitiesImmutable`.

      Lifecycle (creation and destruction) of the given surface handle shall be handled by the caller via `ProxySurface.createNotify()` and `ProxySurface.destroyNotify()`.

      Such surface can be used to instantiate a GLDrawable. With the help of `GLAutoDrawableDelegate` you will be able to implement a new native windowing system binding almost on-the-fly, see `GLCanvas`.

      The resulting `GLOffscreenAutoDrawable` has it's own independent device instance using `device` details which may be blocking depending on platform and windowing-toolkit requirements.

      Parameters:
        `device` - which `connection` denotes the shared the target device, may be `null` for the platform's default device. Caller has to ensure it is compatible w/ the given `windowHandle`
        `screenIdx` - matching screen index of given `windowHandle`
        `windowHandle` - the native window handle
        `caps` - the requested GLCapabilties
        `chooser` - the custom chooser, may be null for default
        `upstream` - optional `UpstreamSurfaceHook` allowing control of the `ProxySurface`'s lifecycle and data it presents.
      Returns:
        the created `ProxySurface` instance w/ defined surface handle.

    - #### canCreateFBO

          public abstract boolean canCreateFBO(AbstractGraphicsDevice device,
                             GLProfile glp)

      Returns true if it is possible to create an framebuffer object (FBO).

      FBO feature is implemented in OpenGL, hence it is `GLProfile` dependent.

      FBO support is queried as described in `GLContext.hasBasicFBOSupport()`.

      Parameters:
        `device` - which `connection` denotes the shared the target device, may be `null` for the platform's default device.
        `glp` - `GLProfile` to check for FBO capabilities
      See Also:
        `GLContext.hasBasicFBOSupport()`

    - #### canCreateGLPbuffer

          public abstract boolean canCreateGLPbuffer(AbstractGraphicsDevice device,
                                   GLProfile glp)

      Returns true if it is possible to create an pbuffer surface.

      Some older graphics cards do not have this capability, as well as some new GL implementation, i.e. OpenGL 3 core on OSX.

      Parameters:
        `device` - which `connection` denotes the shared the target device, may be `null` for the platform's default device.
        `glp` - `GLProfile` to check for FBO capabilities

    - #### createExternalGLContext

          public abstract GLContext createExternalGLContext()
                                                     throws GLException

      Creates a GLContext object representing an existing OpenGL context in an external (third-party) OpenGL-based library. This GLContext object may be used to draw into this preexisting context using its `GL` and `GLU` objects. New contexts created through `GLDrawable`s may share textures and display lists with this external context.

      The underlying OpenGL context must be current on the current thread at the time this method is called. The user is responsible for the maintenance of the underlying OpenGL context; calls to `makeCurrent` and `release` on the returned GLContext object have no effect. If the underlying OpenGL context is destroyed, the `destroy` method should be called on the `GLContext`. A new `GLContext` object should be created for each newly-created underlying OpenGL context.

      Throws:
        `GLException` - if any window system-specific errors caused the creation of the external GLContext to fail.

    - #### canCreateExternalGLDrawable

          public abstract boolean canCreateExternalGLDrawable(AbstractGraphicsDevice device)

      Returns true if it is possible to create an external GLDrawable object via `createExternalGLDrawable()`.
      Parameters:
        `device` - which `connection` denotes the shared the target device, may be `null` for the platform's default device.

    - #### createExternalGLDrawable

          public abstract GLDrawable createExternalGLDrawable()
                                                       throws GLException

      Creates a `GLDrawable` object representing an existing OpenGL drawable in an external (third-party) OpenGL-based library. This GLDrawable object may be used to create new, fully-functional `GLContext`s on the OpenGL drawable. This is useful when interoperating with a third-party OpenGL-based library and it is essential to not perturb the state of the library's existing context, even to the point of not sharing textures or display lists with that context.

      An underlying OpenGL context must be current on the desired drawable and the current thread at the time this method is called. The user is responsible for the maintenance of the underlying drawable. If one or more contexts are created on the drawable using `GLDrawable.createContext(javax.media.opengl.GLContext)`, and the drawable is deleted by the third-party library, the user is responsible for calling `GLContext.destroy()` on these contexts.

      Calls to `setSize`, `getWidth` and `getHeight` are illegal on the returned GLDrawable. If these operations are required by the user, they must be performed by the third-party library.

      It is legal to create both an external GLContext and GLDrawable representing the same third-party OpenGL entities. This can be used, for example, to query current state information using the external GLContext and then create and set up new GLContexts using the external GLDrawable.

      This functionality may not be available on all platforms and `canCreateExternalGLDrawable(javax.media.nativewindow.AbstractGraphicsDevice)` should be called first to see if it is present. For example, on X11 platforms, this API requires the presence of GLX 1.3 or later.

      Throws:
        `GLException` - if any window system-specific errors caused the creation of the external GLDrawable to fail.

Copyright 2010 JogAmp Community.