[−][src]Trait lv2rs_core::Plugin

pub trait Plugin {
    fn instantiate(
        descriptor: &Descriptor, 
        rate: f64, 
        bundle_path: &CStr, 
        features: Option<Vec<&mut Feature>>
    ) -> Self;

    unsafe fn connect_port(&mut self, port: u32, data: *mut ());

    fn run(&mut self, n_samples: u32);

    fn activate(&mut self) { ... }

    fn deactivate(&mut self) { ... }

    fn extension_data(_uri: &CStr) -> Option<&'static dyn ExtensionData> { ... }
}

LV2 plugin trait.

This trait helps you implementing plugins, since it requires you to implement all necessary functions.

Almost every plugin function call from the host will be checked and "safed" before these trait functions may be called. Therefore, most of them are safe, except for one: connect_port. See it's documentations for more information on why it is unsafe.

Required methods

fn instantiate(
    descriptor: &Descriptor,
    rate: f64,
    bundle_path: &CStr,
    features: Option<Vec<&mut Feature>>
) -> Self

Create a new instance of the plugin.

Here, you should instantiate the plugin and supply it with general information. You can look at the plugin descriptor (although you shouldn't), the audio frame rate of the current session, the path from which the host has loaded the plugin and an iterator over features supported by the host.

unsafe fn connect_port(&mut self, port: u32, data: *mut ())

Set internal data pointers.

This function will be called by the host when the location of a port has changed and the plugin should update it's internal pointers. This function is highly unsafe, since the type of the pointed data is generally unknown. The only thing that gives a clue on the type is the id of the port, which should match with the port specified in the plugin's turtle document.

When this function is called, the data pointers may not be valid yet and therefore, you shouldn't use them. Also, if the host passes pointers that will never be valid, you cannot defend yourselves from undefined behaviour, and you should not, in any case, call this function on your own.

fn run(&mut self, n_samples: u32)

Run plugin specific operations.

This is where the action happens! Here, you should execute the actions that make your plugin unique.

Pointers, which were previously set by the connect_port function are guaranteed to be valid now. If they aren't, it's the host's fault, not yours. Also, sample arrays or atom sequence will have a length of n_samples elements. This number may change during the life time of the plugin and therefore, you should not store it somewhere.

Loading content...

Provided methods

fn activate(&mut self)

Activate the plugin.

If your plugin can be turned on or off, you should override this function and set the plugin up for active use.

The default implementation does nothing.

fn deactivate(&mut self)

Deactivate the plugin.

If your plugin can be turned on or off, you should override this function and destroy the plugins active state.

The default implementation does nothing.

fn extension_data(_uri: &CStr) -> Option<&'static dyn ExtensionData>

Return extension specific data to the host.

Some LV2 extensions require special data from a plugin in order to work. This is where you provide the data. The passed C string reference is the URI of the extension in question and you can return a static reference to some data. If you do not know the passed URI, you should return None.

The return value must be a static reference since we don't know how long it needs to be alive; as stated in the LV2 header, the host is not responsible for freeing the returned value. Therefore, the referenced data need to live for the entirety of the program.

Loading content...

Implementors

Loading content...