Host Interface Wrappers

Detailed Description

Wrappers for the interfaces used to communicate with and control the ARA host.

Classes

class  ARA::PlugIn::HostAudioAccessController
 Wrapper class for the ARAAudioAccessControllerInterface provided by the host. More...
 
class  ARA::PlugIn::HostArchivingController
 Wrapper class for the ARAArchivingControllerInterface provided by the host. More...
 
class  ARA::PlugIn::HostContentAccessController
 Wrapper class for the ARAContentAccessControllerInterface by the host. More...
 
class  ARA::PlugIn::HostModelUpdateController
 Wrapper class for the ARAModelUpdateControllerInterface provided by the host. More...
 
class  ARA::PlugIn::HostPlaybackController
 Wrapper class for the ARAPlaybackControllerInterface provided by the host. More...
 

Class Documentation

◆ ARA::PlugIn::HostAudioAccessController

class ARA::PlugIn::HostAudioAccessController

Wrapper class for the ARAAudioAccessControllerInterface provided by the host.

Inheritance diagram for ARA::PlugIn::HostAudioAccessController:
ARA::InterfaceInstance< ARAAudioAccessControllerHostRef, ARAAudioAccessControllerInterface >

Public Member Functions

ARAAudioReaderHostRef createAudioReaderForSource (ARAAudioSourceHostRef audioSourceHostRef, bool use64BitSamples) noexcept
 Create audio reader instance to access sample data in an audio source. The format of the data is matching the format of the audio source, with a choice of reading samples as 32 bit or 64 bit (hosts must support both formats). Similar to the rules for creating content readers, the plug-in may call these functions only from calls in the "Audio Source Management" section of ARADocumentControllerInterface for the particular audio source the call is referring to, or from ARADocumentControllerInterface::endEditing() for any audio source. Contrary to content readers, audio readers are long-living objects that are not bound to a certain stack frame. More...
 
bool readAudioSamples (ARAAudioReaderHostRef audioReaderHostRef, ARASamplePosition samplePosition, ARASampleCount samplesPerChannel, void *const buffers[]) noexcept
 Read audio samples. The samples are provided in non-interleaved buffers of double or float data, depending on whether use64BitSamples was set when creating the reader. The channel count equals the channel count of the audio source. The data alignment and byte order always matches the machine's native layout. If the requested sample range extends beyond the start or end of the audio source, the out-of-range samples should be filled with silence. This should not be treated as an error. This potentially blocking function may be called from any non-realtime thread (including threads for offline rendering), but not from more than one thread per reader at the same time. The host may decide to let the thread sleep until the requested data is available, the plug-in must be designed to deal with this without triggering priority inversion. The target buffer(s) are provided by the caller. Result is kARATrue upon success, or kARAFalse when there is a critical, nonrecoverable I/O error, such as a network failure while the file is being read from a server. In case of failing in this call, the buffers must be filled with silence and the host must notify the user about the problem in an appropriate way. The plug-in must deal gracefully with any such I/O errors, both during analysis and rendering. More...
 
void destroyAudioReader (ARAAudioReaderHostRef audioReaderHostRef) noexcept
 Destroy given audio reader created by the host. The caller must guarantee that the reader is currently not in use in some other thread. See ARAAudioAccessControllerInterface::createAudioReaderForSource() about the restrictions when to call this. More...
 
- Public Member Functions inherited from ARA::InterfaceInstance< ARAAudioAccessControllerHostRef, ARAAudioAccessControllerInterface >
ARAAudioAccessControllerHostRef getRef () const noexcept
 Retrieve the ARA reference associated with Interface.
 
const SizedStructPtr< ARAAudioAccessControllerInterface > & getInterface () const noexcept
 Retrieve the underlying Interface pointer.
 
bool isProvided () const noexcept
 Returns whether or not an implementation of the interface was provided.
 

Additional Inherited Members

- Protected Types inherited from ARA::InterfaceInstance< ARAAudioAccessControllerHostRef, ARAAudioAccessControllerInterface >
using BaseType = InterfaceInstance
 InterfaceInstance alias, to allow derived classes to easily reference their templated base class.
 
- Protected Member Functions inherited from ARA::InterfaceInstance< ARAAudioAccessControllerHostRef, ARAAudioAccessControllerInterface >
 InterfaceInstance (ARAAudioAccessControllerHostRef ref, const ARAAudioAccessControllerInterface *ifc) noexcept
 Constructor for derived classes to wrap a ref and interface pointer. The derived classes typically read these values from an instance struct which is passed to their public c'tor.
 

