From d596bb4bedbf9ff267cfe924bb4d376213efd3ec Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Wed, 3 Oct 2007 18:35:52 +0000
Subject: Updated LV2 spec.
git-svn-id: http://svn.drobilla.net/lad/slv2@809 a436a847-0d15-0410-975c-d299462d15a1
---
slv2/lv2.h | 27 +++++++++---------
slv2/lv2_gui.h | 2 +-
slv2/plugin.h | 73 ++++++++++++++++++++-----------------------------
slv2/plugininstance.h | 6 ++--
slv2/pluginuiinstance.h | 2 +-
slv2/port.h | 21 +++++---------
6 files changed, 56 insertions(+), 75 deletions(-)
(limited to 'slv2')
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><plugin-uri> 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.
--
cgit v1.2.1