Subpages | |
| Partial Document Persistency | |
| These optional filters allow to only store a subset of the document graph into an archive, or only restore a subset of an archive into the document graph. | |
| Processing Algorithm Selection | |
| Document Controller | |
| ARA model objects are created and managed by the ARA Document Controller provided by the plug-in. The host uses the factory and management functions of the Document Controller to create a partial copy of its model translated into the ARA world. It is created using a factory which can be either retrieved by scanning the plug-in binaries for a dedicated factory or by requesting it from a living companion plug-in instance. The host is responsible for keeping the document controller alive as long as any objects created through it are still living (kind of implicit ref-counting). This means that its live time is independent of the companion plug-in instances - they may all be gone at some point but the ARA graph may still be accessed through its document controller. The host must also keep the document controller alive as long as any companion plug-in instance which it has bound to it is actively used. The actual destruction of the plug-in instance may be done later (to ease reference counting implementation), but rendering the plug-in, accessing its state or showing its UI is only valid as long as the ARA document controller it has been bound is still alive. Except for some rare, explicitly documented functions like getPlaybackRegionHeadAndTailTime(), the document controller interface must always be called from the same thread - usually hosts will manage their internal model as well as the attached ARA graph from the application's main thread, triggered from the main run loop. If a host decides to use a different thread for maintaining the ARA model, it may need to implement some sort of locking so that its updates on the ARA model thread do not interfere concurrently with the main run loop's event processing as it drives the plug-in's UI code and notification system. Plug-in developers using C++ ARA Library can implement the ARA::PlugIn::DocumentControllerInterface, or extend the already implemented ARA::PlugIn::DocumentController class as needed. For host developers this interface is wrapped by the ARA::Host::DocumentController. | |
| Document Controller Instance | |
| The callbacks into the plug-in are published by the plug-in when the host requests the creation of a document controller via the factory. The instance struct and all interfaces and host refs therein must remain valid until the document controller is destroyed. The plug-in can choose to create its controller objects per document controller instance, or it can share a single instance between all document controllers, whatever fits its needs. It may even mix-and-match both approaches per individual interface. | |
| Plug-In Factory | |
| Static entry into ARA, allows to create ARA objects. | |
| Plug-In Extension | |
| The plug-in extension provides ARA-specific additional functionality per companion plug-in instance. On a conceptual level, the plug-in extension is not an object of its own, but merely a set of additional interfaces of the companion plug-in instance, augmenting it with a few ARA-specific features in a fashion that is independent from the actual companion API in use. Accordingly, it is coupled 1:1 to the companion plug-in instance and its lifetime matches the lifetime of the companion plug-in instance (no separate destruction function needed). Along the same lines, plug-in extensions themselves are not persistent. The plug-in extension is exposed towards the host when it binds a plug-in instance as created by the companion APIs to a specific ARA model graph, represented by its associated document controller. This setup call is executed via a vendor-specific extension of the companion API and may only be made once. It shifts the "normal" companion plug-in into the ARA world, and once established, this coupling cannot be undone, it remains active until the plug-in instance is destroyed. Note that both performing the explicit binding and the implicit unbinding upon destruction will likely need to access plug-in internal data structures shared with with the document controller implementation. To avoid adding costly thread safety measures when maintaining this shared state, hosts should always perform these operations from the document controller thread (typically the main thread). This restriction may or may not apply when using the same companion API without ARA, so host developers might need to add extra precaution for the ARA case. When ARA is enabled, the renderer behavior has slightly different semantics compared to the non-ARA use case. Since ARA renderers are essentially generators that use non-realtime data to generate realtime signals, they do not use the realtime input signal for processing. Playback renderers will simply ignore their inputs, but editor renderers will always add their output signal to the input signal provided by the host. If a plug-in assumes both rendering roles, playback rendering will already ignore the inputs, so the editor rendering will directly add to the playback output, not to the input. Since ARA 2.0, the host can explicitly establish the roles that the given instance will assume in its specific implementation upon binding the plug-in instance to the ARA document controller. Each role is associated with a dedicated feature set that only is available when the particular role has been established. Depending on the chosen roles, the following calls control which playback regions are to be rendered according to which rule. Separating roles allows for more flexible ARA integrations and optimizes resource usage. A host could for example use a playback renderer plug-in instance playback region, plus one plug-in instance per track for editor rendering and viewing all regions on that track. Amongst other behavior, the roles heavily affect the relationship between plug-in instances and playback regions. For rendering, each plug-in extension can handle multiple playback regions if desired, albeit the semantics for modifying the set of associated regions per renderer are somewhat different between playback and editor renderers, see below. For editor view purposes, the relationship is not explicit to accommodate for a very broad range of user interface concepts that need to interact with the API. Generally, each editor view is associated with all playback regions in the document controller to which the plug-in is bound. However, typically only a varying subset of those regions will be shown at any point in time, depending on the intrinsic feature set of the plug-in, and reflecting the selection that the user has performed in the host - see notifySelection(). | |