Automation: Refactored AutomationCurve and added automation clips via AutomationCurveModifier (#258)

Author: drowaudio

BREAKING-CHANGES.md

@@ -1,6 +1,19 @@
 # Tracktion Engine breaking changes
 
-## Develop
+
+### Change
+`AutomationCurve` has been restructured. It now only stores the parameter as a string and not a reference.
+
+#### Possible Issues
+Many functions now need a `AutomatableParameter&`, `TempoSequence&` or `juce::UndoManager*` as additional arguments. 
+
+#### Workaround
+These extra parameters are usually within easy reach at the call site. You can use the new `getTempoSequence (Type&)` and `getUndoManager_p (Type&)` to easily get these from a bunch of objects.  
+
+#### Rationale
+This decoupling enables `AutomationCurve` to be used in more places and supports clip automation and `AutomationClip`s.
+
+___
 
 ### Change
 The `Edit` constructor can now throw exceptions in rare cases. E.g. if it's being constructed on the message thread which is blocked.

modules/juce

@@ -19,6 +19,7 @@
 #define GRAPH_UNIT_TESTS_EDITNODE                       1
 
 #define ENGINE_UNIT_TESTS_AUTOMATION                    1
+#define ENGINE_UNIT_TESTS_AUTOMATION_CURVE_LIST         1
 #define ENGINE_UNIT_TESTS_AUX_SEND                      1
 #define ENGINE_UNIT_TESTS_CLIPBOARD                     1
 #define ENGINE_UNIT_TESTS_CLIPSLOT                      1
@@ -73,6 +74,7 @@
 
 #define GRAPH_BENCHMARKS_THREADS                        1
 
+#define ENGINE_BENCHMARKS_AUTOMATIONITERATOR            1
 #define ENGINE_BENCHMARKS_AUDIOFILECACHE                1
 #define ENGINE_BENCHMARKS_CONTAINERCLIP                 1
 #define ENGINE_BENCHMARKS_MIDICLIP                      1

modules/tracktion_core/tracktion_TestConfig.h

@@ -173,4 +173,17 @@ juce::Array<Type> remove_if_nullptr (juce::Array<Type>&& container)
     return std::move (container);
 }
 
+/** Implemtation of C++23's std::unreachable. */
+[[noreturn]] inline void unreachable()
+{
+    // Uses compiler specific extensions if possible.
+    // Even if no extension is used, undefined behavior is still raised by
+    // an empty function body and the noreturn attribute.
+   #if defined(_MSC_VER) && !defined(__clang__) // MSVC
+    __assume(false);
+   #else // GCC, Clang
+    __builtin_unreachable();
+   #endif
+}
+
 }}

modules/tracktion_core/utilities/tracktion_AlgorithmAdapters.h

@@ -177,6 +177,29 @@ struct ScopedBenchmark
     Benchmark benchmark;
 };
 
