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 ARA::PlugIn::HostAudioAccessController |
Wrapper class for the ARAAudioAccessControllerInterface provided by the host.
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. | |
|
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.
|
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.
|
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.
| class ARA::PlugIn::HostArchivingController |
Wrapper class for the ARAArchivingControllerInterface provided by the host.
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. | |
|
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).
|
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.
|
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%.
|
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%.
|
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.
|
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.
| 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.
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. | |
|
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.
|
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.
|
noexcept |
Destroy the given content reader.
|
noexcept |
Query the current quality of the information provided for the given audio source and content type.
|
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.
|
noexcept |
Query how many events the given reader exposes.
|
noexcept |
Query the current quality of the information provided for the given musical context and content type.
|
noexcept |
Query whether the given content type is currently available for the given audio source.
|
noexcept |
Query whether the given content type is currently available for the given musical context.
| class ARA::PlugIn::HostModelUpdateController |
Wrapper class for the ARAModelUpdateControllerInterface provided by the host.
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. | |
|
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).
|
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.
|
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).
|
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.
| class ARA::PlugIn::HostPlaybackController |
Wrapper class for the ARAPlaybackControllerInterface provided by the host.
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. | |
|
noexcept |
Message to the host to enable or disable the playback cycle of our document.
|
noexcept |
Message to the host to set the playback cycle range of our document.
|
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.
|
noexcept |
Message to the host to start playback of our document.
|
noexcept |
Message to the host to stop playback of our document.