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!

1 files changed, 29 insertions, 1 deletions

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}