diff options
| -rw-r--r-- | slv2/collections.h | 77 | ||||
| -rw-r--r-- | slv2/plugin.h | 155 | ||||
| -rw-r--r-- | slv2/pluginclass.h | 20 | ||||
| -rw-r--r-- | slv2/plugininstance.h | 31 | ||||
| -rw-r--r-- | slv2/pluginui.h | 37 | ||||
| -rw-r--r-- | slv2/pluginuiinstance.h | 15 | ||||
| -rw-r--r-- | slv2/port.h | 33 | ||||
| -rw-r--r-- | slv2/scalepoint.h | 8 | ||||
| -rw-r--r-- | slv2/types.h | 9 | ||||
| -rw-r--r-- | slv2/util.h | 6 | ||||
| -rw-r--r-- | slv2/value.h | 86 | ||||
| -rw-r--r-- | slv2/world.h | 71 |
12 files changed, 133 insertions, 415 deletions
diff --git a/slv2/collections.h b/slv2/collections.h index 9e816b0..ef2c35d 100644 --- a/slv2/collections.h +++ b/slv2/collections.h @@ -26,7 +26,7 @@ extern "C" { #include "slv2/types.h" #include "slv2/value.h" -/** \defgroup slv2_collections Collections of values/objects +/** @defgroup slv2_collections Collections of values/objects. * * Ordered collections of typed values which are fast for random * access by index (i.e. a fancy array). @@ -39,8 +39,6 @@ extern "C" { #define SLV2_COLLECTION(CollType, ElemType, prefix) \ \ /** Free a collection. - * - * Time = O(1) */ \ SLV2_API \ void \ @@ -48,8 +46,6 @@ prefix ## _free(CollType collection); \ \ \ /** Get the number of elements in the collection. - * - * Time = O(1) */ \ SLV2_API \ unsigned \ @@ -57,15 +53,11 @@ prefix ## _size(CollType collection); \ \ \ /** Get an element from the collection by index. - * - * \a index has no significance other than as an index into this collection. - * Any \a index not less than the size of the collection will return NULL, + * @a index has no significance other than as an index into this collection. + * Any @a index not less than the size of the collection will return NULL, * so all elements in a collection can be enumerated by repeated calls - * to this function starting with \a index = 0. - * - * Time = O(1) - * - * \return NULL if \a index out of range. + * to this function starting with @a index = 0. + * @return NULL if @a index is out of range. */ \ SLV2_API \ ElemType \ @@ -80,10 +72,8 @@ SLV2_COLLECTION(SLV2UIs, SLV2UI, slv2_uis) /* **** PLUGINS **** */ /** Free a plugin collection. - * * Freeing a plugin collection does not destroy the plugins it contains - * (plugins are owned by the world). \a plugins is invalid after this call. - * Time = O(1) + * (plugins are owned by the world). @a plugins is invalid after this call. */ SLV2_API void @@ -91,36 +81,27 @@ slv2_plugins_free(SLV2World world, SLV2Plugins plugins); /** Get the number of plugins in the collection. - * Time = O(1) */ SLV2_API unsigned slv2_plugins_size(SLV2Plugins plugins); -/** Get a plugin from the collection by URI. - * - * Return value is shared (stored in \a plugins) and must not be freed or +/** Get a plugin from @a plugins by URI. + * Return value is shared (stored in @a plugins) and must not be freed or * modified by the caller in any way. - * - * Time = O(log2(n)) - * - * \return NULL if plugin with \a url not found in \a plugins. + * @return NULL if no plugin with @a uri is found in @a plugins. */ SLV2_API SLV2Plugin slv2_plugins_get_by_uri(SLV2Plugins plugins, SLV2Value uri); -/** Get a plugin from the plugins by index. - * - * \a index has no significance other than as an index into this plugins. - * Any \a index not less than slv2_plugins_get_length(plugins) will return NULL, +/** Get a plugin from @a plugins by index. + * @a index has no significance other than as an index into this plugins. + * Any @a index not less than slv2_plugins_get_length(plugins) will return NULL, * so all plugins in a plugins can be enumerated by repeated calls - * to this function starting with \a index = 0. - * - * Time = O(1) - * - * \return NULL if \a index out of range. + * to this function starting with @a index = 0. + * @return NULL if @a index out of range. */ SLV2_API SLV2Plugin @@ -129,14 +110,10 @@ slv2_plugins_get_at(SLV2Plugins plugins, /* **** PLUGIN CLASSES **** */ -/** Get a plugin class from the collection by URI. - * - * Return value is shared (stored in \a classes) and must not be freed or +/** Get a plugin class from @a classes by URI. + * Return value is shared (stored in @a classes) and must not be freed or * modified by the caller in any way. - * - * Time = O(log2(n)) - * - * \return NULL if plugin with \a url not found in \a classes. + * @return NULL if no plugin class with @a uri is found in @a classes. */ SLV2_API SLV2PluginClass @@ -145,7 +122,7 @@ slv2_plugin_classes_get_by_uri(SLV2PluginClasses classes, /* **** SCALE POINTS **** */ -/** Allocate a new, empty SLV2ScalePoints +/** Allocate a new, empty SLV2ScalePoints. */ SLV2_API SLV2ScalePoints @@ -153,15 +130,13 @@ slv2_scale_points_new(void); /* **** VALUES **** */ -/** Allocate a new, empty SLV2Values +/** Allocate a new, empty SLV2Values. */ SLV2_API SLV2Values slv2_values_new(void); -/** Return whether \a values contains \a value. - * - * Time = O(n) +/** Return whether @a values contains @a value. */ SLV2_API bool @@ -169,18 +144,14 @@ slv2_values_contains(SLV2Values values, SLV2Value value); /* **** PLUGIN UIS **** */ -/** Get a plugin from the list by URI. - * - * Return value is shared (stored in \a list) and must not be freed or +/** Get a UI from @a uis by URI. + * Return value is shared (stored in @a uis) and must not be freed or * modified by the caller in any way. - * - * Time = O(log2(n)) - * - * \return NULL if plugin with \a url not found in \a list. + * @return NULL if no UI with @a uri is found in @a list. */ SLV2_API SLV2UI -slv2_uis_get_by_uri(SLV2UIs list, +slv2_uis_get_by_uri(SLV2UIs uis, SLV2Value uri); /** @} */ diff --git a/slv2/plugin.h b/slv2/plugin.h index e936bf4..f688626 100644 --- a/slv2/plugin.h +++ b/slv2/plugin.h @@ -29,7 +29,7 @@ extern "C" { #include "slv2/port.h" #include "slv2/collections.h" -/** \defgroup slv2_data Plugin data access +/** @defgroup slv2_data Plugin data access * * These functions work exclusively with the plugin's RDF data, * they do not access the plugin's shared library in any way. @@ -42,25 +42,19 @@ extern "C" { */ /** Check if this plugin is valid. - * - * This is used by plugin lists to avoid loading plugins that are not valid - * and will not work with libslv2 (eg plugins missing required fields, or - * having multiple values for mandatory single-valued fields, etc. + * This is not a rigorous validator, but can be used to reject some malformed + * plugins that could cause bugs (e.g. plugins with missing required fields). * * Note that normal hosts do NOT need to use this - slv2 does not * load invalid plugins into plugin lists. This is included for plugin * testing utilities, etc. - * - * \return true if \a plugin is valid. - * - * Time = Query + * @return true iff @a plugin is valid. */ SLV2_API bool slv2_plugin_verify(SLV2Plugin plugin); -/** Get the URI of \a plugin. - * +/** Get the URI of @a plugin. * Any serialization that refers to plugins should refer to them by this. * Hosts SHOULD NOT save any filesystem paths, plugin indexes, etc. in saved * files; save only the URI. @@ -71,70 +65,51 @@ slv2_plugin_verify(SLV2Plugin plugin); * is upgraded in an incompatible way (eg if it has different ports), it * MUST have a different URI than it's predecessor. * - * \return a shared string which must not be modified or free()'d. - * - * Time = O(1) + * @return A shared URI value which must not be modified or freed. */ SLV2_API SLV2Value slv2_plugin_get_uri(SLV2Plugin plugin); -/** Get the (resolvable) URI of the plugins "main" bundle. - * +/** Get the (resolvable) URI of the plugin's "main" bundle. * This returns the URI of the bundle where the plugin itself was found. * Note that the data for a plugin may be spread over many bundles, that is, - * slv2_plugin_get_data_uris may returns URIs which are not below this one. + * slv2_plugin_get_data_uris may return URIs which are not within this bundle. * * Typical hosts should not need to use this function. - * * 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. - * - * Time = O(1) + * @return a shared string which must not be modified or freed. */ SLV2_API SLV2Value slv2_plugin_get_bundle_uri(SLV2Plugin plugin); /** Get the (resolvable) URIs of the RDF data files that define a plugin. - * * Typical hosts should not need to use this function. - * * Note this always returns fully qualified URIs. If you want local * filesystem paths, use slv2_uri_to_path. - * - * \return a list of complete URLs eg. "file:///foo/ABundle.lv2/aplug.ttl", + * @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) */ SLV2_API SLV2Values slv2_plugin_get_data_uris(SLV2Plugin plugin); -/** Get the (resolvable) URI of the shared library for \a plugin. - * +/** Get the (resolvable) URI of the shared library for @a 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. - * - * Time = O(1) + * @return a shared string which must not be modified or freed. */ SLV2_API SLV2Value slv2_plugin_get_library_uri(SLV2Plugin plugin); -/** Get the name of \a plugin. - * +/** Get the name of @a plugin. * This returns the name (doap:name) of the plugin. The name may be * translated according to the current locale, this value MUST NOT be used * as a plugin identifier (use the URI for that). * Returned value must be freed by the caller. - * - * Time = Query */ SLV2_API SLV2Value @@ -147,6 +122,7 @@ SLV2PluginClass slv2_plugin_get_class(SLV2Plugin plugin); /** Get a value associated with the plugin in a plugin's data files. + * @a predicate must be either a URI or a QName. * * Returns the ?object of all triples found of the form: * @@ -154,13 +130,7 @@ slv2_plugin_get_class(SLV2Plugin plugin); * * May return NULL if the property was not found, or if object(s) is not * sensibly represented as an SLV2Values (e.g. blank nodes). - * * Return value must be freed by caller with slv2_values_free. - * - * \a predicate must be either a URI or a QName. - * See SLV2URIType documentation for examples. - * - * Time = Query */ SLV2_API SLV2Values @@ -168,7 +138,6 @@ slv2_plugin_get_value(SLV2Plugin p, SLV2Value predicate); /** Get a value associated with the plugin in a plugin's data files. - * * This function is identical to slv2_plugin_get_value, but takes a QName * string parameter for a predicate instead of an SLV2Value, which may be * more convenient. @@ -179,6 +148,7 @@ slv2_plugin_get_value_by_qname(SLV2Plugin p, const char* predicate); /** Get a value associated with some subject in a plugin's data files. + * @a predicate must be either a URI or a QName. * * Returns the ?object of all triples found of the form: * @@ -189,13 +159,7 @@ slv2_plugin_get_value_by_qname(SLV2Plugin p, * * May return NULL if the property was not found, or if object is not * sensibly represented as an SLV2Values (e.g. blank nodes). - * - * \a predicate must be either a URI or a QName. - * See SLV2URIType documentation for examples. - * * Return value must be freed by caller with slv2_values_free. - * - * Time = Query */ SLV2_API SLV2Values @@ -204,11 +168,8 @@ slv2_plugin_get_value_for_subject(SLV2Plugin p, SLV2Value predicate_uri); /** Return whether a feature is supported by a plugin. - * * This will return true if the feature is an optional or required feature * of the plugin. - * - * Time = Query */ SLV2_API bool @@ -216,7 +177,6 @@ slv2_plugin_has_feature(SLV2Plugin p, SLV2Value feature_uri); /** Get the LV2 Features supported (required or optionally) by a plugin. - * * A feature is "supported" by a plugin if it is required OR optional. * * Since required features have special rules the host must obey, this function @@ -224,15 +184,12 @@ slv2_plugin_has_feature(SLV2Plugin p, * and slv2_plugin_get_required_features separately is best in most cases. * * Returned value must be freed by caller with slv2_values_free. - * - * Time = Query */ SLV2_API SLV2Values slv2_plugin_get_supported_features(SLV2Plugin p); /** Get the LV2 Features required by a plugin. - * * If a feature is required by a plugin, hosts MUST NOT use the plugin if they do not * understand (or are unable to support) that feature. * @@ -241,38 +198,30 @@ slv2_plugin_get_supported_features(SLV2Plugin p); * or plugin instantiation will fail. * * Return value must be freed by caller with slv2_values_free. - * - * Time = Query */ SLV2_API SLV2Values slv2_plugin_get_required_features(SLV2Plugin p); /** Get the LV2 Features optionally supported by a plugin. - * * Hosts MAY ignore optional plugin features for whatever reasons. Plugins * MUST operate (at least somewhat) if they are instantiated without being * passed optional features. * * Return value must be freed by caller with slv2_values_free. - * - * Time = Query */ SLV2_API SLV2Values slv2_plugin_get_optional_features(SLV2Plugin p); /** Get the number of ports on this plugin. - * - * Time = O(1) */ SLV2_API uint32_t slv2_plugin_get_num_ports(SLV2Plugin p); /** Get the port ranges (minimum, maximum and default values) for all ports. - * - * \a min_values, \a max_values and \a def_values must either point to an array + * @a min_values, @a max_values and @a def_values must either point to an array * of N floats, where N is the value returned by slv2_plugin_get_num_ports() * for this plugin, or NULL. The elements of the array will be set to the * the minimum, maximum and default values of the ports on this plugin, @@ -292,12 +241,9 @@ slv2_plugin_get_port_ranges_float(SLV2Plugin p, float* def_values); /** Get the number of ports on this plugin that are members of some class(es). - * * Note that this is a varargs function so ports fitting any type 'profile' * desired can be found quickly. REMEMBER TO TERMINATE THE PARAMETER LIST * OF THIS FUNCTION WITH NULL OR VERY NASTY THINGS WILL HAPPEN. - * - * Time = O(1) */ SLV2_API uint32_t @@ -305,82 +251,35 @@ slv2_plugin_get_num_ports_of_class(SLV2Plugin p, SLV2Value class_1, ...); /** Return whether or not the plugin introduces (and reports) latency. - * * The index of the latency port can be found with slv2_plugin_get_latency_port * ONLY if this function returns true. - * - * Time = Query */ SLV2_API bool slv2_plugin_has_latency(SLV2Plugin p); /** Return the index of the plugin's latency port. - * * It is a fatal error to call this on a plugin without checking if the port * exists by first calling slv2_plugin_has_latency. * * 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 */ SLV2_API uint32_t slv2_plugin_get_latency_port_index(SLV2Plugin p); -/** Query a plugin for a single variable (i.e. SELECT a single ?value). - * - * \param plugin The plugin to query. - * \param sparql_str A SPARQL SELECT query. - * \param variable The index of the variable to return results for - * (e.g. with "<code>SELECT ?foo ?bar</code>" foo=0, bar=1). - * \return All matches for \a variable. - * - * Time = Query - */ -SLV2_API -SLV2Values -slv2_plugin_query_variable(SLV2Plugin plugin, - const char* sparql_str, - unsigned variable); - -/** Query a plugin and return the number of results found. - * - * Note that this function will work, but is mostly meaningless for queries - * that are not SELECT DISTINCT. - * - * \param plugin The plugin to query. - * \param sparql_str A SPARQL SELECT DISTINCT query. - * - * Time = Query - */ -SLV2_API -unsigned -slv2_plugin_query_count(SLV2Plugin plugin, - const char* sparql_str); - -/** Get a port on this plugin by \a index. - * - * To perform multiple calls on a port, the returned value should - * be cached and used repeatedly. - * - * Time = O(1) +/** Get a port on @a plugin by @a index. */ SLV2_API SLV2Port slv2_plugin_get_port_by_index(SLV2Plugin plugin, uint32_t index); -/** Get a port on this plugin by \a symbol. - * - * To perform multiple calls on a port, the returned value should - * be cached and used repeatedly. Note this function is slower - * than slv2_plugin_get_port_by_index, especially on plugins - * with a very large number of ports. - * - * Time = O(n) +/** Get a port on @a plugin by @a symbol. + * Note this function is slower than slv2_plugin_get_port_by_index, + * especially on plugins with a very large number of ports. */ SLV2_API SLV2Port @@ -388,49 +287,35 @@ slv2_plugin_get_port_by_symbol(SLV2Plugin plugin, SLV2Value symbol); /** Get a list of all UIs available for this plugin. - * * Note this returns the URI of the UI, and not the path/URI to its shared * library, use slv2_ui_get_library_uri with the values returned * here for that. * * Returned value must be freed by caller using slv2_uis_free. - * - * \param plugin The plugin to get the UIs for. - * - * Time = Query */ SLV2_API SLV2UIs slv2_plugin_get_uis(SLV2Plugin plugin); /** Get the full name of the plugin's author. - * * Returns NULL if author name is not present. * Returned value must be freed by caller. - * - * Time = Query */ SLV2_API SLV2Value slv2_plugin_get_author_name(SLV2Plugin plugin); /** Get the email address of the plugin's author. - * * Returns NULL if author email address is not present. * Returned value must be freed by caller. - * - * Time = Query */ SLV2_API SLV2Value slv2_plugin_get_author_email(SLV2Plugin plugin); /** Get the email address of the plugin's author. - * * Returns NULL if author homepage is not present. * Returned value must be freed by caller. - * - * Time = Query */ SLV2_API SLV2Value diff --git a/slv2/pluginclass.h b/slv2/pluginclass.h index 9adf551..f059522 100644 --- a/slv2/pluginclass.h +++ b/slv2/pluginclass.h @@ -25,45 +25,33 @@ extern "C" { #include "slv2/types.h" -/** \addtogroup slv2_data +/** @addtogroup slv2_data * @{ */ /** Get the URI of this class' superclass. - * - * Returned value is owned by \a plugin_class and must not be freed by caller. + * Returned value is owned by @a plugin_class and must not be freed by caller. * Returned value may be NULL, if class has no parent. - * - * Time = O(1) */ SLV2_API SLV2Value slv2_plugin_class_get_parent_uri(SLV2PluginClass plugin_class); /** Get the URI of this plugin class. - * - * Returned value is owned by \a plugin_class and must not be freed by caller. - * - * Time = O(1) + * Returned value is owned by @a plugin_class and must not be freed by caller. */ SLV2_API SLV2Value slv2_plugin_class_get_uri(SLV2PluginClass plugin_class); /** Get the label of this plugin class, ie "Oscillators". - * - * Returned value is owned by \a plugin_class and must not be freed by caller. - * - * Time = O(1) + * Returned value is owned by @a plugin_class and must not be freed by caller. */ SLV2_API SLV2Value slv2_plugin_class_get_label(SLV2PluginClass plugin_class); /** Get the subclasses of this plugin class. - * * Returned value must be freed by caller with slv2_plugin_classes_free. - * - * Time = O(nclasses) */ SLV2_API SLV2PluginClasses diff --git a/slv2/plugininstance.h b/slv2/plugininstance.h index c860590..a96dc43 100644 --- a/slv2/plugininstance.h +++ b/slv2/plugininstance.h @@ -31,7 +31,7 @@ extern "C" { typedef struct _InstanceImpl* SLV2InstanceImpl; -/** \cond IGNORE */ +/** @cond IGNORE */ /* Instance of a plugin. * @@ -47,9 +47,9 @@ typedef struct _Instance { SLV2InstanceImpl pimpl; ///< Private implementation }* SLV2Instance; -/** \endcond */ +/** @endcond */ -/** \defgroup slv2_library Plugin library access +/** @defgroup slv2_library Plugin library access * * An SLV2Instance is an instantiated SLV2Plugin (ie a loaded dynamic * library). These functions interact with the binary library code only, @@ -59,19 +59,18 @@ typedef struct _Instance { */ /** Instantiate a plugin. - * * The returned object represents shared library objects loaded into memory, * it must be cleaned up with slv2_instance_free when no longer * needed. * - * \a plugin is not modified or directly referenced by the returned object + * @a plugin is not modified or directly referenced by the returned object * (instances store only a copy of the plugin's URI). * - * \a host_features NULL-terminated array of features the host supports. + * @a host_features NULL-terminated array of features the host supports. * NULL may be passed if the host supports no additional features (unlike * the LV2 specification - SLV2 takes care of it). * - * \return NULL if instantiation failed. + * @return NULL if instantiation failed. */ SLV2_API SLV2Instance @@ -80,8 +79,7 @@ slv2_plugin_instantiate(SLV2Plugin plugin, const LV2_Feature*const* features); /** Free a plugin instance. - * - * \a instance is invalid after this call. + * @a instance is invalid after this call. */ SLV2_API void @@ -89,8 +87,7 @@ slv2_instance_free(SLV2Instance instance); #ifndef SLV2_INTERNAL -/** Get the URI of the plugin which \a instance is an instance of. - * +/** Get the URI of the plugin which @a instance is an instance of. * Returned string is shared and must not be modified or deleted. */ static inline const char* @@ -100,7 +97,6 @@ slv2_instance_get_uri(SLV2Instance instance) } /** Connect a port to a data location. - * * This may be called regardless of whether the plugin is activated, * activation and deactivation does not destroy port connections. */ @@ -114,7 +110,6 @@ slv2_instance_connect_port(SLV2Instance instance, } /** Activate a plugin instance. - * * This resets all state information in the plugin, except for port data * locations (as set by slv2_instance_connect_port). This MUST be called * before calling slv2_instance_run. @@ -126,8 +121,7 @@ slv2_instance_activate(SLV2Instance instance) instance->lv2_descriptor->activate(instance->lv2_handle); } -/** Run \a instance for \a sample_count frames. - * +/** Run @a instance for @a sample_count frames. * If the hint lv2:hardRTCapable is set for this plugin, this function is * guaranteed not to block. */ @@ -135,12 +129,10 @@ static inline void slv2_instance_run(SLV2Instance instance, uint32_t sample_count) { - /*if (instance->lv2_descriptor->run)*/ - instance->lv2_descriptor->run(instance->lv2_handle, sample_count); + instance->lv2_descriptor->run(instance->lv2_handle, sample_count); } /** Deactivate a plugin instance. - * * Note that to run the plugin after this you must activate it, which will * reset all state information (except port connections). */ @@ -152,7 +144,6 @@ slv2_instance_deactivate(SLV2Instance instance) } /** Get extension data from the plugin instance. - * * The type and semantics of the data returned is specific to the particular * extension, though in all cases it is shared and must not be deleted. */ @@ -167,7 +158,6 @@ slv2_instance_get_extension_data(SLV2Instance instance, } /** Get the LV2_Descriptor of the plugin instance. - * * Normally hosts should not need to access the LV2_Descriptor directly, * use the slv2_instance_* functions. * @@ -180,7 +170,6 @@ slv2_instance_get_descriptor(SLV2Instance instance) } /** Get the LV2_Handle of the plugin instance. - * * Normally hosts should not need to access the LV2_Handle directly, * use the slv2_instance_* functions. * diff --git a/slv2/pluginui.h b/slv2/pluginui.h index d13f920..93c31fb 100644 --- a/slv2/pluginui.h +++ b/slv2/pluginui.h @@ -23,60 +23,45 @@ extern "C" { #endif -/** \addtogroup slv2_data +/** @addtogroup slv2_data * @{ */ /** Get the URI of a Plugin UI. - * - * \param ui The Plugin UI - * \return a shared value which must not be modified or freed. - * - * Time = O(1) + * @param ui The Plugin UI + * @return a shared value which must not be modified or freed. */ SLV2_API SLV2Value slv2_ui_get_uri(SLV2UI ui); /** Get the types (URIs of RDF classes) of a Plugin UI. - * - * \param ui The Plugin UI - * \return a shared value which must not be modified or freed. - * - * Time = O(1) + * @param ui The Plugin UI + * @return a shared value which must not be modified or freed. */ SLV2_API SLV2Values slv2_ui_get_classes(SLV2UI ui); /** Check whether a plugin UI is a given type. - * - * \param ui The Plugin UI - * \param class_uri The URI of the LV2 UI type to check this UI against - * - * Time = O(1) + * @param ui The Plugin UI + * @param class_uri The URI of the LV2 UI type to check this UI against */ SLV2_API bool slv2_ui_is_a(SLV2UI ui, SLV2Value class_uri); /** Get the URI for a Plugin UI's bundle. - * - * \param ui The Plugin UI - * \return a shared value which must not be modified or freed. - * - * Time = O(1) + * @param ui The Plugin UI + * @return a shared value which must not be modified or freed. */ SLV2_API SLV2Value slv2_ui_get_bundle_uri(SLV2UI ui); /** Get the URI for a Plugin UI's shared library. - * - * \param ui The Plugin UI - * \return a shared value which must not be modified or freed. - * - * Time = O(1) + * @param ui The Plugin UI + * @return a shared value which must not be modified or freed. */ SLV2_API SLV2Value diff --git a/slv2/pluginuiinstance.h b/slv2/pluginuiinstance.h index 503ce53..59bc16d 100644 --- a/slv2/pluginuiinstance.h +++ b/slv2/pluginuiinstance.h @@ -38,24 +38,23 @@ typedef struct _SLV2UIInstance { SLV2UIInstanceImpl pimpl; ///< Private implementation }* SLV2UIInstance; -/** \addtogroup slv2_library +/** @addtogroup slv2_library * @{ */ /** Instantiate a plugin UI. - * * The returned object represents shared library objects loaded into memory, * it must be cleaned up with slv2_ui_instance_free when no longer * needed. * - * \a plugin is not modified or directly referenced by the returned object + * @a plugin is not modified or directly referenced by the returned object * (instances store only a copy of the plugin's URI). * - * \a host_features NULL-terminated array of features the host supports. + * @a host_features NULL-terminated array of features the host supports. * NULL may be passed if the host supports no additional features (unlike * the LV2 specification - SLV2 takes care of it). * - * \return NULL if instantiation failed. + * @return NULL if instantiation failed. */ SLV2_API SLV2UIInstance @@ -66,12 +65,10 @@ slv2_ui_instantiate(SLV2Plugin plugin, const LV2_Feature* const* features); /** Free a plugin UI instance. - * + * @a instance is invalid after this call. * It is the caller's responsibility to ensure all references to the UI * instance (including any returned widgets) are cut before calling * this function. - * - * \a instance is invalid after this call. */ SLV2_API void @@ -84,7 +81,6 @@ LV2UI_Widget slv2_ui_instance_get_widget(SLV2UIInstance instance); /** Get the LV2UI_Descriptor of the plugin UI instance. - * * Normally hosts should not need to access the LV2UI_Descriptor directly, * use the slv2_ui_instance_* functions. * @@ -95,7 +91,6 @@ const LV2UI_Descriptor* slv2_ui_instance_get_descriptor(SLV2UIInstance instance); /** Get the LV2UI_Handle of the plugin UI instance. - * * Normally hosts should not need to access the LV2UI_Handle directly, * use the slv2_ui_instance_* functions. * diff --git a/slv2/port.h b/slv2/port.h index de34946..95b1ed5 100644 --- a/slv2/port.h +++ b/slv2/port.h @@ -28,13 +28,11 @@ extern "C" { #include "slv2/port.h" #include "slv2/collections.h" -/** \addtogroup slv2_data +/** @addtogroup slv2_data * @{ */ /** Port analog of slv2_plugin_get_value. - * - * Time = Query */ SLV2_API SLV2Values @@ -43,8 +41,6 @@ slv2_port_get_value(SLV2Plugin plugin, SLV2Value predicate); /** Port analog of slv2_plugin_get_value_by_qname. - * - * Time = Query */ SLV2_API SLV2Values @@ -53,8 +49,6 @@ slv2_port_get_value_by_qname(SLV2Plugin plugin, const char* property_uri); /** Return the LV2 port properties of a port. - * - * Time = Query */ SLV2_API SLV2Values @@ -62,8 +56,6 @@ slv2_port_get_properties(SLV2Plugin plugin, SLV2Port port); /** Return whether a port has a certain property. - * - * Time = Query */ SLV2_API bool @@ -72,8 +64,6 @@ slv2_port_has_property(SLV2Plugin p, SLV2Value property_uri); /** Return whether a port is an event port and supports a certain event type. - * - * Time = Query */ SLV2_API bool @@ -82,11 +72,8 @@ slv2_port_supports_event(SLV2Plugin p, SLV2Value event_uri); /** Get the symbol of a port. - * * The 'symbol' is a short string, a valid C identifier. - * Returned value is owned by \a port and must not be freed. - * - * Time = Query + * Returned value is owned by @a port and must not be freed. */ SLV2_API SLV2Value @@ -94,12 +81,9 @@ slv2_port_get_symbol(SLV2Plugin plugin, SLV2Port port); /** Get the name of a port. - * * This is guaranteed to return the untranslated name (the doap:name in the * data file without a language tag). Returned value must be freed by * the caller. - * - * Time = Query */ SLV2_API SLV2Value @@ -107,14 +91,10 @@ slv2_port_get_name(SLV2Plugin plugin, SLV2Port port); /** Get all the classes of a port. - * * This can be used to determine if a port is an input, output, audio, * control, midi, etc, etc, though it's simpler to use slv2_port_is_a. * The returned list does not include lv2:Port, which is implied. - * * Returned value is shared and must not be destroyed by caller. - * - * Time = O(1) */ SLV2_API SLV2Values @@ -122,15 +102,11 @@ slv2_port_get_classes(SLV2Plugin plugin, SLV2Port port); /** Determine if a port is of a given class (input, output, audio, etc). - * * For convenience/performance/extensibility reasons, hosts are expected to * create an SLV2Value for each port class they "care about". Well-known type * URI strings are defined (e.g. SLV2_PORT_CLASS_INPUT) for convenience, but * this function is designed so that SLV2 is usable with any port types * without requiring explicit support in SLV2. - * - * Time = O(n) (n pointer comparisons where n is the number of classes of - * this port, so this method is suitable for realtime use on any sane port). */ SLV2_API bool @@ -139,13 +115,10 @@ slv2_port_is_a(SLV2Plugin plugin, SLV2Value port_class); /** Get the default, minimum, and maximum values of a port. - * * @a def, @a min, and @a max are outputs, pass pointers to uninitialized * (i.e. NOT created with slv2_value_new) SLV2Value variables. These will * be set to point at new values (which must be freed by the caller using * slv2_value_free), or NULL if the value does not exist. - * - * Time = Query */ SLV2_API void @@ -156,10 +129,8 @@ slv2_port_get_range(SLV2Plugin plugin, SLV2Value* max); /** Get the scale points (enumeration values) of a port. - * * This returns a collection of 'interesting' named values of a port * (e.g. appropriate entries for a UI selector associated with this port). - * * Returned value may be NULL if @a port has no scale points, otherwise it * must be freed by caller with slv2_scale_points_free. */ diff --git a/slv2/scalepoint.h b/slv2/scalepoint.h index 290ed14..eec1d84 100644 --- a/slv2/scalepoint.h +++ b/slv2/scalepoint.h @@ -25,21 +25,19 @@ extern "C" { #include "slv2/types.h" -/** \addtogroup slv2_data +/** @addtogroup slv2_data * @{ */ /** Get the label of this scale point (enumeration value) - * - * Returned value is owned by \a point and must not be freed. + * Returned value is owned by @a point and must not be freed. */ SLV2_API SLV2Value slv2_scale_point_get_label(SLV2ScalePoint point); /** Get the value of this scale point (enumeration value) - * - * Returned value is owned by \a point and must not be freed. + * Returned value is owned by @a point and must not be freed. */ SLV2_API SLV2Value diff --git a/slv2/types.h b/slv2/types.h index faab351..ec9324b 100644 --- a/slv2/types.h +++ b/slv2/types.h @@ -71,27 +71,24 @@ typedef struct _SLV2PluginClass* SLV2PluginClass; /** A collection of plugin classes. Opaque, but valid to compare to NULL. */ typedef void* SLV2PluginClasses; -/** A typed value */ +/** A typed value. */ typedef struct _SLV2Value* SLV2Value; /** A collection of typed values. */ typedef void* SLV2Values; -/** A scale point */ +/** A scale point. */ typedef struct _SLV2ScalePoint* SLV2ScalePoint; /** A collection of scale points. */ typedef void* SLV2ScalePoints; -/** A plugin UI */ +/** A plugin UI. */ typedef struct _SLV2UI* SLV2UI; /** A collection of plugin UIs. */ typedef void* SLV2UIs; -/** A set of query results (conceptually a table) */ -typedef struct _SLV2Results* SLV2Results; - #ifdef __cplusplus } /* extern "C" */ #endif diff --git a/slv2/util.h b/slv2/util.h index b76a5bf..3c4594d 100644 --- a/slv2/util.h +++ b/slv2/util.h @@ -26,15 +26,13 @@ extern "C" { #include <stdarg.h> #include "slv2/types.h" -/** \defgroup slv2_util Utility functions - * +/** @defgroup slv2_util Utility functions * @{ */ /** Convert a full URI (eg file://foo/bar/baz.ttl) to a local path (e.g. /foo/bar/baz.ttl). - * * Return value is shared and must not be deleted by caller. - * \return \a uri converted to a path, or NULL on failure (URI is not local). + * @return @a uri converted to a path, or NULL on failure (URI is not local). */ SLV2_API const char* slv2_uri_to_path(const char* uri); diff --git a/slv2/value.h b/slv2/value.h index 84c5b94..8e68718 100644 --- a/slv2/value.h +++ b/slv2/value.h @@ -24,14 +24,14 @@ extern "C" { #endif #include <stdbool.h> + #include "slv2/types.h" -/** \addtogroup slv2_data +/** @addtogroup slv2_data * @{ */ /** Create a new URI value. - * * Returned value must be freed by caller with slv2_value_free. */ SLV2_API @@ -39,7 +39,6 @@ SLV2Value slv2_value_new_uri(SLV2World world, const char* uri); /** Create a new string value (with no language). - * * Returned value must be freed by caller with slv2_value_free. */ SLV2_API @@ -47,7 +46,6 @@ SLV2Value slv2_value_new_string(SLV2World world, const char* str); /** Create a new integer value. - * * Returned value must be freed by caller with slv2_value_free. */ SLV2_API @@ -55,7 +53,6 @@ SLV2Value slv2_value_new_int(SLV2World world, int val); /** Create a new floating point value. - * * Returned value must be freed by caller with slv2_value_free. */ SLV2_API @@ -63,7 +60,6 @@ SLV2Value slv2_value_new_float(SLV2World world, float val); /** Create a new boolean value. - * * Returned value must be freed by caller with slv2_value_free. */ SLV2_API @@ -89,135 +85,103 @@ bool slv2_value_equals(SLV2Value value, SLV2Value other); /** Return this value as a Turtle/SPARQL token. - * Examples: - * <http://example.org/foo> - * doap:name - * "this is a string" - * 1.0 - * 1 - * - * Returned string is newly allocated and must be freed by caller. + * <table> + * <caption>Example Turtle Tokens</caption> + * <tr><th>URI</th><td><http://example.org/foo ></td></tr> + * <tr><th>QName</td><td>doap:name</td></tr> + * <tr><th>String</td><td>"this is a string"</td></tr> + * <tr><th>Float</td><td>1.0</td></tr> + * <tr><th>Integer</td><td>1</td></tr> + * <tr><th>Boolean</td><td>true</td></tr> + * </table> */ SLV2_API char* slv2_value_get_turtle_token(SLV2Value value); /** Return whether the value is a URI (resource). - * - * Time = O(1) */ SLV2_API bool slv2_value_is_uri(SLV2Value value); /** Return this value as a URI string, e.g. "http://example.org/foo". - * - * Valid to call only if slv2_value_is_uri(\a value) returns true. - * Returned value is owned by \a value and must not be freed by caller. - * - * Time = O(1) + * Valid to call only if slv2_value_is_uri(@a value) returns true. + * Returned value is owned by @a value and must not be freed by caller. */ SLV2_API const char* slv2_value_as_uri(SLV2Value value); /** Return whether the value is a blank node (resource with no URI). - * - * Time = O(1) */ SLV2_API bool slv2_value_is_blank(SLV2Value value); /** Return this value as a blank node identifier, e.g. "genid03". - * - * Valid to call only if slv2_value_is_blank(\a value) returns true. - * Returned value is owned by \a value and must not be freed by caller. - * - * Time = O(1) + * Valid to call only if slv2_value_is_blank(@a value) returns true. + * Returned value is owned by @a value and must not be freed by caller. */ SLV2_API const char* slv2_value_as_blank(SLV2Value value); /** Return whether this value is a literal (i.e. not a URI). - * - * Returns true if \a value is a string or numeric value. - * - * Time = O(1) + * Returns true if @a value is a string or numeric value. */ SLV2_API bool slv2_value_is_literal(SLV2Value value); /** Return whether this value is a string literal. - * - * Returns true if \a value is a string (but not numeric) value. - * - * Time = O(1) + * Returns true if @a value is a string (but not numeric) value. */ SLV2_API bool slv2_value_is_string(SLV2Value value); -/** Return \a value as a string. - * - * Time = O(1) +/** Return @a value as a string. */ SLV2_API const char* slv2_value_as_string(SLV2Value value); /** Return whether this value is a decimal literal. - * - * Time = O(1) */ SLV2_API bool slv2_value_is_float(SLV2Value value); -/** Return \a value as a float. - * - * Valid to call only if slv2_value_is_float(\a value) or - * slv2_value_is_int(\a value) returns true. - * - * Time = O(1) +/** Return @a value as a float. + * Valid to call only if slv2_value_is_float(@a value) or + * slv2_value_is_int(@a value) returns true. */ SLV2_API float slv2_value_as_float(SLV2Value value); /** Return whether this value is an integer literal. - * - * Time = O(1) */ SLV2_API bool slv2_value_is_int(SLV2Value value); -/** Return \a value as an integer. - * - * Valid to call only if slv2_value_is_int(\a value) returns true. - * - * Time = O(1) +/** Return @a value as an integer. + * Valid to call only if slv2_value_is_int(@a value) returns true. */ SLV2_API int slv2_value_as_int(SLV2Value value); /** Return whether this value is a boolean. - * - * Time = O(1) */ SLV2_API bool slv2_value_is_bool(SLV2Value value); -/** Return \a value as a bool. - * - * Valid to call only if slv2_value_is_bool(\a value) returns true. - * - * Time = O(1) +/** Return @a value as a bool. + * Valid to call only if slv2_value_is_bool(@a value) returns true. */ SLV2_API bool 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 |