CL_Lag.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        CL_Lag.h ( Clip Library, C++)
 *
 * COMMENTS:
 *    Applies a lag filter to input data
 */


#ifndef __CL_Lag__
#define __CL_Lag__

#include <SYS/SYS_Math.h>
#include <SYS/SYS_Types.h>
#include <UT/UT_Vector.h>

#include <algorithm>

class UT_Interrupt;

class CL_Lag
{
public:

    /// Apply a lag filter
    /// data and result must both be of length size
    static void solve(const fpreal *data, fpreal *result, int size, 
                      fpreal lag_up, fpreal lag_down, fpreal overshoot_up, fpreal overshoot_down,
                      bool sclamp = false, bool aclamp = false,
                      fpreal sclamp_up = 0.0, fpreal sclamp_down = 0.0, 
                      fpreal aclamp_up = 0.0, fpreal aclamp_down = 0.0,
                      bool use_value_method = false);

    /// Apply a lag filter using the magnitude method
    /// Must provide lambda functions for getting the data (the p1 value) and 
    /// setting the results (based on the index and resulting p1 and)
    template <class F, class FR, class FP>
    static void solveRealtimeMagnitude(const F& get_data, const FR& set_results, int start, int end,
                                       bool sclamp, bool aclamp,
                                       const FP& get_params,
                                       UT_VectorR &v0, UT_VectorR &p0);

    /// Apply a lag filter to realtime data using using the value or amplitude methods
    /// Must provide a lambda function for computing the p1 value from the data
    template <class F, class FP>
    static bool solveRealtime(const F& get_data, fpreal *result, int start, int end,
                              bool sclamp, bool aclamp,
                              const FP& get_params,
                              fpreal &v0, fpreal &p0,
                              bool use_value_method = false);
                            

private:
    static constexpr fpreal LN_PNT_ONE = -2.3025851;
    static constexpr fpreal MAX_STEADY_DELTA = 0.001;

    /// Calculate Lag Vector
    /// Used when computing lag via magnitude
    static void
    calculateLagVector(UT_VectorR &v0, UT_VectorR &v1,
                       UT_VectorR &p0, UT_VectorR &p1,
                       UT_VectorR &a0, UT_VectorR &a1,
                       bool sclamp, bool aclamp,
                       const fpreal &lag_up, const fpreal &over_up,
                       const fpreal &sclamp_up, const fpreal &aclamp_up)
    {
        fpreal len;

        // lag
        p1 *= lag_up;
        p1.addScaledVec(1.0 - lag_up, p0);

        // overshoot
        v1  = p1;
        v1 -= p0;

        v1 *= over_up;
        v1.addScaledVec(1.0 - over_up, v0);

        // clamp slope
        if (sclamp)
        {
            len = v1.norm();
            if (len > sclamp_up)
                v1 *= (sclamp_up / len);
            p1  = v1;
            p1 += p0;
        }

        // clamp acc
        a1  = v1;
        a1 -= v0;

        if (aclamp)
        {
            len = a1.norm();
            if (len > aclamp_up)
                a1 *= (aclamp_up / len);

            v1  = a1;
            v1 += v0;
        }

        p1 = v1;
        p1 += p0;

        p0 = p1;
        v0 = v1;
    }

    /// Calculate lag
    /// Used when computing lag via value or amplitude methods
    static fpreal calculateLag(bool use_value_method, fpreal &v0, fpreal &p0, fpreal p1,
                               bool sclamp, bool aclamp,
                               const fpreal &lag_up, const fpreal &lag_down,
                               const fpreal &over_up, const fpreal &over_down,
                               const fpreal &sclamp_up, const fpreal &sclamp_down,
                               const fpreal &aclamp_up, const fpreal &aclamp_down)
    {
        fpreal cmp = 0.0;
        fpreal v1 = 0.0;
        fpreal a1 = 0.0;
        
        // lag
        if (use_value_method)
            cmp = p1-p0;
        else
            cmp = abs(p1)-abs(p0);

        if (cmp > 0.0)
            p1 = (1.0 - lag_up)*p0 + lag_up*p1;
        else if (cmp < 0.0)
            p1 = (1.0 - lag_down)*p0 + lag_down*p1;
        
        // overshoot
        v1 = p1 - p0;
        
        if (v1 > 0)
            v1 = (1.0 - over_up)*v0 + over_up*v1;
        else if (v1 < 0)
            v1 = (1.0 - over_down)*v0 + over_down*v1;

        // clamp slope
        if (sclamp)
        {
            if (v1 > 0)
            {
                if (v1 > sclamp_up) 
                    v1 = sclamp_up;
            }
            else if (v1 < 0)
            {
                if (v1 < - sclamp_down) 
                    v1 = -sclamp_down;
            }
            
        }
        
        p1 = v1 + p0;
        
        // clamp acc
        a1 = v1 - v0;

        if (aclamp)
        {
            if (a1 > 0)
            {
                if (a1 > aclamp_up) 
                    a1 = aclamp_up;
            }
            else if (a1 < 0)
            {
                if (a1 < -aclamp_down) 
                    a1 = -aclamp_down;
            }
        }
        
        v1 = a1 + v0;
        p0 = p1;
        v0 = v1;

        return p1;
    }
};

