javax.media.opengl

Interface GLSharedContextSetter

All Superinterfaces:

GLAutoDrawable, GLDrawable, NativeSurfaceHolder

All Known Subinterfaces:

GLOffscreenAutoDrawable, GLOffscreenAutoDrawable.FBO

All Known Implementing Classes:

GLCanvas, GLJPanel

public interface GLSharedContextSetter
extends GLAutoDrawable

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, shared GLContext w/ this master are referred as slave GLContext and controls the shared object's lifecycle, i.e. their construction and destruction.

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.

Be aware that the master GLContext and related resources shall not be destroyed before it's slave GLContext instances while they are using them.
Otherwise the OpenGL driver implementation may crash w/ SIGSEGV, since using already destroyed resources, e.g. OpenGL buffer objects, may not be validated by the driver!

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

Known Driver Issues

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

 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.

Hisilicon's Immersion.16 on Android

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

Field Summary

Fields inherited from interface javax.media.opengl.GLAutoDrawable

SCREEN_CHANGE_ACTION_ENABLED

Method Summary

Methods

Modifier and Type	Method and Description
void	setSharedAutoDrawable(GLAutoDrawable sharedAutoDrawable) Specifies an GLAutoDrawable, which OpenGL context shall be shared by this GLAutoDrawable's GLContext.
void	setSharedContext(GLContext sharedContext) Specifies an OpenGL context, which shall be shared by this GLAutoDrawable's GLContext.

Methods inherited from interface javax.media.opengl.GLAutoDrawable

addGLEventListener, addGLEventListener, areAllGLEventListenerInitialized, createContext, destroy, display, disposeGLEventListener, flushGLRunnables, getAnimator, getAutoSwapBufferMode, getContext, getContextCreationFlags, getDelegatedDrawable, getExclusiveContextThread, getGL, getGLEventListener, getGLEventListenerCount, getGLEventListenerInitState, getUpstreamLock, getUpstreamWidget, invoke, invoke, isThreadGLCapable, removeGLEventListener, setAnimator, setAutoSwapBufferMode, setContext, setContextCreationFlags, setExclusiveContextThread, setGL, setGLEventListenerInitState

Methods inherited from interface javax.media.opengl.GLDrawable

getChosenGLCapabilities, getFactory, getGLProfile, getHandle, getNativeSurface, getRequestedGLCapabilities, getSurfaceHeight, getSurfaceWidth, isGLOriented, isRealized, setRealized, swapBuffers, toString

Method Detail

setSharedContext

void 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:

sharedContext - The OpenGL context to be shared by this GLAutoDrawable's GLContext.

Throws:

IllegalStateException - if 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)

setSharedAutoDrawable

void 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

• GLContext is null, or
• GLContext has not been created natively, or
• GLEventListener are not completely initialized

See Lifecycle Considerations.

Parameters:

sharedContext - The GLAutoDrawable, which OpenGL context shall be shared by this GLAutoDrawable's GLContext.

Throws:

IllegalStateException - if a shared GLContext or shared GLAutoDrawable is already set, the given sharedAutoDrawable is null or equal to this GLAutoDrawable.

See Also:

setSharedContext(GLContext)