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/atom/atom.h | 22 ++++---- lv2/ns/ext/atom/atom.ttl | 18 +++---- lv2/ns/ext/atom/manifest.ttl | 2 +- lv2/ns/ext/state/state.h | 2 +- lv2/ns/ext/state/state.ttl | 124 +++++++++++++++++++++++-------------------- 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 +# Copyright 2007-2012 David Robillard # # 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: . @prefix doap: . @prefix foaf: . -@prefix lv2: . -@prefix rdf: . +@prefix lv2: . +@prefix owl: . +@prefix rdf: . @prefix rdfs: . -@prefix xsd: . -@prefix owl: . +@prefix xsd: . a lv2:Specification ; @@ -29,8 +29,8 @@ doap:license ; rdfs:seeAlso ; 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), including the terminating NULL character. The href="http://www.loc.gov/standards/iso639-2/">ISO 693-2 or ISO 693-3 language code.

-

For compatibility, a Literal MUST have either a datatype -or a lang, but never both.

+

A Literal may have a datatype OR a lang, but never +both.

For example, a Literal can be "Hello" in English:

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 @@
 
 	a lv2:Specification ;
 	lv2:minorVersion 0 ;
-	lv2:microVersion 2 ;
+	lv2:microVersion 3 ;
 	rdfs:seeAlso  .
 
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