diff options
Diffstat (limited to 'src')
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; |