GLAutoDrawable/AnimatorBase: Add ExclusiveContextThread (ECT) feature; AnimatorBase: Add setModeBits/MODE_EXPECT_AWT_RENDERING_THREAD; FPSAnimator: Make transactions deterministic.

ExclusiveContextThread (ECT) allows user to dedicate a GLContext to a given thread.
Only the ECT will be allowed to claim the GLContext, hence releasing must be done on the ECT itself.

The core feature is accessible via GLAutoDrawable, while it can be conveniently enabled and disabled
via an AnimatorBase implementation. The latter ensures it's being released on the ECT and waits for the result.

Note that ECT cannot be guaranteed to work correctly w/ native (heavyweight) AWT components
due to resource locking and AWT-EDT access. This is disabled in all new tests per default and
noted on the API doc.

Note: 'Animator transaction' == start(), stop(), pause(), resume().

- Add ExclusiveContextThread (ECT) feature
  - GLAutoDrawable NEW:
    - Thread setExclusiveContextThread(Thread t)
    - Thread getExclusiveContextThread()

  - AnimatorBase NEW:
    - Thread setExclusiveContext(Thread t)
    - boolean setExclusiveContext(boolean enable)
    - boolean isExclusiveContextEnabled()
    - Thread getExclusiveContextThread()

- AnimatorBase: Add setModeBits/MODE_EXPECT_AWT_RENDERING_THREAD
  Allows user to pre-determine whether AWT rendering is expected before starting the animator.
  If AWT is excluded, a more simple and transaction correct impl. will be used.

- FPSAnimator: Make transactions deterministic.
  FPSAnimator previously did not ensure whether a transaction was completed.
  A deterministic transaction is required to utilize ECT.
  FPSAnimator now uses same mechanism like Animator to ensure completeness,
  i.e. Condition and 'finishLifecycleAction(..)'. Both are moved to AnimatorBase.

Tested manually on Linux/NV, Linux/AMD, Windows/NV and OSX/NV.
  - All new tests validated correctness.
  - All new tests shows an performance increase of ~3x w/ single GLWindow, where multiple GLWindows don't show a perf. increase.

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);
   }