/* libiir/src/docs/MainPage.dox
 *
 *  Copyright: ©2010, Laurence Withers.
 *  Author: Laurence Withers <l@lwithers.me.uk>
 *  License: GPLv3
*/

/*! \mainpage

This library allows the implementation of arbitrary IIR filters in C. It has
functions for generating and manipulating filters in terms of coefficients, for
chaining arbitrary filters together, and for generating coefficients for some
common types of filter. See \ref iir_structure for a definition of the IIR
filter equation.

\section creation Filter creation

At a high level, filters may be specified as strings. See \ref string_desc for
the required format and \ref iir_parse() for a C function returning a filter
instance from such a string.

Otherwise, the library user must first create a set of coefficients using
\ref iir_coeff_new(). Any number of filters can then be instantiated using that
set of coefficients with \ref iir_filter_new(), or the coefficients can be
chained on to the end of an existing filter instance with
\ref iir_filter_chain(). See \ref common_filters for functions to generate
coefficients.

\section operation Filter operation

The function \ref iir_filter() will actually process an input sample through the
coefficient chain and produce the output sample. Effectively it produces
<code>y(t)</code> given <code>x(t)</code>.

A filter may be copied, possibly including its state (for initial conditions),
using the function \ref iir_filter_copy().

\section tools Tools

In the <code>tests</code> directory are some simple tools for examining and
experimenting with filters. <code>run_filter</code> takes a stream of input
samples <code>x(t)</code> and produces the filtered output samples
<code>y(t)</code>.

Perhaps more interesting is <code>plot_filter</code> (requires GNUplot to be
installed) which will generate a Bode plot for a given filter chain. Note the
phase response can be a little rough due to the simplistic time-domain analysis
of the output signal's phase.

*/

/* options for text editors
kate: replace-trailing-space-save true; space-indent true; tab-width 4;
vim: expandtab:ts=4:sw=4:syntax=doxygen
*/