Plug-In Entry

Detailed Description

Classes that implement the entry into the ARA plug-in.

Classes

class  ARA::PlugIn::FactoryConfig
 Customization interface for defining ARAFactory instances in the PlugInEntry. More...
 
class  ARA::PlugIn::PlugInEntry
 Singleton class to define the entry into ARA. For each document controller class in your plug-in, create a single static instance of this class by using the static member template getPlugInEntry () which takes your custom FactoryConfig and DocumentController subclasses as template arguments. More...
 

Class Documentation

◆ ARA::PlugIn::FactoryConfig

class ARA::PlugIn::FactoryConfig

Customization interface for defining ARAFactory instances in the PlugInEntry.

Public Member Functions

virtual ARAAPIGeneration getLowestSupportedApiGeneration () const noexcept
 Lower bound of supported ARAAPIGeneration. More...
 
virtual ARAAPIGeneration getHighestSupportedApiGeneration () const noexcept
 Upper bound of supported ARAAPIGeneration. More...
 
virtual const char * getFactoryID () const noexcept=0
 Unique and versioned plug-in identifier. This ID must be globally unique and identifies the plug-in's document controller class created by this factory at runtime. The ID includes versioning, it must be updated if e.g. the plug-in's (compatible) document archive ID(s) or its analysis or playback transformation capabilities change. Host applications can therefore use it to trigger cache updates if they implement a plug-in caching mechanism to avoid scanning all plug-ins each time the program is launched. If a given plug-in supports multiple companion APIs, it will return the same ID across all companion APIs, allowing the host to choose which API to use for this particular plug-in. See Managing ARA Archives for more information. More...
 
virtual const char * getPlugInName () const noexcept=0
 Name of the plug-in to display to the user. More...
 
virtual const char * getManufacturerName () const noexcept=0
 Name of the manufacturer of the plug-in to display to the user. More...
 
virtual const char * getInformationURL () const noexcept=0
 Web page to refer the user to if they need further information about the plug-in. More...
 
virtual const char * getVersion () const noexcept=0
 Version string of the plug-in to display to the user. More...
 
virtual const char * getDocumentArchiveID () const noexcept=0
 Identifier for document archives created by the document controller. This ID must be globally unique and is shared only amongst document controllers that create the same archives and produce the same render results based upon the same input data. This means that the ID must be updated if the archive format changes in any way that is no longer downwards compatible. See Managing ARA Archives for more information. More...
 
virtual ARASize getCompatibleDocumentArchiveIDsCount () const noexcept
 Length of compatibleDocumentArchiveIDs. More...
 
virtual const ARAPersistentID * getCompatibleDocumentArchiveIDs () const noexcept
 Variable-sized C array listing other identifiers of archives that the document controller can import. This list is used for example when updating the data structures inside the controller. It is ordered descending, expressing a preference which state to load in case a document contains more than one compatible archive of older versions. The list may be empty, in which case count should be 0 and the pointer NULL. More...
 
virtual ARASize getAnalyzeableContentTypesCount () const noexcept
 Length of analyzeableContentTypes. More...
 
virtual const ARAContentType * getAnalyzeableContentTypes () const noexcept
 Variable-sized C array listing the content types for which the plug-in can perform an analysis. This list allows the host to determine whether the plug-in can be used as analysis engine in the background (i.e. without presenting the UI to the user) to achieve certain host features. Note that the plug-in may support more content types than listed here for some or all objects in the graph, but may rely on user interaction when dealing with those content types. The list may be empty, in which case count should be 0 and the pointer NULL. More...
 
virtual ARAPlaybackTransformationFlags getSupportedPlaybackTransformationFlags () const noexcept
 Set of transformations that the plug-in supports when configuring playback regions. These flags allow the host to determine whether e.g. the plug-in can be used as time-stretch engine. More...
 
virtual bool supportsStoringAudioFileChunks () const noexcept
 Flag whether the plug-in supports exporting ARA audio file chunks via ARADocumentControllerInterface::storeAudioSourceToAudioFileChunk(). Note that reading such chunks is unaffected by this flag - as long as the documentArchiveID in the chunk is compatible, the plug-in must be able to read the data via ARADocumentControllerInterface::restoreObjectsFromArchive(). More...
 

Member Function Documentation

◆ getAnalyzeableContentTypes()

virtual const ARAContentType* ARA::PlugIn::FactoryConfig::getAnalyzeableContentTypes ( ) const
virtualnoexcept

Variable-sized C array listing the content types for which the plug-in can perform an analysis. This list allows the host to determine whether the plug-in can be used as analysis engine in the background (i.e. without presenting the UI to the user) to achieve certain host features. Note that the plug-in may support more content types than listed here for some or all objects in the graph, but may rely on user interaction when dealing with those content types. The list may be empty, in which case count should be 0 and the pointer NULL.

◆ getAnalyzeableContentTypesCount()

virtual ARASize ARA::PlugIn::FactoryConfig::getAnalyzeableContentTypesCount ( ) const
virtualnoexcept

Length of analyzeableContentTypes.

◆ getCompatibleDocumentArchiveIDs()

virtual const ARAPersistentID* ARA::PlugIn::FactoryConfig::getCompatibleDocumentArchiveIDs ( ) const
virtualnoexcept

Variable-sized C array listing other identifiers of archives that the document controller can import. This list is used for example when updating the data structures inside the controller. It is ordered descending, expressing a preference which state to load in case a document contains more than one compatible archive of older versions. The list may be empty, in which case count should be 0 and the pointer NULL.

