aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/ns/ext/state/state.ttl
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2012-01-30 01:59:42 +0000
committerDavid Robillard <d@drobilla.net>2012-01-30 01:59:42 +0000
commit5dd744e769713ab6387f473062a64efcb667b738 (patch)
treefe04d77d8d133e3811e4528dc0520eac45a9f491 /lv2/ns/ext/state/state.ttl
parentc93019b5c405a61b84a0ba85486167e6241026cc (diff)
downloadlv2-5dd744e769713ab6387f473062a64efcb667b738.tar.xz
Update documentation.
Diffstat (limited to 'lv2/ns/ext/state/state.ttl')
-rw-r--r--lv2/ns/ext/state/state.ttl124
1 files changed, 65 insertions, 59 deletions
diff --git a/lv2/ns/ext/state/state.ttl b/lv2/ns/ext/state/state.ttl
index 9a31bfb..84cda42 100644
--- a/lv2/ns/ext/state/state.ttl
+++ b/lv2/ns/ext/state/state.ttl
@@ -1,5 +1,5 @@
# LV2 State Extension
-# Copyright 2010-2011 David Robillard <d@drobilla.net>
+# Copyright 2010-2012 David Robillard <d@drobilla.net>
# Copyright 2010 Leonard Ritter <paniq@paniq.org>
#
# Permission to use, copy, modify, and/or distribute this software for any
@@ -28,7 +28,7 @@
doap:license <http://opensource.org/licenses/isc> ;
doap:release [
doap:revision "0.5" ;
- doap:created "2011-12-22"
+ doap:created "2012-01-29"
] ;
doap:developer [
a foaf:Person ;
@@ -42,17 +42,17 @@
rdfs:seeAlso <http://drobilla.net/drobilla.rdf>
] ;
lv2:documentation """
-<p>This extension provides a mechanism for plugins to save and restore state
-across instances, allowing hosts to save, restore, clone, or take a snapshot of
-a plugin instance's state at any point in time. The intention is for a plugin
-instance's state to be <em>completely</em> described by port values (as with all
-LV2 plugins) and a simple dictionary.</p>
+<p>This extension provides a simple mechanism for plugins to save and restore
+state across instances, allowing hosts to save and restore a plugin instance's
+state at any time. The goal is for an instance's state to be
+<em>completely</em> described by port values (as with all LV2 plugins) and a
+dictionary.</p>
<p>The <q>state</q> described by this extension is conceptually a simple
key:value dictionary, where keys are URIDs (URIs mapped to integers) and values
are type-tagged blobs of any type. A single key:value pair is called a
-<q>property</q>. The plugin provides an LV2_State_Interface for working with
-this state. To save or restore, the host calls LV2_State_Interface::save() or
+<q>property</q>. 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.</p>
@@ -72,19 +72,15 @@ in any way.</p>
snapshots.</li>
<li>Easily stored in a typical <q>map</q> or <q>dictionary</q> data
structure.</li>
- <li>Keys may be defined by extensions, making state meaningful between
- implementations and enabling dynamic state control.</li>
+ <li>Keys may be defined by extensions and used by several plugins,
+ making state meaningful enabling dynamic state control.</li>
</ul>
-<p>This extension defines a conceptual state model and a mechanism for saving
-and restoring it, but no interface for manipulating it dynamically. However,
-any such mechanism SHOULD work with the same properties used in this extension
-to avoid complicating the concept of plugin state. For example, an extension
-to the example plugin below could be to support a message like
-<code>set(eg:greeting, "Bonjour")</code>, which could be sent by the host, UIs,
-or other plugins (via the host) to dynamically control the plugin's state.
-Accordingly, plugins SHOULD use meaningful and well-defined keys wherever
-possible.</p>
+<p>Implementations or further extensions which work with plugin state
+(including dynamic plugin control) SHOULD work entirely within this model.
+That is, <strong>do not complicate the state model</strong>. <em>All</em>
+information required to express an instance's state at any given time can, and
+should, be expressed within this model.</p>
<h3>Plugin Code Example</h3>
@@ -185,23 +181,17 @@ Map get_plugin_state(LV2_Handle instance)
<h3>Referring to Existing Files</h3>
-<p>This extension deliberately avoids imposing any file formats or file system
-dependencies on implementations. However, some plugins need to refer to
-files in their state. This is done by storing the file's path as a property
-just like any other value.</p>
-
-<p>Plugins MUST use the type state:Path for all paths in their state. This
-allows hosts to know about all such files, which is necessary for making
-session export and archival possible (among other things). Hosts are free to
-map paths in any way, and plugins MUST NOT assume the restored path will be
-identical to the saved path.</p>
+<p>Plugins may need to refer to 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 <a href="#mapPath">state:mapPath</a> for details.</p>
<h3>Creating New Files or Directories</h3>
-<p>New implementations and basic plugins are strongly encouraged to simply
-store all state as properties using this API. However, some plugins have an
-existing file or directory formats for state. Plugins MAY create new files
-or directories by using the state:newPath feature, if it is provided by the
+<p>Implementations are strongly encouraged to avoid the use of files and simply
+store all state as properties whenever possible. However, occasionally the
+ability to create files is necessary. The feature <a
+href="#newPath">state:newPath</a> makes this possible, if it is provided by the
host.</p>
""" .
@@ -231,12 +221,13 @@ state:State
lv2:documentation """
<p>This class is used to express a plugin instance's state in RDF. The
key/value properties of the instance form the predicate/object (respectively)
-of triples with a state:State as the subject (see state:state for an
-example). This may be used wherever it is useful to express a plugin instance's
-state in RDF (e.g. for serialisation, storing in a model, or transmitting over
-a network). Note that this class is provided because it may be useful for
-hosts, plugins, or extensions that work with instance state, but its use is not
-required to support the LV2 State extension.</p>
+of triples with a state:State as the subject (see <a
+href="#state">state:state</a> for an example). This may be used wherever it is
+useful to express a plugin instance's state in RDF (e.g. for serialisation,
+storing in a model, or transmitting over a network). Note that this class is
+provided because it may be useful for hosts, plugins, or extensions that work
+with instance state, but its use is not required to support the LV2 State
+extension.</p>
""" .
state:state
@@ -267,16 +258,15 @@ state:mapPath
a lv2:Feature ;
rdfs:label "Support for storing paths in files" ;
lv2:documentation """
-<p>This feature allows plugins to store paths inside files stored in its state
-(if, for example, a plugin saves to an existing file format which contains
-paths). To support this feature a host must pass an LV2_Feature with URI
-LV2_STATE_MAP_PATH_URI and data pointed to an LV2_State_Map_Path to the
+
+<p>This feature maps absolute paths to/from <q>abstract paths</q> which are
+stored in state. To support this feature a host must pass an LV2_Feature with
+URI LV2_STATE_MAP_PATH_URI and data pointed to an LV2_State_Map_Path to the
plugin's LV2_State_Interface methods.</p>
-<p>The plugin MUST use the provided functions to map <em>all</em> paths stored
-in any files it creates (using state:makePath) and stores in the state. This
-is necessary to enable host to handle file system references correctly, e.g.
-for session export or archival.</p>
+<p>The plugin MUST map <em>all</em> paths stored in its state (including in any
+files in its state). This is necessary to enable host to handle file system
+references correctly, e.g. for distribution or archival.</p>
<p>For example, a plugin may write a path to a state file like so:</p>
@@ -307,21 +297,37 @@ state:makePath
rdfs:label "Support for creating new files and directories" ;
lv2:documentation """
-<p>This feature allows plugins to create new files or directories. To support
-this feature the host passes an LV2_Feature with URI LV2_STATE_MAKE_PATH_URI
-and data pointed to an LV2_State_Make_Path to the plugin. The host may provide
-this feature during state saving only or at any time, by passing the feature to
-LV2_State_Interface::save() or LV2_Descriptor::instantiate(), respectively.</p>
+<p>This feature allows plugins to create new files and/or directories. To
+support this feature the host passes an LV2_Feature with URI
+LV2_STATE_MAKE_PATH_URI and data pointed to an LV2_State_Make_Path to the
+plugin. The host may make this feature available only during save by passing
+it to LV2_State_Interface::save(), or available any time by passing it to
+LV2_Descriptor::instantiate(). If passed to LV2_State_Interface::save(), the
+feature MUST NOT be used beyond the scope of that call.</p>
+
+<p>The plugin is guaranteed a hierarchial namespace unique to that plugin
+instance, and may expect the returned path to have the requested path as a
+suffix. There is <em>one</em> such namespace, even if the feature is passed to
+both LV2_Descriptor::instantiate() <em>and</em>
+LV2_State_Interface::save(). Beyond this, the plugin MUST NOT make any
+assumptions about the returned paths.</p>
+
+<p>Like any other paths, the plugin MUST map these paths using <a
+href="#mapPath">state:mapPath</a> before storing them in state. The plugin
+MUST NOT assume these paths will be available across a save/restore otherwise,
+i.e. only mapped paths saved to state are persistent, any other created paths
+are temporary.</p>
<p>For example, a plugin may create a file in a subdirectory like so:</p>
<pre class="c-code">
-void save_myfile(LV2_State_Make_Path* make_path)
+char* save_myfile(LV2_State_Make_Path* make_path)
{
char* path = make_path->path(make_path->handle, "foo/bar/myfile.txt");
FILE* myfile = fopen(path, 'w');
fprintf(myfile, "Hello");
fclose(myfile);
+ return path;
}
</pre>
""" .
@@ -332,11 +338,11 @@ state:Path
lv2:documentation """
<p>A path to a file or directory.</p>
-<p>The format of a state:Path is a C string escaped or otherwise restricted in
-a system-specific manner. This URI (LV2_STATE_PATH_URI), mapped to an integer,
-MUST be used as the <code>type</code> parameter for any files passed to the
-LV2_State_Store_Function; and will likewise be returned by the corresponding
-call to the LV2_State_Retrieve_Function.</p>
+<p>The format of a state:Path is a C string, possibly escaped or otherwise
+restricted in a system-specific manner. This URI (LV2_STATE_PATH_URI), mapped
+to an integer, MUST be used as the <code>type</code> parameter for any files
+passed to the LV2_State_Store_Function; and will likewise be returned by the
+corresponding call to the LV2_State_Retrieve_Function.</p>
<p>When storing and retrieving a path, the plugin MUST NOT assume the same path
will be restored. However, the restored path will refer to a file with