From c35b46cb80712a0c84fa87f9a55ba7fbf21e1963 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sat, 26 Apr 2014 20:01:35 +0000 Subject: Improve documentation. --- lv2/lv2plug.in/ns/lv2core/lv2.h | 21 +++++++++++--------- lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl | 9 +++++++++ lv2/lv2plug.in/ns/lv2core/lv2core.ttl | 32 ++++++++++++++++-------------- lv2/lv2plug.in/ns/lv2core/manifest.ttl | 2 +- 4 files changed, 39 insertions(+), 25 deletions(-) (limited to 'lv2/lv2plug.in/ns/lv2core') diff --git a/lv2/lv2plug.in/ns/lv2core/lv2.h b/lv2/lv2plug.in/ns/lv2core/lv2.h index 220fbb0..6e0edaa 100644 --- a/lv2/lv2plug.in/ns/lv2core/lv2.h +++ b/lv2/lv2plug.in/ns/lv2core/lv2.h @@ -353,19 +353,15 @@ typedef struct _LV2_Descriptor { /** Prototype for plugin accessor function. - This is part of the old discovery API, which has been replaced due to being - inadequate for some plugins. It is limited because the bundle path is not - available during discovery, and it relies on non-portable shared library - constructors/destructors. However, this API is still supported and plugins - are not required to migrate. - Plugins are discovered by hosts using RDF data (not by loading libraries). See http://lv2plug.in for details on the discovery process, though most hosts should use an existing library to implement this functionality. - A plugin library MUST include a function called "lv2_descriptor" with this - prototype. This function MUST have C-style linkage (if you are using C++ - this is taken care of by the 'extern "C"' clause at the top of this file). + This is the simple plugin discovery API, suitable for most statically + defined plugins. Advanced plugins that need access to their bundle during + discovery can use lv2_lib_descriptor() instead. Plugin libraries MUST + include a function called "lv2_descriptor" or "lv2_lib_descriptor" with + C-style linkage, but SHOULD provide "lv2_descriptor" wherever possible. When it is time to load a plugin (designated by its URI), the host loads the plugin's library, gets the lv2_descriptor() function from it, and uses this @@ -431,6 +427,13 @@ typedef struct { /** Prototype for library accessor function. + This is the more advanced discovery API, which allows plugin libraries to + access their bundles during discovery, which makes it possible for plugins to + be dynamically defined by files in their bundle. This API also has an + explicit cleanup function, removing any need for non-portable shared library + destructors. Simple plugins that do not require these features may use + lv2_descriptor() instead. + This is the entry point for a plugin library. Hosts load this symbol from the library and call this function to obtain a library descriptor which can be used to access all the contained plugins. The returned object must not diff --git a/lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl b/lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl index df919b6..273a2f9 100644 --- a/lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl +++ b/lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl @@ -16,6 +16,15 @@ ; doap:maintainer ; doap:release [ + doap:revision "12.1" ; + doap:created "2014-04-26" ; + dcs:blame ; + dcs:changeset [ + dcs:item [ + rdfs:label "Clarify lv2_descriptor() and lv2_lib_descriptor() documentation." + ] + ] + ] , [ doap:revision "12.0" ; doap:created "2014-01-04" ; doap:file-release ; diff --git a/lv2/lv2plug.in/ns/lv2core/lv2core.ttl b/lv2/lv2plug.in/ns/lv2core/lv2core.ttl index 7fbffd4..b48b4ca 100644 --- a/lv2/lv2plug.in/ns/lv2core/lv2core.ttl +++ b/lv2/lv2plug.in/ns/lv2core/lv2core.ttl @@ -61,10 +61,10 @@ and non-C programs to work with LV2 data. LV2 itself and extensions are distributed in a similar way.

An LV2 plugin library is suitable for dynamic loading (e.g. via -dlopen()) and provides one or more plugin descriptors via the -lv2_descriptor() function. These can be instantiated to create -plugin instances, which can be run directly on data or connected -together to perform advanced signal processing tasks.

+dlopen()) and provides one or more plugin descriptors via +lv2_descriptor() or lv2_lib_descriptor(). These can +be instantiated to create plugin instances, which can be run directly on +data or connected together to perform advanced signal processing tasks.

Plugins communicate via ports, which can transmit any type of data. Data is processed by first connecting each port to a buffer, then @@ -92,10 +92,11 @@ into several threading classes:

lv2_descriptor() LV2_Descriptor::instantiate() LV2_Descriptor::run() -LV2_Descriptor::extension_data() +lv2_lib_descriptor() LV2_Descriptor::cleanup() LV2_Descriptor::connect_port() -LV2_Descriptor::activate() +LV2_Descriptor::extension_data() + LV2_Descriptor::activate() LV2_Descriptor::deactivate() @@ -416,10 +417,11 @@ resolves to a shared library object (the actual type of this library is system specific).

This is a required property of a Plugin which MUST be included in the -bundle's manifest.ttl file. The lv2:binary of an lv2:Plugin is the -shared object containing the lv2_descriptor() function which can -be used to access the descriptor for that plugin. This property may be used -similarly by extensions to relate other resources to their implementations.

+bundle's manifest.ttl file. The lv2:binary of an lv2:Plugin is the shared +object containing the lv2_descriptor() or +lv2_lib_descriptor() function which can be used to access the +descriptor for that plugin. This property may be used similarly by extensions +to relate other resources to their implementations.

""" . lv2:appliesTo @@ -688,10 +690,10 @@ lv2:ExtensionData a rdfs:Class , owl:Class ; rdfs:label "Extension Data" ; - rdfs:comment """ -Additional data and/or functions a plugin may return from -LV2_Descriptor:extension_data() which can be used to add additional API beyond -that defined by LV2_Descriptor. + lv2:documentation """ +

Additional data and/or functions a plugin may return from +LV2_Descriptor::extension_data() which can be used to add additional API beyond +that defined by LV2_Descriptor.

""" . lv2:extensionData @@ -701,7 +703,7 @@ lv2:extensionData rdfs:label "extension data" ; lv2:documentation """

Signifies that a plugin provides additional data or functions (as defined by -some extension) via LV2:Descriptor::instantiate().

+some extension) via LV2_Descriptor::instantiate().

""" . lv2:isLive diff --git a/lv2/lv2plug.in/ns/lv2core/manifest.ttl b/lv2/lv2plug.in/ns/lv2core/manifest.ttl index 6e1c389..fcced8c 100644 --- a/lv2/lv2plug.in/ns/lv2core/manifest.ttl +++ b/lv2/lv2plug.in/ns/lv2core/manifest.ttl @@ -5,5 +5,5 @@ a lv2:Specification ; lv2:minorVersion 12 ; - lv2:microVersion 0 ; + lv2:microVersion 1 ; rdfs:seeAlso . -- cgit v1.2.1