Member Function Documentation

◆ createAudioReaderForSource()

ARAAudioReaderHostRef ARA::PlugIn::HostAudioAccessController::createAudioReaderForSource ( ARAAudioSourceHostRef  audioSourceHostRef,
bool  use64BitSamples 
)
noexcept

Create audio reader instance to access sample data in an audio source. The format of the data is matching the format of the audio source, with a choice of reading samples as 32 bit or 64 bit (hosts must support both formats). Similar to the rules for creating content readers, the plug-in may call these functions only from calls in the "Audio Source Management" section of ARADocumentControllerInterface for the particular audio source the call is referring to, or from ARADocumentControllerInterface::endEditing() for any audio source. Contrary to content readers, audio readers are long-living objects that are not bound to a certain stack frame.

◆ destroyAudioReader()

void ARA::PlugIn::HostAudioAccessController::destroyAudioReader ( ARAAudioReaderHostRef  audioReaderHostRef)
noexcept

Destroy given audio reader created by the host. The caller must guarantee that the reader is currently not in use in some other thread. See ARAAudioAccessControllerInterface::createAudioReaderForSource() about the restrictions when to call this.

◆ readAudioSamples()

bool ARA::PlugIn::HostAudioAccessController::readAudioSamples ( ARAAudioReaderHostRef  audioReaderHostRef,
ARASamplePosition  samplePosition,
ARASampleCount  samplesPerChannel,
void *const  buffers[] 
)
noexcept

Read audio samples. The samples are provided in non-interleaved buffers of double or float data, depending on whether use64BitSamples was set when creating the reader. The channel count equals the channel count of the audio source. The data alignment and byte order always matches the machine's native layout. If the requested sample range extends beyond the start or end of the audio source, the out-of-range samples should be filled with silence. This should not be treated as an error. This potentially blocking function may be called from any non-realtime thread (including threads for offline rendering), but not from more than one thread per reader at the same time. The host may decide to let the thread sleep until the requested data is available, the plug-in must be designed to deal with this without triggering priority inversion. The target buffer(s) are provided by the caller. Result is kARATrue upon success, or kARAFalse when there is a critical, nonrecoverable I/O error, such as a network failure while the file is being read from a server. In case of failing in this call, the buffers must be filled with silence and the host must notify the user about the problem in an appropriate way. The plug-in must deal gracefully with any such I/O errors, both during analysis and rendering.

◆ ARA::PlugIn::HostArchivingController

class ARA::PlugIn::HostArchivingController

Wrapper class for the ARAArchivingControllerInterface provided by the host.

Inheritance diagram for ARA::PlugIn::HostArchivingController:
ARA::InterfaceInstance< ARAArchivingControllerHostRef, ARAArchivingControllerInterface >

Public Member Functions

ARASize getArchiveSize (ARAArchiveReaderHostRef archiveReaderHostRef) noexcept
 Query the size of the archive. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() calls. Plug-ins must respect this size when reading the archive, reading beyond the end of the data is a programming error (and should thus be asserted by the host). More...
 
bool readBytesFromArchive (ARAArchiveReaderHostRef archiveReaderHostRef, ARASize position, ARASize length, ARAByte buffer[]) noexcept
 Read bytes. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() calls. Result is kARATrue upon success, or kARAFalse when there is a critical, nonrecoverable I/O error, such as a network failure while the file is being read from a server. In case of failing in this call, the host must notify the user about the problem in some appropriate way. The archive will not be restored by the plug-in then, it'll fall back into some proper initial state for the affected objects. More...
 
bool writeBytesToArchive (ARAArchiveWriterHostRef archiveWriterHostRef, ARASize position, ARASize length, const ARAByte buffer[]) noexcept
 Write bytes. This may only be called from storeObjectsToArchive() or the deprecated storeDocumentToArchive(). Result is kARATrue upon success, or kARAFalse when there is a critical, nonrecoverable I/O error, such as a network failure while the file is being written to a server. In case of failing in this call, the host must notify the user about the problem in an appropriate way.
Note that a plug-in should strive to write the data consecutively in a stream-like manner. Nevertheless, repositioning is needed to support chunk-style archives where the chunk length must be specified at the start of the chunk, but is not known until the chunk data has been fully created (and possibly compressed). In that case, the plug-in will need to "rewind" to the chunk size entry in the chunk header after writing the chunk and update it accordingly. As in most file APIs, any range of bytes that was skipped when writing should be filled with 0 by the host. More...
 
