Plug-In Instance Roles

Detailed Description

Classes that implement the ARA plug-in extension instance role interfaces.

Classes

class  ARA::PlugIn::PlaybackRenderer
 Extensible plug-in instance role class implementing an ARA Playback Renderer Interface (Added In ARA 2.0). More...
 
class  ARA::PlugIn::EditorRenderer
 Extensible plug-in instance role class implementing an ARA Editor Renderer Interface (Added In ARA 2.0). More...
 
class  ARA::PlugIn::EditorView
 Extensible plug-in instance role class implementing an ARA Editor View Interface (Added In ARA 2.0). More...
 
class  ARA::PlugIn::PlugInExtension
 Utility class that wraps an ARAPlugInExtensionInstance. Each companion API plug-in instance owns one PlugInExtension (or custom subclass thereof). More...
 

Class Documentation

◆ ARA::PlugIn::PlaybackRenderer

class ARA::PlugIn::PlaybackRenderer

Extensible plug-in instance role class implementing an ARA Playback Renderer Interface (Added In ARA 2.0).

Inheritance diagram for ARA::PlugIn::PlaybackRenderer:
ARA::PlugIn::PlaybackRendererInterface

PlaybackRenderer Region Assignment Customization

To be overridden by subclasses if needed. Overrides do not need to call base class implementation.

virtual void willAddPlaybackRegion (PlaybackRegion *playbackRegion) noexcept
 Override to customize behavior before playbackRegion is assigned to the renderer during addPlaybackRegion().
 
virtual void didAddPlaybackRegion (PlaybackRegion *playbackRegion) noexcept
 Override to customize behavior after playbackRegion is assigned to the renderer during addPlaybackRegion().
 
virtual void willRemovePlaybackRegion (PlaybackRegion *playbackRegion) noexcept
 Override to customize behavior before playbackRegion is removed from the renderer during removePlaybackRegion().
 
virtual void didRemovePlaybackRegion (PlaybackRegion *playbackRegion) noexcept
 Override to customize behavior after playbackRegion is removed from the renderer during removePlaybackRegion().
 

Member Access

Where applicable, use the optional template parameter to cast the returned instances to your custom subclass.

template<typename DocumentController_t = DocumentController>
DocumentController_t * getDocumentController () const noexcept
 Retrieve the DocumentController instance the renderer is bound to. Note that during destruction phase, the document controller may have already deleted its document and associated graph - its getDocument () will then return nullptr.
 
template<typename PlaybackRegion_t = PlaybackRegion>
std::vector< PlaybackRegion_t * > const & getPlaybackRegions () const noexcept
 Retrieve the current list of playback regions assigned to the renderer.
 

Additional Inherited Members

- Public Member Functions inherited from ARA::PlugIn::PlaybackRendererInterface
virtual void addPlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept=0
 
virtual void removePlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept=0
 

◆ ARA::PlugIn::EditorRenderer

class ARA::PlugIn::EditorRenderer

Extensible plug-in instance role class implementing an ARA Editor Renderer Interface (Added In ARA 2.0).

Inheritance diagram for ARA::PlugIn::EditorRenderer:
ARA::PlugIn::EditorRendererInterface

EditorRenderer Region Assignment Customization

To be overridden by subclasses if needed. Overrides do not need to call base class implementation.

virtual void willAddPlaybackRegion (PlaybackRegion *playbackRegion) noexcept
 Override to customize behavior before playbackRegion is assigned to the renderer during addPlaybackRegion().
 
virtual void didAddPlaybackRegion (PlaybackRegion *playbackRegion) noexcept
 Override to customize behavior after playbackRegion is assigned to the renderer during addPlaybackRegion().
 
virtual void willRemovePlaybackRegion (PlaybackRegion *playbackRegion) noexcept
 Override to customize behavior before playbackRegion is removed from renderer during removePlaybackRegion().
 
virtual void didRemovePlaybackRegion (PlaybackRegion *playbackRegion) noexcept
 Override to customize behavior after playbackRegion is removed from renderer during removePlaybackRegion().
 
virtual void willAddRegionSequence (RegionSequence *regionSequence) noexcept
 Override to customize behavior before all regions in regionSequence are added to the renderer during addRegionSequence().
 
virtual void didAddRegionSequence (RegionSequence *regionSequence) noexcept
 Override to customize behavior after all regions in regionSequence are added to the renderer during addRegionSequence().
 
virtual void willRemoveRegionSequence (RegionSequence *regionSequence) noexcept
 Override to customize behavior before all regions in regionSequence are removed from the renderer during removeRegionSequence().
 
