OpenShot Library | OpenShotAudio 0.2.2
juce_Oversampling.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/**
38 A processing class performing multi-channel oversampling.
39
40 It can be configured to do 2 times, 4 times, 8 times or 16 times oversampling
41 using a multi-stage approach, either polyphase allpass IIR filters or FIR
42 filters for the filtering, and reports successfully the latency added by the
43 filter stages.
44
45 The principle of oversampling is to increase the sample rate of a given
46 non-linear process, to prevent it from creating aliasing. Oversampling works
47 by upsampling N times the input signal, processing the upsampled signal
48 with the increased internal sample rate, and downsampling the result to get
49 back the original processing sample rate.
50
51 Choose between FIR or IIR filtering depending on your needs in term of
52 latency and phase distortion. With FIR filters, the phase is linear but the
53 latency is maximised. With IIR filtering, the phase is compromised around the
54 Nyquist frequency but the latency is minimised.
55
56 @see FilterDesign.
57
58 @tags{DSP}
59*/
60template <typename SampleType>
62{
63public:
64 /** The type of filter that can be used for the oversampling processing. */
66 {
67 filterHalfBandFIREquiripple = 0,
68 filterHalfBandPolyphaseIIR,
69 numFilterTypes
70 };
71
72 //==============================================================================
73 /**
74 Constructor of the oversampling class. All the processing parameters must be
75 provided at the creation of the oversampling object.
76
77 @param numChannels the number of channels to process with this object
78 @param factor the processing will perform 2 ^ factor times oversampling
79 @param type the type of filter design employed for filtering during
80 oversampling
81 @param isMaxQuality if the oversampling is done using the maximum quality,
82 the filters will be more efficient, but the CPU load will
83 increase as well
84 */
85 Oversampling (size_t numChannels,
86 size_t factor,
87 FilterType type,
88 bool isMaxQuality = true);
89
90 /** The default constructor of the oversampling class, which can be used to create an
91 empty object and then add the appropriate stages.
92
93 Note: This creates a "dummy" oversampling stage, which needs to be removed first
94 before adding proper oversampling stages.
95
96 @see clearOversamplingStages, addOversamplingStage
97 */
98 explicit Oversampling (size_t numChannels = 1);
99
100 /** Destructor. */
102
103 //==============================================================================
104 /** Returns the latency in samples of the whole processing. Use this information
105 in your main processor to compensate the additional latency involved with
106 the oversampling, for example with a dry / wet functionality, and to report
107 the latency to the DAW.
108
109 Note: The latency might not be integer, so you might need to round its value
110 or to compensate it properly in your processing code.
111 */
112 SampleType getLatencyInSamples() noexcept;
113
114 /** Returns the current oversampling factor. */
115 size_t getOversamplingFactor() noexcept;
116
117 //==============================================================================
118 /** Must be called before any processing, to set the buffer sizes of the internal
119 buffers of the oversampling processing.
120 */
121 void initProcessing (size_t maximumNumberOfSamplesBeforeOversampling);
122
123 /** Resets the processing pipeline, ready to oversample a new stream of data. */
124 void reset() noexcept;
125
126 /** Must be called to perform the upsampling, prior to any oversampled processing.
127
128 Returns an AudioBlock referencing the oversampled input signal, which must be
129 used to perform the non-linear processing which needs the higher sample rate.
130 Don't forget to set the sample rate of that processing to N times the original
131 sample rate.
132 */
133 AudioBlock<SampleType> processSamplesUp (const AudioBlock<const SampleType>& inputBlock) noexcept;
134
135 /** Must be called to perform the downsampling, after the upsampling and the
136 non-linear processing. The output signal is probably delayed by the internal
137 latency of the whole oversampling behaviour, so don't forget to take this
138 into account.
139 */
140 void processSamplesDown (AudioBlock<SampleType>& outputBlock) noexcept;
141
142 //==============================================================================
143 /** Adds a new oversampling stage to the Oversampling class, multiplying the
144 current oversampling factor by two. This is used with the default constructor
145 to create custom oversampling chains, requiring a call to the
146 clearOversamplingStages before any addition.
147
148 Note: Upsampling and downsampling filtering have different purposes, the
149 former removes upsampling artefacts while the latter removes useless frequency
150 content created by the oversampled process, so usually the attenuation is
151 increased when upsampling compared to downsampling.
152
153 @param normalisedTransitionWidthUp a value between 0 and 0.5 which specifies how much
154 the transition between passband and stopband is
155 steep, for upsampling filtering (the lower the better)
156 @param stopbandAmplitudedBUp the amplitude in dB in the stopband for upsampling
157 filtering, must be negative
158 @param normalisedTransitionWidthDown a value between 0 and 0.5 which specifies how much
159 the transition between passband and stopband is
160 steep, for downsampling filtering (the lower the better)
161 @param stopbandAmplitudedBDown the amplitude in dB in the stopband for downsampling
162 filtering, must be negative
163
164 @see clearOversamplingStages
165 */
166 void addOversamplingStage (FilterType,
167 float normalisedTransitionWidthUp, float stopbandAmplitudedBUp,
168 float normalisedTransitionWidthDown, float stopbandAmplitudedBDown);
169
170 /** Adds a new "dummy" oversampling stage, which does nothing to the signal. Using
171 one can be useful if your application features a customisable oversampling factor
172 and if you want to select the current one from an OwnedArray without changing
173 anything in the processing code.
174
175 @see OwnedArray, clearOversamplingStages, addOversamplingStage
176 */
177 void addDummyOversamplingStage();
178
179 /** Removes all the previously registered oversampling stages, so you can add
180 your own from scratch.
181
182 @see addOversamplingStage, addDummyOversamplingStage
183 */
184 void clearOversamplingStages();
185
186 //==============================================================================
187 size_t factorOversampling = 1;
188 size_t numChannels = 1;
189
190 #ifndef DOXYGEN
191 struct OversamplingStage;
192 #endif
193
194private:
195 //==============================================================================
197 bool isReady = false;
198
199 //==============================================================================
200 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Oversampling)
201};
202
203} // namespace dsp
204} // namespace juce
205
206/** @}*/
An array designed for holding objects.
Minimal and lightweight data-structure which contains a list of pointers to channels containing some ...
A processing class performing multi-channel oversampling.
FilterType
The type of filter that can be used for the oversampling processing.
#define JUCE_API
This macro is added to all JUCE public class declarations.