NEWT: Animator API Change - Changed Lifecycle of Display/Screen (part 4)

Change GLAutoDrawable interface: setAnimator(Thread) -> setAnimator(GLAnimatorControl)
to minimize the setAnimator(..) calls and
to allow fine grained control over the animation, ie in case of reparenting
where the animation shall pause while changing the window(s).

Introducing GLAnimatorControl interface:
    - abstract class AnimatorBase implements GLAnimatorControl
    - class Animator extends AnimatorBase
    - class FPSAnimator extends AnimatorBase
This also changes FPSAnimator, since it is no more derived from Animator,
use it's superclass or superinterface instead.

+++

- Fix GLJPanel.paintComponent(): Don't issue reshape/display
  in case an external animator thread is animating.

- Fix: Documentation [API]

5 files changed, 238 insertions, 63 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java b/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java
new file mode 100644
index 000000000..13788fe53
--- /dev/null
+++ b/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java
@@ -0,0 +1,180 @@
+/**
+ * Copyright 2010 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+
+package javax.media.opengl;
+
+/**
+ * An animator control interface, 
+ * which implementation may drive a {@link javax.media.opengl.GLAutoDrawable} animation.
+ * <P>
+ * Note that the methods {@link #start()}, {@link #stop()}, {@link #pause()} and {@link #resume()}
+ * shall be implemented to fail-fast, ie {@link #start()} fails if not started, etc.
+ * This way an implementation can find implementation errors faster.
+ */
+public interface GLAnimatorControl {
+
+    /**
+     * @return Time of the first display call in milliseconds.
+     *         This value is reset if started or resumed.
+     *
+     * @see #start()
+     * @see #resume()
+     */
+    long getStartTime();
+
+    /**
+     * @return Time of the last display call in milliseconds.
+     *         This value is reset if started or resumed.
+     *
+     * @see #start()
+     * @see #resume()
+     */
+    long getCurrentTime();
+
+    /**
+     * @return Duration <code>getCurrentTime() - getStartTime()</code>.
+     *
+     * @see #getStartTime()
+     * @see #getCurrentTime()
+     */
+    long getDuration();
+
+
+    /**
+     * @return Number of frames issued to all registered GLAutoDrawables registered
+     */
+    /**
+     * @return Number of frame cycles displayed by all registered {@link javax.media.opengl.GLAutoDrawable}
+     *         since the first display call, ie <code>getStartTime()</code>.
+     *         This value is reset if started or resumed.
+     *
+     * @see #start()
+     * @see #resume()
+     */
+    int getTotalFrames();
+
+    /**
+     * Indicates whether this animator is currently running, ie started.
+     *
+     * @see #start()
+     * @see #stop()
+     * @see #pause()
+     * @see #resume()
+     */
+    boolean isStarted();
+
+    /**
+     * Indicates whether this animator is currently running and not paused.
+     *
+     * @see #start()
+     * @see #stop()
+     * @see #pause()
+     * @see #resume()
+     */
+    boolean isAnimating();
+
+    /**
+     * Indicates whether this animator is currently running and paused.
+     *
+     * @see #start()
+     * @see #stop()
+     * @see #pause()
+     * @see #resume()
+     */
+    boolean isPaused();
+
+    /**
+     * @return The animation thread if started, ie running.
+     *
+     * @see #start()
+     * @see #stop()
+     */
+    Thread getThread();
+
+    /**
+     * Starts this animator, if not running.
+     * <P>
+     * In most situations this method blocks until
+     * completion, except when called from the animation thread itself
+     * or in some cases from an implementation-internal thread like the
+     * AWT event queue thread.
+     * <P>
+     * If started, all counters (time, frames, ..) are reset to zero.
+     *
+     * @see #stop()
+     * @see #isAnimating()
+     * @see #getThread()
+     * @throws GLException if started and animating already
+     */
+    void start();
+
+    /**
+     * Stops this animator.
+     * <P>
+     * In most situations this method blocks until
+     * completion, except when called from the animation thread itself
+     * or in some cases from an implementation-internal thread like the
+     * AWT event queue thread.
+     *
+     * @see #start()
+     * @see #isAnimating()
+     * @see #getThread()
+     * @throws GLException if not started or not animating
+     */
+    void stop();
+
+    /**
+     * Pauses this animator.
+     * <P>
+     * In most situations this method blocks until
+     * completion, except when called from the animation thread itself
+     * or in some cases from an implementation-internal thread like the
+     * AWT event queue thread.
+     *
+     * @see #resume()
+     * @see #isAnimating()
+     * @throws GLException if not started or not animating or already paused
+     */
+    void pause();
+
+    /**
+     * Resumes animation if paused.
+     * <P>
+     * In most situations this method blocks until
+     * completion, except when called from the animation thread itself
+     * or in some cases from an implementation-internal thread like the
+     * AWT event queue thread.
+     * <P>
+     * If resumed, all counters (time, frames, ..) are reset to zero.
+     *
+     * @see #pause()
+     * @see #isAnimating()
+     * @throws GLException if not started or not paused
+     */
+    void resume();
+}
diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
index 10a32fd1d..bc2f633ce 100644
--- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright (c) 2010 JogAmp Community. All rights reserved.
  * 
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
@@ -115,17 +116,6 @@ public interface GLAutoDrawable extends GLDrawable {
     * where you drag the window to another monitor. */
   public static final boolean SCREEN_CHANGE_ACTION_ENABLED = Debug.getBooleanProperty("jogl.screenchange.action", true, AccessController.getContext());
 
-  /** FIXME:
-  ** Invalid state, the resources are not yet ready to render. *
-  public static final int STATE_INVALID = 0;
-
-  ** Valid state, all resources are ready to render, 
-      and all registered {@link GLEventListener#init init(..)} are called. *
-  public static final int STATE_VALID = 1;
-
-  ** Destroying state, currently executing the {@link #destroy()} method. *
-  public static final int STATE_DESTROYING = 2; */
-
   /**
    * Returns the context associated with this drawable. The returned
    * context will be synchronized.
@@ -163,58 +153,55 @@ public interface GLAutoDrawable extends GLDrawable {
 
   /**
    * <p>
-   * Indicates whether a running animator thread is periodically issuing {@link #display()} calls or not.</p><br>
+   * 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>
    * <p>
    * This method shall be called by an animator implementation only,<br>
-   * e.g. {@link com.jogamp.opengl.util.Animator#start()}, passing the animator thread,<br>
-   * and {@link com.jogamp.opengl.util.Animator#stop()}, passing <code>null</code>.</p><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>
    * <p>
    * Impacts {@link #display()} and {@link #invoke(boolean, GLRunnable)} semantics.</p><br>
    *
-   * @param animator <code>null</code> reference indicates no running animator thread 
-   *                 issues {@link #display()} calls on this <code>GLAutoDrawable</code>,<br>
-   *                 a valid reference indicates a running animator thread 
-   *                 periodically issuing {@link #display()} calls.
+   * @param animator <code>null</code> reference indicates no animator is using
+   *                 this <code>GLAutoDrawable</code>,<br>
+   *                 a valid reference indicates an animator is using this <code>GLAutoDrawable</code>.
    *
-   * @throws GLException if a running animator thread is already registered and you try to register a different one without unregistering the previous one.
+   * @throws GLException if an animator is already registered.
    * @see #display()
    * @see #invoke(boolean, GLRunnable)
+   * @see javax.media.opengl.GLAnimatorControl
    */ 
-  public void setAnimator(Thread animator) throws GLException;
+  public abstract void setAnimator(GLAnimatorControl animatorControl) throws GLException;
 
   /**
-   * @return the value of the registered animator thread
+   * @return the registered {@link javax.media.opengl.GLAnimatorControl} implementation, using this <code>GLAutoDrawable</code>.
    *
-   * @see #setAnimator(Thread)
+   * @see #setAnimator(javax.media.opengl.GLAnimatorControl)
+   * @see javax.media.opengl.GLAnimatorControl
    */
-  public Thread getAnimator();
+  public GLAnimatorControl getAnimator();
 
   /** 
    * <p>
    * Enqueues a one-shot {@link javax.media.opengl.GLRunnable},
-   * which will be executed with the next {@link #display()} call.</p><br>
+   * which will be executed with the next {@link #display()} call.</p>
    * <p>
-   * If {@link #setAnimator(Thread)} has not registered no running animator thread, the default,<br>
+   * If a {@link javax.media.opengl.GLAnimatorControl} is registered, or if it's not animating, the default situation,<br>
    * or if the current thread is the animator thread,<br>
-   * a {@link #display()} call has to be issued after enqueueing the <code>GLRunnable</code>.<br>
-   * No extra synchronization must be performed in case <code>wait</code> is true, since it is executed in the current thread.</p><br>
+   * a {@link #display()} call has to be issued after enqueue the <code>GLRunnable</code>.<br>
+   * No extra synchronization must be performed in case <code>wait</code> is true, since it is executed in the current thread.</p>
    * <p>
-   * If {@link #setAnimator(Thread)} has registered a valid animator thread,<br>
-   * no call of {@link #display()} must be issued, since the animator thread performs it.<br>
-   * If <code>wait</code> is true, the implementation must wait until the <code>GLRunnable</code> is excecuted.</p><br>
+   * If {@link javax.media.opengl.GLAnimatorControl} is registered and is animating,<br>
+   * no call of {@link #display()} must be issued, since the animator thread will performs it.<br>
+   * If <code>wait</code> is true, the implementation must wait until the <code>GLRunnable</code> is executed.<br>
+   * </p><br>
    *
-   * @see #setAnimator(Thread)
+   * @see #setAnimator(javax.media.opengl.GLAnimatorControl)
    * @see #display()
    * @see javax.media.opengl.GLRunnable
    */   
   public void invoke(boolean wait, GLRunnable glRunnable);
 
-  /** FIXME: Returns the current state, 
-      {@link #STATE_INVALID}, {@link #STATE_VALID} or {@link #STATE_DESTROYING}.
-      Tool to determine, e.g. if a {@link GLEventListener#dispose dispose(..)}
-      event is send in the context of the destruction of this GLAutoDrawable.
-  public int getCurrentState(); */
-
   /** Destroys all resources associated with this GLAutoDrawable,
       inclusive the GLContext.
       If a window is attached to it's implementation, it shall be closed.
@@ -236,14 +223,13 @@ public interface GLAutoDrawable extends GLDrawable {
    *          enqueued via {@link #invoke(boolean, GLRunnable)}.</li>
    * </ul></p>
    * <p> 
-   * Called automatically by the
-   * window system toolkit upon receiving a repaint() request, 
-   * except a running animator thread is registered with {@link #setAnimator(Thread)}.</p> <br>
-   * <p> 
-   * Maybe called periodically by a running animator thread,<br>
-   * which must register itself with {@link #setAnimator(Thread)}.</p> <br>
+   * May be called periodically by a running {@link javax.media.opengl.GLAnimatorControl} implementation,<br>
+   * which must register itself with {@link #setAnimator(javax.media.opengl.GLAnimatorControl)}.</p>
+   * <p>
+   * Called automatically by the window system toolkit upon receiving a repaint() request, <br>
+   * except an {@link javax.media.opengl.GLAnimatorControl} implementation {@link javax.media.opengl.GLAnimatorControl#isAnimating()}.</p>
    * <p> 
-   * This routine may be called manually for better control over the
+   * This routine may also be called manually for better control over the
    * rendering process. It is legal to call another GLAutoDrawable's
    * display method from within the {@link GLEventListener#display
    * display(..)} callback.</p>
@@ -254,7 +240,7 @@ public interface GLAutoDrawable extends GLDrawable {
    * actual {@link GLEventListener#display display(..)} calls,
    * in case this has not been done yet.</p>
    *
-   * @see #setAnimator(Thread)
+   * @see #setAnimator(javax.media.opengl.GLAnimatorControl)
    */
   public void display();
 
diff --git a/src/jogl/classes/javax/media/opengl/GLRunnable.java b/src/jogl/classes/javax/media/opengl/GLRunnable.java
index 9d8345fb4..de0f5df48 100644
--- a/src/jogl/classes/javax/media/opengl/GLRunnable.java
+++ b/src/jogl/classes/javax/media/opengl/GLRunnable.java
@@ -28,16 +28,20 @@
  
 package javax.media.opengl;
 
-/** <p> Declares one-shot OpenGL commands, which client code can use to manage OpenGL
-    commands into a {@link GLAutoDrawable}. At the time any of these
-    methods is called, the drawable has made its associated OpenGL
-    context current, so it is valid to make OpenGL calls.<br></p>
-    <p> A GLRunnable maybe used to inject OpenGL commands via I/O event listener,
-    via {@link GLAutoDrawable#invoke(boolean, GLRunnable)}.</p>
-  */
+/**
+ * <p>
+ * Declares one-shot OpenGL commands usable for injection into a {@link GLAutoDrawable},<br>
+ * via {@link GLAutoDrawable#invoke(boolean, javax.media.opengl.GLRunnable)}.<br>
+ * {@link GLAutoDrawable} executes these commands within it's {@link GLAutoDrawable#display()}
+ * method while the OpenGL context is current.<br>
+ * <p>
+ * This might be useful to inject OpenGL commands from an I/O event listener.
+ */
 public interface GLRunnable { 
-  /** Called by the drawable to initiate one-shot OpenGL commands by the
-      client, like {@link GLEventListener#display(GLAutoDrawable)}. */
-  public void run(GLAutoDrawable drawable);
+    /**
+     * Called by the drawable to initiate one-shot OpenGL commands by the
+     * client, like {@link GLEventListener#display(GLAutoDrawable)}.
+     */
+    void run(GLAutoDrawable drawable);
 }
 
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
index f150b2507..705b12783 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLCanvas.java
@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright (c) 2010 JogAmp Community. All rights reserved.
  * 
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
@@ -377,8 +378,7 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable {
                    (int) ((getHeight() + bounds.getHeight()) / 2));
       return;
     }