virtual void didRemoveRegionSequence (RegionSequence *regionSequence) noexcept
 Override to customize behavior after all regions in regionSequence are removed from the renderer during removeRegionSequence().
 

Member Access

Where applicable, use the optional template parameter to cast the returned instances to your custom subclass.

template<typename DocumentController_t = DocumentController>
DocumentController_t * getDocumentController () const noexcept
 Retrieve the DocumentController instance the renderer is bound to. Note that during destruction phase, the document controller may have already deleted its document and associated graph - its getDocument () will then return nullptr.
 
template<typename PlaybackRegion_t = PlaybackRegion>
std::vector< PlaybackRegion_t * > const & getPlaybackRegions () const noexcept
 Retrieve the current list of playback regions assigned to the renderer.
 
template<typename RegionSequence_t = RegionSequence>
std::vector< RegionSequence_t * > const & getRegionSequences () const noexcept
 Retrieve the current list of region sequences assigned to the renderer.
 

Additional Inherited Members

- Public Member Functions inherited from ARA::PlugIn::EditorRendererInterface
virtual void addPlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept=0
 
virtual void removePlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept=0
 
virtual void addRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept=0
 
virtual void removeRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept=0
 

◆ ARA::PlugIn::EditorView

class ARA::PlugIn::EditorView

Extensible plug-in instance role class implementing an ARA Editor View Interface (Added In ARA 2.0).

Inheritance diagram for ARA::PlugIn::EditorView:
ARA::PlugIn::EditorViewInterface

EditorView Host UI notification Customization

To be overridden by subclasses if needed. Overrides do not need to call base class implementation. Only called while there actually is an editor UI open.

virtual void doNotifySelection (const ViewSelection *selection) noexcept
 Override to implement notifySelection().
 
virtual void doNotifyHideRegionSequences (std::vector< RegionSequence * > const &hiddenRegionSequences) noexcept
 Override to implement notifyHideRegionSequences().
 

Member Access

Where applicable, use the optional template parameter to cast the returned instances to your custom subclass.

template<typename DocumentController_t = DocumentController>
DocumentController_t * getDocumentController () const noexcept
 Retrieve the DocumentController instance the view is bound to. Note that during destruction phase, the document controller may have already deleted its document and associated graph - its getDocument () will then return nullptr.
 
const ViewSelection & getViewSelection () const noexcept
 Retrieves the last view selection sent from the host. If some of the selected objects have been deleted by the host, this will return an empty selection, because the host will eventually send a new, properly updated selection. Note that while it clears the selection, the deletion does not trigger doNotifySelection () for the same reason that the host will send it afterwards. This should only be called while there actually is an editor UI open, because otherwise the host will not maintain the view selection in this plug-in instance.
 
template<typename RegionSequence_t = RegionSequence>
std::vector< RegionSequence_t * > const & getHiddenRegionSequences () const noexcept
 Retrieves the hidden region sequences sent from the host. If a hidden region sequence has been deleted by the host, it will no longer appear in this list, but doNotifyHideRegionSequences () will not be triggered implicitly - the host is expected to trigger this once all its updates have completed. This should only be called while there actually is an editor UI open, because otherwise the host will not maintain the hidden region sequences in this plug-in instance.
 
void setEditorOpen (bool isOpen) noexcept
 Must be called by the companion API implementations whenever the UI is opened or closed.
 

Additional Inherited Members

