javax.media.opengl

## Interface GLDrawable

- All Superinterfaces:
    NativeSurfaceHolder
  All Known Subinterfaces:
    AWTGLAutoDrawable, GLAutoDrawable, GLFBODrawable, GLFBODrawable.Resizeable, GLOffscreenAutoDrawable, GLOffscreenAutoDrawable.FBO, GLSharedContextSetter
  All Known Implementing Classes:
    GLCanvas, GLJPanel

      public interface GLDrawable
      extends NativeSurfaceHolder

  An abstraction for an OpenGL rendering target. A GLDrawable's primary functionality is to create OpenGL contexts which can be used to perform rendering. A GLDrawable does not automatically create an OpenGL context, but all implementations of `GLAutoDrawable` do so upon creation.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `GLCapabilitiesImmutable` | `getChosenGLCapabilities()` Fetches the `GLCapabilitiesImmutable` corresponding to the chosen OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.
    `GLDrawableFactory` | `getFactory()` Return the `GLDrawableFactory` being used to create this instance.
    `GLProfile` | `getGLProfile()` Fetches the `GLProfile` for this drawable.
    `long` | `getHandle()` Returns the GL drawable handle, guaranteed to be valid after `realization` and while it's `surface` is being `locked`.
    `NativeSurface` | `getNativeSurface()` Returns the associated `NativeSurface` of this `NativeSurfaceHolder`.
    `GLCapabilitiesImmutable` | `getRequestedGLCapabilities()` Fetches the `GLCapabilitiesImmutable` corresponding to the user requested OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.
    `int` | `getSurfaceHeight()` Returns the height of this `GLDrawable`'s `surface` client area in pixel units.
    `int` | `getSurfaceWidth()` Returns the width of this `GLDrawable`'s `surface` client area in pixel units.
    `boolean` | `isGLOriented()` Returns `true` if the drawable is rendered in OpenGL's coordinate system, origin at bottom left.
    `boolean` | `isRealized()` Returns `true` if this drawable is realized, otherwise `true`.
    `void` | `setRealized(boolean realized)` Indicates to GLDrawable implementations whether the underlying `surface` has been created and can be drawn into.
    `void` | `swapBuffers()` Swaps the front and back buffers of this drawable.
    `String` | `toString()`

- - ### Method Detail

    - #### createContext

          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.

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

    - #### setRealized

          void setRealized(boolean realized)

      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.

      See Also:
        `isRealized()`, `getHandle()`, `NativeSurface.lockSurface()`

    - #### isRealized

          boolean isRealized()

      Returns `true` if this drawable is realized, otherwise `true`.

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

      See Also:
        `setRealized(boolean)`

    - #### getSurfaceWidth

          int getSurfaceWidth()

      Returns the width of this `GLDrawable`'s `surface` client area in pixel units.
      See Also:
        `NativeSurface.getSurfaceWidth()`

    - #### getSurfaceHeight

          int getSurfaceHeight()

      Returns the height of this `GLDrawable`'s `surface` client area in pixel units.
      See Also:
        `NativeSurface.getSurfaceHeight()`

    - #### isGLOriented

          boolean isGLOriented()

      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.

    - #### swapBuffers

          void swapBuffers()
                           throws GLException

      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.
      Throws:
        `GLException`

    - #### getChosenGLCapabilities

          GLCapabilitiesImmutable getChosenGLCapabilities()

      Fetches the `GLCapabilitiesImmutable` corresponding to the chosen OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.

      This query only returns the chosen capabilities if `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.

      Returns:
        The immutable queried instance.
      See Also:
        `getRequestedGLCapabilities()`

    - #### getRequestedGLCapabilities

          GLCapabilitiesImmutable getRequestedGLCapabilities()

      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.

      Returns:
        The immutable queried instance.
      Since:
        2.2
      See Also:
        `getChosenGLCapabilities()`

    - #### getGLProfile

          GLProfile getGLProfile()

      Fetches the `GLProfile` for this drawable. Returns the GLProfile object, no copy.

    - #### getNativeSurface

          NativeSurface getNativeSurface()

      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`
      See Also:
        `getHandle()`

    - #### getHandle

          long getHandle()

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

      See Also:
        `setRealized(boolean)`, `NativeSurface.lockSurface()`, `NativeSurface.unlockSurface()`

    - #### getFactory

          GLDrawableFactory getFactory()

      Return the `GLDrawableFactory` being used to create this instance.

    - #### toString

          String toString()

      Overrides:
        `toString` in class `Object`

Copyright 2010 JogAmp Community.