Add ARAModelUpdateControllerInterface::notifyDocumentDataChanged() and related code

Author: sgretscher

ChangeLog.txt

@@ -9,6 +9,7 @@ Changes since previous releases:
   a channel count too and copies the channel arrangement data instead of referencing it
   As a result, DocumentController::doUpdateChannelArrangement() has been removed since
   the arrangement is now always available, just like sample rate etc.
+- added API to notify the host when the private, opaque document state changes (to trigger saving it)
 - added ARA_VALIDATE_API_THREAD to enable conveniently raising kARAAssertInvalidThread
 - added optional document controller thread validation to ARAPlug
 - required minimum CMake version increased from 3.4 to 3.19 (same as VST3)

Dispatch/ARAHostDispatch.cpp

@@ -213,14 +213,20 @@ namespace ModelUpdateControllerDispatcher
         fromHostRef (controllerHostRef)->notifyPlaybackRegionContentChanged (playbackRegionHostRef, range, flags);
     }
 
+    static void ARA_CALL notifyDocumentDataChanged (ARAModelUpdateControllerHostRef controllerHostRef) noexcept
+    {
+        fromHostRef (controllerHostRef)->notifyDocumentDataChanged ();
+    }
+
     static const ARAModelUpdateControllerInterface* getInterface () noexcept
     {
-        static const SizedStruct<ARA_STRUCT_MEMBER (ARAModelUpdateControllerInterface, notifyPlaybackRegionContentChanged)> ifc =
+        static const SizedStruct<ARA_STRUCT_MEMBER (ARAModelUpdateControllerInterface, notifyDocumentDataChanged)> ifc =
         {
             ModelUpdateControllerDispatcher::notifyAudioSourceAnalysisProgress,
             ModelUpdateControllerDispatcher::notifyAudioSourceContentChanged,
             ModelUpdateControllerDispatcher::notifyAudioModificationContentChanged,
-            ModelUpdateControllerDispatcher::notifyPlaybackRegionContentChanged
+            ModelUpdateControllerDispatcher::notifyPlaybackRegionContentChanged,
+            ModelUpdateControllerDispatcher::notifyDocumentDataChanged
         };
         return &ifc;
     }

Dispatch/ARAHostDispatch.h

@@ -183,6 +183,8 @@ class ModelUpdateControllerInterface
     virtual void notifyAudioModificationContentChanged (ARAAudioModificationHostRef audioModificationHostRef, const ARAContentTimeRange* range, ContentUpdateScopes scopeFlags) noexcept = 0;
     //! \copydoc ARAModelUpdateControllerInterface::notifyPlaybackRegionContentChanged
     virtual void notifyPlaybackRegionContentChanged (ARAPlaybackRegionHostRef playbackRegionHostRef, const ARAContentTimeRange* range, ContentUpdateScopes scopeFlags) noexcept = 0;
+    //! \copydoc ARAModelUpdateControllerInterface::notifyDocumentDataChanged
+    virtual void notifyDocumentDataChanged () noexcept = 0;
 };
 ARA_MAP_HOST_REF (ModelUpdateControllerInterface, ARAModelUpdateControllerHostRef)
 

Dispatch/ARAPlugInDispatch.cpp

@@ -717,6 +717,13 @@ void HostModelUpdateController::notifyPlaybackRegionContentChanged (ARAPlaybackR
         getInterface ()->notifyPlaybackRegionContentChanged (getRef (), playbackRegionHostRef, range, scopeFlags);
 }
 
+void HostModelUpdateController::notifyDocumentDataChanged () noexcept
+{
+    // notifyDocumentDataChanged was added in ARA 2.3 draft, so check its presence here
+    if (getInterface ().implements<ARA_STRUCT_MEMBER (ARAModelUpdateControllerInterface, notifyDocumentDataChanged)> ())
+        getInterface ()->notifyDocumentDataChanged (getRef ());
+}
+
 /*******************************************************************************/
 // PlaybackController
 /*******************************************************************************/

Dispatch/ARAPlugInDispatch.h

@@ -464,6 +464,8 @@ class HostModelUpdateController : public InterfaceInstance<ARAModelUpdateControl
     //! \copydoc ARAModelUpdateControllerInterface::notifyPlaybackRegionContentChanged
     void notifyPlaybackRegionContentChanged (ARAPlaybackRegionHostRef playbackRegionHostRef,
                                              const ARAContentTimeRange* range, ContentUpdateScopes scopeFlags) noexcept;
+    //! \copydoc ARAModelUpdateControllerInterface::notifyDocumentDataChanged
+    void notifyDocumentDataChanged () noexcept;
 };
 
 /*******************************************************************************/

IPC/ARAIPCProxyHost.cpp

