Trait Plugin

pub trait Plugin:
    UriBound
    + Sized
    + Send
    + Sync
    + 'static {
    type Ports: PortCollection;
    type InitFeatures: FeatureCollection<'static>;
    type AudioFeatures: FeatureCollection<'static>;

    // Required methods
    fn new(
        plugin_info: &PluginInfo<'_>,
        features: &mut Self::InitFeatures,
    ) -> Option<Self>;
    fn run(
        &mut self,
        ports: &mut Self::Ports,
        features: &mut Self::AudioFeatures,
        sample_count: u32,
    );

    // Provided methods
    fn activate(&mut self, _features: &mut Self::InitFeatures) { ... }
    fn deactivate(&mut self, _features: &mut Self::InitFeatures) { ... }
    fn extension_data(_uri: &Uri) -> Option<&'static dyn Any> { ... }
}

The central trait to describe LV2 plugins.

This trait and the structs that implement it are the centre of every plugin project, since it hosts the run method. This method is called by the host for every processing cycle.

However, the host will not directly talk to the plugin. Instead, it will create and talk to the PluginInstance, which dereferences raw pointers, does safety checks and then calls the corresponding plugin methods. However, it guarantees that a valid sys::LV2_Handle is always a valid *mut MyPlugin, where MyPlugin is your plugin’s name.

Required Associated Types

type Ports: PortCollection

The type of the port collection.

type InitFeatures: FeatureCollection<'static>

The host features used by this plugin in the “Initialization” thread class.

This collection will be created by the framework when the plugin is initialized and every method in the “Initialization” threading class has access to it via a mutable reference.

If a host feature is missing, the plugin creation simply fails and your plugin host will tell you so. However, this collection may only contain features that are usable in the “Initialization” thread class. Otherwise, the backend may panic during initialization. Please consult each feature’s documentation.

type AudioFeatures: FeatureCollection<'static>

The host features used by this plugin in the “Audio” thread class.

This collection will be created by the framework when the plugin is initialized and every method in the “Audio” threading class has access to it via a mutable reference.

If a host feature is missing, the plugin creation simply fails and your plugin host will tell you so. However, this collection may only contain features that are usable in the “Audio” thread class. Otherwise, the backend may panic during initialization. Please consult each feature’s documentation.

Required Methods

fn new( plugin_info: &PluginInfo<'_>, features: &mut Self::InitFeatures, ) -> Option<Self>

Create a new plugin instance.

This method only creates an instance of the plugin, it does not reset or set up it’s internal state. This is done by the activate method.

fn run( &mut self, ports: &mut Self::Ports, features: &mut Self::AudioFeatures, sample_count: u32, )

Run a processing step.

The host will always call this method after active has been called and before deactivate has been called.

The sample count is the number of frames covered by this run call. Audio and CV ports will contain exactly sample_count frames. Please note that sample_count may be differ between calls.

Provided Methods

fn activate(&mut self, _features: &mut Self::InitFeatures)

Reset and initialize the complete internal state of the plugin.

This method will be called if the plugin has just been created of if the plugin has been deactivated. Also, a host’s activate call will be as close as possible to the first run call.

fn deactivate(&mut self, _features: &mut Self::InitFeatures)

Deactivate the plugin.

The host will always call this method when it wants to shut the plugin down. After deactivate has been called, run will not be called until activate has been called again.

fn extension_data(_uri: &Uri) -> Option<&'static dyn Any>

Return additional, extension-specific data.

Sometimes, the methods from the Plugin trait aren’t enough to support additional LV2 specifications. For these cases, extension exist. In most cases and for Rust users, an extension is simply a trait that can be implemented for a plugin.

However, these implemented methods must be passed to the host. This is where this method comes into play: The host will call it with a URI for an extension. Then, it is the plugin’s responsibilty to return the extension data to the host.

In most cases, you can simply use the match_extensions macro to generate an appropiate method body.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors