Mozzi  version v2.0
sound synthesis library for Arduino
Automatic range adjustment

Detailed Description

Classes

class  AutoMap
 Automatically map an input value to an output range without knowing the precise range of inputs beforehand. More...
 
class  AutoRange< T >
 Keeps a running calculation of the range of the input values it receives. More...
 
class  OverSample< T, RESOLUTION_INCREASE_BITS >
 Enables the resolution of analog inputs to be increased by oversampling and decimation. More...
 
class  RollingAverage< T, WINDOW_LENGTH >
 Calculates a running average over a specified number of the most recent readings. More...
 
class  RollingStat< T, WINDOW_LENGTH >
 WARNING: this class is work in progress, don't use it yet. More...
 

Class Documentation

◆ AutoMap

class AutoMap

Automatically map an input value to an output range without knowing the precise range of inputs beforehand.

Definition at line 29 of file AutoMap.h.

+ Inheritance diagram for AutoMap:

Public Member Functions

 AutoMap (int min_expected, int max_expected, int map_to_min, int map_to_max)
 Constructor. More...
 
int next (int n)
 Process the next value and return it mapped to the range which was set in the constructor. More...
 
int operator() (int n)
 Process the next value and return it mapped to the range which was set in the constructor. More...
 
int getMin ()
 Returns the current minimum. More...
 
int getMax ()
 Returns the current maximum. More...
 
int getRange ()
 Returns the current range. More...
 

Constructor & Destructor Documentation

◆ AutoMap()

AutoMap::AutoMap ( int  min_expected,
int  max_expected,
int  map_to_min,
int  map_to_max 
)
inline

Constructor.

Parameters
min_expectedthe minimum possible input value.
max_expectedthe maximum possible input value.

Definition at line 36 of file AutoMap.h.

Member Function Documentation

◆ getMax()

int AutoRange< int >::getMax ( )
inlineinherited

Returns the current maximum.

Returns
maximum

Definition at line 65 of file AutoRange.h.

◆ getMin()

int AutoRange< int >::getMin ( )
inlineinherited

Returns the current minimum.

Returns
minimum

Definition at line 56 of file AutoRange.h.

◆ getRange()

int AutoRange< int >::getRange ( )
inlineinherited

Returns the current range.

Returns
range

Definition at line 74 of file AutoRange.h.

◆ next()

int AutoMap::next ( int  n)
inline

Process the next value and return it mapped to the range which was set in the constructor.

Can use the operator instead if you prefer, eg. myMap(n) instead of myMap.next(n).

Parameters
nthe next value to process.
Returns
the input value mapped to the range which was set in the constructor.

Definition at line 48 of file AutoMap.h.

◆ operator()()

int AutoMap::operator() ( int  n)
inline

Process the next value and return it mapped to the range which was set in the constructor.

This is an alternative to next() if you prefer, eg. myMap(n) instead of myMap.next(n).

Parameters
nthe next value to process.
Returns
the input value mapped to the range which was set in the constructor.

Definition at line 60 of file AutoMap.h.

◆ AutoRange

class AutoRange

template<class T>
class AutoRange< T >

Keeps a running calculation of the range of the input values it receives.

Definition at line 19 of file AutoRange.h.

Public Member Functions

 AutoRange (T min_expected, T max_expected)
 Constructor. More...
 
void next (T n)
 Updates the current range. More...
 
getMin ()
 Returns the current minimum. More...
 
getMax ()
 Returns the current maximum. More...
 
getRange ()
 Returns the current range. More...
 

Constructor & Destructor Documentation

◆ AutoRange()

template<class T >
AutoRange< T >::AutoRange ( min_expected,
max_expected 
)
inline

Constructor.

Template Parameters
Tthe type of numbers to to use, eg. int, unsigned int, float etc.
Parameters
min_expectedthe minimum possible input value.
max_expectedthe maximum possible input value.

Definition at line 28 of file AutoRange.h.

Member Function Documentation

◆ getMax()

template<class T >
T AutoRange< T >::getMax ( )
inline

Returns the current maximum.

Returns
maximum

Definition at line 65 of file AutoRange.h.

◆ getMin()

template<class T >
T AutoRange< T >::getMin ( )
inline

Returns the current minimum.

Returns
minimum

Definition at line 56 of file AutoRange.h.

◆ getRange()

template<class T >
T AutoRange< T >::getRange ( )
inline

Returns the current range.

Returns
range

Definition at line 74 of file AutoRange.h.

◆ next()

template<class T >
void AutoRange< T >::next ( n)
inline

Updates the current range.

Parameters
nthe next value to include in the range calculation.

Definition at line 36 of file AutoRange.h.

◆ OverSample

class OverSample

template<class T, const uint8_t RESOLUTION_INCREASE_BITS>
class OverSample< T, RESOLUTION_INCREASE_BITS >

Enables the resolution of analog inputs to be increased by oversampling and decimation.

Noise should be added to the input before it's digitised, then a succession of input readings are summed and finally divided to give a number with greater resolution than the ADC.
Often, noise in the Arduino system will be enough, but there are other practical methods described in Enhancing ADC Resolution by Oversampling, as well as an explanation of the overall approach.

