Refine test ff5dba28610b4f680c9320e9e52669ed54d4de43: Perform context switch on GL capable thread if required. Add API doc note about this requirement.

2 files changed, 29 insertions, 3 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/util/GLDrawableUtil.java b/src/jogl/classes/com/jogamp/opengl/util/GLDrawableUtil.java
index c19bb12e9..8473a6e27 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/GLDrawableUtil.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/GLDrawableUtil.java
@@ -28,6 +28,7 @@
 package com.jogamp.opengl.util;
 
 import javax.media.nativewindow.AbstractGraphicsDevice;
+
 import javax.media.nativewindow.NativeSurface;
 import javax.media.opengl.GLAnimatorControl;
 import javax.media.opengl.GLAutoDrawable;
@@ -38,6 +39,7 @@ import javax.media.opengl.GLDrawable;
 import javax.media.opengl.GLEventListener;
 import javax.media.opengl.GLException;
 import javax.media.opengl.GLRunnable;
+import javax.media.opengl.Threading;
 
 import com.jogamp.common.util.locks.RecursiveLock;
 import com.jogamp.opengl.GLEventListenerState;
@@ -165,6 +167,8 @@ public class GLDrawableUtil {
      * <p>
      * [1] See Bug 830: swapGLContextAndAllGLEventListener and onscreen MSAA w/ NV/GLX
      * </p>
+     * @see #swapGLContext(GLAutoDrawable, GLAutoDrawable)
+     * @see #swapGLContextAndAllGLEventListener(GLAutoDrawable, GLAutoDrawable)
      */
     public static boolean isSwapGLContextSafe(final GLCapabilitiesImmutable a, final GLCapabilitiesImmutable b) {
         if( ( a.isOnscreen() && !b.isOnscreen() || !a.isOnscreen() && b.isOnscreen() ) && // switching between on- and offscreen
@@ -196,9 +200,14 @@ public class GLDrawableUtil {
      * hence atomicity of operation is guaranteed,
      * see <a href="../../../../javax/media/opengl/GLAutoDrawable.html#locking">GLAutoDrawable Locking</a>.
      * </p>
-     * @param a
-     * @param b
+     * <p>
+     * Because of above mentioned locking, if this method is not performed
+     * on {@link GLAutoDrawable#isThreadGLCapable() a OpenGL capable thread} of <i>both</i>
+     * {@link GLAutoDrawable}s, it must be invoked on such an OpenGL capable thread,
+     * e.g. via {@link Threading#invokeOnOpenGLThread(boolean, Runnable)}.
+     * </p>
      * @throws GLException if the {@link AbstractGraphicsDevice} are incompatible w/ each other.
+     * @see #isSwapGLContextSafe(GLCapabilitiesImmutable, GLCapabilitiesImmutable)
      */
     public static final void swapGLContextAndAllGLEventListener(final GLAutoDrawable a, final GLAutoDrawable b) {
         final GLEventListenerState gllsA = GLEventListenerState.moveFrom(a, true);
@@ -232,8 +241,15 @@ public class GLDrawableUtil {
      * hence atomicity of operation is guaranteed,
      * see <a href="../../../../javax/media/opengl/GLAutoDrawable.html#locking">GLAutoDrawable Locking</a>.
      * </p>
+     * <p>
+     * Because of above mentioned locking, if this method is not performed
+     * on {@link GLAutoDrawable#isThreadGLCapable() a OpenGL capable thread} of <i>both</i>
+     * {@link GLAutoDrawable}s, it must be invoked on such an OpenGL capable thread,
+     * e.g. via {@link Threading#invokeOnOpenGLThread(boolean, Runnable)}.
+     * </p>
      * @param a
      * @param b
+     * @see #isSwapGLContextSafe(GLCapabilitiesImmutable, GLCapabilitiesImmutable)
      */
     public static final void swapGLContext(final GLAutoDrawable a, final GLAutoDrawable b) {
         final GLAnimatorControl aAnim = a.getAnimator();
diff --git a/src/test/com/jogamp/opengl/test/junit/jogl/acore/glels/GLContextDrawableSwitchBase0.java b/src/test/com/jogamp/opengl/test/junit/jogl/acore/glels/GLContextDrawableSwitchBase0.java
index 49d16a80a..239cab26d 100644
--- a/src/test/com/jogamp/opengl/test/junit/jogl/acore/glels/GLContextDrawableSwitchBase0.java
+++ b/src/test/com/jogamp/opengl/test/junit/jogl/acore/glels/GLContextDrawableSwitchBase0.java
@@ -34,6 +34,7 @@ import javax.media.opengl.GLAutoDrawable;
 import javax.media.opengl.GLCapabilities;
 import javax.media.opengl.GLCapabilitiesImmutable;
 import javax.media.opengl.GLProfile;
+import javax.media.opengl.Threading;
 
 import com.jogamp.opengl.util.Animator;
 import com.jogamp.opengl.util.GLDrawableUtil;
@@ -226,8 +227,17 @@ public abstract class GLContextDrawableSwitchBase0 extends UITestCase {
                     s++;
                     System.err.println(s+" - switch - START "+ ( t1 - t0 ));
 
+                    final Runnable switchAction = new Runnable() {
+                            public void run() {
+                                GLDrawableUtil.swapGLContextAndAllGLEventListener(gladSource, gladDest);
+                            } };
+
                     // switch context _and_ the demo synchronously
-                    GLDrawableUtil.swapGLContextAndAllGLEventListener(gladSource, gladDest);
+                    if( gladSource.isThreadGLCapable() && gladDest.isThreadGLCapable() ) {
+                        switchAction.run();
+                    } else {
+                        Threading.invokeOnOpenGLThread(true, switchAction);
+                    }
                     snapshotGLEventListener.setMakeSnapshot();
 
                     System.err.println(s+" - switch - END "+ ( t1 - t0 ));