hersto:  Library/Damper.h

/*
  Damper.h
 
  A C++ implementation of a Damper.

  Author:
      Herbert Stocker

  Underlying Paper:
      "Linear Filters - Animating Objects in a
      Flexible and Pleasing Way" by Herbert Stocker

  HomePage:
      http://www.hersto.net/Followers
      (various resources there)

  License:
      You may use this file in any project and
      modify it as long as you keep this comment
      block unchanged.

  Accompanying Files:
      Damper.cpp
      Damper_impl.h

  Required Files:
      Follower_Trait.h
      Follower_Trait.cpp
      Follower_Trait_impl.h
      TimeDependent.h
      TimeDependent.cpp

  Documentation:
      See http://www.hersto.net/Followers

 */



#pragma once

#include "Follower_Trait.h" // for specifying the behviour of the dampered variable.

#include "TimeDependent.h"

#define This (*this)
// if you don't like this, replace do a text replacement and remove this line.




template<class Type>
class CTDamper
:   public CTimeDependent
{
public:
    typedef const Type cType;

    explicit CTDamper(double Tau, int Order= 1, bool bStartWithFirstInput= false);
    explicit CTDamper(double Tau, bool bStartWithFirstInput= false);
    CTDamper(double Tau, int Order, cType& InitialVal, cType& InitialDest);
   ~CTDamper();

    void set_destination(cType& Dest);
    void set_value(cType& Val);

    cType& get_destination();
    cType& get_value();

    void set_tau(double Tau);
    double get_tau();

    int get_order();

    void set_eps(double Eps);
    double get_eps();

    bool get_isActive();

    // C-Style callback:
    // NOTE: There is no standard mechanism for callbacks, like in other
    // languages, where there are delegates or closures. Therefore this
    // provides just plain C callbacks, and you may want to replace it
    // with your preferred mechanism.
    // However, maybe the FastDelegates from CodeProject (http://www.code-
    // project.com/cpp/FastDelegate.asp) or Boost::function are good can-
    // didates for a replacement.
    void SetReceivers( void* pvContext
                     , void (*pfValueReceiver)   (void* pvContext, cType& Value)
                     , void (*pfIsActiveReceiver)(void* pvContext, bool bIsActive)
                     );
    
    void Tick(double DeltaT, double Now);

    void SetNeedTickCB(void* pvContext, double (*pfNeedTickCB) (void* pvContext, CTimeDependent* pCaller, bool bNeedTick));


protected:
    double mTau;
    double mEps; // 
    int    mOrder;
    bool   mbNeedTick;
    bool   mbNeedToTakeFirstInput;

    CTFollowerVarTrait<Type> mValue0; // destination.
    CTFollowerVarTrait<Type> mValue1;
    CTFollowerVarTrait<Type> mValue2;
    CTFollowerVarTrait<Type> mValue3;
    CTFollowerVarTrait<Type> mValue4;
    CTFollowerVarTrait<Type> mValue5;

    void* mpvRcvContext;
    void (*mpfValueReceiver)(void* pvContext, cType& Value);
    void (*mpfIsActiveReceiver)(void* pvContext, bool bIsActive);

    void mfCallValueRcv(cType& Value)
      { if(mpfValueReceiver)    mpfValueReceiver(mpvRcvContext, Value); }

    void mfCallIsActiveRcv(bool bIsActive)
      { if(mpfIsActiveReceiver) mpfIsActiveReceiver(mpvRcvContext, bIsActive); }



    double mfGetDist();

    void mfUpdateReached(double Dist)
      {} // currently 'reached' is not implemented.

    void mfUpdateReached()
      { /*mfUpdateReached(mfGetDist());*/ }


    void mfSetNeedTick(bool bNeedTick);
    // sets mbNeedTick and calls the need-tick callback. 

};



#include "Damper_impl.h"


// When using CTDamper for type T, 
//  - make sure that the default constructor of T initializes its values to some kind of zero
//    or write a specialization for CTFollowerVarTrait<T>::CTFollowerVarTrait() that does it,
//    or do not use the default constructor of CDamper (that's an unsafe way).
//    Otherwise the transiton output initially will be not defined.
//  - make sure T provides all the operations used by CTFollowerVarTrait with the same meaning
//    as used with numbers, or provide a specialization for CTFollowerVarTrait<T> with the apropriate
//    translations.