diff options
| -rw-r--r-- | ext/persist.lv2/persist.ttl | 72 |
1 files changed, 35 insertions, 37 deletions
diff --git a/ext/persist.lv2/persist.ttl b/ext/persist.lv2/persist.ttl index 7ec0e0e..64e217e 100644 --- a/ext/persist.lv2/persist.ttl +++ b/ext/persist.lv2/persist.ttl @@ -45,44 +45,42 @@ lv2:documentation """ <p>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).</p> - -<p>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.</p> - -<p>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.</p> - -<p>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.</p> + +<p>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 <em>entirely</em> 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.</p> + +<p>The <q>state</q> 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.</p> + +<p>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.</p> - -<p>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.</p> +such as BDB, etc.). In particular, state can be elegantly described in a +plugin's Turtle description, which is useful for e.g. presets or default +state. Note that these are simply possibilities; this extension defines only a +few function prototypes and does not require the use of any particular syntax, +data structure, file system, or other implementation detail. Hosts are free to +work with plugin state in whatever way is most appropriate for that host.</p> + +<p>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.</p> <p>In pseudo code, a typical use case in a plugin is:</p> <pre> |