Smooth.h

/*
 * Smooth.h
 *
 * This file is part of Mozzi.
 *
 * Copyright 2012-2024 Tim Barrass and the Mozzi Team
 *
 * Mozzi is licensed under the GNU Lesser General Public Licence (LGPL) Version 2.1 or later.
 *
 */
 
#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
MOZZI_CONTROL_RATE and you change MOZZI_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 */
 
 
/* Specialization for UFix */
template<int8_t NI, int8_t NF>
class Smooth<UFix<NI,NF>>
{
private:
  typedef UFix<NI, NF> internal_type;
  internal_type last_out;
  UFix<0,16> a;
 
public:
 
 
  /** Constructor.
      @param smoothness sets how much smoothing the filter will apply to
      its input. Use a float or a UFix<0,NF> in the range 0~1, where 0 is not very smooth and 0.99 is
      very smooth.
  */
  template<typename T>
  Smooth(T 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
  internal_type next(internal_type in)
  {
    internal_type out = last_out + a * (in - last_out);  // With FixMath, the syntax is actually the same than with floats :)
    last_out = out;
    return out;
  }
 
 
 
  inline
  internal_type operator()(internal_type 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=internal_type(1.f-smoothness);
  }
 
  /** 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 UFix<0,NF> in the range 0~1, where 0 is not very smooth and 0.99 is
      very smooth.
  */
  template<int8_t _NF>
  void setSmoothness(UFix<0,_NF> smoothness)
  {
    a = UFix<1,0>(1) - smoothness;
  }
 
};
 
 
 
 
/* Specialization for SFix */
template<int8_t NI, int8_t NF>
class Smooth<SFix<NI,NF>>
{
private:
  typedef SFix<NI, NF> internal_type;
  internal_type last_out;
  UFix<0,16> a;
 
public:
 
 
  /** Constructor.
      @param smoothness sets how much smoothing the filter will apply to
      its input. Use a float or a UFix<0,NF> in the range 0~1, where 0 is not very smooth and 0.99 is
      very smooth.
  */
  template<typename T>
  Smooth(T 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
  internal_type next(internal_type in)
  {
    internal_type out = last_out + a * (in - last_out);
    last_out = out;
    return out;
  }
 
 
 
  inline
  internal_type operator()(internal_type 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=internal_type(1.f-smoothness);
  }
 
  /** 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 UFix<0,NF> in the range 0~1, where 0 is not very smooth and 0.99 is
      very smooth.
  */
  template<int8_t _NF>
  void setSmoothness(UFix<0,_NF> smoothness)
  {
    a = UFix<1,0>(1) - smoothness;
  }
 
};
 
/**
@example 05.Control_Filters/Smooth/Smooth.ino
This example demonstrates the Smooth class.
*/
 
#endif /* SMOOTH_H_ */