---

c:/home/kevn/src/animaniac/ani/KeyFrame/KeyFramer.h

Go to the documentation of this file.

/*************** <auto-copyright.pl BEGIN do not edit this line> **************
 *
 * Animaniac is (C) Copyright 2000,2001 Kevin Meinert
 *
 * Original Authors:
 *   Kevin Meinert
 *
 *
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 *
 * -----------------------------------------------------------------
 * File:          $RCSfile: KeyFramer.h,v $
 * Date modified: $Date: 2002/05/06 05:18:22 $
 * Version:       $Revision: 1.5 $
 * -----------------------------------------------------------------
 *
 *************** <auto-copyright.pl END do not edit this line> ***************/


// NOTE: for best results, read this file using an editor that supports
// color syntax highlighting.  (i.e. nedit, gvim, visual studio, visual 
// slick edit)

#ifndef ANIMATION_KEY_FRAMER
#define ANIMATION_KEY_FRAMER



#include <map>
#include <assert.h>
#include <gmtl/Vec.h>
#include <gmtl/VecOps.h>
#include <gmtl/Quat.h>
#include <gmtl/QuatOps.h>
#include <gmtl/Matrix.h>
#include <gmtl/MatrixOps.h>

namespace ani
{
   // example to create a new KeyFramer:
   //
   //     KeyFramer<PosQuatKey> keyFramer;
   //
   // It is morphable to any key type, currently only PosQuat key is available
   // but I'd like to add bones or polygonal mesh sometime soon.  
   template <class _keyType>
   class KeyFramer
   {
   public:
      //: default constructor
      KeyFramer()
      {
         // initial state.
         this->clear();
         this->stop();
      }
      
      //: play forward
      // resume from a pause(), restart from a stop(), 
      // change directions from an rplay()
      void play() 
      {
         mIsPlaying = true;
         mReverse = false;
      }

      //: play backward
      // resume from a pause(), restart from a stop(), 
      // change directions from a play()
      void rplay()
      {
         mIsPlaying = true;
         mReverse = true;
      }

      //: pause to stop, play or rplay to resume
      void pause()
      {
         mIsPlaying = false;
      }

      //: jump to begin
      void rewind()
      {
         mCurrentTime = this->begintime();
         mFutureTime = this->begintime();
      }
      
      //: jump to end
      void fastforward()
      {
         mCurrentTime = this->length();
         mFutureTime = this->length();
      }
      
      //: stop anim, resetting to beginning.
      void stop()
      {
         mIsPlaying = false;
         mCurrentTime = this->begintime();
         mFutureTime = this->begintime();
         mLoopsLeft = mLoops;
      }
      
      void clear()
      {
         mKeys.clear();
         mPlayFactor = 1.0f;  // 1X (normal play) is default
         mLoops = 1;          // loop once is default
         mCurrentTime = this->begintime();
         mFutureTime = this->begintime();  
         mLoopsLeft = 1;
      }  
          
      //: update func.
      // take one time-step of the animation
      // advances one frame of the animation, 
      // give the current time between frames in seconds...
      void step( float timeOfKey )
      {
         if (mIsPlaying)
         {         
            mCurrentTime = mFutureTime;
            
            // if time is out of bounds,
            if (mCurrentTime > this->length() || mCurrentTime < 0)
            {
               // if we're counting loops, then decrement counter.
               if (mLoopsLeft > 0)
                  --mLoopsLeft;

               // and there are loops left, then rewind
               if (mLoopsLeft != 0)
               {
                  if (mReverse == false)
                     this->rewind();
                  else
                     this->fastforward();
               }
               // otherwise there are no loops left, so stop
               else
               {
                  this->stop();
                  return;
               }               
            }
            
            this->jump( mCurrentTime );
            
            // time passes in the direction of play (forward|reverse)
            // multiply play speed by the set factor...
            if (mReverse == false)
               mFutureTime += timeOfKey * mPlayFactor;
            else
               mFutureTime -= timeOfKey * mPlayFactor;            
         }
      }      


      //: set the speed at which to play (factor > 0)
      // normal play:  1.0
      // double speed: 2.0
      // half speed:   0.5
      void setSpeed( float factor = 1.0f )
      {
         assert( factor > 0.0f && "use reverseplay() and play() to change direction (if factor < 0), use stop() to stop (if factor == 0)" );
         mPlayFactor = factor;
      }
      
