summaryrefslogtreecommitdiffstats
path: root/slv2
diff options
context:
space:
mode:
Diffstat (limited to 'slv2')
-rw-r--r--slv2/lv2.h2
-rw-r--r--slv2/plugin.h60
-rw-r--r--slv2/pluginlist.h36
-rw-r--r--slv2/port.h18
-rw-r--r--slv2/stringlist.h11
-rw-r--r--slv2/types.h7
-rw-r--r--slv2/world.h75
7 files changed, 128 insertions, 81 deletions
diff --git a/slv2/lv2.h b/slv2/lv2.h
index 10ea542..3e7b641 100644
--- a/slv2/lv2.h
+++ b/slv2/lv2.h
@@ -113,7 +113,7 @@ extern "C" {
*
* This plugin handle indicates a particular instance of the plugin
* concerned. It is valid to compare this to NULL (0 for C++) but
- * otherwise the host MUST not attempt to interpret it. The plugin
+ * otherwise the host MUST NOT attempt to interpret it. The plugin
* may use it to reference internal instance data. */
typedef void * LV2_Handle;
diff --git a/slv2/plugin.h b/slv2/plugin.h
index 47cb9ee..30394d3 100644
--- a/slv2/plugin.h
+++ b/slv2/plugin.h
@@ -53,11 +53,14 @@ extern "C" {
* testing utilities, etc.
*
* \return true if \a plugin is valid.
+ *
+ * Time = Query
*/
bool
slv2_plugin_verify(SLV2Plugin plugin);
+#if 0
/** Duplicate a plugin.
*
* Use this if you want to keep an SLV2Plugin around but free the list it came
@@ -68,15 +71,7 @@ slv2_plugin_verify(SLV2Plugin plugin);
*/
SLV2Plugin
slv2_plugin_duplicate(SLV2Plugin plugin);
-
-
-/** Free an SLV2Plugin.
- *
- * This should NEVER be used on a plugin contained in a Plugins. Use this
- * only with plugins created with slv2_plugin_duplicate.
- */
-void
-slv2_plugin_free(SLV2Plugin plugin);
+#endif
/** Get the URI of \a plugin.
@@ -92,6 +87,8 @@ slv2_plugin_free(SLV2Plugin plugin);
* MUST have a different URI than it's predecessor.
*
* \return a shared string which must not be modified or free()'d.
+ *
+ * Time = O(1)
*/
const char*
slv2_plugin_get_uri(SLV2Plugin plugin);
@@ -102,8 +99,10 @@ slv2_plugin_get_uri(SLV2Plugin plugin);
* Note this always returns fully qualified URIs. If you want local
* filesystem paths, use slv2_uri_to_path.
*
- * \return a complete URL eg. "file:///usr/foo/SomeBundle.lv2/someplug.ttl",
- * which is shared and must not be modified or free()'d.
+ * \return a list of complete URLs eg. "file:///foo/ABundle.lv2/aplug.ttl",
+ * which is shared and must not be modified or freed.
+ *
+ * Time = O(1)
*/
SLV2Strings
slv2_plugin_get_data_uris(SLV2Plugin plugin);
@@ -113,8 +112,10 @@ slv2_plugin_get_data_uris(SLV2Plugin plugin);
*
* Note this always returns a fully qualified URI. If you want a local
* filesystem path, use slv2_uri_to_path.
+ *
+ * \return a shared string which must not be modified or freed.
*
- * \return a shared string which must not be modified or free()'d.
+ * Time = O(1)
*/
const char*
slv2_plugin_get_library_uri(SLV2Plugin plugin);
@@ -124,8 +125,10 @@ slv2_plugin_get_library_uri(SLV2Plugin plugin);
/** Get the name of \a plugin.
*
* This is guaranteed to return the untranslated name (the doap:name in the
- * data file without a language tag). Returned value must be free()'d by
+ * data file without a language tag). Returned value must be freed by
* the caller.
+ *
+ * Time = Query
*/
char*
slv2_plugin_get_name(SLV2Plugin plugin);
@@ -141,6 +144,8 @@ slv2_plugin_get_name(SLV2Plugin plugin);
* sensibly represented as an SLV2Strings (e.g. blank nodes).
*
* Return value must be freed by caller with slv2_strings_free.
+ *
+ * Time = Query
*/
SLV2Strings
slv2_plugin_get_value(SLV2Plugin p,
@@ -160,6 +165,8 @@ slv2_plugin_get_value(SLV2Plugin p,
* sensibly represented as an SLV2Strings (e.g. blank nodes).
*
* Return value must be freed by caller with slv2_strings_free.
+ *
+ * Time = Query
*/
SLV2Strings
slv2_plugin_get_value_for_subject(SLV2Plugin p,
@@ -174,6 +181,8 @@ slv2_plugin_get_value_for_subject(SLV2Plugin p,
* not what you want, see slv2_plugin_get_hints).
*
* Return value must be freed by caller with slv2_value_free.
+ *
+ * Time = Query
*/
SLV2Strings
slv2_plugin_get_properties(SLV2Plugin p);
@@ -185,12 +194,16 @@ slv2_plugin_get_properties(SLV2Plugin p);
* ignored and the plugin will still function correctly.
*
* Return value must be freed by caller with slv2_value_free.
+ *
+ * Time = Query
*/
SLV2Strings
slv2_plugin_get_hints(SLV2Plugin p);
/** Get the number of ports on this plugin.
+ *
+ * Time = O(1)
*/
uint32_t
slv2_plugin_get_num_ports(SLV2Plugin p);
@@ -200,6 +213,8 @@ slv2_plugin_get_num_ports(SLV2Plugin p);
*
* The index of the latency port can be found with slv2_plugin_get_latency_port
* ONLY if this function returns true.
+ *
+ * Time = Query
*/
bool
slv2_plugin_has_latency(SLV2Plugin p);
@@ -214,6 +229,8 @@ slv2_plugin_has_latency(SLV2Plugin p);
* Any plugin that introduces unwanted latency that should be compensated for
* (by hosts with the ability/need) MUST provide this port, which is a control
* rate output port that reports the latency for each cycle in frames.
+ *
+ * Time = Query
*/
uint32_t
slv2_plugin_get_latency_port(SLV2Plugin p);
@@ -222,6 +239,8 @@ 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
*/
SLV2Strings
slv2_plugin_get_supported_features(SLV2Plugin p);
@@ -231,6 +250,8 @@ slv2_plugin_get_supported_features(SLV2Plugin p);
*
* 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
*/
SLV2Strings
slv2_plugin_get_required_features(SLV2Plugin p);
@@ -241,6 +262,8 @@ slv2_plugin_get_required_features(SLV2Plugin p);
* 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
*/
SLV2Strings
slv2_plugin_get_optional_features(SLV2Plugin p);
@@ -248,9 +271,12 @@ slv2_plugin_get_optional_features(SLV2Plugin p);
/** Query a plugin for a single variable.
*
+ * \param plugin The plugin to query.
* \param sparql_str A SPARQL SELECT query.
* \param variable The variable to return results for.
* \return All matches for \a variable.
+ *
+ * Time = Query
*/
SLV2Strings
slv2_plugin_simple_query(SLV2Plugin plugin,
@@ -260,7 +286,10 @@ slv2_plugin_simple_query(SLV2Plugin plugin,
/** Query a plugin and return the number of results found.
*
+ * \param plugin The plugin to query.
* \param sparql_str A SPARQL SELECT query.
+ *
+ * Time = Query
*/
unsigned
slv2_plugin_query_count(SLV2Plugin plugin,
@@ -272,7 +301,7 @@ slv2_plugin_query_count(SLV2Plugin plugin,
* To perform multiple calls on a port, the returned value should
* be cached and used repeatedly.
*
- * O(1)
+ * Time = O(1)
*/
SLV2Port
slv2_plugin_get_port_by_index(SLV2Plugin plugin,
@@ -284,14 +313,13 @@ slv2_plugin_get_port_by_index(SLV2Plugin plugin,
* To perform multiple calls on a port, the returned value should
* be cached and used repeatedly.
*
- * O(num_ports)
+ * Time = O(n)
*/
SLV2Port
slv2_plugin_get_port_by_symbol(SLV2Plugin plugin,
const char* symbol);
-
/** @} */
#ifdef __cplusplus
diff --git a/slv2/pluginlist.h b/slv2/pluginlist.h
index cd1bbf8..a2978e1 100644
--- a/slv2/pluginlist.h
+++ b/slv2/pluginlist.h
@@ -39,27 +39,14 @@ typedef void* SLV2Plugins;
*/
-/** Create a new, empty plugin list.
- *
- * Returned object must be freed with slv2_plugins_free.
- */
-SLV2Plugins
-slv2_plugins_new();
-
-
/** Free a plugin list.
*
- * Note that all plugins in the list (eg those returned by the get_plugin
- * functions) will be deleted as well. It is expected that hosts will
- * keep the plugin list allocated until they are done with their plugins.
- * If you want to keep a plugin around, but free the list it came from, you
- * will have to copy it with slv2_plugin_duplicate().
- *
- * \a list is invalid after this call (though it may be used again after a
- * "list = slv2_plugins_new()")
+ * Freeing a plugin list does not destroy the plugins it contains (plugins
+ * are owned by the world). \a list is invalid after this call.
*/
void
-slv2_plugins_free(SLV2Plugins list);
+slv2_plugins_free(SLV2World world,
+ SLV2Plugins list);
/** Get the number of plugins in the list.
@@ -73,7 +60,7 @@ slv2_plugins_size(SLV2Plugins list);
* Return value is shared (stored in \a list) and must not be freed or
* modified by the caller in any way.
*
- * O(log2(n))
+ * Time = O(log2(n))
*
* \return NULL if plugin with \a url not found in \a list.
*/
@@ -84,15 +71,12 @@ slv2_plugins_get_by_uri(SLV2Plugins list,
/** Get a plugin from the list by index.
*
- * \a index has no significance. Any \a index not less than
- * slv2list_get_length(list) will return NULL. All plugins in a list can
- * thus be easily enumerated by repeated calls to this function starting
- * with \a index 0.
- *
- * Return value is shared (stored in \a list) and must not be freed or
- * modified by the caller in any way.
+ * \a index has no significance other than as an index into this list.
+ * Any \a index not less than slv2_list_get_length(list) will return NULL,
+ * so all plugins in a list can be enumerated by repeated calls
+ * to this function starting with \a index = 0.
*
- * O(1)
+ * Time = O(1)
*
* \return NULL if \a index out of range.
*/
diff --git a/slv2/port.h b/slv2/port.h
index 13ac5c1..d415f84 100644
--- a/slv2/port.h
+++ b/slv2/port.h
@@ -34,6 +34,8 @@ extern "C" {
/** Port equivalent to slv2_plugin_get_value.
+ *
+ * Time = Query
*/
SLV2Strings
slv2_port_get_value(SLV2Plugin plugin,
@@ -42,6 +44,8 @@ slv2_port_get_value(SLV2Plugin plugin,
/** Port equivalent to slv2_plugin_get_properties.
+ *
+ * Time = Query
*/
SLV2Strings
slv2_port_get_properties(SLV2Plugin plugin,
@@ -49,6 +53,8 @@ slv2_port_get_properties(SLV2Plugin plugin,
/** Port equivalent to slv2_plugin_get_hints.
+ *
+ * Time = Query
*/
SLV2Strings
slv2_port_get_hints(SLV2Plugin plugin,
@@ -61,6 +67,8 @@ slv2_port_get_hints(SLV2Plugin plugin,
* Returned string must be free()'d by caller.
*
* \return NULL when index is out of range
+ *
+ * Time = Query
*/
char*
slv2_port_get_symbol(SLV2Plugin plugin,
@@ -71,6 +79,8 @@ slv2_port_get_symbol(SLV2Plugin plugin,
* This is guaranteed to return the untranslated name (the doap:name in the
* data file without a language tag). Returned value must be free()'d by
* the caller.
+ *
+ * Time = Query
*/
char*
slv2_port_get_name(SLV2Plugin plugin,
@@ -78,6 +88,8 @@ slv2_port_get_name(SLV2Plugin plugin,
/** Get the class (input/output, data type, rate...) of a port.
+ *
+ * Time = Query
*/
SLV2PortClass
slv2_port_get_class(SLV2Plugin plugin,
@@ -87,6 +99,8 @@ slv2_port_get_class(SLV2Plugin plugin,
/** Get the default value of a port.
*
* Only valid for ports with a data type of lv2:float.
+ *
+ * Time = Query
*/
float
slv2_port_get_default_value(SLV2Plugin plugin,
@@ -96,6 +110,8 @@ slv2_port_get_default_value(SLV2Plugin plugin,
/** Get the minimum value of a port.
*
* Only valid for ports with a data type of lv2:float.
+ *
+ * Time = Query
*/
float
slv2_port_get_minimum_value(SLV2Plugin plugin,
@@ -105,6 +121,8 @@ slv2_port_get_minimum_value(SLV2Plugin plugin,
/** Get the maximum value of a port.
*
* Only valid for ports with a data type of lv2:float.
+ *
+ * Time = Query
*/
float
slv2_port_get_maximum_value(SLV2Plugin plugin,
diff --git a/slv2/stringlist.h b/slv2/stringlist.h
index 0c42318..eb613d6 100644
--- a/slv2/stringlist.h
+++ b/slv2/stringlist.h
@@ -53,18 +53,23 @@ slv2_strings_size(SLV2Strings list);
/** Get a string from a string list at the given index.
*
* @return the element at \a index, or NULL if index is out of range.
+ *
+ * Time = O(1)
*/
const char*
slv2_strings_get_at(SLV2Strings list, unsigned index);
-/** Return whether \a list contains \a uri.
+/** Return whether \a list contains \a string.
+ *
+ * Time = O(n)
*/
bool
-slv2_strings_contains(SLV2Strings list, const char* uri);
+slv2_strings_contains(SLV2Strings list, const char* string);
-/** Free a string list. */
+/** Free a string list.
+ */
void
slv2_strings_free(SLV2Strings);
diff --git a/slv2/types.h b/slv2/types.h
index f0f9b7f..c22b2be 100644
--- a/slv2/types.h
+++ b/slv2/types.h
@@ -43,12 +43,19 @@ typedef enum _PortClass {
SLV2_MIDI_OUTPUT /**< MIDI output (LL extension) */
} SLV2PortClass;
+
+/** A port on a plugin. Opaque, but valid to compare to NULL. */
typedef struct _Port* SLV2Port;
+
+/** A plugin. Opaque, but valid to compare to NULL. */
typedef struct _Plugin* SLV2Plugin;
+
+/** The world. Opaque, but valid to compare to NULL. */
typedef struct _World* SLV2World;
+
#ifdef __cplusplus
}
#endif
diff --git a/slv2/world.h b/slv2/world.h
index 4f5b252..64f0fc2 100644
--- a/slv2/world.h
+++ b/slv2/world.h
@@ -28,17 +28,19 @@ extern "C" {
/** \defgroup world Library context, data loading, etc.
*
- * These functions deal with the data model which other SLV2 methods
- * operate with. The world contains an in-memory cache of all bundles
- * manifest.ttl files, from which you can quickly query plugins, etc.
+ * 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).
+ * Plugins (and plugin extensions) and the LV2 specification (and LV2
+ * 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 find all installed data in the recommended way with
- * \ref slv2_world_load_all rather than find and load bundles manually.
- *
- * Functions are provided for hosts that wish to access bundles explicitly and
- * individually for some reason, this is intended for hosts which are tied to
- * a specific bundle (shipped with the application).
+ * 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
+ * circumstances. However, functions are provided to load individual bundles
+ * explicitly, intended for hosts which depend on a specific bundle
+ * (which is shipped with the application).
*
* @{
*/
@@ -60,7 +62,7 @@ void
slv2_world_free(SLV2World world);
-/** Load all installed LV2 bundles on the system
+/** 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
@@ -70,60 +72,63 @@ slv2_world_free(SLV2World world);
*
* Use of other functions for loading bundles is \em highly discouraged
* without a special reason to do so - use this one.
- */
-void
-slv2_world_load_all(SLV2World world);
-
-
-/** Load all bundles found in \a search_path.
*
- * \param search_path A colon-delimited list of directories. These directories
- * should contain LV2 bundle directories (ie the search path is a list of
- * parent directories of bundles, not a list of bundle directories).
- *
- * If \a search_path is NULL, \a world will be unmodified.
- * Use of this function is \b not recommended. Use \ref slv2_world_load_all.
+ * Time = Query
*/
void
-slv2_world_load_path(SLV2World world,
- const char* search_path);
+slv2_world_load_all(SLV2World world);
-/** Load a specific bundle into \a world.
+/** Load a specific bundle.
*
- * \arg bundle_base_uri is a fully qualified URI to the bundle directory,
+ * \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 not attach \em any long-term significance to bundle paths
+ * 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 they are part of
- * the same package).
+ * bundle (which it knows exists at some path because the bundle is
+ * shipped with the application).
+ *
+ * Time = Query
*/
void
slv2_world_load_bundle(SLV2World world,
- const char* bundle_base_uri);
+ const char* bundle_uri);
-/** Add all plugins present in \a world to \a list.
+/** 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
+ * a query (at which time the data is cached with the SLV2Plugin so future
+ * queries are very fast).
*
* Returned plugins contain a reference to this world, world must not be
* destroyed until plugins are finished with.
+ *
+ * Time = O(1)
*/
SLV2Plugins
slv2_world_get_all_plugins(SLV2World world);
-/** Get plugins filtered by a user-defined filter function.
+/** Return a list of found plugins filtered by a user-defined filter function.
*
- * All plugins in \a world that return true when passed to \a include
- * (a pointer to a function that takes an SLV2Plugin and returns a bool)
- * will be added to \a list.
+ * 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 plugins contain a reference to this world, world must not be
* destroyed until plugins are finished with.
+ *
+ * Time = O(n * Time(include))
*/
SLV2Plugins
slv2_world_get_plugins_by_filter(SLV2World world,