Plug-In Factory

Detailed Description

Static entry into ARA, allows to create ARA objects.

Classes

struct  ARAInterfaceConfiguration
 API configuration. This configuration struct allows for setting the desired API version, the debug callback etc. Note that a pointer to this struct is only valid for the duration of the call to initializeARAWithConfiguration() - the data must be fully evaluated/copied inside the call. More...
 
struct  ARAFactory
 Static plug-in factory. All pointers herein must remain valid as long as the binary is loaded. The declaration of this struct will not change when updating to a new generation of the API, only additions are possible. More...
 

Class Documentation

◆ ARAInterfaceConfiguration

struct ARAInterfaceConfiguration

API configuration. This configuration struct allows for setting the desired API version, the debug callback etc. Note that a pointer to this struct is only valid for the duration of the call to initializeARAWithConfiguration() - the data must be fully evaluated/copied inside the call.

Public Attributes

ARASize structSize
 Size-based struct versioning - see Versioned structs.
 
ARAAPIGeneration desiredApiGeneration
 Defines the API generation to use, must be within the range of supported generations.
 
ARAAssertFunction * assertFunctionAddress
 Pointer to the global assert function address. Be aware that this is a pointer to a function pointer, not the function pointer itself! This indirection is necessary so that plug-ins can inject their debug code if needed. The pointer must be the same for all instances that use the same API generation. It must be always provided by the host, but can point to NULL to suppress debugging in release versions. It must remain valid until uninitializeARA() is called.
 

◆ ARAFactory

struct ARAFactory

Static plug-in factory. All pointers herein must remain valid as long as the binary is loaded. The declaration of this struct will not change when updating to a new generation of the API, only additions are possible.

Size-based struct versioning

See Versioned structs.

ARASize structSize
 

Factory and Global Initialization

The following data members and functions are involved when loading/unloading the plug-in binary.
All function calls in this header may only be made between a single call to initializeARAWithConfiguration() and another single call to uninitializeARA(). Typically, initialization/uninitialization is done right after loading/right before unloading the binary, but it is valid to call them multiple times without loading/unloading the binary in-between, provided the described order of calls is respected.

ARAAPIGeneration lowestSupportedApiGeneration
 Lower bound of supported ARAAPIGeneration.
 
ARAAPIGeneration highestSupportedApiGeneration
 Upper bound of supported ARAAPIGeneration.
 
ARAPersistentID factoryID
 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.
 
void(* initializeARAWithConfiguration )(const ARAInterfaceConfiguration *config)
 Start up ARA with the given configuration.
 
void(* uninitializeARA )(void)
 Shut down ARA.
 

User-Presentable Meta Information

This information is only intended for display purposes and should never be used for flow control. In addition to all other potential uses, this information should always be stored alongside any document archive that the host creates in order to be able to provide a proper error message if the archive is being restored on a different system where the plug-in is not installed (or only an older version of it). See Managing ARA Archives for more information.

ARAUtf8String plugInName
 Name of the plug-in to display to the user.
 
ARAUtf8String manufacturerName
 Name of the manufacturer of the plug-in to display to the user.
 
ARAUtf8String informationURL
 Web page to refer the user to if they need further information about the plug-in.
 
ARAUtf8String version
 Version string of the plug-in to display to the user.
 

Document Controller and Document Archives

This section of the struct deals with creating document controllers and handling versioned document archiving based on archive IDs. Note that in addition to the actual document archive and its ID, the host should save the above meta information about the plug-in alongside so it can do proper error handling, see above.

const ARADocumentControllerInstance *(* createDocumentControllerWithDocument )(const ARADocumentControllerHostInstance *hostInstance, const ARADocumentProperties *properties)
 Factory function for the document controller. This call is used both when creating a new document from scratch and when restoring a document from an archive.
 
ARAPersistentID documentArchiveID
 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.
 
ARASize compatibleDocumentArchiveIDsCount
 Length of compatibleDocumentArchiveIDs.
 
const ARAPersistentID * compatibleDocumentArchiveIDs
 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.
 

Capabilities

If the host wants to utilize the plug-in as an internal engine for analysis or time-stretching, it can use this information to determine if the plug-in is actually capable of handling its needs. Further, the host may want to restrict the user from doing operations that make no sense for the given plug-in, such as trying to time-stretch with a plug-in that cannot perform this task. Note that even if a plug-in cannot analyze a given content type, it still may provide a UI where the user can edit that content type, so it may support content reading for types missing here.

ARASize analyzeableContentTypesCount
 Length of analyzeableContentTypes.
 
const ARAContentType * analyzeableContentTypes
 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.
 
ARAPlaybackTransformationFlags supportedPlaybackTransformationFlags
 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.
 
ARABool supportsStoringAudioFileChunks
 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().