Plug-In Extension

Detailed Description

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...
 

Class Documentation

◆ ARAPlugInExtensionInstance

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
 

Enumeration Type Documentation

◆ ARAPlugInInstanceRoleFlags

Plug-in instance role flags.

Enumerator
kARAPlaybackRendererRole 

Role: playback render. Plug-in instances fulfilling this role are performing playback rendering, both for realtime song playback or for offline or realtime bounces/exports. Playback render plug-ins can be responsible for more than one playback region at a time, although hosts may prefer to use a 1:1 relationship to simplify their implementation and easily allow for further per-region processing in the host (fades, region gain). When dealing with looped regions and using the content based fades, a trivial optimization of the above pattern is to use the same renderer instance for all consecutive repetitions of the loop, which still allows for properly applying region gain and fades at the start or end of the consecutive repetitions. Another viable approach would be to use as many playback renderer instances per track as there are concurrently sounding regions on the track (i.e. including head and tail time), and distribute the regions in a round-robin fashion across those renderers so that in each renderer the regions never overlap. This way, the host could extract a separate signal per region with a minimal count of playback renderers. Note that there may be several playback renderers per playback region, for example if a host executes an export as background tasks that run concurrently with realtime playback. A playback render plug-in will replace its inputs with the rendered signal. If it does not also have editor rendering responsibilities, it does not need to be rendered while stopped, and during playback only needs to be rendered for the range covered by the region, plus its head and tail time. Playback renderers are transient, the host does not need to store the state of these instances via the companion API (unless they also fulfill kARAEditorViewRole or other persistent roles).

kARAEditorRendererRole 

Role: editor render. Plug-in instances fulfilling this role are performing auxiliary realtime rendering that is only used to support the editing process, such as metronome clicks or playing the pitch of a note while it's being dragged to a different pitch. There should only be one plug-in instance that handles editor rendering for any given playback region. Since it is up to the plug-in to decide when it will generate previewing output based on the editing, it needs to be permanently rendered by the host. If a editor rendering plug-in is not responsible for playback, it will always forward its input signal to the output, adding its preview signal as needed. Otherwise it will add the signal to the playback render output described above. Editor renderers are transient, the host does not need to store the state of these instances via the companion API (unless they also fulfill kARAEditorViewRole or other persistent roles).

kARAEditorViewRole 

Role: editor view. Plug-in instances fulfilling this role can be used to display a GUI. Unlike rendering for playback or editing, the view role is not tied to individual playback regions or region sequences, but rather to all regions and sequences within the document controller to which the given plug-in instance is bound. Selection and hiding of host entities is communicated to editor view plug-ins so that they can dynamically show a proper subset of the full document graph. Editor view plug-ins may contain some state related to user interface configuration, and thus their state needs to be persistent via the companion API.