1 /***************************************************/ 2 /*! \class Filter 3 \brief STK filter class. 4 5 This class implements a generic structure that 6 can be used to create a wide range of filters. 7 It can function independently or be subclassed 8 to provide more specific controls based on a 9 particular filter type. 10 11 In particular, this class implements the standard 12 difference equation: 13 14 a[0]*y[n] = b[0]*x[n] + ... + b[nb]*x[n-nb] - 15 a[1]*y[n-1] - ... - a[na]*y[n-na] 16 17 If a[0] is not equal to 1, the filter coeffcients 18 are normalized by a[0]. 19 20 The \e gain parameter is applied at the filter 21 input and does not affect the coefficient values. 22 The default gain value is 1.0. This structure 23 results in one extra multiply per computed sample, 24 but allows easy control of the overall filter gain. 25 26 by Perry R. Cook and Gary P. Scavone, 1995 - 2005. 27 */ 28 /***************************************************/ 29 30 #ifndef STK_FILTER_H 31 #define STK_FILTER_H 32 33 #include "Stk.h" 34 #include <vector> 35 36 namespace Nyq 37 { 38 39 class Filter : public Stk 40 { 41 public: 42 //! Default constructor creates a zero-order pass-through "filter". 43 Filter(void); 44 45 //! Overloaded constructor which takes filter coefficients. 46 /*! 47 An StkError can be thrown if either of the coefficient vector 48 sizes is zero, or if the a[0] coefficient is equal to zero. 49 */ 50 Filter( std::vector<StkFloat> &bCoefficients, std::vector<StkFloat> &aCoefficients ); 51 52 //! Class destructor. 53 virtual ~Filter(void); 54 55 //! Sets all internal states of the filter to zero. 56 void clear(void); 57 58 //! Set filter coefficients. 59 /*! 60 An StkError can be thrown if either of the coefficient vector 61 sizes is zero, or if the a[0] coefficient is equal to zero. If 62 a[0] is not equal to 1, the filter coeffcients are normalized by 63 a[0]. The internal state of the filter is not cleared unless the 64 \e clearState flag is \c true. 65 */ 66 void setCoefficients( std::vector<StkFloat> &bCoefficients, std::vector<StkFloat> &aCoefficients, bool clearState = false ); 67 68 //! Set numerator coefficients. 69 /*! 70 An StkError can be thrown if coefficient vector is empty. Any 71 previously set denominator coefficients are left unaffected. Note 72 that the default constructor sets the single denominator 73 coefficient a[0] to 1.0. The internal state of the filter is not 74 cleared unless the \e clearState flag is \c true. 75 */ 76 void setNumerator( std::vector<StkFloat> &bCoefficients, bool clearState = false ); 77 78 //! Set denominator coefficients. 79 /*! 80 An StkError can be thrown if the coefficient vector is empty or 81 if the a[0] coefficient is equal to zero. Previously set 82 numerator coefficients are unaffected unless a[0] is not equal to 83 1, in which case all coeffcients are normalized by a[0]. Note 84 that the default constructor sets the single numerator coefficient 85 b[0] to 1.0. The internal state of the filter is not cleared 86 unless the \e clearState flag is \c true. 87 */ 88 void setDenominator( std::vector<StkFloat> &aCoefficients, bool clearState = false ); 89 90 //! Set the filter gain. 91 /*! 92 The gain is applied at the filter input and does not affect the 93 coefficient values. The default gain value is 1.0. 94 */ 95 virtual void setGain(StkFloat gain); 96 97 //! Return the current filter gain. 98 virtual StkFloat getGain(void) const; 99 100 //! Return the last computed output value. 101 virtual StkFloat lastOut(void) const; 102 103 //! Input one sample to the filter and return one output. 104 virtual StkFloat tick( StkFloat input ); 105 106 //! Take a channel of the StkFrames object as inputs to the filter and replace with corresponding outputs. 107 /*! 108 The \c channel argument should be zero or greater (the first 109 channel is specified by 0). An StkError will be thrown if the \c 110 channel argument is equal to or greater than the number of 111 channels in the StkFrames object. 112 */ 113 virtual StkFrames& tick( StkFrames& frames, unsigned int channel = 0 ); 114 115 protected: 116 117 StkFloat gain_; 118 std::vector<StkFloat> b_; 119 std::vector<StkFloat> a_; 120 std::vector<StkFloat> outputs_; 121 std::vector<StkFloat> inputs_; 122 123 }; 124 125 } // namespace Nyq 126 127 #endif 128