JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
com.jogamp.opengl.GLSharedContextSetter Interface Reference

Adds capabilities to set a shared GLContext directly or via an GLAutoDrawable. More...

Inheritance diagram for com.jogamp.opengl.GLSharedContextSetter:
Collaboration diagram for com.jogamp.opengl.GLSharedContextSetter:

Public Member Functions

void setSharedContext (GLContext sharedContext) throws IllegalStateException
 Specifies an OpenGL context, which shall be shared by this GLAutoDrawable's GLContext. More...
 
void setSharedAutoDrawable (GLAutoDrawable sharedAutoDrawable) throws IllegalStateException
 Specifies an GLAutoDrawable, which OpenGL context shall be shared by this GLAutoDrawable's GLContext. More...
 
- Public Member Functions inherited from com.jogamp.opengl.GLAutoDrawable
GLDrawable getDelegatedDrawable ()
 If the implementation uses delegation, return the delegated GLDrawable instance, otherwise return this instance. More...
 
GLContext getContext ()
 Returns the context associated with this drawable. More...
 
GLContext setContext (GLContext newCtx, boolean destroyPrevCtx)
 Associate the new context, newtCtx, to this auto-drawable. More...
 
void addGLEventListener (GLEventListener listener)
 Adds the given listener to the end of this drawable queue. More...
 
void addGLEventListener (int index, GLEventListener listener) throws IndexOutOfBoundsException
 Adds the given listener at the given index of this drawable queue. More...
 
int getGLEventListenerCount ()
 Returns the number of GLEventListener of this drawable queue. More...
 
boolean areAllGLEventListenerInitialized ()
 Returns true if all added GLEventListener are initialized, otherwise false. More...
 
GLEventListener getGLEventListener (int index) throws IndexOutOfBoundsException
 Returns the GLEventListener at the given index of this drawable queue. More...
 
boolean getGLEventListenerInitState (GLEventListener listener)
 Retrieves whether the given listener is initialized or not. More...
 
void setGLEventListenerInitState (GLEventListener listener, boolean initialized)
 Sets the given listener's initialized state. More...
 
GLEventListener disposeGLEventListener (GLEventListener listener, boolean remove)
 Disposes the given listener via dispose(..) if it has been initialized and added to this queue. More...
 
GLEventListener removeGLEventListener (GLEventListener listener)
 Removes the given listener from this drawable queue. More...
 
abstract void setAnimator (GLAnimatorControl animatorControl) throws GLException
 Registers the usage of an animator, an com.jogamp.opengl.GLAnimatorControl implementation. More...
 
GLAnimatorControl getAnimator ()
 
Thread setExclusiveContextThread (Thread t) throws GLException
 Dedicates this instance's GLContext to the given thread. More...
 
Thread getExclusiveContextThread ()
 
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. More...
 
boolean invoke (boolean wait, List< GLRunnable > glRunnables) throws IllegalStateException
 Extends invoke(boolean, GLRunnable) functionality allowing to inject a list of GLRunnables. More...
 
void flushGLRunnables ()
 Flushes all enqueued GLRunnable of this GLAutoDrawable including notifying waiting executor. More...
 
void destroy ()
 Destroys all resources associated with this GLAutoDrawable, inclusive the GLContext. More...
 
void display ()
 
void setAutoSwapBufferMode (boolean enable)
 Enables or disables automatic buffer swapping for this drawable. More...
 
boolean getAutoSwapBufferMode ()
 Indicates whether automatic buffer swapping is enabled for this drawable. More...
 
void setContextCreationFlags (int flags)
 
int getContextCreationFlags ()
 
GLContext createContext (GLContext shareWith)
 Creates a new context for drawing to this drawable that will optionally share buffer objects, textures and other server-side OpenGL objects with the specified GLContext.The GLContext 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. More...
 
GL getGL ()
 Returns the GL pipeline object this GLAutoDrawable uses. More...
 
GL setGL (GL gl)
 Sets the GL pipeline object this GLAutoDrawable uses. More...
 
Object getUpstreamWidget ()
 Method may return the upstream UI toolkit object holding this GLAutoDrawable instance, if exist. More...
 
