diff options
Diffstat (limited to 'slv2')
| -rw-r--r-- | slv2/lv2.h | 2 | ||||
| -rw-r--r-- | slv2/plugin.h | 60 | ||||
| -rw-r--r-- | slv2/pluginlist.h | 36 | ||||
| -rw-r--r-- | slv2/port.h | 18 | ||||
| -rw-r--r-- | slv2/stringlist.h | 11 | ||||
| -rw-r--r-- | slv2/types.h | 7 | ||||
| -rw-r--r-- | slv2/world.h | 75 |
7 files changed, 128 insertions, 81 deletions
@@ -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, |