@@ -463,6 +463,7 @@ class ModelUpdateController : public Host::ModelUpdateControllerInterface, prote
     void notifyAudioSourceContentChanged (ARAAudioSourceHostRef audioSourceHostRef, const ARAContentTimeRange* range, ContentUpdateScopes scopeFlags) noexcept override;
     void notifyAudioModificationContentChanged (ARAAudioModificationHostRef audioModificationHostRef, const ARAContentTimeRange* range, ContentUpdateScopes scopeFlags) noexcept override;
     void notifyPlaybackRegionContentChanged (ARAPlaybackRegionHostRef playbackRegionHostRef, const ARAContentTimeRange* range, ContentUpdateScopes scopeFlags) noexcept override;
+    void notifyDocumentDataChanged () noexcept override;
 
 private:
     ARAModelUpdateControllerHostRef _remoteHostRef;
@@ -494,6 +495,12 @@ void ModelUpdateController::notifyPlaybackRegionContentChanged (ARAPlaybackRegio
                 _remoteHostRef, playbackRegionHostRef, range, scopeFlags);
 }
 
+void ModelUpdateController::notifyDocumentDataChanged () noexcept
+{
+    remoteCall (ARA_IPC_HOST_METHOD_ID (ARAModelUpdateControllerInterface, notifyDocumentDataChanged),
+                _remoteHostRef);
+}
+
 
 /*******************************************************************************/
 //! Implementation of PlaybackControllerInterface that channels all calls through IPC

IPC/ARAIPCProxyPlugIn.cpp

@@ -1709,6 +1709,16 @@ void ProxyPlugIn::handleReceivedMessage (const MessageID messageID, const Messag
 
         documentController->getHostModelUpdateController ()->notifyPlaybackRegionContentChanged (playbackRegionHostRef, (range.second) ? &range.first : nullptr, scopeFlags);
     }
+    else if (messageID == ARA_IPC_HOST_METHOD_ID (ARAModelUpdateControllerInterface, notifyDocumentDataChanged))
+    {
+        ARAModelUpdateControllerHostRef controllerHostRef;
+        decodeArguments (decoder, controllerHostRef);
+
+        auto documentController { fromHostRef (controllerHostRef) };
+        ARA_VALIDATE_API_ARGUMENT (controllerHostRef, isValidInstance (documentController));
+
+        documentController->getHostModelUpdateController ()->notifyDocumentDataChanged ();
+    }
 
     // ARAPlaybackControllerInterface
     else if (messageID == ARA_IPC_HOST_METHOD_ID (ARAPlaybackControllerInterface, requestStartPlayback))

PlugIn/ARAPlug.cpp

@@ -1117,6 +1117,10 @@ void DocumentController::notifyModelUpdates () noexcept
         hostModelUpdateController->notifyPlaybackRegionContentChanged (playbackRegionUpdate.first->getHostRef (), nullptr, playbackRegionUpdate.second);
     _playbackRegionContentUpdates.clear ();
 
+    if (_documentDataChanged)
+        hostModelUpdateController->notifyDocumentDataChanged ();
+    _documentDataChanged = false;
+        
     didNotifyModelUpdates ();
 }
 
@@ -2312,6 +2316,11 @@ void DocumentController::notifyPlaybackRegionContentChanged (PlaybackRegion* pla
         _playbackRegionContentUpdates[playbackRegion] += scopeFlags;
 }
 
+void DocumentController::notifyDocumentDataChanged () noexcept
+{
+    _documentDataChanged = true;
+}
+
 /*******************************************************************************/
 
 HostAudioReader::HostAudioReader (const AudioSource* audioSource, bool use64BitSamples) noexcept

PlugIn/ARAPlug.h

@@ -1274,6 +1274,7 @@ class DocumentController : public DocumentControllerInterface,
     void notifyAudioSourceContentChanged (AudioSource* audioSource, ContentUpdateScopes scopeFlags) noexcept;
     void notifyAudioModificationContentChanged (AudioModification* audioModification, ContentUpdateScopes scopeFlags) noexcept;
     void notifyPlaybackRegionContentChanged (PlaybackRegion* playbackRegion, ContentUpdateScopes scopeFlags) noexcept;
+    void notifyDocumentDataChanged () noexcept;
 //@}
 
     // Helper for analysis requests.
@@ -1348,6 +1349,7 @@ class DocumentController : public DocumentControllerInterface,
     std::map<AudioSource*, ContentUpdateScopes> _audioSourceContentUpdates;
     std::map<AudioModification*, ContentUpdateScopes> _audioModificationContentUpdates;
     std::map<PlaybackRegion*, ContentUpdateScopes> _playbackRegionContentUpdates;
+    bool _documentDataChanged { false };
     std::atomic_flag _analysisProgressIsSynced {}; // { true } would be better but C++ standard only allows for default-init to false
 
     bool _isHostEditingDocument { false };