Subpages | |
| Audio Access Controller | |
| This interface allows plug-ins to read the audio data from the host in a random access order. It is used from multiple threads, both host and plug-in need to carefully observe the threading rules for each function. The basic design idea is that each audio reader is used single-threaded, but multiple audio readers can work concurrently (even on the same audio source). Audio readers can be considered random access iterators, and like most iterators operate on conceptually constant data structures. If the host changes sample rate, channel count or other audio source properties that the reader relies upon, the plug-in must discard any existing audio readers for the source and later re-create them based on the new configuration. The host can temporarily disable access to the audio source in order to control the exact timing of stopping the readers from accessing the source. Whenever an audio reader is destroyed, the plug-in is responsible for thread safety - it may need to block until a concurrent read operation on the I/O thread has finished. Hosts must take care in their audio reader implementation to avoid potential deadlocks in this situation. Note that when rendering, the audio source will often not be read in a consecutive order - depending on the edits the user applied at audio modification level, the access may jump back and forth quite often. The reader implementation should be optimized accordingly. Host developer using C++ ARA Library can implement the ARA::Host::AudioAccessControllerInterface. For plug-in developers this interface is wrapped by the ARA::PlugIn::HostAudioAccessController. | |
| Archiving Controller | |
| This interface allows plug-ins to read and write archives with minimal memory impact. It also allows for displaying progress when archiving or unarchiving model graphs. Its functions may only be called during the archiving/unarchiving process. Because of the potentially large size of the archives, ARA does not use simple monolithic memory blocks as known from many companion APIs. Instead, it establishes a stream-like archive format so that copying large blocks of memory can be avoided. Plug-ins that create large archives should use any mean of data reduction that is appropriate to reduce the archive size. For example, they may implement gzip compression. Since it has good knowledge of the characteristics of the data, it can configure the compression algorithms so that optimal results are achieved. Consequently, there's no point for host to try to compress the data any further with generic algorithms. Hosts that support both 32 and 64 bit architectures shall be aware of the fact that ARA archive sizes are pointer-sized data types, so they will differ in bit width between these architectures. This must be taken into account when storing the archive size in the host's document structure. Also, when importing documents from 64 bit into 32 bit, the host must check whether the archive is small enough to be loaded at all (i.e. its size fits into 32 bits). If not, it shall refuse to load the archive and provide a proper error message. This may seem like a restriction, but the reasoning behind this is that if the archive already exceeds the available address space, the resulting unarchived graph will do so too. There's no creation or destruction call for the archive readers/writers because they are provided by the host for the duration of the (un-)archiving process, so the lifetime is implicitly defined. When using API generation 1 or older and loading an archive through the deprecated functions begin-/endRestoringDocumentFromArchive(), plug-ins may choose to access the associated archive reader upon either begin- or endRestoringDocumentFromArchive() or even upon both calls, as suitable for their implementation - hosts must be able to provide the requested data during the duration of both calls. Host developer using C++ ARA Library can implement the ARA::Host::ArchivingControllerInterface. For plug-in developers this interface is wrapped by the ARA::PlugIn::HostArchivingController. | |
| Model Content Access Controller | |
| This optional interface provides access to host model data such as the musical context. Its functions may only be called from ARADocumentControllerInterface.create...() or update...() for the object currently created/updated, or from ARADocumentControllerInterface::endEditing() for any object. Host developer using C++ ARA Library can implement the ARA::Host::ContentAccessControllerInterface. For plug-in developers this interface is wrapped by the ARA::PlugIn::HostContentAccessController. | |
| Model Update Controller Interface | |
| This optional host interface allows the host to be notified about content changes in the plug-in. Its functions may only be called from ARADocumentControllerInterface::notifyModelUpdates(). Host developer using C++ ARA Library can implement the ARA::Host::ModelUpdateControllerInterface. For plug-in developers this interface is wrapped by the ARA::PlugIn::HostModelUpdateController. | |
| Playback Controller Interface | |
| This optional host interface allows the plug-in to request playback state changes. The functions in this interface may be called concurrently, but not from render-threads. The host may choose to ignore any of these requests. The requests will typically be scheduled and executed with some delay. The current state of playback is transmitted via the companion API. Host developer using C++ ARA Library can implement the ARA::Host::PlaybackControllerInterface. For plug-in developers this interface is wrapped by the ARA::PlugIn::HostPlaybackController. | |
| Document Controller Instance | |
| The callbacks into the host are published by the host when creating a document controller on the plug-in side to maintain an ARA model graph. The instance struct and all interfaces and host refs therein must remain valid until the document controller is destroyed. The host can choose to create its controller objects per document controller instance, or it can share a single instance between all document controllers, whatever fits its needs. It may even mix-and-match both approaches per individual interface. | |