From d596bb4bedbf9ff267cfe924bb4d376213efd3ec Mon Sep 17 00:00:00 2001 From: David Robillard 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); * * <plugin-uri> predicate ?object * - * 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