Added support for letting a media know when it's about to be ticked for

the first time. This is the only indication that things are really
underway and it's a fine time to do things like play sounds that are
synchronized with that media and do other fun stuff.


git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@3084 542714f4-19e9-0310-aa3c-eee0fc999fb1

src/java/com/threerings/media/AbstractMedia.java

@@ -1,5 +1,5 @@
 //
-// $Id: AbstractMedia.java,v 1.10 2004/02/25 14:43:17 mdb Exp $
+// $Id: AbstractMedia.java,v 1.11 2004/08/18 01:33:32 mdb Exp $
 
 package com.threerings.media;
 
@@ -58,6 +58,8 @@ public abstract class AbstractMedia
      */
     public void fastForward (long timeDelta)
     {
+        // adjust our first tick stamp
+        _firstTick += timeDelta;
     }
 
     /**
@@ -189,7 +191,6 @@ public abstract class AbstractMedia
     protected final void init (AbstractMediaManager manager)
     {
         _mgr = manager;
-
         init();
     }
 
@@ -202,6 +203,23 @@ public abstract class AbstractMedia
     {
     }
 
+    /**
+     * Prior to the first call to {@link #tick} on an abstract media, this
+     * method is called by the {@link AbstractMediaManager}. It is called
+     * during the normal tick cycle, immediately prior to the first call
+     * to {@link #tick}.
+     *
+     * <p><em>Note:</em> It is imperative that
+     * <code>super.willStart()</code> is called by any entity that
+     * overrides this method because the {@link AbstractMediaManager}
+     * depends on the setting of the {@link #_firstTick} value to know
+     * whether or not to call this method.
+     */
+    protected void willStart (long tickStamp)
+    {
+        _firstTick = tickStamp;
+    }
+
     /**
      * Called by the media manager after the media is removed from service.
      * Derived classes may override this method, but should be sure to
@@ -267,4 +285,8 @@ public abstract class AbstractMedia
 
     /** Our observers. */
     protected ObserverList _observers = null;
+
+    /** The tick stamp associated with our first call to {@link #tick}.
+     * This is set up automatically in {@link #willStart}. */
+    protected long _firstTick;
 }

src/java/com/threerings/media/AbstractMediaManager.java

@@ -1,5 +1,5 @@
 //
-// $Id: AbstractMediaManager.java,v 1.11 2003/11/22 19:57:03 mdb Exp $
+// $Id: AbstractMediaManager.java,v 1.12 2004/08/18 01:33:32 mdb Exp $
 
 package com.threerings.media;
 
@@ -131,7 +131,7 @@ public abstract class AbstractMediaManager
         // we use _tickpos so that it can be adjusted if media is added or
         // removed during the tick dispatch
         for (_tickpos = 0; _tickpos < _media.size(); _tickpos++) {
-            ((AbstractMedia) _media.get(_tickpos)).tick(tickStamp);
+            tickMedia((AbstractMedia) _media.get(_tickpos), tickStamp);
         }
         _tickpos = -1;
     }
@@ -159,7 +159,7 @@ public abstract class AbstractMediaManager
             if (_tickpos == -1) {
                 // if we're done with our own call to tick(), we
                 // definitely need to tick this new media
-                media.tick(_tickStamp);
+                tickMedia(media, _tickStamp);
             } else if (ipos <= _tickpos) {
                 // otherwise, we're in the middle of our call to tick()
                 // and we only need to tick this guy if he's being
@@ -167,13 +167,22 @@ public abstract class AbstractMediaManager
                 // inserted after our current position, we'll get to him
                 // as part of this tick iteration)
                 _tickpos++;
-                media.tick(_tickStamp);
+                tickMedia(media, _tickStamp);
             }
         }
 
         return true;
     }
 
+    /** A helper function used to call {@link AbstractMedia#tick}. */
+    protected final void tickMedia (AbstractMedia media, long tickStamp)
+    {
+        if (media._firstTick == 0L) {
+            media.willStart(tickStamp);
+        }
+        media.tick(tickStamp);
+    }
+
     /**
      * Removes the specified media from this manager, return true on
      * success.

src/java/com/threerings/media/animation/Animation.java

@@ -1,10 +1,12 @@
 //
-// $Id: Animation.java,v 1.11 2004/02/25 14:43:17 mdb Exp $
+// $Id: Animation.java,v 1.12 2004/08/18 01:33:32 mdb Exp $
 
 package com.threerings.media.animation;
 
 import java.awt.Rectangle;
 
+import com.samskivert.util.ObserverList;
+
 import com.threerings.media.AbstractMedia;
 
 /**
@@ -42,13 +44,28 @@ public abstract class Animation extends AbstractMedia
         _finished = false;
     }
 
+    // documentation inherited
+    protected void willStart (long tickStamp)
+    {
+        super.willStart(tickStamp);
+        queueNotification(new AnimStartedOp(this, tickStamp));
+    }
+
+    /**
+     * Called when the animation is finished and the animation manager is
+     * about to remove it from service.
+     */
+    protected void willFinish (long tickStamp)
+    {
+        queueNotification(new AnimCompletedOp(this, tickStamp));
+    }
+
     /**
      * Called when the animation is finished and the animation manager has
      * removed it from service.
      */
-    protected void didFinish ()
+    protected void didFinish (long tickStamp)
     {
-        // nothing for now
     }
 
     /**
@@ -61,4 +78,38 @@ public abstract class Animation extends AbstractMedia
 
     /** Whether the animation is finished. */
     protected boolean _finished = false;