      //: number of times to loop
      //  loop once:      1 (default) 
      //  loop infinite: -1
      //  loop n times:   n > 0
      // NOTE: enter 0 and the animation will never run...
      void setLoops( int numTimesToLoop = 1 )
      {
         mLoops = numTimesToLoop;
         mLoopsLeft = mLoops;
      }
      
      //: add a key to the keyframer.
      void addkey( const _keyType& key )
      {
         mKeys[key.time()] = key;
      }
      
// state querys
public:
      //: access all the keys in the system (non-const version)
      //  useful in case you need to write your own data traverser
      std::map<float, _keyType>& keys() { return mKeys; }
      
      //: access all the keys in the system (const version)
      //  useful in case you need to write your own data traverser
      const std::map<float, _keyType>& keys() const { return mKeys; }

      //: what is the time at the first key (start time of the animation)
      float begintime() const
      {
         return (*(mKeys.begin())).first;
      }

      //: what is the time at the last key (end time of the animation)
      float endtime() const
      {
         return (*(mKeys.rbegin())).first;
      }
      
      //: returns animation time in seconds
      float length() 
      { 
         if (mKeys.size() == 0) 
            return 0.0f; // if no keys, then there is no length to the animation
         
         return this->endtime() - this->begintime(); 
      }
      
      bool isPlaying() { return mIsPlaying; }
      
      //: speed of play (factor > 0)
      // normal play:  1.0
      // double speed: 2.0
      // half speed:   0.5
      float speed() const
      {
         return mPlayFactor;
      }
      
      //: Total number of Loops
      // get the number of times the animation is set to repeat
      int loops() { return mLoops; }
      
      //: Number of loops left
      // get the number of times the animation has yet to repeat
      int loopsLeft() { return mLoopsLeft; }
      
      //: get the current interpolated key
      const _keyType& key() const { return mCurrentKey; }
      
      //: get the current interpolated key's quaternion rotation
      const gmtl::Quatf& rotation() const { return mCurrentKey.rotation(); }
      
      //: get the current interpolated key's position
      const gmtl::Vec3f& position() const { return mCurrentKey.position(); }
      
      //: get the time of the current interpolated key
      const float& time() const
      {
         //assert( mCurrentTime == mCurrentKey.time() && "should be equal" );
         return mCurrentKey.time();
      }

private:
      // util func
      //void output( _keyType& key )
      //{
      //   printf( "KEY %f: %4.1f, \t%4.1f, \t%4.1f, |#| %4.1f, %4.1f, %4.1f, %4.1f\n", key.time(), key.position()[0], key.position()[1], key.position()[2], key.rotation()[0], key.rotation()[1], key.rotation()[2], key.rotation()[3] );
      //}
public:

      //: jump to arbitrary time
      // O( lg n )
      // seekToTime: time that you want to jump to in the animation 
      //             must be in the range: [0 <= x <= length()]
      // post: time() returns time
      void jump( float seekToTime )
      {
         if (mKeys.size() <= 0)
            return;

         assert( seekToTime <= this->length() );
         
         // grab the two keys that come before and after the requested time.
         std::map<float, _keyType>::iterator first, second;
         second = mKeys.lower_bound( seekToTime );// will always return a valid it because of the assert above.
         first = second;
         --first;
         if (first == mKeys.end())
         {
            first = second;
         }         
         
         // if out of bounds, then fix it...
         float a = (*first).first, b = (*second).first;
         if (seekToTime < a || seekToTime > b)
         {
            seekToTime = (*first).first;
         }
         
         // interpolate (set the current key)
         const _keyType& key_one = (*first).second; assert( key_one.time() == (*first).first && "not good" );
         const _keyType& key_two = (*second).second; assert( key_two.time() == (*second).first && "not good" );
         mCurrentKey.setInterpolate( seekToTime, key_one, key_two );
         
         //output( mCurrentKey );
         
         // set the current time.
         mCurrentTime = seekToTime;
      }
      

private:
      // map a time to a key (binary tree, O(lg n) lookup)
      std::map<float, _keyType>  mKeys; 
      bool           mIsPlaying, mReverse;
      
      // how fast to play
      float          mPlayFactor;
      
      // -1 is continuous, 0 is none, n is number of times.
      int            mLoops, mLoopsLeft;
      
      // position in animation...
      float          mCurrentTime, mFutureTime;
      
      // the current key (interpolated)
      _keyType       mCurrentKey;
   };
}; //namespace ani

#endif

---