Interface GLAutoDrawable
-
- All Superinterfaces:
GLDrawable,NativeSurfaceHolder
- All Known Subinterfaces:
AWTGLAutoDrawable,GLOffscreenAutoDrawable,GLOffscreenAutoDrawable.FBO,GLSharedContextSetter
- All Known Implementing Classes:
jogamp.opengl.GLAutoDrawableBase,GLAutoDrawableDelegate,GLCanvas,GLCanvas,GLJPanel,GLWindow
public interface GLAutoDrawable extends GLDrawable
A higher-level abstraction thanGLDrawablewhich 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
GLContextmakeCurrentimplementation is synchronized, i.e. blocks if the context is current on another thread, the internalGLContextfor the GLAutoDrawable can be used for the event based rendering mechanism and by end users directly.GLAutoDrawable Initialization
The implementation shall initialize itself as soon as possible, which is only possible after the attached
NativeSurfacebecomes visible and and is realized.
The following initialization sequence should be implemented:- Create the
GLDrawablewith the requestedGLCapabilities - Notify
GLDrawableto validate theGLCapabilitiesby callingsetRealized(true). - Create the new
GLContext. - Initialize all OpenGL resources by calling
init(..)for all registeredGLEventListeners. This can be done immediately, or with the followupdisplay(..)call. - Send a reshape event by calling
reshape(..)for all registeredGLEventListeners. This shall be done after theinit(..)calls.
GLEventListeneractions shall be also performed, whenaddinga new one to an already initializedGLAutoDrawable.GLAutoDrawable Reconfiguration
Another implementation detail is the
GLDrawablereconfiguration. One use case is where a window is being dragged to another screen with a different pixel configuration, ieGLCapabilities. The implementation shall be able to detect such cases in conjunction with the associatedNativeSurface.
For example, AWT'sCanvas'sgetGraphicsConfiguration()is capable to determine a display device change. This is demonstrated withinGLCanvas's and NEWT'sAWTCanvasgetGraphicsConfiguration()specialization. Another demonstration is NEWT'sNativeWindowimplementation on the Windows platform, which utilizes the native platform's MonitorFromWindow(HWND) function.
All OpenGL resources shall be regenerated, while the drawable'sGLCapabilitieshas to be chosen again. The following protocol shall be satisfied.- Controlled disposal:
- Dispose all OpenGL resources by calling
dispose(..)for all registeredGLEventListeners. - Destroy the
GLContext. - Notify
GLDrawableof the invalid state by callingsetRealized(false). - Controlled regeneration:
- Create the new
GLDrawablewith the requestedGLCapabilities - Notify
GLDrawableto revalidate theGLCapabilitiesby callingsetRealized(true). - Create the new
GLContext. - Initialize all OpenGL resources by calling
init(..)for all registeredGLEventListeners. This can be done immediatly, or with the followupdisplay(..)call. - Send a reshape event by calling
reshape(..)for all registeredGLEventListeners. This shall be done after theinit(..)calls.
Avoiding breakage with older applications and because of the situation mentioned above, the
booleansystem propertyjogl.screenchange.actionwill control the screen change action as follows:
-Djogl.screenchange.action=false Disable theGLDrawablereconfiguration (the default) -Djogl.screenchange.action=true Enable theGLDrawablereconfigurationGLAutoDrawable Locking
GLAutoDrawable implementations perform locking in the following order: and releases the locks accordingly: Above locking order is mandatory to guarantee atomicity of operation and to avoid race-conditions. A custom implementation or user applications requiring exclusive access shall follow the locking order. See:
-
-
Field Summary
Fields Modifier and Type Field Description static booleanSCREEN_CHANGE_ACTION_ENABLEDFlag reflecting whether theGLDrawablereconfiguration will be issued in case a screen device change occurred, e.g.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description voidaddGLEventListener(int index, GLEventListener listener)Adds the givenlistenerat the given index of this drawable queue.voidaddGLEventListener(GLEventListener listener)Adds the givenlistenerto the end of this drawable queue.booleanareAllGLEventListenerInitialized()Returns true if all addedGLEventListenerare initialized, otherwise false.GLContextcreateContext(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.voiddestroy()Destroys all resources associated with this GLAutoDrawable, inclusive the GLContext.voiddisplay()Causes OpenGL rendering to be performed for this GLAutoDrawable in the following order: Callingdisplay(..)for all registeredGLEventListeners.GLEventListenerdisposeGLEventListener(GLEventListener listener, boolean remove)Disposes the givenlistenerviadispose(..)if it has been initialized and added to this queue.voidflushGLRunnables()GLAnimatorControlgetAnimator()booleangetAutoSwapBufferMode()Indicates whether automatic buffer swapping is enabled for this drawable.GLContextgetContext()Returns the context associated with this drawable.intgetContextCreationFlags()GLDrawablegetDelegatedDrawable()If the implementation uses delegation, return the delegatedGLDrawableinstance, otherwise returnthisinstance.ThreadgetExclusiveContextThread()GLgetGL()Returns theGLpipeline object this GLAutoDrawable uses.GLEventListenergetGLEventListener(int index)Returns theGLEventListenerat the given index of this drawable queue.intgetGLEventListenerCount()Returns the number ofGLEventListenerof this drawable queue.booleangetGLEventListenerInitState(GLEventListener listener)Retrieves whether the givenlisteneris initialized or not.RecursiveLockgetUpstreamLock()Returns the recursive lock object of theupstream widgetto synchronize multithreaded access on top ofNativeSurface.lockSurface().ObjectgetUpstreamWidget()Method may return the upstream UI toolkit object holding thisGLAutoDrawableinstance, if exist.booleaninvoke(boolean wait, GLRunnable glRunnable)Enqueues a one-shotGLRunnable, which will be executed within the nextdisplay()call after all registeredGLEventListenersdisplay(GLAutoDrawable)methods have been called.booleaninvoke(boolean wait, List<GLRunnable> glRunnables)Extendsinvoke(boolean, GLRunnable)functionality allowing to inject a list ofGLRunnables.booleanisThreadGLCapable()Indicates whether the current thread is capable of performing OpenGL-related work.GLEventListenerremoveGLEventListener(GLEventListener listener)Removes the givenlistenerfrom this drawable queue.voidsetAnimator(GLAnimatorControl animatorControl)Registers the usage of an animator, anGLAnimatorControlimplementation.voidsetAutoSwapBufferMode(boolean enable)Enables or disables automatic buffer swapping for this drawable.GLContextsetContext(GLContext newCtx, boolean destroyPrevCtx)Associate the new context,newtCtx, to this auto-drawable.voidsetContextCreationFlags(int flags)ThreadsetExclusiveContextThread(Thread t)GLsetGL(GL gl)Sets theGLpipeline object this GLAutoDrawable uses.voidsetGLEventListenerInitState(GLEventListener listener, boolean initialized)Sets the givenlistener'sinitialized state.-
Methods inherited from interface com.jogamp.opengl.GLDrawable
getChosenGLCapabilities, getFactory, getGLProfile, getHandle, getNativeSurface, getRequestedGLCapabilities, getSurfaceHeight, getSurfaceWidth, isGLOriented, isRealized, setRealized, swapBuffers, toString
-
-
-
-
Field Detail
-
SCREEN_CHANGE_ACTION_ENABLED
static final boolean SCREEN_CHANGE_ACTION_ENABLED
Flag reflecting whether theGLDrawablereconfiguration will be issued in case a screen device change occurred, e.g. in a multihead environment, where you drag the window to another monitor.
-
-
Method Detail
-
getDelegatedDrawable
GLDrawable getDelegatedDrawable()
If the implementation uses delegation, return the delegatedGLDrawableinstance, otherwise returnthisinstance.
-
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, boolean destroyPrevCtx)
Associate the new context,newtCtx, to this auto-drawable.Remarks:
- The currently associated context will be destroyed if
destroyPrevCtxistrue, otherwise it will be disassociated from this auto-drawable viasetGLDrawable(null, true);includingglFinish(). - The new context will be associated with this auto-drawable
via
newCtx.setGLDrawable(drawable, true);. - If the old context was current on this thread, it is being released after disassociating this auto-drawable.
- If the new context was current on this thread, it is being released before associating this auto-drawable and made current afterwards.
- Implementation may issue
GLContext.makeCurrent()andGLContext.release()while drawable reassociation. - The user shall take extra care of thread synchronization,
i.e. lock the involved
auto-drawable'supstream-locksandsurfacesto avoid a race condition. See GLAutoDrawable Locking.
- Parameters:
newCtx- the new context, maybenullfor dis-association.destroyPrevCtx- iftrue, destroy the previous context if exists- Returns:
- the previous GLContext, maybe
null - See Also:
GLContext.setGLDrawable(GLDrawable, boolean),GLContext.setGLReadDrawable(GLDrawable),GLDrawableHelper.switchContext(GLDrawable, GLContext, boolean, GLContext, int)
- The currently associated context will be destroyed if
-
addGLEventListener
void addGLEventListener(GLEventListener listener)
Adds the givenlistenerto the end of this drawable queue. Thelistenersare 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. SeegetGLEventListenerInitState(GLEventListener)for details.- Parameters:
listener- The GLEventListener object to be inserted
-
addGLEventListener
void addGLEventListener(int index, GLEventListener listener) throws IndexOutOfBoundsExceptionAdds the givenlistenerat the given index of this drawable queue. Thelistenersare 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. SeegetGLEventListenerInitState(GLEventListener)for details.- 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
-
getGLEventListenerCount
int getGLEventListenerCount()
Returns the number ofGLEventListenerof this drawable queue.- Returns:
- The number of GLEventListener objects of this drawable queue.
-
areAllGLEventListenerInitialized
boolean areAllGLEventListenerInitialized()
Returns true if all addedGLEventListenerare initialized, otherwise false.- Since:
- 2.2
-
getGLEventListener
GLEventListener getGLEventListener(int index) throws IndexOutOfBoundsException
Returns theGLEventListenerat the given index of this drawable queue.- Parameters:
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.- Returns:
- The GLEventListener object at the given index.
- Throws:
IndexOutOfBoundsException- If the index is not within (0 <= index && index < size()), or -1
-
getGLEventListenerInitState
boolean getGLEventListenerInitState(GLEventListener listener)
Retrieves whether the givenlisteneris initialized or not.After
addingaGLEventListenerit is marked uninitialized and added to a list of to be initializedGLEventListener. If such uninitializedGLEventListener's handler methods (reshape, display) are about to be invoked, it'sinit(..)method is invoked first. Afterwards theGLEventListeneris marked initialized and removed from the list of to be initializedGLEventListener.This methods returns the
GLEventListenerinitialized state, i.e. returnsfalseif it is included in the list of to be initializedGLEventListener, otherwisetrue.- Parameters:
listener- the GLEventListener object to query it's initialized state.
-
setGLEventListenerInitState
void setGLEventListenerInitState(GLEventListener listener, boolean initialized)
Sets the givenlistener'sinitialized state.This methods allows manually setting the
GLEventListenerinitialized state, i.e. adding it to, or removing it from the list of to be initializedGLEventListener. SeegetGLEventListenerInitState(GLEventListener)for details.Warning: This method does not validate whether the given
listener'sis 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
GLContextand their initializedGLEventListenerfrom oneGLAutoDrawableto another, where a subsequentinit(..)call after adding it to the new owner is neither required nor desired. SeeswapGLContextAndAllGLEventListener(..).- Parameters:
listener- the GLEventListener object to perform a state change.initialized- iftrue, mark the listener initialized, otherwise uninitialized.
-
disposeGLEventListener
GLEventListener disposeGLEventListener(GLEventListener listener, boolean remove)
Disposes the givenlistenerviadispose(..)if it has been initialized and added to this queue.If
removeistrue, theGLEventListeneris removed from this drawable queue before disposal, otherwise marked uninitialized.If an
GLAnimatorControlis being attached and the current thread is different thanthe animator's thread, it is paused during the operation.Note that this is an expensive operation, since
dispose(..)is decorated byGLContext.makeCurrent()andGLContext.release().Use
removeGLEventListener(listener)instead if you just want to remove thelistenerand don't care about the disposal of the it's (OpenGL) resources.Also note that this is done from within a particular drawable's
GLEventListenerhandler (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 disposed and removed ifremoveistrueremove- passtrueto have thelistenerremoved from this drawable queue, otherwise passfalse- Returns:
- the disposed and/or removed GLEventListener, or null if no action was performed, i.e. listener was not added
-
removeGLEventListener
GLEventListener removeGLEventListener(GLEventListener listener)
Removes the givenlistenerfrom 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 thelistener's (OpenGL) resources.Note that if this is done from within a particular drawable's
GLEventListenerhandler (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- Returns:
- the removed GLEventListener, or null if listener was not added
-
setAnimator
void setAnimator(GLAnimatorControl animatorControl) throws GLException
Registers the usage of an animator, anGLAnimatorControlimplementation. The animator will be queried whether it's animating, ie periodically issuingdisplay()calls or not.This method shall be called by an animator implementation only,
e.g.AnimatorBase.add(com.jogamp.opengl.GLAutoDrawable), passing it's control implementation,
andAnimatorBase.remove(com.jogamp.opengl.GLAutoDrawable), passingnull.Impacts
display()andinvoke(boolean, GLRunnable)semantics.- Parameters:
animatorControl-nullreference indicates no animator is using thisGLAutoDrawable,
a valid reference indicates an animator is using thisGLAutoDrawable.- Throws:
GLException- if an animator is already registered.- See Also:
display(),invoke(boolean, GLRunnable),GLAnimatorControl
-
getAnimator
GLAnimatorControl getAnimator()
- Returns:
- the registered
GLAnimatorControlimplementation, using thisGLAutoDrawable. - See Also:
setAnimator(com.jogamp.opengl.GLAnimatorControl),GLAnimatorControl
-
setExclusiveContextThread
Thread setExclusiveContextThread(Thread t) throws GLException
Dedicates this instance'sGLContextto the given thread.
The thread will exclusively claim theGLContextviadisplay()and not release it untildestroy()orsetExclusiveContextThread(null)has been called.Default non-exclusive behavior is requested via
setExclusiveContextThread(null), which will cause the next call ofdisplay()on the exclusive thread to release theGLContext. Only after it's async release,getExclusiveContextThread()will returnnull.To release a previous made exclusive thread, a user issues
setExclusiveContextThread(null)and may pollgetExclusiveContextThread()until it returnsnull, 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 threadand spare redundant context switches, seeAnimatorBase.setExclusiveContext(boolean).- Parameters:
t- the exclusive thread to claim the context, ornullfor default operation.- Returns:
- previous exclusive context thread
- Throws:
GLException- If an exclusive thread is still active but a new one is attempted to be set- See Also:
AnimatorBase.setExclusiveContext(boolean)
-
getExclusiveContextThread
Thread getExclusiveContextThread()
- See Also:
setExclusiveContextThread(Thread)
-
invoke
boolean invoke(boolean wait, GLRunnable glRunnable) throws IllegalStateExceptionEnqueues a one-shotGLRunnable, which will be executed within the nextdisplay()call after all registeredGLEventListenersdisplay(GLAutoDrawable)methods have been called.The given
GLRunnable.run(GLAutoDrawable)shall return true to indicate that the GL [back] framebuffer remains intact by this runnable.
If returning falseGLAutoDrawablewill calldisplay(GLAutoDrawable)of all registeredGLEventListeners once more to reinstate the framebuffer.If no
GLAnimatorControlis animating (default),
or if the current thread is the animator thread,
adisplay()call is issued after enqueue theGLRunnable, hence theGLRunnablewill be executed right away.
If an
animatoris running,
no explicitdisplay()call is issued, allowing theanimatorto perform at due time.
If
waitistruethe call blocks until theglRunnablehas been executed by theanimator, otherwise the method returns immediately.If
waitistrueandGLDrawable.isRealized()returnsfalseorgetContext()returnsnull, the call is ignored and returnsfalse.
This helps avoiding deadlocking the caller.The internal queue of
GLRunnable's is being flushed withdestroy()where all blocked callers are being notified.To avoid a deadlock situation which causes an
IllegalStateExceptionone should avoid issuinginvokewhile this GLAutoDrawable is being locked.
Detected deadlock situations throwing anIllegalStateExceptionare:- Parameters:
wait- iftrueblock until execution ofglRunnableis finished, otherwise return immediately w/o waitingglRunnable- theGLRunnableto execute withindisplay()- Returns:
trueif theGLRunnablehas been processed or queued, otherwisefalse.- Throws:
IllegalStateException- in case of a detected deadlock situation ahead, see above.- See Also:
setAnimator(GLAnimatorControl),display(),GLRunnable,invoke(boolean, List),flushGLRunnables()
-
invoke
boolean invoke(boolean wait, List<GLRunnable> glRunnables) throws IllegalStateExceptionExtendsinvoke(boolean, GLRunnable)functionality allowing to inject a list ofGLRunnables.- Parameters:
wait- iftrueblock until execution of the lastglRunnableis finished, otherwise return immediately w/o waitingglRunnables- theGLRunnables to execute withindisplay()- Returns:
trueif theGLRunnables has been processed or queued, otherwisefalse.- Throws:
IllegalStateException- in case of a detected deadlock situation ahead, seeinvoke(boolean, GLRunnable).- See Also:
invoke(boolean, GLRunnable),flushGLRunnables()
-
flushGLRunnables
void flushGLRunnables()
Flushes allenqueuedGLRunnableof thisGLAutoDrawableincluding notifying waiting executor.The executor which might have been blocked until notified will be unblocked and all tasks removed from the queue.
- Since:
- 2.2
- See Also:
invoke(boolean, 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 callingdispose(..)for all registeredGLEventListeners. 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 registeredGLEventListeners. - Executes all one-shot
GLRunnable, enqueued viainvoke(boolean, GLRunnable).
May be called periodically by a running
GLAnimatorControlimplementation,
which must register itself withsetAnimator(com.jogamp.opengl.GLAnimatorControl).Called automatically by the window system toolkit upon receiving a repaint() request,
except anGLAnimatorControlimplementationGLAnimatorControl.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 registeredGLEventListeners before making the actualdisplay(..)calls, in case this has not been done yet. - Calling
-
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 {@link #swapBuffers(..)} manually.
-
getAutoSwapBufferMode
boolean getAutoSwapBufferMode()
Indicates whether automatic buffer swapping is enabled for this drawable. SeesetAutoSwapBufferMode(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 buffer objects, textures and other server-side OpenGL objects with the specified GLContext.The GLContext
shareneed 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 asGLSharedContextSetter.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).- Specified by:
createContextin interfaceGLDrawable
-
getGL
GL getGL()
Returns theGLpipeline object this GLAutoDrawable uses. If this method is called outside of theGLEventListener'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 theGLpipeline 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 thisGLAutoDrawableinstance, if exist.Currently known Java UI toolkits and it's known return types are:
However, the result may be other object types than the listed above due to new supported toolkits.Toolkit GLAutoDrawable Implementation ~ Return Type of getUpstreamWidget() NEWT GLWindowhas a WindowSWT GLCanvasis a CanvasAWT GLCanvasis a CanvasAWT GLJPanelis a JPanelThis method may also return
nullif no UI toolkit is being used, as common for offscreen rendering.
-
getUpstreamLock
RecursiveLock getUpstreamLock()
Returns the recursive lock object of theupstream widgetto synchronize multithreaded access on top ofNativeSurface.lockSurface().- Since:
- 2.2
-
isThreadGLCapable
boolean isThreadGLCapable()
Indicates whether the current thread is capable of performing OpenGL-related work.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.- Since:
- 2.2
-
-