void notifyDocumentArchivingProgress (float value) noexcept
 Message to the host signaling document save progress, value ranges from 0.0f to 1.0f. This may only be called from storeObjectsToArchive() or from the deprecated storeDocumentToArchive(). In order to keep CPU load low, plug-ins should try to keep the update rate for this call as low as about 1000 calls per archive, which equals increments of 0.1%. More...
 
void notifyDocumentUnarchivingProgress (float value) noexcept
 Message to the host signaling document save progress, value ranges from 0.0f to 1.0f. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() and the associated model object creation/update calls guarded by them. In the deprecated form, the first call should be made from begin- and the last call from endRestoringDocumentFromArchive(). In order to keep CPU load low, plug-ins should try to keep the update rate for this call as low as about 1000 calls per archive, which equals increments of 0.1%. More...
 
ARAPersistentID getDocumentArchiveID (ARAArchiveReaderHostRef archiveReaderHostRef) noexcept
 Query the document archive ID that the plug-in's factory provided when saving the archive. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(). Plug-ins can use this information to optimize their unarchiving code in case different archive formats are used depending on document archive ID. The returned pointer is owned by the host and must remain valid until the archive reader is destroyed. All hosts that support kARAAPIGeneration_2_0_Final or newer must implement this call. More...
 
- Public Member Functions inherited from ARA::InterfaceInstance< ARAArchivingControllerHostRef, ARAArchivingControllerInterface >
ARAArchivingControllerHostRef getRef () const noexcept
 Retrieve the ARA reference associated with Interface.
 
const SizedStructPtr< ARAArchivingControllerInterface > & getInterface () const noexcept
 Retrieve the underlying Interface pointer.
 
bool isProvided () const noexcept
 Returns whether or not an implementation of the interface was provided.
 

Additional Inherited Members

- Protected Types inherited from ARA::InterfaceInstance< ARAArchivingControllerHostRef, ARAArchivingControllerInterface >
using BaseType = InterfaceInstance
 InterfaceInstance alias, to allow derived classes to easily reference their templated base class.
 
- Protected Member Functions inherited from ARA::InterfaceInstance< ARAArchivingControllerHostRef, ARAArchivingControllerInterface >
 InterfaceInstance (ARAArchivingControllerHostRef ref, const ARAArchivingControllerInterface *ifc) noexcept
 Constructor for derived classes to wrap a ref and interface pointer. The derived classes typically read these values from an instance struct which is passed to their public c'tor.
 

Member Function Documentation

◆ getArchiveSize()

ARASize ARA::PlugIn::HostArchivingController::getArchiveSize ( ARAArchiveReaderHostRef  archiveReaderHostRef)
noexcept

Query the size of the archive. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() calls. Plug-ins must respect this size when reading the archive, reading beyond the end of the data is a programming error (and should thus be asserted by the host).

◆ getDocumentArchiveID()

ARAPersistentID ARA::PlugIn::HostArchivingController::getDocumentArchiveID ( ARAArchiveReaderHostRef  archiveReaderHostRef)
noexcept

Query the document archive ID that the plug-in's factory provided when saving the archive. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(). Plug-ins can use this information to optimize their unarchiving code in case different archive formats are used depending on document archive ID. The returned pointer is owned by the host and must remain valid until the archive reader is destroyed. All hosts that support kARAAPIGeneration_2_0_Final or newer must implement this call.

◆ notifyDocumentArchivingProgress()

void ARA::PlugIn::HostArchivingController::notifyDocumentArchivingProgress ( float  value)
noexcept

Message to the host signaling document save progress, value ranges from 0.0f to 1.0f. This may only be called from storeObjectsToArchive() or from the deprecated storeDocumentToArchive(). In order to keep CPU load low, plug-ins should try to keep the update rate for this call as low as about 1000 calls per archive, which equals increments of 0.1%.

◆ notifyDocumentUnarchivingProgress()

void ARA::PlugIn::HostArchivingController::notifyDocumentUnarchivingProgress ( float  value)
noexcept

Message to the host signaling document save progress, value ranges from 0.0f to 1.0f. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() and the associated model object creation/update calls guarded by them. In the deprecated form, the first call should be made from begin- and the last call from endRestoringDocumentFromArchive(). In order to keep CPU load low, plug-ins should try to keep the update rate for this call as low as about 1000 calls per archive, which equals increments of 0.1%.

◆ readBytesFromArchive()

