diff options
Diffstat (limited to 'src/jogl/classes/javax/media/opengl')
5 files changed, 85 insertions, 9 deletions
diff --git a/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java b/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java index 83e9e22c4..3052b924e 100644 --- a/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java +++ b/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java @@ -117,7 +117,7 @@ public interface GLAnimatorControl extends FPSCounter { * or in some cases from an implementation-internal thread like the * AWT event queue thread. * - * @return false if if not started or already paused, otherwise true + * @return false if not started, already paused or failed to pause, otherwise true * * @see #resume() * @see #isAnimating() @@ -134,7 +134,7 @@ public interface GLAnimatorControl extends FPSCounter { * <P> * If resumed, all counters (time, frames, ..) are reset to zero. * - * @return false if if not started or not paused, otherwise true + * @return false if not started, not paused or unable to resume, otherwise true * * @see #pause() * @see #isAnimating() @@ -142,13 +142,24 @@ public interface GLAnimatorControl extends FPSCounter { boolean resume(); /** + * Adds a drawable to this animator's list of rendering drawables.<br> + * This allows the animator thread to become active, i.e. {@link #isAnimating()}==true, + * in case the first drawable is added and {@link #isStarted()} and not {@link #isPaused()}.<br> + * + * @param drawable the drawable to be added + * @throws IllegalArgumentException if drawable was already added to this animator + */ + void add(GLAutoDrawable drawable); + + /** * Removes a drawable from the animator's list of rendering drawables.<br> * This method should get called in case a drawable becomes invalid, * and will not be recovered.<br> - * This allows the animator thread to become idle in case the last drawable - * has reached it's end of life.<br> + * This allows the animator thread to become idle, i.e. {@link #isAnimating()}==false, + * in case the last drawable has reached it's end of life.<br> * - * @param drawable the to be removed drawable + * @param drawable the drawable to be removed + * @throws IllegalArgumentException if drawable was not added to this animator */ void remove(GLAutoDrawable drawable); } diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java index 0f487f463..a7db3f3fd 100644 --- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java +++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java @@ -311,13 +311,13 @@ public interface GLAutoDrawable extends GLDrawable { public GLEventListener removeGLEventListener(GLEventListener listener); /** - * <p> * Registers the usage of an animator, an {@link javax.media.opengl.GLAnimatorControl} implementation. - * The animator will be queried whether it's animating, ie periodically issuing {@link #display()} calls or not.</p><br> + * The animator will be queried whether it's animating, ie periodically issuing {@link #display()} calls or not. * <p> * This method shall be called by an animator implementation only,<br> * e.g. {@link com.jogamp.opengl.util.Animator#add(javax.media.opengl.GLAutoDrawable)}, passing it's control implementation,<br> - * and {@link com.jogamp.opengl.util.Animator#remove(javax.media.opengl.GLAutoDrawable)}, passing <code>null</code>.</p><br> + * and {@link com.jogamp.opengl.util.Animator#remove(javax.media.opengl.GLAutoDrawable)}, passing <code>null</code>. + * </p> * <p> * Impacts {@link #display()} and {@link #invoke(boolean, GLRunnable)} semantics.</p><br> * @@ -341,6 +341,45 @@ public interface GLAutoDrawable extends GLDrawable { public GLAnimatorControl getAnimator(); /** + * Dedicates this instance's {@link GLContext} to the given thread.<br/> + * The thread will exclusively claim the {@link GLContext} via {@link #display()} and not release it + * until {@link #destroy()} or <code>setExclusiveContextThread(null)</code> has been called. + * <p> + * Default non-exclusive behavior is <i>requested</i> via <code>setExclusiveContextThread(null)</code>, + * which will cause the next call of {@link #display()} on the exclusive thread to + * release the {@link GLContext}. Only after it's async release, {@link #getExclusiveContextThread()} + * will return <code>null</code>. + * </p> + * <p> + * To release a previous made exclusive thread, a user issues <code>setExclusiveContextThread(null)</code> + * and may poll {@link #getExclusiveContextThread()} until it returns <code>null</code>, + * <i>while</i> the exclusive thread is still running. + * </p> + * <p> + * Note: Setting a new exclusive thread without properly releasing a previous one + * will throw an GLException. + * </p> + * <p> + * Note: Utilizing this feature w/ AWT could lead to an AWT-EDT deadlock, depending on the AWT implementation. + * Hence it is advised not to use it with native AWT GLAutoDrawable like GLCanvas. + * </p> + * <p> + * One scenario could be to dedicate the context to the {@link GLAnimatorControl#getThread() animator thread} + * and spare redundant context switches, see {@link com.jogamp.opengl.util.AnimatorBase#setExclusiveContext(boolean)}. + * </p> + * @param t the exclusive thread to claim the context, or <code>null</code> for default operation. + * @return previous exclusive context thread + * @throws GLException If an exclusive thread is still active but a new one is attempted to be set + * @see com.jogamp.opengl.util.AnimatorBase#setExclusiveContext(boolean) + */ + public Thread setExclusiveContextThread(Thread t) throws GLException; + + /** + * @see #setExclusiveContextThread(Thread) + */ + public Thread getExclusiveContextThread(); + + /** * Enqueues a one-shot {@link GLRunnable}, * which will be executed within the next {@link #display()} call * after all registered {@link GLEventListener}s diff --git a/src/jogl/classes/javax/media/opengl/GLContext.java b/src/jogl/classes/javax/media/opengl/GLContext.java index 235003c38..461d481a8 100644 --- a/src/jogl/classes/javax/media/opengl/GLContext.java +++ b/src/jogl/classes/javax/media/opengl/GLContext.java @@ -276,6 +276,9 @@ public abstract class GLContext { /** * Makes this GLContext current on the calling thread. * <p> + * Recursive call to {@link #makeCurrent()} and hence {@link #release()} are supported. + * </p> + * <p> * There are two return values that indicate success and one that * indicates failure. * </p> @@ -288,7 +291,7 @@ public abstract class GLContext { * </p> * <p> * A return value of {@link #CONTEXT_CURRENT} indicates that the context has - * been made currrent, with its previous state restored. + * been made current, with its previous state restored. * </p> * <p> * If the context could not be made current (for example, because @@ -320,6 +323,9 @@ public abstract class GLContext { /** * Releases control of this GLContext from the current thread. * <p> + * Recursive call to {@link #release()} and hence {@link #makeCurrent()} are supported. + * </p> + * <p> * The drawable's surface is being unlocked at exit, * assumed to be locked by {@link #makeCurrent()}. * </p> diff --git a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java index 2f7fef9be..2de86b545 100644 --- a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java +++ b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java @@ -742,6 +742,16 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable, WindowClosing } @Override + public final Thread setExclusiveContextThread(Thread t) throws GLException { + return helper.setExclusiveContextThread(t, context); + } + + @Override + public final Thread getExclusiveContextThread() { + return helper.getExclusiveContextThread(); + } + + @Override public boolean invoke(boolean wait, GLRunnable glRunnable) { return helper.invoke(this, wait, glRunnable); } diff --git a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java index 23dedaa66..664edb996 100644 --- a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java +++ b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java @@ -474,6 +474,16 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable, WindowClosing } @Override + public final Thread setExclusiveContextThread(Thread t) throws GLException { + return helper.setExclusiveContextThread(t, getContext()); + } + + @Override + public final Thread getExclusiveContextThread() { + return helper.getExclusiveContextThread(); + } + + @Override public boolean invoke(boolean wait, GLRunnable glRunnable) { return helper.invoke(this, wait, glRunnable); } |