Bug 776 GLContext Sharing: GLSharedContextSetter API Doc: No 'Driver stability constraints' ; Fixing Test cases: Enable all, GearsObject*: Check VBO

- GLSharedContextSetter API Doc: No 'Driver stability constraints'
  - No driver issues ..
  - Use 'Lifecycle Considerations' to describe usage issues ..

- Fixing Test cases: Enable all, GearsObject*: Check VBO
  - GearsObject* needs to check whether VBO is 'still alive'
    if sharing is enabled.

  - Enable all unit tests.

8 files changed, 57 insertions, 45 deletions

diff --git a/make/scripts/tests.sh b/make/scripts/tests.sh
index 6a8ff80ca..8a59e68e3 100644
--- a/make/scripts/tests.sh
+++ b/make/scripts/tests.sh
@@ -84,8 +84,10 @@ function jrun() {
     #D_ARGS="-Dnativewindow.debug.X11Util.ATI_HAS_NO_XCLOSEDISPLAY_BUG"
     #D_ARGS="-Dnativewindow.debug.X11Util.ATI_HAS_NO_MULTITHREADING_BUG"
     #D_ARGS="-Djogl.disable.opengles"
-    #D_ARGS="-Djogl.debug.DebugGL"
+    #D_ARGS="-Djogl.debug.DebugGL -Dnewt.debug.Window"
     #D_ARGS="-Djogl.debug.DebugGL -Djogl.debug.FBObject"
+    #D_ARGS="-Djogl.debug.TraceGL"
+    #D_ARGS="-Djogl.debug.DebugGL"
     #D_ARGS="-Djogl.debug.FBObject -Djogl.debug.TraceGL -Djogl.debug.GLBufferStateTracker"
     #D_ARGS="-Djogl.debug.FBObject"
     #D_ARGS="-Djogl.debug.GLSLCode"
@@ -376,10 +378,10 @@ function testawtswt() {
 #testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2NEWT0 $*
 #testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2NEWT1 $*
 #testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2NEWT2 $*
-#testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2NEWT3 $*
+testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2NEWT3 $*
 #testawt com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2AWT3 $*
 #testawt com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2AWT3b $*
-testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2SWT3 $*
+#testnoawt com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2SWT3 $*
 #testawt com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextWithJTabbedPaneAWT $*
 #testawt com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextNewtAWTBug523 $*
 #testawt com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextListAWT $*
diff --git a/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java b/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
index 8c2311329..fd48d12bf 100644
--- a/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
+++ b/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
@@ -36,24 +36,40 @@ package javax.media.opengl;
  * </p>
  * <p>
  * A <i>master</i> {@link GLContext} is the {@link GLContext} which is created first,
- * shared {@link GLContext} w/ this master are referred as slave {@link GLContext}.
+ * shared {@link GLContext} w/ this master are referred as slave {@link GLContext}
+ * and controls the shared object's lifecycle, i.e. their construction and destruction.
  * </p>
- * <h5><a name="driverstabilityconstraints">Driver stability constraints</a></h5>
+ * <h5><a name="lifecycle">Lifecycle Considerations</a></h5>
  * <p>
- * Be aware that the <i>master</i> {@link GLContext} and related resources, i.e. the {@link GLAutoDrawable},
- * <i>shall not</i> be destroyed before it's <i>slave</i> {@link GLContext} instances.<br>
- * Otherwise the OpenGL driver implementation may crash w/ SIGSEGV if shared resources are still used!<br>
- * Note that this is not specified within OpenGL and <i>should work</i>, however, some drivers
- * do not seem to handle this situation well, i.e. they do not postpone resource destruction
- * until the last reference is removed.<br>
- * Since pending destruction of {@link GLContext} and it's {@link GLDrawable} is complex and nearly impossible
- * for us at the top level, considering the different windowing systems and {@link GLAutoDrawable} types,
- * the user shall take care of proper destruction order.
+ * Be aware that the <i>master</i> {@link GLContext} and related resources
+ * <i>shall not</i> be destroyed before it's <i>slave</i> {@link GLContext} instances <i>while they are using them</i>.<br>
+ * 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!<br>
  * </p>
  * <p>
- * Users may use a {@link GLDrawableFactory#createDummyDrawable(javax.media.nativewindow.AbstractGraphicsDevice, boolean, GLProfile) dummy}
+ * Either proper lifecycle synchronization is implemented, e.g. by notifying the <i>slaves</i> about the loss of the shared resources,
+ * <i>or</i> the <i>slaves</i> validate whether the resources are still valid.
+ * </p>
+ * <p>
+ * To simplify above lifecycle issues, one may use a {@link GLDrawableFactory#createDummyDrawable(javax.media.nativewindow.AbstractGraphicsDevice, boolean, GLProfile) dummy}
  * {@link GLDrawable} and it's {@link GLContext} as the <i>master</i> of all shared <i>slave</i> {@link GLContext}.
- * Same constraints as above apply, i.e. it shall be destroyed <i>after</i> all shared slaves.
+ * Since this <i>dummy instance</i> does not depend on any native windowing system, it can be controlled easily w/o being <i>in sight</i>.<br>
+ * Below code creates a {@link GLAutoDrawable} based on a <i>dummy GLDrawable</i>:
+ * <pre>
+        // 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, glp);
+        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 ..
+ * </pre>
  * </p>
  */
 public interface GLSharedContextSetter extends GLAutoDrawable {
@@ -69,7 +85,7 @@ public interface GLSharedContextSetter extends GLAutoDrawable {
      * as long it is not {@link GLContext#isCreated() created natively}.
      * </p>
      * <p>
-     * See <a href="#driverstabilityconstraints">driver stability constraints</a>.
+     * See <a href="#lifecycle">Lifecycle Considerations</a>.
      * </p>
      *
      * @param sharedContext The OpenGL context to be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
@@ -93,7 +109,7 @@ public interface GLSharedContextSetter extends GLAutoDrawable {
      * or has not been {@link GLContext#isCreated() created natively}.
      * </p>
      * <p>
-     * See <a href="#driverstabilityconstraints">driver stability constraints</a>.
+     * See <a href="#lifecycle">Lifecycle Considerations</a>.
      * </p>
      *
      * @param sharedContext The GLAutoDrawable, which OpenGL context shall be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
diff --git a/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2AWT3.java b/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2AWT3.java
index 710a9772b..ede01b52f 100644
--- a/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2AWT3.java
+++ b/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2AWT3.java
@@ -97,8 +97,7 @@ public class TestSharedContextVBOES2AWT3 extends UITestCase {
         syncedOneAnimator(true);
     }
 
-    // Don't test erroneous test case !
-    // @Test
+    @Test
     public void test02SyncedOneAnimatorDirtyDtorOrder() throws InterruptedException, InvocationTargetException {
         syncedOneAnimator(false);
     }
@@ -234,13 +233,12 @@ public class TestSharedContextVBOES2AWT3 extends UITestCase {
     }
 
     @Test
-    public void test11SyncEachAnimatorCleanDtorOrder() throws InterruptedException, InvocationTargetException {
+    public void test11AsyncEachAnimatorCleanDtorOrder() throws InterruptedException, InvocationTargetException {
         syncedOneAnimator(true);
     }
 
-    // Don't test erroneous test case !
-    // @Test
-    public void test12SyncEachAnimatorDirtyDtorOrder() throws InterruptedException, InvocationTargetException {
+    @Test
+    public void test12AsyncEachAnimatorDirtyDtorOrder() throws InterruptedException, InvocationTargetException {
         asyncEachOneAnimator(false);
     }
 
diff --git a/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2NEWT1.java b/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2NEWT1.java
index 827601869..3cd26028b 100644
--- a/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2NEWT1.java
+++ b/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2NEWT1.java
@@ -34,11 +34,9 @@ import javax.media.nativewindow.util.InsetsImmutable;
 import javax.media.opengl.GLAutoDrawable;
 import javax.media.opengl.GLCapabilities;
 import javax.media.opengl.GLContext;
-import javax.media.opengl.GLDrawable;
 import javax.media.opengl.GLDrawableFactory;
 import javax.media.opengl.GLProfile;
 
-import com.jogamp.opengl.GLAutoDrawableDelegate;
 import com.jogamp.opengl.util.Animator;
 import com.jogamp.opengl.test.junit.util.AWTRobotUtil;
 import com.jogamp.opengl.test.junit.util.MiscUtils;
@@ -107,9 +105,7 @@ public class TestSharedContextVBOES2NEWT1 extends UITestCase {
             glWindow.setVisible(true);
             sharedDrawable = glWindow;
         } else {
-            GLDrawable dummyDrawable = GLDrawableFactory.getFactory(glp).createDummyDrawable(null, true /* createNewDevice */, caps.getGLProfile());
-            dummyDrawable.setRealized(true);
-            sharedDrawable = new GLAutoDrawableDelegate(dummyDrawable, null, null, true /*ownDevice*/, null) { };
+            sharedDrawable = GLDrawableFactory.getFactory(glp).createDummyAutoDrawable(null, true /* createNewDevice */, caps.getGLProfile());
         }
         Assert.assertNotNull(sharedDrawable);
         Assert.assertTrue(AWTRobotUtil.waitForRealized(sharedDrawable, true));
diff --git a/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2NEWT2.java b/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2NEWT2.java
index d9fe2a949..24dc09ffb 100644
--- a/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2NEWT2.java
+++ b/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2NEWT2.java
@@ -100,8 +100,7 @@ public class TestSharedContextVBOES2NEWT2 extends UITestCase {
         syncedOneAnimator(true);
     }
 
-    // Don't test erroneous test case !
-    // @Test
+    @Test
     public void test02SyncedOneAnimatorDirtyDtorOrder() throws InterruptedException {
         syncedOneAnimator(false);
     }
@@ -215,12 +214,11 @@ public class TestSharedContextVBOES2NEWT2 extends UITestCase {
     }
 
     @Test
-    public void test11ASyncEachAnimatorCleanDtorOrder() throws InterruptedException {
+    public void test11AsyncEachAnimatorCleanDtorOrder() throws InterruptedException {
         asyncEachAnimator(true);
     }
 
-    // Don't test erroneous test case !
-    // @Test
+    @Test
     public void test12AsyncEachAnimatorDirtyDtorOrder() throws InterruptedException {
         asyncEachAnimator(false);
     }
diff --git a/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2NEWT3.java b/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2NEWT3.java
index adadf85e3..96a8a5094 100644
--- a/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2NEWT3.java
+++ b/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestSharedContextVBOES2NEWT3.java
@@ -97,8 +97,7 @@ public class TestSharedContextVBOES2NEWT3 extends UITestCase {
         syncedOneAnimator(true);
     }
 
-    // Don't test erroneous test case !
-    // @Test
+    @Test
     public void test02SyncedOneAnimatorDirtyDtorOrder() throws InterruptedException {
         syncedOneAnimator(false);
     }
@@ -203,8 +202,7 @@ public class TestSharedContextVBOES2NEWT3 extends UITestCase {
         asyncEachAnimator(true);
     }
 
-    // Don't test erroneous test case !
-    // @Test
+    @Test
     public void test12AsyncEachAnimatorDirtyDtorOrder() throws InterruptedException {
         asyncEachAnimator(false);
     }
diff --git a/src/test/com/jogamp/opengl/test/junit/jogl/demos/es1/GearsObjectES1.java b/src/test/com/jogamp/opengl/test/junit/jogl/demos/es1/GearsObjectES1.java
index 1edf1c3a8..fb9251e75 100644
--- a/src/test/com/jogamp/opengl/test/junit/jogl/demos/es1/GearsObjectES1.java
+++ b/src/test/com/jogamp/opengl/test/junit/jogl/demos/es1/GearsObjectES1.java
@@ -52,9 +52,11 @@ public class GearsObjectES1 extends GearsObject {
     }
 
     private void draw(GL2ES1 gl, GLArrayDataServer array, int mode) {
-        array.enableBuffer(gl, true);
-        gl.glDrawArrays(mode, 0, array.getElementCount());
-        array.enableBuffer(gl, false);
+        if( !isShared || gl.glIsBuffer(array.getVBOName()) ) {
+            array.enableBuffer(gl, true);
+            gl.glDrawArrays(mode, 0, array.getElementCount());
+            array.enableBuffer(gl, false);
+        }
     }
 
     @Override
diff --git a/src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/GearsObjectES2.java b/src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/GearsObjectES2.java
index 82e9089cf..f3367ad1c 100644
--- a/src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/GearsObjectES2.java
+++ b/src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/GearsObjectES2.java
@@ -89,10 +89,12 @@ public class GearsObjectES2 extends GearsObject {
     }
 
     private void draw(GL2ES2 gl, GLArrayDataServer array, int mode, int face) {
-        array.enableBuffer(gl, true);
-        // System.err.println("XXX Draw face "+face+" of "+this);
-        gl.glDrawArrays(mode, 0, array.getElementCount());
-        array.enableBuffer(gl, false);
+        if( !isShared || gl.glIsBuffer(array.getVBOName()) ) {
+            array.enableBuffer(gl, true);
+            // System.err.println("XXX Draw face "+face+" of "+this);
+            gl.glDrawArrays(mode, 0, array.getElementCount());
+            array.enableBuffer(gl, false);
+        }
     }
 
     @Override