CUGL 2.0
Cornell University Game Library
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
cugl::dsp::BiquadIIR Class Reference

#include <CUBiquadIIR.h>

Public Types

enum  Type : int {
  Type::UNDEFINED = 0, Type::LOWPASS = 1, Type::HIGHPASS = 2, Type::BANDPASS = 3,
  Type::ALLPASS = 4, Type::NOTCH = 5, Type::PEAK = 6, Type::LOWSHELF = 7,
  Type::HIGHSHELF = 8, Type::RESONANCE = 9
}
 

Public Member Functions

 BiquadIIR ()
 
 BiquadIIR (unsigned channels)
 
 BiquadIIR (unsigned channels, Type type, float frequency, float gainDB, float qVal=INV_SQRT2)
 
 BiquadIIR (const BiquadIIR &copy)
 
 BiquadIIR (BiquadIIR &&filter)
 
 ~BiquadIIR ()
 
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 setBCoeff (float b0, float b1, float b2)
 
void setACoeff (float a1, float a2)
 
void setType (Type type, float frequency, float gainDB, float qVal=INV_SQRT2)
 
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 Member Functions

static float db2gain (float gainDB)
 
static float gain2db (float gain)
 
static float bandwidth2q (float width)
 
static float q2Bandwidth (float qVal)
 

Static Public Attributes

static bool VECTORIZE
 

Detailed Description

This class implements a biquad digital filter.

This is the most efficient filter acceptable for a parametric equalizer. As such, this filter has several types for quick creation of parameteric components. However, in most settings Butterworth filters are preferred because they have better roll off.

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. However, filters are not intended to be model classes, and so it does not save the defining frequency.

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

Member Enumeration Documentation

◆ Type

enum cugl::dsp::BiquadIIR::Type : int
strong

The underlying type of the biquad filter.

Most biquad filters are intended for a parameteric equalizer, and so will have one of the filters types below. If the coefficients of the biquad filter are set directly, it will have type UNDEFINED.

Enumerator
UNDEFINED 

For direct coefficient manipulation

LOWPASS 

A second-order lowpass filter

HIGHPASS 

A second-order lowpass filter

BANDPASS 

A second-order bandpass filter

ALLPASS 

A second-order allpass filter

NOTCH 

Inverse of a bandpass (called a band-stop)

PEAK 

Parametric equalizer

LOWSHELF 

The inverse of a lowpass

HIGHSHELF 

The inverse of a highpass

RESONANCE 

A resonance filter with radius Q

Constructor & Destructor Documentation

◆ BiquadIIR() [1/5]

cugl::dsp::BiquadIIR::BiquadIIR ( )

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

◆ BiquadIIR() [2/5]

cugl::dsp::BiquadIIR::BiquadIIR ( unsigned  channels)

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

Parameters
channelsThe number of channels

◆ BiquadIIR() [3/5]

cugl::dsp::BiquadIIR::BiquadIIR ( unsigned  channels,
Type  type,
float  frequency,
float  gainDB,
float  qVal = INV_SQRT2 
)

Creates a special purpose filter of the given type

In addition to the type, the filter is defined by the target frequency and the gain for that frequency (which may be negative). This gain will be applied to the target frequency, but will roll-off or attenuate for other frequencies according to the type. The gain is specified in decibels, not as a multiplicative factor.

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.

The Q factor is the inverse of the bandwidth, and is generally only relevant for the BANDPASS and BANDSTOP filter types. For the other types, the default value of 1/sqrt(2) is generally sufficient. For BANDPASS and BANDSTOP, the bandwidth2q() value produces the appropriate value for proper filter design.

Filters are not intended to be model classes, and so it does not save the defining frequency, type, gain, or other values.

If the type is undefined, the frequency and peakGain will be ignored, creating a pass-through filter.

Parameters
channelsThe number of channels to process
typeThe filter type
frequencyThe (normalized) target frequency
gainDBThe gain at the target frequency in decibels
qValThe special Q factor

◆ BiquadIIR() [4/5]

cugl::dsp::BiquadIIR::BiquadIIR ( const BiquadIIR copy)

Creates a copy of the biquad filter.

Parameters
copyThe filter to copy

◆ BiquadIIR() [5/5]

cugl::dsp::BiquadIIR::BiquadIIR ( BiquadIIR &&  filter)

Creates a biquad filter with the resources of the original.

Parameters
filterThe filter to acquire

◆ ~BiquadIIR()

cugl::dsp::BiquadIIR::~BiquadIIR ( )

Destroys the filter, releasing all resources.

Member Function Documentation

◆ bandwidth2q()

