tracktion_Node.h

Go to the documentation of this file.

 /*
    ,--.                     ,--.     ,--.  ,--.
  ,-'  '-.,--.--.,--,--.,---.|  |,-.,-'  '-.`--' ,---. ,--,--,      Copyright 2024
  '-.  .-'|  .--' ,-.  | .--'|     /'-.  .-',--.| .-. ||      \   Tracktion Software
    |  |  |  |  \ '-'  \ `--.|  \  \  |  |  |  |' '-' '|  ||  |       Corporation
    `---' `--'   `--`--'`---'`--'`--' `---' `--' `---' `--''--'    www.tracktion.com
 
    Tracktion Engine uses a GPL/commercial licence - see LICENCE.md for details.
*/
 
#pragma once
 
//==============================================================================
//==============================================================================
namespace tracktion { inline namespace graph
{
 
class Node;
 
//==============================================================================
//==============================================================================
template<typename NodeType, typename... Args>
std::unique_ptr<Node> makeNode (Args&&... args)
{
    return std::unique_ptr<tracktion::graph::Node> (std::move (std::make_unique<NodeType> (std::forward<Args> (args)...)));
}
 
 
//==============================================================================
struct NodeBuffer
{
    choc::buffer::ChannelArrayView<float> view;
    choc::buffer::ChannelArrayBuffer<float> data;
};
 
//==============================================================================
struct NodeAndID
{
    Node* node = nullptr;
    size_t id = 0;
};
 
inline bool operator< (NodeAndID n1, NodeAndID n2)
{
    return n1.id < n2.id;
}
 
inline bool operator== (NodeAndID n1, NodeAndID n2)
{
    return n1.node == n2.node && n1.id == n2.id;
}
 
struct NodeGraph
{
    std::unique_ptr<Node> rootNode;
    std::vector<Node*> orderedNodes;
    std::vector<NodeAndID> sortedNodes;
};
 
 
std::unique_ptr<NodeGraph> createNodeGraph (std::unique_ptr<Node>);
 
 
//==============================================================================
struct PlaybackInitialisationInfo
{
    double sampleRate;
    int blockSize;
    NodeGraph& nodeGraph;
    NodeGraph* nodeGraphToReplace = nullptr;
    std::function<NodeBuffer (choc::buffer::Size)> allocateAudioBuffer = nullptr;
    std::function<void (NodeBuffer&&)> deallocateAudioBuffer = nullptr;
    bool enableNodeMemorySharing = false; //** @internal */
};
 
struct NodeProperties
{
    bool hasAudio = false;
    bool hasMidi = false;
    int numberOfChannels = 0;
    int latencyNumSamples = 0;
    size_t nodeID = 0;
};
 
//==============================================================================
//==============================================================================
enum class TransformResult
{
    none,               
    connectionsMade,    
    nodesDeleted        
};
 
enum class ClearBuffers
{
    no, 
    yes 
};
 
enum class AllocateAudioBuffer
{
    no, 
    yes 
};
 
struct NodeOptimisations
{
    ClearBuffers clear = ClearBuffers::yes;
    AllocateAudioBuffer allocate = AllocateAudioBuffer::yes;
};
 
//==============================================================================
//==============================================================================
class TransformCache
{
public:
    TransformCache() = default;
 
    template<typename T>
    void cacheProperty (size_t key, T value);
 
    template<typename T>
    T* getCachedProperty (size_t key);
 
private:
    std::unordered_map<size_t, std::any> cache;
};
 
//==============================================================================
//==============================================================================
class Node
{
public:
    Node() = default;
    virtual ~Node() = default;
 
    //==============================================================================
    void initialise (const PlaybackInitialisationInfo&);
 
    void prepareForNextBlock (juce::Range<int64_t> referenceSampleRange);
 
    void process (choc::buffer::FrameCount numSamples, juce::Range<int64_t> referenceSampleRange);
 
    bool hasProcessed() const;
 
    struct AudioAndMidiBuffer
    {
        choc::buffer::ChannelArrayView<float> audio;
        tracktion_engine::MidiMessageArray& midi;
    };
 
    AudioAndMidiBuffer getProcessedOutput();
 
    //==============================================================================
    virtual TransformResult transform (Node& /*rootNode*/,
                                       const std::vector<Node*>& /*postOrderedNodes*/,
                                       TransformCache&)
    {
        return TransformResult::none;
    }
 
    virtual std::vector<Node*> getDirectInputNodes() { return {}; }
 
    virtual std::vector<Node*> getInternalNodes() { return {}; }
 
    virtual NodeProperties getNodeProperties() = 0;
 
    virtual bool isReadyToProcess() = 0;
 
    struct ProcessContext
    {
        choc::buffer::FrameCount numSamples;
        juce::Range<int64_t> referenceSampleRange;
        AudioAndMidiBuffer buffers;
    };
 
    //==============================================================================
    void retain();
 
    void release();
 
    //==============================================================================
    void* internal = nullptr;
    int numOutputNodes = -1;
    virtual size_t getAllocatedBytes() const;
    void enablePreProcess (bool);
 
protected:
    virtual void prepareToPlay (const PlaybackInitialisationInfo&) {}
 
    virtual void prefetchBlock (juce::Range<int64_t> /*referenceSampleRange*/) {}
 
    virtual void process (ProcessContext&) = 0;
 
    virtual void preProcess (choc::buffer::FrameCount /*numSamples*/,
                             juce::Range<int64_t> /*referenceSampleRange*/)
    {}
 
    //==============================================================================
    void setOptimisations (NodeOptimisations);
 
    void setBufferViewToUse (Node* sourceNode, const choc::buffer::ChannelArrayView<float>&);
 
    void setAudioOutput (Node* sourceNode, const choc::buffer::ChannelArrayView<float>&);
 
private:
    std::atomic<bool> hasBeenProcessed { false };
    choc::buffer::Size audioBufferSize;
    choc::buffer::ChannelArrayBuffer<float> audioBuffer;
    choc::buffer::ChannelArrayView<float> audioView, allocatedView;
    std::optional<choc::buffer::ChannelArrayView<float>> referencedViewToUse;
    tracktion_engine::MidiMessageArray midiBuffer;
    std::atomic<int> numSamplesProcessed { 0 }, retainCount { 0 };
    NodeOptimisations nodeOptimisations;
 
 
    std::vector<Node*> directInputNodes;
    std::atomic<Node*> nodeToRelease { nullptr };
    std::function<NodeBuffer (choc::buffer::Size)> allocateAudioBuffer = nullptr;
    std::function<void (NodeBuffer&&)> deallocateAudioBuffer = nullptr;
 
   #if JUCE_DEBUG
    std::atomic<bool> isBeingProcessed { false };
   #endif
};
 
//==============================================================================
//==============================================================================
template<typename Visitor>
void visitNodes (Node&, Visitor&&, bool preordering);
 
//==============================================================================
enum class VertexOrdering
{
    preordering,            // The order in which nodes are first visited
    postordering,           // The order in which nodes are last visited
    reversePreordering,     // The reverse of the preordering
    reversePostordering,    // The reverse of the postordering
    bfsPreordering,         // A breadth-first search
    bfsReversePreordering   // A reversed breadth-first search
};
 
static inline std::vector<Node*> getNodes (Node&, VertexOrdering);
 
 
//==============================================================================
//==============================================================================
static inline std::vector<Node*> transformNodes (Node& rootNode)
{
    for (;;)
    {
        bool needToTransformAgain = false;
 
        auto allNodes = getNodes (rootNode, VertexOrdering::postordering);
        TransformCache cache;
 
        for (auto node : allNodes)
        {
            const auto res = node->transform (rootNode, allNodes, cache);
 
            if (res == TransformResult::none)
                continue;
 
            needToTransformAgain = true;
 
            // Nodes may have been deleted from allNodes so start from the top
            if (res == TransformResult::nodesDeleted)
                break;
 
            // New connections have been made but allNodes is still valid
            assert (res == TransformResult::connectionsMade);
        }
 
        if (! needToTransformAgain)
            return allNodes;
    }
}
 
 
//==============================================================================
//==============================================================================
inline void Node::initialise (const PlaybackInitialisationInfo& info)
{
    prepareToPlay (info);
 
    auto props = getNodeProperties();
    audioBufferSize = choc::buffer::Size::create ((choc::buffer::ChannelCount) props.numberOfChannels,
                                                  (choc::buffer::FrameCount) info.blockSize);
 
    if (info.allocateAudioBuffer)
    {
        allocateAudioBuffer = info.allocateAudioBuffer;
        deallocateAudioBuffer = info.deallocateAudioBuffer;
    }
    else if (nodeOptimisations.allocate == AllocateAudioBuffer::yes)
    {
        audioBuffer.resize (audioBufferSize);
    }
 
    directInputNodes = getDirectInputNodes();
}
 
inline void Node::prepareForNextBlock (juce::Range<int64_t> referenceSampleRange)
{
    // Only do this once as prepare may be called multiple times
    if (retainCount == 0)
    {
        assert (directInputNodes.size() == getDirectInputNodes().size());
        nodeToRelease.store (nullptr, std::memory_order_relaxed); // Reset in case the output node behaviour changes
 
        retain();
 
        for (auto& n : directInputNodes)
            n->retain();
    }
 
    hasBeenProcessed.store (false, std::memory_order_release);
    prefetchBlock (referenceSampleRange);
}
 
inline void Node::process (choc::buffer::FrameCount numSamples, juce::Range<int64_t> referenceSampleRange)
{
   #if JUCE_DEBUG
    assert (! isBeingProcessed);
    isBeingProcessed = true;
 
    for (auto n : directInputNodes)
        assert (n->hasProcessed());
   #endif
 
    preProcess (numSamples, referenceSampleRange);
 
    // First, allocate buffers if possible
    if (allocateAudioBuffer)
    {
        auto nodeBuffer = allocateAudioBuffer (audioBufferSize);
        audioBuffer = std::move (nodeBuffer.data);
        allocatedView = std::move (nodeBuffer.view);
        assert (audioBufferSize == allocatedView.getSize());
    }
 
    if (nodeOptimisations.clear == ClearBuffers::yes)
    {
        audioBuffer.clear();
        midiBuffer.clear();
    }
 
    const auto numChannelsBeforeProcessing = audioBuffer.getNumChannels();
    const auto numSamplesBeforeProcessing = audioBuffer.getNumFrames();
    juce::ignoreUnused (numChannelsBeforeProcessing, numSamplesBeforeProcessing);
 
    jassert (numSamples > 0); // This must be a valid number of samples to process
    jassert (numChannelsBeforeProcessing == 0 || numSamples <= audioBuffer.getNumFrames());
 
    if (allocatedView.getSize() == audioBufferSize)
    {
        // Use a pre-allocated view if one has been initialised
        audioView = allocatedView;
    }
    else
    {
        // Fallback to the internal buffer or an empty view
        audioView = ((nodeOptimisations.allocate == AllocateAudioBuffer::yes ? audioBuffer.getView()
                                                                             : referencedViewToUse ? referencedViewToUse->getFirstChannels (audioBufferSize.numChannels)
                                                                                                   : choc::buffer::ChannelArrayView<float> { {}, audioBufferSize }));
    }
 
    audioView = audioView.getStart (numSamples);
 
    auto destAudioView = audioView;
    ProcessContext pc { numSamples, referenceSampleRange, { destAudioView, midiBuffer } };
    process (pc);
    numSamplesProcessed.store ((int) numSamples, std::memory_order_release);
 
    jassert (numChannelsBeforeProcessing == audioBuffer.getNumChannels());
    jassert (numSamplesBeforeProcessing == audioBuffer.getNumFrames());
 
    release();
 
    for (auto& n : directInputNodes)
        n->release();
 
    // If you've set a new view with setAudioOutput, they must be the same size!
    jassert (destAudioView.getSize() == audioView.getSize());
 
   #if JUCE_DEBUG
    isBeingProcessed = false;
   #endif
 
    // N.B. This must be set last to release the Node back to the player
    hasBeenProcessed.store (true, std::memory_order_release);
}
 
inline bool Node::hasProcessed() const
{
    return hasBeenProcessed.load (std::memory_order_acquire);
}
 
inline Node::AudioAndMidiBuffer Node::getProcessedOutput()
{
    jassert (hasProcessed());
 
   #if JUCE_DEBUG
    if ([[ maybe_unused ]] auto node = nodeToRelease.load (std::memory_order_acquire))
        jassert (node->hasProcessed());
   #endif
 
    return { audioView.getStart ((choc::buffer::FrameCount) numSamplesProcessed.load (std::memory_order_acquire)),
             midiBuffer };
}
 
inline size_t Node::getAllocatedBytes() const
{
    return audioBuffer.getView().data.getBytesNeeded (audioBuffer.getSize())
        + (size_t (midiBuffer.size()) * sizeof (tracktion_engine::MidiMessageArray::MidiMessageWithSource));
}
 
inline void Node::setOptimisations (NodeOptimisations newOptimisations)
{
    nodeOptimisations = newOptimisations;
}
 
inline void Node::setBufferViewToUse (Node* sourceNode, const choc::buffer::ChannelArrayView<float>& view)
{
    if (sourceNode)
    {
        sourceNode->retain();
        nodeToRelease.store (sourceNode, std::memory_order_relaxed);
    }
 
    referencedViewToUse = view;
}
 
inline void Node::setAudioOutput (Node* sourceNode, const choc::buffer::ChannelArrayView<float>& newAudioView)
{
    if ([[ maybe_unused ]] auto node = nodeToRelease.load (std::memory_order_relaxed))
    {
        assert (sourceNode == node);
    }
    else if (sourceNode)
    {
        sourceNode->retain();
        nodeToRelease.store (sourceNode, std::memory_order_relaxed);
    }
 
    audioView = newAudioView;
}
 
inline void Node::retain()
{
    assert (retainCount.load() >= 0);
    retainCount.fetch_add (1, std::memory_order_relaxed);
}
 
inline void Node::release()
{
    assert (retainCount.load() > 0);
 
    if (retainCount.fetch_sub (1, std::memory_order_acq_rel) == 1)
    {
        if (auto node = nodeToRelease.load (std::memory_order_relaxed))
            node->release();
 
        if (deallocateAudioBuffer)
            deallocateAudioBuffer ({ std::move (allocatedView), std::move (audioBuffer) });
    }
}
 
//==============================================================================
//==============================================================================
namespace detail
{
    struct VisitNodesWithRecord
    {
        template<typename Visitor>
        static void visit (std::vector<Node*>& visitedNodes, Node& visitingNode, Visitor&& visitor, bool preordering)
        {
            if (std::find (visitedNodes.begin(), visitedNodes.end(), &visitingNode) != visitedNodes.end())
                return;
 
            if (preordering)
            {
                visitedNodes.push_back (&visitingNode);
                visitor (visitingNode);
            }
 
            for (auto n : visitingNode.getDirectInputNodes())
                visit  (visitedNodes, *n, visitor, preordering);
 
            if (! preordering)
            {
                visitedNodes.push_back (&visitingNode);
                visitor (visitingNode);
            }
        }
    };
 
