Struct PluginInstance 

pub struct PluginInstance<H: HostHandlers> { /* private fields */ }

A plugin instance.

This type is generic over H, the type of the host callback handlers, which the plugin can call use directly when its own methods are called by the host.

Implementations

impl<H: HostHandlers> PluginInstance<H>

pub fn new<FS, FH>( shared: FS, main_thread: FH, entry: &PluginEntry, plugin_id: &CStr, host: &HostInfo, ) -> Result<Self, PluginInstanceError>

where FS: for<'b> FnOnce(&'b ()) -> <H as HostHandlers>::Shared<'b>, FH: for<'b> FnOnce(&'b <H as HostHandlers>::Shared<'b>) -> <H as HostHandlers>::MainThread<'b>,

Creates a new plugin instance from a given PluginEntry.

The specific plugin to be instantiated is identified by the given plugin_id.

This method takes two closures, here named FS and FH, which will respectively create the Shared and MainThread callback handler instances associated with this plugin instance.

The MainThread-producing callback takes a long-lived reference to its Shared counterpart, so that it can be accessed at any time from the main thread if needed.

The Shared-producing callback takes a unit reference &(). It is not used for anything, but is necessary for proper lifetime binding.

This method also takes a reference to a HostInfo, giving the plugin some metadata about the host itself.

Errors

If for some reason the given PluginEntry does not expose a PluginFactory, then this will return PluginInstanceError::MissingPluginFactory.

If the PluginFactory’s create_plugin function pointer is NULL, this will return PluginInstanceError::NullFactoryCreatePluginFunction.

If the given plugin_id does not exist, or if more generally the PluginFactory’s create_plugin function returned NULL, then this will return PluginInstanceError::PluginNotFound.

Otherwise, if the plugin instantiation implementation failed, it will return PluginInstanceError::InstantiationFailed.

Example

use clack_host::prelude::*;

struct MyHost;

struct MyHostMainThread { /* ... */ }

impl HostHandlers for MyHost {
    type Shared<'a> = /* ... */
    type AudioProcessor<'a> = /* ... */
    type MainThread<'a> = MyHostMainThread;
}

impl<'a> MainThreadHandler<'a> for MyHostMainThread {
    fn initialized(&self, instance: InitializedPluginHandle<'a>) {
        // Called whn the plugin has been fully initialized.
    }
}


let entry = /* ... */
let host_info = HostInfo::new("Foo DAW", "Foo Inc.", "https://example.com", "0.0.1").unwrap();

let instance = PluginInstance::<MyHost>::new(
    |_|(),
    |_| MyHostMainThread {},
    &entry,
    c"com.audio.the-plugin",
    &host_info
);

pub fn activate<FA>( &mut self, audio_processor: FA, configuration: PluginAudioConfiguration, ) -> Result<StoppedPluginAudioProcessor<H>, PluginInstanceError>

where FA: for<'a> FnOnce(&'a <H as HostHandlers>::Shared<'a>, &<H as HostHandlers>::MainThread<'a>) -> <H as HostHandlers>::AudioProcessor<'a>,

Activates the plugin instance, preparing it to process audio and events according to the given PluginAudioConfiguration.

This method takes a closure FA, which will create the AudioProcessor callback handler instance associated with this plugin instance.

This closure takes a long-lived reference to the Shared handler so that it can be accessed at any time from the audio thread / audio-processing context if needed.

This closure also provides a temporary, exclusive reference to the MainThread handler.

Errors

This will return PluginInstanceError::AlreadyActivatedPlugin if the plugin has already been activated.

If the plugin instance’s activate function pointer is NULL, this will return PluginInstanceError::NullActivateFunction.

Otherwise, if the plugin instance’s activate function implementation failed for any reason, this will return PluginInstanceError::ActivationFailed.

Panics

This function will panic if either min_frames_count or max_frames_count is 0, or if min_frames_count is greater than max_frames_count.

pub fn deactivate(&mut self, processor: StoppedPluginAudioProcessor<H>)

De-activates the plugin instance, freeing its processing-related resources, and allows it to be re-activated with a different audio configuration.

This consumes the StoppedPluginAudioProcessor handle created by activate, in order to ensure it cannot be used anymore.

For a version of this method that does not require the StoppedPluginAudioProcessor handle, see try_deactivate.

Panics

This will panic if the provided processor handle did not come from this plugin instance.

pub fn try_deactivate(&mut self) -> Result<(), PluginInstanceError>

Attempts to de-activate a plugin instance, which PluginAudioProcessor handle has been dropped.

This is an alternative to deactivate which does not require the associated PluginAudioProcessorHandle to be passed. However, this method is fallible, and will return an error if the PluginAudioProcessorHandle has not been dropped.

This may be useful if it is more practical for you to drop the PluginAudioProcessorHandle (e.g. in another thread) compared to sending it back to the main thread to use with deactivate.

