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 NativeSurface becomes visible/realized. 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 GLEventListeners. This can be done immediatly, or with the followup display(..) call.
• Send a reshape event by calling reshape(..) for all registered GLEventListeners. 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 NativeSurface.
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 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 GLEventListeners.
• 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 GLEventListeners. This can be done immediatly, or with the followup display(..) call.
• Send a reshape event by calling reshape(..) for all registered GLEventListeners. 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 the end of this drawable queue.
void	addGLEventListener(int index, GLEventListener listener) Adds a GLEventListener at the given index of this drawable queue.
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 GLEventListeners.
GLAnimatorControl	getAnimator()
boolean	getAutoSwapBufferMode() Indicates whether automatic buffer swapping is enabled for this drawable.
GLContext	getContext() Returns the context associated with this drawable.
int	getContextCreationFlags()
GL	getGL() Returns the GL pipeline object this GLAutoDrawable uses.
void	invoke(boolean wait, GLRunnable glRunnable) Enqueues a one-shot GLRunnable, which will be executed with the next display() call.
void	removeGLEventListener(GLEventListener listener) Removes a GLEventListener from this drawable.
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.
void	setContext(GLContext context) Associate a new context to this drawable.
void	setContextCreationFlags(int flags)
GL	setGL(GL gl) Sets the GL pipeline object this GLAutoDrawable uses.

Methods inherited from interface javax.media.opengl.GLDrawable

createContext, getChosenGLCapabilities, getFactory, getGLProfile, getHandle, getHeight, getNativeSurface, getWidth, isRealized, 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 the end of this drawable queue. The listeners are notified of events in the order of the queue.

addGLEventListener

void addGLEventListener(int index,
                        GLEventListener listener)
                        throws IndexOutOfBoundsException

Adds a GLEventListener at the given index of this drawable queue. The listeners are notified of events in the order of the queue.

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

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.

setAnimator

void setAnimator(GLAnimatorControl animatorControl)
                 throws GLException

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

Parameters:

animator - null reference indicates no animator is using this GLAutoDrawable,
a valid reference indicates an animator is using this GLAutoDrawable.

Throws:

GLException - if an animator is already registered.

See Also:

display(), invoke(boolean, GLRunnable), GLAnimatorControl

getAnimator

GLAnimatorControl getAnimator()

Returns:

the registered GLAnimatorControl implementation, using this GLAutoDrawable.

See Also:

setAnimator(javax.media.opengl.GLAnimatorControl), GLAnimatorControl

invoke

void invoke(boolean wait,
            GLRunnable glRunnable)

Enqueues a one-shot GLRunnable, which will be executed with the next display() call.

If no GLAnimatorControl is registered, or if it is not animating, the default situation,
or if the current thread is the animator thread,
a display() call is issued after enqueue the GLRunnable.
No extra synchronization is performed in case wait is true, since it is executed in the current thread.

If GLAnimatorControl is registered and is animating,
no display() call is issued, since the animator thread performs it.
If wait is true, the implementation waits until the GLRunnable is executed.

See Also:

setAnimator(javax.media.opengl.GLAnimatorControl), display(), GLRunnable

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 GLEventListeners. 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 in the following order:

• Calling display(..) for all registered GLEventListeners.
• Executes all one-shot GLRunnable, enqueued via invoke(boolean, GLRunnable).

May be called periodically by a running GLAnimatorControl implementation,
which must register itself with 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 GLEventListeners before making the actual display(..) calls, in case this has not been done yet.

See Also:

setAnimator(javax.media.opengl.GLAnimatorControl)

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

setContextCreationFlags

void setContextCreationFlags(int flags)

Parameters:

flags - Additional context creation flags.

See Also:

GLContext.setContextCreationFlags(int), GLContext.enableGLDebugMessage(boolean)

getContextCreationFlags

int getContextCreationFlags()

Returns:

Additional context creation flags

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