RecursiveLock getUpstreamLock ()
 Returns the recursive lock object of the upstream widget to synchronize multithreaded access on top of NativeSurface#lockSurface(). More...
 
boolean isThreadGLCapable ()
 Indicates whether the current thread is capable of performing OpenGL-related work. More...
 
- Public Member Functions inherited from com.jogamp.opengl.GLDrawable
GLContext createContext (GLContext shareWith)
 Creates a new context for drawing to this drawable that will optionally share buffer objects, textures and other server-side OpenGL objects with the specified GLContext. More...
 
void setRealized (boolean realized)
 Indicates to GLDrawable implementations whether the underlying surface has been created and can be drawn into. More...
 
boolean isRealized ()
 Returns true if this drawable is realized, otherwise false. More...
 
int getSurfaceWidth ()
 Returns the width of this GLDrawable's surface client area in pixel units. More...
 
int getSurfaceHeight ()
 Returns the height of this GLDrawable's surface client area in pixel units. More...
 
boolean isGLOriented ()
 Returns true if the drawable is rendered in OpenGL's coordinate system, origin at bottom left. More...
 
void swapBuffers () throws GLException
 Swaps the front and back buffers of this drawable. More...
 
GLCapabilitiesImmutable getChosenGLCapabilities ()
 Fetches the GLCapabilitiesImmutable corresponding to the chosen OpenGL capabilities (pixel format / visual / GLProfile) for this drawable. More...
 
GLCapabilitiesImmutable getRequestedGLCapabilities ()
 Fetches the GLCapabilitiesImmutable corresponding to the user requested OpenGL capabilities (pixel format / visual / GLProfile) for this drawable. More...
 
GLProfile getGLProfile ()
 Fetches the GLProfile for this drawable. More...
 
NativeSurface getNativeSurface ()
 Returns the associated NativeSurface of this NativeSurfaceHolder. More...
 
long getHandle ()
 Returns the GL drawable handle, guaranteed to be valid after realization and while it's surface is being locked. More...
 
GLDrawableFactory getFactory ()
 Return the GLDrawableFactory being used to create this instance. More...
 
String toString ()
 
NativeSurface getNativeSurface ()
 Returns the associated NativeSurface of this NativeSurfaceHolder. More...
 

Additional Inherited Members

- Static Public Attributes inherited from com.jogamp.opengl.GLAutoDrawable
static final boolean SCREEN_CHANGE_ACTION_ENABLED = Debug.getBooleanProperty("jogl.screenchange.action", true)
 Flag reflecting whether the GLDrawable reconfiguration will be issued in case a screen device change occurred, e.g. More...
 

Detailed Description

Adds capabilities to set a shared GLContext directly or via an GLAutoDrawable.

Sharing of server-side OpenGL objects such as buffer objects, e.g. VBOs, and textures among OpenGL contexts is supported with this interface.

A master GLContext is the GLContext which is created first. Subsequent shared GLContext w/ the master are referred as slave GLContext.

Implementations of this interface control the slave's GLContext and GLAutoDrawable realization, i.e. the slave GLAutoDrawable will not be realized before their associated master.

Using the nearest or same visual ID or caps across the shared GLDrawables will yield best compatibility.

Lifecycle Considerations

After shared objects are created on the master, the OpenGL pipeline might need to be synchronized w/ the slaves, e.g. via GL#glFinish(). At least this has been experienced w/ OSX 10.9.

In general, destroying a master GLContext before their shared slaves shall be permissible, i.e. the OpenGL driver needs to handle pending destruction of shared resources. This is confirmed to work properly on most platform/driver combinations, see unit test com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2NEWT3 and similar.

However, to avoid scenarios with buggy drivers, users may not destroy the master GLContext before its shared slave GLContext instances as long as they are using them.
Otherwise the OpenGL driver may crash w/ SIGSEGV, due to using already destroyed shared resources, if not handling the pending destruction of the latter!
Either proper lifecycle synchronization is implemented, e.g. by notifying the slaves about the loss of the shared resources, or the slaves validate whether the resources are still valid.

