path: root/lv2/lv2plug.in/ns/lv2core/lv2.h
diff options
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/lv2.h
parentf95dfae4da8502375151e59099349e30973371a3 (diff)
Improve documentation.
Diffstat (limited to 'lv2/lv2plug.in/ns/lv2core/lv2.h')
1 files changed, 12 insertions, 9 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