JOGL 2.3.2 · com.jogamp.opengl.GLAutoDrawable

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.

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.

GLAutoDrawable Initialization

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:

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 immediately, 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: The last to GLEventListener actions shall be also performed, when adding a new one to an already initialized GLAutoDrawable.

GLAutoDrawable Reconfiguration

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 java.awt.Canvas 's getGraphicsConfiguration() is capable to determine a display device change. This is demonstrated within com.jogamp.opengl.awt.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.

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.

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

GLAutoDrawable 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

Modifier and Type	Field and Description
public static final boolean	SCREEN_CHANGE_ACTION_ENABLED Flag reflecting whether the `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.

Method Summary

Modifier and Type	Method and Description
public void	addGLEventListener(GLEventListener The GLEventListener object to be inserted listener) Adds the given `listener` to the end of this drawable queue.
public void	addGLEventListener(int 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(). index, GLEventListener The GLEventListener object to be inserted listener) Adds the given `listener` at the given index of this drawable queue.
public boolean	areAllGLEventListenerInitialized() Returns true if all added `GLEventListener` are initialized, otherwise false.
public GLContext	createContext(GLContext shareWith) Redeclares com.jogamp.opengl.GLDrawable.createContext. 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.
public void	destroy() Destroys all resources associated with this GLAutoDrawable, inclusive the GLContext.
public void	display() Causes OpenGL rendering to be performed for this GLAutoDrawable in the following order: Calling `display(..)` for all registered `GLEventListener`s. Executes all one-shot `GLRunnable`, enqueued via `invoke(boolean, GLRunnable)`.
public GLEventListener	Returns: the disposed and/or removed GLEventListener, or null if no action was performed, i.e. listener was not added disposeGLEventListener(GLEventListener The GLEventListener object to be disposed and removed if `remove` is `true` listener, boolean pass `true` to have the `listener` removed from this drawable queue, otherwise pass `false` remove) Disposes the given `listener` via `dispose(..)` if it has been initialized and added to this queue.
public void	flushGLRunnables() Flushes all `enqueued` `GLRunnable` of this `GLAutoDrawable` including notifying waiting executor.
public GLAnimatorControl	Returns: the registered `com.jogamp.opengl.GLAnimatorControl` implementation, using this `GLAutoDrawable`. getAnimator()
public boolean	getAutoSwapBufferMode() Indicates whether automatic buffer swapping is enabled for this drawable.
public GLContext	getContext() Returns the context associated with this drawable.
public int	Returns: Additional context creation flags getContextCreationFlags()
public GLDrawable	getDelegatedDrawable() If the implementation uses delegation, return the delegated `GLDrawable` instance, otherwise return `this` instance.
public Thread	getExclusiveContextThread()
public GL	getGL() Returns the `GL` pipeline object this GLAutoDrawable uses.
public GLEventListener	Returns: The GLEventListener object at the given index. getGLEventListener(int 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. index) Returns the `GLEventListener` at the given index of this drawable queue.
public int	Returns: The number of GLEventListener objects of this drawable queue. getGLEventListenerCount() Returns the number of `GLEventListener` of this drawable queue.
public boolean	getGLEventListenerInitState(GLEventListener the GLEventListener object to query it's initialized state. listener) Retrieves whether the given `listener` is initialized or not.
public RecursiveLock	getUpstreamLock() Returns the recursive lock object of the `upstream widget` to synchronize multithreaded access on top of `NativeSurface#lockSurface()`.
public Object	getUpstreamWidget() Method may return the upstream UI toolkit object holding this `GLAutoDrawable` instance, if exist.</td<></td<></td<></td<></td<>
public boolean	Returns: `true` if the `GLRunnable` has been processed or queued, otherwise `false`. invoke(boolean if `true` block until execution of `glRunnable` is finished, otherwise return immediately w/o waiting wait, GLRunnable the `GLRunnable` to execute within `display()` glRunnable) Enqueues a one-shot `GLRunnable`, which will be executed within the next `display()` call after all registered `GLEventListener`s `display(GLAutoDrawable)` methods have been called.
public boolean	Returns: `true` if the `GLRunnable`s has been processed or queued, otherwise `false`. invoke(boolean if `true` block until execution of the last `glRunnable` is finished, otherwise return immediately w/o waiting wait, List<GLRunnable> the `GLRunnable`s to execute within `display()` glRunnables) Extends `invoke(boolean, GLRunnable)` functionality allowing to inject a list of `GLRunnable`s.
public boolean	isThreadGLCapable() Indicates whether the current thread is capable of performing OpenGL-related work.
public GLEventListener	Returns: the removed GLEventListener, or null if listener was not added removeGLEventListener(GLEventListener The GLEventListener object to be removed listener) Removes the given `listener` from this drawable queue.
public void	setAnimator(GLAnimatorControl `null` reference indicates no animator is using this `GLAutoDrawable`, a valid reference indicates an animator is using this `GLAutoDrawable`. animatorControl) Registers the usage of an animator, an `com.jogamp.opengl.GLAnimatorControl` implementation.
public void	setAutoSwapBufferMode(boolean enable) Enables or disables automatic buffer swapping for this drawable.
public GLContext	Returns: the previous GLContext, maybe `null` setContext(GLContext the new context, maybe `null` for dis-association. newCtx, boolean if `true`, destroy the previous context if exists destroyPrevCtx) Associate the new context, `newtCtx`, to this auto-drawable.
public void	setContextCreationFlags(int Additional context creation flags. flags)
public Thread	Returns: previous exclusive context thread setExclusiveContextThread(Thread the exclusive thread to claim the context, or `null` for default operation. t) Dedicates this instance's `GLContext` to the given thread.
public GL	Returns: the set GL pipeline or null if not successful setGL(GL gl) Sets the `GL` pipeline object this GLAutoDrawable uses.
public void	setGLEventListenerInitState(GLEventListener the GLEventListener object to perform a state change. listener, boolean if `true`, mark the listener initialized, otherwise uninitialized. initialized) Sets the given `listener's` initialized state.