bool ARA::PlugIn::HostArchivingController::readBytesFromArchive ( ARAArchiveReaderHostRef  archiveReaderHostRef,
ARASize  position,
ARASize  length,
ARAByte  buffer[] 
)
noexcept

Read bytes. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() calls. Result is kARATrue upon success, or kARAFalse when there is a critical, nonrecoverable I/O error, such as a network failure while the file is being read from a server. In case of failing in this call, the host must notify the user about the problem in some appropriate way. The archive will not be restored by the plug-in then, it'll fall back into some proper initial state for the affected objects.

◆ writeBytesToArchive()

bool ARA::PlugIn::HostArchivingController::writeBytesToArchive ( ARAArchiveWriterHostRef  archiveWriterHostRef,
ARASize  position,
ARASize  length,
const ARAByte  buffer[] 
)
noexcept

Write bytes. This may only be called from storeObjectsToArchive() or the deprecated storeDocumentToArchive(). Result is kARATrue upon success, or kARAFalse when there is a critical, nonrecoverable I/O error, such as a network failure while the file is being written to a server. In case of failing in this call, the host must notify the user about the problem in an appropriate way.
Note that a plug-in should strive to write the data consecutively in a stream-like manner. Nevertheless, repositioning is needed to support chunk-style archives where the chunk length must be specified at the start of the chunk, but is not known until the chunk data has been fully created (and possibly compressed). In that case, the plug-in will need to "rewind" to the chunk size entry in the chunk header after writing the chunk and update it accordingly. As in most file APIs, any range of bytes that was skipped when writing should be filled with 0 by the host.

◆ ARA::PlugIn::HostContentAccessController

class ARA::PlugIn::HostContentAccessController

Wrapper class for the ARAContentAccessControllerInterface by the host.

Note that ARAPlug.h includes convenient wrappers for content readers via the HostContentReader classes that allow to use them with stl iterators and also provide additional validation.

Inheritance diagram for ARA::PlugIn::HostContentAccessController:
ARA::InterfaceInstance< ARAContentAccessControllerHostRef, ARAContentAccessControllerInterface >

Public Member Functions

bool isMusicalContextContentAvailable (ARAMusicalContextHostRef musicalContextHostRef, ARAContentType contentType) noexcept
 Query whether the given content type is currently available for the given musical context. More...
 
ARAContentGrade getMusicalContextContentGrade (ARAMusicalContextHostRef musicalContextHostRef, ARAContentType contentType) noexcept
 Query the current quality of the information provided for the given musical context and content type. More...
 
ARAContentReaderHostRef createMusicalContextContentReader (ARAMusicalContextHostRef musicalContextHostRef, ARAContentType contentType, const ARAContentTimeRange *range) noexcept
 Create a content reader for the given musical context and content type. This should only be called after availability has been confirmed using isMusicalContextContentAvailable(), and is mainly used to communicate the song timeline to the plug-in. The time range may be NULL, which means that the entire musical context shall be read. If a time range is specified, all events that at least partially intersect with the range will be read. More...
 
bool isAudioSourceContentAvailable (ARAAudioSourceHostRef audioSourceHostRef, ARAContentType contentType) noexcept
 Query whether the given content type is currently available for the given audio source. More...
 
ARAContentGrade getAudioSourceContentGrade (ARAAudioSourceHostRef audioSourceHostRef, ARAContentType contentType) noexcept
 Query the current quality of the information provided for the given audio source and content type. More...
 
ARAContentReaderHostRef createAudioSourceContentReader (ARAAudioSourceHostRef audioSourceHostRef, ARAContentType contentType, const ARAContentTimeRange *range) noexcept
 Create a content reader for the given audio source and content type. This should only be called after availability has been confirmed using isAudioSourceContentAvailable(). The host may be able to provide meta-information such as a known tempo or a known set of notes used in the material, which may enable the plug-in to speed up or even skip completely certain analysis passes (often depending on the content grade of the information). The time range may be NULL, which means that the entire audio source shall be read. If a time range is specified, all events that at least partially intersect with the range will be read. More...
 
ARAInt32 getContentReaderEventCount (ARAContentReaderHostRef contentReaderHostRef) noexcept
 Query how many events the given reader exposes. More...
 
const void * getContentReaderDataForEvent (ARAContentReaderHostRef contentReaderHostRef, ARAInt32 eventIndex) noexcept
 Query data of the given event of the given reader. The returned pointer is owned by the host and must remain valid until either getContentReaderDataForEvent() is called again or the content reader is destroyed. More...
 
