ece486_running_mean.h

Go to the documentation of this file.

/*!
 * @file ece486_running_mean.h
 * 
 * @brief FIR filter using fixed-length input sample blocks
 * 
 * @author ECE486 Lab Group ????
 * @author Your Name
 * 
 * @date ????
 * 
 * @defgroup Lab_1 Running Mean Filters
 *   @{
 * 
 * Implementation of running-mean filters for in which a very long input sequence
 * x[n] can be processed by breaking the input sequence into fixed length blocks.
 * 
 * Filter output values are given by 
 * @verbatim
 *    y(n) = 1/M*( x[n] + x[n-1] + ... + x[n-M+1] )
 * @endverbatim
 * 
 * Filters are initialized by a single call to init_running_mean(), which allocates
 * and initializes a filter descriptor structure of type RUNNING_MEAN_T
 * 
 * @code 
 *    #include "ece486_running_mean.h"
 *    ...
 *    RUNNING_MEAN_T  *filt;
 *    ...
 *    // Allocate memory for inputs x[i] and outputs y[i] of length "blocksize"...
 *    ...
 *    filt = init_running_mean(M,blocksize);
 * @endcode
 * 
 * Once a filter descriptor is initialized, repeated calls to calc_running_mean()
 * provide the filter outputs, where the input samples are provided in fixed 
 * length blocks of "blocksize" samples at a time.
 * 
 * @code
 *    while( ...input sample blocks are available...) {
 *       // fill the vector x[i] with the next "blocksize" samples from the input sequence.
 *       calc_running_mean(filt, x, y);
 *       // do something with the filter output samples y[i].
 *    }
 * @endcode
 * 
 * When processing completes, destroy_running_mean() should be called to release
 * any allocated memory.
 * 
 * @code
 *    destroy_running_mean(filt);
 * @endcode
 * 
 * @note 
 * All input and output vectors (x[i] and y[i]) must be allocated by the caller.
 * 
 * @note
 * The input and output arrays MAY point to the same location, in which case the 
 * input sequence x[i] is replaced by the output 
 * sequence y[i] in the calls to calc_running_mean().  
 * 
 */
 
 
#ifndef ECE486_RUNNING_MEAN
#define ECE486_RUNNING_MEAN
 
/*
 * Parameter Structure Definitions
 */
 
/*!
 * @brief filter structure containing the filter state
 * 
 */
typedef struct running_mean {
  int M;                 // Number of samples to average.
  int blocksize;         // Number of samples per call to calc_running_mean
  float *history;        //  Most recent M input samples
    } RUNNING_MEAN_T;
 
/*
 * Function Prototypes
 */
 
/*!
 * @brief running mean filter initialization 
 * 
 * Call init_running_mean() to create and initialize a running meain filter structure.  
 * 
 * @returns pointer to an initialized structure of type #RUNNING_MEAN_T which may 
 * be used to calculate the requested filter outputs.
 */
RUNNING_MEAN_T *init_running_mean(
  int   M,         //!< [in] Number of samples to average for each output sample
  int   blocksize       //!< [in] Block size for input sample blocks
);
 
/*!
 * @brief Calculate a block of output samples of a running meain filter from an input sample block
 * 
 * Calling calc_running_mean() repeatedly generates the filter output for an arbitrary sequence
 * of input samples.  The FIR filter output samples y(n) are given by
 * @verbatim
 *
 *                            i=M-1
 *              y[n] = (1/M)   sum   x[n-i] 
 *                             i=0
 * @endverbatim
 * For each call, an input block of samples @a x[i] with length "blocksize" (as specified 
 * in init_running_mean() ) is processed to generate the corresponding output samples
 * in the output vector @a y[i]. In subsequent calls to calc_running_mean(), the 
 * new input blocks @a x[i] are assumed to follow the input blocks provided in
 * the previous calls to calc_running_mean().  As a result, very long input sequences
 * may be processed by breaking the sequence into many fixed-length blocks of 
 * "blocksize" samples.
 * 
 * Memory required to store the output vector @a y[i] must be allocated by the 
 * caller.  
 * 
 * \note
 *   @a x and @a y CAN point to the same location.  In this case, the filter output
 *   samples will replace the input sample array.
 * 
 * @returns On return, y[i] contains the calculated output samples.
 *  (The contents of the structure @a *s are also modified to keep track of the filter state.)
 * 
 * @sa init_running_mean()
 */ 
void calc_running_mean(
  RUNNING_MEAN_T *s,    //!< [in,out] Pointer to previously initialized running mean filter structure,
                        //!< as provided by init_running() (and possibly modified by 
                        //!< previous calls to calc_running_mean() )
  float *x,             //!< [in] pointer to the input sample array
  float *y              //!< [out] Pointer to an array for storage of output samples
);
 
/*!
 * @brief Release memory associated with an #FIR_T
 */
void destroy_running_mean(
  RUNNING_MEAN_T *s             //!< [in] Pointer to previously initialized FIR filter 
                        //!< structure, provided by init_fir()
);
 
/*! @} end of ece486_running_mean group. */
#endif