Escape IIR in Doxygen strings for upcoming C++ library
This commit is contained in:
Laurence Withers
parent
b12a49542a
commit
ccc5bc6738
|
|
@ -1,16 +1,16 @@
|
|||
/* libiir/src/docs/MainPage.dox
|
||||
*
|
||||
* Copyright: ©2010, Laurence Withers.
|
||||
* Copyright: ©2010–2014, 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
|
||||
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
|
||||
common types of filter. See \ref iir_structure for a definition of the %IIR
|
||||
filter equation.
|
||||
|
||||
\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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/* libiir/src/docs/iir_structure.dox
|
||||
*
|
||||
* Copyright: ©2010–2011, Laurence Withers.
|
||||
* Copyright: ©2010–2014, Laurence Withers.
|
||||
* Author: Laurence Withers <l@lwithers.me.uk>
|
||||
* 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>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>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,17 +1,17 @@
|
|||
/* libiir/src/docs/string_desc.dox
|
||||
*
|
||||
* Copyright: ©2010, Laurence Withers.
|
||||
* Copyright: ©2010–2014, Laurence Withers.
|
||||
* Author: Laurence Withers <l@lwithers.me.uk>
|
||||
* License: GPLv3
|
||||
*/
|
||||
|
||||
/*! \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
|
||||
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
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
<code>c[0],c[1],…,c[n]/d[0],d[1]…d[n]</code>
|
||||
|
|
|
|||
|
|
@ -12,10 +12,10 @@
|
|||
\ingroup libiir
|
||||
|
||||
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
|
||||
basic building block of an IIR filter instance (see \ref libiir_filter),
|
||||
which may chain several IIR filters in sequence.
|
||||
basic building block of an %IIR filter instance (see \ref libiir_filter),
|
||||
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 c Array of \a c coefficients.
|
||||
\param nd Number 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
|
||||
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.
|
||||
\returns Pointer to new general IIR filter object.
|
||||
\param other Set of %IIR filter coefficients to copy.
|
||||
\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);
|
||||
|
||||
|
||||
|
||||
/*! \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.
|
||||
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
|
||||
|
|
@ -80,7 +80,7 @@ void iir_coeff_free(struct iir_coeff_t* coeff);
|
|||
|
||||
/*! \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).
|
||||
|
||||
*/
|
||||
|
|
@ -90,7 +90,7 @@ int iir_coeff_get_nc(const struct iir_coeff_t* coeff);
|
|||
|
||||
/*! \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).
|
||||
|
||||
*/
|
||||
|
|
@ -100,7 +100,7 @@ int iir_coeff_get_nd(const struct iir_coeff_t* coeff);
|
|||
|
||||
/*! \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()).
|
||||
\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.
|
||||
|
||||
\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()).
|
||||
\returns D coefficient value.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,15 +11,15 @@
|
|||
|
||||
\ingroup libiir
|
||||
|
||||
The functions in this module present a basic interface for representing IIR
|
||||
filters, creating instances of (possibly chained) IIR filters, and filtering an
|
||||
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
|
||||
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
|
||||
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
|
||||
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().
|
||||
|
||||
|
|
@ -33,12 +33,12 @@ struct iir_filter_t;
|
|||
|
||||
|
||||
|
||||
/*! \brief Create IIR filter instance
|
||||
/*! \brief Create %IIR filter instance
|
||||
|
||||
\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
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
*/
|
||||
|
|
@ -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 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 >4th order Butterworth filters, for example. This
|
||||
copies the set of coefficients from \a coeff so the coefficients can be freed
|
||||
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 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.
|
||||
\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.
|
||||
|
||||
*/
|
||||
|
|
@ -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 idx Index of coefficient set (0 ≤ \a idx < \ref iir_filter_coeff_sets()).
|
||||
\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
|
||||
which can be freed with \ref iir_coeff_free().
|
||||
|
||||
|
|
|
|||
|
|
@ -11,8 +11,8 @@
|
|||
|
||||
\ingroup libiir
|
||||
|
||||
Functions to create coefficients for various common types of IIR filter. The
|
||||
coefficient structures which are returned may be used to instantiate IIR
|
||||
Functions to create coefficients for various common types of %IIR filter. The
|
||||
coefficient structures which are returned may be used to instantiate %IIR
|
||||
filters using \ref iir_filter_new().
|
||||
|
||||
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 corner Corner frequency expressed as a fraction of Nyquist
|
||||
(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
|
||||
\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.
|
||||
|
||||
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).
|
||||
|
||||
*/
|
||||
|
|
@ -61,7 +61,7 @@ struct iir_coeff_t* iir_butterworth_lowpass(int order,
|
|||
\param gain Linear gain of filter.
|
||||
\param corner Corner frequency expressed as a fraction of Nyquist
|
||||
(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
|
||||
\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.
|
||||
|
||||
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).
|
||||
|
||||
*/
|
||||
|
|
@ -94,7 +94,7 @@ struct iir_coeff_t* iir_butterworth_highpass(int order,
|
|||
(0 ≤ \a c1 ≤ 1)
|
||||
\param c2 High corner frequency expressed as a fraction of Nyquist
|
||||
(0 ≤ \a c2 ≤ 1, and \a c1 < \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
|
||||
\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.
|
||||
|
||||
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),
|
||||
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)
|
||||
\param c2 High corner frequency expressed as a fraction of Nyquist
|
||||
(0 ≤ \a c2 ≤ 1, and \a c1 < \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
|
||||
\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.
|
||||
|
||||
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),
|
||||
and \a c2 should be greater than \a c1.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,9 +11,9 @@
|
|||
|
||||
\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
|
||||
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.
|
||||
|
||||
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.
|
||||
\returns Pointer to newly-allocated IIR filter instance.
|
||||
\param desc %IIR filter description.
|
||||
\returns Pointer to newly-allocated %IIR filter instance.
|
||||
\retval 0 on error.
|
||||
|
||||
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
|
||||
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
|
||||
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.
|
||||
\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.
|
||||
|
||||
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
|
||||
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
|
||||
pointer to an array of new filters. If \a desc cannot be parsed correctly,
|
||||
returns 0 and sets \a errno to \c EINVAL.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@
|
|||
|
||||
\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;
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue