Updated LV2 spec.

git-svn-id: http://svn.drobilla.net/lad/slv2@809 a436a847-0d15-0410-975c-d299462d15a1

6 files changed, 56 insertions, 75 deletions

diff --git a/slv2/lv2.h b/slv2/lv2.h
index 7c856d6..e19ff1e 100644
--- a/slv2/lv2.h
+++ b/slv2/lv2.h
@@ -1,5 +1,5 @@
 /* LV2 - LADSPA (Linux Audio Developer's Simple Plugin API) Version 2.0
- * *** PROVISIONAL Revision 1.0beta5 (2007-09-23) ***
+ * *** PROVISIONAL Revision 1.0beta6 (2007-10-03) ***
  *
  * Copyright (C) 2000-2002 Richard W.E. Furse, Paul Barton-Davis,
  *                         Stefan Westerfeld.
@@ -36,7 +36,7 @@ extern "C" {
 
 /** @file lv2.h
  *
- * Revision: 1.0beta5
+ * Revision: 1.0beta6
  *
  * == Overview ==
  *
@@ -121,14 +121,15 @@ typedef void * LV2_Handle;
 /* ************************************************************************* */
 
 
-/** Host feature.
+/** Feature data.
  * 
  * These are passed to a plugin's instantiate method to represent a special
  * feature the host has which the plugin may depend on.  This is to allow
- * extensions to the LV2 specification without causing any breakage.  The base
- * LV2 specification does not define any host features; hosts are not required
+ * extensions to the LV2 specification without causing any breakage.
+ * Extensions may specify what data needs to be passed here.  The base
+ * LV2 specification does not define any features; hosts are not required
  * to use this facility. */
-typedef struct _LV2_Host_Feature {
+typedef struct _LV2_Feature {
 	/** A globally unique, case-sensitive identifier for this feature.
 	 *
 	 * This MUST be defined in the specification of any LV2 extension which
@@ -144,7 +145,7 @@ typedef struct _LV2_Host_Feature {
 	 * this feature.
 	 * If no data is required, this may be set to NULL. */
 	void * data;
-} LV2_Host_Feature;
+} LV2_Feature;
 
 
 /* ************************************************************************* */
@@ -192,10 +193,10 @@ typedef struct _LV2_Descriptor {
 	 * Note that instance initialisation should generally occur in
 	 * activate() rather than here.  If a host calls instantiate, it MUST
 	 * call cleanup() at some point in the future. */
-	LV2_Handle (*instantiate)(const struct _LV2_Descriptor *  descriptor,
-	                          double                          sample_rate,
-	                          const char *                    bundle_path,
-	                          const LV2_Host_Feature *const * host_features);
+	LV2_Handle (*instantiate)(const struct _LV2_Descriptor * descriptor,
+	                          double                         sample_rate,
+	                          const char *                   bundle_path,
+	                          const LV2_Feature *const *     features);
 
 	/** Function pointer that connects a port on a plugin instance to a memory
 	 * location where the block of data for the port will be read/written.
@@ -229,7 +230,7 @@ typedef struct _LV2_Descriptor {
 	 * However, overlapped buffers or use of a single buffer for both
 	 * audio and control data may result in unexpected behaviour.
 	 *
-	 * If the plugin has the property lv2:hardRTCapable then there are 
+	 * If the plugin has the feature lv2:hardRTCapable then there are 
 	 * various things that the plugin MUST NOT do within the connect_port()
 	 * function (see lv2.ttl). */
 	void (*connect_port)(LV2_Handle instance,
@@ -271,7 +272,7 @@ typedef struct _LV2_Descriptor {
 	 * the plugin instance may not be reused until activate() has been
 	 * called again.
 	 *
-	 * If the plugin has the property lv2:hardRTCapable then there are 
+	 * If the plugin has the feature lv2:hardRTCapable then there are 
 	 * various things that the plugin MUST NOT do within the run()
 	 * function (see lv2.ttl). */
 	void (*run)(LV2_Handle instance,
diff --git a/slv2/lv2_gui.h b/slv2/lv2_gui.h
index 696f20b..7b108b3 100644
--- a/slv2/lv2_gui.h
+++ b/slv2/lv2_gui.h
@@ -210,7 +210,7 @@ typedef struct _LV2UI_Descriptor {
                               LV2UI_Program_Save_Function     save_function,
                               LV2UI_Controller                controller,
                               LV2UI_Widget*                   widget,
-                              const LV2_Host_Feature* const*  host_features);
+                              const LV2_Feature* const*       features);
 
   
   /** Destroy the GUI object and the associated widget. 
diff --git a/slv2/plugin.h b/slv2/plugin.h
index 94b5a93..c22fda5 100644
--- a/slv2/plugin.h
+++ b/slv2/plugin.h
@@ -153,7 +153,7 @@ slv2_plugin_get_class(SLV2Plugin plugin);
  *
  * <code>&lt;plugin-uri&gt; predicate ?object</code>
  * 
- * May return NULL if the property was not found, or if object is not
+ * May return NULL if the property was not found, or if object(s) is not
  * sensibly represented as an SLV2Values (e.g. blank nodes).
  *
  * Return value must be freed by caller with slv2_values_free.
@@ -195,31 +195,51 @@ slv2_plugin_get_value_for_subject(SLV2Plugin  p,
                                   const char* predicate);
 
 
-/** Get the LV2 Properties of a plugin.
+/** Get the LV2 Features supported (required or optionally) by a plugin.
+ *
+ * A feature is "supported" by a plugin if it is required OR optional.
+ *
+ * Since required features have special rules the host must obey, this function
+ * probably shouldn't be used by normal hosts.  Using slv2_plugin_get_optional_features
+ * and slv2_plugin_get_required_features separately is best in most cases.
  *
- * LV2 Properties are mandatory.  Hosts MUST NOT use a plugin if they do not
- * understand all the LV2 Properties associated with that plugin (if this is
- * not what you want, see slv2_plugin_get_hints).
+ * Returned value must be freed by caller with slv2_values_free.
+ *
+ * Time = Query
+ */
+SLV2Values
+slv2_plugin_get_supported_features(SLV2Plugin p);
+
+
+/** Get the LV2 Features required by a plugin.
+ *
+ * If a feature is required by a plugin, hosts MUST NOT use the plugin if they do not
+ * understand (or are unable to support) that feature.
+ *
+ * All values returned here MUST be passed to the plugin's instantiate method
+ * (along with data, if necessary, as defined by the feature specification)
+ * or plugin instantiation will fail.
  *
  * Return value must be freed by caller with slv2_values_free.
  *
  * Time = Query
  */
 SLV2Values
-slv2_plugin_get_properties(SLV2Plugin p);
+slv2_plugin_get_required_features(SLV2Plugin p);
 
 
-/** Get the LV2 Hints of a plugin.
+/** Get the LV2 Features optionally supported by a plugin.
  *
- * LV2 Hints are suggestions that may be useful for a host.  LV2 Hints may be
- * ignored and the plugin will still function correctly.
+ * Hosts MAY ignore optional plugin features for whatever reasons.  Plugins
+ * MUST operate (at least somewhat) if they are instantiated without being
+ * passed optional features.
  *
  * Return value must be freed by caller with slv2_values_free.
  *
  * Time = Query
  */
 SLV2Values
-slv2_plugin_get_hints(SLV2Plugin p);
+slv2_plugin_get_optional_features(SLV2Plugin p);
 
 
 /** Get the number of ports on this plugin.
@@ -256,39 +276,6 @@ uint32_t
 slv2_plugin_get_latency_port(SLV2Plugin p);
 
 
-/** Get a plugin's supported host features / extensions.
- *
- * This returns a list of all supported features (both required and optional).
- *
- * Time = Query
- */
-SLV2Values
-slv2_plugin_get_supported_features(SLV2Plugin p);
-
-
-/** Get a plugin's requires host features / extensions.
- *
- * All feature URI's returned by this call MUST be passed to the plugin's
- * instantiate method for the plugin to instantiate successfully.
- *
- * Time = Query
- */
-SLV2Values
-slv2_plugin_get_required_features(SLV2Plugin p);
-
-
-/** Get a plugin's optional host features / extensions.
- *
- * If the feature URI's returned by this method are passed to the plugin's
- * instantiate method, those features will be used by the function, otherwise
- * the plugin will act as it would if it did not support that feature at all.
- *
- * Time = Query
- */
-SLV2Values
-slv2_plugin_get_optional_features(SLV2Plugin p);
-
-
 /** Query a plugin for a single variable.
  *
  * \param plugin The plugin to query.
diff --git a/slv2/plugininstance.h b/slv2/plugininstance.h
index ecaa509..982f536 100644
--- a/slv2/plugininstance.h
+++ b/slv2/plugininstance.h
@@ -72,9 +72,9 @@ typedef struct _Instance {
  * \return NULL if instantiation failed.
  */
 SLV2Instance
-slv2_plugin_instantiate(SLV2Plugin               plugin,
-                        double                   sample_rate,
-                        const LV2_Host_Feature** host_features);
+slv2_plugin_instantiate(SLV2Plugin          plugin,
+                        double              sample_rate,
+                        const LV2_Feature** features);
 
 
 /** Free a plugin instance.
diff --git a/slv2/pluginuiinstance.h b/slv2/pluginuiinstance.h
index 0ebae99..ba2ada6 100644
--- a/slv2/pluginuiinstance.h
+++ b/slv2/pluginuiinstance.h
@@ -71,7 +71,7 @@ slv2_ui_instantiate(SLV2Plugin                     plugin,
                     LV2UI_Program_Change_Function  program_function,
                     LV2UI_Program_Save_Function    save_function,
                     LV2UI_Controller               controller,
-                    const LV2_Host_Feature* const* host_features);
+                    const LV2_Feature* const*      features);
 
 
 /** Free a plugin UI instance.
diff --git a/slv2/port.h b/slv2/port.h
index 3eef680..dc477cd 100644
--- a/slv2/port.h
+++ b/slv2/port.h
@@ -33,7 +33,7 @@ extern "C" {
  */
 
 
-/** Port equivalent to slv2_plugin_get_value.
+/** Port analog of slv2_plugin_get_value.
  *
  * Time = Query
  */
@@ -43,7 +43,7 @@ slv2_port_get_value(SLV2Plugin  plugin,
                     const char* property);
 
 
-/** Port equivalent to slv2_plugin_get_properties.
+/** Return the LV2 port properties of a port.
  *
  * Time = Query
  */
@@ -52,25 +52,18 @@ slv2_port_get_properties(SLV2Plugin plugin,
                          SLV2Port   port);
 
 
-/** Port equivalent to slv2_plugin_get_hints.
- *
- * Time = Query
- */
-SLV2Values
-slv2_port_get_hints(SLV2Plugin plugin,
-                    SLV2Port   port);
-
 #if 0
-/** Return whether a port has a certain  hint.
+/** Return whether a port has a certain property.
  *
  * Time = Query
  */
 bool
-slv2_port_has_hint(SLV2Plugin p,
-                   SLV2Port   port,
-                   SLV2Value  hint)
+slv2_port_has_property(SLV2Plugin p,
+                       SLV2Port   port,
+                       SLV2Value  hint)
 #endif
 
+
 /** Get the symbol of a port given the index.
  *
  * The 'symbol' is a short string, a valid C identifier.