Classes that plug-in developers can use to make ARA operations and host communication easier.
Classes | |
| class | ARA::PlugIn::OptionalProperty< T > |
| Template container class managing optional property data sent from the host. If the host passes nullptr for the property, this is stored, otherwise the property data is copied to newly allocated memory. More... | |
| class | ARA::PlugIn::ContentReader |
| Abstract base class for objects that can export plug-in supplied content to the host. If your plug-in can supply ARA content, implementations of this class must be returned that can randomly access and iterate over plug-in content data. Concrete implementations of this class must be returned from DocumentController::doCreateAudioSourceContentReader, DocumentController::doCreateAudioModificationContentReader and DocumentController::doCreatePlaybackRegionContentReader. More... | |
| class | ARA::PlugIn::RestoreObjectsFilter |
| Utility class that wraps an ARARestoreObjectsFilter instance. More... | |
| class | ARA::PlugIn::StoreObjectsFilter |
| Utility class that wraps an ARAStoreObjectsFilter instance. More... | |
| class | ARA::PlugIn::HostContentReader< contentType > |
| Utility class that wraps the host ARAContentAccessControllerInterface. More... | |
| class | ARA::PlugIn::HostAudioReader |
| Utility class that wraps the host ARAAudioAccessControllerInterface. More... | |
| class | ARA::PlugIn::HostArchiveReader |
| Utility class that wraps the host ARAArchivingControllerInterface archive reading functions. More... | |
| class | ARA::PlugIn::HostArchiveWriter |
| Utility class that wraps the host ARAArchivingControllerInterface archive writing functions. More... | |
| class | ARA::PlugIn::ViewSelection |
| Utility class that wraps an ARAViewSelection instance. More... | |
Typedefs | |
| template<ARAContentType contentType> | |
| using | ARA::PlugIn::HostContentReaderBase = ARA::ContentReader< contentType, HostContentAccessController, ARAContentReaderHostRef, ARA::NoContentValidator< contentType, HostContentAccessController, ARAContentReaderHostRef > > |
| Internal helper template class for HostContentReader. | |
| class ARA::PlugIn::OptionalProperty |
Template container class managing optional property data sent from the host. If the host passes nullptr for the property, this is stored, otherwise the property data is copied to newly allocated memory.
| class ARA::PlugIn::ContentReader |
Abstract base class for objects that can export plug-in supplied content to the host. If your plug-in can supply ARA content, implementations of this class must be returned that can randomly access and iterate over plug-in content data. Concrete implementations of this class must be returned from DocumentController::doCreateAudioSourceContentReader, DocumentController::doCreateAudioModificationContentReader and DocumentController::doCreatePlaybackRegionContentReader.
Public Member Functions | |
| virtual ARAInt32 | getEventCount () noexcept=0 |
| Get the count of available content events. | |
| virtual const void * | getDataForEvent (ARAInt32 eventIndex) noexcept=0 |
Get a pointer to the content for event eventIndex. | |
| class ARA::PlugIn::RestoreObjectsFilter |
Utility class that wraps an ARARestoreObjectsFilter instance.
Filter Queries | |
Use these functions to filter and map the objects restored during DocumentController::doRestoreObjectsFromArchive(). | |
| bool | shouldRestoreDocumentData () const noexcept |
| AudioSource * | getAudioSourceToRestoreStateWithID (ARAPersistentID archivedAudioSourceID) const noexcept |
| template<typename AudioSource_t = AudioSource> | |
| AudioSource_t * | getAudioSourceToRestoreStateWithID (ARAPersistentID archivedAudioSourceID) const noexcept |
| AudioModification * | getAudioModificationToRestoreStateWithID (ARAPersistentID archivedAudioModificationID) const noexcept |
| template<typename AudioModification_t = AudioModification> | |
| AudioModification_t * | getAudioModificationToRestoreStateWithID (ARAPersistentID archivedAudioModificationID) const noexcept |
| class ARA::PlugIn::StoreObjectsFilter |
Utility class that wraps an ARAStoreObjectsFilter instance.
Filter Queries | |
Use these functions to filter the objects stored during DocumentController::doStoreObjectsToArchive(). | |
| bool | shouldStoreDocumentData () const noexcept |
| template<typename AudioSource_t = AudioSource> | |
| std::vector< const AudioSource_t * > const & | getAudioSourcesToStore () const noexcept |
| template<typename AudioModification_t = AudioModification> | |
| std::vector< const AudioModification_t * > const & | getAudioModificationsToStore () const noexcept |
| class ARA::PlugIn::HostContentReader |
Utility class that wraps the host ARAContentAccessControllerInterface.
| contentType | The type of ARA content event that can be read. |
Public Member Functions | |
| HostContentReader (const MusicalContext *musicalContext, const ARAContentTimeRange *range=nullptr) noexcept | |
| Read musical context content with an optional time range. | |
| HostContentReader (const AudioSource *audioSource, const ARAContentTimeRange *range=nullptr) noexcept | |
| Read audio source content with an optional time range. | |
Public Member Functions inherited from ARA::ContentReader< contentType, ControllerType, ContentReaderRefType, ValidatorClass > | |
| operator bool () const noexcept | |
Tests whether content is available. Can be written as if (someContentReader) ... | |
| ARAContentGrade | getGrade () const noexcept |
| Get the grade of the content. | |
| ARAInt32 | getEventCount () const noexcept |
| Get the number of content events. Will be 0 if content is not available, or for time-limited content types if range does not cover any events. | |
| const DataType * | getDataPtrForEvent (ARAInt32 eventIndex) const noexcept |
Returns a pointer to the data at index eventIndex. Care must be taken when accessing this pointer, its content will only be valid until any other content reading call is made or the reader is destroyed! | |
| DataType | getDataForEvent (ARAInt32 eventIndex) const noexcept |
Returns the data at index eventIndex. | |
| DataType | operator[] (ARAInt32 eventIndex) const noexcept |
Returns the data at index eventIndex. | |
| const_iterator | begin () const |
| const_iterator | end () const |
Additional Inherited Members | |
Public Types inherited from ARA::ContentReader< contentType, ControllerType, ContentReaderRefType, ValidatorClass > | |
| using | DataType = typename ContentTypeMapper< contentType >::DataType |
| The type of ARA content data for this reader. | |
| using | const_iterator = ContentReaderEventIterator< ContentReader > |
| class ARA::PlugIn::HostAudioReader |
Utility class that wraps the host ARAAudioAccessControllerInterface.
Public Member Functions | |
| HostAudioReader (const AudioSource *audioSource, bool use64BitSamples=false) noexcept | |
Convenience constructor - use to read samples from audioSource. | |
| HostAudioReader (HostAudioAccessController *audioAccessController, ARAAudioSourceHostRef audioSourceHostRef, bool use64BitSamples=false) noexcept | |
| Primitive constructor - see ARAAudioAccessControllerInterface::createAudioReaderForSource. | |
| bool | readAudioSamples (ARASamplePosition samplePosition, ARASampleCount samplesPerChannel, void *const buffers[]) const 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... | |
|
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::HostArchiveReader |
Utility class that wraps the host ARAArchivingControllerInterface archive reading functions.
Public Member Functions | |
| ARASize | getArchiveSize () const 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 (ARASize position, ARASize length, ARAByte buffer[]) const 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... | |
| 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 () const 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... | |
|
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 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.
| class ARA::PlugIn::HostArchiveWriter |
Utility class that wraps the host ARAArchivingControllerInterface archive writing functions.
Public Member Functions | |
| bool | writeBytesToArchive (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... | |
|
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 |
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::ViewSelection |
Utility class that wraps an ARAViewSelection instance.
Effective Selection Functions | |
These variants interpret the selection and return explicitly or implicitly selected data. For example if a selection is made across region sequences and time range (e.g. marquee tool in Logic, range tool in Studio One) getPlaybackRegions() will return an empty vector, whereas getEffectivePlaybackRegions() returns all regions in those selected sequences which intersect with the given time range. Likewise, if no time range is provided because the selection was made by selecting individual playback regions, the effective time range would be the union of the time range of all regions. Where applicable, use the optional template parameter to cast the returned instances to your custom subclass. | |
| std::vector< PlaybackRegion * > | getEffectivePlaybackRegions () const noexcept |
| Return selected playback regions, or all playback regions in getRegionSequences() (limited to those intersecting getTimeRange() if provided) | |
| template<typename PlaybackRegion_t > | |
| std::vector< PlaybackRegion_t * > | getEffectivePlaybackRegions () const noexcept |
| Return selected playback regions, or all playback regions in getRegionSequences() (limited to those intersecting getTimeRange() if provided) | |
| std::vector< RegionSequence * > | getEffectiveRegionSequences () const noexcept |
| Return the selected region sequences, or the sequences of all regions in getPlaybackRegions() if no sequences are selected. | |
| template<typename RegionSequence_t > | |
| std::vector< RegionSequence_t * > | getEffectiveRegionSequences () const noexcept |
| Return selected playback regions, or all playback regions in getRegionSequences() (limited to those intersecting getTimeRange() if provided) | |
| ARAContentTimeRange | getEffectiveTimeRange () const noexcept |
| Return the host provided time range, or the range enclosing getEffectivePlaybackRegions() if no time range is provided. | |
Selection Queries | |
Where applicable, use the optional template parameter to cast the returned instances to your custom subclass. | |
| template<typename PlaybackRegion_t = PlaybackRegion> | |
| std::vector< PlaybackRegion_t * > const & | getPlaybackRegions () const noexcept |
| Retrieve the current list of selected playback regions. | |
| template<typename RegionSequence_t = RegionSequence> | |
| std::vector< RegionSequence_t * > const & | getRegionSequences () const noexcept |
| Retrieve the current list of selected region sequences. | |
| OptionalProperty< ARAContentTimeRange * > const & | getTimeRange () const noexcept |
| Get the selected time range - may be nullptr if not supported by the host. | |