Basic IIR filtering

Functions
struct iir_filter_t *	iir_filter_new (const struct iir_coeff_t *coeff)
	Create IIR filter instance.
void	iir_filter_free (struct iir_filter_t *fi)
	Free IIR filter instance.
void	iir_filter_chain (struct iir_filter_t *fi, const struct iir_coeff_t *coeff)
	Add a further IIR filter to a filter instance.
struct iir_filter_t *	iir_filter_copy (const struct iir_filter_t *fi, int state)
	Create a deep copy of an IIR filter instance.
double	iir_filter (struct iir_filter_t *fi, double samp)
	Process a sample.
int	iir_filter_coeff_sets (const struct iir_filter_t *fi)
	Count number of coefficient sets in IIR filter chain.
struct iir_coeff_t *	iir_filter_coeff_set (const struct iir_filter_t *fi, int idx)
	Get IIR coefficient set from filter chain.

Detailed Description

The functions in this module present a basic interface for representing IIR filters, creating instances of (possibly chained) IIR filters, and filtering an input sample.

A general IIR filter consists of a set of coefficients, and may be created through iir_coeff_new(). The filter object (the opaque struct iir_coeff_t) is then used to instantiate specific filters (the opaque struct iir_filter_t) through iir_filter_new(). Each filter instance may have an arbitrary further number of IIR filters chained on to it through iir_filter_chain(). The filter processes one sample at a time through iir_filter().

Function Documentation

struct iir_filter_t* iir_filter_new ( const struct iir_coeff_t *  coeff )

read

Create IIR filter instance.

Parameters

coeff

Filter coefficients to use.

Returns

Pointer to new instance of IIR filter.

Creates a new instance of a general IIR filter. The set of coefficients coeff is copied into the returned structure, meaning the coefficients can be freed after this function returns if they will not be needed again.

The first sample passed through iir_filter() will be used to set initial conditions (see Structure of IIR filter).

An arbitrary number of further filters may be chained on to the end of this instance through iir_filter_chain().

void iir_filter_free

(

struct iir_filter_t *

fi

)

Free IIR filter instance.

Parameters

fi	Filter object to free. May be 0.

Frees a previously-allocated IIR filter instance. Can be called on a null pointer without consequences.

void iir_filter_chain	(	struct iir_filter_t *	fi,
		const struct iir_coeff_t *	coeff
	)

Add a further IIR filter to a filter instance.

Parameters

fi	Filter instance to chain onto.
coeff	New IIR filter coefficients to add to chain.

Extends an existing IIR filter by chaining a new set of coefficients onto the end. This can be used for >4th order Butterworth filters, for example. This copies the set of coefficients from coeff so the coefficients can be freed after this function returns if they are no longer required.

struct iir_filter_t* iir_filter_copy ( const struct iir_filter_t *  fi, int  state  )

read

Create a deep copy of an IIR filter instance.

Parameters

fi	Filter instance to copy.
state	Non-zero to copy state as well.

Returns

Pointer to newly-allocated filter instance.

Performs a deep copy of the filter instance fi. If state is non-zero, then the internal state of fi is copied as well (otherwise it is as treated as a brand new instance).

double iir_filter	(	struct iir_filter_t *	fi,
		double	samp
	)

Process a sample.

Parameters

fi	Filter object to run.
samp	Input sample x(t).

Returns

Filtered output sample y(t).

Given the input sample x(t) (the parameter samp), runs the filter chain in fi and produces the output sample y(t), which it returns.

int iir_filter_coeff_sets

(

const struct iir_filter_t *

fi

)

Count number of coefficient sets in IIR filter chain.

Parameters

fi	Filter object.

Returns

Number of coefficient sets in chain (≥1).

Returns the number of discrete IIR filter coefficient sets used in the filter object fi. There will always be at least one set.

struct iir_coeff_t* iir_filter_coeff_set ( const struct iir_filter_t *  fi, int  idx  )

read

Get IIR coefficient set from filter chain.

Parameters

fi	Filter object.
idx	Index of coefficient set (0 ≤ idx < iir_filter_coeff_sets()).

Returns

Newly-allocated coefficient set object.

Extracts the IIR filter coefficient set for the given step (idx) in the chain of filters in fi. Returns a newly-allocated filter coefficient set object which can be freed with iir_coeff_free().