Basic IIR filtering

Functions
struct iir_coeff_t *	iir_coeff_new (int nc, double *c, int nd, double *d)
	Create general IIR filter.
void	iir_coeff_free (struct iir_coeff_t *coeff)
	Free general IIR filter.
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.

---

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_coeff_t* iir_coeff_new	(	int	nc,
		double *	c,
		int	nd,
		double *	d
	)			[read]

Create general IIR filter.

Parameters:

	nc	Number of c coefficients.
	c	Array of c coefficients.
	nd	Number of d coefficients.
	d	Array of d coefficients.

Returns:

Pointer to new general IIR filter object.

This function creates a new general IIR filter object which may be used to create filter instances through iir_filter_new() or chained on to existing instances through iir_filter().

See Structure of IIR filter for a full explanation of the parameters.

void iir_coeff_free

(

struct iir_coeff_t *

coeff

)

Free general IIR filter.

Parameters:

coeff

Pointer to IIR filter object. May be 0.

Frees a set of IIR filter coefficients previously allocated through iir_coeff_new(). Can be called on a null pointer without consequences. Note that iir_filter_new() and iir_filter_chain() actually store a copy of the coefficients, so it is possible to free coeff even if existing filters are still using its coefficient values.

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.