1 /*
2   ==============================================================================
3 
4    This file is part of the JUCE library.
5    Copyright (c) 2020 - Raw Material Software Limited
6 
7    JUCE is an open source library subject to commercial or open-source
8    licensing.
9 
10    By using JUCE, you agree to the terms of both the JUCE 6 End-User License
11    Agreement and JUCE Privacy Policy (both effective as of the 16th June 2020).
12 
13    End User License Agreement: www.juce.com/juce-6-licence
14    Privacy Policy: www.juce.com/juce-privacy-policy
15 
16    Or: You may also use this code under the terms of the GPL v3 (see
17    www.gnu.org/licenses).
18 
19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
21    DISCLAIMED.
22 
23   ==============================================================================
24 */
25 
26 namespace juce
27 {
28 namespace dsp
29 {
30 
31 /**
32     This structure is passed into a DSP algorithm's prepare() method, and contains
33     information about various aspects of the context in which it can expect to be called.
34 
35     @tags{DSP}
36 */
37 struct ProcessSpec
38 {
39     /** The sample rate that will be used for the data that is sent to the processor. */
40     double sampleRate;
41 
42     /** The maximum number of samples that will be in the blocks sent to process() method. */
43     uint32 maximumBlockSize;
44 
45     /** The number of channels that the process() method will be expected to handle. */
46     uint32 numChannels;
47 };
48 
49 //==============================================================================
50 /**
51     This is a handy base class for the state of a processor (such as parameter values)
52     which is typically shared among several processors. This is useful for multi-mono
53     filters which share the same state among several mono processors.
54 
55     @tags{DSP}
56 */
57 struct ProcessorState  : public ReferenceCountedObject
58 {
59     /** The ProcessorState structure is ref-counted, so this is a handy type that can be used
60         as a pointer to one.
61     */
62     using Ptr = ReferenceCountedObjectPtr<ProcessorState>;
63 };
64 
65 //==============================================================================
66 /**
67     Contains context information that is passed into an algorithm's process method.
68 
69     This context is intended for use in situations where a single block is being used
70     for both the input and output, so it will return the same object for both its
71     getInputBlock() and getOutputBlock() methods.
72 
73     @see ProcessContextNonReplacing
74 
75     @tags{DSP}
76 */
77 template <typename ContextSampleType>
78 struct ProcessContextReplacing
79 {
80 public:
81     /** The type of a single sample (which may be a vector if multichannel). */
82     using SampleType     = ContextSampleType;
83     /** The type of audio block that this context handles. */
84     using AudioBlockType = AudioBlock<SampleType>;
85     using ConstAudioBlockType = AudioBlock<const SampleType>;
86 
87     /** Creates a ProcessContextReplacing that uses the given audio block.
88         Note that the caller must not delete the block while it is still in use by this object!
89     */
ProcessContextReplacingProcessContextReplacing90     ProcessContextReplacing (AudioBlockType& block) noexcept : ioBlock (block) {}
91 
92     ProcessContextReplacing (const ProcessContextReplacing&) = default;
93     ProcessContextReplacing (ProcessContextReplacing&&) = default;
94 
95     /** Returns the audio block to use as the input to a process function. */
getInputBlockProcessContextReplacing96     const ConstAudioBlockType& getInputBlock() const noexcept   { return constBlock; }
97 
98     /** Returns the audio block to use as the output to a process function. */
getOutputBlockProcessContextReplacing99     AudioBlockType& getOutputBlock() const noexcept             { return ioBlock; }
100 
101     /** All process context classes will define this constant method so that templated
102         code can determine whether the input and output blocks refer to the same buffer,
103         or to two different ones.
104     */
usesSeparateInputAndOutputBlocksProcessContextReplacing105     static constexpr bool usesSeparateInputAndOutputBlocks()    { return false; }
106 
107     /** If set to true, then a processor's process() method is expected to do whatever
108         is appropriate for it to be in a bypassed state.
109     */
110     bool isBypassed = false;
111 
112 private:
113     AudioBlockType& ioBlock;
114     ConstAudioBlockType constBlock { ioBlock };
115 };
116 
117 //==============================================================================
118 /**
119     Contains context information that is passed into an algorithm's process method.
120 
121     This context is intended for use in situations where two different blocks are being
122     used the input and output to the process algorithm, so the processor must read from
123     the block returned by getInputBlock() and write its results to the block returned by
124     getOutputBlock().
125 
126     @see ProcessContextReplacing
127 
128     @tags{DSP}
129 */
130 template <typename ContextSampleType>
131 struct ProcessContextNonReplacing
132 {
133 public:
134     /** The type of a single sample (which may be a vector if multichannel). */
135     using SampleType     = ContextSampleType;
136     /** The type of audio block that this context handles. */
137     using AudioBlockType = AudioBlock<SampleType>;
138     using ConstAudioBlockType = AudioBlock<const SampleType>;
139 
140     /** Creates a ProcessContextReplacing that uses the given input and output blocks.
141         Note that the caller must not delete these blocks while they are still in use by this object!
142     */
ProcessContextNonReplacingProcessContextNonReplacing143     ProcessContextNonReplacing (const ConstAudioBlockType& input, AudioBlockType& output) noexcept
144         : inputBlock (input), outputBlock (output)
145     {
146         // If the input and output blocks are the same then you should use
147         // ProcessContextReplacing instead.
148         jassert (input != output);
149     }
150 
151     ProcessContextNonReplacing (const ProcessContextNonReplacing&) = default;
152     ProcessContextNonReplacing (ProcessContextNonReplacing&&) = default;
153 
154     /** Returns the audio block to use as the input to a process function. */
getInputBlockProcessContextNonReplacing155     const ConstAudioBlockType& getInputBlock() const noexcept   { return inputBlock; }
156 
157     /** Returns the audio block to use as the output to a process function. */
getOutputBlockProcessContextNonReplacing158     AudioBlockType& getOutputBlock() const noexcept             { return outputBlock; }
159 
160     /** All process context classes will define this constant method so that templated
161         code can determine whether the input and output blocks refer to the same buffer,
162         or to two different ones.
163     */
usesSeparateInputAndOutputBlocksProcessContextNonReplacing164     static constexpr bool usesSeparateInputAndOutputBlocks()    { return true; }
165 
166     /** If set to true, then a processor's process() method is expected to do whatever
167         is appropriate for it to be in a bypassed state.
168     */
169     bool isBypassed = false;
170 
171 private:
172     ConstAudioBlockType inputBlock;
173     AudioBlockType& outputBlock;
174 };
175 
176 } // namespace dsp
177 } // namespace juce
178