CUGL 2.3
Cornell University Game Library

#include <CUOnePoleIIR.h>
Public Member Functions  
OnePoleIIR ()  
OnePoleIIR (unsigned channels)  
OnePoleIIR (unsigned channels, float b0, float a1)  
OnePoleIIR (const OnePoleIIR ©)  
OnePoleIIR (OnePoleIIR &&filter)  
~OnePoleIIR ()  
unsigned  getChannels () const 
void  setChannels (unsigned channels) 
void  setCoeff (const std::vector< float > &bvals, const std::vector< float > &avals) 
const std::vector< float >  getBCoeff () const 
const std::vector< float >  getACoeff () const 
void  setTransfer (const Polynomial &p, const Polynomial &q) 
Polynomial  getNumerator () const 
Polynomial  getDenominator () const 
void  setBCoeff (float b0) 
void  setACoeff (float a1) 
void  setLowpass (float frequency) 
float  getPole () const 
void  setPole (float pole) 
void  step (float gain, float *input, float *output) 
void  calculate (float gain, float *input, float *output, size_t size) 
void  clear () 
size_t  flush (float *output) 
Static Public Attributes  
static bool  VECTORIZE 
This class implements a onepole digital filter.
This is the standard class for implementing first order lowpass filters. It is a lowpass filter when the pole is positive (and close to 1). Use the method setLowpass
for setting the lowpass frequency.
Frequencies are specified in "normalized" format. A normalized frequency is frequency/sample rate. For example, a 7 kHz frequency with a 44100 Hz sample rate has a normalized value 7000/44100 = 0.15873.
This class supports vector optimizations for SSE and Neon 64. In timed simulations, these optimizations provide at least a 34x performance increase (and for 4 or 8 channel audio, much higher). These optimizations make use of the matrix precomputation outlined in "Implementation of Recursive Digital Filters into Vector SIMD DSP Architectures".
https://pdfs.semanticscholar.org/d150/a3f75dc033916f14029cd9101a8ea1d050bb.pdf
The algorithm in this paper performs extremely well in our tests, and even outperforms Apple's Acceleration library. However, our implementation is limited to 128bit words as 256bit (e.g. AVX) and higher show no significant increase in performance.
For performance reasons, this class does not have a (virtualized) subclass relationship with other IIR or FIR filters. However, the signature of the the calculation and coefficient methods has been standardized so that it can support templated polymorphism.
This class is not thread safe. External locking may be required when the filter is shared between multiple threads (such as between an audio thread and the main thread).
cugl::dsp::OnePoleIIR::OnePoleIIR  (  ) 
Creates a firstorder passthrough filter for a single channel.
cugl::dsp::OnePoleIIR::OnePoleIIR  (  unsigned  channels  ) 
Creates a firstorder passthrough filter for the given number of channels.
channels  The number of channels 
cugl::dsp::OnePoleIIR::OnePoleIIR  (  unsigned  channels, 
float  b0,  
float  a1  
) 
Creates an IIR filter with the given coefficients and number of channels.
This filter implements the standard difference equation:
y[n] = b[0]*x[n]a[1]*y[n1]
where y is the output and x in the input.
channels  The number of channels 
b0  The upper zeroorder coefficient 
a1  The lower firstorder coefficient 
cugl::dsp::OnePoleIIR::OnePoleIIR  (  const OnePoleIIR &  copy  ) 
Creates a copy of the onepole filter.
copy  The filter to copy 
cugl::dsp::OnePoleIIR::OnePoleIIR  (  OnePoleIIR &&  filter  ) 
Creates a onepole filter with the resources of the original.
filter  The filter to acquire 
cugl::dsp::OnePoleIIR::~OnePoleIIR  (  ) 
Destroys the filter, releasing all resources.
void cugl::dsp::OnePoleIIR::calculate  (  float  gain, 
float *  input,  
float *  output,  
size_t  size  
) 
Performs a filter of interleaved input data.
The output is written to the given output array, which should be the same size as the input array. The size is the number of frames, not samples. Hence the arrays must be size times the number of channels in size.
To provide real time processing, the output is delayed by the number of acoefficients. Delayed results are buffered to be used the next time the filter is used (though they may be extracted with the flush
method). The gain parameter is applied at the filter input, but does not affect the filter coefficients.
gain  The input gain factor 
input  The array of input samples 
output  The array to write the sample output 
size  The input size in frames 
void cugl::dsp::OnePoleIIR::clear  (  ) 
Clears the filter buffer of any delayed outputs or cached inputs
size_t cugl::dsp::OnePoleIIR::flush  (  float *  output  ) 
Flushes any delayed outputs to the provided array
The array size should be the number of channels. This method will also clear the buffer.
const std::vector< float > cugl::dsp::OnePoleIIR::getACoeff  (  )  const 
Returns the lower coefficients for this IIR filter.
This filter implements the standard difference equation:
a[0]*y[n] = b[0]*x[n]+...+b[nb]*x[nnb]a[1]*y[n1]...a[na]*y[nna]
where y is the output and x in the input.
const std::vector< float > cugl::dsp::OnePoleIIR::getBCoeff  (  )  const 
Returns the upper coefficients for this IIR filter.
This filter implements the standard difference equation:
a[0]*y[n] = b[0]*x[n]+...+b[nb]*x[nnb]a[1]*y[n1]...a[na]*y[nna]
where y is the output and x in the input.

