JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
GLAutoDrawable.java
Go to the documentation of this file.
1/*
2 * Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved.
3 * Copyright (c) 2010 JogAmp Community. All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are
7 * met:
8 *
9 * - Redistribution of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * - Redistribution in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * Neither the name of Sun Microsystems, Inc. or the names of
17 * contributors may be used to endorse or promote products derived from
18 * this software without specific prior written permission.
19 *
20 * This software is provided "AS IS," without a warranty of any kind. ALL
21 * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
22 * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
23 * PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
24 * MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR
25 * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
26 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR
27 * ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR
28 * DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
29 * DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
30 * ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF
31 * SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
32 *
33 * You acknowledge that this software is not designed or intended for use
34 * in the design, construction, operation or maintenance of any nuclear
35 * facility.
36 *
37 * Sun gratefully acknowledges that this software was originally authored
38 * and developed by Kenneth Bradley Russell and Christopher John Kline.
39 */
40
41package com.jogamp.opengl;
42
43import java.util.List;
44
45import com.jogamp.nativewindow.NativeSurface;
46
47import com.jogamp.common.util.locks.RecursiveLock;
48
49import jogamp.opengl.Debug;
50
51/** A higher-level abstraction than {@link GLDrawable} which supplies
52 an event based mechanism ({@link GLEventListener}) for performing
53 OpenGL rendering. A GLAutoDrawable automatically creates a primary
54 rendering context which is associated with the GLAutoDrawable for
55 the lifetime of the object.
56 <p>
57 Since the {@link GLContext} {@link GLContext#makeCurrent makeCurrent}
58 implementation is synchronized, i.e. blocks if the context
59 is current on another thread, the internal
60 {@link GLContext} for the GLAutoDrawable can be used for the event
61 based rendering mechanism and by end users directly.
62 </p>
63 <h5><a name="initialization">GLAutoDrawable Initialization</a></h5>
64 <p>
65 The implementation shall initialize itself as soon as possible,
66 which is only possible <i>after</i> the attached {@link com.jogamp.nativewindow.NativeSurface NativeSurface} becomes visible and and is realized.<br>
67 The following initialization sequence should be implemented:
68 <ul>
69 <li> Create the {@link GLDrawable} with the requested {@link GLCapabilities}</li>
70 <li> Notify {@link GLDrawable} to validate the {@link GLCapabilities} by calling {@link GLDrawable#setRealized setRealized(true)}.</li>
71 <li> Create the new {@link GLContext}.</li>
72 <li> Initialize all OpenGL resources by calling {@link GLEventListener#init init(..)} for all
73 registered {@link GLEventListener}s. This can be done immediately, or with the followup {@link #display display(..)} call.</li>
74 <li> Send a reshape event by calling {@link GLEventListener#reshape reshape(..)} for all
75 registered {@link GLEventListener}s. This shall be done after the {@link GLEventListener#init init(..)} calls.</li>
76 </ul>
77 Note: The last to {@link GLEventListener} actions shall be also performed, when {@link #addGLEventListener(GLEventListener) adding}
78 a new one to an already initialized {@link GLAutoDrawable}.
79 </p>
80 <h5><a name="reconfiguration">GLAutoDrawable Reconfiguration</a></h5>
81 <p>
82 Another implementation detail is the {@link GLDrawable} reconfiguration. One use case is where a window is being
83 dragged to another screen with a different pixel configuration, ie {@link GLCapabilities}. The implementation
84 shall be able to detect such cases in conjunction with the associated {@link com.jogamp.nativewindow.NativeSurface NativeSurface}.<br/>
85 For example, AWT's {@link java.awt.Canvas} 's {@link java.awt.Canvas#getGraphicsConfiguration getGraphicsConfiguration()}
86 is capable to determine a display device change. This is demonstrated within {@link com.jogamp.opengl.awt.GLCanvas}'s
87 and NEWT's <code>AWTCanvas</code> {@link com.jogamp.opengl.awt.GLCanvas#getGraphicsConfiguration getGraphicsConfiguration()}
88 specialization. Another demonstration is NEWT's {@link com.jogamp.nativewindow.NativeWindow NativeWindow}
89 implementation on the Windows platform, which utilizes the native platform's <i>MonitorFromWindow(HWND)</i> function.<br/>
90 All OpenGL resources shall be regenerated, while the drawable's {@link GLCapabilities} has
91 to be chosen again. The following protocol shall be satisfied.
92 <ul>
93 <li> Controlled disposal:</li>
94 <ul>
95 <li> Dispose all OpenGL resources by calling {@link GLEventListener#dispose dispose(..)} for all
96 registered {@link GLEventListener}s.</li>
97 <li> Destroy the {@link GLContext}.</li>
98 <li> Notify {@link GLDrawable} of the invalid state by calling {@link GLDrawable#setRealized setRealized(false)}.</li>
99 </ul>
100 <li> Controlled regeneration:</li>
101 <ul>
102 <li> Create the new {@link GLDrawable} with the requested {@link GLCapabilities}
103 <li> Notify {@link GLDrawable} to revalidate the {@link GLCapabilities} by calling {@link GLDrawable#setRealized setRealized(true)}.</li>
104 <li> Create the new {@link GLContext}.</li>
105 <li> Initialize all OpenGL resources by calling {@link GLEventListener#init init(..)} for all
106 registered {@link GLEventListener}s. This can be done immediatly, or with the followup {@link #display display(..)} call.</li>
107 <li> Send a reshape event by calling {@link GLEventListener#reshape reshape(..)} for all
108 registered {@link GLEventListener}s. This shall be done after the {@link GLEventListener#init init(..)} calls.</li>
109 </ul>
110 </ul>
111 Note: Current graphics driver keep the surface configuration for a given window, even if the window is moved to
112 a monitor with a different pixel configuration, ie 32bpp to 16bpp. However, it is best to not assume such behavior
113 and make your application comply with the above protocol.
114 <p>
115 Avoiding breakage with older applications and because of the situation
116 mentioned above, the <code>boolean</code> system property <code>jogl.screenchange.action</code> will control the
117 screen change action as follows:<br/>
118 <PRE>
119 -Djogl.screenchange.action=false Disable the {@link GLDrawable} reconfiguration (the default)
120 -Djogl.screenchange.action=true Enable the {@link GLDrawable} reconfiguration
121 </PRE>
122 </p>
123 <h5><a name="locking">GLAutoDrawable Locking</a></h5>
124 GLAutoDrawable implementations perform locking in the following order:
125 <ol>
126 <li> {@link #getUpstreamLock()}.{@link RecursiveLock#lock() lock()}</li>
127 <li> {@link #getNativeSurface()}.{@link NativeSurface#lockSurface() lockSurface()} </li>
128 </ol>
129 and releases the locks accordingly:
130 <ol>
131 <li> {@link #getNativeSurface()}.{@link NativeSurface#unlockSurface() unlockSurface()} </li>
132 <li> {@link #getUpstreamLock()}.{@link RecursiveLock#unlock() unlock()}</li>
133 </ol>
134 Above <i>locking order</i> is mandatory to guarantee
135 atomicity of operation and to avoid race-conditions.
136 A custom implementation or user applications requiring exclusive access
137 shall follow the <i>locking order</i>.
138 See:
139 <ul>
140 <li>{@link #getUpstreamLock()}</li>
141 <li>{@link #invoke(boolean, GLRunnable)}</li>
142 <li>{@link #invoke(boolean, List)}</li>
143 </ul>
144 </p>
145 */
146public interface GLAutoDrawable extends GLDrawable {
147 /** Flag reflecting whether the {@link GLDrawable} reconfiguration will be issued in
148 * case a screen device change occurred, e.g. in a multihead environment,
149 * where you drag the window to another monitor. */
150 public static final boolean SCREEN_CHANGE_ACTION_ENABLED = Debug.getBooleanProperty("jogl.screenchange.action", true);
151
152 /**
153 * If the implementation uses delegation, return the delegated {@link GLDrawable} instance,
154 * otherwise return <code>this</code> instance.
155 */
157
158 /**
159 * Returns the context associated with this drawable. The returned
160 * context will be synchronized.
161 * Don't rely on it's identity, the context may change.
162 */
164
165 /**
166 * Associate the new context, <code>newtCtx</code>, to this auto-drawable.
167 * <p>
168 * Remarks:
169 * <ul>
170 * <li>The currently associated context will be destroyed if <code>destroyPrevCtx</code> is <code>true</code>,
171 * otherwise it will be disassociated from this auto-drawable
172 * via {@link GLContext#setGLDrawable(GLDrawable, boolean) setGLDrawable(null, true);} including {@link GL#glFinish() glFinish()}.</li>
173 * <li>The new context will be associated with this auto-drawable
174 * via {@link GLContext#setGLDrawable(GLDrawable, boolean) newCtx.setGLDrawable(drawable, true);}.</li>
175 * <li>If the old context was current on this thread, it is being released after disassociating this auto-drawable.</li>
176 * <li>If the new context was current on this thread, it is being released before associating this auto-drawable
177 * and made current afterwards.</li>
178 * <li>Implementation may issue {@link GLContext#makeCurrent()} and {@link GLContext#release()} while drawable reassociation.</li>
179 * <li>The user shall take extra care of thread synchronization,
180 * i.e. lock the involved {@link GLAutoDrawable auto-drawable's}
181 * {@link GLAutoDrawable#getUpstreamLock() upstream-locks} and {@link GLAutoDrawable#getNativeSurface() surfaces}
182 * to avoid a race condition. See <a href="#locking">GLAutoDrawable Locking</a>.</li>
183 * </ul>
184 * </p>
185 *
186 * @param newCtx the new context, maybe <code>null</code> for dis-association.
187 * @param destroyPrevCtx if <code>true</code>, destroy the previous context if exists
188 * @return the previous GLContext, maybe <code>null</code>
189 *
190 * @see GLContext#setGLDrawable(GLDrawable, boolean)
191 * @see GLContext#setGLReadDrawable(GLDrawable)
192 * @see jogamp.opengl.GLDrawableHelper#switchContext(GLDrawable, GLContext, boolean, GLContext, int)
193 */
194 public GLContext setContext(GLContext newCtx, boolean destroyPrevCtx);
195
196 /**
197 * Adds the given {@link GLEventListener listener} to the end of this drawable queue.
198 * The {@link GLEventListener listeners} are notified of events in the order of the queue.
199 * <p>
200 * The newly added listener's {@link GLEventListener#init(GLAutoDrawable) init(..)}
201 * method will be called once before any other of it's callback methods.
202 * See {@link #getGLEventListenerInitState(GLEventListener)} for details.
203 * </p>
204 * @param listener The GLEventListener object to be inserted
205 */
206 public void addGLEventListener(GLEventListener listener);
207
208 /**
209 * Adds the given {@link GLEventListener listener} at the given index of this drawable queue.
210 * The {@link GLEventListener listeners} are notified of events in the order of the queue.
211 * <p>
212 * The newly added listener's {@link GLEventListener#init(GLAutoDrawable) init(..)}
213 * method will be called once before any other of it's callback methods.
214 * See {@link #getGLEventListenerInitState(GLEventListener)} for details.
215 * </p>
216 * @param index Position where the listener will be inserted.
217 * Should be within (0 <= index && index <= size()).
218 * An index value of -1 is interpreted as the end of the list, size().
219 * @param listener The GLEventListener object to be inserted
220 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
221 */
222 public void addGLEventListener(int index, GLEventListener listener) throws IndexOutOfBoundsException;
223
224 /**
225 * Returns the number of {@link GLEventListener} of this drawable queue.
226 * @return The number of GLEventListener objects of this drawable queue.
227 */
229
230 /**
231 * Returns true if all added {@link GLEventListener} are initialized, otherwise false.
232 * @since 2.2
233 */
235
236 /**
237 * Returns the {@link GLEventListener} at the given index of this drawable queue.
238 * @param index Position of the listener to be returned.
239 * Should be within (0 <= index && index < size()).
240 * An index value of -1 is interpreted as last listener, size()-1.
241 * @return The GLEventListener object at the given index.
242 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index < size()), or -1
243 */
244 public GLEventListener getGLEventListener(int index) throws IndexOutOfBoundsException;
245
246 /**
247 * Retrieves whether the given {@link GLEventListener listener} is initialized or not.
248 * <p>
249 * After {@link #addGLEventListener(GLEventListener) adding} a {@link GLEventListener} it is
250 * marked <i>uninitialized</i> and added to a list of to be initialized {@link GLEventListener}.
251 * If such <i>uninitialized</i> {@link GLEventListener}'s handler methods (reshape, display)
252 * are about to be invoked, it's {@link GLEventListener#init(GLAutoDrawable) init(..)} method is invoked first.
253 * Afterwards the {@link GLEventListener} is marked <i>initialized</i>
254 * and removed from the list of to be initialized {@link GLEventListener}.
255 * </p>
256 * <p>
257 * This methods returns the {@link GLEventListener} initialized state,
258 * i.e. returns <code>false</code> if it is included in the list of to be initialized {@link GLEventListener},
259 * otherwise <code>true</code>.
260 * </p>
261 * @param listener the GLEventListener object to query it's initialized state.
262 */
264
265 /**
266 * Sets the given {@link GLEventListener listener's} initialized state.
267 * <p>
268 * This methods allows manually setting the {@link GLEventListener} initialized state,
269 * i.e. adding it to, or removing it from the list of to be initialized {@link GLEventListener}.
270 * See {@link #getGLEventListenerInitState(GLEventListener)} for details.
271 * </p>
272 * <p>
273 * <b>Warning:</b> This method does not validate whether the given {@link GLEventListener listener's}
274 * is member of this drawable queue, i.e. {@link #addGLEventListener(GLEventListener) added}.
275 * </p>
276 * <p>
277 * This method is only exposed to allow users full control over the {@link GLEventListener}'s state
278 * and is usually not recommended to change.
279 * </p>
280 * <p>
281 * One use case is moving a {@link GLContext} and their initialized {@link GLEventListener}
282 * from one {@link GLAutoDrawable} to another,
283 * where a subsequent {@link GLEventListener#init(GLAutoDrawable) init(..)} call after adding it
284 * to the new owner is neither required nor desired.
285 * See {@link com.jogamp.opengl.util.GLDrawableUtil#swapGLContextAndAllGLEventListener(GLAutoDrawable, GLAutoDrawable) swapGLContextAndAllGLEventListener(..)}.
286 * </p>
287 * @param listener the GLEventListener object to perform a state change.
288 * @param initialized if <code>true</code>, mark the listener initialized, otherwise uninitialized.
289 */
290 public void setGLEventListenerInitState(GLEventListener listener, boolean initialized);
291
292 /**
293 * Disposes the given {@link GLEventListener listener} via {@link GLEventListener#dispose(GLAutoDrawable) dispose(..)}
294 * if it has been initialized and added to this queue.
295 * <p>
296 * If <code>remove</code> is <code>true</code>, the {@link GLEventListener} is removed from this drawable queue before disposal,
297 * otherwise marked uninitialized.
298 * </p>
299 * <p>
300 * If an {@link GLAnimatorControl} is being attached and the current thread is different
301 * than {@link GLAnimatorControl#getThread() the animator's thread}, it is paused during the operation.
302 * </p>
303 * <p>
304 * Note that this is an expensive operation, since {@link GLEventListener#dispose(GLAutoDrawable) dispose(..)}
305 * is decorated by {@link GLContext#makeCurrent()} and {@link GLContext#release()}.
306 * </p>
307 * <p>
308 * Use {@link #removeGLEventListener(GLEventListener) removeGLEventListener(listener)} instead
309 * if you just want to remove the {@link GLEventListener listener} and <i>don't care</i> about the disposal of the it's (OpenGL) resources.
310 * </p>
311 * <p>
312 * Also note that this is done from within a particular drawable's
313 * {@link GLEventListener} handler (reshape, display, etc.), that it is not
314 * guaranteed that all other listeners will be evaluated properly
315 * during this update cycle.
316 * </p>
317 * @param listener The GLEventListener object to be disposed and removed if <code>remove</code> is <code>true</code>
318 * @param remove pass <code>true</code> to have the <code>listener</code> removed from this drawable queue, otherwise pass <code>false</code>
319 * @return the disposed and/or removed GLEventListener, or null if no action was performed, i.e. listener was not added
320 */
322
323 /**
324 * Removes the given {@link GLEventListener listener} from this drawable queue.
325 * <p>
326 * This is an inexpensive operation, since the removed listener's
327 * {@link GLEventListener#dispose(GLAutoDrawable) dispose(..)} method will <i>not</i> be called.
328 * </p>
329 * <p>
330 * Use {@link #disposeGLEventListener(GLEventListener, boolean) disposeGLEventListener(listener, true)}
331 * instead to ensure disposal of the {@link GLEventListener listener}'s (OpenGL) resources.
332 * </p>
333 * <p>
334 * Note that if this is done from within a particular drawable's
335 * {@link GLEventListener} handler (reshape, display, etc.), that it is not
336 * guaranteed that all other listeners will be evaluated properly
337 * during this update cycle.
338 * </p>
339 * @param listener The GLEventListener object to be removed
340 * @return the removed GLEventListener, or null if listener was not added
341 */
343
344 /**
345 * Registers the usage of an animator, an {@link com.jogamp.opengl.GLAnimatorControl} implementation.
346 * The animator will be queried whether it's animating, ie periodically issuing {@link #display()} calls or not.
347 * <p>
348 * This method shall be called by an animator implementation only,<br>
349 * e.g. {@link com.jogamp.opengl.util.Animator#add(com.jogamp.opengl.GLAutoDrawable)}, passing it's control implementation,<br>
350 * and {@link com.jogamp.opengl.util.Animator#remove(com.jogamp.opengl.GLAutoDrawable)}, passing <code>null</code>.
351 * </p>
352 * <p>
353 * Impacts {@link #display()} and {@link #invoke(boolean, GLRunnable)} semantics.</p><br>
354 *
355 * @param animatorControl <code>null</code> reference indicates no animator is using
356 * this <code>GLAutoDrawable</code>,<br>
357 * a valid reference indicates an animator is using this <code>GLAutoDrawable</code>.
358 *
359 * @throws GLException if an animator is already registered.
360 * @see #display()
361 * @see #invoke(boolean, GLRunnable)
362 * @see com.jogamp.opengl.GLAnimatorControl
363 */
364 public abstract void setAnimator(GLAnimatorControl animatorControl) throws GLException;
365
366 /**
367 * @return the registered {@link com.jogamp.opengl.GLAnimatorControl} implementation, using this <code>GLAutoDrawable</code>.
368 *
369 * @see #setAnimator(com.jogamp.opengl.GLAnimatorControl)
370 * @see com.jogamp.opengl.GLAnimatorControl
371 */
373
374 /**
375 * Dedicates this instance's {@link GLContext} to the given thread.<br/>
376 * The thread will exclusively claim the {@link GLContext} via {@link #display()} and not release it
377 * until {@link #destroy()} or <code>setExclusiveContextThread(null)</code> has been called.
378 * <p>
379 * Default non-exclusive behavior is <i>requested</i> via <code>setExclusiveContextThread(null)</code>,
380 * which will cause the next call of {@link #display()} on the exclusive thread to
381 * release the {@link GLContext}. Only after it's async release, {@link #getExclusiveContextThread()}
382 * will return <code>null</code>.
383 * </p>
384 * <p>
385 * To release a previous made exclusive thread, a user issues <code>setExclusiveContextThread(null)</code>
386 * and may poll {@link #getExclusiveContextThread()} until it returns <code>null</code>,
387 * <i>while</i> the exclusive thread is still running.
388 * </p>
389 * <p>
390 * Note: Setting a new exclusive thread without properly releasing a previous one
391 * will throw an GLException.
392 * </p>
393 * <p>
394 * Note: Utilizing this feature w/ AWT could lead to an AWT-EDT deadlock, depending on the AWT implementation.
395 * Hence it is advised not to use it with native AWT GLAutoDrawable like GLCanvas.
396 * </p>
397 * <p>
398 * One scenario could be to dedicate the context to the {@link GLAnimatorControl#getThread() animator thread}
399 * and spare redundant context switches, see {@link com.jogamp.opengl.util.AnimatorBase#setExclusiveContext(boolean)}.
400 * </p>
401 * @param t the exclusive thread to claim the context, or <code>null</code> for default operation.
402 * @return previous exclusive context thread
403 * @throws GLException If an exclusive thread is still active but a new one is attempted to be set
404 * @see com.jogamp.opengl.util.AnimatorBase#setExclusiveContext(boolean)
405 */
406 public Thread setExclusiveContextThread(Thread t) throws GLException;
407
408 /**
409 * @see #setExclusiveContextThread(Thread)
410 */
412
413 /**
414 * Enqueues a one-shot {@link GLRunnable},
415 * which will be executed within the next {@link #display()} call
416 * after all registered {@link GLEventListener}s
417 * {@link GLEventListener#display(GLAutoDrawable) display(GLAutoDrawable)}
418 * methods have been called.
419 * <p>
420 * The given {@link GLRunnable#run(GLAutoDrawable)} shall return true to indicate
421 * that the GL [back] framebuffer remains intact by this runnable. <br/>
422 * If returning false {@link GLAutoDrawable} will call
423 * {@link GLEventListener#display(GLAutoDrawable) display(GLAutoDrawable)}
424 * of all registered {@link GLEventListener}s once more to reinstate the framebuffer.
425 * </p>
426 * <p>
427 * If no {@link GLAnimatorControl} is animating (default),<br>
428 * or if the current thread is the animator thread,<br>
429 * a {@link #display()} call is issued after enqueue the <code>GLRunnable</code>,
430 * hence the {@link GLRunnable} will be executed right away.<br/>
431 * </p>
432 * <p>
433 * If an {@link GLAnimatorControl animator} is running,<br>
434 * no explicit {@link #display()} call is issued, allowing the {@link GLAnimatorControl animator} to perform at due time.<br>
435 * </p>
436 * <p>
437 * If <code>wait</code> is <code>true</code> the call blocks until the <code>glRunnable</code>
438 * has been executed by the {@link GLAnimatorControl animator}, otherwise the method returns immediately.
439 * </p>
440 * <p>
441 * If <code>wait</code> is <code>true</code> <b>and</b>
442 * {@link #isRealized()} returns <code>false</code> <i>or</i> {@link #getContext()} returns <code>null</code>,
443 * the call is ignored and returns <code>false</code>.<br>
444 * This helps avoiding deadlocking the caller.
445 * </p>
446 * <p>
447 * The internal queue of {@link GLRunnable}'s is being flushed with {@link #destroy()}
448 * where all blocked callers are being notified.
449 * </p>
450 * <p>
451 * To avoid a deadlock situation which causes an {@link IllegalStateException} one should
452 * avoid issuing {@link #invoke(boolean, GLRunnable) invoke} while this <a href="#locking">GLAutoDrawable is being locked</a>.<br>
453 * Detected deadlock situations throwing an {@link IllegalStateException} are:
454 * <ul>
455 * <li>{@link #getAnimator() Animator} is running on another thread and waiting and is locked on current thread, but is not {@link #isThreadGLCapable() GL-Thread}</li>
456 * <li>No {@link #getAnimator() Animator} is running on another thread and is locked on current thread, but is not {@link #isThreadGLCapable() GL-Thread}</li>
457 * </ul>
458 * </p>
459 *
460 * @param wait if <code>true</code> block until execution of <code>glRunnable</code> is finished, otherwise return immediately w/o waiting
461 * @param glRunnable the {@link GLRunnable} to execute within {@link #display()}
462 * @return <code>true</code> if the {@link GLRunnable} has been processed or queued, otherwise <code>false</code>.
463 * @throws IllegalStateException in case of a detected deadlock situation ahead, see above.
464 *
465 * @see #setAnimator(GLAnimatorControl)
466 * @see #display()
467 * @see GLRunnable
468 * @see #invoke(boolean, List)
469 * @see #flushGLRunnables()
470 */
471 public boolean invoke(boolean wait, GLRunnable glRunnable) throws IllegalStateException ;
472
473 /**
474 * Extends {@link #invoke(boolean, GLRunnable)} functionality
475 * allowing to inject a list of {@link GLRunnable}s.
476 * @param wait if <code>true</code> block until execution of the last <code>glRunnable</code> is finished, otherwise return immediately w/o waiting
477 * @param glRunnables the {@link GLRunnable}s to execute within {@link #display()}
478 * @return <code>true</code> if the {@link GLRunnable}s has been processed or queued, otherwise <code>false</code>.
479 * @throws IllegalStateException in case of a detected deadlock situation ahead, see {@link #invoke(boolean, GLRunnable)}.
480 * @see #invoke(boolean, GLRunnable)
481 * @see #flushGLRunnables()
482 */
483 public boolean invoke(boolean wait, List<GLRunnable> glRunnables) throws IllegalStateException;
484
485 /**
486 * Flushes all {@link #invoke(boolean, GLRunnable) enqueued} {@link GLRunnable} of this {@link GLAutoDrawable}
487 * including notifying waiting executor.
488 * <p>
489 * The executor which might have been blocked until notified
490 * will be unblocked and all tasks removed from the queue.
491 * </p>
492 * @see #invoke(boolean, GLRunnable)
493 * @since 2.2
494 */
495 public void flushGLRunnables();
496
497 /** Destroys all resources associated with this GLAutoDrawable,
498 inclusive the GLContext.
499 If a window is attached to it's implementation, it shall be closed.
500 Causes disposing of all OpenGL resources
501 by calling {@link GLEventListener#dispose dispose(..)} for all
502 registered {@link GLEventListener}s. Called automatically by the
503 window system toolkit upon receiving a destroy notification. This
504 routine may be called manually. */
505 public void destroy();
506
507 /**
508 * <p>
509 * Causes OpenGL rendering to be performed for this GLAutoDrawable
510 * in the following order:
511 * <ul>
512 * <li> Calling {@link GLEventListener#display display(..)} for all
513 * registered {@link GLEventListener}s. </li>
514 * <li> Executes all one-shot {@link com.jogamp.opengl.GLRunnable GLRunnable},
515 * enqueued via {@link #invoke(boolean, GLRunnable)}.</li>
516 * </ul></p>
517 * <p>
518 * May be called periodically by a running {@link com.jogamp.opengl.GLAnimatorControl} implementation,<br>
519 * which must register itself with {@link #setAnimator(com.jogamp.opengl.GLAnimatorControl)}.</p>
520 * <p>
521 * Called automatically by the window system toolkit upon receiving a repaint() request, <br>
522 * except an {@link com.jogamp.opengl.GLAnimatorControl} implementation {@link com.jogamp.opengl.GLAnimatorControl#isAnimating()}.</p>
523 * <p>
524 * This routine may also be called manually for better control over the
525 * rendering process. It is legal to call another GLAutoDrawable's
526 * display method from within the {@link GLEventListener#display
527 * display(..)} callback.</p>
528 * <p>
529 * In case of a new generated OpenGL context,
530 * the implementation shall call {@link GLEventListener#init init(..)} for all
531 * registered {@link GLEventListener}s <i>before</i> making the
532 * actual {@link GLEventListener#display display(..)} calls,
533 * in case this has not been done yet.</p>
534 *
535 * @see #setAnimator(com.jogamp.opengl.GLAnimatorControl)
536 */
537 public void display();
538
539 /** Enables or disables automatic buffer swapping for this drawable.
540 By default this property is set to true; when true, after all
541 GLEventListeners have been called for a display() event, the
542 front and back buffers are swapped, displaying the results of
543 the render. When disabled, the user is responsible for calling
544 {@link #swapBuffers(..)} manually. */
545 public void setAutoSwapBufferMode(boolean enable);
546
547 /** Indicates whether automatic buffer swapping is enabled for this
548 drawable. See {@link #setAutoSwapBufferMode}. */
549 public boolean getAutoSwapBufferMode();
550
551 /**
552 * @param flags Additional context creation flags.
553 *
554 * @see GLContext#setContextCreationFlags(int)
555 * @see GLContext#enableGLDebugMessage(boolean)
556 */
557 public void setContextCreationFlags(int flags);
558
559 /**
560 * @return Additional context creation flags
561 */
563
564 /**
565 * {@inheritDoc}
566 * <p>
567 * This GLAutoDrawable implementation holds it's own GLContext reference,
568 * thus created a GLContext using this methods won't replace it implicitly.
569 * To replace or set this GLAutoDrawable's GLContext you need to call {@link #setContext(GLContext, boolean)}.
570 * </p>
571 * <p>
572 * The GLAutoDrawable implementation shall also set the
573 * context creation flags as customized w/ {@link #setContextCreationFlags(int)}.
574 * </p>
575 */
576 @Override
578
579 /** Returns the {@link GL} pipeline object this GLAutoDrawable uses.
580 If this method is called outside of the {@link
581 GLEventListener}'s callback methods (init, display, etc.) it may
582 return null. Users should not rely on the identity of the
583 returned GL object; for example, users should not maintain a
584 hash table with the GL object as the key. Additionally, the GL
585 object should not be cached in client code, but should be
586 re-fetched from the GLAutoDrawable at the beginning of each call
587 to init, display, etc. */
588 public GL getGL();
589
590 /** Sets the {@link GL} pipeline object this GLAutoDrawable uses.
591 This should only be called from within the GLEventListener's
592 callback methods, and usually only from within the init()
593 method, in order to install a composable pipeline. See the JOGL
594 demos for examples.
595 @return the set GL pipeline or null if not successful */
596 public GL setGL(GL gl);
597
598 /**
599 * Method <i>may</i> return the upstream UI toolkit object
600 * holding this {@link GLAutoDrawable} instance, if exist.
601 * <p>
602 * Currently known Java UI toolkits and it's known return types are:
603 *
604 * <table border="1">
605 * <tr><td>Toolkit</td> <td>GLAutoDrawable Implementation</td> <td>~</td> <td>Return Type of getUpstreamWidget()</td</tr>
606 * <tr><td>NEWT</td> <td>{@link com.jogamp.newt.opengl.GLWindow}</td> <td>has a</td> <td>{@link com.jogamp.newt.Window}</td</tr>
607 * <tr><td>SWT</td> <td>{@link com.jogamp.opengl.swt.GLCanvas}</td> <td>is a</td> <td>{@link org.eclipse.swt.widgets.Canvas}</td</tr>
608 * <tr><td>AWT</td> <td>{@link com.jogamp.opengl.awt.GLCanvas}</td> <td>is a</td> <td>{@link java.awt.Canvas}</td</tr>
609 * <tr><td>AWT</td> <td>{@link com.jogamp.opengl.awt.GLJPanel}</td> <td>is a</td> <td>{@link javax.swing.JPanel}</td</tr>
610 * </table>
611 * However, the result may be other object types than the listed above
612 * due to new supported toolkits.
613 * </p>
614 * <p>
615 * This method may also return <code>null</code> if no UI toolkit is being used,
616 * as common for offscreen rendering.
617 * </p>
618 */
619 public Object getUpstreamWidget();
620
621 /**
622 * Returns the recursive lock object of the {@link #getUpstreamWidget() upstream widget}
623 * to synchronize multithreaded access on top of {@link NativeSurface#lockSurface()}.
624 * <p>
625 * See <a href="#locking">GLAutoDrawable Locking</a>.
626 * </p>
627 * @since 2.2
628 */
629 public RecursiveLock getUpstreamLock();
630
631 /**
632 * Indicates whether the current thread is capable of
633 * performing OpenGL-related work.
634 * <p>
635 * Implementation utilizes this knowledge to determine
636 * whether {@link #display()} performs the OpenGL commands on the current thread directly
637 * or spawns them on the dedicated OpenGL thread.
638 * </p>
639 * @since 2.2
640 */
641 public boolean isThreadGLCapable();
642
643}
Abstraction for an OpenGL rendering context.
Definition: GLContext.java:74
A generic exception for OpenGL errors used throughout the binding as a substitute for RuntimeExceptio...
An animator control interface, which implementation may drive a com.jogamp.opengl....
A higher-level abstraction than GLDrawable which supplies an event based mechanism (GLEventListener) ...
GLEventListener getGLEventListener(int index)
Returns the GLEventListener at the given index of this drawable queue.
GLContext setContext(GLContext newCtx, boolean destroyPrevCtx)
Associate the new context, newtCtx, to this auto-drawable.
void setContextCreationFlags(int flags)
boolean invoke(boolean wait, GLRunnable glRunnable)
Enqueues a one-shot GLRunnable, which will be executed within the next display() call after all regis...
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.
GLAnimatorControl getAnimator()
GLEventListener disposeGLEventListener(GLEventListener listener, boolean remove)
Disposes the given listener via dispose(..) if it has been initialized and added to this queue.
static final boolean SCREEN_CHANGE_ACTION_ENABLED
Flag reflecting whether the GLDrawable reconfiguration will be issued in case a screen device change ...
void addGLEventListener(int index, GLEventListener listener)
Adds the given listener at the given index of this drawable queue.
GL getGL()
Returns the GL pipeline object this GLAutoDrawable uses.
GLContext createContext(GLContext shareWith)
Creates a new context for drawing to this drawable that will optionally share buffer objects,...
Thread setExclusiveContextThread(Thread t)
Dedicates this instance's GLContext to the given thread.
void setGLEventListenerInitState(GLEventListener listener, boolean initialized)
Sets the given listener's initialized state.
Object getUpstreamWidget()
Method may return the upstream UI toolkit object holding this GLAutoDrawable instance,...
RecursiveLock getUpstreamLock()
Returns the recursive lock object of the upstream widget to synchronize multithreaded access on top o...
boolean getAutoSwapBufferMode()
Indicates whether automatic buffer swapping is enabled for this drawable.
void addGLEventListener(GLEventListener listener)
Adds the given listener to the end of this drawable queue.
abstract void setAnimator(GLAnimatorControl animatorControl)
Registers the usage of an animator, an com.jogamp.opengl.GLAnimatorControl implementation.
int getGLEventListenerCount()
Returns the number of GLEventListener of this drawable queue.
boolean areAllGLEventListenerInitialized()
Returns true if all added GLEventListener are initialized, otherwise false.
GLEventListener removeGLEventListener(GLEventListener listener)
Removes the given listener from this drawable queue.
void destroy()
Destroys all resources associated with this GLAutoDrawable, inclusive the GLContext.
GLContext getContext()
Returns the context associated with this drawable.
void flushGLRunnables()
Flushes all enqueued GLRunnable of this GLAutoDrawable including notifying waiting executor.
GL setGL(GL gl)
Sets the GL pipeline object this GLAutoDrawable uses.
boolean getGLEventListenerInitState(GLEventListener listener)
Retrieves whether the given listener is initialized or not.
void setAutoSwapBufferMode(boolean enable)
Enables or disables automatic buffer swapping for this drawable.
GLDrawable getDelegatedDrawable()
If the implementation uses delegation, return the delegated GLDrawable instance, otherwise return thi...
An abstraction for an OpenGL rendering target.
Definition: GLDrawable.java:51
Declares events which client code can use to manage OpenGL rendering into a GLAutoDrawable.