void destroyContentReader (ARAContentReaderHostRef contentReaderHostRef) noexcept
 Destroy the given content reader. More...
 
- Public Member Functions inherited from ARA::InterfaceInstance< ARAContentAccessControllerHostRef, ARAContentAccessControllerInterface >
ARAContentAccessControllerHostRef getRef () const noexcept
 Retrieve the ARA reference associated with Interface.
 
const SizedStructPtr< ARAContentAccessControllerInterface > & getInterface () const noexcept
 Retrieve the underlying Interface pointer.
 
bool isProvided () const noexcept
 Returns whether or not an implementation of the interface was provided.
 

Additional Inherited Members

- Protected Types inherited from ARA::InterfaceInstance< ARAContentAccessControllerHostRef, ARAContentAccessControllerInterface >
using BaseType = InterfaceInstance
 InterfaceInstance alias, to allow derived classes to easily reference their templated base class.
 
- Protected Member Functions inherited from ARA::InterfaceInstance< ARAContentAccessControllerHostRef, ARAContentAccessControllerInterface >
 InterfaceInstance (ARAContentAccessControllerHostRef ref, const ARAContentAccessControllerInterface *ifc) noexcept
 Constructor for derived classes to wrap a ref and interface pointer. The derived classes typically read these values from an instance struct which is passed to their public c'tor.
 

Member Function Documentation

◆ createAudioSourceContentReader()

ARAContentReaderHostRef ARA::PlugIn::HostContentAccessController::createAudioSourceContentReader ( ARAAudioSourceHostRef  audioSourceHostRef,
ARAContentType  contentType,
const ARAContentTimeRange *  range 
)
noexcept

Create a content reader for the given audio source and content type. This should only be called after availability has been confirmed using isAudioSourceContentAvailable(). The host may be able to provide meta-information such as a known tempo or a known set of notes used in the material, which may enable the plug-in to speed up or even skip completely certain analysis passes (often depending on the content grade of the information). The time range may be NULL, which means that the entire audio source shall be read. If a time range is specified, all events that at least partially intersect with the range will be read.

◆ createMusicalContextContentReader()

ARAContentReaderHostRef ARA::PlugIn::HostContentAccessController::createMusicalContextContentReader ( ARAMusicalContextHostRef  musicalContextHostRef,
ARAContentType  contentType,
const ARAContentTimeRange *  range 
)
noexcept

Create a content reader for the given musical context and content type. This should only be called after availability has been confirmed using isMusicalContextContentAvailable(), and is mainly used to communicate the song timeline to the plug-in. The time range may be NULL, which means that the entire musical context shall be read. If a time range is specified, all events that at least partially intersect with the range will be read.

◆ destroyContentReader()

void ARA::PlugIn::HostContentAccessController::destroyContentReader ( ARAContentReaderHostRef  contentReaderHostRef)
noexcept

Destroy the given content reader.

◆ getAudioSourceContentGrade()

ARAContentGrade ARA::PlugIn::HostContentAccessController::getAudioSourceContentGrade ( ARAAudioSourceHostRef  audioSourceHostRef,
ARAContentType  contentType 
)
noexcept

Query the current quality of the information provided for the given audio source and content type.

◆ getContentReaderDataForEvent()

const void* ARA::PlugIn::HostContentAccessController::getContentReaderDataForEvent ( ARAContentReaderHostRef  contentReaderHostRef,
ARAInt32  eventIndex 
)
noexcept

Query data of the given event of the given reader. The returned pointer is owned by the host and must remain valid until either getContentReaderDataForEvent() is called again or the content reader is destroyed.

◆ getContentReaderEventCount()

ARAInt32 ARA::PlugIn::HostContentAccessController::getContentReaderEventCount ( ARAContentReaderHostRef  contentReaderHostRef)
noexcept

Query how many events the given reader exposes.

◆ getMusicalContextContentGrade()

ARAContentGrade ARA::PlugIn::HostContentAccessController::getMusicalContextContentGrade ( ARAMusicalContextHostRef  musicalContextHostRef,
ARAContentType  contentType 
)
noexcept

Query the current quality of the information provided for the given musical context and content type.

◆ isAudioSourceContentAvailable()

bool ARA::PlugIn::HostContentAccessController::isAudioSourceContentAvailable ( ARAAudioSourceHostRef  audioSourceHostRef,
ARAContentType  contentType 
)
noexcept

Query whether the given content type is currently available for the given audio source.

◆ isMusicalContextContentAvailable()

