summaryrefslogtreecommitdiffstats
path: root/src/jogl/classes/javax
diff options
context:
space:
mode:
authorSven Gothel <[email protected]>2014-08-29 01:31:03 +0200
committerSven Gothel <[email protected]>2014-08-29 01:31:03 +0200
commit4dfa5e34b5bbfc74dd9ca6ead89b23d12e7a1b01 (patch)
tree404baacbe3b199526c5b58112aae55d14ba751ec /src/jogl/classes/javax
parent28ad09d75c7565983fb43e83da6e1726f92677db (diff)
GLSharedContextSetter: Fix API doc and all html references (fix URL and complete notes in all implementations)
Diffstat (limited to 'src/jogl/classes/javax')
-rw-r--r--src/jogl/classes/javax/media/opengl/GLDrawable.java5
-rw-r--r--src/jogl/classes/javax/media/opengl/GLOffscreenAutoDrawable.java6
-rw-r--r--src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java22
-rw-r--r--src/jogl/classes/javax/media/opengl/awt/GLCanvas.java4
-rw-r--r--src/jogl/classes/javax/media/opengl/awt/GLJPanel.java4
5 files changed, 30 insertions, 11 deletions
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")