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
31namespace juce
32{
33namespace dsp
34{
35
36/**
37 Classes for IIR filter processing.
38*/
39namespace 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 */
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>
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
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.
This structure is passed into a DSP algorithm's prepare() method, and contains information about vari...
A set of coefficients for use in an Filter object.
const NumericType * getRawCoefficients() const noexcept
Returns a raw data pointer to the coefficients.
Array< NumericType > coefficients
The raw coefficients.
This is a handy base class for the state of a processor (such as parameter values) which is typically...