    struct VisitNodesWithRecordBFS
    {
        template<typename Visitor>
        static void visit (std::vector<Node*>& visitedNodes, Node& visitingNode, Visitor&& visitor)
        {
            if (std::find (visitedNodes.begin(), visitedNodes.end(), &visitingNode) == visitedNodes.end())
            {
                visitedNodes.push_back (&visitingNode);
                visitor (visitingNode);
            }
 
            auto inputs = visitingNode.getDirectInputNodes();
 
            // Visit each node then go back to the first and recurse
            for (auto n : inputs)
            {
                if (std::find (visitedNodes.begin(), visitedNodes.end(), n) == visitedNodes.end())
                {
                    visitedNodes.push_back (n);
                    visitor (visitingNode);
                }
            }
 
            for (auto n : inputs)
                visit  (visitedNodes, *n, visitor);
        }
    };
}
 
template<typename Visitor>
inline void visitNodes (Node& node, Visitor&& visitor, bool preordering)
{
    std::vector<Node*> visitedNodes;
    detail::VisitNodesWithRecord::visit (visitedNodes, node, visitor, preordering);
}
 
template<typename Visitor>
inline void visitNodesBFS (Node& node, Visitor&& visitor)
{
    std::vector<Node*> visitedNodes;
    detail::VisitNodesWithRecordBFS::visit (visitedNodes, node, visitor);
}
 
inline std::vector<Node*> getNodes (Node& node, VertexOrdering vertexOrdering)
{
    if (vertexOrdering == VertexOrdering::bfsPreordering
        || vertexOrdering == VertexOrdering::bfsReversePreordering)
    {
        std::vector<Node*> visitedNodes;
        detail::VisitNodesWithRecordBFS::visit (visitedNodes, node, [](auto&){});
 
        if (vertexOrdering == VertexOrdering::bfsReversePreordering)
            std::reverse (visitedNodes.begin(), visitedNodes.end());
 
        return visitedNodes;
    }
 
    bool preordering = vertexOrdering == VertexOrdering::preordering
                    || vertexOrdering == VertexOrdering::reversePreordering;
 
    std::vector<Node*> visitedNodes;
    detail::VisitNodesWithRecord::visit (visitedNodes, node, [](auto&){}, preordering);
 
    if (vertexOrdering == VertexOrdering::reversePreordering
        || vertexOrdering == VertexOrdering::reversePostordering)
       std::reverse (visitedNodes.begin(), visitedNodes.end());
 
    return visitedNodes;
}
 
inline void addNodesRecursive (std::vector<NodeAndID>& nodeMap, Node& n)
{
    nodeMap.push_back ({ &n, n.getNodeProperties().nodeID });
 
    for (auto internalNode : n.getInternalNodes())
        addNodesRecursive (nodeMap, *internalNode);
}
 
inline std::vector<NodeAndID> createNodeMap (const std::vector<Node*>& nodes)
{
    std::vector<NodeAndID> nodeMap;
 
    for (auto n : nodes)
        addNodesRecursive (nodeMap, *n);
 
    std::sort (nodeMap.begin(), nodeMap.end());
    nodeMap.erase (std::unique (nodeMap.begin(), nodeMap.end()),
                   nodeMap.end());
 
    return nodeMap;
}
 
inline std::unique_ptr<NodeGraph> createNodeGraph (std::unique_ptr<Node> rootNode)
{
    assert (rootNode != nullptr);
    auto orderedNodes = transformNodes (*rootNode);
    auto sortedNodes = createNodeMap (orderedNodes);
 
    // Iterate all nodes, for each input, increment the dest Node output count
    for (auto node : orderedNodes)
        node->numOutputNodes = 0;
 
    for (auto node : orderedNodes)
        for (auto inputNode : node->getDirectInputNodes())
            ++inputNode->numOutputNodes;
 
    auto nodeGraph = std::make_unique<NodeGraph>();
    nodeGraph->rootNode = std::move (rootNode);
    nodeGraph->orderedNodes = std::move (orderedNodes);
    nodeGraph->sortedNodes = std::move (sortedNodes);
 
    return nodeGraph;
}
 
template<typename T>
inline void TransformCache::cacheProperty (size_t key, T value)
{
    cache[key] = std::move (value);
}
 
template<typename T>
inline T* TransformCache::getCachedProperty (size_t key)
{
    if (auto found = cache.find (key); found != cache.end())
        if (auto* typedValue = std::any_cast<T> (&found->second))
            return typedValue;
 
    return {};
}
 
}}