javax.media.opengl
Interface GLAutoDrawable

All Superinterfaces:
GLDrawable
All Known Subinterfaces:
AWTGLAutoDrawable, GLPbuffer
All Known Implementing Classes:
jogamp.opengl.GLAutoDrawableBase, GLAutoDrawableDelegate, GLCanvas, GLCanvas, GLJPanel, GLWindow, OffscreenAutoDrawable

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:

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 chosen again. The following protocol shall be satisfied.

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.

Avoiding 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.
 GLContext createContext(GLContext shareWith)
          Creates a new context for drawing to this drawable that will optionally share display lists 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 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.
 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 display() call after all registered GLEventListeners display(GLAutoDrawable) methods has been called.
 void removeGLEventListener(GLEventListener listener)
          Removes a GLEventListener from this drawable.
 GLEventListener removeGLEventListener(int index)
          Removes a GLEventListener at the given index from this drawable.
 void setAnimator(GLAnimatorControl animatorControl)
           Registers the usage of an animator, an GLAnimatorControl implementation.
 void setAutoSwapBufferMode(boolean enable)
          Enables or disables automatic buffer swapping for this drawable.
 GLContext setContext(GLContext newCtx)
          Associate a new context to this drawable and also propagates the context/drawable switch by calling newCtx.setGLDrawable(drawable, true);.
 void setContextCreationFlags(int flags)
           
 GL setGL(GL gl)
          Sets the GL pipeline object this GLAutoDrawable uses.
 
Methods inherited from interface javax.media.opengl.GLDrawable
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

GLContext setContext(GLContext newCtx)
Associate a new context to this drawable and also propagates the context/drawable switch by calling newCtx.setGLDrawable(drawable, true);. drawable might be an inner GLDrawable instance if using such a delegation pattern, or this GLAutoDrawable itself.

If the old context's drawable was an GLAutoDrawable, it's reference to the given drawable is being cleared by calling ((GLAutoDrawable)oldCtx.getGLDrawable()).setContext(null).

If the old or new context was current on this thread, it is being released before switching the drawable. The new context will be made current afterwards, if it was current before. However the user shall take extra care that not other thread attempts to make this context current. Otherwise a race condition may happen.

Disclaimer: Even though the API may allows this functionality in theory, your mileage may vary switching the drawable of an already established GLContext, i.e. which is already made current once. FIXME: Validate functionality!

Parameters:
newCtx - the new context
Returns:
the replaced GLContext, maybe null
See Also:
GLContext.setGLDrawable(GLDrawable, boolean), GLContext.setGLReadDrawable(GLDrawable), GLDrawableHelper.switchContext(GLDrawable, GLContext, GLContext, int)

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.

Parameters:
listener - The GLEventListener object to be removed

removeGLEventListener

GLEventListener removeGLEventListener(int index)
                                      throws IndexOutOfBoundsException
Removes a GLEventListener at the given index 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.

Parameters:
index - Position of the listener to be removed. Should be within (0 <= index && index < size()). An index value of -1 is interpreted as last listener, size()-1.
Returns:
The removed GLEventListener object
Throws:
IndexOutOfBoundsException - If the index is not within (0 <= index && index < size()), or -1

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

boolean invoke(boolean wait,
               GLRunnable glRunnable)

Enqueues a one-shot GLRunnable, which will be executed within the next display() call after all registered GLEventListeners display(GLAutoDrawable) methods has been called.

If no GLAnimatorControl is animating (default),
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 an GLAnimatorControl is animating,
no display() call is issued, since the animator thread performs it.

If wait is true the call blocks until the glRunnable has been executed.

If wait is true and GLDrawable.isRealized() returns false or 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 destroy() where all blocked callers are being notified.

Parameters:
wait - if true block until execution of glRunnable is finished, otherwise return immediatly w/o waiting
glRunnable - the GLRunnable to execute within display()
Returns:
true if the GLRunnable has been processed or queued, otherwise false.
See Also:
setAnimator(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:

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

createContext

GLContext createContext(GLContext shareWith)
Creates a new context for drawing to this drawable that will optionally share display lists 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 on context sharing.

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 setContext(GLContext).

The GLAutoDrawable implementation shall also set the context creation flags as customized w/ setContextCreationFlags(int).

Specified by:
createContext in interface GLDrawable

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

getUpstreamWidget

Object getUpstreamWidget()
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.

Returns:


Copyright 2010 JogAmp Community.