diff --git a/src/docs/MainPage.dox b/src/docs/MainPage.dox index 8695025..ee9a49e 100644 --- a/src/docs/MainPage.dox +++ b/src/docs/MainPage.dox @@ -1,16 +1,16 @@ /* libiir/src/docs/MainPage.dox * - * Copyright: ©2010, Laurence Withers. + * Copyright: ©2010–2014, Laurence Withers. * Author: Laurence Withers * 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 diff --git a/src/docs/iir_structure.dox b/src/docs/iir_structure.dox index 9831e5e..b258b96 100644 --- a/src/docs/iir_structure.dox +++ b/src/docs/iir_structure.dox @@ -1,6 +1,6 @@ /* libiir/src/docs/iir_structure.dox * - * Copyright: ©2010–2011, Laurence Withers. + * Copyright: ©2010–2014, Laurence Withers. * Author: Laurence Withers * License: GPLv3 */ @@ -14,7 +14,7 @@ For the purposes of this library, the following notation is used: \li c[n]: array of \c x(t) coefficients \li d[n]: array of \c y(t) coefficients -This leads to a general IIR filter equation: +This leads to a general %IIR filter equation: 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] diff --git a/src/docs/string_desc.dox b/src/docs/string_desc.dox index 3161afb..1c8ca01 100644 --- a/src/docs/string_desc.dox +++ b/src/docs/string_desc.dox @@ -1,17 +1,17 @@ /* libiir/src/docs/string_desc.dox * - * Copyright: ©2010, Laurence Withers. + * Copyright: ©2010–2014, Laurence Withers. * Author: Laurence Withers * 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: c[0],c[1],…,c[n]/d[0],d[1]…d[n] diff --git a/src/libiir/100_coeff.h b/src/libiir/100_coeff.h index 48ff240..3e1b493 100644 --- a/src/libiir/100_coeff.h +++ b/src/libiir/100_coeff.h @@ -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. diff --git a/src/libiir/200_filter.h b/src/libiir/200_filter.h index 0ea2ea5..eea7df9 100644 --- a/src/libiir/200_filter.h +++ b/src/libiir/200_filter.h @@ -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 struct iir_coeff_t) is then used to instantiate specific filters (the opaque struct iir_filter_t) 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(). diff --git a/src/libiir/300_common_filters.h b/src/libiir/300_common_filters.h index a661f4f..dc0db48 100644 --- a/src/libiir/300_common_filters.h +++ b/src/libiir/300_common_filters.h @@ -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. diff --git a/src/libiir/400_parser.h b/src/libiir/400_parser.h index 285493f..ea43539 100644 --- a/src/libiir/400_parser.h +++ b/src/libiir/400_parser.h @@ -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. diff --git a/src/libiir/500_response.h b/src/libiir/500_response.h index a23f37a..9572a28 100644 --- a/src/libiir/500_response.h +++ b/src/libiir/500_response.h @@ -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.