Inherited from com.jogamp.opengl.GLDrawable:: getChosenGLCapabilities getFactory getGLProfile getHandle getNativeSurface getRequestedGLCapabilities getSurfaceHeight getSurfaceWidth isGLOriented isRealized setRealized swapBuffers toString

Field Detail

SCREEN_CHANGE_ACTION_ENABLED	back to summary
public static final boolean SCREEN_CHANGE_ACTION_ENABLED Flag reflecting whether the `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.

Method Detail

addGLEventListener back to summary

addGLEventListener	back to summary
public void addGLEventListener(GLEventListener listener) Adds the given `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. Parameters listener:GLEventListener The GLEventListener object to be inserted

public void addGLEventListener(GLEventListener listener)

Adds the given 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.

Parameters

listener:GLEventListener: The GLEventListener object to be inserted

addGLEventListener back to summary

addGLEventListener	back to summary
public void addGLEventListener(int index, GLEventListener listener) throws IndexOutOfBoundsException Adds the given `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. Parameters index:int 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:GLEventListener The GLEventListener object to be inserted Exceptions IndexOutOfBoundsException: If the index is not within (0 <= index && index <= size()), or -1

public void addGLEventListener(int index, GLEventListener listener) throws IndexOutOfBoundsException

Adds the given 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.

Parameters

index:int: 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:GLEventListener: The GLEventListener object to be inserted

Exceptions

IndexOutOfBoundsException:: If the index is not within (0 <= index && index <= size()), or -1

areAllGLEventListenerInitialized back to summary

areAllGLEventListenerInitialized	back to summary
public boolean areAllGLEventListenerInitialized() Returns true if all added `GLEventListener` are initialized, otherwise false. Since 2.2

public boolean areAllGLEventListenerInitialized()

Returns true if all added GLEventListener are initialized, otherwise false.

Since: 2.2

createContext back to summary

createContext	back to summary
public GLContext createContext(GLContext shareWith) Redeclares com.jogamp.opengl.GLDrawable.createContext. Doc from com.jogamp.opengl.GLDrawable.createContext. 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 `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)`. Annotations @Override

public GLContext createContext(GLContext shareWith)

Redeclares com.jogamp.opengl.GLDrawable.createContext.

Doc from com.jogamp.opengl.GLDrawable.createContext.

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

Annotations

@Override

destroy back to summary

destroy	back to summary
public 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.

public 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 back to summary

display	back to summary
public void display() Causes OpenGL rendering to be performed for this GLAutoDrawable in the following order: Calling `display(..)` for all registered `GLEventListener`s. Executes all one-shot `GLRunnable`, enqueued via `invoke(boolean, GLRunnable)`. May be called periodically by a running `com.jogamp.opengl.GLAnimatorControl` implementation, which must register itself with `setAnimator(com.jogamp.opengl.GLAnimatorControl)`. Called automatically by the window system toolkit upon receiving a repaint() request, except an `com.jogamp.opengl.GLAnimatorControl` implementation `com.jogamp.opengl.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 `GLEventListener`s before making the actual `display(..)` calls, in case this has not been done yet. See Also `setAnimator(com.jogamp.opengl.GLAnimatorControl)`

