public interface GLAutoDrawable extends GLDrawable
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.
Since the GLContext makeCurrent
implementation is synchronized, i.e. blocks if the context
is current on another thread, the internal
GLContext for the GLAutoDrawable can be used for the event
based rendering mechanism and by end users directly.
The implementation shall initialize itself as soon as possible,
which is only possible after the attached NativeSurface becomes visible and and is realized.
The following initialization sequence should be implemented:
GLDrawable with the requested GLCapabilitiesGLDrawable to validate the GLCapabilities by calling setRealized(true).GLContext.init(..) for all
registered GLEventListeners. This can be done immediately, or with the followup display(..) call.reshape(..) for all
registered GLEventListeners. This shall be done after the init(..) calls.GLEventListener actions shall be also performed, when adding
a new one to an already initialized GLAutoDrawable.
Another implementation detail is the GLDrawable 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.
dispose(..) for all
registered GLEventListeners.GLContext.GLDrawable of the invalid state by calling setRealized(false).GLDrawable with the requested GLCapabilities
GLDrawable to revalidate the GLCapabilities by calling setRealized(true).GLContext.init(..) for all
registered GLEventListeners. This can be done immediatly, or with the followup display(..) call.reshape(..) for all
registered GLEventListeners. This shall be done after the init(..) calls.
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 GLDrawable reconfiguration (the default)
-Djogl.screenchange.action=true Enable the GLDrawable reconfiguration
| Modifier and Type | Field and Description |
|---|---|
static boolean |
SCREEN_CHANGE_ACTION_ENABLED
Flag reflecting whether the
GLDrawable reconfiguration will be issued in
case a screen device change occurred, e.g. |
| Modifier and Type | Method and Description |
|---|---|
void |
addGLEventListener(GLEventListener listener)
Adds the given
listener to the end of this drawable queue. |
void |
addGLEventListener(int index,
GLEventListener listener)
Adds the given
listener at the given index of this drawable queue. |
boolean |
areAllGLEventListenerInitialized()
Returns true if all added
GLEventListener are initialized, otherwise false. |
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.
|
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. |
GLEventListener |
disposeGLEventListener(GLEventListener listener,
boolean remove)
Disposes the given
listener via dispose(..)
if it has been initialized and added to this queue. |
void |
flushGLRunnables()
|
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() |
GLDrawable |
getDelegatedDrawable()
If the implementation uses delegation, return the delegated
GLDrawable instance,
otherwise return this instance. |
Thread |
getExclusiveContextThread() |
GL |
getGL()
Returns the
GL pipeline object this GLAutoDrawable uses. |
GLEventListener |
getGLEventListener(int index)
Returns the
GLEventListener at the given index of this drawable queue. |
int |
getGLEventListenerCount()
Returns the number of
GLEventListener of this drawable queue. |
boolean |
getGLEventListenerInitState(GLEventListener listener)
Retrieves whether the given
listener is initialized or not. |
RecursiveLock |
getUpstreamLock()
Returns the recursive lock object of the
upstream widget
to synchronize multithreaded access on top of NativeSurface.lockSurface(). |
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 have been called. |
boolean |
invoke(boolean wait,
List<GLRunnable> glRunnables)
Extends
invoke(boolean, GLRunnable) functionality
allowing to inject a list of GLRunnables. |
boolean |
isThreadGLCapable()
Indicates whether the current thread is capable of
performing OpenGL-related work.
|
GLEventListener |
removeGLEventListener(GLEventListener listener)
Removes the given
listener from this drawable queue. |
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,
boolean destroyPrevCtx)
Associate the new context,
newtCtx, to this auto-drawable. |
void |
setContextCreationFlags(int flags) |
Thread |
setExclusiveContextThread(Thread t)
|
GL |
setGL(GL gl)
Sets the
GL pipeline object this GLAutoDrawable uses. |
void |
setGLEventListenerInitState(GLEventListener listener,
boolean initialized)
Sets the given
listener's initialized state. |
getChosenGLCapabilities, getFactory, getGLProfile, getHandle, getNativeSurface, getRequestedGLCapabilities, getSurfaceHeight, getSurfaceWidth, isGLOriented, isRealized, setRealized, swapBuffers, toStringstatic final boolean SCREEN_CHANGE_ACTION_ENABLED
GLDrawable reconfiguration will be issued in
case a screen device change occurred, e.g. in a multihead environment,
where you drag the window to another monitor.GLDrawable getDelegatedDrawable()
GLDrawable instance,
otherwise return this instance.GLContext getContext()
GLContext setContext(GLContext newCtx, boolean destroyPrevCtx)
newtCtx, to this auto-drawable.
Remarks:
destroyPrevCtx is true,
otherwise it will be disassociated from this auto-drawable
via setGLDrawable(null, true); including glFinish().newCtx.setGLDrawable(drawable, true);.#makeCurrent() and #release() while drawable reassociation.auto-drawable's
upstream-locks and surfaces
to avoid a race condition. See GLAutoDrawable Locking.newCtx - the new context, maybe null for dis-association.destroyPrevCtx - if true, destroy the previous context if existsnullGLContext.setGLDrawable(GLDrawable, boolean),
GLContext.setGLReadDrawable(GLDrawable),
GLDrawableHelper.switchContext(GLDrawable, GLContext, boolean, GLContext, int)void addGLEventListener(GLEventListener listener)
listener to the end of this drawable queue.
The listeners are notified of events in the order of the queue.
The newly added listener's init(..)
method will be called once before any other of it's callback methods.
See getGLEventListenerInitState(GLEventListener) for details.
listener - The GLEventListener object to be insertedvoid addGLEventListener(int index,
GLEventListener listener)
throws IndexOutOfBoundsException
listener at the given index of this drawable queue.
The listeners are notified of events in the order of the queue.
The newly added listener's init(..)
method will be called once before any other of it's callback methods.
See getGLEventListenerInitState(GLEventListener) for details.
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 insertedIndexOutOfBoundsException - If the index is not within (0 <= index && index <= size()), or -1int getGLEventListenerCount()
GLEventListener of this drawable queue.boolean areAllGLEventListenerInitialized()
GLEventListener are initialized, otherwise false.GLEventListener getGLEventListener(int index) throws IndexOutOfBoundsException
GLEventListener at the given index of this drawable queue.index - Position of the listener to be returned.
Should be within (0 <= index && index < size()).
An index value of -1 is interpreted as last listener, size()-1.IndexOutOfBoundsException - If the index is not within (0 <= index && index < size()), or -1boolean getGLEventListenerInitState(GLEventListener listener)
listener is initialized or not.
After adding a GLEventListener it is
marked uninitialized and added to a list of to be initialized GLEventListener.
If such uninitialized GLEventListener's handler methods (reshape, display)
are about to be invoked, it's init(..) method is invoked first.
Afterwards the GLEventListener is marked initialized
and removed from the list of to be initialized GLEventListener.
This methods returns the GLEventListener initialized state,
i.e. returns false if it is included in the list of to be initialized GLEventListener,
otherwise true.
listener - the GLEventListener object to query it's initialized state.void setGLEventListenerInitState(GLEventListener listener, boolean initialized)
listener's initialized state.
This methods allows manually setting the GLEventListener initialized state,
i.e. adding it to, or removing it from the list of to be initialized GLEventListener.
See getGLEventListenerInitState(GLEventListener) for details.
Warning: This method does not validate whether the given listener's
is member of this drawable queue, i.e. added.
This method is only exposed to allow users full control over the GLEventListener's state
and is usually not recommended to change.
One use case is moving a GLContext and their initialized GLEventListener
from one GLAutoDrawable to another,
where a subsequent init(..) call after adding it
to the new owner is neither required nor desired.
See swapGLContextAndAllGLEventListener(..).
listener - the GLEventListener object to perform a state change.initialized - if true, mark the listener initialized, otherwise uninitialized.GLEventListener disposeGLEventListener(GLEventListener listener, boolean remove)
listener via dispose(..)
if it has been initialized and added to this queue.
If remove is true, the GLEventListener is removed from this drawable queue before disposal,
otherwise marked uninitialized.
If an GLAnimatorControl is being attached and the current thread is different
than the animator's thread, it is paused during the operation.
Note that this is an expensive operation, since dispose(..)
is decorated by GLContext.makeCurrent() and GLContext.release().
Use removeGLEventListener(listener) instead
if you just want to remove the listener and don't care about the disposal of the it's (OpenGL) resources.
Also note that 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.
listener - The GLEventListener object to be disposed and removed if remove is trueremove - pass true to have the listener removed from this drawable queue, otherwise pass falseGLEventListener removeGLEventListener(GLEventListener listener)
listener from this drawable queue.
This is an inexpensive operation, since the removed listener's
dispose(..) method will not be called.
Use disposeGLEventListener(listener, true)
instead to ensure disposal of the listener's (OpenGL) resources.
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.
listener - The GLEventListener object to be removedvoid setAnimator(GLAnimatorControl animatorControl) throws GLException
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.
animatorControl - null reference indicates no animator is using
this GLAutoDrawable,GLAutoDrawable.GLException - if an animator is already registered.display(),
invoke(boolean, GLRunnable),
GLAnimatorControlGLAnimatorControl getAnimator()
GLAnimatorControl implementation, using this GLAutoDrawable.setAnimator(javax.media.opengl.GLAnimatorControl),
GLAnimatorControlThread setExclusiveContextThread(Thread t) throws GLException
GLContext to the given thread.GLContext via display() and not release it
until destroy() or setExclusiveContextThread(null) has been called.
Default non-exclusive behavior is requested via setExclusiveContextThread(null),
which will cause the next call of display() on the exclusive thread to
release the GLContext. Only after it's async release, getExclusiveContextThread()
will return null.
To release a previous made exclusive thread, a user issues setExclusiveContextThread(null)
and may poll getExclusiveContextThread() until it returns null,
while the exclusive thread is still running.
Note: Setting a new exclusive thread without properly releasing a previous one will throw an GLException.
Note: Utilizing this feature w/ AWT could lead to an AWT-EDT deadlock, depending on the AWT implementation. Hence it is advised not to use it with native AWT GLAutoDrawable like GLCanvas.
One scenario could be to dedicate the context to the animator thread
and spare redundant context switches, see AnimatorBase.setExclusiveContext(boolean).
t - the exclusive thread to claim the context, or null for default operation.GLException - If an exclusive thread is still active but a new one is attempted to be setAnimatorBase.setExclusiveContext(boolean)Thread getExclusiveContextThread()
setExclusiveContextThread(Thread)boolean invoke(boolean wait,
GLRunnable glRunnable)
throws IllegalStateException
GLRunnable,
which will be executed within the next display() call
after all registered GLEventListeners
display(GLAutoDrawable)
methods have 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,
hence the GLRunnable will be executed right away.
If an animator is running,
no explicit display() call is issued, allowing the animator to perform at due time.
If wait is true the call blocks until the glRunnable
has been executed by the animator, otherwise the method returns immediately.
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.
To avoid a deadlock situation which causes an IllegalStateException one should
avoid issuing invoke while this GLAutoDrawable is being locked.
Detected deadlock situations throwing an IllegalStateException are:
wait - if true block until execution of glRunnable is finished, otherwise return immediately w/o waitingglRunnable - the GLRunnable to execute within display()true if the GLRunnable has been processed or queued, otherwise false.IllegalStateException - in case of a detected deadlock situation ahead, see above.setAnimator(GLAnimatorControl),
display(),
GLRunnable,
invoke(boolean, List),
flushGLRunnables()boolean invoke(boolean wait,
List<GLRunnable> glRunnables)
throws IllegalStateException
invoke(boolean, GLRunnable) functionality
allowing to inject a list of GLRunnables.wait - if true block until execution of the last glRunnable is finished, otherwise return immediately w/o waitingglRunnables - the GLRunnables to execute within display()true if the GLRunnables has been processed or queued, otherwise false.IllegalStateException - in case of a detected deadlock situation ahead, see invoke(boolean, GLRunnable).invoke(boolean, GLRunnable),
flushGLRunnables()void flushGLRunnables()
enqueued GLRunnable of this GLAutoDrawable
including notifying waiting executor.
The executor which might have been blocked until notified will be unblocked and all tasks removed from the queue.
invoke(boolean, GLRunnable)void destroy()
dispose(..) for all
registered GLEventListeners. Called automatically by the
window system toolkit upon receiving a destroy notification. This
routine may be called manually.void display()
Causes OpenGL rendering to be performed for this GLAutoDrawable in the following order:
display(..) for all
registered GLEventListeners. 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.
void setAutoSwapBufferMode(boolean enable)
GLDrawable.swapBuffers(..) manually.boolean getAutoSwapBufferMode()
setAutoSwapBufferMode(boolean).void setContextCreationFlags(int flags)
flags - Additional context creation flags.GLContext.setContextCreationFlags(int),
GLContext.enableGLDebugMessage(boolean)int getContextCreationFlags()
GLContext createContext(GLContext shareWith)
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.
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, boolean).
The GLAutoDrawable implementation shall also set the
context creation flags as customized w/ setContextCreationFlags(int).
createContext in interface GLDrawableGL getGL()
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.GL setGL(GL gl)
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.Object getUpstreamWidget()
GLAutoDrawable instance, if exist.
Currently known Java UI toolkits and it's known return types are:
| Toolkit | GLAutoDrawable Implementation | ~ | Return Type of getUpstreamWidget() |
| NEWT | com.jogamp.newt.opengl.GLWindow | has a | com.jogamp.newt.Window |
| SWT | com.jogamp.opengl.swt.GLCanvas | is a | org.eclipse.swt.widgets.Canvas |
| AWT | GLCanvas | is a | Canvas |
| AWT | GLJPanel | is a | JPanel |
This method may also return null if no UI toolkit is being used,
as common for offscreen rendering.
RecursiveLock getUpstreamLock()
upstream widget
to synchronize multithreaded access on top of NativeSurface.lockSurface().
boolean isThreadGLCapable()
Implementation utilizes this knowledge to determine
whether display() performs the OpenGL commands on the current thread directly
or spawns them on the dedicated OpenGL thread.
Copyright 2010 JogAmp Community.