diff options
Diffstat (limited to 'lv2/ns/ext/state/state.ttl')
| -rw-r--r-- | lv2/ns/ext/state/state.ttl | 124 |
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 |