c
/
libiir
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Escape IIR in Doxygen strings for upcoming C++ library

This commit is contained in:
Laurence Withers 2014-07-07 13:05:55 +00:00
parent b12a49542a
commit ccc5bc6738
8 changed files with 71 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
src/docs/MainPage.dox
View File

@ -1,16 +1,16 @@
/* libiir/src/docs/MainPage.dox /* libiir/src/docs/MainPage.dox
* *
* Copyright: ©2010, Laurence Withers. * Copyright: ©2010–2014, Laurence Withers.
* Author: Laurence Withers <l@lwithers.me.uk> * Author: Laurence Withers <l@lwithers.me.uk>
* License: GPLv3 * License: GPLv3
*/ */
/*! \mainpage /*! \mainpage
This library allows the implementation of arbitrary IIR filters in C. It has This library allows the implementation of arbitrary %IIR filters in C. It has
functions for generating and manipulating filters in terms of coefficients, for functions for generating and manipulating filters in terms of coefficients, for
chaining arbitrary filters together, and for generating coefficients for some chaining arbitrary filters together, and for generating coefficients for some
common types of filter. See \ref iir_structure for a definition of the IIR common types of filter. See \ref iir_structure for a definition of the %IIR
filter equation. filter equation.
\section creation Filter creation \section creation Filter creation
@ -47,6 +47,11 @@ 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 phase response can be a little rough due to the simplistic time-domain analysis
of the output signal's phase. of the output signal's phase.
\section cpp C++
Two C++ wrapper objects, \ref IIR::Coeff and \ref IIR::Filter, are supplied which provide
a true object-oriented interface on top of the C implementation.
*/ */
/* options for text editors /* options for text editors

4
src/docs/iir_structure.dox
View File

@ -1,6 +1,6 @@
/* libiir/src/docs/iir_structure.dox /* libiir/src/docs/iir_structure.dox
* *
* Copyright: ©2010–2011, Laurence Withers. * Copyright: ©2010–2014, Laurence Withers.
* Author: Laurence Withers <l@lwithers.me.uk> * Author: Laurence Withers <l@lwithers.me.uk>
* License: GPLv3 * License: GPLv3
*/ */
@ -14,7 +14,7 @@ For the purposes of this library, the following notation is used:
\li <code>c[n]</code>: array of \c x(t) coefficients \li <code>c[n]</code>: array of \c x(t) coefficients
\li <code>d[n]</code>: array of \c y(t) coefficients \li <code>d[n]</code>: array of \c y(t) coefficients
This leads to a general IIR filter equation: This leads to a general %IIR filter equation:
<code>y(t) = x(t).c[0] + x(t-1).c[1] + … + x(t-N).c[N] - y(t-1).d[0] - y(t-2).d[1] - … - y(t-1-M).d[M]</code> <code>y(t) = x(t).c[0] + x(t-1).c[1] + … + x(t-N).c[N] - y(t-1).d[0] - y(t-2).d[1] - … - y(t-1-M).d[M]</code>

8
src/docs/string_desc.dox
View File

