aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/ns/ext
diff options
context:
space:
mode:
Diffstat (limited to 'lv2/ns/ext')
-rw-r--r--lv2/ns/ext/atom/atom.h22
-rw-r--r--lv2/ns/ext/atom/atom.ttl18
-rw-r--r--lv2/ns/ext/atom/manifest.ttl2
-rw-r--r--lv2/ns/ext/state/state.h2
-rw-r--r--lv2/ns/ext/state/state.ttl124
5 files changed, 87 insertions, 81 deletions
diff --git a/lv2/ns/ext/atom/atom.h b/lv2/ns/ext/atom/atom.h
index 39d721c..569ab49 100644
--- a/lv2/ns/ext/atom/atom.h
+++ b/lv2/ns/ext/atom/atom.h
@@ -55,7 +55,7 @@ typedef struct {
/**
An atom:String.
- This type may safely be cast to LV2_Atom.
+ May be cast to LV2_Atom.
*/
typedef struct {
uint32_t type; /**< Type of this atom (mapped URI). */
@@ -65,7 +65,7 @@ typedef struct {
/**
An atom:Literal.
- This type may safely be cast to LV2_Atom.
+ May be cast to LV2_Atom.
*/
typedef struct {
uint32_t type; /**< Type of this atom (mapped URI). */
@@ -77,17 +77,17 @@ typedef struct {
/**
An atom:URID or atom:BlankID.
- This type may safely be cast to LV2_Atom.
+ May be cast to LV2_Atom.
*/
typedef struct {
uint32_t type; /**< Type of this atom (mapped URI). */
uint32_t size; /**< Size in bytes, not including type and size. */
uint32_t id; /**< URID (integer mapped URI) or blank node ID. */
-} LV2_Atom_ID;
+} LV2_Atom_URID;
/**
An atom:Vector.
- This type may safely be cast to LV2_Atom.
+ May be cast to LV2_Atom.
*/
typedef struct {
uint32_t type; /**< Type of this atom (mapped URI). */
@@ -108,7 +108,7 @@ typedef struct _LV2_Atom_Property {
/**
An atom:Thing (Resource, Blank, or Message).
- This type may safely be cast to LV2_Atom.
+ May be cast to LV2_Atom.
*/
typedef struct {
uint32_t type; /**< Type of this atom (mapped URI). */
@@ -130,7 +130,7 @@ typedef struct {
/**
An atom:Int32, a signed 32-bit integer.
- This type may safely be cast to LV2_Atom.
+ May be cast to LV2_Atom.
*/
typedef struct {
uint32_t type;
@@ -140,17 +140,17 @@ typedef struct {
/**
An atom:Int64, a signed 64-bit integer.
- This type may safely be cast to LV2_Atom.
+ May be cast to LV2_Atom.
*/
typedef struct {
uint32_t type;
uint32_t size;
- int64_t value;
+ int64_t value;
} LV2_Atom_Int64;
/**
An atom:Float, a 32-bit IEEE-754 floating point number.
- This type may safely be cast to LV2_Atom.
+ May be cast to LV2_Atom.
*/
typedef struct {
uint32_t type;
@@ -160,7 +160,7 @@ typedef struct {
/**
An atom:Double, a 64-bit IEEE-754 floating point number.
- This type may safely be cast to LV2_Atom.
+ May be cast to LV2_Atom.
*/
typedef struct {
uint32_t type;
diff --git a/lv2/ns/ext/atom/atom.ttl b/lv2/ns/ext/atom/atom.ttl
index 2556776..c28b610 100644
--- a/lv2/ns/ext/atom/atom.ttl
+++ b/lv2/ns/ext/atom/atom.ttl
@@ -1,5 +1,5 @@
# LV2 Atom Extension
-# Copyright 2007-2011 David Robillard <d@drobilla.net>
+# Copyright 2007-2012 David Robillard <d@drobilla.net>
#
# Permission to use, copy, modify, and/or distribute this software for any
# purpose with or without fee is hereby granted, provided that the above
@@ -16,11 +16,11 @@
@prefix atom: <http://lv2plug.in/ns/ext/atom#> .
@prefix doap: <http://usefulinc.com/ns/doap#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
-@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
-@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
-@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
<http://lv2plug.in/ns/ext/atom>
a lv2:Specification ;
@@ -29,8 +29,8 @@
doap:license <http://opensource.org/licenses/isc> ;
rdfs:seeAlso <atom-buffer.h> ;
doap:release [
- doap:revision "0.2" ;
- doap:created "2011-11-05"
+ doap:revision "0.3" ;
+ doap:created "2012-01-28"
] ;
doap:maintainer [
a foaf:Person ;
@@ -137,8 +137,8 @@ sizeof(LV2_Atom_Literal)</code>, including the terminating NULL character. The
href="http://www.loc.gov/standards/iso639-2/">ISO 693-2</a> or <a
href="http://www.loc.gov/standards/iso639-2/">ISO 693-3</a> language code.</p>
-<p>For compatibility, a Literal MUST have either a <code>datatype</code>
-or a <code>lang</code>, but never both.</p>
+<p>A Literal may have a <code>datatype</code> OR a <code>lang</code>, but never
+both.</p>
<p>For example, a Literal can be "Hello" in English:</p>
<pre class="c-code">
diff --git a/lv2/ns/ext/atom/manifest.ttl b/lv2/ns/ext/atom/manifest.ttl
index adb10e5..20c974d 100644
--- a/lv2/ns/ext/atom/manifest.ttl
+++ b/lv2/ns/ext/atom/manifest.ttl
@@ -4,6 +4,6 @@
<http://lv2plug.in/ns/ext/atom>
a lv2:Specification ;
lv2:minorVersion 0 ;
- lv2:microVersion 2 ;
+ lv2:microVersion 3 ;
rdfs:seeAlso <atom.ttl> .
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 <http://drobilla.net>
+ Copyright 2010-2012 David Robillard <http://drobilla.net>
Copyright 2010 Leonard Ritter <paniq@paniq.org>
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 <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
generated by cgit v1.2.1 (git 2.18.0) at 2024-11-03 02:20:30 +0000