diff options
Diffstat (limited to 'src/jogl/classes/javax/media/opengl')
4 files changed, 34 insertions, 13 deletions
diff --git a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java index 817dff8ad..98eb9bdde 100644 --- a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java +++ b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java @@ -675,8 +675,8 @@ public abstract class GLDrawableFactory { * The GLPbuffer drawable is realized and initialized eagerly. * </p> * - * See the note in the overview documentation on - * <a href="../../../spec-summary.html#SHARING">context sharing</a>. + * See the note in the overview documentation in {@link GLSharedContextSetter} and on + * <a href="../../../spec-overview.html#SHARING">context sharing</a>. * * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be <code>null</code> for the platform's default device. * @param capabilities the requested capabilities diff --git a/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java b/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java index d5a10931e..8c2311329 100644 --- a/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java +++ b/src/jogl/classes/javax/media/opengl/GLSharedContextSetter.java @@ -31,7 +31,29 @@ package javax.media.opengl; /** * Adds capabilities to set a shared {@link GLContext} directly or via an {@link GLAutoDrawable}. * <p> - * Warning: Don't reference this interface directly, since it may end up in {@link GLAutoDrawable} + * Sharing of server-side OpenGL objects such as buffer objects, e.g. VBOs, + * 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}. + * </p> + * <h5><a name="driverstabilityconstraints">Driver stability constraints</a></h5> + * <p> + * Be aware that the <i>master</i> {@link GLContext} and related resources, i.e. the {@link GLAutoDrawable}, + * <i>shall not</i> be destroyed before it's <i>slave</i> {@link GLContext} instances.<br> + * Otherwise the OpenGL driver implementation may crash w/ SIGSEGV if shared resources are still used!<br> + * Note that this is not specified within OpenGL and <i>should work</i>, however, some drivers + * do not seem to handle this situation well, i.e. they do not postpone resource destruction + * until the last reference is removed.<br> + * Since pending destruction of {@link GLContext} and it's {@link GLDrawable} is complex and nearly impossible + * for us at the top level, considering the different windowing systems and {@link GLAutoDrawable} types, + * the user shall take care of proper destruction order. + * </p> + * <p> + * Users may use a {@link GLDrawableFactory#createDummyDrawable(javax.media.nativewindow.AbstractGraphicsDevice, boolean, GLProfile) dummy} + * {@link GLDrawable} and it's {@link GLContext} as the <i>master</i> of all shared <i>slave</i> {@link GLContext}. + * Same constraints as above apply, i.e. it shall be destroyed <i>after</i> all shared slaves. * </p> */ public interface GLSharedContextSetter extends GLAutoDrawable { @@ -46,6 +68,9 @@ public interface GLSharedContextSetter extends GLAutoDrawable { * A set <i>sharedContext</i> will block context creation, i.e. {@link GLAutoDrawable#initialization GLAutoDrawable initialization}, * as long it is not {@link GLContext#isCreated() created natively}. * </p> + * <p> + * See <a href="#driverstabilityconstraints">driver stability constraints</a>. + * </p> * * @param sharedContext The OpenGL context to be shared by this {@link GLAutoDrawable}'s {@link GLContext}. * @throws IllegalStateException if a {@link #setSharedContext(GLContext) shared GLContext} @@ -67,6 +92,9 @@ public interface GLSharedContextSetter extends GLAutoDrawable { * as long it's {@link GLContext} is <code>null</code> * or has not been {@link GLContext#isCreated() created natively}. * </p> + * <p> + * See <a href="#driverstabilityconstraints">driver stability constraints</a>. + * </p> * * @param sharedContext The GLAutoDrawable, which OpenGL context shall be shared by this {@link GLAutoDrawable}'s {@link GLContext}. * @throws IllegalStateException if a {@link #setSharedContext(GLContext) shared GLContext} diff --git a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java index c2d8e0535..439a5bd30 100644 --- a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java +++ b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java @@ -246,7 +246,7 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable, WindowClosing textures, display lists and other OpenGL state, and may be null if sharing is not desired. See the note in the overview documentation on <a - href="../../../spec-summary.html#SHARING">context + href="../../../spec-overview.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 diff --git a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java index faf00c19a..8b1467268 100644 --- a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java +++ b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java @@ -286,14 +286,7 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing default set of capabilities is used. The GLCapabilitiesChooser specifies the algorithm for selecting one of the available GLCapabilities for the component; a DefaultGLCapabilitesChooser - 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. See the note in the overview documentation on - <a href="../../../spec-summary.html#SHARING">context sharing</a>. - <P> - Note: Sharing cannot be enabled using J2D OpenGL FBO sharing, - since J2D GL Context must be shared and we can only share one context. + is used if null is passed for this argument. * @throws GLException if no GLCapabilities are given and no default profile is available for the default desktop device. */ public GLJPanel(GLCapabilitiesImmutable userCapsRequest, GLCapabilitiesChooser chooser) @@ -311,7 +304,7 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing 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. See the note in the overview documentation on - <a href="../../../spec-summary.html#SHARING">context sharing</a>. + <a href="../../../spec-overview.html#SHARING">context sharing</a>. <P> Note: Sharing cannot be enabled using J2D OpenGL FBO sharing, since J2D GL Context must be shared and we can only share one context. |