Bug 776 GLContext Sharing: Add note about driver stability (destruction order) ; Fix unit tests (Shared Gears, wait for created context and destruction order)

- Add note about driver stability (destruction order)
  - See GLSharedContextSetter: Don't destroy master context before slaves!

- Fix spec-overview.html#SHARED links, add link to GLSharedContextSetter in SHARED subsection.

- Fix unit tests (Shared Gears, wait for created context and destruction order)
  - The GearsObject sharing was completly bogus!
    It simply used the _same_ GLArrayDataServer instance for sharing,
    but it should use a _copy_ of the shared GLArrayDataServer while
    only preserving the VBO object!
    Fixed, while adding required methods to GLArrayDataServer.

  - Waiting for the created GLContext of a GLAutoDrawable required us
    to pass the latter _and_ check whether it's GLContext exists and is natively created.

  - Accomodated the destruction order - see above!

4 files changed, 34 insertions, 13 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
index 817dff8ad..98eb9bdde 100644
--- a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
+++ b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
@@ -675,8 +675,8 @@ public abstract class GLDrawableFactory {
    * The GLPbuffer drawable is realized and initialized eagerly.
    * </p>
    *
-   * See the note in the overview documentation on
-   * <a href="../../../spec-summary.html#SHARING">context sharing</a>.
+   * See the note in the overview documentation in {@link GLSharedContextSetter} and on
+   * <a href="../../../spec-overview.html#SHARING">context sharing</a>.
    *
    * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be <code>null</code> for the platform's default device.
    * @param capabilities the requested capabilities
diff --git a/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java b/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
index d5a10931e..8c2311329 100644
--- a/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
+++ b/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
@@ -31,7 +31,29 @@ package javax.media.opengl;
 /**
  * Adds capabilities to set a shared {@link GLContext} directly or via an {@link GLAutoDrawable}.
  * <p>
- * Warning: Don't reference this interface directly, since it may end up in {@link GLAutoDrawable}
+ * Sharing of server-side OpenGL objects such as buffer objects, e.g. VBOs,
+ * and textures among OpenGL contexts is supported with this interface.
+ * </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}.
+ * </p>
+ * <h5><a name="driverstabilityconstraints">Driver stability constraints</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.
+ * </p>
+ * <p>
+ * Users 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.
  * </p>
  */
 public interface GLSharedContextSetter extends GLAutoDrawable {
@@ -46,6 +68,9 @@ public interface GLSharedContextSetter extends GLAutoDrawable {
      * A set <i>sharedContext</i> will block context creation, i.e. {@link GLAutoDrawable#initialization GLAutoDrawable initialization},
      * as long it is not {@link GLContext#isCreated() created natively}.
      * </p>
+     * <p>
+     * See <a href="#driverstabilityconstraints">driver stability constraints</a>.
+     * </p>
      *
      * @param sharedContext The OpenGL context to be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
      * @throws IllegalStateException if a {@link #setSharedContext(GLContext) shared GLContext}
@@ -67,6 +92,9 @@ public interface GLSharedContextSetter extends GLAutoDrawable {
      * as long it's {@link GLContext} is <code>null</code>
      * or has not been {@link GLContext#isCreated() created natively}.
      * </p>
+     * <p>
+     * See <a href="#driverstabilityconstraints">driver stability constraints</a>.
+     * </p>
      *
      * @param sharedContext The GLAutoDrawable, which OpenGL context shall be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
      * @throws IllegalStateException if a {@link #setSharedContext(GLContext) shared GLContext}
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
index c2d8e0535..439a5bd30 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
@@ -246,7 +246,7 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable, WindowClosing
       textures, display lists and other OpenGL state, and may be null
       if sharing is not desired. See the note in the overview
       documentation on <a
-      href="../../../spec-summary.html#SHARING">context
+      href="../../../spec-overview.html#SHARING">context
       sharing</a>. The passed GraphicsDevice indicates the screen on
       which to create the GLCanvas; the GLDrawableFactory uses the
       default screen device of the local GraphicsEnvironment if null
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
index faf00c19a..8b1467268 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
@@ -286,14 +286,7 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing
       default set of capabilities is used. The GLCapabilitiesChooser
       specifies the algorithm for selecting one of the available
       GLCapabilities for the component; a DefaultGLCapabilitesChooser
-      is used if null is passed for this argument. The passed
-      GLContext specifies an OpenGL context with which to share
-      textures, display lists and other OpenGL state, and may be null
-      if sharing is not desired. See the note in the overview documentation on
-      <a href="../../../spec-summary.html#SHARING">context sharing</a>.
-      <P>
-      Note: Sharing cannot be enabled using J2D OpenGL FBO sharing,
-      since J2D GL Context must be shared and we can only share one context.
+      is used if null is passed for this argument.
     * @throws GLException if no GLCapabilities are given and no default profile is available for the default desktop device.
   */
   public GLJPanel(GLCapabilitiesImmutable userCapsRequest, GLCapabilitiesChooser chooser)
@@ -311,7 +304,7 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing
       GLContext specifies an OpenGL context with which to share
       textures, display lists and other OpenGL state, and may be null
       if sharing is not desired. See the note in the overview documentation on
-      <a href="../../../spec-summary.html#SHARING">context sharing</a>.
+      <a href="../../../spec-overview.html#SHARING">context sharing</a>.
       <P>
       Note: Sharing cannot be enabled using J2D OpenGL FBO sharing,
       since J2D GL Context must be shared and we can only share one context.