◆ getCompatibleDocumentArchiveIDsCount()

virtual ARASize ARA::PlugIn::FactoryConfig::getCompatibleDocumentArchiveIDsCount ( ) const
virtualnoexcept

Length of compatibleDocumentArchiveIDs.

◆ getDocumentArchiveID()

virtual const char* ARA::PlugIn::FactoryConfig::getDocumentArchiveID ( ) const
pure virtualnoexcept

Identifier for document archives created by the document controller. This ID must be globally unique and is shared only amongst document controllers that create the same archives and produce the same render results based upon the same input data. This means that the ID must be updated if the archive format changes in any way that is no longer downwards compatible. See Managing ARA Archives for more information.

◆ getFactoryID()

virtual const char* ARA::PlugIn::FactoryConfig::getFactoryID ( ) const
pure virtualnoexcept

Unique and versioned plug-in identifier. This ID must be globally unique and identifies the plug-in's document controller class created by this factory at runtime. The ID includes versioning, it must be updated if e.g. the plug-in's (compatible) document archive ID(s) or its analysis or playback transformation capabilities change. Host applications can therefore use it to trigger cache updates if they implement a plug-in caching mechanism to avoid scanning all plug-ins each time the program is launched. If a given plug-in supports multiple companion APIs, it will return the same ID across all companion APIs, allowing the host to choose which API to use for this particular plug-in. See Managing ARA Archives for more information.

◆ getHighestSupportedApiGeneration()

virtual ARAAPIGeneration ARA::PlugIn::FactoryConfig::getHighestSupportedApiGeneration ( ) const
virtualnoexcept

Upper bound of supported ARAAPIGeneration.

◆ getInformationURL()

virtual const char* ARA::PlugIn::FactoryConfig::getInformationURL ( ) const
pure virtualnoexcept

Web page to refer the user to if they need further information about the plug-in.

◆ getLowestSupportedApiGeneration()

virtual ARAAPIGeneration ARA::PlugIn::FactoryConfig::getLowestSupportedApiGeneration ( ) const
virtualnoexcept

Lower bound of supported ARAAPIGeneration.

◆ getManufacturerName()

virtual const char* ARA::PlugIn::FactoryConfig::getManufacturerName ( ) const
pure virtualnoexcept

Name of the manufacturer of the plug-in to display to the user.

◆ getPlugInName()

virtual const char* ARA::PlugIn::FactoryConfig::getPlugInName ( ) const
pure virtualnoexcept

Name of the plug-in to display to the user.

◆ getSupportedPlaybackTransformationFlags()

virtual ARAPlaybackTransformationFlags ARA::PlugIn::FactoryConfig::getSupportedPlaybackTransformationFlags ( ) const
virtualnoexcept

Set of transformations that the plug-in supports when configuring playback regions. These flags allow the host to determine whether e.g. the plug-in can be used as time-stretch engine.

◆ getVersion()

virtual const char* ARA::PlugIn::FactoryConfig::getVersion ( ) const
pure virtualnoexcept

Version string of the plug-in to display to the user.

◆ supportsStoringAudioFileChunks()

virtual bool ARA::PlugIn::FactoryConfig::supportsStoringAudioFileChunks ( ) const
virtualnoexcept

Flag whether the plug-in supports exporting ARA audio file chunks via ARADocumentControllerInterface::storeAudioSourceToAudioFileChunk(). Note that reading such chunks is unaffected by this flag - as long as the documentArchiveID in the chunk is compatible, the plug-in must be able to read the data via ARADocumentControllerInterface::restoreObjectsFromArchive().

◆ ARA::PlugIn::PlugInEntry

class ARA::PlugIn::PlugInEntry

Singleton class to define the entry into ARA. For each document controller class in your plug-in, create a single static instance of this class by using the static member template getPlugInEntry () which takes your custom FactoryConfig and DocumentController subclasses as template arguments.

Getters for Document Controller and Companion API implementations

const ARAFactory * getFactory () const noexcept
 
ARAAPIGeneration getUsedApiGeneration () const noexcept
 

PlugInEntry creation

template<typename FactoryConfigClass , typename DocumentControllerClass = void>
static PlugInEntry * getPlugInEntry () noexcept
 This static template function should be used to create a single static PlugInEntry per DocumentController class. The DocumentControllerClass parameter is optional - if omitted, the FactoryConfigClass must overload createDocumentController () and can optionally overload destroyDocumentController (), otherwise the template takes care of this using new and delete. More...
 

Member Function Documentation

◆ getPlugInEntry()

template<typename FactoryConfigClass , typename DocumentControllerClass = void>
static PlugInEntry* ARA::PlugIn::PlugInEntry::getPlugInEntry ( )
staticnoexcept

This static template function should be used to create a single static PlugInEntry per DocumentController class. The DocumentControllerClass parameter is optional - if omitted, the FactoryConfigClass must overload createDocumentController () and can optionally overload destroyDocumentController (), otherwise the template takes care of this using new and delete.

class MyFactoryConfig : public FactoryConfig
{
// ... implement customization overrides ...
};
class MyDocumentController : public DocumentController
{
using DocumentController::DocumentController; // publish inherited constructor
// ... implement customization overrides ...
};
static const ARAFactory* getMyARAFactory () noexcept
{
return PlugInEntry::getPlugInEntry<MyFactoryConfig, MyDocumentController> ()->getFactory ();
}
Static plug-in factory. All pointers herein must remain valid as long as the binary is loaded....
Definition: ARAInterface.h:3180