public 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 com.jogamp.opengl.GLAnimatorControl implementation,
which must register itself with setAnimator(com.jogamp.opengl.GLAnimatorControl).

Called automatically by the window system toolkit upon receiving a repaint() request,
except an com.jogamp.opengl.GLAnimatorControl implementation com.jogamp.opengl.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(com.jogamp.opengl.GLAnimatorControl)

disposeGLEventListener back to summary

disposeGLEventListener	back to summary
public GLEventListener disposeGLEventListener(GLEventListener listener, boolean remove) Disposes the given `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. Parameters listener:GLEventListener The GLEventListener object to be disposed and removed if `remove` is `true` remove:boolean pass `true` to have the `listener` removed from this drawable queue, otherwise pass `false` Returns:GLEventListener the disposed and/or removed GLEventListener, or null if no action was performed, i.e. listener was not added

public GLEventListener disposeGLEventListener(GLEventListener listener, boolean remove)

Disposes the given 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.

Parameters

listener:GLEventListener: The GLEventListener object to be disposed and removed if remove is true
remove:boolean: pass true to have the listener removed from this drawable queue, otherwise pass false

Returns:GLEventListener

the disposed and/or removed GLEventListener, or null if no action was performed, i.e. listener was not added

flushGLRunnables back to summary

flushGLRunnables	back to summary
public void flushGLRunnables() Flushes all `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. Since 2.2 See Also `invoke(boolean, GLRunnable)`

public void flushGLRunnables()

Flushes all 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.

Since: 2.2
See Also: invoke(boolean, GLRunnable)

getAnimator	back to summary
public GLAnimatorControl getAnimator() Returns:GLAnimatorControl the registered `com.jogamp.opengl.GLAnimatorControl` implementation, using this `GLAutoDrawable`. See Also `setAnimator(com.jogamp.opengl.GLAnimatorControl)`, `com.jogamp.opengl.GLAnimatorControl`

getAutoSwapBufferMode	back to summary
public boolean getAutoSwapBufferMode() Indicates whether automatic buffer swapping is enabled for this drawable. See `setAutoSwapBufferMode`.

getContext	back to summary
public 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.

getContextCreationFlags	back to summary
public int getContextCreationFlags() Returns:int Additional context creation flags

getDelegatedDrawable	back to summary
public GLDrawable getDelegatedDrawable() If the implementation uses delegation, return the delegated `GLDrawable` instance, otherwise return `this` instance.

