source/modules/water/processors/AudioProcessorGraph.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_AUDIOPROCESSORGRAPH_H_INCLUDED
  22 #define WATER_AUDIOPROCESSORGRAPH_H_INCLUDED
  23
  24 #include "AudioProcessor.h"
  25 #include "../containers/OwnedArray.h"
  26 #include "../containers/ReferenceCountedArray.h"
  27 #include "../midi/MidiBuffer.h"
  28
  29 namespace water {
  30
  31 //==============================================================================
  32 /**
  33     A type of AudioProcessor which plays back a graph of other AudioProcessors.
  34
  35     Use one of these objects if you want to wire-up a set of AudioProcessors
  36     and play back the result.
  37
  38     Processors can be added to the graph as "nodes" using addNode(), and once
  39     added, you can connect any of their input or output channels to other
  40     nodes using addConnection().
  41
  42     To play back a graph through an audio device, you might want to use an
  43     AudioProcessorPlayer object.
  44 */
  45 class AudioProcessorGraph   : public AudioProcessor
  46 {
  47 public:
  48     //==============================================================================
  49     /** Creates an empty graph. */
  50     AudioProcessorGraph();
  51
  52     /** Destructor.
  53         Any processor objects that have been added to the graph will also be deleted.
  54     */
  55     ~AudioProcessorGraph();
  56
  57     //==============================================================================
  58     /** Represents one of the nodes, or processors, in an AudioProcessorGraph.
  59
  60         To create a node, call AudioProcessorGraph::addNode().
  61     */
  62     class Node   : public ReferenceCountedObject
  63     {
  64     public:
  65         //==============================================================================
  66         /** The ID number assigned to this node.
  67             This is assigned by the graph that owns it, and can't be changed.
  68         */
  69         const uint32 nodeId;
  70
  71         /** The actual processor object that this node represents. */
  72         AudioProcessor* getProcessor() const noexcept           { return processor; }
  73
  74         /** Custom properties for Carla usage. */
  75         struct Properties {
  76             bool isAudio;
  77             bool isCV;
  78             bool isMIDI;
  79             bool isOSC;
  80             bool isOutput;
  81             bool isPlugin;
  82             uint32_t pluginId;
  83
  84             struct Position {
  85                 int x1, x2, y1, y2;
  86                 bool valid;
  87
  88                 Position() noexcept
  89                     : x1(0),
  90                       x2(0),
  91                       y1(0),
  92                       y2(0),
  93                       valid(false) {}
  94             } position;
  95
  96             Properties() noexcept
  97                 : isAudio(false),
  98                   isCV(false),
  99                   isMIDI(false),
 100                   isOSC(false),
 101                   isOutput(false),
 102                   isPlugin(false),
 103                   pluginId(0),
 104                   position() {}
 105         } properties;
 106
 107         //==============================================================================
 108         /** A convenient typedef for referring to a pointer to a node object. */
 109         typedef ReferenceCountedObjectPtr<Node> Ptr;
 110
 111     private:
 112         //==============================================================================
 113         friend class AudioProcessorGraph;
 114
 115         const CarlaScopedPointer<AudioProcessor> processor;
 116         bool isPrepared;
 117
 118         Node (uint32 nodeId, AudioProcessor*) noexcept;
 119
 120         void setParentGraph (AudioProcessorGraph*) const;
 121         void prepare (double newSampleRate, int newBlockSize, AudioProcessorGraph*);
 122         void unprepare();
 123
 124         CARLA_DECLARE_NON_COPYABLE (Node)
 125     };
 126
 127     //==============================================================================
 128     /** Represents a connection between two channels of two nodes in an AudioProcessorGraph.
 129
 130         To create a connection, use AudioProcessorGraph::addConnection().
 131     */
 132     struct Connection
 133     {
 134     public:
 135         //==============================================================================
 136         Connection (ChannelType channelType,
 137                     uint32 sourceNodeId, uint sourceChannelIndex,
 138                     uint32 destNodeId, uint destChannelIndex) noexcept;
 139
 140         //==============================================================================
 141         /** Defines the connection type. */
 142         ChannelType channelType;
 143
 144         /** The ID number of the node which is the input source for this connection.
 145             @see AudioProcessorGraph::getNodeForId
 146         */
 147         uint32 sourceNodeId;
 148
 149         /** The index of the output channel of the source node from which this
 150             connection takes its data.
 151
 152             If this value is the special number AudioProcessorGraph::midiChannelIndex, then
 153             it is referring to the source node's midi output. Otherwise, it is the zero-based
 154             index of an audio output channel in the source node.
 155         */
 156         uint sourceChannelIndex;
 157
 158         /** The ID number of the node which is the destination for this connection.
 159             @see AudioProcessorGraph::getNodeForId
 160         */
 161         uint32 destNodeId;
 162
 163         /** The index of the input channel of the destination node to which this
 164             connection delivers its data.
 165
 166             If this value is the special number AudioProcessorGraph::midiChannelIndex, then
 167             it is referring to the destination node's midi input. Otherwise, it is the zero-based
 168             index of an audio input channel in the destination node.
 169         */
 170         uint destChannelIndex;
 171     };
 172
 173     //==============================================================================
 174     /** Deletes all nodes and connections from this graph.
 175         Any processor objects in the graph will be deleted.
 176     */
 177     void clear();
 178
 179     /** Returns the number of nodes in the graph. */
 180     int getNumNodes() const noexcept                                { return nodes.size(); }
 181
 182     /** Returns a pointer to one of the nodes in the graph.
 183         This will return nullptr if the index is out of range.
 184         @see getNodeForId
 185     */
 186     Node* getNode (const int index) const noexcept                  { return nodes [index]; }
 187
 188     /** Searches the graph for a node with the given ID number and returns it.
 189         If no such node was found, this returns nullptr.
 190         @see getNode
 191     */
 192     Node* getNodeForId (const uint32 nodeId) const;
 193
 194     /** Adds a node to the graph.
 195
 196         This creates a new node in the graph, for the specified processor. Once you have
 197         added a processor to the graph, the graph owns it and will delete it later when
 198         it is no longer needed.
 199
 200         The optional nodeId parameter lets you specify an ID to use for the node, but
 201         if the value is already in use, this new node will overwrite the old one.
 202
 203         If this succeeds, it returns a pointer to the newly-created node.
 204     */
 205     Node* addNode (AudioProcessor* newProcessor, uint32 nodeId = 0);
 206
 207     /** Deletes a node within the graph which has the specified ID.
 208
 209         This will also delete any connections that are attached to this node.
 210     */
 211     bool removeNode (uint32 nodeId);
 212
 213     /** Deletes a node within the graph which has the specified ID.
 214
 215         This will also delete any connections that are attached to this node.
 216      */
 217     bool removeNode (Node* node);
 218
 219     //==============================================================================
 220     /** Returns the number of connections in the graph. */
 221     size_t getNumConnections() const                                    { return connections.size(); }
 222
 223     /** Returns a pointer to one of the connections in the graph. */
 224     const Connection* getConnection (size_t index) const                { return connections [index]; }
 225
 226     /** Searches for a connection between some specified channels.
 227         If no such connection is found, this returns nullptr.
 228     */
 229     const Connection* getConnectionBetween (ChannelType channelType,
 230                                             uint32 sourceNodeId,
 231                                             uint sourceChannelIndex,
 232                                             uint32 destNodeId,
 233                                             uint destChannelIndex) const;
 234
 235     /** Returns true if there is a connection between any of the channels of
 236         two specified nodes.
 237     */
 238     bool isConnected (uint32 possibleSourceNodeId,
 239                       uint32 possibleDestNodeId) const;
 240
 241     /** Returns true if it would be legal to connect the specified points. */
 242     bool canConnect (ChannelType channelType,
 243                      uint32 sourceNodeId, uint sourceChannelIndex,
 244                      uint32 destNodeId, uint destChannelIndex) const;
 245
 246     /** Attempts to connect two specified channels of two nodes.
 247
 248         If this isn't allowed (e.g. because you're trying to connect a midi channel
 249         to an audio one or other such nonsense), then it'll return false.
 250     */
 251     bool addConnection (ChannelType channelType,
 252                         uint32 sourceNodeId, uint sourceChannelIndex,
 253                         uint32 destNodeId, uint destChannelIndex);
 254
 255     /** Deletes the connection with the specified index. */
 256     void removeConnection (int index);
 257
 258     /** Deletes any connection between two specified points.
 259         Returns true if a connection was actually deleted.
 260     */
 261     bool removeConnection (ChannelType channelType,
 262                            uint32 sourceNodeId, uint sourceChannelIndex,
 263                            uint32 destNodeId, uint destChannelIndex);
 264
 265     /** Removes all connections from the specified node. */
 266     bool disconnectNode (uint32 nodeId);
 267
 268     /** Returns true if the given connection's channel numbers map on to valid
 269         channels at each end.
 270         Even if a connection is valid when created, its status could change if
 271         a node changes its channel config.
 272     */
 273     bool isConnectionLegal (const Connection* connection) const;
 274
 275     /** Performs a sanity checks of all the connections.
 276
 277         This might be useful if some of the processors are doing things like changing
 278         their channel counts, which could render some connections obsolete.
 279     */
 280     bool removeIllegalConnections();
 281
 282     //==============================================================================
 283     /** A special number that represents the midi channel of a node.
 284
 285         This is used as a channel index value if you want to refer to the midi input
 286         or output instead of an audio channel.
 287     */
 288     static const uint midiChannelIndex;
 289
 290
 291     //==============================================================================
 292     /** A special type of AudioProcessor that can live inside an AudioProcessorGraph
 293         in order to use the audio that comes into and out of the graph itself.
 294
 295         If you create an AudioGraphIOProcessor in "input" mode, it will act as a
 296         node in the graph which delivers the audio that is coming into the parent
 297         graph. This allows you to stream the data to other nodes and process the
 298         incoming audio.
 299
 300         Likewise, one of these in "output" mode can be sent data which it will add to
 301         the sum of data being sent to the graph's output.
 302
 303         @see AudioProcessorGraph
 304     */
 305     class AudioGraphIOProcessor     : public AudioProcessor
 306     {
 307     public:
 308         /** Specifies the mode in which this processor will operate.
 309         */
 310         enum IODeviceType
 311         {
 312             audioInputNode,     /**< In this mode, the processor has output channels
 313                                      representing all the audio input channels that are
 314                                      coming into its parent audio graph. */
 315             audioOutputNode,    /**< In this mode, the processor has input channels
 316                                      representing all the audio output channels that are
 317                                      going out of its parent audio graph. */
 318             midiInputNode,      /**< In this mode, the processor has a midi output which
 319                                      delivers the same midi data that is arriving at its
 320                                      parent graph. */
 321             midiOutputNode,     /**< In this mode, the processor has a midi input and
 322                                      any data sent to it will be passed out of the parent
 323                                      graph. */
 324             cvInputNode, cvOutputNode,
 325         };
 326
 327         //==============================================================================
 328         /** Returns the mode of this processor. */
 329         IODeviceType getType() const noexcept                       { return type; }
 330
 331         /** Returns the parent graph to which this processor belongs, or nullptr if it
 332             hasn't yet been added to one. */
 333         AudioProcessorGraph* getParentGraph() const noexcept        { return graph; }
 334
 335         /** True if this is an audio or midi input. */
 336         bool isInput() const noexcept;
 337         /** True if this is an audio or midi output. */
 338         bool isOutput() const noexcept;
 339
 340         //==============================================================================
 341         AudioGraphIOProcessor (const IODeviceType type);
 342         ~AudioGraphIOProcessor();
 343
 344         const String getName() const override;
 345         void prepareToPlay (double newSampleRate, int estimatedSamplesPerBlock) override;
 346         void releaseResources() override;
 347         void processBlockWithCV (AudioSampleBuffer& audioBuffer,
 348                                  const AudioSampleBuffer& cvInBuffer,
 349                                  AudioSampleBuffer& cvOutBuffer,
 350                                  MidiBuffer& midiMessages) override;
 351
 352         bool acceptsMidi() const override;
 353         bool producesMidi() const override;
 354
 355         /** @internal */
 356         void setParentGraph (AudioProcessorGraph*);
 357
 358     private:
 359         const IODeviceType type;
 360         AudioProcessorGraph* graph;
 361
 362         //==============================================================================
 363         //void processAudio (AudioSampleBuffer& buffer, MidiBuffer& midiMessages);
 364         void processAudioAndCV (AudioSampleBuffer& audioBuffer,
 365                                 const AudioSampleBuffer& cvInBuffer,
 366                                 AudioSampleBuffer& cvOutBuffer,
 367                                 MidiBuffer& midiMessages);
 368
 369         CARLA_DECLARE_NON_COPYABLE (AudioGraphIOProcessor)
 370     };
 371
 372     //==============================================================================
 373     const String getName() const override;
 374     void prepareToPlay (double, int) override;
 375     void releaseResources() override;
 376     //void processBlock (AudioSampleBuffer&,  MidiBuffer&) override;
 377     void processBlockWithCV (AudioSampleBuffer& audioBuffer,
 378                              const AudioSampleBuffer& cvInBuffer,
 379                              AudioSampleBuffer& cvOutBuffer,
 380                              MidiBuffer& midiMessages) override;
 381
 382     void reset() override;
 383     void setNonRealtime (bool) noexcept override;
 384
 385     bool acceptsMidi() const override;
 386     bool producesMidi() const override;
 387
 388     void reorderNowIfNeeded();
 389     const CarlaRecursiveMutex& getReorderMutex() const;
 390
 391 private:
 392     //==============================================================================
 393     // void processAudio (AudioSampleBuffer& audioBuffer, MidiBuffer& midiMessages);
 394     void processAudioAndCV (AudioSampleBuffer& audioBuffer,
 395                             const AudioSampleBuffer& cvInBuffer,
 396                             AudioSampleBuffer& cvOutBuffer,
 397                             MidiBuffer& midiMessages);
 398
 399     //==============================================================================
 400     ReferenceCountedArray<Node> nodes;
 401     OwnedArray<Connection> connections;
 402     uint32 lastNodeId;
 403     OwnedArray<MidiBuffer> midiBuffers;
 404     Array<void*> renderingOps;
 405
 406     friend class AudioGraphIOProcessor;
 407     struct AudioProcessorGraphBufferHelpers;
 408     CarlaScopedPointer<AudioProcessorGraphBufferHelpers> audioAndCVBuffers;
 409
 410     MidiBuffer* currentMidiInputBuffer;
 411     MidiBuffer currentMidiOutputBuffer;
 412
 413     bool isPrepared, needsReorder;
 414     CarlaRecursiveMutex reorderMutex;
 415
 416 public:
 417     void clearRenderingSequence();
 418     void buildRenderingSequence();
 419     bool isAnInputTo (uint32 possibleInputId, uint32 possibleDestinationId, int recursionCheck) const;
 420
 421     CARLA_DECLARE_NON_COPYABLE (AudioProcessorGraph)
 422 };
 423
 424 }
 425
 426 #endif // WATER_AUDIOPROCESSORGRAPH_H_INCLUDED