javax.media.opengl

## Interface GLSharedContextSetter

- All Superinterfaces:
    GLAutoDrawable, GLDrawable, NativeSurfaceHolder
  All Known Subinterfaces:
    GLOffscreenAutoDrawable, GLOffscreenAutoDrawable.FBO
  All Known Implementing Classes:
    jogamp.opengl.GLAutoDrawableBase, GLAutoDrawableDelegate, GLCanvas, GLCanvas, GLJPanel, GLWindow

      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. 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 `GLDrawable`s 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 ..

  ##### 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)`

Copyright 2010 JogAmp Community.