+
+    /** Used to dispatch {@link AnimationObserver#animationStarted}. */
+    protected static class AnimStartedOp implements ObserverList.ObserverOp
+    {
+        public AnimStartedOp (Animation anim, long when) {
+            _anim = anim;
+            _when = when;
+        }
+
+        public boolean apply (Object observer) {
+            ((AnimationObserver)observer).animationStarted(_anim, _when);
+            return true;
+        }
+
+        protected Animation _anim;
+        protected long _when;
+    }
+
+    /** Used to dispatch {@link AnimationObserver#animationCompleted}. */
+    protected static class AnimCompletedOp implements ObserverList.ObserverOp
+    {
+        public AnimCompletedOp (Animation anim, long when) {
+            _anim = anim;
+            _when = when;
+        }
+
+        public boolean apply (Object observer) {
+            ((AnimationObserver)observer).animationCompleted(_anim, _when);
+            return true;
+        }
+
+        protected Animation _anim;
+        protected long _when;
+    }
 }

src/java/com/threerings/media/animation/AnimationAdapter.java

@@ -1,5 +1,5 @@
 //
-// $Id: AnimationAdapter.java,v 1.1 2003/04/30 00:45:02 mdb Exp $
+// $Id: AnimationAdapter.java,v 1.2 2004/08/18 01:33:32 mdb Exp $
 
 package com.threerings.media.animation;
 
@@ -8,6 +8,11 @@ package com.threerings.media.animation;
  */
 public class AnimationAdapter implements AnimationObserver
 {
+    // documentation inherited from interface
+    public void animationStarted (Animation anim, long when)
+    {
+    }
+
     // documentation inherited from interface
     public void animationCompleted (Animation anim, long when)
     {

src/java/com/threerings/media/animation/AnimationManager.java

@@ -1,10 +1,8 @@
 //
-// $Id: AnimationManager.java,v 1.17 2004/02/25 14:43:17 mdb Exp $
+// $Id: AnimationManager.java,v 1.18 2004/08/18 01:33:32 mdb Exp $
 
 package com.threerings.media.animation;
 
-import com.samskivert.util.ObserverList;
-
 import com.threerings.media.AbstractMediaManager;
 import com.threerings.media.RegionManager;
 
@@ -56,27 +54,10 @@ public class AnimationManager extends AbstractMediaManager
             }
 
             // as the anim is finished, remove it and notify observers
-            anim.queueNotification(new AnimCompletedOp(anim, tickStamp));
+            anim.willFinish(tickStamp);
             unregisterAnimation(anim);
-            anim.didFinish();
+            anim.didFinish(tickStamp);
             // Log.info("Removed finished animation " + anim + ".");
         }
     }
-
-    /** Used to dispatch {@link AnimationObserver#animationCompleted}. */
-    protected static class AnimCompletedOp implements ObserverList.ObserverOp
-    {
-        public AnimCompletedOp (Animation anim, long when) {
-            _anim = anim;
-            _when = when;
-        }
-
-        public boolean apply (Object observer) {
-            ((AnimationObserver)observer).animationCompleted(_anim, _when);
-            return true;
-        }
-
-        protected Animation _anim;
-        protected long _when;
-    }
 }

src/java/com/threerings/media/animation/AnimationObserver.java

@@ -1,5 +1,5 @@
 //
-// $Id: AnimationObserver.java,v 1.2 2003/04/30 00:45:02 mdb Exp $
+// $Id: AnimationObserver.java,v 1.3 2004/08/18 01:33:32 mdb Exp $
 
 package com.threerings.media.animation;
 
@@ -9,6 +9,11 @@ package com.threerings.media.animation;
  */
 public interface AnimationObserver
 {
+    /**
+     * Called the first time this animation is ticked.
+     */
+    public void animationStarted (Animation anim, long when);
+
     /**
      * Called when the observed animation has completed.
      */

src/java/com/threerings/media/animation/AnimationSequencer.java

@@ -1,5 +1,5 @@
 //
-// $Id: AnimationSequencer.java,v 1.13 2003/04/30 00:45:02 mdb Exp $
+// $Id: AnimationSequencer.java,v 1.14 2004/08/18 01:33:32 mdb Exp $
 
 package com.threerings.media.animation;
 
@@ -149,8 +149,7 @@ public abstract class AnimationSequencer extends Animation
      */
     protected abstract void startAnimation (Animation anim, long tickStamp);
 
-    protected class AnimRecord
+    protected class AnimRecord extends AnimationAdapter
-        implements AnimationObserver
     {
         public AnimRecord (Animation anim, long delta, AnimRecord trigger,
                            Runnable completionAction) {

src/java/com/threerings/media/animation/AnimationWaiter.java

@@ -1,5 +1,5 @@
 //
-// $Id: AnimationWaiter.java,v 1.3 2003/04/30 00:45:02 mdb Exp $
+// $Id: AnimationWaiter.java,v 1.4 2004/08/18 01:33:32 mdb Exp $
 
 package com.threerings.media.animation;
 
@@ -34,6 +34,11 @@ public abstract class AnimationWaiter
         }
     }
 
+    // documentation inherited from interface
+    public void animationStarted (Animation anim, long when)
+    {
+    }
+
     // documentation inherited from interface
     public void animationCompleted (Animation anim, long when)
     {

src/java/com/threerings/media/animation/SpriteAnimation.java

@@ -1,5 +1,5 @@
 //
-// $Id: SpriteAnimation.java,v 1.3 2003/04/30 00:45:02 mdb Exp $
+// $Id: SpriteAnimation.java,v 1.4 2004/08/18 01:33:32 mdb Exp $
 
 package com.threerings.media.animation;
 
@@ -65,9 +65,9 @@ public class SpriteAnimation extends Animation
     }
 
     // documentation inherited
-    protected void didFinish ()
+    protected void didFinish (long tickStamp)
     {
-        super.didFinish();
+        super.didFinish(tickStamp);
 
         _spritemgr.removeSprite(_sprite);
         _sprite = null;