Added note on limitations of OpenGL context sharing to spec overview

and pointed to it from GLDrawableFactory, GLDrawable, GLCanvas and
GLJPanel


git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@611 232f8b59-042b-4e1e-8c03-345bb8c30851

5 files changed, 32 insertions, 8 deletions

diff --git a/make/spec-overview.html b/make/spec-overview.html
index c8c45142a..a187e2c51 100644
--- a/make/spec-overview.html
+++ b/make/spec-overview.html
@@ -199,6 +199,20 @@ which a separate thread attempts to alter the contents of the argument during
 the time interval following validation but preceding passage of the argument 
 to the underlying native engine.<br>
    
+<h3><a name="SHARING">Sharing of Server-Side OpenGL Objects between GLContexts</a></h3>
+
+Sharing of server-side OpenGL objects such as textures and display
+lists among OpenGL contexts is supported in this specification.
+However, the specification does not guarantee that a request to share
+objects between two contexts will succeed. Certain OpenGL
+implementations restrict sharing in certain ways. Applications should
+assume that sharing is a request more than an assertion.
+Implementations of this specification should, but are not required to,
+provide timely notification of a failure of a request to share objects
+between two GLContexts, perhaps in the form of a GLException. The
+situation in which sharing is most likely to work on all platforms is
+between two GLContexts associated with the same GLDrawable.
+
 <h3>Criteria Used for Inclusion of APIs into the Java Bindings</h3>
    
 <h4>OpenGL API Inclusion Criteria</h4>
diff --git a/src/classes/javax/media/opengl/GLCanvas.java b/src/classes/javax/media/opengl/GLCanvas.java
index b6c1ca0d0..0329e4017 100644
--- a/src/classes/javax/media/opengl/GLCanvas.java
+++ b/src/classes/javax/media/opengl/GLCanvas.java
@@ -90,10 +90,13 @@ public class GLCanvas extends Canvas implements GLAutoDrawable {
       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. 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 is passed for this argument. */
+      if sharing is not desired. See the note in the overview
+      documentation on <a
+      href="../../../overview-summary.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
+      is passed for this argument. */
   public GLCanvas(GLCapabilities capabilities,
                   GLCapabilitiesChooser chooser,
                   GLContext shareWith,
diff --git a/src/classes/javax/media/opengl/GLDrawable.java b/src/classes/javax/media/opengl/GLDrawable.java
index a1780bd2a..13b905167 100644
--- a/src/classes/javax/media/opengl/GLDrawable.java
+++ b/src/classes/javax/media/opengl/GLDrawable.java
@@ -71,11 +71,13 @@ public interface GLDrawable {
   /**
    * Creates a new context for drawing to this drawable that will
    * optionally share display lists and other server-side OpenGL
-   * objects with the specified GLContext.
+   * objects with the specified GLContext. <P>
    *
    * 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.
+   * objects is not desired. See the note in the overview
+   * documentation on
+   * <a href="../../../overview-summary.html#SHARING">context sharing</a>.
    */
   public GLContext createContext(GLContext shareWith);
 
diff --git a/src/classes/javax/media/opengl/GLDrawableFactory.java b/src/classes/javax/media/opengl/GLDrawableFactory.java
index ded3a0304..fd934195c 100644
--- a/src/classes/javax/media/opengl/GLDrawableFactory.java
+++ b/src/classes/javax/media/opengl/GLDrawableFactory.java
@@ -186,7 +186,10 @@ public abstract class GLDrawableFactory {
   public abstract boolean canCreateGLPbuffer();
 
   /**
-   * Creates a GLPbuffer with the given capabilites and dimensions.
+   * Creates a GLPbuffer with the given capabilites and dimensions. <P>
+   *
+   * See the note in the overview documentation on
+   * <a href="../../../overview-summary.html#SHARING">context sharing</a>.
    *
    * @throws GLException if any window system-specific errors caused
    *         the creation of the GLPbuffer to fail.
diff --git a/src/classes/javax/media/opengl/GLJPanel.java b/src/classes/javax/media/opengl/GLJPanel.java
index dbc5e432a..086e7c055 100644
--- a/src/classes/javax/media/opengl/GLJPanel.java
+++ b/src/classes/javax/media/opengl/GLJPanel.java
@@ -213,7 +213,9 @@ public class GLJPanel extends JPanel implements GLAutoDrawable {
       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. */
+      if sharing is not desired. See the note in the overview documentation on
+      <a href="../../../overview-summary.html#SHARING">context sharing</a>.
+  */
   public GLJPanel(GLCapabilities capabilities, GLCapabilitiesChooser chooser, GLContext shareWith) {
     super();