OpenShot Library | OpenShotAudio  0.2.2
juce_dsp/processors/juce_IIRFilter.h
1 
2 /** @weakgroup juce_dsp-processors
3  * @{
4  */
5 /*
6  ==============================================================================
7 
8  This file is part of the JUCE library.
9  Copyright (c) 2017 - ROLI Ltd.
10 
11  JUCE is an open source library subject to commercial or open-source
12  licensing.
13 
14  By using JUCE, you agree to the terms of both the JUCE 5 End-User License
15  Agreement and JUCE 5 Privacy Policy (both updated and effective as of the
16  27th April 2017).
17 
18  End User License Agreement: www.juce.com/juce-5-licence
19  Privacy Policy: www.juce.com/juce-5-privacy-policy
20 
21  Or: You may also use this code under the terms of the GPL v3 (see
22  www.gnu.org/licenses).
23 
24  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
25  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
26  DISCLAIMED.
27 
28  ==============================================================================
29 */
30 
31 namespace juce
32 {
33 namespace dsp
34 {
35 
36 /**
37  Classes for IIR filter processing.
38 */
39 namespace IIR
40 {
41  template <typename NumericType>
42  struct Coefficients;
43 
44  /**
45  A processing class that can perform IIR filtering on an audio signal, using
46  the Transposed Direct Form II digital structure.
47 
48  If you need a lowpass, bandpass or highpass filter with fast modulation of
49  its cutoff frequency, you might use the class StateVariableFilter instead,
50  which is designed to prevent artefacts at parameter changes, instead of the
51  class Filter.
52 
53  @see Filter::Coefficients, FilterAudioSource, StateVariableFilter
54 
55  @tags{DSP}
56  */
57  template <typename SampleType>
58  class Filter
59  {
60  public:
61  /** The NumericType is the underlying primitive type used by the SampleType (which
62  could be either a primitive or vector)
63  */
64  using NumericType = typename SampleTypeHelpers::ElementType<SampleType>::Type;
65 
66  /** A typedef for a ref-counted pointer to the coefficients object */
68 
69  //==============================================================================
70  /** Creates a filter.
71 
72  Initially the filter is inactive, so will have no effect on samples that
73  you process with it. You can modify the coefficients member to turn it into
74  the type of filter needed.
75  */
76  Filter();
77 
78  /** Creates a filter with a given set of coefficients. */
79  Filter (CoefficientsPtr coefficientsToUse);
80 
81  Filter (const Filter&) = default;
82  Filter (Filter&&) = default;
83  Filter& operator= (const Filter&) = default;
84  Filter& operator= (Filter&&) = default;
85 
86  //==============================================================================
87  /** The coefficients of the IIR filter. It's up to the caller to ensure that
88  these coefficients are modified in a thread-safe way.
89 
90  If you change the order of the coefficients then you must call reset after
91  modifying them.
92  */
94 
95  //==============================================================================
96  /** Resets the filter's processing pipeline, ready to start a new stream of data.
97 
98  Note that this clears the processing state, but the type of filter and
99  its coefficients aren't changed.
100  */
101  void reset() { reset (SampleType {0}); }
102 
103  /** Resets the filter's processing pipeline to a specific value.
104  @see reset
105  */
106  void reset (SampleType resetToValue);
107 
108  //==============================================================================
109  /** Called before processing starts. */
110  void prepare (const ProcessSpec&) noexcept;
111 
112  /** Processes a block of samples */
113  template <typename ProcessContext>
114  void process (const ProcessContext& context) noexcept
115  {
116  if (context.isBypassed)
117  processInternal<ProcessContext, true> (context);
118  else
119  processInternal<ProcessContext, false> (context);
120  }
121 
122  /** Processes a single sample, without any locking.
123 
124  Use this if you need processing of a single value.
125 
126  Moreover, you might need the function snapToZero after a few calls to avoid
127  potential denormalisation issues.
128  */
129  SampleType JUCE_VECTOR_CALLTYPE processSample (SampleType sample) noexcept;
130 
131  /** Ensure that the state variables are rounded to zero if the state
132  variables are denormals. This is only needed if you are doing
133  sample by sample processing.
134  */
135  void snapToZero() noexcept;
136 
137  private:
138  //==============================================================================
139  void check();
140 
141  /** Processes a block of samples */
142  template <typename ProcessContext, bool isBypassed>
143  void processInternal (const ProcessContext& context) noexcept;
144 
145  //==============================================================================
146  HeapBlock<SampleType> memory;
147  SampleType* state = nullptr;
148  size_t order = 0;
149 
150  JUCE_LEAK_DETECTOR (Filter)
151  };
152 
153 
154  //==============================================================================
155  /** A set of coefficients for use in an Filter object.
156  @see IIR::Filter
157 
158  @tags{DSP}
159  */
160  template <typename NumericType>
161  struct Coefficients : public ProcessorState
162  {
163  /** Creates a null set of coefficients (which will produce silence). */
164  Coefficients();
165 
166  /** Directly constructs an object from the raw coefficients.
167  Most people will want to use the static methods instead of this, but the
168  constructor is public to allow tinkerers to create their own custom filters!
169  */
171  NumericType a0, NumericType a1);
172 
174  NumericType a0, NumericType a1, NumericType a2);
175 
178 
179  Coefficients (const Coefficients&) = default;
180  Coefficients (Coefficients&&) = default;
181  Coefficients& operator= (const Coefficients&) = default;
182  Coefficients& operator= (Coefficients&&) = default;
183 
184  /** The Coefficients structure is ref-counted, so this is a handy type that can be used
185  as a pointer to one.
186  */
188 
189  //==============================================================================
190  /** Returns the coefficients for a first order low-pass filter. */
191  static Ptr makeFirstOrderLowPass (double sampleRate, NumericType frequency);
192 
193  /** Returns the coefficients for a first order high-pass filter. */
194  static Ptr makeFirstOrderHighPass (double sampleRate, NumericType frequency);
195 
196  /** Returns the coefficients for a first order all-pass filter. */
197  static Ptr makeFirstOrderAllPass (double sampleRate, NumericType frequency);
198 
199  //==============================================================================
200  /** Returns the coefficients for a low-pass filter. */
201  static Ptr makeLowPass (double sampleRate, NumericType frequency);
202 
203  /** Returns the coefficients for a low-pass filter with variable Q. */
204  static Ptr makeLowPass (double sampleRate, NumericType frequency, NumericType Q);
205 
206  //==============================================================================
207  /** Returns the coefficients for a high-pass filter. */
208  static Ptr makeHighPass (double sampleRate, NumericType frequency);
209 
210  /** Returns the coefficients for a high-pass filter with variable Q. */
211  static Ptr makeHighPass (double sampleRate, NumericType frequency, NumericType Q);
212 
213  //==============================================================================
214  /** Returns the coefficients for a band-pass filter. */
215  static Ptr makeBandPass (double sampleRate, NumericType frequency);
216 
217  /** Returns the coefficients for a band-pass filter with variable Q. */
218  static Ptr makeBandPass (double sampleRate, NumericType frequency, NumericType Q);
219 
220  //==============================================================================
221  /** Returns the coefficients for a notch filter. */
222  static Ptr makeNotch (double sampleRate, NumericType frequency);
223 
224  /** Returns the coefficients for a notch filter with variable Q. */
225  static Ptr makeNotch (double sampleRate, NumericType frequency, NumericType Q);
226 
227  //==============================================================================
228  /** Returns the coefficients for an all-pass filter. */
229  static Ptr makeAllPass (double sampleRate, NumericType frequency);
230 
231  /** Returns the coefficients for an all-pass filter with variable Q. */
232  static Ptr makeAllPass (double sampleRate, NumericType frequency, NumericType Q);
233 
234  //==============================================================================
235  /** Returns the coefficients for a low-pass shelf filter with variable Q and gain.
236 
237  The gain is a scale factor that the low frequencies are multiplied by, so values
238  greater than 1.0 will boost the low frequencies, values less than 1.0 will
239  attenuate them.
240  */
241  static Ptr makeLowShelf (double sampleRate, NumericType cutOffFrequency,
242  NumericType Q, NumericType gainFactor);
243 
244  /** Returns the coefficients for a high-pass shelf filter with variable Q and gain.
245 
246  The gain is a scale factor that the high frequencies are multiplied by, so values
247  greater than 1.0 will boost the high frequencies, values less than 1.0 will
248  attenuate them.
249  */
250  static Ptr makeHighShelf (double sampleRate, NumericType cutOffFrequency,
251  NumericType Q, NumericType gainFactor);
252 
253  /** Returns the coefficients for a peak filter centred around a
254  given frequency, with a variable Q and gain.
255 
256  The gain is a scale factor that the centre frequencies are multiplied by, so
257  values greater than 1.0 will boost the centre frequencies, values less than
258  1.0 will attenuate them.
259  */
260  static Ptr makePeakFilter (double sampleRate, NumericType centreFrequency,
261  NumericType Q, NumericType gainFactor);
262 
263  //==============================================================================
264  /** Returns the filter order associated with the coefficients */
265  size_t getFilterOrder() const noexcept;
266 
267  /** Returns the magnitude frequency response of the filter for a given frequency
268  and sample rate
269  */
270  double getMagnitudeForFrequency (double frequency, double sampleRate) const noexcept;
271 
272  /** Returns the magnitude frequency response of the filter for a given frequency array
273  and sample rate.
274  */
275  void getMagnitudeForFrequencyArray (const double* frequencies, double* magnitudes,
276  size_t numSamples, double sampleRate) const noexcept;
277 
278  /** Returns the phase frequency response of the filter for a given frequency and
279  sample rate
280  */
281  double getPhaseForFrequency (double frequency, double sampleRate) const noexcept;
282 
283  /** Returns the phase frequency response of the filter for a given frequency array
284  and sample rate.
285  */
286  void getPhaseForFrequencyArray (double* frequencies, double* phases,
287  size_t numSamples, double sampleRate) const noexcept;
288 
289  /** Returns a raw data pointer to the coefficients. */
290  NumericType* getRawCoefficients() noexcept { return coefficients.getRawDataPointer(); }
291 
292  /** Returns a raw data pointer to the coefficients. */
293  const NumericType* getRawCoefficients() const noexcept { return coefficients.begin(); }
294 
295  //==============================================================================
296  /** The raw coefficients.
297  You should leave these numbers alone unless you really know what you're doing.
298  */
300 
301  private:
302  // Unfortunately, std::sqrt is not marked as constexpr just yet in all compilers
303  static constexpr NumericType inverseRootTwo = static_cast<NumericType> (0.70710678118654752440L);
304  };
305 
306 } // namespace IIR
307 } // namespace dsp
308 } // namespace juce
309 
310 #include "juce_IIRFilter_Impl.h"
311 
312 /** @}*/
Very simple container class to hold a pointer to some data on the heap.
A smart-pointer class which points to a reference-counted object.
A processing class that can perform IIR filtering on an audio signal, using the Transposed Direct For...
void prepare(const ProcessSpec &) noexcept
Called before processing starts.
Filter()
Creates a filter.
CoefficientsPtr coefficients
The coefficients of the IIR filter.
Filter(CoefficientsPtr coefficientsToUse)
Creates a filter with a given set of coefficients.
void snapToZero() noexcept
Ensure that the state variables are rounded to zero if the state variables are denormals.
void reset()
Resets the filter's processing pipeline, ready to start a new stream of data.
SampleType JUCE_VECTOR_CALLTYPE processSample(SampleType sample) noexcept
Processes a single sample, without any locking.
typename Coefficients< NumericType >::Ptr CoefficientsPtr
A typedef for a ref-counted pointer to the coefficients object.
typename SampleTypeHelpers::ElementType< SampleType >::Type NumericType
The NumericType is the underlying primitive type used by the SampleType (which could be either a prim...
void process(const ProcessContext &context) noexcept
Processes a block of samples.
void reset(SampleType resetToValue)
Resets the filter's processing pipeline to a specific value.
A set of coefficients for use in an Filter object.
Array< NumericType > coefficients
The raw coefficients.
const NumericType * getRawCoefficients() const noexcept
Returns a raw data pointer to the coefficients.
This structure is passed into a DSP algorithm's prepare() method, and contains information about vari...
This is a handy base class for the state of a processor (such as parameter values) which is typically...