GLSharedContextSetter: Fix API doc and all html references (fix URL and complete notes in all implementations)

8 files changed, 50 insertions, 11 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java b/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java
index 4ef717a38..b9f1fb10c 100644
--- a/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java
+++ b/src/jogl/classes/com/jogamp/opengl/GLAutoDrawableDelegate.java
@@ -38,6 +38,7 @@ import javax.media.opengl.GLDrawable;
 import javax.media.opengl.GLDrawableFactory;
 import javax.media.opengl.GLEventListener;
 import javax.media.opengl.GLException;
+import javax.media.opengl.GLSharedContextSetter;
 
 import com.jogamp.common.util.locks.LockFactory;
 import com.jogamp.common.util.locks.RecursiveLock;
@@ -62,6 +63,12 @@ import jogamp.opengl.GLDrawableImpl;
  * <p>
  * See example {@link com.jogamp.opengl.test.junit.jogl.acore.TestGLAutoDrawableDelegateNEWT TestGLAutoDrawableDelegateNEWT}.
  * </p>
+ * <p>
+ * <a name="contextSharing"><h5>OpenGL Context Sharing</h5></a>
+ * To share a {@link GLContext} see the following note in the documentation overview:
+ * <a href="../../../overview-summary.html#SHARING">context sharing</a>
+ * as well as {@link GLSharedContextSetter}.
+ * </p>
  */
 public class GLAutoDrawableDelegate extends GLAutoDrawableBase implements GLAutoDrawable {
     /**
diff --git a/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java b/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
index e33ceeefb..28f572d7d 100644
--- a/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
+++ b/src/jogl/classes/com/jogamp/opengl/swt/GLCanvas.java
@@ -85,6 +85,12 @@ import com.jogamp.opengl.JoglVersion;
  * <p>
  * Implementation allows use of custom {@link GLCapabilities}.
  * </p>
+ * <p>
+ * <a name="contextSharing"><h5>OpenGL Context Sharing</h5></a>
+ * To share a {@link GLContext} see the following note in the documentation overview:
+ * <a href="../../../../overview-summary.html#SHARING">context sharing</a>
+ * as well as {@link GLSharedContextSetter}.
+ * </p>
  */
 public class GLCanvas extends Canvas implements GLAutoDrawable, GLSharedContextSetter {
   private static final boolean DEBUG = Debug.debug("GLCanvas");
diff --git a/src/jogl/classes/javax/media/opengl/GLDrawable.java b/src/jogl/classes/javax/media/opengl/GLDrawable.java
index 7ed057ea4..5c881ab73 100644
--- a/src/jogl/classes/javax/media/opengl/GLDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLDrawable.java
@@ -60,8 +60,9 @@ public interface GLDrawable extends NativeSurfaceHolder {
    * The GLContext <code>share</code> need not be associated with this
    * GLDrawable and may be null if sharing of display lists and other
    * objects is not desired. See the note in the overview
-   * documentation on
-   * <a href="../../../spec-overview.html#SHARING">context sharing</a>.
+   * documentation
+   * <a href="../../../overview-summary.html#SHARING">context sharing</a>
+   * as well as {@link GLSharedContextSetter}.
    * </p>
    */
   public GLContext createContext(GLContext shareWith);
diff --git a/src/jogl/classes/javax/media/opengl/GLOffscreenAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLOffscreenAutoDrawable.java
index a69480242..62d10d4cb 100644
--- a/src/jogl/classes/javax/media/opengl/GLOffscreenAutoDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLOffscreenAutoDrawable.java
@@ -39,6 +39,12 @@ import com.jogamp.opengl.FBObject;
  * This class distinguishes itself from {@link GLAutoDrawable}
  * with it's {@link #setSurfaceSize(int, int)} functionality.
  * </p>
+ * <p>
+ * <a name="contextSharing"><h5>OpenGL Context Sharing</h5></a>
+ * To share a {@link GLContext} see the following note in the documentation overview:
+ * <a href="../../../overview-summary.html#SHARING">context sharing</a>
+ * as well as {@link GLSharedContextSetter}.
+ * </p>
  */
 public interface GLOffscreenAutoDrawable extends GLAutoDrawable, GLSharedContextSetter {
 
diff --git a/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java b/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
index 679898dca..526967d69 100644
--- a/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
+++ b/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java
@@ -35,9 +35,12 @@ package javax.media.opengl;
  * 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}
- * and controls the shared object's lifecycle, i.e. their construction and destruction.
+ * A <i>master</i> {@link GLContext} is the {@link GLContext} which is created first.
+ * Subsequent shared {@link GLContext} w/ the <i>master</i> are referred as <i>slave</i> {@link GLContext}.
+ * </p>
+ * <p>
+ * Implementations of this interface control the <i>slave's</i> {@link GLContext} and {@link GLAutoDrawable} realization,
+ * i.e. the <i>slave</i> {@link GLAutoDrawable} will not be realized before their associated <i>master</i>.
  * </p>
  * <p>
  * Using the nearest or same {@link GLCapabilitiesImmutable#getVisualID(javax.media.nativewindow.VisualIDHolder.VIDType) visual ID}
@@ -50,12 +53,17 @@ package javax.media.opengl;
  * At least this has been experienced w/ OSX 10.9.
  * </p>
  * <p>
- * 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>
+ * In general, destroying a <i>master</i> {@link GLContext} before their shared <i>slaves</i>
+ * 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 <code>com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2NEWT3</code> and similar.
  * </p>
  * <p>
+ * However, to avoid scenarios with buggy drivers, users <i>may not</i> destroy the
+ * <i>master</i> {@link GLContext} before its shared <i>slave</i> {@link GLContext} instances
+ * <i>as long as they are using them</i>.<br>
+ * Otherwise the OpenGL driver may crash w/ SIGSEGV, due to using already destroyed shared resources,
+ * if not handling the pending destruction of the latter!<br>
  * 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>
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
index dba1dbc04..b8e518ea5 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
@@ -156,10 +156,12 @@ import jogamp.opengl.awt.AWTTilePainter;
  *   <li><pre>sun.awt.noerasebackground=true</pre></li>
  * </ul>
  *
+ * <p>
  * <a name="contextSharing"><h5>OpenGL Context Sharing</h5></a>
  * To share a {@link GLContext} see the following note in the documentation overview:
- * <a href="../../../spec-overview.html#SHARING">context sharing</a>
+ * <a href="../../../../overview-summary.html#SHARING">context sharing</a>
  * as well as {@link GLSharedContextSetter}.
+ * </p>
  */
 
 @SuppressWarnings("serial")
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
index 1682c6d2a..a95681ee7 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
@@ -173,10 +173,12 @@ import com.jogamp.opengl.util.texture.TextureState;
     It is recommended to reset those states to default when leaving the {@link GLEventListener#display(GLAutoDrawable)} method!
     We may change this behavior in the future, i.e. preserve all influencing states.
     </p>
+    <p>
     <a name="contextSharing"><h5>OpenGL Context Sharing</h5></a>
     To share a {@link GLContext} see the following note in the documentation overview:
-    <a href="../../../spec-overview.html#SHARING">context sharing</a>
+    <a href="../../../../overview-summary.html#SHARING">context sharing</a>
     as well as {@link GLSharedContextSetter}.
+    </p>
 */
 
 @SuppressWarnings("serial")
diff --git a/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java b/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java
index 24a203b31..42b886742 100644
--- a/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java
+++ b/src/newt/classes/com/jogamp/newt/opengl/GLWindow.java
@@ -65,6 +65,7 @@ import javax.media.opengl.GLEventListener;
 import javax.media.opengl.GLException;
 import javax.media.opengl.GLProfile;
 import javax.media.opengl.GLRunnable;
+import javax.media.opengl.GLSharedContextSetter;
 
 import jogamp.newt.WindowImpl;
 import jogamp.opengl.GLAutoDrawableBase;
@@ -108,6 +109,12 @@ import com.jogamp.opengl.GLStateKeeper;
  * you can inject {@link GLRunnable} objects
  * via {@link #invoke(boolean, GLRunnable)} to the OpenGL command stream.<br>
  * </p>
+ * <p>
+ * <a name="contextSharing"><h5>OpenGL Context Sharing</h5></a>
+ * To share a {@link GLContext} see the following note in the documentation overview:
+ * <a href="../../../../overview-summary.html#SHARING">context sharing</a>
+ * as well as {@link GLSharedContextSetter}.
+ * </p>
  */
 public class GLWindow extends GLAutoDrawableBase implements GLAutoDrawable, Window, NEWTEventConsumer, FPSCounter {
     private final WindowImpl window;