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().
Subpages | |
| Playback Renderer Interface (Added In ARA 2.0) | |
| See kARAPlaybackRendererRole. Plug-in developers using C++ ARA Library can implement the ARA::PlugIn::PlaybackRendererInterface, or extend the already implemented ARA::PlugIn::PlaybackRenderer class as needed. For host developers this interface is wrapped by the ARA::Host::PlaybackRenderer. | |
| Editor Renderer Interface (Added In ARA 2.0) | |
| See kARAEditorRendererRole. Plug-in developers using C++ ARA Library can implement the ARA::PlugIn::EditorRendererInterface, or extend the already implemented ARA::PlugIn::EditorRenderer class as needed. For host developers this interface is wrapped by the ARA::Host::EditorRenderer. | |
| Editor View Interface (Added In ARA 2.0) | |
| See kARAEditorViewRole. Users will often reconfigure the plug-in view through scrolling, zooming, navigating lists of entities, etc. to select the subset of ARA entities that they currently need to view or edit. Those selection features can be implemented in the plug-in (which was the only available solution in ARA 1). However, the host applications already have established user workflows for selecting their representations of the ARA objects. Making those workflows available to the plug-ins is leads to a much more consistent, streamlined user experience. Since the views are implemented through the companion API, there is no matching ARA entity yet. Instead, the companion plug-in instance is used as a controller for its associated view. (Note that while some companion APIs allow for multiple views of a given plug-in used at the same time, this is not recommended when using ARA editor views.) These calls only affect views, not the audio rendering. They only should be made while the plug-in is showing its UI, or before entering this state (i.e. during GUI setup phase), in order to optimize resource usage. Accordingly, the host should send an update of the selection when (re-)opening an ARA plug-in view. These calls also may be made while changes are being made to the model graph (i.e. inside of pairs of ARADocumentControllerInterface::beginEditing() and ARADocumentControllerInterface::endEditing()). Plug-in developers using C++ ARA Library can implement the ARA::PlugIn::EditorViewInterface, or extend the already implemented ARA::PlugIn::EditorView class as needed. For host developers this interface is wrapped by the ARA::Host::EditorView. | |
| Deprecated: Plug-In Extension Interface. | |
| This interface was used before ARA 2.0 defined dedicated plug-in roles. It is only to be implemented when ARA 1 backwards compatibility is desired. An ARA 1 call to set/removePlaybackRegion() in this interface is equivalent to calling both set/removePlaybackRegion() in ARAPlaybackRendererInterface and add/removePlaybackRegion() in ARAEditorRendererInterface. To some extend ARA 1 also uses this to for tasks now associated with ARAEditorViewInterface: opening the UI of an ARA 1 plug-in instance is interpreted as selection of the playback region set via this interface. | |
Classes | |
| struct | ARAPlugInExtensionInstance |
| The plug-in extension instance struct and all interfaces and refs therein must remain valid until the companion plug-in is destroyed by the host. Note that the companion plug-in destruction may happen before or after destroying the document controller it has been bound to, plug-ins must handle both possible destruction orders. Plug-ins must provide all interfaces that have been requested by the host through the role assignment, and suppress interfaces explicitly excluded by the roles - e.g. if the host did not assign kARAEditorRendererRole even it was known, editorRendererInterface will be NULL. More... | |
| struct ARAPlugInExtensionInstance |
The plug-in extension instance struct and all interfaces and refs therein must remain valid until the companion plug-in is destroyed by the host. Note that the companion plug-in destruction may happen before or after destroying the document controller it has been bound to, plug-ins must handle both possible destruction orders. Plug-ins must provide all interfaces that have been requested by the host through the role assignment, and suppress interfaces explicitly excluded by the roles - e.g. if the host did not assign kARAEditorRendererRole even it was known, editorRendererInterface will be NULL.
Size-based struct versioning | |
See Versioned structs. | |
| ARASize | structSize |
| ARAPlugInExtensionRef | plugInExtensionRef |
| const ARAPlugInExtensionInterface * | plugInExtensionInterface |
ARA2 Instance Roles | |
| ARAPlaybackRendererRef | playbackRendererRef |
| const ARAPlaybackRendererInterface * | playbackRendererInterface |
| ARAEditorRendererRef | editorRendererRef |
| const ARAEditorRendererInterface * | editorRendererInterface |
| ARAEditorViewRef | editorViewRef |
| const ARAEditorViewInterface * | editorViewInterface |
Plug-in instance role flags.