bool ARA::PlugIn::HostContentAccessController::isMusicalContextContentAvailable ( ARAMusicalContextHostRef  musicalContextHostRef,
ARAContentType  contentType 
)
noexcept

Query whether the given content type is currently available for the given musical context.

◆ ARA::PlugIn::HostModelUpdateController

class ARA::PlugIn::HostModelUpdateController

Wrapper class for the ARAModelUpdateControllerInterface provided by the host.

Inheritance diagram for ARA::PlugIn::HostModelUpdateController:
ARA::InterfaceInstance< ARAModelUpdateControllerHostRef, ARAModelUpdateControllerInterface >

Public Member Functions

void notifyAudioSourceAnalysisProgress (ARAAudioSourceHostRef audioSourceHostRef, ARAAnalysisProgressState state, float value) noexcept
 Message to the host signaling analysis progress, value ranges from 0.0f to 1.0f. The first message must be marked with kARAAnalysisProgressStarted, the last with kARAAnalysisProgressCompleted. This notification is intended solely for displaying a progress indication if desired, but not to trigger content reading for updating content information. That is instead done when receiving notifyAudioSourceContentChanged(), see below. Note that since the updates are polled by the host, any analysis may already have progressed somewhat by the time the start notification is actually delivered, so it may start with a progress larger than 0. It is even possible that an analysis fully completes before its start is notified, in which case the plug-in may choose not notify it at all. If the plug-in internally executes multiple analysis task per audio source simultaneously (for example because it splits them by content type), it must merge all internal progress into a single outer progress. More...
 
