 |
CUGL 2.0
Cornell University Game Library
|
|
CUGL 2.0
Cornell University Game Library
|
#include <CUIIRFilter.h>
Public Member Functions | |
| IIRFilter () | |
| IIRFilter (unsigned channels) | |
| IIRFilter (unsigned channels, const std::vector< float > &bvals, const std::vector< float > &avals) | |
| IIRFilter (const IIRFilter ©) | |
| IIRFilter (IIRFilter &&filter) | |
| ~IIRFilter () | |
| unsigned | getChannels () const |
| void | setChannels (unsigned channels) |
| void | setCoeff (const std::vector< float > &bvals, const std::vector< float > &avals) |
| std::vector< float > | getBCoeff () const |
| std::vector< float > | getACoeff () const |
| void | setTransfer (const Polynomial &p, const Polynomial &q) |
| Polynomial | getNumerator () const |
| Polynomial | getDenominator () const |
| 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 an infinite impulse response filter.
In particular, this class implements the standard difference equation:
a[0]*y[n] = b[0]*x[n]+...+b[nb]*x[n-nb]-a[1]*y[n-1]-...-a[na]*y[n-na]
If a[0] is not equal to 1, the filter coeffcients are normalized by a[0].
For filters containing only feedforward terms, FIRFilter is slightly more efficient.
This class supports vector optimizations for SSE and Neon 64. In timed simulations, these optimizations provide at least a 3-4x 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 out-performs Apple's Acceleration library. However, our implementation is limited to 128-bit words as 256-bit (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::IIRFilter::IIRFilter | ( | ) |
Creates a zero-order pass-through filter for a single channel.
| cugl::dsp::IIRFilter::IIRFilter | ( | unsigned | channels | ) |
Creates a zero-order pass-through filter for the given number of channels.
| channels | The number of channels |
| cugl::dsp::IIRFilter::IIRFilter | ( | unsigned | channels, |
| const std::vector< float > & | bvals, | ||
| const std::vector< float > & | avals | ||
| ) |
Creates an IIR filter with the given coefficients and number of channels.
This filter implements the standard difference equation:
a[0]*y[n] = b[0]*x[n]+...+b[nb]*x[n-nb]-a[1]*y[n-1]-...-a[na]*y[n-na]
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].
| channels | The number of channels |
| bvals | The upper coefficients |
| avals | The lower coefficients |
| cugl::dsp::IIRFilter::IIRFilter | ( | const IIRFilter & | copy | ) |
Creates a copy of the IIR filter.
| copy | The filter to copy |
| cugl::dsp::IIRFilter::IIRFilter | ( | IIRFilter && | filter | ) |
Creates an IIR filter with the resources of the original.
| filter | The filter to acquire |
| cugl::dsp::IIRFilter::~IIRFilter | ( | ) |
Destroys the filter, releasing all resources.
| void cugl::dsp::IIRFilter::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 a-coefficients. 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::IIRFilter::clear | ( | ) |
Clears the filter buffer of any delayed outputs or cached inputs
| size_t cugl::dsp::IIRFilter::flush | ( | float * | output | ) |
Flushes any delayed outputs to the provided array
The array size should be the number of channels times one less the number of a-coefficients.
This method will also clear the buffer.
| std::vector<float> cugl::dsp::IIRFilter::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[n-nb]-a[1]*y[n-1]-...-a[na]*y[n-na]
where y is the output and x in the input.
| std::vector<float> cugl::dsp::IIRFilter::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[n-nb]-a[1]*y[n-1]-...-a[na]*y[n-na]
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::IIRFilter::getDenominator | ( | ) | const |
Returns the denominator polynomail for the filter transfer function.
Every digital filter is defined by by a z-domain 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 b-coefficients and the coefficients of q are the q-coefficients.
| Polynomial cugl::dsp::IIRFilter::getNumerator | ( | ) | const |
Returns the numerator polynomail for the filter transfer function.
Every digital filter is defined by by a z-domain 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 b-coefficients and the coefficients of q are the q-coefficients.
| void cugl::dsp::IIRFilter::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::IIRFilter::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[n-nb]-a[1]*y[n-1]-...-a[na]*y[n-na]
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].
| bvals | The upper coefficients |
| avals | The lower coefficients |
| void cugl::dsp::IIRFilter::setTransfer | ( | const Polynomial & | p, |
| const Polynomial & | q | ||
| ) |
Sets the transfer function for this IIR filter.
Every digital filter is defined by by a z-domain 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 b-coefficients and the coefficients of q are the q-coefficients.
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::IIRFilter::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 a-coefficients. 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)
1.8.16