getExclusiveContextThread	back to summary
public Thread getExclusiveContextThread() See Also `setExclusiveContextThread(Thread)`

getGL back to summary

getGL	back to summary
public 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.

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

getGLEventListener back to summary

getGLEventListener	back to summary
public GLEventListener getGLEventListener(int index) throws IndexOutOfBoundsException Returns the `GLEventListener` at the given index of this drawable queue. Parameters index:int 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:GLEventListener The GLEventListener object at the given index. Exceptions IndexOutOfBoundsException: If the index is not within (0 <= index && index < size()), or -1

public GLEventListener getGLEventListener(int index) throws IndexOutOfBoundsException

Returns the GLEventListener at the given index of this drawable queue.

Parameters

index:int: 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:GLEventListener

The GLEventListener object at the given index.

Exceptions

IndexOutOfBoundsException:: If the index is not within (0 <= index && index < size()), or -1

getGLEventListenerCount back to summary

getGLEventListenerCount	back to summary
public int getGLEventListenerCount() Returns the number of `GLEventListener` of this drawable queue. Returns:int The number of GLEventListener objects of this drawable queue.

public int getGLEventListenerCount()

Returns the number of GLEventListener of this drawable queue.

Returns:int: The number of GLEventListener objects of this drawable queue.

getGLEventListenerInitState back to summary

getGLEventListenerInitState	back to summary
public boolean getGLEventListenerInitState(GLEventListener listener) Retrieves whether the given `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`. Parameters listener:GLEventListener the GLEventListener object to query it's initialized state.

public boolean getGLEventListenerInitState(GLEventListener listener)

Retrieves whether the given 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.

Parameters

listener:GLEventListener: the GLEventListener object to query it's initialized state.

getUpstreamLock back to summary

getUpstreamLock	back to summary
public RecursiveLock getUpstreamLock() Returns the recursive lock object of the `upstream widget` to synchronize multithreaded access on top of `NativeSurface#lockSurface()`. See GLAutoDrawable Locking. Since 2.2

public RecursiveLock getUpstreamLock()

Returns the recursive lock object of the upstream widget to synchronize multithreaded access on top of NativeSurface#lockSurface().

See GLAutoDrawable Locking.

Since: 2.2

getUpstreamWidget back to summary

public 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	`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	`com.jogamp.opengl.awt.GLCanvas`	is a	`java.awt.Canvas`
AWT	`com.jogamp.opengl.awt.GLJPanel`	is a	`javax.swing.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.

invoke back to summary

invoke	back to summary
public boolean invoke(boolean wait, GLRunnable glRunnable) throws IllegalStateException Enqueues a one-shot `GLRunnable`, which will be executed within the next `display()` call after all registered `GLEventListener`s `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 `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: `Animator` is running on another thread and waiting and is locked on current thread, but is not `GL-Thread` No `Animator` is running on another thread and is locked on current thread, but is not `GL-Thread` Parameters wait:boolean if `true` block until execution of `glRunnable` is finished, otherwise return immediately w/o waiting glRunnable:GLRunnable the `GLRunnable` to execute within `display()` Returns:boolean `true` if the `GLRunnable` has been processed or queued, otherwise `false`. Exceptions IllegalStateException: in case of a detected deadlock situation ahead, see above. See Also `setAnimator(GLAnimatorControl)`, `display()`, `GLRunnable`, `invoke(boolean, List)`, `flushGLRunnables()`

public boolean invoke(boolean wait, GLRunnable glRunnable) throws IllegalStateException

Enqueues a one-shot 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 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:

Animator is running on another thread and waiting and is locked on current thread, but is not GL-Thread
No Animator is running on another thread and is locked on current thread, but is not GL-Thread

Parameters

wait:boolean: if true block until execution of glRunnable is finished, otherwise return immediately w/o waiting
glRunnable:GLRunnable: the GLRunnable to execute within display()

Returns:boolean