-
-    if( null == getAnimator() ) {
+    if( this.drawableHelper.isExternalAnimatorAnimating() ) {
         display();
     }
   }
@@ -494,11 +494,11 @@ public class GLCanvas extends Canvas implements AWTGLAutoDrawable {
     drawableHelper.removeGLEventListener(listener);
   }
 
-  public void setAnimator(Thread animator) {
-    drawableHelper.setAnimator(animator);
+  public void setAnimator(GLAnimatorControl animatorControl) {
+    drawableHelper.setAnimator(animatorControl);
   }
 
-  public Thread getAnimator() {
+  public GLAnimatorControl getAnimator() {
     return drawableHelper.getAnimator();
   }
 
diff --git a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
index d0d97fe31..72b782f9a 100644
--- a/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
+++ b/src/jogl/classes/javax/media/opengl/awt/GLJPanel.java
@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved.
+ * Copyright (c) 2010 JogAmp Community. All rights reserved.
  * 
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
@@ -286,6 +287,10 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable {
       return;
     }
 
+    if ( drawableHelper.isExternalAnimatorAnimating() ) {
+        return;
+    }
+
     if (backend == null || !isInitialized) {
       createAndInitializeBackend();
     }
@@ -380,11 +385,11 @@ public class GLJPanel extends JPanel implements AWTGLAutoDrawable {
     drawableHelper.removeGLEventListener(listener);
   }
 
-  public void setAnimator(Thread animator) {
-    drawableHelper.setAnimator(animator);
+  public void setAnimator(GLAnimatorControl animatorControl) {
+    drawableHelper.setAnimator(animatorControl);
   }
 
-  public Thread getAnimator() {
+  public GLAnimatorControl getAnimator() {
     return drawableHelper.getAnimator();
   }