Using Biquadratic Filter Functions
The vDSP API provides two sets of functions to support single-channel and multichannel biquadratic (IIR) filtering of a signal. These are the
vDSP_biquadm families, respectively.
For an example of biquadratic filters in use, see SignalProcessing: Using Biquadratic Filter Functions. This chapter will make frequent references to this code sample.
In biquadratic filtering, we use a set of individual filter objects called sections. The filters are cascaded: that is, the filters are set up in a sequence, and the entire signal passes through each filter in turn.
To prepare for biquad filtering of a signal, we provide an array of filter coefficients, five for each section: three feedforward coefficients and two feedback coefficients. The layout of this array is described in vDSP Reference and illustrated in SignalProcessing: Using Biquadratic Filter Functions.
CreateSetup function takes the coefficients array and the number of sections as parameters, and returns a setup object.
The setup object is passed into an execution function: either
vDSP_biquad for single-channel filtering, or
vDSP_biquadm for multichannel filtering. The execution function may be called repeatedly using the same setup object for a series of signals.
In single channel filtering, the direct-form 1 state values are explicitly specified to the execution function; whereas for multichannel filtering the state values are opaque to the user and modified by the execution function.
In multichannel filtering, a set of functions is provided for manipulating the state of the setup between calls to the execution function. This is illustrated in SignalProcessing: Using Biquadratic Filter Functions.
Finally, a setup is destroyed by one of the functions
Creating Biquadratic Filter Setups
A setup is an opaque object containing all the information needed to define a cascading biquadratic filter. In multichannel filtering it includes internal state information that can be altered by any function that the setup is passed to. A setup should only be used in one thread at a time.
There are four
vDSP_biquad_CreateSetup: single-channel, single precision; returns a setup of type
vDSP_biquad_CreateSetupD: single-channel, double precision; returns a setup of type
vDSP_biquadm_CreateSetup: multichannel, single precision; returns a setup of type
vDSP_biquadm_CreateSetupD: multichannel, double precision; returns a setup of type
Each of the single-channel functions takes two parameters: an array of filter coefficients, and the number of sections. For the multichannel functions, there is a third parameter, the number of channels.
The array of coefficients should have a length of 5 *
M is the number of channels and
N is the number of sections. For the layout and interpretation of the coefficients, see
vDSP_biquadm_CreateSetup in the reference manual.
Creating setups is a preparation step to be done when a program is starting, or is starting some new phase (e.g., when a communication channel is opened). It should never be done during real-time processing. The setup routine is slow and is called only once to prepare data that can be used many times.
Applying Single-Channel Biquadratic Filters
Each section of a single-channel biquadratic cascade implements a direct-form 1 filter.
The cascade is applied to a signal by passing a setup of type
vDSP_biquad_SetupD to the
vDSP_biquadD function. The other parameters are pointers to input and output signal arrays and their strides, a pointer to an array of “delay” values, and the number of input samples to be processed.
Delay array should have a length equal (2 *
M) + 2, where
M is the number of sections. For further details, see
vDSP_biquad in the reference manual. After this function executes, this array contains the final state data of the filters.
Delay should be initialized to appropriate initial values if they are known, or to zeros otherwise.
vDSP_biquadD executes, the filtered signal data are left in the output array and the final state of the filters is left in
Delay. Thus you can continue processing where you left off, if desired.
Applying Multichannel Biquadratic Filters
Each section of a multichannel biquadratic cascade implements a direct-form 2 filter for each channel.
The cascade is applied to a set of signals by passing a setup of type
vDSP_biquadm_SetupD to the
vDSP_biquadmD function. The other parameters are pointers to input and output signal arrays and their strides, and the number of input samples to be processed. (In multichannel filtering, the filter’s internal state is managed automatically.)
In multichannel filtering, an additional set of functions is available for altering the filter’s internal state or its coefficients between executions:
vDSP_biquadm_CopyStateDcopies the internal state of one setup to another.
vDSP_biquadm_ResetStateDresets the internal state of a setup to what it was when first initialized.
vDSP_biquadm_SetActiveFiltersselects which sections of the filter cascade are active. Inactive sections will be skipped in processing the signal.
vDSP_biquadm_SetCoefficientsDoubleexplicitly sets the values of a range of coefficients.
vDSP_biquadm_SetTargetsDoublesets up a ramped change in the values of a range of filter coefficients, to be applied while the filter is iterating through the input samples. For each coefficient to be changed, a target value, a rate (between 0 and 1), and a threshold (>0) are given. When the filter is applied, at each sample, each coefficient’s value is incremented until the difference between its value and target is less than the specified threshold. The size of the increment is a function of rate and the difference between target and the initial value. For an example of this, see SignalProcessing: Using Biquadratic Filter Functions.
After the execution function finishes, the filtered signal is left in the output array, and the state of the filter is preserved so that you can continue processing from where you left off, or reset the state if desired.