Crate lv2_state

Extension for LV2 plugins to store their state.

This is a rather classic extension to LV2 plugins: There is a trait called State which requires the methods save and restore to be implemented. These methods will be called by the host to save and restore the state of the plugin.

Refering to files

This crate also includes features to create files in a unique namespace for the plugin instance. However, these files will not persist across save/restore calls and therefore need to be safed together with the state as well. For more information, see the documentation of the path module.

Example usage

use lv2_atom::prelude::*;
use lv2_core::prelude::*;
use lv2_state::*;
use lv2_urid::*;
use urid::*;

/// A plugin that stores a float value.
struct Stateful {
    internal: f32,
    urids: AtomURIDCollection,
}

/// `Stateful`s implementation of `State`.
impl State for Stateful {
    type StateFeatures = ();

    fn save(&self, mut store: StoreHandle, _: ()) -> Result<(), StateErr> {
        // Try to draft a new property and store the float inside it.
        store
            .draft(URID::new(1000).unwrap())
            .init(self.urids.float, self.internal)?;

        // Commit the written property.
        // Otherwise, it will discarded.
        store.commit_all()
    }

    fn restore(&mut self, store: RetrieveHandle, _: ()) -> Result<(), StateErr> {
        // Try to restore the property.
        self.internal = store
            .retrieve(URID::new(1000).unwrap())?
            .read(self.urids.float, ())?;

        // We're done.
        Ok(())
    }
}

impl Plugin for Stateful {
    type Ports = ();
    type InitFeatures = Features<'static>;
    type AudioFeatures = ();

    fn new(_: &PluginInfo, features: &mut Features<'static>) -> Option<Self> {
        Some(Stateful {
            internal: 42.0,
            urids: features.map.populate_collection()?,
        })
    }

    fn run(&mut self, _: &mut (), _: &mut (), _: u32) {
        // Set the float to a different value than the previous one.
        self.internal += 1.0;
    }

    fn extension_data(uri: &Uri) -> Option<&'static dyn std::any::Any> {
        // Export the store extension. Otherwise, the host won't use it.
        match_extensions!(uri, StateDescriptor<Self>)
    }
}

#[derive(FeatureCollection)]
pub struct Features<'a> {
    map: LV2Map<'a>,
}

unsafe impl UriBound for Stateful {
    const URI: &'static [u8] = b"urn:lv2_atom:stateful\0";
}

Modules

path	Host features for file path managment.

Structs

RetrieveHandle	Property retrieval handle.
StateDescriptor	Raw wrapper of the State extension.
StatePropertyReader	Reading handle for properties.
StatePropertyWriter	Writing handle for properties.
Storage	A simple property store.
StoreHandle	Property storage handle.

Enums

StateErr

Kinds of errors that may occur in the crate.

Traits

State

A plugin extension that lets a plugins save and restore it's state.