Smooth.h

/*
 * Smooth.h
 *
 * Copyright 2012 Tim Barrass.
 *
 * This file is part of Mozzi.
 *
 * Mozzi is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
 *
 */

#ifndef SMOOTH_H_
#define SMOOTH_H_

#include "Arduino.h"
#include "mozzi_fixmath.h"

/** A simple infinite impulse response low pass filter for smoothing control or audio signals.
This algorithm comes from http://en.wikipedia.org/wiki/Low-pass_filter:
y[i] := y[i-1] + α * (x[i] - y[i-1]),
translated as
out = last_out + a * (in - last_out).
It's not calibrated to any real-world update rate, so if you use it at
CONTROL_RATE and you change CONTROL_RATE, you'll need to adjust the smoothness
value to suit.
@tparam T the type of numbers being smoothed.  Watch out for numbers overflowing the
internal calculations. Some experimentation is recommended.
@note Timing: ~5us for 16 bit types, ~1us for 8 bit types.
@todo Check if 8 bit templates can work efficiently with a higher res smoothness -
    as is they don't have enough resolution to work well at audio rate.  See if Line might be
    more useful in most cases.
*/

template <class T>
class Smooth
{
private:
    long last_out;
    Q0n16 a;

public:
    /** Constructor.
    @param smoothness sets how much smoothing the filter will apply to
    its input. Use a float in the range 0~1, where 0 is not very smooth and 0.99 is
    very smooth.
     */
    Smooth(float smoothness)
    {
        setSmoothness(smoothness);
    }

    /** Constructor.
    This constructor which doesn't take a smoothness parameter is useful when you incorporate Smooth into another class definition.
    You need to call setSmoothness(float) for your object before using Smooth.
    @note there's probably a better way to do this...
     */
    Smooth()
    {}


    /** Filters the input and returns the filtered value.  You can also use the operator() function, eg. something like mySmoother(input-value).
    @param in the signal to be smoothed.
    @return the filtered signal.
     */
    inline
    T next(T in)
    {
        long out = ((((((long)in - (last_out>>8)) * a))>>8) + last_out);
        last_out = out;
        return (T)(out>>8);
    }


    /** Filters the input and returns the filtered value.  Same as next(input-value).
    @param in the signal to be smoothed.
    @return the filtered signal.
     */
    inline
    T operator()(T n) {
        return next(n);
    }


    /** Sets how much smoothing the filter will apply to its input.
    @param smoothness sets how much smoothing the filter will apply to
    its input. Use a float in the range 0~1, where 0 is not very smooth and 0.99 is
    very smooth.
     */
    inline
    void setSmoothness(float smoothness)
    {
        a=float_to_Q0n16(1.f-smoothness);
    }

};


/** @cond */ // doxygen can ignore the specialisations

/** uint8_t specialisation of Smooth template*/
template <>
class Smooth <uint8_t>
{
private:
    unsigned int last_out;
    Q0n8 a;

public:
    /** Constructor.
    @param smoothness sets how much smoothing the filter will apply to
    its input. Use a float in the range 0~1, where 0 is not very smooth and 0.99 is
    very smooth.
     */
    Smooth(float smoothness)
    {
        setSmoothness(smoothness);
    }

    /** Filters the input and returns the filtered value.  You can also use the operator() function, eg. something like mySmoother(input-value).
    @param in the signal to be smoothed.
    @return the filtered signal.
     */
    inline
    uint8_t next(uint8_t in)
    {
        unsigned int out = (((((int)in - (last_out>>8)) * a)) + last_out);
        last_out = out;
        return (uint8_t)(out>>8);
    }


    /** Filters the input and returns the filtered value.  Same as next(input-value).
    @param in the signal to be smoothed.
    @return the filtered signal.
     */
    inline
    uint8_t  operator()(uint8_t  n) {
        return next(n);
    }


    /** Sets how much smoothing the filter will apply to its input.
    @param smoothness sets how much smoothing the filter will apply to
    its input. Use a float in the range 0~1, where 0 is not very smooth and 0.99 is
    very smooth.
     */
    inline
    void setSmoothness(float smoothness)
    {
        a=float_to_Q0n8(1.f-smoothness);
    }

};


/** int8_t specialisation of Smooth template*/
template <>
class Smooth <int8_t>
{
private:
    int last_out;
    Q0n8 a;

public:
    /** Constructor.
    @param smoothness sets how much smoothing the filter will apply to
    its input. Use a float in the range 0~1, where 0 is not very smooth and 0.99 is
    very smooth.
     */
    Smooth(float smoothness)
    {
        setSmoothness(smoothness);
    }


    /** Filters the input and returns the filtered value.  You can also use the operator() function, eg. something like mySmoother(input-value).
    @param in the signal to be smoothed.
    @return the filtered signal.
     */
    inline
    int8_t next(int8_t in)
    {
        int out = (((((int)in - (last_out>>8)) * a)) + last_out);
        last_out = out;
        return (int8_t)(out>>8);
    }


    /** Filters the input and returns the filtered value.  Same as next(input-value).
    @param in the signal to be smoothed.
    @return the filtered signal.
     */
    inline
    int8_t operator()(int8_t n) {
        return next(n);
    }


    /** Sets how much smoothing the filter will apply to its input.
    @param smoothness sets how much smoothing the filter will apply to
    its input. Use a float in the range 0~1, where 0 is not very smooth and 0.99 is
    very smooth.
     */
    inline
    void setSmoothness(float smoothness)
    {
        a=float_to_Q0n8(1.f-smoothness);
    }

};

/** float specialisation of Smooth template*/
template <>
class Smooth <float>
{
private:
    float last_out;
    float a;

public:
    /** Constructor.
    @param smoothness sets how much smoothing the filter will apply to
    its input. Use a float in the range 0~1, where 0 is not very smooth and 0.99 is
    very smooth.
     */
    Smooth(float smoothness)
    {
        setSmoothness(smoothness);
    }

    /** Filters the input and returns the filtered value.  You can also use the operator() function, eg. something like mySmoother(input-value).
    @param in the signal to be smoothed.
    @return the filtered signal.
     */
    inline
    float next(float in)
    {
        float out = last_out + a * (in - last_out);
        //float out = (in - last_out * a) + last_out;
        last_out = out;
        return out;
    }


    /** Filters the input and returns the filtered value.  Same as next(input-value).
    @param in the signal to be smoothed.
    @return the filtered signal.
     */
    inline
    float operator()(float n) {
        return next(n);
    }


    /** Sets how much smoothing the filter will apply to its input.
    @param smoothness sets how much smoothing the filter will apply to
    its input. Use a float in the range 0~1, where 0 is not very smooth and 0.99 is
    very smooth.
     */
    inline
    void setSmoothness(float smoothness)
    {
        a=1.f-smoothness;
    }

};


/** @endcond */

/**
@example 05.Control_Filters/Smooth/Smooth.ino
This example demonstrates the Smooth class.
*/

#endif /* SMOOTH_H_ */