Utility Classes

Detailed Description

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 Documentation

◆ ARA::PlugIn::OptionalProperty

class ARA::PlugIn::OptionalProperty

template<typename T>
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.

◆ ARA::PlugIn::ContentReader

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.
 

◆ ARA::PlugIn::RestoreObjectsFilter

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
 

◆ ARA::PlugIn::StoreObjectsFilter

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
 

◆ ARA::PlugIn::HostContentReader

class ARA::PlugIn::HostContentReader

template<ARAContentType contentType>
class ARA::PlugIn::HostContentReader< contentType >

Utility class that wraps the host ARAContentAccessControllerInterface.

Template Parameters
contentTypeThe type of ARA content event that can be read.
Inheritance diagram for ARA::PlugIn::HostContentReader< contentType >:
ARA::ContentReader< contentType, ControllerType, ContentReaderRefType, ValidatorClass >

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 >
 

◆ ARA::PlugIn::HostAudioReader

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

Member Function Documentation

◆ readAudioSamples()

bool ARA::PlugIn::HostAudioReader::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.

◆ ARA::PlugIn::HostArchiveReader

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

Member Function Documentation

◆ getArchiveSize()

ARASize ARA::PlugIn::HostArchiveReader::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).

◆ getDocumentArchiveID()

ARAPersistentID ARA::PlugIn::HostArchiveReader::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.

◆ notifyDocumentUnarchivingProgress()

void ARA::PlugIn::HostArchiveReader::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::HostArchiveReader::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.

◆ ARA::PlugIn::HostArchiveWriter

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

Member Function Documentation

◆ notifyDocumentArchivingProgress()

void ARA::PlugIn::HostArchiveWriter::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%.

◆ writeBytesToArchive()

bool ARA::PlugIn::HostArchiveWriter::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.

◆ ARA::PlugIn::ViewSelection

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.