inline 
Returns the number of channels for this filter
The data buffers depend on the number of channels. Changing this value will reset the data buffers to 0.
Polynomial cugl::dsp::OnePoleIIR::getDenominator  (  )  const 
Returns the denominator polynomail for the filter transfer function.
Every digital filter is defined by by a zdomain transfer function. This function has the form
H(z) = p(z)/q(z)
where p(z) and q(z) are polynomials of z^1. This function uniquely determines the coefficients of the digital filter. In particular, the the coefficients of p are the bcoefficients and the coefficients of q are the qcoefficients.
Polynomial cugl::dsp::OnePoleIIR::getNumerator  (  )  const 
Returns the numerator polynomail for the filter transfer function.
Every digital filter is defined by by a zdomain transfer function. This function has the form
H(z) = p(z)/q(z)
where p(z) and q(z) are polynomials of z^1. This function uniquely determines the coefficients of the digital filter. In particular, the the coefficients of p are the bcoefficients and the coefficients of q are the qcoefficients.

inline 
Returns the pole position in the zplane.
A positive pole value produces a lowpass filter, while a negative pole value produces a highpass filter. The magnitude should be less than one to maintain filter stability.
void cugl::dsp::OnePoleIIR::setACoeff  (  float  a1  ) 
Sets the lower firstorder coefficient.
a1  The lower firstorder coefficient 
void cugl::dsp::OnePoleIIR::setBCoeff  (  float  b0  ) 
Sets the upper zeroorder coefficient.
b0  The upper zeroorder coefficient 
void cugl::dsp::OnePoleIIR::setChannels  (  unsigned  channels  ) 
Sets the number of channels for this filter
The data buffers depend on the number of channels. Changing this value will reset the data buffers to 0.
channels  The number of channels for this filter 
void cugl::dsp::OnePoleIIR::setCoeff  (  const std::vector< float > &  bvals, 
const std::vector< float > &  avals  
) 
Sets the coefficients for this IIR filter.
This filter implements the standard difference equation:
a[0]*y[n] = b[0]*x[n]+...+b[nb]*x[nnb]a[1]*y[n1]...a[na]*y[nna]
where y is the output and x in the input. If a[0] is not equal to 1, the filter coeffcients are normalized by a[0].
All bcoefficients after the first, and all acoefficients after the second are ignored. If any coefficients are missing, they are replaced with 1 for b[0] and a[0], and 0 otherwise.
bvals  The upper coefficients 
avals  The lower coefficients 
void cugl::dsp::OnePoleIIR::setLowpass  (  float  frequency  ) 
Sets the (normalized) cutoff frequency for a lowpass filter
A normalized frequency is frequency/sample rate. For example, a 7 kHz frequency with a 44100 Hz sample rate has a normalized value of 7000/44100 = 0.15873.
Filters are not intended to be model classes, and so it does not save the defining frequency.
frequency  The (normalized) cutoff frequency for a lowpass filter 
void cugl::dsp::OnePoleIIR::setPole  (  float  pole  ) 
Sets the pole position in the zplane.
This method sets the pole position along the realaxis of the zplane and normalizes the coefficients for a maximum gain of one. A positive pole value produces a lowpass filter, while a negative pole value produces a highpass filter. This method does not affect the filter gain. The argument magnitude should be less than one to maintain filter stability.
pole  The filter pole 
void cugl::dsp::OnePoleIIR::setTransfer  (  const Polynomial &  p, 
const Polynomial &  q  
) 
Sets the transfer function for this IIR filter.
Every digital filter is defined by by a zdomain transfer function. This function has the form
H(z) = p(z)/q(z)
where p(z) and q(z) are polynomials of z^1. This function uniquely determines the coefficients of the digital filter. In particular, the the coefficients of p are the bcoefficients and the coefficients of q are the qcoefficients.
We provide this setter method because filter chaining corresponds to multiplication in the transfer domain. Hence complex filter chains can be collapsed into a single filter for optimization.
p  The numerator polynomial 
q  The denominator polynomial 
void cugl::dsp::OnePoleIIR::step  (  float  gain, 
float *  input,  
float *  output  
) 
Performs a filter of single frame of data.
The output is written to the given output array, which should be the same size as the input array. The size should be the number of channels.
To provide real time processing, the output is delayed by the number of acoefficients. Delayed results are buffered to be used the next time the filter is used (though they may be extracted with the flush
method). The gain parameter is applied at the filter input, but does not affect the filter coefficients.
gain  The input gain factor 
input  The input frame 
output  The frame to receive the output 

static 
Whether to use a vectorization algorithm (Access not thread safe)