void notifyAudioSourceContentChanged (ARAAudioSourceHostRef audioSourceHostRef, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept
 Message to the host when content of the given audio source changes. Not to be called if the change was explicitly triggered by the host, e.g. when restoring audio source state or if the host calls ARADocumentControllerInterface::updateAudioSourceContent(). When restoring state, plug-ins shall only make this call if the object state after loading is not equal to the archived state. This can happen e.g when unarchiving encounters errors, or when state is imported from older versions and converted to some updated model state. The time range may be NULL, this means that the entire audio source is affected. Note that this notification is what hosts will listen to when determining whether the state returned by isAudioSourceContentAnalysisIncomplete() has changed. In other words, the completion state of the analysis itself is considered to be a part of the overall content. Thus, if it changes, the overall content has changed, even if neither the grade nor the data for content readers did change (e.g. because an analysis failed to provide proper results). More...
 
void notifyAudioModificationContentChanged (ARAAudioModificationHostRef audioModificationHostRef, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept
 Message to the host when content of the given audio modification changes. Not to be called if the change was explicitly triggered by the host, e.g. when restoring audio modification state. When restoring state, plug-ins will only make this call if the object state after loading is not equal to the archived state. This can happen e.g when unarchiving encounters errors, or when state is imported from older versions and converted to some updated model state. The time range may be NULL, this means that the entire audio modification is affected. Whenever this notification is received, all playback regions for the given modification are affected as well if their range in modification time intersects with the given time range. Because of this, there was no separate change notification for playback region in ARA 1. This changed with the introduction of content-based fades in ARA 2.0, because playback region content can now change without any audio modification changes. For many use cases, hosts that implement ARA 2 do no longer concern themselves with this call (unless they are also hosting ARA 1 plug-ins and implement an according ARA 2 adapter). More...
 
void notifyPlaybackRegionContentChanged (ARAPlaybackRegionHostRef playbackRegionHostRef, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept
 Message to the host when content of the given playback region changes (added in ARA 2.0). In ARA 1, region content updates were implicitly derived from audio modification updates, (see notifyAudioModificationContentChanged()), based on the assumption that the content of a playback region did depend only on the modification content and the transformation described in the playback region properties. Since ARA 2.0 however, plug-ins use the grouping provided by the region sequences to derive further parameters for the transformation, which enables them to perform content based fades or other custom adjustments. This means the content of any given region can change even if its modification and region properties remain unchanged, and that the host can no longer calculate the content of a region based on the content of its modification. Note that when kARAContentUpdateSignalScopeRemainsUnchanged is not set, this message also indicates that the host needs to update any cached copies of the rendered signal it may hold, and needs to query getPlaybackRegionHeadAndTailTime() for potential updates. The time range is specified in playback time and potentially covers head and tail time too. The time range may be NULL, this means that the entire playback region (including its head and tail time, which may be updated at the same time) is affected. More...
 
- Public Member Functions inherited from ARA::InterfaceInstance< ARAModelUpdateControllerHostRef, ARAModelUpdateControllerInterface >
ARAModelUpdateControllerHostRef getRef () const noexcept
 Retrieve the ARA reference associated with Interface.
 
const SizedStructPtr< ARAModelUpdateControllerInterface > & getInterface () const noexcept
 Retrieve the underlying Interface pointer.
 
bool isProvided () const noexcept
 Returns whether or not an implementation of the interface was provided.
 

Additional Inherited Members

- Protected Types inherited from ARA::InterfaceInstance< ARAModelUpdateControllerHostRef, ARAModelUpdateControllerInterface >
using BaseType = InterfaceInstance
 InterfaceInstance alias, to allow derived classes to easily reference their templated base class.
 
- Protected Member Functions inherited from ARA::InterfaceInstance< ARAModelUpdateControllerHostRef, ARAModelUpdateControllerInterface >
 InterfaceInstance (ARAModelUpdateControllerHostRef ref, const ARAModelUpdateControllerInterface *ifc) noexcept
 Constructor for derived classes to wrap a ref and interface pointer. The derived classes typically read these values from an instance struct which is passed to their public c'tor.
 

Member Function Documentation

◆ notifyAudioModificationContentChanged()

void ARA::PlugIn::HostModelUpdateController::notifyAudioModificationContentChanged ( ARAAudioModificationHostRef  audioModificationHostRef,
const ARAContentTimeRange *  range,
ContentUpdateScopes  scopeFlags 
)
noexcept

Message to the host when content of the given audio modification changes. Not to be called if the change was explicitly triggered by the host, e.g. when restoring audio modification state. When restoring state, plug-ins will only make this call if the object state after loading is not equal to the archived state. This can happen e.g when unarchiving encounters errors, or when state is imported from older versions and converted to some updated model state. The time range may be NULL, this means that the entire audio modification is affected. Whenever this notification is received, all playback regions for the given modification are affected as well if their range in modification time intersects with the given time range. Because of this, there was no separate change notification for playback region in ARA 1. This changed with the introduction of content-based fades in ARA 2.0, because playback region content can now change without any audio modification changes. For many use cases, hosts that implement ARA 2 do no longer concern themselves with this call (unless they are also hosting ARA 1 plug-ins and implement an according ARA 2 adapter).

◆ notifyAudioSourceAnalysisProgress()

void ARA::PlugIn::HostModelUpdateController::notifyAudioSourceAnalysisProgress ( ARAAudioSourceHostRef  audioSourceHostRef,
ARAAnalysisProgressState  state,
float  value 
)
noexcept

Message to the host signaling analysis progress, value ranges from 0.0f to 1.0f. The first message must be marked with kARAAnalysisProgressStarted, the last with kARAAnalysisProgressCompleted. This notification is intended solely for displaying a progress indication if desired, but not to trigger content reading for updating content information. That is instead done when receiving notifyAudioSourceContentChanged(), see below. Note that since the updates are polled by the host, any analysis may already have progressed somewhat by the time the start notification is actually delivered, so it may start with a progress larger than 0. It is even possible that an analysis fully completes before its start is notified, in which case the plug-in may choose not notify it at all. If the plug-in internally executes multiple analysis task per audio source simultaneously (for example because it splits them by content type), it must merge all internal progress into a single outer progress.

◆ notifyAudioSourceContentChanged()

void ARA::PlugIn::HostModelUpdateController::notifyAudioSourceContentChanged ( ARAAudioSourceHostRef  audioSourceHostRef,
const ARAContentTimeRange *  range,
ContentUpdateScopes  scopeFlags 
)
noexcept

Message to the host when content of the given audio source changes. Not to be called if the change was explicitly triggered by the host, e.g. when restoring audio source state or if the host calls ARADocumentControllerInterface::updateAudioSourceContent(). When restoring state, plug-ins shall only make this call if the object state after loading is not equal to the archived state. This can happen e.g when unarchiving encounters errors, or when state is imported from older versions and converted to some updated model state. The time range may be NULL, this means that the entire audio source is affected. Note that this notification is what hosts will listen to when determining whether the state returned by isAudioSourceContentAnalysisIncomplete() has changed. In other words, the completion state of the analysis itself is considered to be a part of the overall content. Thus, if it changes, the overall content has changed, even if neither the grade nor the data for content readers did change (e.g. because an analysis failed to provide proper results).

◆ notifyPlaybackRegionContentChanged()

void ARA::PlugIn::HostModelUpdateController::notifyPlaybackRegionContentChanged ( ARAPlaybackRegionHostRef  playbackRegionHostRef,
const ARAContentTimeRange *  range,
ContentUpdateScopes  scopeFlags 
)
noexcept

Message to the host when content of the given playback region changes (added in ARA 2.0). In ARA 1, region content updates were implicitly derived from audio modification updates, (see notifyAudioModificationContentChanged()), based on the assumption that the content of a playback region did depend only on the modification content and the transformation described in the playback region properties. Since ARA 2.0 however, plug-ins use the grouping provided by the region sequences to derive further parameters for the transformation, which enables them to perform content based fades or other custom adjustments. This means the content of any given region can change even if its modification and region properties remain unchanged, and that the host can no longer calculate the content of a region based on the content of its modification. Note that when kARAContentUpdateSignalScopeRemainsUnchanged is not set, this message also indicates that the host needs to update any cached copies of the rendered signal it may hold, and needs to query getPlaybackRegionHeadAndTailTime() for potential updates. The time range is specified in playback time and potentially covers head and tail time too. The time range may be NULL, this means that the entire playback region (including its head and tail time, which may be updated at the same time) is affected.

◆ ARA::PlugIn::HostPlaybackController

class ARA::PlugIn::HostPlaybackController

Wrapper class for the ARAPlaybackControllerInterface provided by the host.

Inheritance diagram for ARA::PlugIn::HostPlaybackController:
ARA::InterfaceInstance< ARAPlaybackControllerHostRef, ARAPlaybackControllerInterface >

Public Member Functions

void requestStartPlayback () noexcept
 Message to the host to start playback of our document. More...
 
void requestStopPlayback () noexcept
 Message to the host to stop playback of our document. More...
 
void requestSetPlaybackPosition (ARATimePosition timePosition) noexcept
 Message to the host to set the playback position of our document. Note that this may be called both when playing back or when stopped. More...
 
void requestSetCycleRange (ARATimePosition startTime, ARATimeDuration duration) noexcept
 Message to the host to set the playback cycle range of our document. More...
 
void requestEnableCycle (bool enable) noexcept
 Message to the host to enable or disable the playback cycle of our document. More...
 
- Public Member Functions inherited from ARA::InterfaceInstance< ARAPlaybackControllerHostRef, ARAPlaybackControllerInterface >
ARAPlaybackControllerHostRef getRef () const noexcept
 Retrieve the ARA reference associated with Interface.
 
const SizedStructPtr< ARAPlaybackControllerInterface > & getInterface () const noexcept
 Retrieve the underlying Interface pointer.
 
bool isProvided () const noexcept
 Returns whether or not an implementation of the interface was provided.
 

Additional Inherited Members

- Protected Types inherited from ARA::InterfaceInstance< ARAPlaybackControllerHostRef, ARAPlaybackControllerInterface >
using BaseType = InterfaceInstance
 InterfaceInstance alias, to allow derived classes to easily reference their templated base class.
 
- Protected Member Functions inherited from ARA::InterfaceInstance< ARAPlaybackControllerHostRef, ARAPlaybackControllerInterface >
 InterfaceInstance (ARAPlaybackControllerHostRef ref, const ARAPlaybackControllerInterface *ifc) noexcept
 Constructor for derived classes to wrap a ref and interface pointer. The derived classes typically read these values from an instance struct which is passed to their public c'tor.
 

Member Function Documentation

◆ requestEnableCycle()

void ARA::PlugIn::HostPlaybackController::requestEnableCycle ( bool  enable)
noexcept

Message to the host to enable or disable the playback cycle of our document.

◆ requestSetCycleRange()

void ARA::PlugIn::HostPlaybackController::requestSetCycleRange ( ARATimePosition  startTime,
ARATimeDuration  duration 
)
noexcept

Message to the host to set the playback cycle range of our document.

◆ requestSetPlaybackPosition()

void ARA::PlugIn::HostPlaybackController::requestSetPlaybackPosition ( ARATimePosition  timePosition)
noexcept

Message to the host to set the playback position of our document. Note that this may be called both when playing back or when stopped.

◆ requestStartPlayback()

void ARA::PlugIn::HostPlaybackController::requestStartPlayback ( )
noexcept

Message to the host to start playback of our document.

◆ requestStopPlayback()

void ARA::PlugIn::HostPlaybackController::requestStopPlayback ( )
noexcept

Message to the host to stop playback of our document.