However, if you can easily access or retrieve PluginAudioProcessorHandle back to the main thread, you should use deactivate instead.

Errors

This method will return PluginInstanceError::StillActivatedPlugin if the associated PluginAudioProcessorHandle has not been dropped.

pub fn deactivate_with<T, D>( &mut self, processor: StoppedPluginAudioProcessor<H>, drop_with: D, ) -> T

where D: for<'s> FnOnce(<H as HostHandlers>::AudioProcessor<'s>, &<H as HostHandlers>::MainThread<'s>) -> T,

De-activates the plugin instance, freeing its processing-related resources, and allows it to be re-activated with a different audio configuration.

This consumes the StoppedPluginAudioProcessor handle created by activate, in order to ensure it cannot be used anymore.

This is equivalent to Self::deactivate, except this method also takes a closure type D, which allows to customize the destruction process of the AudioProcessor callback handler instance that was created during activate.

This may be useful to e.g. reuse or reprocess components or allocations the AudioProcessor callback handler instance owned, either by giving it to the MainThread handler (which is also provided by a temporary, exclusive reference), or by returning it.

This function will return whatever the destructor closure returned.

Panics

This will panic if the provided processor handle did not come from this plugin instance.

pub fn try_deactivate_with<T, D>( &mut self, drop_with: D, ) -> Result<T, PluginInstanceError>

where D: for<'s> FnOnce(<H as HostHandlers>::AudioProcessor<'s>, &<H as HostHandlers>::MainThread<'s>) -> T,

Attempts to de-activate a plugin instance, which PluginAudioProcessor handle has been dropped.

This is equivalent to Self::try_deactivate, except this method also takes a closure type D, which allows to customize the destruction process of the AudioProcessor callback handler instance that was created during activate.

This is an alternative to deactivate_with which does not require the associated PluginAudioProcessorHandle to be passed. However, this method is fallible, and will return an error if the PluginAudioProcessorHandle has not been dropped.

This may be useful if it is more practical for you to drop the PluginAudioProcessorHandle (e.g. in another thread) compared to sending it back to the main thread to use with deactivate_with.

However, if you can easily access or retrieve PluginAudioProcessorHandle back to the main thread, you should use deactivate_with instead.

Errors

This method will return PluginInstanceError::StillActivatedPlugin if the associated PluginAudioProcessorHandle has not been dropped.

pub fn call_on_main_thread_callback(&mut self)

Calls the plugin’s on_main_thread callback.

This is usually done in response to the plugin calling SharedHandler::request_callback earlier from a different thread, allowing it to “wake up” its main thread after e.g. another of the plugin’s threads sent a message to it.

pub fn raw_instance(&self) -> &clap_plugin

Returns a shared, read-only reference to the raw, C-FFI compatible representation of thsi plugin instance.

pub fn entry(&self) -> &PluginEntry

Returns the PluginEntry this plugin instance was loaded from.

pub fn is_active(&self) -> bool

Returns true if the current plugin instance has been activated.

pub fn access_shared_handler<'s, R>( &'s self, access: impl for<'a> FnOnce(&'s <H as HostHandlers>::Shared<'a>) -> R, ) -> R

Access the SharedHandler instance associated to this plugin instance using the given callback.

The callback’s return value R is returned directly by this method.

Accessing the HostHandlers types can only be done with accessor callbacks because this type is self-referential: both the HostHandlers and the plugin’s instance data hold references to each other, and both are owned by this type.

pub fn access_handler<R>( &self, access: impl for<'a> FnOnce(&<H as HostHandlers>::MainThread<'a>) -> R, ) -> R

Access a shared reference to MainThreadHandler instance associated to this plugin instance using the given callback.

The callback’s return value R is returned directly by this method.

Accessing the HostHandlers types can only be done with accessor callbacks because this type is self-referential: both the HostHandlers and the plugin’s instance data hold references to each other, and both are owned by this type.

pub fn plugin_shared_handle(&self) -> PluginSharedHandle<'_>

Returns a thread-safe handle to the plugin.

Unlike the PluginMainThreadHandle returned by plugin_handle, this handle can be cloned and sent to other threads.

However, it has fewer capabilities, and cannot be used for operations that have to be performed on the main-thread (e.g. GUI).

pub fn plugin_handle(&mut self) -> PluginMainThreadHandle<'_>

Returns a main-thread handle to the plugin.

pub fn inactive_plugin_handle( &mut self, ) -> Option<InactivePluginMainThreadHandle<'_>>

Returns a main-thread handle to the plugin, that can only exist while the plugin is in the ‘inactive’ state.

Calling this method also prevents the plugin instance to be activated as long as the handle exists.

If the plugin is actually activated, this returns None.

Trait Implementations

impl<H: HostHandlers> Drop for PluginInstance<H>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.