#include <CUOnePoleIIR.h>

Public Member Functions
	OnePoleIIR ()

	OnePoleIIR (unsigned channels)

	OnePoleIIR (unsigned channels, float b0, float a1)

	OnePoleIIR (const OnePoleIIR &copy)

	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

Detailed Description

This class implements a one-pole 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 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).

Constructor & Destructor Documentation

◆ OnePoleIIR() [1/5]

cugl::dsp::OnePoleIIR::OnePoleIIR ( )

Creates a first-order pass-through filter for a single channel.

◆ OnePoleIIR() [2/5]

cugl::dsp::OnePoleIIR::OnePoleIIR ( unsigned channels )

Creates a first-order pass-through filter for the given number of channels.

Parameters

channels The number of channels

◆ OnePoleIIR() [3/5]

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[n-1]

where y is the output and x in the input.

Parameters

channels	The number of channels
b0	The upper zero-order coefficient
a1	The lower first-order coefficient

◆ OnePoleIIR() [4/5]

cugl::dsp::OnePoleIIR::OnePoleIIR ( const OnePoleIIR & copy )

Creates a copy of the one-pole filter.

Parameters

copy	The filter to copy

◆ OnePoleIIR() [5/5]

cugl::dsp::OnePoleIIR::OnePoleIIR ( OnePoleIIR && filter )

Creates a one-pole filter with the resources of the original.

Parameters

filter The filter to acquire

◆ ~OnePoleIIR()

cugl::dsp::OnePoleIIR::~OnePoleIIR ( )

Destroys the filter, releasing all resources.

Member Function Documentation

◆ calculate()

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 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.

Parameters

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

◆ clear()

void cugl::dsp::OnePoleIIR::clear ( )

Clears the filter buffer of any delayed outputs or cached inputs

◆ flush()

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.

Returns: The number of frames (not samples) written

◆ getACoeff()

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[n-nb]-a[1]*y[n-1]-...-a[na]*y[n-na]

where y is the output and x in the input.

Returns: The lower coefficients

◆ getBCoeff()

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[n-nb]-a[1]*y[n-1]-...-a[na]*y[n-na]

where y is the output and x in the input.

Returns: The upper coefficients

◆ getChannels()

unsigned cugl::dsp::OnePoleIIR::getChannels ( ) const

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.

Returns: the number of channels for this filter

◆ getDenominator()

Polynomial cugl::dsp::OnePoleIIR::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.

Returns: The denominator polynomail for the filter transfer function.

◆ getNumerator()

Polynomial cugl::dsp::OnePoleIIR::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.

Returns: The numerator polynomail for the filter transfer function.

◆ getPole()

float cugl::dsp::OnePoleIIR::getPole ( ) const

inline

Returns the pole position in the z-plane.

A positive pole value produces a low-pass filter, while a negative pole value produces a high-pass filter. The magnitude should be less than one to maintain filter stability.

Returns: the pole position in the z-plane.

◆ setACoeff()

void cugl::dsp::OnePoleIIR::setACoeff ( float a1 )

Sets the lower first-order coefficient.

Parameters

a1	The lower first-order coefficient

◆ setBCoeff()

void cugl::dsp::OnePoleIIR::setBCoeff ( float b0 )

Sets the upper zero-order coefficient.

Parameters

b0	The upper zero-order coefficient

◆ setChannels()

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.

Parameters

channels The number of channels for this filter

◆ setCoeff()

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[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].

All b-coefficients after the first, and all a-coefficients after the second are ignored. If any coefficients are missing, they are replaced with 1 for b[0] and a[0], and 0 otherwise.

Parameters

bvals	The upper coefficients
avals	The lower coefficients

◆ setLowpass()

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.

Parameters

frequency The (normalized) cutoff frequency for a lowpass filter

◆ setPole()

void cugl::dsp::OnePoleIIR::setPole ( float pole )

Sets the pole position in the z-plane.

This method sets the pole position along the real-axis of the z-plane and normalizes the coefficients for a maximum gain of one. A positive pole value produces a low-pass filter, while a negative pole value produces a high-pass filter. This method does not affect the filter gain. The argument magnitude should be less than one to maintain filter stability.

Parameters

pole	The filter pole

◆ setTransfer()

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 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.

Parameters

p	The numerator polynomial
q	The denominator polynomial

◆ step()

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 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.

Parameters

gain	The input gain factor
input	The input frame
output	The frame to receive the output

Member Data Documentation

◆ VECTORIZE

bool cugl::dsp::OnePoleIIR::VECTORIZE

static

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

The documentation for this class was generated from the following file:

include/cugl/math/dsp/CUOnePoleIIR.h

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ OnePoleIIR() [1/5]

◆ OnePoleIIR() [2/5]

◆ OnePoleIIR() [3/5]

◆ OnePoleIIR() [4/5]

◆ OnePoleIIR() [5/5]

◆ ~OnePoleIIR()

Member Function Documentation

◆ calculate()

◆ clear()

◆ flush()

◆ getACoeff()

◆ getBCoeff()

◆ getChannels()

◆ getDenominator()

◆ getNumerator()

◆ getPole()

◆ setACoeff()

◆ setBCoeff()

◆ setChannels()

◆ setCoeff()

◆ setLowpass()

◆ setPole()

◆ setTransfer()

◆ step()

Member Data Documentation

◆ VECTORIZE