From 4dfa5e34b5bbfc74dd9ca6ead89b23d12e7a1b01 Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Fri, 29 Aug 2014 01:31:03 +0200 Subject: GLSharedContextSetter: Fix API doc and all html references (fix URL and complete notes in all implementations) --- .../com/jogamp/opengl/GLAutoDrawableDelegate.java | 7 +++++++ .../classes/com/jogamp/opengl/swt/GLCanvas.java | 6 ++++++ .../classes/javax/media/opengl/GLDrawable.java | 5 +++-- .../media/opengl/GLOffscreenAutoDrawable.java | 6 ++++++ .../javax/media/opengl/GLSharedContextSetter.java | 22 +++++++++++++++------- .../classes/javax/media/opengl/awt/GLCanvas.java | 4 +++- .../classes/javax/media/opengl/awt/GLJPanel.java | 4 +++- 7 files changed, 43 insertions(+), 11 deletions(-) (limited to 'src/jogl') 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; *

* See example {@link com.jogamp.opengl.test.junit.jogl.acore.TestGLAutoDrawableDelegateNEWT TestGLAutoDrawableDelegateNEWT}. *

+ *

+ *

OpenGL Context Sharing
+ * To share a {@link GLContext} see the following note in the documentation overview: + * context sharing + * as well as {@link GLSharedContextSetter}. + *

*/ 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; *

* Implementation allows use of custom {@link GLCapabilities}. *

+ *

+ *

OpenGL Context Sharing
+ * To share a {@link GLContext} see the following note in the documentation overview: + * context sharing + * as well as {@link GLSharedContextSetter}. + *

*/ 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 share 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 - * context sharing. + * documentation + * context sharing + * as well as {@link GLSharedContextSetter}. *

*/ 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. *

+ *

+ *

OpenGL Context Sharing
+ * To share a {@link GLContext} see the following note in the documentation overview: + * context sharing + * as well as {@link GLSharedContextSetter}. + *

*/ 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. *

*

- * A master {@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 master {@link GLContext} is the {@link GLContext} which is created first. + * Subsequent shared {@link GLContext} w/ the master are referred as slave {@link GLContext}. + *

+ *

+ * Implementations of this interface control the slave's {@link GLContext} and {@link GLAutoDrawable} realization, + * i.e. the slave {@link GLAutoDrawable} will not be realized before their associated master. *

*

* 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. *

*

- * Be aware that the master {@link GLContext} and related resources - * shall not be destroyed before it's slave {@link GLContext} instances while they are using them.
- * 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!
+ * In general, destroying a master {@link GLContext} before their shared slaves + * 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 com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2NEWT3 and similar. *

*

+ * However, to avoid scenarios with buggy drivers, users may not destroy the + * master {@link GLContext} before its shared slave {@link GLContext} instances + * as long as they are using them.
+ * Otherwise the OpenGL driver may crash w/ SIGSEGV, due to using already destroyed shared resources, + * if not handling the pending destruction of the latter!
* Either proper lifecycle synchronization is implemented, e.g. by notifying the slaves about the loss of the shared resources, * or the slaves validate whether the resources are still valid. *

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; * 
  • sun.awt.noerasebackground=true
    • * * + *

    *

    OpenGL Context Sharing
    * To share a {@link GLContext} see the following note in the documentation overview: - * context sharing + * context sharing * as well as {@link GLSharedContextSetter}. + *

    */ @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.

    +

    OpenGL Context Sharing
    To share a {@link GLContext} see the following note in the documentation overview: - context sharing + context sharing as well as {@link GLSharedContextSetter}. +

    */ @SuppressWarnings("serial") -- cgit v1.2.3