From a08f846437ce414c1ad258cf0a9d889b3d80a4df Mon Sep 17 00:00:00 2001 From: Laurence Withers Date: Mon, 7 Jul 2014 11:50:09 +0000 Subject: [PATCH] Split filtering/coefficient handling files Splits the code for handling coefficient objects and handling filter objects into separate files. This is just to aid documentation and comprehension. --- src/libiir/000_TopHeader.h | 2 + src/libiir/100_coeff.c | 113 ++++++++++++++++++++++ src/libiir/100_coeff.h | 126 +++++++++++++++++++++++++ src/libiir/{200_iir.c => 200_filter.c} | 103 +------------------- src/libiir/{200_iir.h => 200_filter.h} | 106 +-------------------- 5 files changed, 244 insertions(+), 206 deletions(-) create mode 100644 src/libiir/100_coeff.c create mode 100644 src/libiir/100_coeff.h rename src/libiir/{200_iir.c => 200_filter.c} (72%) rename src/libiir/{200_iir.h => 200_filter.h} (57%) diff --git a/src/libiir/000_TopHeader.h b/src/libiir/000_TopHeader.h index fedd597..14f8421 100644 --- a/src/libiir/000_TopHeader.h +++ b/src/libiir/000_TopHeader.h @@ -15,6 +15,8 @@ extern "C" { #endif +/*! \defgroup libiir C library */ + /* options for text editors vim: expandtab:ts=4:sw=4:syntax=c.doxygen */ diff --git a/src/libiir/100_coeff.c b/src/libiir/100_coeff.c new file mode 100644 index 0000000..bbd22bb --- /dev/null +++ b/src/libiir/100_coeff.c @@ -0,0 +1,113 @@ +/* libiir/src/libiir/100_coeff.c + * + * Copyright: ©2010–2014, Laurence Withers. + * Author: Laurence Withers + * License: GPLv3 +*/ + + + +/* struct iir_coeff_t + * Holds a general IIR filter (i.e. the set of coefficients that define it). + * nc >= 1 and nd >= 1. + */ +struct iir_coeff_t { + int nc, nd; + double* c, * d; +}; + + + +/* iir_coeff_new() + * Allocates a new set of coefficient objects. + */ +struct iir_coeff_t* +iir_coeff_new(int nc, const double* c, int nd, const double* d) +{ + struct iir_coeff_t* coeff; + + if(nc < 1 || nd < 1) { + errno = EINVAL; + return 0; + } + + coeff = malloc(sizeof(struct iir_coeff_t)); + coeff->nc = nc; + coeff->nd = nd; + coeff->c = malloc(sizeof(double) * nc); + coeff->d = malloc(sizeof(double) * nd); + memcpy(coeff->c, c, sizeof(double) * nc); + memcpy(coeff->d, d, sizeof(double) * nd); + + return coeff; +} + + + +/* iir_coeff_copy() + * Deep copy of coefficient object. + */ +struct iir_coeff_t* +iir_coeff_copy(const struct iir_coeff_t* other) +{ + struct iir_coeff_t* coeff; + + coeff = malloc(sizeof(struct iir_coeff_t)); + coeff->nc = other->nc; + coeff->nd = other->nd; + coeff->c = malloc(sizeof(double) * coeff->nc); + coeff->d = malloc(sizeof(double) * coeff->nd); + memcpy(coeff->c, other->c, sizeof(double) * coeff->nc); + memcpy(coeff->d, other->d, sizeof(double) * coeff->nd); + + return coeff; +} + + + +/* iir_coeff_free() + * Frees memory associated with ‘coeff’. + */ +void +iir_coeff_free(struct iir_coeff_t* coeff) +{ + if(!coeff) return; + free(coeff->c); + free(coeff->d); + free(coeff); +} + + + +/* iir_coeff_get_*() + * Functions for querying the coefficients that make up an IIR filter. + */ +int +iir_coeff_get_nc(const struct iir_coeff_t* coeff) +{ + return coeff->nc; +} + +int +iir_coeff_get_nd(const struct iir_coeff_t* coeff) +{ + return coeff->nd; +} + +double +iir_coeff_get_c(const struct iir_coeff_t* coeff, int idx) +{ + return coeff->c[idx]; +} + +double +iir_coeff_get_d(const struct iir_coeff_t* coeff, int idx) +{ + return coeff->d[idx]; +} + + + +/* options for text editors +vim: expandtab:ts=4:sw=4 +*/ diff --git a/src/libiir/100_coeff.h b/src/libiir/100_coeff.h new file mode 100644 index 0000000..48ff240 --- /dev/null +++ b/src/libiir/100_coeff.h @@ -0,0 +1,126 @@ +/* libiir/src/libiir/100_coeff.h + * + * Copyright: ©2010–2014, Laurence Withers. + * Author: Laurence Withers + * License: GPLv3 +*/ + + + +/*! \defgroup libiir_coeff Coefficient handling + +\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 +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. + +*/ +/*!@{*/ + + + +/* opaque structure */ +struct iir_coeff_t; + + + +/*! \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. + +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(). + +See \ref iir_structure for a full explanation of the parameters. + +*/ +struct iir_coeff_t* iir_coeff_new(int nc, const double* c, int nd, + const double* d) +#ifndef DOXYGEN + __attribute__((malloc,nonnull)) +#endif +; + + + +/*! \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. + +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 + +\param coeff Pointer to IIR coefficient object. May be 0. + +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 +filters are still using its coefficient values. + +*/ +void iir_coeff_free(struct iir_coeff_t* coeff); + + + +/*! \brief Query number of C coefficients. + +\param coeff Pointer to IIR coefficient object. +\returns Number of C coefficients (≥1). + +*/ +int iir_coeff_get_nc(const struct iir_coeff_t* coeff); + + + +/*! \brief Query number of D coefficients. + +\param coeff Pointer to IIR coefficient object. +\returns Number of D coefficients (≥1). + +*/ +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 idx Index of coefficient (≥0, < \ref iir_coeff_get_nc()). +\returns C coefficient value. + +*/ +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 idx Index of coefficient (≥0, < \ref iir_coeff_get_nd()). +\returns D coefficient value. + +*/ +double iir_coeff_get_d(const struct iir_coeff_t* coeff, int idx); + + + +/*!@}*/ +/* options for text editors +vim: expandtab:ts=4:sw=4:syntax=c.doxygen +*/ diff --git a/src/libiir/200_iir.c b/src/libiir/200_filter.c similarity index 72% rename from src/libiir/200_iir.c rename to src/libiir/200_filter.c index 46409ad..d69b62b 100644 --- a/src/libiir/200_iir.c +++ b/src/libiir/200_filter.c @@ -1,4 +1,4 @@ -/* libiir/src/libiir/200_iir.c +/* libiir/src/libiir/200_filter.c * * Copyright: ©2010–2014, Laurence Withers. * Author: Laurence Withers @@ -7,107 +7,6 @@ -/* struct iir_coeff_t - * Holds a general IIR filter (i.e. the set of coefficients that define it). - * nc >= 1 and nd >= 1. - */ -struct iir_coeff_t { - int nc, nd; - double* c, * d; -}; - - - -/* iir_coeff_new() - * Allocates a new set of coefficient objects. - */ -struct iir_coeff_t* -iir_coeff_new(int nc, const double* c, int nd, const double* d) -{ - struct iir_coeff_t* coeff; - - if(nc < 1 || nd < 1) { - errno = EINVAL; - return 0; - } - - coeff = malloc(sizeof(struct iir_coeff_t)); - coeff->nc = nc; - coeff->nd = nd; - coeff->c = malloc(sizeof(double) * nc); - coeff->d = malloc(sizeof(double) * nd); - memcpy(coeff->c, c, sizeof(double) * nc); - memcpy(coeff->d, d, sizeof(double) * nd); - - return coeff; -} - - - -/* iir_coeff_copy() - * Deep copy of coefficient object. - */ -struct iir_coeff_t* -iir_coeff_copy(const struct iir_coeff_t* other) -{ - struct iir_coeff_t* coeff; - - coeff = malloc(sizeof(struct iir_coeff_t)); - coeff->nc = other->nc; - coeff->nd = other->nd; - coeff->c = malloc(sizeof(double) * coeff->nc); - coeff->d = malloc(sizeof(double) * coeff->nd); - memcpy(coeff->c, other->c, sizeof(double) * coeff->nc); - memcpy(coeff->d, other->d, sizeof(double) * coeff->nd); - - return coeff; -} - - - -/* iir_coeff_free() - * Frees memory associated with ‘coeff’. - */ -void -iir_coeff_free(struct iir_coeff_t* coeff) -{ - if(!coeff) return; - free(coeff->c); - free(coeff->d); - free(coeff); -} - - - -/* iir_coeff_get_*() - * Functions for querying the coefficients that make up an IIR filter. - */ -int -iir_coeff_get_nc(const struct iir_coeff_t* coeff) -{ - return coeff->nc; -} - -int -iir_coeff_get_nd(const struct iir_coeff_t* coeff) -{ - return coeff->nd; -} - -double -iir_coeff_get_c(const struct iir_coeff_t* coeff, int idx) -{ - return coeff->c[idx]; -} - -double -iir_coeff_get_d(const struct iir_coeff_t* coeff, int idx) -{ - return coeff->d[idx]; -} - - - /* struct iir_filter_t * An instantiated IIR filter. This is actually a linked list node, so that we * can create chains of filters. It also has a copy of the coefficients so that diff --git a/src/libiir/200_iir.h b/src/libiir/200_filter.h similarity index 57% rename from src/libiir/200_iir.h rename to src/libiir/200_filter.h index 8b4ba21..247a8ba 100644 --- a/src/libiir/200_iir.h +++ b/src/libiir/200_filter.h @@ -1,4 +1,4 @@ -/* libiir/src/libiir/200_iir.h +/* libiir/src/libiir/200_filter.h * * Copyright: ©2010–2014, Laurence Withers. * Author: Laurence Withers @@ -7,11 +7,7 @@ -/*! \defgroup libiir C library */ - - - -/*! \defgroup libiir_iir Basic IIR filtering +/*! \defgroup libiir_filter Basic IIR filtering \ingroup libiir @@ -32,104 +28,6 @@ through \ref iir_filter(). -/* opaque structure */ -struct iir_coeff_t; - - - -/*! \brief Create general IIR filter - -\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. - -This function creates a new general IIR filter object which may be used to -create filter instances through \ref iir_filter_new() or chained on to existing -instances through \ref iir_filter(). - -See \ref iir_structure for a full explanation of the parameters. - -*/ -struct iir_coeff_t* iir_coeff_new(int nc, const double* c, int nd, - const double* d) -#ifndef DOXYGEN - __attribute__((malloc,nonnull)) -#endif -; - - - -/*! \brief Create copy of general IIR filter - -\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. - -*/ -struct iir_coeff_t* iir_coeff_copy(const struct iir_coeff_t* other); - - - -/*! \brief Free general IIR filter - -\param coeff Pointer to IIR filter object. May be 0. - -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 -filters are still using its coefficient values. - -*/ -void iir_coeff_free(struct iir_coeff_t* coeff); - - - -/*! \brief Query number of C coefficients. - -\param coeff Pointer to IIR filter object. -\returns Number of C coefficients (≥1). - -*/ -int iir_coeff_get_nc(const struct iir_coeff_t* coeff); - - - -/*! \brief Query number of D coefficients. - -\param coeff Pointer to IIR filter object. -\returns Number of D coefficients (≥1). - -*/ -int iir_coeff_get_nd(const struct iir_coeff_t* coeff); - - - -/*! \brief Get value of C coefficient. - -\param coeff Pointer to IIR filter object. -\param idx Index of coefficient (≥0, < \ref iir_coeff_get_nc()). -\returns C coefficient value. - -*/ -double iir_coeff_get_c(const struct iir_coeff_t* coeff, int idx); - - - -/*! \brief Get value of D coefficient. - -\param coeff Pointer to IIR filter object. -\param idx Index of coefficient (≥0, < \ref iir_coeff_get_nd()). -\returns D coefficient value. - -*/ -double iir_coeff_get_d(const struct iir_coeff_t* coeff, int idx); - - - /* opaque structure */ struct iir_filter_t;