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

#include <CUOneZeroFIR.h>

Public Member Functions

 OneZeroFIR ()
 
 OneZeroFIR (unsigned channels)
 
 OneZeroFIR (unsigned channels, float b0, float b1)
 
 OneZeroFIR (const OneZeroFIR &copy)
 
 OneZeroFIR (OneZeroFIR &&filter)
 
 ~OneZeroFIR ()
 
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 getZero () const
 
void setZero (float zero)
 
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-zero digital filter.

There is a method to set the zero position along the real axis of the z-plane while maintaining a constant filter gain.

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

◆ OneZeroFIR() [1/5]

cugl::dsp::OneZeroFIR::OneZeroFIR ( )

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

◆ OneZeroFIR() [2/5]

cugl::dsp::OneZeroFIR::OneZeroFIR ( unsigned  channels)

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

Parameters
channelsThe number of channels

◆ OneZeroFIR() [3/5]

cugl::dsp::OneZeroFIR::OneZeroFIR ( unsigned  channels,
float  b0,
float  b1 
)

Creates a FIR filter with the given coefficients and number of channels.

This filter implements the standard difference equation:

 y[n] = b[0]*x[n] + b[1]*x[n-1]

where y is the output and x in the input.

Parameters
channelsThe number of channels
b0The upper zero-order coefficient
b1The upper first-order coefficient

◆ OneZeroFIR() [4/5]

cugl::dsp::OneZeroFIR::OneZeroFIR ( const OneZeroFIR copy)

Creates a copy of the FIR filter.

Parameters
copyThe filter to copy

◆ OneZeroFIR() [5/5]

cugl::dsp::OneZeroFIR::OneZeroFIR ( OneZeroFIR &&  filter)

Creates a FIR filter with the resources of the original.

Parameters
filterThe filter to acquire

◆ ~OneZeroFIR()

cugl::dsp::OneZeroFIR::~OneZeroFIR ( )

Destroys the filter, releasing all resources.

Member Function Documentation

◆ calculate()

void cugl::dsp::OneZeroFIR::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::OneZeroFIR::clear ( )

Clears the filter buffer of any delayed outputs or cached inputs

◆ flush()

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

Flushes any delayed outputs to the provided array

As this filter has no delayed terms, this method will write nothing. It is only here to standardize the filter signature.

Returns
The number of frames (not samples) written

◆ getACoeff()

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

◆ getZero()

float cugl::dsp::OneZeroFIR::getZero ( ) const

Returns the zero position in the z-plane.

A positive zero value produces a high-pass filter, while a negative pole value produces a low-pass filter.

Returns
the zero position in the z-plane.

◆ setBCoeff()

void cugl::dsp::OneZeroFIR::setBCoeff ( float  b0,
float  b1 
)

Sets the coefficients for this IIR filter.

This filter implements the standard difference equation:

 y[n] = b[0]*x[n] + b[1]*x[n-1]

where y is the output and x in the input.

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

◆ setChannels()

void cugl::dsp::OneZeroFIR::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::OneZeroFIR::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]

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 other a-coefficients are ignored (they are only present for signature standardization). Similarly, all b-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
bvalsThe upper coefficients
avalsThe lower coefficients

◆ setZero()

void cugl::dsp::OneZeroFIR::setZero ( float  zero)

Sets the zero position in the z-plane.

This method sets the zero 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 high-pass filter, while a negative pole value produces a low-pass filter. This method does not affect the filter gain.

Parameters
zeroThe filter zero

◆ step()

void cugl::dsp::OneZeroFIR::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::OneZeroFIR::VECTORIZE
static

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


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