true if the GLRunnable has been processed or queued, otherwise false.

Exceptions

IllegalStateException:: in case of a detected deadlock situation ahead, see above.

invoke back to summary

invoke	back to summary
public boolean invoke(boolean wait, List<GLRunnable> glRunnables) throws IllegalStateException Extends `invoke(boolean, GLRunnable)` functionality allowing to inject a list of `GLRunnable`s. Parameters wait:boolean if `true` block until execution of the last `glRunnable` is finished, otherwise return immediately w/o waiting glRunnables:List<GLRunnable> the `GLRunnable`s to execute within `display()` Returns:boolean `true` if the `GLRunnable`s has been processed or queued, otherwise `false`. Exceptions IllegalStateException: in case of a detected deadlock situation ahead, see `invoke(boolean, GLRunnable)`. See Also `invoke(boolean, GLRunnable)`, `flushGLRunnables()`

public boolean invoke(boolean wait, List<GLRunnable> glRunnables) throws IllegalStateException

Extends invoke(boolean, GLRunnable) functionality allowing to inject a list of GLRunnables.

Parameters

wait:boolean: if true block until execution of the last glRunnable is finished, otherwise return immediately w/o waiting
glRunnables:List<GLRunnable>: the GLRunnables to execute within display()

Returns:boolean

true if the GLRunnables has been processed or queued, otherwise false.

Exceptions

IllegalStateException:: in case of a detected deadlock situation ahead, see invoke(boolean, GLRunnable).

isThreadGLCapable back to summary

isThreadGLCapable	back to summary
public 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

public 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

removeGLEventListener back to summary

removeGLEventListener	back to summary
public GLEventListener removeGLEventListener(GLEventListener listener) Removes the given `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. Parameters listener:GLEventListener The GLEventListener object to be removed Returns:GLEventListener the removed GLEventListener, or null if listener was not added

public GLEventListener removeGLEventListener(GLEventListener listener)

Removes the given 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.

Parameters

listener:GLEventListener: The GLEventListener object to be removed

Returns:GLEventListener

the removed GLEventListener, or null if listener was not added

setAnimator back to summary

setAnimator	back to summary
public void setAnimator(GLAnimatorControl animatorControl) throws GLException Registers the usage of an animator, an `com.jogamp.opengl.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. `com.jogamp.opengl.util.Animator#add(com.jogamp.opengl.GLAutoDrawable)`, passing it's control implementation, and `com.jogamp.opengl.util.Animator#remove(com.jogamp.opengl.GLAutoDrawable)`, passing `null`. Impacts `display()` and `invoke(boolean, GLRunnable)` semantics. Parameters animatorControl:GLAnimatorControl `null` reference indicates no animator is using this `GLAutoDrawable`, a valid reference indicates an animator is using this `GLAutoDrawable`. Exceptions GLException: if an animator is already registered. See Also `display()`, `invoke(boolean, GLRunnable)`, `com.jogamp.opengl.GLAnimatorControl`

public void setAnimator(GLAnimatorControl animatorControl) throws GLException

Registers the usage of an animator, an com.jogamp.opengl.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. com.jogamp.opengl.util.Animator#add(com.jogamp.opengl.GLAutoDrawable), passing it's control implementation,
and com.jogamp.opengl.util.Animator#remove(com.jogamp.opengl.GLAutoDrawable), passing null.

Impacts display() and invoke(boolean, GLRunnable) semantics.

Parameters

animatorControl:GLAnimatorControl: null reference indicates no animator is using this GLAutoDrawable,
a valid reference indicates an animator is using this GLAutoDrawable.

Exceptions

GLException:: if an animator is already registered.

setAutoSwapBufferMode	back to summary
public 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 `swapBuffers(..)` manually.

setContext back to summary