Template Parameters
RESOLUTION_INCREASE_BITShow many extra bits of resolution to produce. The window length and the memory it needs increases quickly as the oversampling resolution increases.
1 bit = 4 unsigned ints (analog input between 0-1023) = 8 uint8_ts, 2 bits = 16 unsigned ints = 32 uint8_ts,
3 bits = 64 unsigned ints = 128 uint8_ts, More than 3 bits increase in resolution would require either using longs to store the readings, which would need 1024 uint8_ts for a 4 bit increase and 4096 uint8_ts for 5 bits (do any avr's have that much room?), or the average reading would have to be no more than 128 (for 4 bits increase), because 256 readings would be needed, and the sum of all 256 readings would have to fit into an int. (32767 / 256 = 128). Changing OverSample to use unsigned ints could enable an average reading of 256, but isn't tested properly yet.
Note
The higher the resolution, the more lag there will be. It's almost a RollingAverage filter, with the difference that OverSample doesn't divide by as much as you would for an average.

Definition at line 42 of file OverSample.h.

+ Inheritance diagram for OverSample< T, RESOLUTION_INCREASE_BITS >:

Public Member Functions

next (T input)
 Oversample and decimate the input to increase resolution by RESOLUTION_INCREASE_BITS;. More...
 

Member Function Documentation

◆ next()

template<class T , const uint8_t RESOLUTION_INCREASE_BITS>
T OverSample< T, RESOLUTION_INCREASE_BITS >::next ( input)
inline

Oversample and decimate the input to increase resolution by RESOLUTION_INCREASE_BITS;.

Parameters
inputan analog input to oversample.
Returns
the higher resolution result.
Note
timing 5.7us

Definition at line 53 of file OverSample.h.

◆ RollingAverage

class RollingAverage

template<class T, int WINDOW_LENGTH>
class RollingAverage< T, WINDOW_LENGTH >

Calculates a running average over a specified number of the most recent readings.


Like Smooth(), this is good for smoothing analog inputs in updateControl().

Template Parameters
WINDOW_LENGTHthe number of readings to include in the rolling average. It must be a power of two (unless you're averaging floats). The higher the number, the more the readings will be smoothed, but the slower the output will respond to the input.

Definition at line 36 of file RollingAverage.h.

Public Member Functions

 RollingAverage ()
 Constructor. More...
 
next (T input)
 Give the average of the last WINDOW_LENGTH. More...
 

Protected Member Functions

add (T input)
 

Constructor & Destructor Documentation

◆ RollingAverage()

template<class T , int WINDOW_LENGTH>
RollingAverage< T, WINDOW_LENGTH >::RollingAverage ( )
inline

Constructor.

Template Parameters
Tthe type of numbers to average, eg. int, unsigned int, float etc. It will be relatively slow with floating point numbers, as it will use a divide operation for the averaging. Nevertheless, there might be a time when it's useful.
WINDOW_LENGTHthe number of readings to keep track of. It must be a power of two (unless you're averaging floats). The higher the number, the more the readings will be smoothed, but the slower the output will respond to the input.
Note
Watch out for overflows!

Definition at line 50 of file RollingAverage.h.

Member Function Documentation

◆ next()

template<class T , int WINDOW_LENGTH>
T RollingAverage< T, WINDOW_LENGTH >::next ( input)
inline

Give the average of the last WINDOW_LENGTH.

Parameters
inputa control signal such as an analog input which needs smoothing.
Returns
the smoothed result.
Note
unsigned int timing 5.7us

Definition at line 63 of file RollingAverage.h.

◆ RollingStat

class RollingStat

template<class T, int WINDOW_LENGTH>
class RollingStat< T, WINDOW_LENGTH >

WARNING: this class is work in progress, don't use it yet.

Calculates an approximation of the variance and standard deviation for a window of recent inputs.

Template Parameters
Tthe type of numbers to use. Choose unsigned int, int , uint8_t, int8_t, or float
WINDOW_LENGTHhow many recent input values to include in the calculations.

Definition at line 27 of file RollingStat.h.

Public Member Functions

 RollingStat ()
 Constructor.
 
void update (T x)
 Update the mean and variance given a new input value. More...
 
void update (int8_t x)
 Update the mean and variance given a new input value. More...
 
getMean () const
 Return the mean of the last WINDOW_LENGTH number of inputs. More...
 
getVariance () const
 Return the approximate variance of the last WINDOW_LENGTH number of inputs. More...
 
getStandardDeviation () const
 Return the approximate standard deviation of the last WINDOW_LENGTH number of inputs. More...
 

Member Function Documentation

◆ getMean()

template<class T , int WINDOW_LENGTH>
T RollingStat< T, WINDOW_LENGTH >::getMean ( ) const
inline

Return the mean of the last WINDOW_LENGTH number of inputs.

Returns
mean

Definition at line 60 of file RollingStat.h.

◆ getStandardDeviation()

template<class T , int WINDOW_LENGTH>
T RollingStat< T, WINDOW_LENGTH >::getStandardDeviation ( ) const
inline

Return the approximate standard deviation of the last WINDOW_LENGTH number of inputs.

Returns
standard deviation.

Definition at line 77 of file RollingStat.h.

◆ getVariance()

template<class T , int WINDOW_LENGTH>
T RollingStat< T, WINDOW_LENGTH >::getVariance ( ) const
inline

Return the approximate variance of the last WINDOW_LENGTH number of inputs.

Returns
variance
Note
This should really be calculated using WINDOW_LENGTH-1, but sacrificing accuracy for speed we use the power of two value of WINDOW_LENGTH.

Definition at line 70 of file RollingStat.h.

◆ update() [1/2]

template<class T , int WINDOW_LENGTH>
void RollingStat< T, WINDOW_LENGTH >::update ( int8_t  x)
inline

Update the mean and variance given a new input value.

Parameters
xthe next input value

Definition at line 50 of file RollingStat.h.

◆ update() [2/2]

template<class T , int WINDOW_LENGTH>
void RollingStat< T, WINDOW_LENGTH >::update ( x)
inline

Update the mean and variance given a new input value.

Parameters
xthe next input value
Note
timing for unsigned int 10us, int 22us

Definition at line 40 of file RollingStat.h.