#[repr(C, packed(1))]pub struct ARADocumentControllerInterface {Show 55 fields
pub structSize: ARASize,
pub destroyDocumentController: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef)>,
pub getFactory: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef) -> *const ARAFactory>,
pub beginEditing: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef)>,
pub endEditing: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef)>,
pub notifyModelUpdates: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef)>,
pub beginRestoringDocumentFromArchive: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, archiveReaderHostRef: ARAArchiveReaderHostRef) -> ARABool>,
pub endRestoringDocumentFromArchive: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, archiveReaderHostRef: ARAArchiveReaderHostRef) -> ARABool>,
pub storeDocumentToArchive: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, archiveWriterHostRef: ARAArchiveWriterHostRef) -> ARABool>,
pub updateDocumentProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, properties: *const ARADocumentProperties)>,
pub createMusicalContext: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, hostRef: ARAMusicalContextHostRef, properties: *const ARAMusicalContextProperties) -> ARAMusicalContextRef>,
pub updateMusicalContextProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, musicalContextRef: ARAMusicalContextRef, properties: *const ARAMusicalContextProperties)>,
pub updateMusicalContextContent: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, musicalContextRef: ARAMusicalContextRef, range: *const ARAContentTimeRange, flags: ARAContentUpdateFlags)>,
pub destroyMusicalContext: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, musicalContextRef: ARAMusicalContextRef)>,
pub createAudioSource: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, hostRef: ARAAudioSourceHostRef, properties: *const ARAAudioSourceProperties) -> ARAAudioSourceRef>,
pub updateAudioSourceProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, properties: *const ARAAudioSourceProperties)>,
pub updateAudioSourceContent: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, range: *const ARAContentTimeRange, flags: ARAContentUpdateFlags)>,
pub enableAudioSourceSamplesAccess: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, enable: ARABool)>,
pub deactivateAudioSourceForUndoHistory: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, deactivate: ARABool)>,
pub destroyAudioSource: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef)>,
pub createAudioModification: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, hostRef: ARAAudioModificationHostRef, properties: *const ARAAudioModificationProperties) -> ARAAudioModificationRef>,
pub cloneAudioModification: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, hostRef: ARAAudioModificationHostRef, properties: *const ARAAudioModificationProperties) -> ARAAudioModificationRef>,
pub updateAudioModificationProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, properties: *const ARAAudioModificationProperties)>,
pub deactivateAudioModificationForUndoHistory: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, deactivate: ARABool)>,
pub destroyAudioModification: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef)>,
pub createPlaybackRegion: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, hostRef: ARAPlaybackRegionHostRef, properties: *const ARAPlaybackRegionProperties) -> ARAPlaybackRegionRef>,
pub updatePlaybackRegionProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, playbackRegionRef: ARAPlaybackRegionRef, properties: *const ARAPlaybackRegionProperties)>,
pub destroyPlaybackRegion: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, playbackRegionRef: ARAPlaybackRegionRef)>,
pub isAudioSourceContentAvailable: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, contentType: ARAContentType) -> ARABool>,
pub isAudioSourceContentAnalysisIncomplete: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, contentType: ARAContentType) -> ARABool>,
pub requestAudioSourceContentAnalysis: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, contentTypesCount: ARASize, contentTypes: *const ARAContentType)>,
pub getAudioSourceContentGrade: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, contentType: ARAContentType) -> ARAContentGrade>,
pub createAudioSourceContentReader: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, contentType: ARAContentType, range: *const ARAContentTimeRange) -> ARAContentReaderRef>,
pub isAudioModificationContentAvailable: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, contentType: ARAContentType) -> ARABool>,
pub getAudioModificationContentGrade: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, contentType: ARAContentType) -> ARAContentGrade>,
pub createAudioModificationContentReader: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, contentType: ARAContentType, range: *const ARAContentTimeRange) -> ARAContentReaderRef>,
pub isPlaybackRegionContentAvailable: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, playbackRegionRef: ARAPlaybackRegionRef, contentType: ARAContentType) -> ARABool>,
pub getPlaybackRegionContentGrade: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, playbackRegionRef: ARAPlaybackRegionRef, contentType: ARAContentType) -> ARAContentGrade>,
pub createPlaybackRegionContentReader: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, playbackRegionRef: ARAPlaybackRegionRef, contentType: ARAContentType, range: *const ARAContentTimeRange) -> ARAContentReaderRef>,
pub getContentReaderEventCount: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, contentReaderRef: ARAContentReaderRef) -> ARAInt32>,
pub getContentReaderDataForEvent: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, contentReaderRef: ARAContentReaderRef, eventIndex: ARAInt32) -> *const c_void>,
pub destroyContentReader: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, contentReaderRef: ARAContentReaderRef)>,
pub createRegionSequence: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, hostRef: ARARegionSequenceHostRef, properties: *const ARARegionSequenceProperties) -> ARARegionSequenceRef>,
pub updateRegionSequenceProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, regionSequenceRef: ARARegionSequenceRef, properties: *const ARARegionSequenceProperties)>,
pub destroyRegionSequence: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, regionSequenceRef: ARARegionSequenceRef)>,
pub getPlaybackRegionHeadAndTailTime: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, playbackRegionRef: ARAPlaybackRegionRef, headTime: *mut ARATimeDuration, tailTime: *mut ARATimeDuration)>,
pub restoreObjectsFromArchive: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, archiveReaderHostRef: ARAArchiveReaderHostRef, filter: *const ARARestoreObjectsFilter) -> ARABool>,
pub storeObjectsToArchive: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, archiveWriterHostRef: ARAArchiveWriterHostRef, filter: *const ARAStoreObjectsFilter) -> ARABool>,
pub getProcessingAlgorithmsCount: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef) -> ARAInt32>,
pub getProcessingAlgorithmProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, algorithmIndex: ARAInt32) -> *const ARAProcessingAlgorithmProperties>,
pub getProcessingAlgorithmForAudioSource: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef) -> ARAInt32>,
pub requestProcessingAlgorithmForAudioSource: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, algorithmIndex: ARAInt32)>,
pub isLicensedForCapabilities: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, runModalActivationDialogIfNeeded: ARABool, contentTypesCount: ARASize, contentTypes: *const ARAContentType, transformationFlags: ARAPlaybackTransformationFlags) -> ARABool>,
pub storeAudioSourceToAudioFileChunk: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, archiveWriterHostRef: ARAArchiveWriterHostRef, audioSourceRef: ARAAudioSourceRef, documentArchiveID: *mut ARAPersistentID, openAutomatically: *mut ARABool) -> ARABool>,
pub isAudioModificationPreservingAudioSourceSignal: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef) -> ARABool>,
}Expand description
! Plug-in interface: document controller. ! The function pointers in this struct must remain valid until the document controller is ! destroyed by the host.
Fields§
§structSize: ARASize! @see_Versioned_Structs_
destroyDocumentController: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef)>! Destroy the controller and its associated document. ! The host must delete all objects associated with the document graph (audio sources, ! musical contexts etc.) before making this call. ! Note that the objects exported via the ARAPlugInExtensionInstance are not considered ! part of the document graph, their destruction may happen before or after destroying the ! document controller that they are bound to.
getFactory: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef) -> *const ARAFactory>! Query the static ARA factory that was used to create this controller. ! This provides a convenient traversal to the name of the plug-in, the description of its ! capabilities, its archive IDs etc.
beginEditing: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef)>! Start an editing session on a document. ! An editing session can contain an arbitrary set of modifications that belong together. ! Since many model edits can result in rather expensive updates on the plug-in side, this call ! allows for grouping the edits and postponing the updates until the new model state is final, ! which potentially saves some intermediate updates.
endEditing: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef)>! End an editing session on a document. ! Note that when receiving this call, the plug-in will update any amount of internal state. ! These edits may lead to update notifications to the host, and the host may in turn read ! affected content from the plug-in and update its own model accordingly. ! One example for this the way that Melodyne maintains chords and scales associated with ! audio modifications. It copies this data from the musical context into the audio ! modifications, so that when editing regions the notes appear in the proper pitch grid. ! If moving playback regions in the song, these copies may need to be updated, and Melodyne ! will report the resulting audio modification content changes to the host. ! To ensure that any such follow-up updates are added to the same undo cycle, hosts that ! actively read plug-in content data should immediately (i.e. within the same undo frame) ! call notifyModelUpdates() after making this call.
notifyModelUpdates: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef)>! Tell the plug-in to send all pending update notifications for the given document. ! This must be called periodically by the host whenever not editing nor restoring the document. ! Only when processing this call, the plug-in may call back into the host using ! ARAModelUpdateControllerInterface. ! Hosts must be aware after receiving beginEditing(), plug-ins may choose to postpone any subset ! of their internal state updates until the matching call to endEditing(). This means that if ! the host for some reason needs to wait for a specific update in the plug-in to occur ! (such as waiting for an analysis to finish) it must do so outside of pairs of beginEditing() ! and endEditing().
beginRestoringDocumentFromArchive: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, archiveReaderHostRef: ARAArchiveReaderHostRef) -> ARABool>! Begin an unarchiving session of the document and its associated objects. ! \deprecated ! Since version 2_0_Final this call has been superseded by the combination of beginEditing() ! and restoreObjectsFromArchive(). This allows for optional filtering, but also simplifies ! both host and plug-in implementation.
endRestoringDocumentFromArchive: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, archiveReaderHostRef: ARAArchiveReaderHostRef) -> ARABool>! End an unarchiving session of the document and its associated objects. ! \deprecated ! Since version 2_0_Final this call has been superseded by the combination of endEditing() ! and restoreObjectsFromArchive(). This allows for optional filtering, but also simplifies ! both host and plug-in implementation. ! \br ! When using API generation 1 or older and using this call, the host must pass the same ! archiveReaderHostRef as used for beginRestoringDocumentFromArchive(). ! This way, plug-ins can choose to evaluate the archive upon beginRestoring() or endRestoring(), ! or even upon both calls if needed.
storeDocumentToArchive: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, archiveWriterHostRef: ARAArchiveWriterHostRef) -> ARABool>! Create an archive of the internal state of a given document and all its associated objects. ! \deprecated ! Since version 2_0_Final this call has been superseded by storeObjectsToArchive(), ! which allows for optional filtering, but is otherwise identical.
updateDocumentProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, properties: *const ARADocumentProperties)>! Update the properties of the controller’s document. ! All properties must be specified, the plug-in will determine which have actually changed.
createMusicalContext: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, hostRef: ARAMusicalContextHostRef, properties: *const ARAMusicalContextProperties) -> ARAMusicalContextRef>! Create a new musical context associated with the controller’s document.
updateMusicalContextProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, musicalContextRef: ARAMusicalContextRef, properties: *const ARAMusicalContextProperties)>! Update the properties of a given musical context. ! All properties must be specified, the plug-in will determine which have actually changed.
updateMusicalContextContent: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, musicalContextRef: ARAMusicalContextRef, range: *const ARAContentTimeRange, flags: ARAContentUpdateFlags)>! Tell the plug-in to update the information obtainable via content readers for a given musical context. ! The time range may be NULL, this means that the entire musical content is affected. ! Creating a new musical context implies an initial content update for it - the host will ! call this explicitly only for later content updates.
destroyMusicalContext: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, musicalContextRef: ARAMusicalContextRef)>! Destroy a given musical context. ! Destroying a musical context also implies removing it from its document. ! The musical context must no longer be referred to by any playback region when making this call.
createAudioSource: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, hostRef: ARAAudioSourceHostRef, properties: *const ARAAudioSourceProperties) -> ARAAudioSourceRef>! Create a new audio source associated with the controller’s document. ! The newly created audio source has its sample data access initially disabled, ! an explicit call to enableAudioSourceSamplesAccess() is needed.
updateAudioSourceProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, properties: *const ARAAudioSourceProperties)>! Update the properties of a given audio source. ! Depending on which properties are changed (see documentation of ARAAudioSourceProperties), ! the host may not be able to make this call while the plug-in is reading data - ! in that case, use enableAudioSourceSamplesAccess() accordingly. ! All properties must be specified, the plug-in will determine which have actually changed.
updateAudioSourceContent: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, range: *const ARAContentTimeRange, flags: ARAContentUpdateFlags)>! Tell the plug-in that the sample data or content information for the given audio source has changed. ! Not to be called in response to ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged(). ! The time range may be NULL, this means that the entire audio source is affected. ! When implementing this call, remember to also flush any caches of the sampled data if needed ! (see ::kARAContentUpdateSignalScopeRemainsUnchanged). ! Creating a new audio source always implies an initial content update for it, i.e. the host ! will call this function only for later content updates. Since audio sources are persistent, ! plug-ins should preferably postpone the initial content reading until endEditing() - ! if the host is restoring the audio source, this will remove the need to read initial content.
enableAudioSourceSamplesAccess: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, enable: ARABool)>! Enable or disable access to a given audio source. ! This call allows the host to control the time when the plug-in may access sample data from ! the given audio source. Disabling access forces the plug-in to destroy all audio readers ! it currently has created for the affected audio source. This is a synchronous call, ! blocking until all currently executing reads of the audio source are finished. ! Access is disabled by default, hosts must explicitly enable it after creating an audio source. ! Since this call does not modify the model graph, it may be called outside the usual ! beginEditing() and endEditing() scope. ! Note that disabling access will also abort any analysis currently being executed for the ! audio source, making it necessary to start it from scratch when the access is enabled again. ! This means that enableAudioSourceSamplesAccess() is an expensive call that only should be ! made when necessary. It should not be (ab-)used to simply “pause ARA” whenever convenient.
deactivateAudioSourceForUndoHistory: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, deactivate: ARABool)>! Deactivate the given audio source because it has become part of the undo history ! and is no longer used actively. ! The plug-in will cancel any pending analysis for this audio source and may free memory ! that is only needed when the audio source can be edited or rendered. ! Before deactivating an audio source, the host must deactivate all associated audio ! modifications, and the opposite order is required when re-activating upon redo. ! When deactivated, updating the properties or content of the audio source or reading its ! content is no longer valid. ! Like properties, deactivation is not necessarily persistent in the plug-in, so the host must ! call this explicitly when restoring deactivated audio sources. ! Note that with the introduction of partial persistency with ARA 2.0, hosts likely will prefer ! to simply create partial archives of deleted audio sources and manage these in their undo ! history rather than utilizing this call.
destroyAudioSource: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef)>! Destroy a given audio source. ! Destroying an audio source also implies removing it from its document. ! The host must delete all objects associated with the audio source (audio modifications etc.) ! before deleting the audio source. ! The host does not need to explicitly disable access to the audio source before making this call.
createAudioModification: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, hostRef: ARAAudioModificationHostRef, properties: *const ARAAudioModificationProperties) -> ARAAudioModificationRef>! Create a new audio modification associated with the given audio source.
cloneAudioModification: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, hostRef: ARAAudioModificationHostRef, properties: *const ARAAudioModificationProperties) -> ARAAudioModificationRef>! Create a new audio modification which copies the state of another given audio modification. ! The new modification will be associated with the same audio source. ! This call is used to create independent variations of the audio edits as opposed to creating ! aliases by merely adding playback regions to a given audio modification. ! Note that with the introduction of partial persistency with ARA 2.0, hosts can achieve the ! same effect by creating an archive of the modification that should be cloned and unarchiving ! that state into a new modification.
updateAudioModificationProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, properties: *const ARAAudioModificationProperties)>! Update the properties of a given audio modification. ! All properties must be specified, the plug-in will determine which have actually changed.
deactivateAudioModificationForUndoHistory: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, deactivate: ARABool)>! Deactivate the given audio modification because it has become part of the undo history ! and is no longer used actively. ! The plug-in may free some memory that is only needed when the audio modification can be ! edited or rendered. ! Before deactivating an audio modification, the host must destroy all associated playback ! regions, and the opposite order is required when re-activating upon redo. ! When deactivated, updating the properties of the audio modification or reading its ! content is no longer valid. ! Like properties, deactivation is not necessarily persistent in the plug-in, so the host must ! call this explicitly when restoring deactivated audio modifications. ! Note that with the introduction of partial persistency with ARA 2.0, hosts likely will prefer ! to simply create partial archives of deleted audio modifications and manage these in their undo ! history rather than utilizing this call.
destroyAudioModification: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef)>! Destroy a given audio modification. ! Destroying an audio modification also implies removing it from its audio source. ! The host must delete all objects associated with the audio modification (playback regions etc.) ! before deleting the audio modification.
createPlaybackRegion: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, hostRef: ARAPlaybackRegionHostRef, properties: *const ARAPlaybackRegionProperties) -> ARAPlaybackRegionRef>! Create a new playback region associated with the given audio modification.
updatePlaybackRegionProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, playbackRegionRef: ARAPlaybackRegionRef, properties: *const ARAPlaybackRegionProperties)>! Update the properties of a given playback region. ! All properties must be specified, the plug-in will determine which have actually changed.
destroyPlaybackRegion: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, playbackRegionRef: ARAPlaybackRegionRef)>! Destroy a given playback region. ! Destroying a playback region also implies removing it from its audio modification. ! The playback region must no longer be referred to by any plug-in extension when making this call.
isAudioSourceContentAvailable: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, contentType: ARAContentType) -> ARABool>! Query whether the given content type is currently available for the given audio source.
isAudioSourceContentAnalysisIncomplete: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, contentType: ARAContentType) -> ARABool>! Query whether an analysis of the given content type has been done for the given audio source. ! This call will typically be used when the host uses the plug-in as a detection engine in the ! background (i.e. without presenting the UI to the user). In that scenario, the host will ! trigger the analysis of the desired content types using requestAudioSourceContentAnalysis() ! and then wait until the plug-in calls ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged(). ! From that call, the host will query the plug-in via isAudioSourceContentAnalysisIncomplete() ! to determine which of the analysis requests have completed. ! If the host did request a specific algorithm to be used, then the plug-in should return ! kARATrue here until the request was satisfied (or rejected).
requestAudioSourceContentAnalysis: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, contentTypesCount: ARASize, contentTypes: *const ARAContentType)>! Explicitly trigger a certain analysis. ! If the host wants to use the plug-in as detection engine, it needs to explicitly trigger the ! desired analysis, since otherwise the plug-in may postpone any analysis as suitable. ! To allow for optimizing the analysis on the plug-in side, all content types that are of ! interest for the host should be specified in a single call if possible. ! \br ! Note that the plug-in may choose to perform any additional analysis at any point in time ! if this is appropriate for its design. It will call ! ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged() if such an analysis ! concludes successfully so that the host can update accordingly. ! \br ! The provided content types must be a non-empty subset of the plug-in’s ! ARAFactory::analyzeableContentTypes. To request all analysis types exported by the plug-in, ! hosts can directly pass analyzeableContentTypes and -Count from the plug-in’s ARAFactory. ! The contentTypes pointer may be only valid for the duration of the call, it must be ! evaluated inside the call, and the pointer must not be stored anywhere. ! \br ! Note that ARA 2.0 adds the capability for the host to also request the use of a certain ! processing algorithm via requestProcessingAlgorithmForAudioSource() - if both are used then ! the algorithm must be selected before requesting the analysis.
getAudioSourceContentGrade: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, contentType: ARAContentType) -> ARAContentGrade>! Query the current quality of the information provided for the given audio source and content type.
createAudioSourceContentReader: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, contentType: ARAContentType, range: *const ARAContentTimeRange) -> ARAContentReaderRef>! 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 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.
isAudioModificationContentAvailable: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, contentType: ARAContentType) -> ARABool>! Query whether the given content type is currently available for the given audio modification. ! Note that since ARA 2.0, reading at playback region level is recommended for most content types, ! see createAudioModificationContentReader().
getAudioModificationContentGrade: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, contentType: ARAContentType) -> ARAContentGrade>! Query the current quality of the information provided for a given audio modification and content type. ! Note that since ARA 2.0, reading at playback region level is recommended for most content types, ! see createAudioModificationContentReader().
createAudioModificationContentReader: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef, contentType: ARAContentType, range: *const ARAContentTimeRange) -> ARAContentReaderRef>! Create a content reader for the given audio modification and content type. ! This should only be called after availability has been confirmed using isAudioModificationContentAvailable(). ! The time range may be NULL, which means that the entire audio modification shall be read. ! If a time range is specified, all events that at least partially intersect with the range ! will be read. ! Note that with the introduction of region transitions in ARA 2.0, the content of a given ! playback region can no longer be externally calculated by the host based on the content of ! its underlying audio modification and the transformation flags. Instead, hosts should read ! such content directly at region level. This particularly applies to kARAContentTypeNotes - ! notes at borders will be adjusted on a per-region basis when using content based fades. ! Playback region content reading is available in ARA 1.0 already, thus such an implementation ! will be fully backwards compatible. ! Reading content at audio modification (or audio source) level is still valid and useful if ! the host needs access to the content in its original state, not transformed by a playback ! region, e.g. when implementing features such as tempo and signature detection through ARA.
isPlaybackRegionContentAvailable: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, playbackRegionRef: ARAPlaybackRegionRef, contentType: ARAContentType) -> ARABool>! Query whether the given content type is currently available for the given playback region.
getPlaybackRegionContentGrade: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, playbackRegionRef: ARAPlaybackRegionRef, contentType: ARAContentType) -> ARAContentGrade>! Query the current quality of the information provided for the given playback region and content type.
createPlaybackRegionContentReader: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, playbackRegionRef: ARAPlaybackRegionRef, contentType: ARAContentType, range: *const ARAContentTimeRange) -> ARAContentReaderRef>! Create a content reader for the given playback region and content type. ! This should only be called after availability has been confirmed using isPlaybackRegionContentAvailable(). ! The time range may be NULL, which means that the entire playback region shall be read, ! including its potential head and tail time. ! If a time range is specified, all events that at least partially intersect with the range ! will be read. ! The time range must be given in playback time, and the time stamps provided by the content ! reader are in playback time as well.
getContentReaderEventCount: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, contentReaderRef: ARAContentReaderRef) -> ARAInt32>! Query how many events the given reader exposes.
getContentReaderDataForEvent: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, contentReaderRef: ARAContentReaderRef, eventIndex: ARAInt32) -> *const c_void>! Query data of the given event of the given reader. ! The returned pointer is owned by the plug-in and must remain valid until either ! getContentReaderDataForEvent() is called again or the content reader is destroyed.
destroyContentReader: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, contentReaderRef: ARAContentReaderRef)>! Destroy the given content reader.
createRegionSequence: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, hostRef: ARARegionSequenceHostRef, properties: *const ARARegionSequenceProperties) -> ARARegionSequenceRef>! Create a new region sequence associated with the controller’s document.
updateRegionSequenceProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, regionSequenceRef: ARARegionSequenceRef, properties: *const ARARegionSequenceProperties)>! Update the properties of a given region sequence. ! All properties must be specified, the plug-in will determine which have actually changed.
destroyRegionSequence: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, regionSequenceRef: ARARegionSequenceRef)>! Destroy a given region sequence. ! The region sequence must no longer be referred to by any playback region when making this call.
getPlaybackRegionHeadAndTailTime: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, playbackRegionRef: ARAPlaybackRegionRef, headTime: *mut ARATimeDuration, tailTime: *mut ARATimeDuration)>! Query the current head and tail time of a given playback region. ! Note that when a plug-in optimizes region transitions, the head and tail of any given ! region can change upon any model edit, even if it is not directly affected by the edit. ! Also, in order to properly track interaction between regions, plug-ins may lazily update ! this information upon endEditing(). Plug-ins will call notifyPlaybackRegionContentChanged() ! whenever these values change. ! headTime and tailTime must not be NULL. ! Host may query this often, so plug-ins should cache the value if there’s any expensive ! calculation involved. ! Note that most companion APIs also feature a tail time concept. For playback renderer plug-in ! instances, the tail time reported via the companion API should be equal to or greater than ! the maximum of the tail times of all playback regions currently associated with the given ! renderer (i.e. the tail for any given playback region may be somewhat shorter then the ! companion API tail, depending on the region’s content).
restoreObjectsFromArchive: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, archiveReaderHostRef: ARAArchiveReaderHostRef, filter: *const ARARestoreObjectsFilter) -> ARABool>! Unarchive the internal state of the specified objects. ! This call can be used both for unarchiving entire documents and for importing arbitrary ! objects into an existing document. ! An unarchiving session is conceptually identical to an editing session: after starting the ! session, the host rebuilds the graph using the regular object creation calls, then makes ! this call to let the plug-in parse the archive and inject the archived internal state into ! the graph as indicated by the persistentIDs of the relevant objects. ! Similarly, when importing objects, the host will perform an editing session and either create ! new objects or re-use existing objects (potentially adjusting their persistentID), then ! make this call to inject the imported state. ! \br ! The optional filter allows for restoring only a subset of the archived states into the graph. ! It can be NULL, in which case all archived states with matching persistentIDs will be restored. ! In that case, the call sequence beginEditing(), restoreObjectsFromArchive(), endEditing() ! is equivalent to the deprecated begin-/endRestoringDocumentFromArchive() for ARA 1, which ! has been superseded by this call. ! The host is not required to restore all objects in the archive. Any archived states that are ! either filtered explicitly, or for which there is no object with a matching persistent ID in ! the current graph are simply ignored. ! Since persistent IDs are only required to be unique per document (and not globally), hosts ! may encounter persistent ID conflicts when importing data from other documents. ! The optional ARARestoreObjectsFilter provided for this call therefore allows to map between ! the IDs used in the archive and those used in the current graph if needed. ! \br ! The host can make multiple calls to restoreObjectsFromArchive() within the same editing ! session to import objects from multiple archives in one operation. It may even decide ! to implement its persistency based on partial archives entirely, using several calls to ! storeObjectsToArchive() with varying filters to split the document into slices appropriate ! to its implementation, see ARAStoreObjectsFilter::documentData. ! \br ! Result is kARAFalse if the access to the archive reader failed while trying to read the ! archive, or if decoding the data failed, kARATrue otherwise. Potential reason for failure ! include data corruption due to storage hardware failures, or broken dependencies when ! restoring partial archives as discussed above. The plug-in should try to recover as much ! state as possible in all cases, and the host should notify the user of such errors. ! If a failure happened already while reading the archive, the host is aware of this and can ! augment its error message to the user accordingly. If the failure happens inside the plug-in ! when decoding the data, the plug-in is responsible for guiding the user as good as possible, ! e.g. by listing or marking the affected objects. ! Note that since versioning is expressed through the ARA factory, the host must deal with ! potential versioning conflicts before making this call, and provide proper UI too.
storeObjectsToArchive: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, archiveWriterHostRef: ARAArchiveWriterHostRef, filter: *const ARAStoreObjectsFilter) -> ARABool>! Create a partial archive of the internal state of the specified objects. ! Archives may only be created from documents that are not being currently edited. ! The optional filter allows for storing only a subset of the document graph into the archive. ! It can be NULL, in which case all objects in the graph will be stored. ! In that case, the call is equivalent to the deprecated storeDocumentToArchive(), ! which has been superseded by this call. ! Result is kARAFalse if the access to the archive writer failed while trying to write the ! archive, kARATrue otherwise. ! The host is responsible for alerting the user about archive write errors, ! see ARAArchivingControllerInterface::writeBytesToArchive(). ! Note that for creating ARA audio file chunk archives, storeAudioSourceToAudioFileChunk() ! must be used instead, so that the plug-in can pick the correct encoding and return the ! corresponding (compatible) document archive ID.
getProcessingAlgorithmsCount: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef) -> ARAInt32>! Return the count of processing algorithms provided by the plug-in. ! If this optional method is not implemented or the call returns 0, then the plug-in does not support ! algorithm selection through the host and the other related functions below must not be called.
getProcessingAlgorithmProperties: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, algorithmIndex: ARAInt32) -> *const ARAProcessingAlgorithmProperties>! List of processing algorithms provided by the plug-in, described by their properties. ! This method must be implemented if getProcessingAlgorithmsCount() is implemented. ! Provides a unique identifier and a user-readable name of the algorithm as displayed in the plug-in. ! The host should present the algorithms to the user in the order of this list, e.g. in a menu. ! For a given version of the plug-in, the count and the order and values of the persistentIDs ! must be the same, while the names may depend on localization settings that can be different ! on different machines or between individual runs of the host. ! The list may however change between different versions of the plug-in. ! Both hosts and plug-ins must implement fallbacks for loading a document that contains an ! processing algorithm persistentID which is no longer supported by the plug-in. ! The pointers returned by this calls must remain valid until the document controller ! is destroyed.
getProcessingAlgorithmForAudioSource: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef) -> ARAInt32>! Query currently used processing algorithm for a given audio source. ! This method must be implemented if getProcessingAlgorithmsCount() is implemented. ! After the plug-in has concluded an analysis (as indicated via ! ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged()), ! the host can query which processing algorithm was used and update its UI accordingly. ! This is particularly relevant if the host did explicitly request an analysis with a ! specific algorithm, but the plug-in was unable to satisfy this request for some reason. ! Similarly, the user may have changed the algorithm through the plug-in’s UI. ! Note that until the first analysis has completed (i.e. as long as ! isAudioSourceContentAnalysisIncomplete() returns kARATrue), the value returned here may be ! an abstract default, not related to the actual audio source content. This will e.g. typically ! be the case in Melodyne, which uses an “automatic mode” as default until the first analysis ! has determined the actual processing algorithm that is suitable for the material. ! The call should not be made while isAudioSourceContentAnalysisIncomplete() returns kARATrue, ! because the returned value is likely stale.
requestProcessingAlgorithmForAudioSource: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioSourceRef: ARAAudioSourceRef, algorithmIndex: ARAInt32)>! Request that any future analysis of the given audio source should use the given processing algorithm. ! This method must be implemented if getProcessingAlgorithmsCount() is implemented. ! This both affects any analysis requested by the host via requestAudioSourceContentAnalysis() ! as well as any analysis done by the plug-in on demand. ! Since this typically results in a model graph edit, calling this functions must be guarded ! by beginEditing() and endEditing(). ! Note that the plug-in is not required to heed this request if its internal state suggest ! otherwise, or if the user switches actively to a different algorithm. ! Also, some algorithms may be “meta” algorithms that will be replaced by a different actual ! algorithm, such as the “automatic” default algorithm in Melodyne which will pick an ! appropriate algorithm from the remaining list of algorithms when doing the initial analysis.
isLicensedForCapabilities: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, runModalActivationDialogIfNeeded: ARABool, contentTypesCount: ARASize, contentTypes: *const ARAContentType, transformationFlags: ARAPlaybackTransformationFlags) -> ARABool>! With this optional call, hosts can test whether the current license state of the plug-in allows ! for requesting analysis of the given content types and rendering the given playback transformations ! (see requestAudioSourceContentAnalysis() and ARAPlaybackRegionProperties::transformationFlags). ! The host can also optionally instruct the plug-in to run a modal licensing dialog if the current ! license is not sufficient to perform the selected engine tasks, so that the user can review and ! adjust the licensing accordingly, such downloading a license from their respective user account ! or even purchase an upgrade that enables the requested features. ! \br ! The provided content types must be a subset of the plug-in’s ARAFactory::analyzeableContentTypes. ! To request all analysis types exported by the plug-in, hosts can directly pass ! analyzeableContentTypes and -Count from the ARAFactory. ! The contentTypes pointer may be only valid for the duration of the call, it must be evaluated ! inside the call, and the pointer must not be stored anywhere. ! If not intending to use analysis, the count should be 0 and the array pointer NULL. ! The transformationFlags must be a subset of the plug-in’s ARAFactory::supportedPlaybackTransformationFlags, ! and may be kARAPlaybackTransformationNoChanges if not intending to use transformations. ! The call returns kARATrue if the (potentially updated) license is sufficient to perform the ! requested tasks.
storeAudioSourceToAudioFileChunk: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, archiveWriterHostRef: ARAArchiveWriterHostRef, audioSourceRef: ARAAudioSourceRef, documentArchiveID: *mut ARAPersistentID, openAutomatically: *mut ARABool) -> ARABool>! Create an archive of the internal state of the specified audio source suitable to be ! embedded into the underlying audio file as ARA audio file chunks, see @ref ARAAudioFileChunks. ! Hosts must check ARAFactory::supportsStoringAudioFileChunks before enabling users to store ! audio file chunks for the given plug-in. ! Archives may only be created from documents that are not being currently edited. ! \br ! This call differs from using storeObjectsToArchive() with an ARAStoreObjectsFilter in that ! the plug-in may choose a different internal encoding more suitable for this use case, ! indicated by returning a \p documentArchiveID that is likely one of the ! ARAFactory::compatibleDocumentArchiveIDs rather than the ARAFactory::documentArchiveID. ! The plug-in also returns whether openAutomatically should be set in the audio file chunk. ! Result is kARAFalse if the access to the archive writer failed while trying to write the ! archive, kARATrue otherwise. ! The host is responsible for alerting the user about archive write errors, ! see ARAArchivingControllerInterface::writeBytesToArchive().
isAudioModificationPreservingAudioSourceSignal: Option<unsafe extern "C" fn(controllerRef: ARADocumentControllerRef, audioModificationRef: ARAAudioModificationRef) -> ARABool>! Some hosts such as Pro Tools provide indicators whether a given plug-in’s current ! settings cause it to alter the sound of the original audio source, or preserve it so that ! bypassing/removing the plug-in would not change the perceived audible result (note that ! actual rendering involves using a playback region, which still may apply time-stretching ! or pitch-shifting to the audio modification’s potentially unaltered output). ! \br ! Changes to this state are tracked via ARAModelUpdateControllerInterface::notifyAudioModificationContentChanged() ! with ::kARAContentUpdateSignalScopeRemainsUnchanged == false. Note that it is possible to ! perform other edits such as reassigning the chords associated with the audio modification ! which would not affect this state. ! \br ! It is valid for plug-in implementations to deliver false negatives here to reasonably ! limit the cost of maintaining the state. For example, if the plug-in does some ! threshold-based processing, but the signal happens to never actually reach the threshold, ! the plug-in still may report to alter the sound. ! Another example is pitch&time editing in a Melodyne-like plug-in: if notes are moved to a ! different pitch or time position so that this flag is cleared, but later the user manually ! moves them back to the original location, this might not cause this flag to turn back on. ! If however the user invokes undo, or some explicit reset command instead of the manual ! adjustment, then the plug-in should maintain this state properly.
Trait Implementations§
Source§impl Clone for ARADocumentControllerInterface
impl Clone for ARADocumentControllerInterface
Source§fn clone(&self) -> ARADocumentControllerInterface
fn clone(&self) -> ARADocumentControllerInterface
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more