To simplify above lifecycle issues, one may use a dummy GLDrawable and it's GLContext as the master of all shared slave GLContext. Since this dummy instance does not depend on any native windowing system, it can be controlled easily w/o being in sight.
Below code creates a GLAutoDrawable based on a dummy GLDrawable:

     // GLProfile and GLCapabilities should be equal across all shared GL drawable/context.
     final GLCapabilitiesImmutable caps = ... ;
     final GLProfile glp = caps.getGLProfile();
     ..
     final boolean createNewDevice = true; // use 'own' display device!
     final GLAutoDrawable sharedDrawable = GLDrawableFactory.getFactory(glp).createDummyAutoDrawable(null, createNewDevice, caps, null);
     sharedDrawable.display(); // triggers GLContext object creation and native realization.
     ...
     // Later a shared 'slave' can be created e.g.:
     GLWindow glad = GLWindow.create(caps); // or any other GLAutoDrawable supporting GLSharedContextSetter
     glad.setSharedAutoDrawable(sharedDrawable);
     glad.addGLEventListener(..);
     glad.setVisible(true); // GLWindow creation ..
GL Object Synchronization

Usually synchronization of shared GL objects should not be required, if the shared GL objects are created and immutable before concurrent usage.

However, using drivers exposing GLRendererQuirks#NeedSharedObjectSync always require the user to synchronize access of shared GL objects.

Synchronization can be avoided if accessing the shared GL objects exclusively via a queue or Ringbuffer, see GLMediaPlayerImpl as an example.

Known Driver Issues

<h7>Intel's Mesa >= 9.1.2 Backend for [Sandybridge/Ivybridge] on GNU/Linux</h7>

Error: 'intel_do_flush_locked: No such file or directory'
JogAmp: https://jogamp.org/bugzilla/show_bug.cgi?id=873
freedesktop.org: https://bugs.freedesktop.org/show_bug.cgi?id=41736#c8

Shared context seems not to be supported w/ lock-free bound X11 display connections per OpenGL drawable/context. The error message above is thrown in this case. Hence the driver bug renders shared context use w/ JOGL impossible.

<h7>Hisilicon's Immersion.16 on Android</h7>

We failed to create a shared ES2 context on another thread.

Definition at line 124 of file GLSharedContextSetter.java.

Member Function Documentation

◆ setSharedAutoDrawable()

void com.jogamp.opengl.GLSharedContextSetter.setSharedAutoDrawable ( GLAutoDrawable  sharedAutoDrawable) throws IllegalStateException

Specifies an GLAutoDrawable, which OpenGL context shall be shared by this GLAutoDrawable's GLContext.

Since the drawable and context is created at GLAutoDrawable initialization this method shall be called beforehand to have any effect.

A set sharedAutoDrawable will block context creation, i.e. initialization as long it's

See Lifecycle Considerations.

Parameters
sharedContextThe GLAutoDrawable, which OpenGL context shall be shared by this GLAutoDrawable's GLContext.
Exceptions
IllegalStateExceptionif a shared GLContext or shared GLAutoDrawable is already set, the given sharedAutoDrawable is null or equal to this GLAutoDrawable.
See also
setSharedContext(GLContext)

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, and com.jogamp.opengl.swt.GLCanvas.

Here is the caller graph for this function:

◆ setSharedContext()

void com.jogamp.opengl.GLSharedContextSetter.setSharedContext ( GLContext  sharedContext) throws IllegalStateException

Specifies an OpenGL context, which shall be shared by this GLAutoDrawable's GLContext.

Since the drawable and context is created at GLAutoDrawable initialization this method shall be called beforehand to have any effect.

A set sharedContext will block context creation, i.e. GLAutoDrawable initialization, as long it is not created natively.

The preferred method of assigning a shared context is to set the shared GLAutoDrawable, since this method also takes the GLEventListener initialization into account.

See Lifecycle Considerations.

Parameters
sharedContextThe OpenGL context to be shared by this GLAutoDrawable's GLContext.
Exceptions
IllegalStateExceptionif a shared GLContext or shared GLAutoDrawable is already set, the given sharedContext is null or equal to this GLAutoDrawable's context.
See also
setSharedAutoDrawable(GLAutoDrawable)

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, and com.jogamp.opengl.swt.GLCanvas.

Here is the caller graph for this function:

The documentation for this interface was generated from the following file: