Replace LV2_Morph_Interface with more general LV2_Options_Interface.

4 files changed, 148 insertions, 127 deletions

diff --git a/lv2/lv2plug.in/ns/ext/morph/morph.h b/lv2/lv2plug.in/ns/ext/morph/morph.h
index 3c8ec46..6739d39 100644
--- a/lv2/lv2plug.in/ns/ext/morph/morph.h
+++ b/lv2/lv2plug.in/ns/ext/morph/morph.h
@@ -29,88 +29,6 @@
 #define LV2_MORPH__MorphPort     LV2_MORPH_PREFIX "MorphPort"
 #define LV2_MORPH__interface     LV2_MORPH_PREFIX "interface"
 #define LV2_MORPH__supportsType  LV2_MORPH_PREFIX "supportsType"
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum {
-	LV2_MORPH_SUCCESS      = 0,  /**< Completed successfully. */
-	LV2_MORPH_ERR_UNKNOWN  = 1,  /**< Unknown error. */
-	LV2_MORPH_ERR_BAD_TYPE = 2,  /**< Unsupported type. */
-	LV2_MORPH_ERR_BAD_PORT = 3   /**< Port is not morphable. */
-} LV2_Morph_Status;
-
-/** A port property. */
-typedef struct {
-	LV2_URID    key;    /**< Key (predicate) */
-	uint32_t    size;   /**< Value size */
-	LV2_URID    type;   /**< Value type */
-	const void* value;  /**< Value (object) */
-} LV2_Morph_Property;
-
-/** The interface provided by a plugin to support morph ports. */
-typedef struct {
-	/**
-	   Morph a port to a different type.
-	 
-	   This function is in the audio threading class.
-
-	   This function MAY return an error, in which case the port's type was not
-	   changed.  If the type was changed and the plugin has AutoMorphPort
-	   ports, the host MUST check the type of every AutoMorphPort using the
-	   port_type() function since they may have changed.
-
-	   This function MUST gracefully handle being called for ports that are not
-	   MorpPorts by ignoring the request and returning LV2_MORPH_ERR_BAD_PORT.
-
-	   A NULL-terminated array of additional properties to set on the port may
-	   be passed via @p properties.  These properties and their values are
-	   owned by the caller and valid only for the duration of the call.
-
-	   @param instance The plugin instance.
-	   @param port The index of the port to change the type of.
-	   @param type The new port type URID.
-	   @param properties Additional properties to set, or NULL.
-	*/
-	LV2_Morph_Status (*morph_port)(LV2_Handle                      instance,
-	                               uint32_t                        port,
-	                               LV2_URID                        type,
-	                               const LV2_Morph_Property*const* properties);
-
-	/**
-	   Get the type of an AutoMorphPort.
-
-	   This function is in the audio threading class.
-
-	   If the plugin has no auto morph ports, this field may be NULL.  This
-	   function may only be called for ports which are AutoMorphPorts.
-
-	   This function MAY return 0, which indicates that the current
-	   configuration of MorphPort types is invalid and the port is
-	   non-functional.  If the port is not lv2:connectionOptional, then the
-	   plugin MUST NOT be used.
-
-	   The @p properties parameter may be used to get additional properties of
-	   the port.  To do so, the host passes a NULL-terminated property array
-	   with keys set to the desired properties and all other fields zeroed.
-	   The plugin sets these fields appropriately if possible.  The data
-	   pointed to is owned by the plugin and only valid until the next call to
-	   a method on this plugin (this mechanism is only meant for accessing
-	   simple properties, such as buffer size).
-
-	   @param instance The plugin instance.
-	   @param port The index of the port to return the type of.
-	   @param properties Additional properties to get, or NULL.
-	   @return The current type of the port.
-	*/
-	LV2_URID (*port_type)(LV2_Handle                instance,
-	                      uint32_t                  port,
-	                      LV2_Morph_Property*const* properties);
-} LV2_Morph_Interface;
-
-#ifdef __cplusplus
-}  /* extern "C" */
-#endif
+#define LV2_MORPH__currentType   LV2_MORPH_PREFIX "currentType"
 
 #endif  /* LV2_MORPH_H */
diff --git a/lv2/lv2plug.in/ns/ext/morph/morph.ttl b/lv2/lv2plug.in/ns/ext/morph/morph.ttl
index 09351b1..9457089 100644
--- a/lv2/lv2plug.in/ns/ext/morph/morph.ttl
+++ b/lv2/lv2plug.in/ns/ext/morph/morph.ttl
@@ -1,10 +1,11 @@
 @prefix doap:  <http://usefulinc.com/ns/doap#> .
 @prefix foaf:  <http://xmlns.com/foaf/0.1/> .
 @prefix lv2:   <http://lv2plug.in/ns/lv2core#> .
+@prefix morph: <http://lv2plug.in/ns/ext/morph#> .
+@prefix opts: <http://lv2plug.in/ns/ext/options#> .
 @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 morph: <http://lv2plug.in/ns/ext/morph#> .
 @prefix xsd:   <http://www.w3.org/2001/XMLSchema#> .
 
 <http://lv2plug.in/ns/ext/morph>
@@ -15,11 +16,14 @@
 	lv2:documentation """
 <p>This extension defines two port types: morph:MorphPort, which has a
 host-configurable type, and morph:AutoMorphPort, which may automatically change
-type when a MorphPort type is changed.  These ports always have a default type
-and work normally work in hosts that are unaware of this extension.  Thus, this
-extension provides a backwards compatibility mechanism which allows plugins to
-use new port types but gracefully fall back to a default type in hosts that do
-not support them.</p>
+type when a MorphPort's type is changed.  These ports always have a default
+type and work normally work in hosts that are unaware of this extension.  Thus,
+this extension provides a backwards compatibility mechanism which allows
+plugins to use new port types but gracefully fall back to a default type in
+hosts that do not support them.</p>
+
+<p>This extension only defines port types and properties for describing morph
+ports.  The actual run-time switching is done via the opts:interface API.</p>
 """ .
 
 morph:MorphPort
@@ -30,13 +34,12 @@ morph:MorphPort
 	lv2:documentation """
 <p>Ports of this type MUST have another type which defines the default buffer
 format (e.g. lv2:ControlPort) but can be dynamically changed to a different
-type in hosts that support morph:interface.</p>
+type in hosts that support opts:interface.</p>
 
-<p>The host may change the type of a MorphPort by calling
-LV2_Morph_Interface::morph_port().  If the plugin has any morph:AutoMorphPort
+<p>The host may change the type of a MorphPort by setting its morph:currentType
+with LV2_Options_Interface::set().  If the plugin has any morph:AutoMorphPort
 ports, the host MUST check their types after changing any port type since they
-may have changed.</p>
-""" .
+may have changed.</p> """ .
 
 morph:AutoMorphPort
 	a rdfs:Class ,
@@ -48,31 +51,36 @@ morph:AutoMorphPort
 format (e.g. lv2:ControlPort) but may dynamically change types based on the
 configured types of any morph:MorphPort ports on the same plugin instance.</p>
 
-<p>The type of a port may only change in response to a call to
-LV2_Morph_Interface::morph_port(), i.e. ports can only change type as a result
-of an explicit host request.  Whenever any port type on the instance changes,
-the host MUST check the type of all morph:AutoMorphPort ports on the instance
-before calling run() again, since they may have changed.</p>
+<p>The type of a port may only change in response to a host call to
+LV2_Options_Interface::set().  Whenever any port type on the instance changes,
+the host MUST check the type of all morph:AutoMorphPort ports with
+LV2_Options_Interface::get() before calling run() again, since they may have
+changed.  If the type of any port is zero, it means the current configuration
+is invalid and the plugin may not be run (unless that port is
+lv2:connectionOptional and connected to NULL).</p>
 
 <p>This is mainly useful for outputs whose type depends on the type of
 corresponding inputs.</p>
 """ .
 
-morph:interface
-	a lv2:ExtensionData ;
+morph:supportsType
+	a rdf:Property ,
+		owl:ObjectProperty ;
+	rdfs:domain morph:MorphPort ;
+	rdfs:label "supports type" ;
 	lv2:documentation """
-<p>The interface provided by the plugin to support morph ports.  To support
-this extension, the plugin must return a LV2_Morph_Interface from
-LV2_Descriptor::extension_data() when it is called with this URI
-(LV2_MORPH__interface).</p>
+<p>Indicates that a port supports being switched to a certain type.  A
+MorphPort MUST list each type it supports being switched to in the plugin data
+using this property.</p>
 """ .
 
-morph:supportsType
+morph:currentType
 	a rdf:Property ,
+		opts:Option ,
 		owl:ObjectProperty ;
 	rdfs:domain morph:MorphPort ;
-	rdfs:label "supports type" ;
+	rdfs:label "current type" ;
 	lv2:documentation """
-<p>Indicates that a port supports being switched to a certain type via
-morph:interface.</p>
+<p>The currently active type of the port.  This is for dynamic use as an option
+and SHOULD NOT be listed in the static plugin data.</p>
 """ .
diff --git a/lv2/lv2plug.in/ns/ext/options/options.h b/lv2/lv2plug.in/ns/ext/options/options.h
index 089464a..1a71a3e 100644
--- a/lv2/lv2plug.in/ns/ext/options/options.h
+++ b/lv2/lv2plug.in/ns/ext/options/options.h
@@ -20,11 +20,13 @@
 #include <stdint.h>
 
 #include "lv2/lv2plug.in/ns/ext/urid/urid.h"
+#include "lv2/lv2plug.in/ns/lv2core/lv2.h"
 
 #define LV2_OPTIONS_URI    "http://lv2plug.in/ns/ext/options"
 #define LV2_OPTIONS_PREFIX LV2_OPTIONS_URI "#"
 
 #define LV2_OPTIONS__Option          LV2_OPTIONS_PREFIX "Option"
+#define LV2_OPTIONS__interface       LV2_OPTIONS_PREFIX "interface"
 #define LV2_OPTIONS__options         LV2_OPTIONS_PREFIX "options"
 #define LV2_OPTIONS__requiredOption  LV2_OPTIONS_PREFIX "requiredOption"
 #define LV2_OPTIONS__supportedOption LV2_OPTIONS_PREFIX "supportedOption"
@@ -34,18 +36,95 @@ extern "C" {
 #endif
 
 /**
-   An instantiation time option.
+   The context of an Option, which defines the subject it applies to.
+*/
+typedef enum {
+	/**
+	   This option applies to the instance itself.  The subject must be
+	   ignored.
+	*/
+	LV2_OPTIONS_INSTANCE,
+
+	/**
+	   This option applies to some named resource.  The subject is a URI mapped
+	   to an integer (a LV2_URID, like the key)
+	*/
+	LV2_OPTIONS_RESOURCE,
+
+	/**
+	   This option applies to some blank node.  The subject is a blank node
+	   identifier, which is valid only within the current local scope.
+	*/
+	LV2_OPTIONS_BLANK,
 
-   An array of these is passed to the instantiate method in a Feature with URI
-   LV2_OPTIONS__options .
+	/**
+	   This option applies to a port on the instance.  The subject is the
+	   port's index.
+	*/
+	LV2_OPTIONS_PORT
+} LV2_Options_Context;
+
+/**
+   An option.
+
+   This is a property with a subject, also known as a triple or statement.
+
+   This struct is useful anywhere a statement needs to be passed where no
+   memory ownership issues are present (since the value is a const pointer).
+
+   Options can be passed to an instance via the feature LV2_OPTIONS__options
+   with data pointed to an array of options terminated by a zeroed option, or
+   accessed/manipulated using LV2_Options_Interface.
 */
-typedef struct {
-	LV2_URID    key;    /**< Key (a property URID). */
-	uint32_t    size;   /**< Size of value in bytes. */
-	LV2_URID    type;   /**< Type of value (a datatype URID). */
-	const void* value;  /**< Pointer to value. */
+typedef struct _LV2_Options_Option {
+	LV2_Options_Context context;  /**< Context (type of subject). */
+	uint32_t            subject;  /**< Subject. */
+	LV2_URID            key;      /**< Key (property). */
+	uint32_t            size;     /**< Size of value in bytes. */
+	LV2_URID            type;     /**< Type of value (datatype). */
+	const void*         value;    /**< Pointer to value (object). */
 } LV2_Options_Option;
 
+/** A status code for option functions. */
+typedef enum {
+	LV2_OPTIONS_SUCCESS         = 0,       /**< Completed successfully. */
+	LV2_OPTIONS_ERR_UNKNOWN     = 1,       /**< Unknown error. */
+	LV2_OPTIONS_ERR_BAD_SUBJECT = 1 << 1,  /**< Invalid/unsupported subject. */
+	LV2_OPTIONS_ERR_BAD_KEY     = 1 << 2,  /**< Invalid/unsupported key. */
+	LV2_OPTIONS_ERR_BAD_VALUE   = 1 << 3   /**< Invalid/unsupported value. */
+} LV2_Options_Status;
+
+/**
+   Interface for dynamically setting options (LV2_OPTIONS__interface).
+*/
+typedef struct _LV2_Options_Interface {
+	/**
+	   Get the given options.
+
+	   Each element of the passed options array MUST have type, subject, and
+	   key set.  All other fields (size, type, value) MUST be initialised to
+	   zero, and are set to the option value if such an option is found.
+
+	   This function is in the "instantiation" LV2 threading class, so no other
+	   instance functions may be called concurrently.
+
+	   @return Bitwise OR of LV2_Options_Status values.
+	*/
+	uint32_t (*get)(LV2_Handle          instance,
+	                LV2_Options_Option* options);
+
+	/**
+	   Set the given options.
+
+	   This function is in the "instantiation" LV2 threading class, so no other
+	   instance functions may be called concurrently.
+
+	   @return Bitwise OR of LV2_Options_Status values.
+	*/
+	uint32_t (*set)(LV2_Handle                instance,
+	                const LV2_Options_Option* options);
+} LV2_Options_Interface;
+
 #ifdef __cplusplus
 }  /* extern "C" */
 #endif
diff --git a/lv2/lv2plug.in/ns/ext/options/options.ttl b/lv2/lv2plug.in/ns/ext/options/options.ttl
index c66aff3..12ac4aa 100644
--- a/lv2/lv2plug.in/ns/ext/options/options.ttl
+++ b/lv2/lv2plug.in/ns/ext/options/options.ttl
@@ -11,18 +11,17 @@
 		<../../meta/meta.ttl> ,
 		<lv2-options.doap.ttl> ;
 	lv2:documentation """
-<p>This extension defines a facility for <q>options</q>, which are parameters
-passed to a plugin, UI, or other instance at instantiation time.  Like the
-command-line <em>options</em> of a program, options do not change over the
-lifetime of an instance.</p>
 
-<p>Because they are available at instantiation time, options are useful for
-adding parameters which are not suitable for dynamic control, such as those
-that require expensive pre-computation.  They are also useful for providing
-information which would not otherwise be available.</p>
+<p>This extension defines a facility for <q>options</q>, which are dynamic
+properties that may be changed at run time.</p>
 
-<p>Options are provided to instances by the host via the opts:options
-feature.</p>
+<p>There are two facilities for passing options to an instance: opts:options
+allows passing options at instantiation time, and the opts:interface interface
+allows options to be dynamically set and retrieved after instantiation.</p>
+
+<p>Note that this extension is only for allowing hosts to configure plugins,
+and is not a <q>live</q> control mechanism.  For real-time control, use
+event-based control via an atom:AtomPort with an atom:Sequence buffer.</p>
 
 <p>Instances may indicate they <q>require</q> an option with the
 opts:requiredOption property, or that they optionally <q>support</q> an option
@@ -43,6 +42,23 @@ given this type for documentation purposes, and to assist hosts in discovering
 option definitions.</p>
 """ .
 
+opts:interface
+	a lv2:ExtensionData ;
+	lv2:documentation """
+<p>An interface (LV2_Options_Interface) for dynamically setting and getting
+options.  Note this is intended for use by the host for configuring plugins
+only, and and is <em>not</em> a <q>live</q> plugin control mechanism.</p>
+
+<p>The plugin data file should describe this like so:</p>
+<pre class="turtle-code">
+@prefix opts: &lt;http://lv2plug.in/ns/ext/options#&gt; .
+
+&lt;plugin&gt;
+    a lv2:Plugin ;
+    lv2:extensionData opts:interface .
+</pre>
+""" .
+
 opts:options
 	a lv2:Feature ;
 	rdfs:label "options" ;