- Public Member Functions inherited from ARA::PlugIn::EditorViewInterface
virtual void notifySelection (SizedStructPtr< ARAViewSelection > selection) noexcept=0
 Apply the given host selection to all associated views. This ARA 2.0 addition allows hosts to translate the effects of their selection implementation to a selection of ARA objects that can be interpreted by the plug-in. The command is not strict a setter for the given selection state, it rather notifies the plug-in about relevant user interaction in the host so that it can adopt in whatever way provides the best user experience within the context of the given plug-in design. A plug-in may e.g. implement scrolling to relevant positions, select the playback regions in its inspector(s), or filter the provided objects further depending on user settings. The plug-in also remains free to modify its internal selection at any time through its build-in UI behavior. For example, a plug-in may design its UI around individual regions being edited, or around entire region sequences. Melodyne features both modes, switchable by the user. When editing an individual region, it will always pick the "most suitable" region from the selection, and ignore the other selected regions. Melodyne also implements various ways to switch the editable region sequence(s) or playback region at any time independently from the host selection, as well as a user option to temporarily ignore host selection changes to "pin" the current selection. The same "loose" coupling applies on the host side: the selection sent by the host is not necessarily equal to its actual selection, but rather the best representation of the users' intent. For example, the user may be able to select entities that are not directly represented in the ARA API, but relate to a set of playback regions in some meaningful way. In that case, those regions may be sent as selection. The selection command includes various optional entities that describe the selection on the host side, such as playback regions or region sequences. Host will only explicitly provide those objects that best describe their current selection, but plug-ins can often derive other selections from that, such as calculating a region selection based on sequence selection and time range. Most hosts offer both an object-based selection which typically centers around selected arrange events (playback regions) and tracks (region sequences) versus a time-range based selection that is independent of the arrange events but typically also includes track selection. Both modes shall be distinguished by providing a time range only in the latter case. Some hosts even allow to select multiple time ranges, this should be expressed by sending their union range across the API. For an object-based selection, the time range remains NULL, and plug-ins can calculate an implicit time range from the selected playback regions if desired. Arrange event selection may linked to track selection in a variety of ways. For example, selecting a track may select its events (often filter by playback cycle range), and selecting an event may select its associated track as well. The ARA selection must be always updated to reflect any such linking accordingly. In each object list, objects are ordered by importance, with the most relevant, "focused" object being first. So if a plug-in supports only a single region selection, it should use the first region. If it can only show a single region sequence at a time, it should use the first selected sequence, or if no sequences are included in the selection fall back to the sequence of the first selected region, etc. Each new selection call describes a full selection, i.e. replaces the previous selection. An empty selection is valid and should be communicated by the host, since some plug-ins may need to evaluate this in special cases. Being selected does not affect the life time of the objects - selected objects may be deleted without updating the selection status first. Note that a pointer to this struct and all pointers contained therein are only valid for the duration of the current call receiving the pointer - the data must be evaluated/copied inside the call, and the pointers must not be stored anywhere. More...
 
virtual void notifyHideRegionSequences (ARASize regionSequenceRefsCount, const ARARegionSequenceRef regionSequenceRefs[]) noexcept=0
 Reflect hiding of region sequences in all associated views. Some hosts offer the option to hide arrange tracks from view, so that they are no longer visible, while still being played back regularly. This can be communicated to the plug-in so that it follows suite. Each call implicitly unhides all previously hidden region sequences, so calling this with an empty list makes all sequences visible. The regionSequenceRefs pointer is only valid for the duration of the call, it must be evaluated inside the call, and the pointer must not be stored anywhere. It should be NULL if regionSequenceRefsCount is 0. More...
 

◆ ARA::PlugIn::PlugInExtension

class ARA::PlugIn::PlugInExtension

Utility class that wraps an ARAPlugInExtensionInstance. Each companion API plug-in instance owns one PlugInExtension (or custom subclass thereof).

Public Member Functions

const ARAPlugInExtensionInstance * bindToARA (ARADocumentControllerRef documentControllerRef, ARAPlugInInstanceRoleFlags knownRoles, ARAPlugInInstanceRoleFlags assignedRoles) noexcept
 Establish the binding to ARA when requested through the companion API, switching the plug-in from regular processing to ARA mode.
 
bool isBoundToARA () const noexcept
 Test whether bindToDocumentController () has been called.
 
template<typename DocumentController_t = DocumentController>
DocumentController_t * getDocumentController () const noexcept
 Retrieve the DocumentController instance the plug-in instance is bound to. Returns nullptr if bindToDocumentController () hasn't been called yet. Note that during destruction phase, the document controller may have already deleted its document and associated graph - its getDocument () will then return nullptr.
 

ARA2 Instance Roles

Use these functions to access the plug-in extension roles defined by ARA. These functions return nullptr if the plug-in instance doesn't fill the requested role - i.e if the plug-in instance is not an EditorView, getEditorView() returns nullptr.

Where applicable, use the optional template parameter to cast the returned instances to your custom subclass.

template<typename PlaybackRenderer_t = PlaybackRenderer>
PlaybackRenderer_t * getPlaybackRenderer () const noexcept
 Get the PlaybackRenderer instance role, if it exists.
 
template<typename EditorRenderer_t = EditorRenderer>
EditorRenderer_t * getEditorRenderer () const noexcept
 Get the EditorRenderer instance role, if it exists.
 
template<typename EditorView_t = EditorView>
EditorView_t * getEditorView () const noexcept
 Get the EditorView instance role, if it exists.
 
virtual void didBindToARA () noexcept
 Optional hook for derived classes to perform any additional initialization that may be needed.