inline void 
CL_Lag::solve(const fpreal *data, fpreal *result, int size, 
              fpreal lag_up, fpreal lag_down, fpreal overshoot_up, fpreal overshoot_down,
              bool sclamp, bool aclamp, 
              fpreal sclamp_up, fpreal sclamp_down, 
              fpreal aclamp_up, fpreal aclamp_down,
              bool use_value_method)
{
    if (size < 2)
    {
        if (result != data)
            std::copy(data, data + size, result);
        return;
    }

    fpreal p = data[0];
    fpreal p1 = data[1];
    fpreal v = 0.0;

    fpreal lag0 = (lag_up > 0.0) ? 1.0 - exp(LN_PNT_ONE / lag_up)  : 1.0;
    fpreal lag1 = (lag_down > 0.0) ? 1.0 - exp(LN_PNT_ONE / lag_down)  : 1.0;
    fpreal over0 = (overshoot_up > 0.0) ? 1.0 - exp(LN_PNT_ONE / overshoot_up) : 1.0;
    fpreal over1 = (overshoot_down > 0.0) ? 1.0 - exp(LN_PNT_ONE / overshoot_down) : 1.0;

    for (exint idx = 0; idx < size; ++idx)
    {        
        p1 = data[idx];
        
        p1 = calculateLag(use_value_method, v, p, p1,
                          sclamp, aclamp,
                          lag0, lag1, over0, over1,
                          sclamp_up, sclamp_down, aclamp_up, aclamp_down);
       
        result[idx] = p1;
    }
}

template <class F, class FP>
inline bool 
CL_Lag::solveRealtime(const F& get_data, fpreal *result, int start, int end,
                      bool sclamp, bool aclamp,
                      const FP& get_params,
                      fpreal &v0, fpreal &p0,
                      bool use_value_method)
{
    fpreal delta = 0.0;
    bool steady = true;

    fpreal lag_up; 
    fpreal lag_down;
    fpreal over_up; 
    fpreal over_down;
    fpreal sclamp_up; 
    fpreal sclamp_down;
    fpreal aclamp_up; 
    fpreal aclamp_down;

    for (exint i = start; i <= end; i++)
    {
        fpreal p1 = get_data(i);

        if (!get_params(lag_up, lag_down, over_up, over_down, 
                        sclamp_up, sclamp_down, aclamp_up, aclamp_down))
        {
            break;
        }

        fpreal res = calculateLag(use_value_method, v0, p0, p1, sclamp, aclamp, 
                                  lag_up, lag_down, over_up, over_down,
                                  sclamp_up, sclamp_down, aclamp_up, aclamp_down);

        delta = SYSabs(p1 - res);
        if (delta > MAX_STEADY_DELTA)
            steady = false;

        result[i] = res;
    }

    return steady;
}

template <class F, class FR, class FP>
void 
CL_Lag::solveRealtimeMagnitude(const F& get_data, const FR& set_results, int start, int end,
                               bool sclamp, bool aclamp,
                               const FP& get_params,
                               UT_VectorR &v0, UT_VectorR &p0)
{
    UT_VectorR v1;
    UT_VectorR p1;
    UT_VectorR a0;
    UT_VectorR a1;

    v1.init(v0.getNL(), v0.getNH());
    p1.init(v0.getNL(), v0.getNH());
    a0.init(v0.getNL(), v0.getNH());
    a1.init(v0.getNL(), v0.getNH());

    fpreal lag_up;
    fpreal over_up;
    fpreal sclamp_up;
    fpreal aclamp_up;

    for (exint i = start; i <= end; i++)
    {
        get_data(i, p1);

        if (!get_params(lag_up, over_up, sclamp_up, aclamp_up))
        {
            break;
        }

        calculateLagVector(v0, v1, p0, p1, a0, a1, 
                           sclamp, aclamp, 
                           lag_up, over_up, 
                           sclamp_up, aclamp_up);

        set_results(i, p1);
    }
}

#endif