@ -1,17 +1,17 @@
/* libiir/src/docs/string_desc.dox /* libiir/src/docs/string_desc.dox
* *
* Copyright: ©2010, Laurence Withers. * Copyright: ©2010–2014, Laurence Withers.
* Author: Laurence Withers <l@lwithers.me.uk> * Author: Laurence Withers <l@lwithers.me.uk>
* License: GPLv3 * License: GPLv3
*/ */
/*! \page string_desc Describing IIR filters as strings /*! \page string_desc Describing IIR filters as strings
This library allows the user to describe an IIR filter chain as a string, which This library allows the user to describe an %IIR filter chain as a string, which
is useful to allow configurable filtering using e.g. a configuration file. This is useful to allow configurable filtering using e.g. a configuration file. This
page describes the format of such strings. page describes the format of such strings.
The string is first split into individual IIR filters. Each filter is written as The string is first split into individual %IIR filters. Each filter is written as
\c type(params) and separated by whitespace. The string must contain at least \c type(params) and separated by whitespace. The string must contain at least
one filter but may contain an arbitrary number. one filter but may contain an arbitrary number.
@ -23,7 +23,7 @@ one filter but may contain an arbitrary number.
\subsection string_desc_coeff Raw coefficients \subsection string_desc_coeff Raw coefficients
An IIR filter may be specified as raw coefficients, in which case the \c type An %IIR filter may be specified as raw coefficients, in which case the \c type
is \c raw and the \c params consists of a string: is \c raw and the \c params consists of a string:
<code>c[0],c[1],…,c[n]/d[0],d[1]…d[n]</code> <code>c[0],c[1],…,c[n]/d[0],d[1]…d[n]</code>

34
src/libiir/100_coeff.h
View File

@ -12,10 +12,10 @@
\ingroup libiir \ingroup libiir
The functions in this module present an interface for managing the set of The functions in this module present an interface for managing the set of
coefficients of a single IIR filter instance. See \ref iir_structure for coefficients of a single %IIR filter instance. See \ref iir_structure for
the definition of a coefficient set. The coefficient sets form the the definition of a coefficient set. The coefficient sets form the
basic building block of an IIR filter instance (see \ref libiir_filter), basic building block of an %IIR filter instance (see \ref libiir_filter),
which may chain several IIR filters in sequence. which may chain several %IIR filters in sequence.
*/ */
/*!@{*/ /*!@{*/
@ -27,15 +27,15 @@ struct iir_coeff_t;
/*! \brief Create IIR coefficient set /*! \brief Create %IIR coefficient set
\param nc Number of \a c coefficients. \param nc Number of \a c coefficients.
\param c Array of \a c coefficients. \param c Array of \a c coefficients.
\param nd Number of \a d coefficients. \param nd Number of \a d coefficients.
\param d Array of \a d coefficients. \param d Array of \a d coefficients.
\returns Pointer to new general IIR filter object. \returns Pointer to new general %IIR filter object.
This function creates a new set of IIR filter coefficients which may be used to This function creates a new set of %IIR filter coefficients which may be used to
create filter instances through \ref iir_filter_new() or chained on to existing create filter instances through \ref iir_filter_new() or chained on to existing
instances through \ref iir_filter(). instances through \ref iir_filter().
@ -51,23 +51,23 @@ struct iir_coeff_t* iir_coeff_new(int nc, const double* c, int nd,
/*! \brief Create copy of a set of IIR coefficients /*! \brief Create copy of a set of %IIR coefficients
\param other Set of IIR filter coefficients to copy. \param other Set of %IIR filter coefficients to copy.
\returns Pointer to new general IIR filter object. \returns Pointer to new general %IIR filter object.
Performs a deep copy of the set of IIR coefficients contained within \a other. Performs a deep copy of the set of %IIR coefficients contained within \a other.
*/ */
struct iir_coeff_t* iir_coeff_copy(const struct iir_coeff_t* other); struct iir_coeff_t* iir_coeff_copy(const struct iir_coeff_t* other);
/*! \brief Free IIR coefficient set /*! \brief Free %IIR coefficient set
\param coeff Pointer to IIR coefficient object. May be 0. \param coeff Pointer to %IIR coefficient object. May be 0.
Frees a set of IIR filter coefficients previously allocated through Frees a set of %IIR filter coefficients previously allocated through
\ref iir_coeff_new(). Can be called on a null pointer without consequences. \ref iir_coeff_new(). Can be called on a null pointer without consequences.
Note that \ref iir_filter_new() and \ref iir_filter_chain() actually store a Note that \ref iir_filter_new() and \ref iir_filter_chain() actually store a
copy of the coefficients, so it is possible to free \a coeff even if existing copy of the coefficients, so it is possible to free \a coeff even if existing
@ -80,7 +80,7 @@ void iir_coeff_free(struct iir_coeff_t* coeff);
/*! \brief Query number of C coefficients. /*! \brief Query number of C coefficients.
\param coeff Pointer to IIR coefficient object. \param coeff Pointer to %IIR coefficient object.
\returns Number of C coefficients (≥1). \returns Number of C coefficients (≥1).
*/ */
@ -90,7 +90,7 @@ int iir_coeff_get_nc(const struct iir_coeff_t* coeff);
/*! \brief Query number of D coefficients. /*! \brief Query number of D coefficients.
\param coeff Pointer to IIR coefficient object. \param coeff Pointer to %IIR coefficient object.
\returns Number of D coefficients (≥1). \returns Number of D coefficients (≥1).
*/ */
@ -100,7 +100,7 @@ int iir_coeff_get_nd(const struct iir_coeff_t* coeff);
/*! \brief Get value of C coefficient. /*! \brief Get value of C coefficient.
\param coeff Pointer to IIR coefficient object. \param coeff Pointer to %IIR coefficient object.
\param idx Index of coefficient (≥0, < \ref iir_coeff_get_nc()). \param idx Index of coefficient (≥0, < \ref iir_coeff_get_nc()).
\returns C coefficient value. \returns C coefficient value.
@ -111,7 +111,7 @@ double iir_coeff_get_c(const struct iir_coeff_t* coeff, int idx);
/*! \brief Get value of D coefficient. /*! \brief Get value of D coefficient.
\param coeff Pointer to IIR coefficient object. \param coeff Pointer to %IIR coefficient object.
\param idx Index of coefficient (≥0, < \ref iir_coeff_get_nd()). \param idx Index of coefficient (≥0, < \ref iir_coeff_get_nd()).
\returns D coefficient value. \returns D coefficient value.

34
src/libiir/200_filter.h
View File

@ -11,15 +11,15 @@
\ingroup libiir \ingroup libiir
The functions in this module present a basic interface for representing IIR The functions in this module present a basic interface for representing %IIR
filters, creating instances of (possibly chained) IIR filters, and filtering an filters, creating instances of (possibly chained) %IIR filters, and filtering an
input sample. input sample.
A general IIR filter consists of a set of coefficients, and may be created A general %IIR filter consists of a set of coefficients, and may be created
through \ref iir_coeff_new(). The filter object (the opaque <code>struct through \ref iir_coeff_new(). The filter object (the opaque <code>struct
iir_coeff_t</code>) is then used to instantiate specific filters (the opaque iir_coeff_t</code>) is then used to instantiate specific filters (the opaque
<code>struct iir_filter_t</code>) through \ref iir_filter_new(). Each filter <code>struct iir_filter_t</code>) through \ref iir_filter_new(). Each filter
instance may have an arbitrary further number of IIR filters chained on to it instance may have an arbitrary further number of %IIR filters chained on to it
through \ref iir_filter_chain(). The filter processes one sample at a time through \ref iir_filter_chain(). The filter processes one sample at a time
through \ref iir_filter(). through \ref iir_filter().
@ -33,12 +33,12 @@ struct iir_filter_t;
/*! \brief Create IIR filter instance /*! \brief Create %IIR filter instance
\param coeff Filter coefficients to use. \param coeff Filter coefficients to use.
\returns Pointer to new instance of IIR filter. \returns Pointer to new instance of %IIR filter.
Creates a new instance of a general IIR filter. The set of coefficients \a coeff Creates a new instance of a general %IIR filter. The set of coefficients \a coeff
is copied into the returned structure, meaning the coefficients can be freed is copied into the returned structure, meaning the coefficients can be freed
after this function returns if they will not be needed again. after this function returns if they will not be needed again.
@ -57,11 +57,11 @@ struct iir_filter_t* iir_filter_new(const struct iir_coeff_t* coeff)
/*! \brief Free IIR filter instance /*! \brief Free %IIR filter instance
\param fi Filter object to free. May be 0. \param fi Filter object to free. May be 0.
Frees a previously-allocated IIR filter instance. Can be called on a null Frees a previously-allocated %IIR filter instance. Can be called on a null
pointer without consequences. pointer without consequences.
*/ */
@ -69,12 +69,12 @@ void iir_filter_free(struct iir_filter_t* fi);
/*! \brief Add a further IIR filter to a filter instance /*! \brief Add a further %IIR filter to a filter instance
\param fi Filter instance to chain onto. \param fi Filter instance to chain onto.
\param coeff New IIR filter coefficients to add to chain. \param coeff New %IIR filter coefficients to add to chain.
Extends an existing IIR filter by chaining a new set of coefficients onto the Extends an existing %IIR filter by chaining a new set of coefficients onto the
end. This can be used for &gt;4th order Butterworth filters, for example. This end. This can be used for &gt;4th order Butterworth filters, for example. This
copies the set of coefficients from \a coeff so the coefficients can be freed copies the set of coefficients from \a coeff so the coefficients can be freed
after this function returns if they are no longer required. after this function returns if they are no longer required.
@ -88,7 +88,7 @@ void iir_filter_chain(struct iir_filter_t* fi, const struct iir_coeff_t* coeff)
/*! \brief Create a deep copy of an IIR filter instance /*! \brief Create a deep copy of an %IIR filter instance
\param fi Filter instance to copy. \param fi Filter instance to copy.
\param state Non-zero to copy state as well. \param state Non-zero to copy state as well.
@ -121,12 +121,12 @@ double iir_filter(struct iir_filter_t* fi, double samp);
/*! \brief Count number of coefficient sets in IIR filter chain /*! \brief Count number of coefficient sets in %IIR filter chain
\param fi Filter object. \param fi Filter object.
\returns Number of coefficient sets in chain (≥1). \returns Number of coefficient sets in chain (≥1).
Returns the number of discrete IIR filter coefficient sets used in the filter Returns the number of discrete %IIR filter coefficient sets used in the filter
object \a fi. There will always be at least one set. object \a fi. There will always be at least one set.
*/ */
@ -134,13 +134,13 @@ int iir_filter_coeff_sets(const struct iir_filter_t* fi);
/*! \brief Get IIR coefficient set from filter chain /*! \brief Get %IIR coefficient set from filter chain
\param fi Filter object. \param fi Filter object.
\param idx Index of coefficient set (0 ≤ \a idx &lt; \ref iir_filter_coeff_sets()). \param idx Index of coefficient set (0 ≤ \a idx &lt; \ref iir_filter_coeff_sets()).
\returns Newly-allocated coefficient set object. \returns Newly-allocated coefficient set object.
Extracts the IIR filter coefficient set for the given step (\a idx) in the chain Extracts the %IIR filter coefficient set for the given step (\a idx) in the chain
of filters in \a fi. Returns a newly-allocated filter coefficient set object of filters in \a fi. Returns a newly-allocated filter coefficient set object
which can be freed with \ref iir_coeff_free(). which can be freed with \ref iir_coeff_free().

20
src/libiir/300_common_filters.h
View File

@ -11,8 +11,8 @@
\ingroup libiir \ingroup libiir
Functions to create coefficients for various common types of IIR filter. The Functions to create coefficients for various common types of %IIR filter. The
coefficient structures which are returned may be used to instantiate IIR coefficient structures which are returned may be used to instantiate %IIR
filters using \ref iir_filter_new(). filters using \ref iir_filter_new().
The Butterworth filter code comes from the Exstrom Labs LLC code available under The Butterworth filter code comes from the Exstrom Labs LLC code available under
@ -30,7 +30,7 @@ is a copy of the original code available in the top level of this project.
\param gain Linear gain of filter. \param gain Linear gain of filter.
\param corner Corner frequency expressed as a fraction of Nyquist \param corner Corner frequency expressed as a fraction of Nyquist
(0 ≤ \a corner ≤ 1) (0 ≤ \a corner ≤ 1)
\returns Newly-allocated IIR filter coefficients. \returns Newly-allocated %IIR filter coefficients.
Uses the Exstrom labs code to compute the coefficients of an nth-order (param Uses the Exstrom labs code to compute the coefficients of an nth-order (param
\a order) Butterworth-type low pass filter with gain \a gain and corner \a order) Butterworth-type low pass filter with gain \a gain and corner
@ -41,7 +41,7 @@ greater than a 4th-order filter. This function won't do that directly for you.
\a gain will usually be set to be 1.0. \a gain will usually be set to be 1.0.
The corner frequency \a corner is expressed as a fraction of the sampling The corner frequency \a corner is expressed as a fraction of the sampling
frequency (which is of course not known by the IIR code). It should lie between frequency (which is of course not known by the %IIR code). It should lie between
0 (0Hz) and 1 (the Nyquist frequency, or ½ the sampling frequency). 0 (0Hz) and 1 (the Nyquist frequency, or ½ the sampling frequency).
*/ */
@ -61,7 +61,7 @@ struct iir_coeff_t* iir_butterworth_lowpass(int order,
\param gain Linear gain of filter. \param gain Linear gain of filter.
\param corner Corner frequency expressed as a fraction of Nyquist \param corner Corner frequency expressed as a fraction of Nyquist
(0 ≤ \a corner ≤ 1) (0 ≤ \a corner ≤ 1)
\returns Newly-allocated IIR filter coefficients. \returns Newly-allocated %IIR filter coefficients.
Uses the Exstrom labs code to compute the coefficients of an nth-order (param Uses the Exstrom labs code to compute the coefficients of an nth-order (param
\a order) Butterworth-type high pass filter with gain \a gain and corner \a order) Butterworth-type high pass filter with gain \a gain and corner
@ -72,7 +72,7 @@ greater than a 4th-order filter. This function won't do that directly for you.
\a gain will usually be set to be 1.0. \a gain will usually be set to be 1.0.
The corner frequency \a corner is expressed as a fraction of the sampling The corner frequency \a corner is expressed as a fraction of the sampling
frequency (which is of course not known by the IIR code). It should lie between frequency (which is of course not known by the %IIR code). It should lie between
0 (0Hz) and 1 (the Nyquist frequency, or ½ the sampling frequency). 0 (0Hz) and 1 (the Nyquist frequency, or ½ the sampling frequency).
*/ */
@ -94,7 +94,7 @@ struct iir_coeff_t* iir_butterworth_highpass(int order,
(0 ≤ \a c1 ≤ 1) (0 ≤ \a c1 ≤ 1)
\param c2 High corner frequency expressed as a fraction of Nyquist \param c2 High corner frequency expressed as a fraction of Nyquist
(0 ≤ \a c2 ≤ 1, and \a c1 &lt; \a c2) (0 ≤ \a c2 ≤ 1, and \a c1 &lt; \a c2)
\returns Newly-allocated IIR filter coefficients. \returns Newly-allocated %IIR filter coefficients.
Uses the Exstrom labs code to compute the coefficients of an nth-order (param Uses the Exstrom labs code to compute the coefficients of an nth-order (param
\a order) Butterworth-type band pass filter with gain \a gain and corner \a order) Butterworth-type band pass filter with gain \a gain and corner
@ -105,7 +105,7 @@ greater than a 4th-order filter. This function won't do that directly for you.
\a gain will usually be set to be 1.0. \a gain will usually be set to be 1.0.
The corner frequencies \a c1 and \a c2 are expressed as a fraction of the The corner frequencies \a c1 and \a c2 are expressed as a fraction of the
sampling frequency (which is of course not known by the IIR code). They should sampling frequency (which is of course not known by the %IIR code). They should
lie between 0 (0Hz) and 1 (the Nyquist frequency, or ½ the sampling frequency), lie between 0 (0Hz) and 1 (the Nyquist frequency, or ½ the sampling frequency),
and \a c2 should be greater than \a c1. and \a c2 should be greater than \a c1.
@ -129,7 +129,7 @@ struct iir_coeff_t* iir_butterworth_bandpass(int order,
(0 ≤ \a c1 ≤ 1) (0 ≤ \a c1 ≤ 1)
\param c2 High corner frequency expressed as a fraction of Nyquist \param c2 High corner frequency expressed as a fraction of Nyquist
(0 ≤ \a c2 ≤ 1, and \a c1 &lt; \a c2) (0 ≤ \a c2 ≤ 1, and \a c1 &lt; \a c2)
\returns Newly-allocated IIR filter coefficients. \returns Newly-allocated %IIR filter coefficients.
Uses the Exstrom labs code to compute the coefficients of an nth-order (param Uses the Exstrom labs code to compute the coefficients of an nth-order (param
\a order) Butterworth-type band stop filter with gain \a gain and corner \a order) Butterworth-type band stop filter with gain \a gain and corner
@ -140,7 +140,7 @@ greater than a 4th-order filter. This function won't do that directly for you.
\a gain will usually be set to be 1.0. \a gain will usually be set to be 1.0.
The corner frequencies \a c1 and \a c2 are expressed as a fraction of the The corner frequencies \a c1 and \a c2 are expressed as a fraction of the
sampling frequency (which is of course not known by the IIR code). They should sampling frequency (which is of course not known by the %IIR code). They should
lie between 0 (0Hz) and 1 (the Nyquist frequency, or ½ the sampling frequency), lie between 0 (0Hz) and 1 (the Nyquist frequency, or ½ the sampling frequency),
and \a c2 should be greater than \a c1. and \a c2 should be greater than \a c1.

24
src/libiir/400_parser.h
View File

@ -11,9 +11,9 @@
\ingroup libiir \ingroup libiir
This is a high-level interface that can instantiate a set of IIR filters based This is a high-level interface that can instantiate a set of %IIR filters based
on a user-specified, human-readable string. The intention of this interface is on a user-specified, human-readable string. The intention of this interface is
to allow IIR filters to be specified in configuration files so that they can be to allow %IIR filters to be specified in configuration files so that they can be
easily modified by the user and easily understood/parsed by the system. easily modified by the user and easily understood/parsed by the system.
See \ref string_desc for details on the string description format. See \ref string_desc for details on the string description format.
@ -23,14 +23,14 @@ See \ref string_desc for details on the string description format.
/*! \brief Instantiate an IIR filter based on a string description /*! \brief Instantiate an %IIR filter based on a string description
\param desc IIR filter description. \param desc %IIR filter description.
\returns Pointer to newly-allocated IIR filter instance. \returns Pointer to newly-allocated %IIR filter instance.
\retval 0 on error. \retval 0 on error.
Parses the human-readable description of an IIR filter chain in \a desc, Parses the human-readable description of an %IIR filter chain in \a desc,
instantiating an IIR filter object to match. Returns the new filter. If \a desc instantiating an %IIR filter object to match. Returns the new filter. If \a desc
cannot be parsed correctly, returns 0 and sets \a errno to \c EINVAL. cannot be parsed correctly, returns 0 and sets \a errno to \c EINVAL.
*/ */
@ -42,15 +42,15 @@ struct iir_filter_t* iir_parse(const char* desc)
/*! \brief Instantiate a set of IIR filters based on a string description /*! \brief Instantiate a set of %IIR filters based on a string description
\param desc IIR filter description. \param desc %IIR filter description.
\param n Number of instances to allocate. \param n Number of instances to allocate.
\returns Pointer to array of \a n newly-allocated IIR filter instances. \returns Pointer to array of \a n newly-allocated %IIR filter instances.
\retval 0 on error. \retval 0 on error.
Parses the human-readable description of an IIR filter chain in \a desc, Parses the human-readable description of an %IIR filter chain in \a desc,
instantiating a set of \a n identical IIR filter objects to match. Returns a instantiating a set of \a n identical %IIR filter objects to match. Returns a
pointer to an array of new filters. If \a desc cannot be parsed correctly, pointer to an array of new filters. If \a desc cannot be parsed correctly,
returns 0 and sets \a errno to \c EINVAL. returns 0 and sets \a errno to \c EINVAL.

2
src/libiir/500_response.h
View File

@ -11,7 +11,7 @@
\ingroup libiir \ingroup libiir
These functions allow measuring the IIR response (i.e. frequency and phase of These functions allow measuring the %IIR response (i.e. frequency and phase of
the transfer function) at a given frequency. The response is a complex number; the transfer function) at a given frequency. The response is a complex number;
see \c complex(5) for details. The magnitude \c cabs(z) is the gain of the see \c complex(5) for details. The magnitude \c cabs(z) is the gain of the
filter and the phase \c carg(z) its phase delay. filter and the phase \c carg(z) its phase delay.