diff --git a/BREAKING_CHANGES.md b/BREAKING_CHANGES.md index 9680019c62..9152e5ae39 100644 --- a/BREAKING_CHANGES.md +++ b/BREAKING_CHANGES.md @@ -2,6 +2,30 @@ # develop +## Change + +A new type member ARAConfigurationType has been added to +ARADemoPluginDocumentControllerSpecialisation. + +**Possible Issues** + +In the unlikely case than an ARA document controller implementation previously +added an ARAConfigurationType member to +ARADemoPluginDocumentControllerSpecialisation, the code will fail to compile. + +**Workaround** + +The previous ARAConfigurationType member must be renamed. +ARADemoPluginDocumentControllerSpecialisation::ARAConfigurationType from now on +must be a type that has a static member function +`ARA::ARAAPIGeneration getHighestSupportedApiGeneration()`. + +**Rationale** + +Supporting the partial persistency feature of ARA 2.3.0 required the addition +of the new type member. + + ## Change The ARA SDK required by JUCE has been updated to version 2.3.0. diff --git a/modules/juce_audio_processors_headless/utilities/ARA/juce_ARADocumentController.h b/modules/juce_audio_processors_headless/utilities/ARA/juce_ARADocumentController.h index 9b363410e2..e78111536a 100644 --- a/modules/juce_audio_processors_headless/utilities/ARA/juce_ARADocumentController.h +++ b/modules/juce_audio_processors_headless/utilities/ARA/juce_ARADocumentController.h @@ -43,6 +43,39 @@ class ARAEditorView; class ARAInputStream; class ARAOutputStream; +/** This class provides customisable configuration options that are available at the ARAFactory + construction's time. + + This is used as the ARAConfigurationType type member inside ARADocumentControllerSpecialisation. + + If you wish to override the default configuration values, shadow + ARADocumentControllerSpecialisation::ARAConfigurationType with a custom type of your own that + has the same member function signatures as this struct. + + @see ARADocumentControllerSpecialisation::ARAConfigurationType +*/ +struct ARADocumentControllerConfiguration +{ + /** In order to report kARAAPIGeneration_2_3_Final or higher, the plugin must notify the host + via the ARA::PlugIn::HostModelUpdateController::notifyDocumentDataChanged() function + whenever any private, opaque document state is changed, that must be persisted. Likewise, + notifyAudioSourceContentChanged() and notifyAudioModificationContentChanged() must be + called whenever the persistent state of the respective objects changes. + + Otherwise data loss may occur. Reporting this version signals to the host that the plugin + conforms to the ARA 2.3 partial persistence features. + + e.g. + @code + getDocumentController()->getHostModelUpdateController()->notifyDocumentDataChanged(); + @endcode + */ + static constexpr ARA::ARAAPIGeneration getHighestSupportedApiGeneration() noexcept + { + return ARA::kARAAPIGeneration_2_0_Final; + } +}; + /** This class contains the customisation points for the JUCE provided ARA document controller implementation. @@ -100,6 +133,13 @@ class ARADocumentControllerSpecialisation : public ARADocument::Listener, public ARAPlaybackRegion::Listener { public: + /** Used for configuration options that are available during the ARAFactory's construction. + + You can shadow this type member with a custom type that has the same member function + signatures. + */ + using ARAConfigurationType = ARADocumentControllerConfiguration; + //============================================================================== /** Constructor. Used internally by the ARAFactory implementation. */ @@ -134,6 +174,9 @@ public: { static_assert (std::is_base_of_v, "DocumentController specialization types must inherit from ARADocumentControllerSpecialisation"); + static_assert (std::is_same_v, + "The ARAConfigurationType type member must have a static member function " + "`ARAAPIGeneration getHighestSupportedApiGeneration()`."); return ARA::PlugIn::PlugInEntry::getPlugInEntry>()->getFactory(); } @@ -382,6 +425,8 @@ private: class FactoryConfig : public ARA::PlugIn::FactoryConfig { public: + using ARAConfigurationType = typename SpecialisationType::ARAConfigurationType; + FactoryConfig() noexcept { const juce::String compatibleDocumentArchiveIDString = JucePlugin_ARACompatibleArchiveIDs; @@ -430,6 +475,11 @@ private: JUCE_END_IGNORE_WARNINGS_MSVC } + ARA::ARAAPIGeneration getHighestSupportedApiGeneration() const noexcept override + { + return ARAConfigurationType::getHighestSupportedApiGeneration(); + } + const char* getFactoryID() const noexcept override { return JucePlugin_ARAFactoryID; } const char* getPlugInName() const noexcept override { return JucePlugin_Name; } const char* getManufacturerName() const noexcept override { return JucePlugin_Manufacturer; }