summaryrefslogtreecommitdiffstats
path: root/slv2/world.h
diff options
context:
space:
mode:
Diffstat (limited to 'slv2/world.h')
-rw-r--r--slv2/world.h71
1 files changed, 24 insertions, 47 deletions
diff --git a/slv2/world.h b/slv2/world.h
index 8bd4b35..c360642 100644
--- a/slv2/world.h
+++ b/slv2/world.h
@@ -25,7 +25,7 @@ extern "C" {
#include "slv2/collections.h"
-/** \defgroup slv2_world Global library state
+/** @defgroup slv2_world Global library state
*
* The "world" represents all library state, and the data found in bundles'
* manifest.ttl (ie it is an in-memory index of all things LV2 found).
@@ -33,7 +33,7 @@ extern "C" {
* extensions) itself can be queried from the world for use.
*
* Normal hosts which just want to easily load plugins by URI are strongly
- * recommended to simply call \ref slv2_world_load_all to find all installed
+ * recommended to simply call @ref slv2_world_load_all to find all installed
* data in the recommended way.
*
* Normal hosts should NOT have to refer to bundles directly under normal
@@ -45,7 +45,6 @@ extern "C" {
*/
/** Initialize a new, empty world.
- *
* If initialization fails, NULL is returned.
*/
SLV2_API
@@ -69,49 +68,38 @@ slv2_world_set_option(SLV2World world,
const SLV2Value value);
/** Destroy the world, mwahaha.
- *
- * NB: Destroying the world will leave dangling references in any plugin lists,
- * plugins, etc. Do not destroy the world until you are finished with all
- * objects that came from it.
+ * Note that destroying @a world will destroy all the objects it contains
+ * (e.g. instances of SLV2Plugin). Do not destroy the world until you are
+ * finished with all objects that came from it.
*/
SLV2_API
void
slv2_world_free(SLV2World world);
/** Load all installed LV2 bundles on the system.
- *
- * This is the recommended way for hosts to load LV2 data. It does the most
- * reasonable thing to find all installed plugins, extensions, etc. on the
- * system. The environment variable LV2_PATH may be used to set the
- * directories inside which this function will look for bundles. Otherwise
- * a sensible, standard default will be used.
- *
- * Use of other functions for loading bundles is \em highly discouraged
- * without a special reason to do so - use this one.
- *
- * Time = Query
+ * This is the recommended way for hosts to load LV2 data. It implements the
+ * established/standard best practice for discovering all LV2 data on the
+ * system. The environment variable LV2_PATH may be used to control where
+ * this function will look for bundles.
+ *
+ * Hosts should use this function rather than explicitly load bundles, except
+ * in special circumstances (e.g. development utilities, or hosts that ship
+ * with special plugin bundles which are installed to a known location).
*/
SLV2_API
void
slv2_world_load_all(SLV2World world);
/** Load a specific bundle.
+ * @a bundle_uri must be a fully qualified URI to the bundle directory,
+ * with the trailing slash, eg. file:///usr/lib/lv2/foo.lv2/
*
- * \arg bundle_uri A fully qualified URI to the bundle directory,
- * with the trailing slash, eg. file:///usr/lib/lv2/someBundle/
- *
- * Normal hosts should not use this function.
- *
- * Hosts should \b never attach any long-term significance to bundle paths
- * as there are no guarantees they will remain consistent whatsoever.
- * Plugins (and other things) are identified by URIs, \b not bundle or
- * file names.
- *
- * This function should only be used by apps which ship with a special
- * bundle (which it knows exists at some path because the bundle is
- * shipped with the application).
+ * Normal hosts should not need this function (use slv2_world_load_all).
*
- * Time = Query
+ * Hosts MUST NOT attach any long-term significance to bundle paths
+ * (e.g. in save files), since there are no guarantees they will remain
+ * unchanged between (or even during) program invocations. Plugins (among
+ * other things) MUST be identified by URIs (not paths) in save files.
*/
SLV2_API
void
@@ -119,25 +107,19 @@ slv2_world_load_bundle(SLV2World world,
SLV2Value bundle_uri);
/** Get the parent of all other plugin classes, lv2:Plugin.
- *
- * Time = O(1)
*/
SLV2_API
SLV2PluginClass
slv2_world_get_plugin_class(SLV2World world);
/** Return a list of all found plugin classes.
- *
* Returned list is owned by world and must not be freed by the caller.
- *
- * Time = O(1)
*/
SLV2_API
SLV2PluginClasses
slv2_world_get_plugin_classes(SLV2World world);
/** Return a list of all found plugins.
- *
* The returned list contains just enough references to query
* or instantiate plugins. The data for a particular plugin will not be
* loaded into memory until a call to an slv2_plugin_* function results in
@@ -145,24 +127,19 @@ slv2_world_get_plugin_classes(SLV2World world);
* queries are very fast).
*
* Returned list must be freed by user with slv2_plugins_free. The contained
- * plugins are owned by \a world and must not be freed by caller.
- *
- * Time = O(1)
+ * plugins are owned by @a world and must not be freed by caller.
*/
SLV2_API
SLV2Plugins
slv2_world_get_all_plugins(SLV2World world);
/** Return a list of found plugins filtered by a user-defined filter function.
- *
- * All plugins currently found in \a world that return true when passed to
- * \a include (a pointer to a function which takes an SLV2Plugin and returns
+ * All plugins currently found in @a world that return true when passed to
+ * @a include (a pointer to a function which takes an SLV2Plugin and returns
* a bool) will be in the returned list.
*
* Returned list must be freed by user with slv2_plugins_free. The contained
- * plugins are owned by \a world and must not be freed by caller.
- *
- * Time = O(n * Time(include))
+ * plugins are owned by @a world and must not be freed by caller.
*/
SLV2_API
SLV2Plugins