javax.media.opengl.GLAutoDrawable Maven / Gradle / Ivy
Show all versions of jogl-all Show documentation
/*
* Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved.
* Copyright (c) 2010 JogAmp Community. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are
* met:
*
* - Redistribution of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* - Redistribution in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* Neither the name of Sun Microsystems, Inc. or the names of
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* This software is provided "AS IS," without a warranty of any kind. ALL
* EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
* INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
* MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR
* ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
* DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR
* ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR
* DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
* DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
* ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF
* SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
*
* You acknowledge that this software is not designed or intended for use
* in the design, construction, operation or maintenance of any nuclear
* facility.
*
* Sun gratefully acknowledges that this software was originally authored
* and developed by Kenneth Bradley Russell and Christopher John Kline.
*/
package javax.media.opengl;
import java.util.List;
import javax.media.nativewindow.NativeSurface;
import com.jogamp.common.util.locks.RecursiveLock;
import jogamp.opengl.Debug;
/** A higher-level abstraction than {@link GLDrawable} which supplies
an event based mechanism ({@link 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 {@link GLContext} {@link GLContext#makeCurrent makeCurrent}
implementation is synchronized, i.e. blocks if the context
is current on another thread, the internal
{@link 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 {@link javax.media.nativewindow.NativeSurface NativeSurface} becomes visible and and is realized.
The following initialization sequence should be implemented:
- Create the {@link GLDrawable} with the requested {@link GLCapabilities}
- Notify {@link GLDrawable} to validate the {@link GLCapabilities} by calling {@link GLDrawable#setRealized setRealized(true)}.
- Create the new {@link GLContext}.
- Initialize all OpenGL resources by calling {@link GLEventListener#init init(..)} for all
registered {@link GLEventListener}s. This can be done immediately, or with the followup {@link #display display(..)} call.
- Send a reshape event by calling {@link GLEventListener#reshape reshape(..)} for all
registered {@link GLEventListener}s. This shall be done after the {@link GLEventListener#init init(..)} calls.
Note: The last to {@link GLEventListener} actions shall be also performed, when {@link #addGLEventListener(GLEventListener) adding}
a new one to an already initialized {@link GLAutoDrawable}.
GLAutoDrawable Reconfiguration
Another implementation detail is the {@link GLDrawable} reconfiguration. One use case is where a window is being
dragged to another screen with a different pixel configuration, ie {@link GLCapabilities}. The implementation
shall be able to detect such cases in conjunction with the associated {@link javax.media.nativewindow.NativeSurface NativeSurface}.
For example, AWT's {@link java.awt.Canvas} 's {@link java.awt.Canvas#getGraphicsConfiguration getGraphicsConfiguration()}
is capable to determine a display device change. This is demonstrated within {@link javax.media.opengl.awt.GLCanvas}'s
and NEWT's AWTCanvas {@link javax.media.opengl.awt.GLCanvas#getGraphicsConfiguration getGraphicsConfiguration()}
specialization. Another demonstration is NEWT's {@link javax.media.nativewindow.NativeWindow 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 {@link GLCapabilities} has
to be chosen again. The following protocol shall be satisfied.
- Controlled disposal:
- Dispose all OpenGL resources by calling {@link GLEventListener#dispose dispose(..)} for all
registered {@link GLEventListener}s.
- Destroy the {@link GLContext}.
- Notify {@link GLDrawable} of the invalid state by calling {@link GLDrawable#setRealized setRealized(false)}.
- Controlled regeneration:
- Create the new {@link GLDrawable} with the requested {@link GLCapabilities}
- Notify {@link GLDrawable} to revalidate the {@link GLCapabilities} by calling {@link GLDrawable#setRealized setRealized(true)}.
- Create the new {@link GLContext}.
- Initialize all OpenGL resources by calling {@link GLEventListener#init init(..)} for all
registered {@link GLEventListener}s. This can be done immediatly, or with the followup {@link #display display(..)} call.
- Send a reshape event by calling {@link GLEventListener#reshape reshape(..)} for all
registered {@link GLEventListener}s. This shall be done after the {@link GLEventListener#init 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 {@link GLDrawable} reconfiguration (the default)
-Djogl.screenchange.action=true Enable the {@link GLDrawable} reconfiguration
GLAutoDrawable Locking
GLAutoDrawable implementations perform locking in the following order:
- {@link #getUpstreamLock()}.{@link RecursiveLock#lock() lock()}
- {@link #getNativeSurface()}.{@link NativeSurface#lockSurface() lockSurface()}
and releases the locks accordingly:
- {@link #getNativeSurface()}.{@link NativeSurface#unlockSurface() unlockSurface()}
- {@link #getUpstreamLock()}.{@link RecursiveLock#unlock() unlock()}
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:
- {@link #getUpstreamLock()}
- {@link #invoke(boolean, GLRunnable)}
- {@link #invoke(boolean, List)}
*/
public interface GLAutoDrawable extends GLDrawable {
/** Flag reflecting whether the {@link 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. */
public static final boolean SCREEN_CHANGE_ACTION_ENABLED = Debug.getBooleanProperty("jogl.screenchange.action", true);
/**
* If the implementation uses delegation, return the delegated {@link GLDrawable} instance,
* otherwise return this instance.
*/
public GLDrawable getDelegatedDrawable();
/**
* Returns the context associated with this drawable. The returned
* context will be synchronized.
* Don't rely on it's identity, the context may change.
*/
public GLContext getContext();
/**
* 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 {@link GLContext#setGLDrawable(GLDrawable, boolean) setGLDrawable(null, true);} including {@link GL#glFinish() glFinish()}.
* - The new context will be associated with this auto-drawable
* via {@link GLContext#setGLDrawable(GLDrawable, boolean) 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 {@link #makeCurrent()} and {@link #release()} while drawable reassociation.
* - The user shall take extra care of thread synchronization,
* i.e. lock the involved {@link GLAutoDrawable auto-drawable's}
* {@link GLAutoDrawable#getUpstreamLock() upstream-locks} and {@link GLAutoDrawable#getNativeSurface() surfaces}
* to avoid a race condition. See GLAutoDrawable Locking.
*
*
*
* @param newCtx the new context, maybe null for dis-association.
* @param destroyPrevCtx if true, destroy the previous context if exists
* @return the previous GLContext, maybe null
*
* @see GLContext#setGLDrawable(GLDrawable, boolean)
* @see GLContext#setGLReadDrawable(GLDrawable)
* @see jogamp.opengl.GLDrawableHelper#switchContext(GLDrawable, GLContext, boolean, GLContext, int)
*/
public GLContext setContext(GLContext newCtx, boolean destroyPrevCtx);
/**
* Adds the given {@link GLEventListener listener} to the end of this drawable queue.
* The {@link GLEventListener listeners} are notified of events in the order of the queue.
*
* The newly added listener's {@link GLEventListener#init(GLAutoDrawable) init(..)}
* method will be called once before any other of it's callback methods.
* See {@link #getGLEventListenerInitState(GLEventListener)} for details.
*
* @param listener The GLEventListener object to be inserted
*/
public void addGLEventListener(GLEventListener listener);
/**
* Adds the given {@link GLEventListener listener} at the given index of this drawable queue.
* The {@link GLEventListener listeners} are notified of events in the order of the queue.
*
* The newly added listener's {@link GLEventListener#init(GLAutoDrawable) init(..)}
* method will be called once before any other of it's callback methods.
* See {@link #getGLEventListenerInitState(GLEventListener)} for details.
*
* @param 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().
* @param listener The GLEventListener object to be inserted
* @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
*/
public void addGLEventListener(int index, GLEventListener listener) throws IndexOutOfBoundsException;
/**
* Returns the number of {@link GLEventListener} of this drawable queue.
* @return The number of GLEventListener objects of this drawable queue.
*/
public int getGLEventListenerCount();
/**
* Returns true if all added {@link GLEventListener} are initialized, otherwise false.
* @since 2.2
*/
boolean areAllGLEventListenerInitialized();
/**
* Returns the {@link GLEventListener} at the given index of this drawable queue.
* @param 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.
* @return The GLEventListener object at the given index.
* @throws IndexOutOfBoundsException If the index is not within (0 <= index && index < size()), or -1
*/
public GLEventListener getGLEventListener(int index) throws IndexOutOfBoundsException;
/**
* Retrieves whether the given {@link GLEventListener listener} is initialized or not.
*
* After {@link #addGLEventListener(GLEventListener) adding} a {@link GLEventListener} it is
* marked uninitialized and added to a list of to be initialized {@link GLEventListener}.
* If such uninitialized {@link GLEventListener}'s handler methods (reshape, display)
* are about to be invoked, it's {@link GLEventListener#init(GLAutoDrawable) init(..)} method is invoked first.
* Afterwards the {@link GLEventListener} is marked initialized
* and removed from the list of to be initialized {@link GLEventListener}.
*
*
* This methods returns the {@link GLEventListener} initialized state,
* i.e. returns false if it is included in the list of to be initialized {@link GLEventListener},
* otherwise true.
*
* @param listener the GLEventListener object to query it's initialized state.
*/
public boolean getGLEventListenerInitState(GLEventListener listener);
/**
* Sets the given {@link GLEventListener listener's} initialized state.
*
* This methods allows manually setting the {@link GLEventListener} initialized state,
* i.e. adding it to, or removing it from the list of to be initialized {@link GLEventListener}.
* See {@link #getGLEventListenerInitState(GLEventListener)} for details.
*
*
* Warning: This method does not validate whether the given {@link GLEventListener listener's}
* is member of this drawable queue, i.e. {@link #addGLEventListener(GLEventListener) added}.
*
*
* This method is only exposed to allow users full control over the {@link GLEventListener}'s state
* and is usually not recommended to change.
*
*
* One use case is moving a {@link GLContext} and their initialized {@link GLEventListener}
* from one {@link GLAutoDrawable} to another,
* where a subsequent {@link GLEventListener#init(GLAutoDrawable) init(..)} call after adding it
* to the new owner is neither required nor desired.
* See {@link com.jogamp.opengl.util.GLDrawableUtil#swapGLContextAndAllGLEventListener(GLAutoDrawable, GLAutoDrawable) swapGLContextAndAllGLEventListener(..)}.
*
* @param listener the GLEventListener object to perform a state change.
* @param initialized if true, mark the listener initialized, otherwise uninitialized.
*/
public void setGLEventListenerInitState(GLEventListener listener, boolean initialized);
/**
* Disposes the given {@link GLEventListener listener} via {@link GLEventListener#dispose(GLAutoDrawable) dispose(..)}
* if it has been initialized and added to this queue.
*
* If remove is true, the {@link GLEventListener} is removed from this drawable queue before disposal,
* otherwise marked uninitialized.
*
*
* If an {@link GLAnimatorControl} is being attached and the current thread is different
* than {@link GLAnimatorControl#getThread() the animator's thread}, it is paused during the operation.
*
*
* Note that this is an expensive operation, since {@link GLEventListener#dispose(GLAutoDrawable) dispose(..)}
* is decorated by {@link GLContext#makeCurrent()} and {@link GLContext#release()}.
*
*
* Use {@link #removeGLEventListener(GLEventListener) removeGLEventListener(listener)} instead
* if you just want to remove the {@link GLEventListener 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
* {@link GLEventListener} handler (reshape, display, etc.), that it is not
* guaranteed that all other listeners will be evaluated properly
* during this update cycle.
*
* @param listener The GLEventListener object to be disposed and removed if remove is true
* @param remove pass true to have the listener removed from this drawable queue, otherwise pass false
* @return 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);
/**
* Removes the given {@link GLEventListener listener} from this drawable queue.
*
* This is an inexpensive operation, since the removed listener's
* {@link GLEventListener#dispose(GLAutoDrawable) dispose(..)} method will not be called.
*
*
* Use {@link #disposeGLEventListener(GLEventListener, boolean) disposeGLEventListener(listener, true)}
* instead to ensure disposal of the {@link GLEventListener listener}'s (OpenGL) resources.
*
*
* Note that if this is done from within a particular drawable's
* {@link GLEventListener} handler (reshape, display, etc.), that it is not
* guaranteed that all other listeners will be evaluated properly
* during this update cycle.
*
* @param listener The GLEventListener object to be removed
* @return the removed GLEventListener, or null if listener was not added
*/
public GLEventListener removeGLEventListener(GLEventListener listener);
/**
* Registers the usage of an animator, an {@link javax.media.opengl.GLAnimatorControl} implementation.
* The animator will be queried whether it's animating, ie periodically issuing {@link #display()} calls or not.
*
* This method shall be called by an animator implementation only,
* e.g. {@link com.jogamp.opengl.util.Animator#add(javax.media.opengl.GLAutoDrawable)}, passing it's control implementation,
* and {@link com.jogamp.opengl.util.Animator#remove(javax.media.opengl.GLAutoDrawable)}, passing null.
*
*
* Impacts {@link #display()} and {@link #invoke(boolean, GLRunnable)} semantics.
*
* @param animatorControl null reference indicates no animator is using
* this GLAutoDrawable,
* a valid reference indicates an animator is using this GLAutoDrawable.
*
* @throws GLException if an animator is already registered.
* @see #display()
* @see #invoke(boolean, GLRunnable)
* @see javax.media.opengl.GLAnimatorControl
*/
public abstract void setAnimator(GLAnimatorControl animatorControl) throws GLException;
/**
* @return the registered {@link javax.media.opengl.GLAnimatorControl} implementation, using this GLAutoDrawable.
*
* @see #setAnimator(javax.media.opengl.GLAnimatorControl)
* @see javax.media.opengl.GLAnimatorControl
*/
public GLAnimatorControl getAnimator();
/**
* Dedicates this instance's {@link GLContext} to the given thread.
* The thread will exclusively claim the {@link GLContext} via {@link #display()} and not release it
* until {@link #destroy()} or setExclusiveContextThread(null) has been called.
*
* Default non-exclusive behavior is requested via setExclusiveContextThread(null),
* which will cause the next call of {@link #display()} on the exclusive thread to
* release the {@link GLContext}. Only after it's async release, {@link #getExclusiveContextThread()}
* will return null.
*
*
* To release a previous made exclusive thread, a user issues setExclusiveContextThread(null)
* and may poll {@link #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 {@link GLAnimatorControl#getThread() animator thread}
* and spare redundant context switches, see {@link com.jogamp.opengl.util.AnimatorBase#setExclusiveContext(boolean)}.
*
* @param t the exclusive thread to claim the context, or null for default operation.
* @return previous exclusive context thread
* @throws GLException If an exclusive thread is still active but a new one is attempted to be set
* @see com.jogamp.opengl.util.AnimatorBase#setExclusiveContext(boolean)
*/
public Thread setExclusiveContextThread(Thread t) throws GLException;
/**
* @see #setExclusiveContextThread(Thread)
*/
public Thread getExclusiveContextThread();
/**
* Enqueues a one-shot {@link GLRunnable},
* which will be executed within the next {@link #display()} call
* after all registered {@link GLEventListener}s
* {@link GLEventListener#display(GLAutoDrawable) display(GLAutoDrawable)}
* methods have been called.
*
* If no {@link GLAnimatorControl} is animating (default),
* or if the current thread is the animator thread,
* a {@link #display()} call is issued after enqueue the GLRunnable,
* hence the {@link GLRunnable} will be executed right away.
*
*
* If an {@link GLAnimatorControl animator} is running,
* no explicit {@link #display()} call is issued, allowing the {@link GLAnimatorControl animator} to perform at due time.
*
*
* If wait is true the call blocks until the glRunnable
* has been executed by the {@link GLAnimatorControl animator}, otherwise the method returns immediately.
*
*
* If wait is true and
* {@link #isRealized()} returns false or {@link #getContext()} returns null,
* the call is ignored and returns false.
* This helps avoiding deadlocking the caller.
*
*
* The internal queue of {@link GLRunnable}'s is being flushed with {@link #destroy()}
* where all blocked callers are being notified.
*
*
* To avoid a deadlock situation which causes an {@link IllegalStateException} one should
* avoid issuing {@link #invoke(boolean, GLRunnable) invoke} while this GLAutoDrawable is being locked.
* Detected deadlock situations throwing an {@link IllegalStateException} are:
*
* - {@link #getAnimator() Animator} is running on another thread and waiting and is locked on current thread, but is not {@link #isThreadGLCapable() GL-Thread}
* - No {@link #getAnimator() Animator} is running on another thread and is locked on current thread, but is not {@link #isThreadGLCapable() GL-Thread}
*
*
*
* @param wait if true block until execution of glRunnable is finished, otherwise return immediately w/o waiting
* @param glRunnable the {@link GLRunnable} to execute within {@link #display()}
* @return true if the {@link GLRunnable} has been processed or queued, otherwise false.
* @throws IllegalStateException in case of a detected deadlock situation ahead, see above.
*
* @see #setAnimator(GLAnimatorControl)
* @see #display()
* @see GLRunnable
* @see #invoke(boolean, List)
* @see #flushGLRunnables()
*/
public boolean invoke(boolean wait, GLRunnable glRunnable) throws IllegalStateException ;
/**
* Extends {@link #invoke(boolean, GLRunnable)} functionality
* allowing to inject a list of {@link GLRunnable}s.
* @param wait if true block until execution of the last glRunnable is finished, otherwise return immediately w/o waiting
* @param glRunnables the {@link GLRunnable}s to execute within {@link #display()}
* @return true if the {@link GLRunnable}s has been processed or queued, otherwise false.
* @throws IllegalStateException in case of a detected deadlock situation ahead, see {@link #invoke(boolean, GLRunnable)}.
* @see #invoke(boolean, GLRunnable)
* @see #flushGLRunnables()
*/
public boolean invoke(boolean wait, List glRunnables) throws IllegalStateException;
/**
* Flushes all {@link #invoke(boolean, GLRunnable) enqueued} {@link GLRunnable} of this {@link GLAutoDrawable}
* including notifying waiting executor.
*
* The executor which might have been blocked until notified
* will be unblocked and all tasks removed from the queue.
*
* @see #invoke(boolean, GLRunnable)
* @since 2.2
*/
public void flushGLRunnables();
/** 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 {@link GLEventListener#dispose dispose(..)} for all
registered {@link GLEventListener}s. Called automatically by the
window system toolkit upon receiving a destroy notification. This
routine may be called manually. */
public void destroy();
/**
*
* Causes OpenGL rendering to be performed for this GLAutoDrawable
* in the following order:
*
* - Calling {@link GLEventListener#display display(..)} for all
* registered {@link GLEventListener}s.
* - Executes all one-shot {@link javax.media.opengl.GLRunnable GLRunnable},
* enqueued via {@link #invoke(boolean, GLRunnable)}.
*
*
* May be called periodically by a running {@link javax.media.opengl.GLAnimatorControl} implementation,
* which must register itself with {@link #setAnimator(javax.media.opengl.GLAnimatorControl)}.
*
* Called automatically by the window system toolkit upon receiving a repaint() request,
* except an {@link javax.media.opengl.GLAnimatorControl} implementation {@link javax.media.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 {@link GLEventListener#display
* display(..)} callback.
*
* In case of a new generated OpenGL context,
* the implementation shall call {@link GLEventListener#init init(..)} for all
* registered {@link GLEventListener}s before making the
* actual {@link GLEventListener#display display(..)} calls,
* in case this has not been done yet.
*
* @see #setAnimator(javax.media.opengl.GLAnimatorControl)
*/
public void display();
/** 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. */
public void setAutoSwapBufferMode(boolean enable);
/** Indicates whether automatic buffer swapping is enabled for this
drawable. See {@link #setAutoSwapBufferMode}. */
public boolean getAutoSwapBufferMode();
/**
* @param flags Additional context creation flags.
*
* @see GLContext#setContextCreationFlags(int)
* @see GLContext#enableGLDebugMessage(boolean)
*/
public void setContextCreationFlags(int flags);
/**
* @return Additional context creation flags
*/
public int getContextCreationFlags();
/**
* {@inheritDoc}
*
* 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 {@link #setContext(GLContext, boolean)}.
*
*
* The GLAutoDrawable implementation shall also set the
* context creation flags as customized w/ {@link #setContextCreationFlags(int)}.
*
*/
@Override
public GLContext createContext(GLContext shareWith);
/** Returns the {@link GL} pipeline object this GLAutoDrawable uses.
If this method is called outside of the {@link
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();
/** Sets the {@link 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.
@return the set GL pipeline or null if not successful */
public GL setGL(GL gl);
/**
* Method may return the upstream UI toolkit object
* holding this {@link GLAutoDrawable} instance, if exist.
*
* Currently known Java UI toolkits and it's known return types are:
*
*
* Toolkit GLAutoDrawable Implementation ~ Return Type of getUpstreamWidget()
* NEWT {@link com.jogamp.newt.opengl.GLWindow} has a {@link com.jogamp.newt.Window}
* SWT {@link com.jogamp.opengl.swt.GLCanvas} is a {@link org.eclipse.swt.widgets.Canvas}
* AWT {@link javax.media.opengl.awt.GLCanvas} is a {@link java.awt.Canvas}
* AWT {@link javax.media.opengl.awt.GLJPanel} is a {@link 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.
*
*/
public Object getUpstreamWidget();
/**
* Returns the recursive lock object of the {@link #getUpstreamWidget() upstream widget}
* to synchronize multithreaded access on top of {@link NativeSurface#lockSurface()}.
*
* See GLAutoDrawable Locking.
*
* @since 2.2
*/
public RecursiveLock getUpstreamLock();
/**
* Indicates whether the current thread is capable of
* performing OpenGL-related work.
*
* Implementation utilizes this knowledge to determine
* whether {@link #display()} performs the OpenGL commands on the current thread directly
* or spawns them on the dedicated OpenGL thread.
*
* @since 2.2
*/
public boolean isThreadGLCapable();
}