aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/lv2plug.in/ns/lv2core
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2014-04-26 20:01:35 +0000
committerDavid Robillard <d@drobilla.net>2014-04-26 20:01:35 +0000
commitc35b46cb80712a0c84fa87f9a55ba7fbf21e1963 (patch)
treed1d5b5d8310a3ea686da250e7222b3be89f487ea /lv2/lv2plug.in/ns/lv2core
parentf95dfae4da8502375151e59099349e30973371a3 (diff)
downloadlv2-c35b46cb80712a0c84fa87f9a55ba7fbf21e1963.tar.xz
Improve documentation.
Diffstat (limited to 'lv2/lv2plug.in/ns/lv2core')
-rw-r--r--lv2/lv2plug.in/ns/lv2core/lv2.h21
-rw-r--r--lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl9
-rw-r--r--lv2/lv2plug.in/ns/lv2core/lv2core.ttl32
-rw-r--r--lv2/lv2plug.in/ns/lv2core/manifest.ttl2
4 files changed, 39 insertions, 25 deletions
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 @@
<http://drobilla.net/drobilla#me> ;
doap:maintainer <http://drobilla.net/drobilla#me> ;
doap:release [
+ doap:revision "12.1" ;
+ doap:created "2014-04-26" ;
+ dcs:blame <http://drobilla.net/drobilla#me> ;
+ 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 <http://lv2plug.in/spec/lv2-1.8.0.tar.bz2> ;
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.</p>
<p>An LV2 plugin library is suitable for dynamic loading (e.g. via
-<code>dlopen()</code>) and provides one or more plugin descriptors via the
-<code>lv2_descriptor()</code> function. These can be instantiated to create
-plugin <q>instances</q>, which can be run directly on data or connected
-together to perform advanced signal processing tasks.</p>
+<code>dlopen()</code>) and provides one or more plugin descriptors via
+<code>lv2_descriptor()</code> or <code>lv2_lib_descriptor()</code>. These can
+be instantiated to create plugin <q>instances</q>, which can be run directly on
+data or connected together to perform advanced signal processing tasks.</p>
<p>Plugins communicate via <q>ports</q>, which can transmit any type of data.
Data is processed by first <q>connecting</q> each port to a buffer, then
@@ -92,10 +92,11 @@ into several threading classes:</p>
<tr><td>lv2_descriptor()</td>
<td>LV2_Descriptor::instantiate()</td>
<td>LV2_Descriptor::run()</td></tr>
-<tr><td>LV2_Descriptor::extension_data()</td>
+<tr><td>lv2_lib_descriptor()</td>
<td>LV2_Descriptor::cleanup()</td>
<td>LV2_Descriptor::connect_port()</td></tr>
-<tr><td></td><td>LV2_Descriptor::activate()</td><td></td></tr>
+<tr><td>LV2_Descriptor::extension_data()</td>
+ <td>LV2_Descriptor::activate()</td><td></td></tr>
<tr><td></td><td>LV2_Descriptor::deactivate()</td><td></td></tr>
</table>
@@ -416,10 +417,11 @@ resolves to a shared library object (the actual type of this library is system
specific).</p>
<p>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 <code>lv2_descriptor()</code> 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.</p>
+bundle's manifest.ttl file. The lv2:binary of an lv2:Plugin is the shared
+object containing the <code>lv2_descriptor()</code> or
+<code>lv2_lib_descriptor()</code> 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.</p>
""" .
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 """
+<p>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.</p>
""" .
lv2:extensionData
@@ -701,7 +703,7 @@ lv2:extensionData
rdfs:label "extension data" ;
lv2:documentation """
<p>Signifies that a plugin provides additional data or functions (as defined by
-some extension) via LV2:Descriptor::instantiate().</p>
+some extension) via LV2_Descriptor::instantiate().</p>
""" .
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 @@
<http://lv2plug.in/ns/lv2core>
a lv2:Specification ;
lv2:minorVersion 12 ;
- lv2:microVersion 0 ;
+ lv2:microVersion 1 ;
rdfs:seeAlso <lv2core.ttl> .