From 333aba2e488e3d84ae357dd2f3aec76a0f6021aa Mon Sep 17 00:00:00 2001
From: David Robillard This extension provides a mechanism for plugins to save and restore state
across instances, allowing hosts to save configuration/state/data with a
-project or fully clone a plugin instance (including internal state). Unlike ports, this extension allows plugins to save private state data.
-The motivating ideal behind this extension is for the state of a plugin
-instance to be entirely described by port values (as with all LV2 plugins) and
-a key/value dictionary as defined by this extension. This mechanism is simple,
-yet sufficiently powerful to describe the state of very advanced plugins. The "state" described by this extension is conceptually a single key/value
-dictionary. Keys are URIs, and values are typed-tagged blobs of any type.
-The plugin provides a save and restore method for saving and restoring state.
-To initiate a save or restore, the host calls these methods, passing a callback
-to be used for saving or restoring a single key/value pair. In this way,
-the actual mechanism of saving and restoring state is completely abstract
-from the plugin's perspective. Because the state is a simple dictionary, hosts and plugins can work
-with state easily (virtually all programming languages have an appropriate
-dictionary type available). Additionally, this format is simple and terse to
+project or fully clone (i.e. make a deep copy of) a plugin instance. This extension allows plugins to save private state data, i.e. data that is
+not contained in input ports. The motivating ideal is for the state of a plugin
+instance to be entirely described by port values (as with all LV2
+plugins) and a key/value dictionary as defined by this extension. This
+mechanism is simple, yet sufficiently powerful to describe arbitrarily advanced
+state. The Because the state is a simple dictionary, hosts and plugins can work with
+state easily (virtually all programming languages have an appropriate
+dictionary type available). Additionally, this format is simple and terse to
serialise in many formats (e.g. any RDF syntax, JSON, XML, key/value databases
-such as BDB, etc.). In particular, state can be elegantly described in a
-plugin's Turtle description, which is useful for presets (among other things).
-Note that these are all simply possibilities enabled by this simple data
-model. This extension defines only a few function prototypes and does not
-impose any requirement to use a particular syntax, data structure, library,
-or other implementation detail. Hosts are free to work with plugin state
-in whatever way is most appropriate for that host. This extension makes it possible for plugins to save private data, but
-state is not necessarily private, e.g. a plugin could have a public interface
-via ports for manipulating internal state, which would be saved using this
-extension. Plugins are strongly encouraged to represent all state change as
-modifications of such key/value variables, to minimize implementation burden
-and enable the many benefits of having a universal model for describing
-plugin state. The use of URI keys prevents conflict and allows unrelated
-plugins to meaningfully describe state changes. Future extensions will
-describe a dynamic mechanism for manipulating plugin state, as well as define
-various keys likely to be useful to a wide range of plugins.state
described by this extension is conceptually a single key/value
+dictionary. Keys are URIs, and values are typed-tagged blobs of any type. The
+plugin provides a save and restore method for saving and restoring state. To
+initiate a save or restore, the host calls these methods, passing a callback to
+be used for saving or restoring a key/value pair. This data is available
+to the host, allowing state to be easily used in many different way. The
+actual mechanism of saving and restoring state is completely abstract from the
+plugin's perspective.
This extension makes it possible for plugins to save private data, but state +is not necessarily private, e.g. a plugin could have a public interface for +inspecting and manipulating internal state, which would be saved using this +extension. Plugins and extensions SHOULD express state changes as modifications +to this key/value dictionary, and use meaningful types wherever +possible. Extensions may define a dynamic mechanism for accessing plugin state, +or conventional state keys likely to be useful to several implementations.
In pseudo code, a typical use case in a plugin is:
-- cgit v1.2.1