+//==============================================================================
+/**
+    Similar to ScopedBenchmark except it doesn't start/stop the measurement so
+    you can do this manually (or with a ScopedMeasurement) around a specific
+    code section.
+*/
+struct PublishingBenchmark
+{
+    /** Constructs a Benchmark. */
+    PublishingBenchmark (BenchmarkDescription desc)
+        : benchmark (std::move (desc))
+    {
+    }
+
+    /** Adds the result to the BenchmarkList. */
+    ~PublishingBenchmark()
+    {
+        BenchmarkList::getInstance().addResult (benchmark.getResult());
+    }
+
+    Benchmark benchmark;
+};
+
 //==============================================================================
 /**
     Helper class for starting/stopping a benchmark measurement.

modules/tracktion_core/utilities/tracktion_Benchmark.h

@@ -70,6 +70,39 @@ inline void getBezierEnds (const double x1, const double y1, const double x2, co
     }
 }
 
+struct BezierEnds
+{
+    double x1, y1, x2, y2;
+};
+
+inline BezierEnds getBezierEnds (const double x1, const double y1, const double x2, const double y2, const double c) noexcept
+{
+    BezierEnds ends;
+
+    auto minic = (std::abs (c) - 0.5f) * 2.0f;
+    auto run   = minic * (x2 - x1);
+    auto rise  = minic * ((y2 > y1) ? (y2 - y1) : (y1 - y2));
+
+    if (c > 0)
+    {
+        ends.x1 = x1 + run;
+        ends.y1 = (float) y1;
+
+        ends.x2 = x2;
+        ends.y2 = (float) (y1 < y2 ? (y2 - rise) : (y2 + rise));
+    }
+    else
+    {
+        ends.x1 = x1;
+        ends.y1 = (float) (y1 < y2 ? (y1 + rise) : (y1 - rise));
+
+        ends.x2 = x2 - run;
+        ends.y2 = (float) y2;
+    }
+
+    return ends;
+}
+
 inline double getBezierYFromX (double x, double x1, double y1, double xb, double yb, double x2, double y2) noexcept
 {
     // test for straight lines and bail out
@@ -110,4 +143,13 @@ inline double getBezierYFromX (double x, double x1, double y1, double xb, double
     return y;
 }
 
+inline double getBezierXfromT (double t, double x1, double xb, double x2)
+{
+    // test for straight lines and bail out
+    if (x1 == x2)
+        return (x1 + x2) / 2.0 * t + x1;
+
+    return (std::pow (1.0 - t, 2.0) * x1) + 2 * t * (1 - t) * xb + std::pow (t, 2.0) * x2;
+}
+
 }}

modules/tracktion_core/utilities/tracktion_Bezier.h

@@ -16,10 +16,12 @@ AutomatableEditItem::AutomatableEditItem (Edit& ed, const juce::ValueTree& v)
       elementState (v)
 {
     remapOnTempoChange.referTo (elementState, IDs::remapOnTempoChange, &edit.getUndoManager(), false);
+    edit.automatableEditItemCache.addItem (*this);
 }
 
 AutomatableEditItem::~AutomatableEditItem()
 {
+    edit.automatableEditItemCache.removeItem (*this);
 }
 
 //==============================================================================
@@ -106,7 +108,6 @@ AutomatableParameterTree& AutomatableEditItem::getParameterTree() const
         sendListChangeMessage();
     }
 
-
     return parameterTree;
 }
 
@@ -128,6 +129,11 @@ juce::ReferenceCountedArray<AutomatableParameter> AutomatableEditItem::getFlatte
 }
 
 //==============================================================================
+bool AutomatableEditItem::isAutomationNeeded() const noexcept
+{
+    return numActiveParameters.load (std::memory_order_acquire) > 0;
+}
+
 void AutomatableEditItem::setAutomatableParamPosition (TimePosition time)
 {
     if (setIfDifferent (lastTime, time))
@@ -142,6 +148,9 @@ bool AutomatableEditItem::isBeingActivelyPlayed() const
 
 void AutomatableEditItem::updateAutomatableParamPosition (TimePosition time)
 {
+    if (! isAutomationNeeded())
+        return;
+
     for (auto p : automatableParams)
         if (p->isAutomationActive())
             p->updateToFollowCurve (time);
@@ -161,6 +170,79 @@ void AutomatableEditItem::resetRecordingStatus()
         p->resetRecordingStatus();
 }
 
+void AutomatableEditItem::updateStreamIterators()
+{
+    for (auto p : automatableParams)
+        p->updateStream();
+}
+
+void AutomatableEditItem::addActiveParameter (const AutomatableParameter& p)
+{
+    if (auto param = automatableParams[automatableParams.indexOf (&p)])
+    {
+        // This confusing order is to avoid allocating whilst the lock is held
+        juce::ReferenceCountedArray<AutomatableParameter> newParams;
+        int numParams = 0;
+
+         {
+            const std::scoped_lock sl (activeParameterLock);
+
+            if (activeParameters.contains (param))
+                return;
+
+            numParams = activeParameters.size() + 1;
+        }
+
+        newParams.ensureStorageAllocated (numParams);
+
+        {
+            const std::scoped_lock sl (activeParameterLock);
+            newParams = activeParameters;
+        }
+
+        newParams.add (param);
+
+        const std::scoped_lock sl (activeParameterLock);
+        std::swap (activeParameters, newParams);
+    }
+
+    lastTime = -1.0s;
+}
+
+void AutomatableEditItem::removeActiveParameter (const AutomatableParameter& p)
+{
+    if (auto param = automatableParams[automatableParams.indexOf (&p)])
+    {
+        // This confusing order is to avoid removing whilst the lock is held,
+        // juce::ReferenceCountedArray can free when that happens
+        juce::ReferenceCountedArray<AutomatableParameter> nowActiveParams;
+        int numParams = 0;
+
+        {
+            const std::scoped_lock sl (activeParameterLock);
+
+            if (! activeParameters.contains (param))
+                return;
+
+            numParams = activeParameters.size() - 1;
+        }
+
+        nowActiveParams.ensureStorageAllocated (numParams);
+
+        {
+            const std::scoped_lock sl (activeParameterLock);
+            nowActiveParams = activeParameters;
+        }
+
+        nowActiveParams.removeObject (param);
+
+        const std::scoped_lock sl (activeParameterLock);
+        std::swap (activeParameters, nowActiveParams);
+    }
+
+    lastTime = -1.0s;
+}
+
 //==============================================================================
 void AutomatableEditItem::buildParameterTree() const
 {
@@ -183,6 +265,10 @@ void AutomatableEditItem::addAutomatableParameter (const AutomatableParameter::P
 {
     jassert (param != nullptr);
     automatableParams.add (param);
+
+    if (param->isAutomationActive())
+        addActiveParameter (*param);
+
     rebuildParameterTree();
 }
 
@@ -207,22 +293,10 @@ juce::ReferenceCountedArray<AutomatableParameter> AutomatableEditItem::getFlatte
     return params;
 }
 
-void AutomatableEditItem::updateActiveParameters()
+bool AutomatableEditItem::isActiveParameter (AutomatableParameter& p)
 {
-    CRASH_TRACER
-    juce::ReferenceCountedArray<AutomatableParameter> nowActiveParams;
-
-    for (auto ap : automatableParams)
-        if (ap->isAutomationActive())
-            nowActiveParams.add (ap);
-
-    {
-        const std::scoped_lock sl (activeParameterLock);
-        activeParameters.swapWith (nowActiveParams);
-        automationActive.store (! activeParameters.isEmpty(), std::memory_order_relaxed);
-    }
-
-    lastTime = -1.0s;
+    const std::scoped_lock sl (activeParameterLock);
+    return activeParameters.contains (p);
 }
 
 void AutomatableEditItem::saveChangedParametersToState()

modules/tracktion_engine/model/automation/tracktion_AutomatableEditItem.cpp

@@ -50,32 +50,42 @@ class AutomatableEditItem  : public EditItem
 
     //==============================================================================
     // true if it's got any points on any params
-    bool isAutomationNeeded() const noexcept                    { return automationActive.load (std::memory_order_relaxed); }
+    bool isAutomationNeeded() const noexcept;
 
     // updates any automatables to their state at this time
     void setAutomatableParamPosition (TimePosition);
 
     // true if it's not been more than a few hundred ms since a block was processed
     bool isBeingActivelyPlayed() const;
 
-    /** Updates all the auto params to their positions at this time. */
+    /** Updates all the auto params to their positions at this time.
+        [[ message_thread ]]
+    */
     virtual void updateAutomatableParamPosition (TimePosition);
 
     /** Updates all the parameter streams to their positions at this time.
-        This should be used during real time processing as it's a lot quicker than the above method.
+        This should be used during real time processing as it's a lot quicker than
+        the above method but is called automatically by the audio graph so
+        shouldn't really be called manually.
     */
     void updateParameterStreams (TimePosition);
 
-    /** Iterates all the parameters to find out which ones need to be automated. */
-    void updateActiveParameters();
-
     /** Marks the end of an automation recording stream. Call this when play stops or starts. */
     void resetRecordingStatus();
 
     //==============================================================================
     juce::ValueTree elementState;
     juce::CachedValue<bool> remapOnTempoChange;
 
+    /** @internal. */
+    void updateStreamIterators();
+    /** @internal. */
+    void addActiveParameter (const AutomatableParameter&);
+    /** @internal. */
+    void removeActiveParameter (const AutomatableParameter&);
+    /** @internal. Testing only. */
+    bool isActiveParameter (AutomatableParameter&);
+
 protected:
     virtual void buildParameterTree() const;
 
@@ -96,7 +106,8 @@ class AutomatableEditItem  : public EditItem
     mutable AutomatableParameterTree parameterTree;
 
     mutable bool parameterTreeBuilt = false;
-    std::atomic<bool> automationActive { false };
+    friend struct AutomatableParameter::ScopedActiveParameter;
+    mutable std::atomic<int> numActiveParameters { 0 };
     uint32_t systemTimeOfLastPlayedBlock = 0;
     TimePosition lastTime;