From 02104525a63aed70c51b825be0e8c83ed17cfa31 Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Sun, 27 Jan 2013 04:32:01 +0100 Subject: Animator: API doc cleanup, isPaused()==true if drawablesEmpty (Animator == FPSAnimator behavior), resume after add ifPaused() - GLAnimatorControl: Refine API doc - Animator.run(): - if( drawablesEmpt) { pausedIssued = true; } - Same behavior as FPSAnimator - AnimatorBase.add(..) - consider paused case if no drawablesEmpty, i.e. if ( isPaused() ) { resume(); } --- .../classes/com/jogamp/opengl/util/Animator.java | 3 ++ .../com/jogamp/opengl/util/AnimatorBase.java | 4 +- .../javax/media/opengl/GLAnimatorControl.java | 53 +++++++++++++++------- 3 files changed, 41 insertions(+), 19 deletions(-) diff --git a/src/jogl/classes/com/jogamp/opengl/util/Animator.java b/src/jogl/classes/com/jogamp/opengl/util/Animator.java index 10f43a0c1..22832f6bd 100644 --- a/src/jogl/classes/com/jogamp/opengl/util/Animator.java +++ b/src/jogl/classes/com/jogamp/opengl/util/Animator.java @@ -157,6 +157,9 @@ public class Animator extends AnimatorBase { // Pause; Also don't consume CPU unless there is work to be done and not paused boolean ectCleared = false; while (!stopIssued && (pauseIssued || drawablesEmpty)) { + if( drawablesEmpty ) { + pauseIssued = true; + } boolean wasPaused = pauseIssued; if (DEBUG) { System.err.println("Animator pause:" + Thread.currentThread() + ": " + toString()); diff --git a/src/jogl/classes/com/jogamp/opengl/util/AnimatorBase.java b/src/jogl/classes/com/jogamp/opengl/util/AnimatorBase.java index bda716e97..53a99b640 100644 --- a/src/jogl/classes/com/jogamp/opengl/util/AnimatorBase.java +++ b/src/jogl/classes/com/jogamp/opengl/util/AnimatorBase.java @@ -179,14 +179,14 @@ public abstract class AnimatorBase implements GLAnimatorControl { throw new IllegalArgumentException("Drawable already added to animator: "+this+", "+drawable); } initImpl(false); - boolean paused = pause(); + pause(); if( isStarted() ) { drawable.setExclusiveContextThread( exclusiveContext ? getExclusiveContextThread() : null ); // if already running .. } drawables.add(drawable); drawablesEmpty = drawables.size() == 0; drawable.setAnimator(this); - if(paused) { + if( isPaused() ) { // either paused by pause() above, or if previously drawablesEmpty==true resume(); } final Condition waitForAnimatingAndECTCondition = new Condition() { diff --git a/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java b/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java index 3052b924e..a72403eae 100644 --- a/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java +++ b/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java @@ -35,18 +35,18 @@ package javax.media.opengl; public interface GLAnimatorControl extends FPSCounter { /** - * Indicates whether this animator is running, ie. has been started and not stopped. + * Indicates whether this animator has been {@link #start() started}. * * @see #start() * @see #stop() + * @see #isPaused() * @see #pause() * @see #resume() */ boolean isStarted(); /** - * Indicates whether this animator is running and animating,
- * the latter is true if it has {@link GLAutoDrawable}s to render and is not paused. + * Indicates whether this animator {@link #isStarted() is started} and {@link #isPaused() is not paused}. * * @see #start() * @see #stop() @@ -56,7 +56,9 @@ public interface GLAnimatorControl extends FPSCounter { boolean isAnimating(); /** - * Indicates whether this animator is running and paused. + * Indicates whether this animator {@link #isStarted() is started} + * and either {@link #pause() manually paused} or paused + * automatically due to no {@link #add(GLAutoDrawable) added} {@link GLAutoDrawable}s. * * @see #start() * @see #stop() @@ -75,30 +77,38 @@ public interface GLAnimatorControl extends FPSCounter { /** * Starts this animator, if not running. - *

+ *

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

+ *

+ *

+ * Note that an animator w/o {@link #add(GLAutoDrawable) added drawables} + * will be paused automatically. + *

+ *

* If started, all counters (time, frames, ..) are reset to zero. + *

* * @return true is started due to this call, * otherwise false, ie started already or unable to start. * * @see #stop() * @see #isAnimating() + * @see #isPaused() * @see #getThread() */ boolean start(); /** * Stops this animator. - *

+ *

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

* * @return true is stopped due to this call, * otherwise false, ie not started or unable to stop. @@ -111,11 +121,12 @@ public interface GLAnimatorControl extends FPSCounter { /** * Pauses this animator. - *

+ *

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

* * @return false if not started, already paused or failed to pause, otherwise true * @@ -126,13 +137,15 @@ public interface GLAnimatorControl extends FPSCounter { /** * Resumes animation if paused. - *

+ *

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

+ *

+ *

* If resumed, all counters (time, frames, ..) are reset to zero. + *

* * @return false if not started, not paused or unable to resume, otherwise true * @@ -142,9 +155,11 @@ public interface GLAnimatorControl extends FPSCounter { boolean resume(); /** - * Adds a drawable to this animator's list of rendering drawables.
- * 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()}.
+ * Adds a drawable to this animator's list of rendering drawables. + *

+ * This allows the animator thread to become {@link #isAnimating() animating}, + * in case the first drawable is added and the animator {@link #isStarted() is started}. + *

* * @param drawable the drawable to be added * @throws IllegalArgumentException if drawable was already added to this animator @@ -152,11 +167,15 @@ public interface GLAnimatorControl extends FPSCounter { void add(GLAutoDrawable drawable); /** - * Removes a drawable from the animator's list of rendering drawables.
+ * Removes a drawable from the animator's list of rendering drawables. + *

* This method should get called in case a drawable becomes invalid, - * and will not be recovered.
- * 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.
+ * and will not be recovered. + *

+ *

+ * This allows the animator thread to become {@link #isAnimating() not animating}, + * in case the last drawable has been removed. + *

* * @param drawable the drawable to be removed * @throws IllegalArgumentException if drawable was not added to this animator -- cgit v1.2.3