source/modules/water/processors/AudioProcessor.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the Water library.
   5    Copyright (c) 2015 ROLI Ltd.
   6    Copyright (C) 2017-2022 Filipe Coelho <falktx@falktx.com>
   7
   8    Permission is granted to use this software under the terms of the GNU
   9    General Public License as published by the Free Software Foundation;
  10    either version 2 of the License, or any later version.
  11
  12    This program is distributed in the hope that it will be useful, but WITHOUT
  13    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  14    FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  15
  16    For a full copy of the GNU General Public License see the doc/GPL.txt file.
  17
  18   ==============================================================================
  19 */
  20
  21 #ifndef WATER_AUDIOPROCESSOR_H_INCLUDED
  22 #define WATER_AUDIOPROCESSOR_H_INCLUDED
  23
  24 #include "../text/String.h"
  25 #include "../buffers/AudioSampleBuffer.h"
  26
  27 #include "CarlaMutex.hpp"
  28
  29 namespace water {
  30
  31 //==============================================================================
  32 /**
  33     Base class for audio processing filters or plugins.
  34
  35     This is intended to act as a base class of audio filter that is general enough to
  36     be wrapped as a VST, AU, RTAS, etc, or used internally.
  37
  38     It is also used by the plugin hosting code as the wrapper around an instance
  39     of a loaded plugin.
  40
  41     Derive your filter class from this base class, and if you're building a plugin,
  42     you should implement a global function called createPluginFilter() which creates
  43     and returns a new instance of your subclass.
  44 */
  45 class AudioProcessor
  46 {
  47 protected:
  48     //==============================================================================
  49     /** Constructor.
  50
  51         This constructor will create a main input and output bus which are diabled
  52         by default. If you need more fine grain control then use the other
  53         constructors.
  54     */
  55     AudioProcessor();
  56
  57 public:
  58     enum ChannelType {
  59         ChannelTypeAudio,
  60         ChannelTypeCV,
  61         ChannelTypeMIDI,
  62     };
  63
  64     //==============================================================================
  65     /** Destructor. */
  66     virtual ~AudioProcessor();
  67
  68     //==============================================================================
  69     /** Returns the name of this processor. */
  70     virtual const String getName() const = 0;
  71
  72     //==============================================================================
  73     /** Called before playback starts, to let the filter prepare itself.
  74
  75         The sample rate is the target sample rate, and will remain constant until
  76         playback stops.
  77
  78         You can call getTotalNumInputChannels and getTotalNumOutputChannels
  79         or query the busLayout member variable to find out the number of
  80         channels your processBlock callback must process.
  81
  82         The maximumExpectedSamplesPerBlock value is a strong hint about the maximum
  83         number of samples that will be provided in each block. You may want to use
  84         this value to resize internal buffers. You should program defensively in
  85         case a buggy host exceeds this value. The actual block sizes that the host
  86         uses may be different each time the callback happens: completely variable
  87         block sizes can be expected from some hosts.
  88
  89        @see busLayout, getTotalNumInputChannels, getTotalNumOutputChannels
  90     */
  91     virtual void prepareToPlay (double sampleRate,
  92                                 int maximumExpectedSamplesPerBlock) = 0;
  93
  94     /** Called after playback has stopped, to let the filter free up any resources it
  95         no longer needs.
  96     */
  97     virtual void releaseResources() = 0;
  98
  99     /** Renders the next block.
 100
 101         When this method is called, the buffer contains a number of channels which is
 102         at least as great as the maximum number of input and output channels that
 103         this filter is using. It will be filled with the filter's input data and
 104         should be replaced with the filter's output.
 105
 106         So for example if your filter has a total of 2 input channels and 4 output
 107         channels, then the buffer will contain 4 channels, the first two being filled
 108         with the input data. Your filter should read these, do its processing, and
 109         replace the contents of all 4 channels with its output.
 110
 111         Or if your filter has a total of 5 inputs and 2 outputs, the buffer will have 5
 112         channels, all filled with data, and your filter should overwrite the first 2 of
 113         these with its output. But be VERY careful not to write anything to the last 3
 114         channels, as these might be mapped to memory that the host assumes is read-only!
 115
 116         If your plug-in has more than one input or output buses then the buffer passed
 117         to the processBlock methods will contain a bundle of all channels of each bus.
 118         Use AudiobusLayout::getBusBuffer to obtain an audio buffer for a
 119         particular bus.
 120
 121         Note that if you have more outputs than inputs, then only those channels that
 122         correspond to an input channel are guaranteed to contain sensible data - e.g.
 123         in the case of 2 inputs and 4 outputs, the first two channels contain the input,
 124         but the last two channels may contain garbage, so you should be careful not to
 125         let this pass through without being overwritten or cleared.
 126
 127         Also note that the buffer may have more channels than are strictly necessary,
 128         but you should only read/write from the ones that your filter is supposed to
 129         be using.
 130
 131         The number of samples in these buffers is NOT guaranteed to be the same for every
 132         callback, and may be more or less than the estimated value given to prepareToPlay().
 133         Your code must be able to cope with variable-sized blocks, or you're going to get
 134         clicks and crashes!
 135
 136         Also note that some hosts will occasionally decide to pass a buffer containing
 137         zero samples, so make sure that your algorithm can deal with that!
 138
 139         If the filter is receiving a midi input, then the midiMessages array will be filled
 140         with the midi messages for this block. Each message's timestamp will indicate the
 141         message's time, as a number of samples from the start of the block.
 142
 143         Any messages left in the midi buffer when this method has finished are assumed to
 144         be the filter's midi output. This means that your filter should be careful to
 145         clear any incoming messages from the array if it doesn't want them to be passed-on.
 146
 147         Be very careful about what you do in this callback - it's going to be called by
 148         the audio thread, so any kind of interaction with the UI is absolutely
 149         out of the question. If you change a parameter in here and need to tell your UI to
 150         update itself, the best way is probably to inherit from a ChangeBroadcaster, let
 151         the UI components register as listeners, and then call sendChangeMessage() inside the
 152         processBlock() method to send out an asynchronous message. You could also use
 153         the AsyncUpdater class in a similar way.
 154
 155         @see AudiobusLayout::getBusBuffer
 156     */
 157     virtual void processBlockWithCV (AudioSampleBuffer& audioBuffer,
 158                                      const AudioSampleBuffer& cvInBuffer,
 159                                      AudioSampleBuffer& cvOutBuffer,
 160                                      MidiBuffer& midiMessages) = 0;
 161
 162     //==============================================================================
 163     /** Returns the total number of input channels. */
 164     uint getTotalNumInputChannels(ChannelType t) const noexcept;
 165
 166     /** Returns the total number of output channels. */
 167     uint getTotalNumOutputChannels(ChannelType t) const noexcept;
 168
 169     //==============================================================================
 170     /** Returns the current sample rate.
 171
 172         This can be called from your processBlock() method - it's not guaranteed
 173         to be valid at any other time, and may return 0 if it's unknown.
 174     */
 175     double getSampleRate() const noexcept                       { return currentSampleRate; }
 176
 177     /** Returns the current typical block size that is being used.
 178
 179         This can be called from your processBlock() method - it's not guaranteed
 180         to be valid at any other time.
 181
 182         Remember it's not the ONLY block size that may be used when calling
 183         processBlock, it's just the normal one. The actual block sizes used may be
 184         larger or smaller than this, and will vary between successive calls.
 185     */
 186     int getBlockSize() const noexcept                           { return blockSize; }
 187
 188     //==============================================================================
 189
 190     /** This returns the number of samples delay that the filter imposes on the audio
 191         passing through it.
 192
 193         The host will call this to find the latency - the filter itself should set this value
 194         by calling setLatencySamples() as soon as it can during its initialisation.
 195     */
 196     int getLatencySamples() const noexcept                      { return latencySamples; }
 197
 198     /** The filter should call this to set the number of samples delay that it introduces.
 199
 200         The filter should call this as soon as it can during initialisation, and can call it
 201         later if the value changes.
 202     */
 203     void setLatencySamples (int newLatency);
 204
 205     /** Returns true if the processor wants midi messages. */
 206     virtual bool acceptsMidi() const = 0;
 207
 208     /** Returns true if the processor produces midi messages. */
 209     virtual bool producesMidi() const = 0;
 210
 211     /** Returns true if the processor supports MPE. */
 212     virtual bool supportsMPE() const                            { return false; }
 213
 214     virtual const String getInputChannelName  (ChannelType, uint) const;
 215     virtual const String getOutputChannelName (ChannelType, uint) const;
 216
 217     //==============================================================================
 218     /** This returns a critical section that will automatically be locked while the host
 219         is calling the processBlock() method.
 220
 221         Use it from your UI or other threads to lock access to variables that are used
 222         by the process callback, but obviously be careful not to keep it locked for
 223         too long, because that could cause stuttering playback. If you need to do something
 224         that'll take a long time and need the processing to stop while it happens, use the
 225         suspendProcessing() method instead.
 226
 227         @see suspendProcessing
 228     */
 229     const CarlaRecursiveMutex& getCallbackLock() const noexcept     { return callbackLock; }
 230
 231     /** Enables and disables the processing callback.
 232
 233         If you need to do something time-consuming on a thread and would like to make sure
 234         the audio processing callback doesn't happen until you've finished, use this
 235         to disable the callback and re-enable it again afterwards.
 236
 237         E.g.
 238         @code
 239         void loadNewPatch()
 240         {
 241             suspendProcessing (true);
 242
 243             ..do something that takes ages..
 244
 245             suspendProcessing (false);
 246         }
 247         @endcode
 248
 249         If the host tries to make an audio callback while processing is suspended, the
 250         filter will return an empty buffer, but won't block the audio thread like it would
 251         do if you use the getCallbackLock() critical section to synchronise access.
 252
 253         Any code that calls processBlock() should call isSuspended() before doing so, and
 254         if the processor is suspended, it should avoid the call and emit silence or
 255         whatever is appropriate.
 256
 257         @see getCallbackLock
 258     */
 259     void suspendProcessing (bool shouldBeSuspended);
 260
 261     /** Returns true if processing is currently suspended.
 262         @see suspendProcessing
 263     */
 264     bool isSuspended() const noexcept                                   { return suspended; }
 265
 266     /** A plugin can override this to be told when it should reset any playing voices.
 267
 268         The default implementation does nothing, but a host may call this to tell the
 269         plugin that it should stop any tails or sounds that have been left running.
 270     */
 271     virtual void reset();
 272
 273     /** A plugin can override this to be told when it should reconfigure itself.
 274
 275         The default implementation does nothing, but a host may call this to tell the
 276         plugin that it should call setPlayConfigDetails again.
 277     */
 278     virtual void reconfigure();
 279
 280     //==============================================================================
 281     /** Returns true if the processor is being run in an offline mode for rendering.
 282
 283         If the processor is being run live on realtime signals, this returns false.
 284         If the mode is unknown, this will assume it's realtime and return false.
 285
 286         This value may be unreliable until the prepareToPlay() method has been called,
 287         and could change each time prepareToPlay() is called.
 288
 289         @see setNonRealtime()
 290     */
 291     bool isNonRealtime() const noexcept                                 { return nonRealtime; }
 292
 293     /** Called by the host to tell this processor whether it's being used in a non-realtime
 294         capacity for offline rendering or bouncing.
 295     */
 296     virtual void setNonRealtime (bool isNonRealtime) noexcept;
 297
 298     //==============================================================================
 299     /** This is called by the processor to specify its details before being played. Use this
 300         version of the function if you are not interested in any sidechain and/or aux buses
 301         and do not care about the layout of channels. Otherwise use setRateAndBufferSizeDetails.*/
 302     void setPlayConfigDetails (uint numAudioIns, uint numAudioOuts,
 303                                uint numCVIns, uint numCVOuts,
 304                                uint numMIDIIns, uint numMIDIOuts,
 305                                double sampleRate, int blockSize);
 306
 307     /** This is called by the processor to specify its details before being played. You
 308         should call this function after having informed the processor about the channel
 309         and bus layouts via setBusesLayout.
 310
 311         @see setBusesLayout
 312     */
 313     void setRateAndBufferSizeDetails (double sampleRate, int blockSize) noexcept;
 314
 315 private:
 316     //==============================================================================
 317     double currentSampleRate;
 318     int blockSize, latencySamples;
 319     bool suspended, nonRealtime;
 320     CarlaRecursiveMutex callbackLock;
 321
 322     uint numAudioIns, numAudioOuts;
 323     uint numCVIns, numCVOuts;
 324     uint numMIDIIns, numMIDIOuts;
 325
 326     CARLA_DECLARE_NON_COPYABLE (AudioProcessor)
 327 };
 328
 329 }
 330
 331 #endif // WATER_AUDIOPROCESSOR_H_INCLUDED