This extension defines a simple mechanism which allows hosts to save and restore a plugin instance's state. The goal is for an instance's state to be completely described by port values (as with all LV2 plugins) and a simple dictionary.
The state
defined here is conceptually a key:value dictionary, with
URI keys and values of any type. For performance reasons the key and value
type are actually a URID
, a URI mapped to an integer. A single
key:value pair is called a property
.
This state model is simple yet has many benefits:
- Both fast and extensible thanks to URID keys.
- No limitations on possible value types.
- Easy to serialise in almost any format.
- Easy to store in a typical
map
ordictionary
data structure. - Elegantly described in Turtle, so state can be described in LV2 data files (including presets).
- Does not impose any file formats, data structures, or file system requirements.
- Suitable for portable persistent state as well as fast in-memory snapshots.
- Keys may be well-defined and used meaningfully across several implementations.
- State may be dynamic, but plugins are not required to have a dynamic dictionary data structure available.
To implement state, the plugin provides a state:interface to the host. To save or restore, the host calls LV2_State_Interface::save() or LV2_State_Interface::restore(), passing a callback to be used for handling a single property. The host is free to implement property storage and retrieval in any way.
Since value types are defined by URI, any type is possible. However, a set of standard types is defined by the LV2 Atom extension. Use of these types is recommended. Hosts MUST implement at least atom:String, which is simply a C string.
Referring to Files
Plugins may need to refer to existing files (e.g. loaded samples) in their state. This is done by storing the file's path as a property just like any other value. However, there are some rules which MUST be followed when storing paths, see state:mapPath for details. Plugins MUST use the type atom:Path for all paths in their state.
Plugins are strongly encouraged to avoid creating files, instead storing all state as properties. However, occasionally the ability to create files is necessary. To make this possible, the host can provide the feature state:makePath which allocates paths for plugin-created files. Plugins MUST NOT create files in any other locations.
Plugin Code Example
/* Namespace for this plugin's keys. This SHOULD be something that could be
published as a document, even if that document does not exist right now.
*/
#define NS_MY "http://example.org/myplugin/schema#"
#define DEFAULT_GREETING "Hello"
LV2_Handle
my_instantiate(...)
{
MyPlugin* plugin = ...;
plugin->uris.atom_String = map_uri(LV2_ATOM__String);
plugin->uris.my_greeting = map_uri(NS_MY "greeting");
plugin->state.greeting = strdup(DEFAULT_GREETING);
return plugin;
}
LV2_State_Status
my_save(LV2_Handle instance,
LV2_State_Store_Function store,
LV2_State_Handle handle,
uint32_t flags,
const LV2_Feature *const * features)
{
MyPlugin* plugin = (MyPlugin*)instance;
const char* greeting = plugin->state.greeting;
store(handle,
plugin->uris.my_greeting,
greeting,
strlen(greeting) + 1, // Careful! Need space for terminator
plugin->uris.atom_String,
LV2_STATE_IS_POD | LV2_STATE_IS_PORTABLE);
return LV2_STATE_SUCCESS;
}
LV2_State_Status
my_restore(LV2_Handle instance,
LV2_State_Retrieve_Function retrieve,
LV2_State_Handle handle,
uint32_t flags,
const LV2_Feature *const * features)
{
MyPlugin* plugin = (MyPlugin*)instance;
size_t size;
uint32_t type;
uint32_t flags;
const char* greeting = retrieve(
handle, plugin->uris.my_greeting, &size, &type, &flags);
if (greeting) {
free(plugin->state->greeting);
plugin->state->greeting = strdup(greeting);
} else {
plugin->state->greeting = strdup(DEFAULT_GREETING);
}
return LV2_STATE_SUCCESS;
}
const void*
my_extension_data(const char* uri)
{
static const LV2_State_Interface state_iface = { my_save, my_restore };
if (!strcmp(uri, LV2_STATE__interface)) {
return &state_iface;
}
}
Host Code Example
LV2_State_Status
store_callback(LV2_State_Handle handle,
uint32_t key,
const void* value,
size_t size,
uint32_t type,
uint32_t flags)
{
if ((flags & LV2_STATE_IS_POD)) {
/* We only care about POD since we're keeping state in memory only.
For disk or network use, LV2_STATE_IS_PORTABLE must also be checked.
*/
Map* state_map = (Map*)handle;
state_map->insert(key, Value(copy(value), size, type));
return 0;
} else {
return 1; /* Non-POD events are unsupported. */
}
}
Map
get_plugin_state(LV2_Handle instance)
{
LV2_State* state = instance.extension_data(LV2_STATE__interface);
Map state_map;
/** Request a fast/native/POD save, since we're just copying in memory */
state.save(instance, store_callback, &state_map,
LV2_STATE_IS_POD|LV2_STATE_IS_NATIVE);
return state_map;
}
Extensions to this Specification
It is likely that other interfaces for working with plugin state will be developed as needed. This is encouraged, however everything SHOULD work within the state model defined here. That is, do not complicate the state model. Implementations can assume the following:
- The current port values and state dictionary completely describe a plugin
instance, at least well enough that saving and restoring will yield an
identical
instance from the user's perspective. - Hosts are not expected to save and/or restore any other attributes of a plugin instance.
The Property Principle
The main benefit of this meaningful state model is that it can double as a
plugin control/query mechanism. For plugins that require more advanced control
than simple control ports, instead of defining a set of commands, define
properties whose values can be set appropriately. This provides both a way to
control and save that state for free
, since there is no need to define
commands and a set of properties for storing their effects. In
particular, this is a good way for UIs to achieve more advanced control of
plugins.
This property principle
is summed up in the phrase:
Don't stop; set playing to false
.
This extension does not define a dynamic mechanism for state access and manipulation. The LV2 Patch extension defines a generic set of messages which can be used to access or manipulate properties, and the LV2 Atom extension defines a port type and data container capable of transmitting those messages.