Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.media.opengl
Interface GLAutoDrawable

All Superinterfaces:
  GLDrawable

All Known Subinterfaces:
  AWTGLAutoDrawable, GLPbuffer

All Known Implementing Classes:
  GLCanvas, GLJPanel

    public interface GLAutoDrawable

extends GLDrawable

A higher-level abstraction than `GLDrawable` which supplies an event based mechanism (`GLEventListener`) for performing OpenGL rendering. A GLAutoDrawable automatically creates a primary rendering context which is associated with the GLAutoDrawable for the lifetime of the object. This context has the `synchronized` property enabled so that calls to `makeCurrent` will block if the context is current on another thread. This allows the internal GLContext for the GLAutoDrawable to be used both by the event based rendering mechanism as well by end users directly.

The implementation shall initialize itself as soon as possible, ie if the attached `NativeWindow` is become visible. The following protocol shall be satisfied:

- Create the `GLDrawable` with the requested `GLCapabilities`
- Notify `GLDrawable` to validate the `GLCapabilities` by calling `setRealized(true)`.
- Create the new `GLContext`.
- Initialize all OpenGL resources by calling `init(..)` for all registered `GLEventListener`s. This can be done immediatly, or with the followup `display(..)` call.
- Send a reshape event by calling `reshape(..)` for all registered `GLEventListener`s. This shall be done after the `init(..)` calls.

Another implementation detail is the drawable reconfiguration. One use case is where a window is being dragged to another screen with a different pixel configuration, ie `GLCapabilities`. The implementation shall be able to detect such cases in conjunction with the associated `NativeWindow`.
For example, AWT's `Canvas` 's `getGraphicsConfiguration()` is capable to determine a display device change. This is demonstrated within `GLCanvas`'s and NEWT's `AWTCanvas` `getGraphicsConfiguration()` specialization. Another demonstration is NEWT's `NativeWindow` implementation on the the Windows platform, which utilizes the native platform's MonitorFromWindow(HWND) function.
All OpenGL resources shall be regenerated, while the drawable's `GLCapabilities` has to be choosen again. The following protocol shall be satisfied.

- Controlled disposal:

- Dispose all OpenGL resources by calling `dispose(..)` for all registered `GLEventListener`s.
- Destroy the `GLContext`.
- Notify `GLDrawable` of the invalid state by calling `setRealized(false)`.

- Controlled regeneration:

- Create the new `GLDrawable` with the requested `GLCapabilities`
- Notify `GLDrawable` to revalidate the `GLCapabilities` by calling `setRealized(true)`.
- Create the new `GLContext`.
- Initialize all OpenGL resources by calling `init(..)` for all registered `GLEventListener`s. This can be done immediatly, or with the followup `display(..)` call.
- Send a reshape event by calling `reshape(..)` for all registered `GLEventListener`s. This shall be done after the `init(..)` calls.

Note: Current graphics driver keep the surface configuration for a given window, even if the window is moved to a monitor with a different pixel configuration, ie 32bpp to 16bpp. However, it is best to not assume such behavior and make your application comply with the above protocol.

However, to not introduce to much breakage with older applications and because of the situation mentioned above, the `boolean` system property `jogl.screenchange.action` will control the screen change action as follows:

        -Djogl.screenchange.action=false Disable the drawable reconfiguration (the default)
        -Djogl.screenchange.action=true  Enable  the drawable reconfiguration

Field Summary
`static boolean` | `SCREEN_CHANGE_ACTION_ENABLED` Flag reflecting wheather the drawable reconfiguration will be issued in case a screen device change occured, e.g.

Method Summary
`void` | `addGLEventListener(GLEventListener listener)` Adds a `GLEventListener` to this drawable.
`void` | `destroy()` Destroys all resources associated with this GLAutoDrawable, inclusive the GLContext.
`void` | `display()` Causes OpenGL rendering to be performed for this GLAutoDrawable by calling `display(..)` for all registered `GLEventListener`s.
`boolean` | `getAutoSwapBufferMode()` Indicates whether automatic buffer swapping is enabled for this drawable.
`GLContext` | `getContext()` Returns the context associated with this drawable.
`GL` | `getGL()` Returns the `GL` pipeline object this GLAutoDrawable uses.
`void` | `removeGLEventListener(GLEventListener listener)` Removes a `GLEventListener` from this drawable.
`void` | `setAutoSwapBufferMode(boolean onOrOff)` Enables or disables automatic buffer swapping for this drawable.
`void` | `setContext(GLContext context)` Associate a new context to this drawable.
`GL` | `setGL(GL gl)` Sets the `GL` pipeline object this GLAutoDrawable uses.

Methods inherited from interface javax.media.opengl.GLDrawable
`createContext, getChosenGLCapabilities, getFactory, getGLProfile, getHeight, getNativeWindow, getWidth, setRealized, swapBuffers, toString`

Field Detail

### SCREEN_CHANGE_ACTION_ENABLED

    static final boolean SCREEN_CHANGE_ACTION_ENABLED

  Flag reflecting wheather the drawable reconfiguration will be issued in case a screen device change occured, e.g. in a multihead environment, where you drag the window to another monitor.

Method Detail

### getContext

    GLContext getContext()

  Returns the context associated with this drawable. The returned context will be synchronized. Don't rely on it's identity, the context may change.

### setContext

    void setContext(GLContext context)

  Associate a new context to this drawable.

### addGLEventListener

    void addGLEventListener(GLEventListener listener)

  Adds a `GLEventListener` to this drawable. If multiple listeners are added to a given drawable, they are notified of events in an arbitrary order.

### removeGLEventListener

    void removeGLEventListener(GLEventListener listener)

  Removes a `GLEventListener` from this drawable. 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.

### destroy

    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.

### display

    void display()

  Causes OpenGL rendering to be performed for this GLAutoDrawable by calling `display(..)` for all registered `GLEventListener`s. Called automatically by the window system toolkit upon receiving a repaint() request. this routine may 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.

### setAutoSwapBufferMode

    void setAutoSwapBufferMode(boolean onOrOff)

  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.

### getAutoSwapBufferMode

    boolean getAutoSwapBufferMode()

  Indicates whether automatic buffer swapping is enabled for this drawable. See `setAutoSwapBufferMode(boolean)`.

### getGL

    GL getGL()

  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.

### setGL

    GL setGL(GL gl)

  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.

  Returns:
    the set GL pipeline or null if not successful

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2005 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.