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 
31 namespace juce
32 {
33 namespace 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 */
60 template <typename SampleType>
62 {
63 public:
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. */
101  ~Oversampling();
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 
194 private:
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 /** @}*/
Abstract class for the provided oversampling stages used internally in the Oversampling class...
#define JUCE_API
This macro is added to all JUCE public class declarations.
Minimal and lightweight data-structure which contains a list of pointers to channels containing some ...
A processing class performing multi-channel oversampling.
An array designed for holding objects.
FilterType
The type of filter that can be used for the oversampling processing.