static float cugl::dsp::BiquadIIR::bandwidth2q ( float  width)
static

Returns the q value for the given the filter bandwidth (in octaves)

The filter bandwidth is generally only relevant for the BANDPASS and BANDSTOP filter types. For the other types, the q value of 1/sqrt(2) is generally sufficient.

Parameters
widthThe filter bandwidth in octaves
Returns
the q value for the given the filter bandwidth

◆ calculate()

void cugl::dsp::BiquadIIR::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
gainThe input gain factor
inputThe array of input samples
outputThe array to write the sample output
sizeThe input size in frames

◆ clear()

void cugl::dsp::BiquadIIR::clear ( )

Clears the filter buffer of any delayed outputs or cached inputs

◆ db2gain()

static float cugl::dsp::BiquadIIR::db2gain ( float  gainDB)
static

Returns the gain factor for given value in decibels.

The factor is the amount to multiply the amplitude signal. The provided value is represented in decibels, so there may be some round-off error in conversion.

Parameters
gainDBThe audio gain in decibels
Returns
The gain factor for given value in decibels.

◆ flush()

size_t cugl::dsp::BiquadIIR::flush ( float *  output)

Flushes any delayed outputs to the provided array

The array size should be twice the number of channels. This method will also clear the buffer.

Returns
The number of frames (not samples) written

◆ gain2db()

static float cugl::dsp::BiquadIIR::gain2db ( float  gain)
static

Returns the decibel gain for given factor.

The factor is the amount to multiply the amplitude signal. The returned result is in decibels, so there may be some round-off error in conversion.

Parameters
gainThe audio gain factor
Returns
The decibel gain for given factor.

◆ getACoeff()

const std::vector<float> cugl::dsp::BiquadIIR::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::BiquadIIR::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::BiquadIIR::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

◆ q2Bandwidth()

static float cugl::dsp::BiquadIIR::q2Bandwidth ( float  qVal)
static

Returns the filter bandwidth (in octaves) for the given q value

The filter bandwidth is generally only relevant for the BANDPASS and BANDSTOP filter types. For the other types, the q value of 1/sqrt(2) is generally sufficient.

Parameters
qValThe special Q factor
Returns
the filter bandwidth (in octaves) for the given q value

◆ setACoeff()

void cugl::dsp::BiquadIIR::setACoeff ( float  a1,
float  a2 
)

Sets the lower coefficients.

Setting this leaves the upper coefficients unchanged.

Parameters
a1The lower first-order coefficient
a2The lower second-order coefficient

◆ setBCoeff()

void cugl::dsp::BiquadIIR::setBCoeff ( float  b0,
float  b1,
float  b2 
)

Sets the upper coefficients.

Setting this leaves the lower coefficients unchanged.

Parameters
b0The upper zero-order coefficient
b1The upper first-order coefficient
b2The upper second-order coefficient

◆ setChannels()

void cugl::dsp::BiquadIIR::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
channelsThe number of channels for this filter

◆ setCoeff()

void cugl::dsp::BiquadIIR::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 and a-coefficients after the third are ignored. If any coefficients are missing, they are replaced with 1 for b[0] and a[0], and 0 otherwise.

Parameters
bvalsThe upper coefficients
avalsThe lower coefficients

◆ setType()

void cugl::dsp::BiquadIIR::setType ( Type  type,
float  frequency,
float  gainDB,
float  qVal = INV_SQRT2 
)

Sets this filter to the special purpose one of the given type

In addition to the type, the filter is defined by the target frequency and the gain for that frequency (which may be negative). This gain will be applied to the target frequency, but will roll-off or attenuate for other frequencies according to the type. The gain is specified in decibels, not as a multiplicative factor,

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.

The Q factor is the inverse of the bandwidth, and is generally only relevant for the BANDPASS and BANDSTOP filter types. For the other types, the default value of 1/sqrt(2) is generally sufficient. For BANDPASS and BANDSTOP, the bandwidth2q() value produces the appropriate value for proper filter design.

Filters are not intended to be model classes, and so it does not save the defining frequency, type, gain, or other values.

If the type is undefined, the frequency and peakGain will be ignored, creating a pass-through filter.

Parameters
typeThe filter type
frequencyThe (normalized) target frequency
gainDBThe gain at the target frequency in decibels
qValThe special Q factor

◆ step()

void cugl::dsp::BiquadIIR::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
gainThe input gain factor
inputThe input frame
outputThe frame to receive the output

Member Data Documentation

◆ VECTORIZE

bool cugl::dsp::BiquadIIR::VECTORIZE
static

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


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