setContext	back to summary
public GLContext setContext(GLContext newCtx, boolean destroyPrevCtx) Associate the new context, `newtCtx`, to this auto-drawable. Remarks: The currently associated context will be destroyed if `destroyPrevCtx` is `true`, otherwise it will be disassociated from this auto-drawable via `setGLDrawable(null, true);` including `glFinish()`. 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 `makeCurrent()` and `release()` while drawable reassociation. The user shall take extra care of thread synchronization, i.e. lock the involved `auto-drawable's` `upstream-locks` and `surfaces` to avoid a race condition. See GLAutoDrawable Locking. Parameters newCtx:GLContext the new context, maybe `null` for dis-association. destroyPrevCtx:boolean if `true`, destroy the previous context if exists Returns:GLContext the previous GLContext, maybe `null` See Also `GLContext#setGLDrawable(GLDrawable, boolean)`, `GLContext#setGLReadDrawable(GLDrawable)`, `jogamp.opengl.GLDrawableHelper#switchContext(GLDrawable, GLContext, boolean, GLContext, int)`

public GLContext setContext(GLContext newCtx, boolean destroyPrevCtx)

Associate the new context, newtCtx, to this auto-drawable.

Remarks:

The currently associated context will be destroyed if destroyPrevCtx is true, otherwise it will be disassociated from this auto-drawable via setGLDrawable(null, true); including glFinish().
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 makeCurrent() and release() while drawable reassociation.
The user shall take extra care of thread synchronization, i.e. lock the involved auto-drawable's upstream-locks and surfaces to avoid a race condition. See GLAutoDrawable Locking.

Parameters

newCtx:GLContext: the new context, maybe null for dis-association.
destroyPrevCtx:boolean: if true, destroy the previous context if exists

Returns:GLContext

the previous GLContext, maybe null

setContextCreationFlags	back to summary
public void setContextCreationFlags(int flags) Parameters flags:int Additional context creation flags. See Also `GLContext#setContextCreationFlags(int)`, `GLContext#enableGLDebugMessage(boolean)`

setExclusiveContextThread back to summary

setExclusiveContextThread	back to summary
public Thread setExclusiveContextThread(Thread t) throws GLException Dedicates this instance's `GLContext` to the given thread. The thread will exclusively claim the `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 `com.jogamp.opengl.util.AnimatorBase#setExclusiveContext(boolean)`. Parameters t:Thread the exclusive thread to claim the context, or `null` for default operation. Returns:Thread previous exclusive context thread Exceptions GLException: If an exclusive thread is still active but a new one is attempted to be set See Also `com.jogamp.opengl.util.AnimatorBase#setExclusiveContext(boolean)`

public Thread setExclusiveContextThread(Thread t) throws GLException

Dedicates this instance's GLContext to the given thread.
The thread will exclusively claim the 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 com.jogamp.opengl.util.AnimatorBase#setExclusiveContext(boolean).

Parameters

t:Thread: the exclusive thread to claim the context, or null for default operation.

Returns:Thread

previous exclusive context thread

Exceptions

GLException:: If an exclusive thread is still active but a new one is attempted to be set

setGL back to summary

setGL	back to summary
public 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:GL the set GL pipeline or null if not successful

public 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:GL: the set GL pipeline or null if not successful

setGLEventListenerInitState back to summary

setGLEventListenerInitState	back to summary
public void setGLEventListenerInitState(GLEventListener listener, boolean initialized) Sets the given `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(..)`. Parameters listener:GLEventListener the GLEventListener object to perform a state change. initialized:boolean if `true`, mark the listener initialized, otherwise uninitialized.

public void setGLEventListenerInitState(GLEventListener listener, boolean initialized)

Sets the given 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(..).

Parameters

listener:GLEventListener: the GLEventListener object to perform a state change.
initialized:boolean: if true, mark the listener initialized, otherwise uninitialized.

public Interface GLAutoDrawable

GLAutoDrawable Initialization

GLAutoDrawable Reconfiguration

GLAutoDrawable Locking

Field Summary

Method Summary

Field Detail

Method Detail