From 5dd744e769713ab6387f473062a64efcb667b738 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Mon, 30 Jan 2012 01:59:42 +0000 Subject: Update documentation. --- lv2/ns/ext/state/state.h | 2 +- lv2/ns/ext/state/state.ttl | 124 ++++++++++++++++++++++++--------------------- 2 files changed, 66 insertions(+), 60 deletions(-) (limited to 'lv2/ns/ext/state') diff --git a/lv2/ns/ext/state/state.h b/lv2/ns/ext/state/state.h index bbb8fad..15510e7 100644 --- a/lv2/ns/ext/state/state.h +++ b/lv2/ns/ext/state/state.h @@ -1,5 +1,5 @@ /* - Copyright 2010-2011 David Robillard + Copyright 2010-2012 David Robillard Copyright 2010 Leonard Ritter Permission to use, copy, modify, and/or distribute this software for any 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 +# Copyright 2010-2012 David Robillard # Copyright 2010 Leonard Ritter # # Permission to use, copy, modify, and/or distribute this software for any @@ -28,7 +28,7 @@ doap:license ; 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 ] ; lv2:documentation """ -

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 completely described by port values (as with all -LV2 plugins) and a simple dictionary.

+

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 +completely described by port values (as with all LV2 plugins) and a +dictionary.

The state 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 -property. The plugin provides an LV2_State_Interface for working with -this state. To save or restore, the host calls LV2_State_Interface::save() or +property. 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.

@@ -72,19 +72,15 @@ in any way.

snapshots.
  • Easily stored in a typical map or dictionary data structure.
    • -
  • Keys may be defined by extensions, making state meaningful between - implementations and enabling dynamic state control.
    • +
  • Keys may be defined by extensions and used by several plugins, + making state meaningful enabling dynamic state control.
    • -

    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 -set(eg:greeting, "Bonjour"), 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.

    +

    Implementations or further extensions which work with plugin state +(including dynamic plugin control) SHOULD work entirely within this model. +That is, do not complicate the state model. All +information required to express an instance's state at any given time can, and +should, be expressed within this model.

    Plugin Code Example

    @@ -185,23 +181,17 @@ Map get_plugin_state(LV2_Handle instance)

    Referring to Existing Files

    -

    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.

    - -

    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.

    +

    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 state:mapPath for details.

    Creating New Files or Directories

    -

    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 +

    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 state:newPath makes this possible, if it is provided by the host.

    """ . @@ -231,12 +221,13 @@ state:State lv2:documentation """

    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.

    +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.

    """ . state:state @@ -267,16 +258,15 @@ state:mapPath a lv2:Feature ; rdfs:label "Support for storing paths in files" ; lv2:documentation """ -

    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 + +

    This feature maps absolute paths to/from abstract paths 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.

    -

    The plugin MUST use the provided functions to map all 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.

    +

    The plugin MUST map all 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.

    For example, a plugin may write a path to a state file like so:

    @@ -307,21 +297,37 @@ state:makePath rdfs:label "Support for creating new files and directories" ; lv2:documentation """ -

    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.

    +

    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.

    + +

    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 one such namespace, even if the feature is passed to +both LV2_Descriptor::instantiate() and +LV2_State_Interface::save(). Beyond this, the plugin MUST NOT make any +assumptions about the returned paths.

    + +

    Like any other paths, the plugin MUST map these paths using state:mapPath 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.

    For example, a plugin may create a file in a subdirectory like so:

    -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;
 }
    """ . @@ -332,11 +338,11 @@ state:Path lv2:documentation """

    A path to a file or directory.

    -

    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 type 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.

    +

    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 type 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.

    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 -- cgit v1.2.1