From afa8ead99e019b1ba850e28aaf71525f65084fe2 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Wed, 2 Mar 2011 23:23:03 +0000 Subject: Clean up slv2.h. git-svn-id: http://svn.drobilla.net/lad/trunk/slv2@3034 a436a847-0d15-0410-975c-d299462d15a1 --- slv2/slv2.h | 1384 ++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 755 insertions(+), 629 deletions(-) diff --git a/slv2/slv2.h b/slv2/slv2.h index 4855202..b6aae6f 100644 --- a/slv2/slv2.h +++ b/slv2/slv2.h @@ -16,8 +16,12 @@ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. */ -#ifndef SLV2_SLV2_H__ -#define SLV2_SLV2_H__ +/** + @file slv2.h API for SLV2, a lightweight LV2 host library. +*/ + +#ifndef SLV2_SLV2_H +#define SLV2_SLV2_H #include #include @@ -25,30 +29,25 @@ #include "lv2/lv2plug.in/ns/lv2core/lv2.h" #include "lv2/lv2plug.in/ns/extensions/ui/ui.h" -#ifdef __cplusplus -extern "C" { -#endif - -#if defined _WIN32 || defined __CYGWIN__ - #define SLV2_LIB_IMPORT __declspec(dllimport) - #define SLV2_LIB_EXPORT __declspec(dllexport) -#else - #define SLV2_LIB_IMPORT __attribute__ ((visibility("default"))) - #define SLV2_LIB_EXPORT __attribute__ ((visibility("default"))) -#endif - -#ifdef SLV2_SHARED // Building a shared library - #ifdef SLV2_INTERNAL // Building SLV2 (not using it) +#ifdef SLV2_SHARED + #if defined _WIN32 || defined __CYGWIN__ + #define SLV2_LIB_IMPORT __declspec(dllimport) + #define SLV2_LIB_EXPORT __declspec(dllexport) + #else + #define SLV2_LIB_IMPORT __attribute__ ((visibility("default"))) + #define SLV2_LIB_EXPORT __attribute__ ((visibility("default"))) + #endif + #ifdef SLV2_INTERNAL #define SLV2_API SLV2_LIB_EXPORT #else #define SLV2_API SLV2_LIB_IMPORT #endif -#else // Building a static library +#else #define SLV2_API #endif #if (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1)) - #ifdef SLV2_INTERNAL // Building SLV2 (not using it) + #ifdef SLV2_INTERNAL #define SLV2_DEPRECATED #else #define SLV2_DEPRECATED __attribute__((__deprecated__)) @@ -57,6 +56,10 @@ extern "C" { #define SLV2_DEPRECATED #endif +#ifdef __cplusplus +extern "C" { +#endif + #define SLV2_NAMESPACE_LV2 "http://lv2plug.in/ns/lv2core#" #define SLV2_PORT_CLASS_PORT "http://lv2plug.in/ns/lv2core#Port" #define SLV2_PORT_CLASS_INPUT "http://lv2plug.in/ns/lv2core#InputPort" @@ -80,225 +83,255 @@ typedef void* SLV2ScalePoints; /**< array. */ typedef void* SLV2UIs; /**< set. */ typedef void* SLV2Values; /**< array. */ -/** @defgroup slv2 SLV2 - * SLV2 is a simple yet powerful C API for using LV2 plugins. - * - * For more information about LV2, see . - * For more information about SLV2, see . - * @{ - */ - -/** @name Value - * @{ - */ - -/** Convert a file URI string to a local path string. - * For example, "file://foo/bar/baz.ttl" returns "/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). - */ +/** + @defgroup slv2 SLV2 + SLV2 is a simple yet powerful C API for using LV2 plugins. + + For more information about LV2, see . + For more information about SLV2, see . + @{ +*/ + +/** + @name Value + @{ +*/ + +/** + Convert a file URI string to a local path string. + For example, "file://foo/bar/baz.ttl" returns "/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). +*/ SLV2_API -const char* slv2_uri_to_path(const char* uri); +const char* +slv2_uri_to_path(const char* uri); -/** Create a new URI value. - * Returned value must be freed by caller with slv2_value_free. - */ +/** + Create a new URI value. + Returned value must be freed by caller with slv2_value_free. +*/ SLV2_API 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. - */ +/** + Create a new string value (with no language). + Returned value must be freed by caller with slv2_value_free. +*/ SLV2_API 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. - */ +/** + Create a new integer value. + Returned value must be freed by caller with slv2_value_free. +*/ SLV2_API 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. - */ +/** + Create a new floating point value. + Returned value must be freed by caller with slv2_value_free. +*/ SLV2_API 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. - */ +/** + Create a new boolean value. + Returned value must be freed by caller with slv2_value_free. +*/ SLV2_API SLV2Value slv2_value_new_bool(SLV2World world, bool val); -/** Free an SLV2Value. - */ +/** + Free an SLV2Value. +*/ SLV2_API void slv2_value_free(SLV2Value val); -/** Duplicate an SLV2Value. - */ +/** + Duplicate an SLV2Value. +*/ SLV2_API SLV2Value slv2_value_duplicate(SLV2Value val); -/** Return whether two values are equivalent. - */ +/** + Return whether two values are equivalent. +*/ SLV2_API bool slv2_value_equals(SLV2Value value, SLV2Value other); -/** Return this value as a Turtle/SPARQL token. - * - * - * - * - * - * - * - * - *
Example Turtle Tokens
URI<http://example.org/foo >
QNamedoap:name
String"this is a string"
Float1.0
Integer1
Booleantrue
- */ +/** + Return this value as a Turtle/SPARQL token. + + + + + + + + +
Example Turtle Tokens
URI<http://example.org/foo >
QNamedoap:name
String"this is a string"
Float1.0
Integer1
Booleantrue
+*/ SLV2_API char* slv2_value_get_turtle_token(SLV2Value value); -/** Return whether the value is a URI (resource). - */ +/** + Return whether the value is a URI (resource). +*/ 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. - */ +/** + 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. +*/ SLV2_API const char* slv2_value_as_uri(SLV2Value value); -/** Return whether the value is a blank node (resource with no URI). - */ +/** + Return whether the value is a blank node (resource with no URI). +*/ 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. - */ +/** + 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. +*/ 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. - */ +/** + Return whether this value is a literal (i.e. not a URI). + 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. - */ +/** + Return whether this value is a string literal. + 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. - */ +/** + Return @a value as a string. +*/ SLV2_API const char* slv2_value_as_string(SLV2Value value); -/** Return whether this value is a decimal literal. - */ +/** + Return whether this value is a decimal literal. +*/ 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. - */ +/** + 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. - */ +/** + Return whether this value is an integer literal. +*/ 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. - */ +/** + 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. - */ +/** + Return whether this value is a boolean. +*/ 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. - */ +/** + Return @a value as a bool. + Valid to call only if slv2_value_is_bool(@a value) returns true. +*/ SLV2_API bool slv2_value_as_bool(SLV2Value value); -/** @} */ -/** @name Collections - * SLV2 has several collection types for holding various types of value: - *
    - *
  • SLV2Plugins (function prefix "slv2_plugins_")
    • - *
  • SLV2PluginClasses (function prefix "slv2_plugin_classes_")
    • - *
  • SLV2ScalePoints (function prefix "slv2_scale_points_")
    • - *
  • SLV2Values (function prefix "slv2_values_")
    • - *
  • SLV2UIs (function prefix "slv2_uis_")
    • - *
- * - * Each collection type supports the following functions: - *
    - *
  • PREFIX_free (coll)
    • - *
  • PREFIX_size (coll)
    • - *
  • PREFIX_get_at (coll, index)
    • - *
- * @{ - */ +/** + @} + @name Collections + SLV2 has several collection types for holding various types of value: +
    +
  • SLV2Plugins (function prefix "slv2_plugins_")
    • +
  • SLV2PluginClasses (function prefix "slv2_plugin_classes_")
    • +
  • SLV2ScalePoints (function prefix "slv2_scale_points_")
    • +
  • SLV2Values (function prefix "slv2_values_")
    • +
  • SLV2UIs (function prefix "slv2_uis_")
    • +
+ + Each collection type supports the following functions: +
    +
  • PREFIX_free (coll)
    • +
  • PREFIX_size (coll)
    • +
  • PREFIX_get_at (coll, index)
    • +
+ @{ +*/ #define SLV2_COLLECTION(CollType, ElemType, prefix) \ \ -/** Free @a collection. - */ \ +/** + Free @a collection. +*/ \ SLV2_API \ void \ prefix ## _free(CollType collection); \ \ \ -/** Get the number of elements in @a collection. - */ \ +/** + Get the number of elements in @a collection. +*/ \ SLV2_API \ unsigned \ prefix ## _size(CollType collection); \ \ \ -/** Get an element from @a 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, - * so all elements in a collection can be enumerated by repeated calls - * to this function starting with @a index = 0. - * @return NULL if @a index is out of range. - */ \ +/** + Get an element from @a 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, + so all elements in a collection can be enumerated by repeated calls + to this function starting with @a index = 0. + @return NULL if @a index is out of range. +*/ \ SLV2_API \ ElemType \ prefix ## _get_at(CollType collection, \ @@ -309,386 +342,423 @@ SLV2_COLLECTION(SLV2ScalePoints, SLV2ScalePoint, slv2_scale_points) SLV2_COLLECTION(SLV2UIs, SLV2UI, slv2_uis) SLV2_COLLECTION(SLV2Values, SLV2Value, slv2_values) -/** 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. - */ +/** + 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. +*/ SLV2_API void slv2_plugins_free(SLV2World world, SLV2Plugins plugins); -/** Get the number of plugins in the collection. - */ +/** + Get the number of plugins in the collection. +*/ SLV2_API unsigned slv2_plugins_size(SLV2Plugins plugins); -/** 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. - * @return NULL if no plugin with @a uri is found in @a plugins. - */ +/** + 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. + @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 @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. - * @return NULL if @a index out of range. - */ +/** + 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. + @return NULL if @a index out of range. +*/ SLV2_API SLV2Plugin slv2_plugins_get_at(SLV2Plugins plugins, unsigned index); -/** 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. - * @return NULL if no plugin class with @a uri is found in @a classes. - */ +/** + 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. + @return NULL if no plugin class with @a uri is found in @a classes. +*/ SLV2_API SLV2PluginClass slv2_plugin_classes_get_by_uri(SLV2PluginClasses classes, SLV2Value uri); -/** Allocate a new, empty SLV2ScalePoints. - */ +/** + Allocate a new, empty SLV2ScalePoints. +*/ SLV2_API SLV2ScalePoints slv2_scale_points_new(void); -/** Allocate a new, empty SLV2Values. - */ +/** + Allocate a new, empty SLV2Values. +*/ SLV2_API SLV2Values slv2_values_new(void); -/** Return whether @a values contains @a value. - */ +/** + Return whether @a values contains @a value. +*/ SLV2_API bool slv2_values_contains(SLV2Values values, SLV2Value value); -/** @} */ -/** @name World - * The "world" represents all SLV2 state, and is used to discover/load/cache - * LV2 data (plugins, UIs, and extensions). - * Normal hosts which just need to load plugins by URI should simply use - * @ref slv2_world_load_all to discover/load the system's LV2 resources. - * @{ - */ - -/** Initialize a new, empty world. - * If initialization fails, NULL is returned. - */ +/** + @} + @name World + The "world" represents all SLV2 state, and is used to discover/load/cache + LV2 data (plugins, UIs, and extensions). + Normal hosts which just need to load plugins by URI should simply use + @ref slv2_world_load_all to discover/load the system's LV2 resources. + @{ +*/ + +/** + Initialize a new, empty world. + If initialization fails, NULL is returned. +*/ SLV2_API SLV2World slv2_world_new(void); -/** Enable/disable language filtering. - * Language filtering applies to any functions that return (a) value(s). - * With filtering enabled, SLV2 will automatically return the best value(s) - * for the current LANG. With filtering disabled, all matching values will - * be returned regardless of language tag. Filtering is enabled by default. - */ +/** + Enable/disable language filtering. + Language filtering applies to any functions that return (a) value(s). + With filtering enabled, SLV2 will automatically return the best value(s) + for the current LANG. With filtering disabled, all matching values will + be returned regardless of language tag. Filtering is enabled by default. +*/ #define SLV2_OPTION_FILTER_LANG "http://drobilla.net/ns/slv2#filter-lang" -/** Set an SLV2 option for @a world. - */ +/** + Set an SLV2 option for @a world. +*/ SLV2_API void slv2_world_set_option(SLV2World world, const char* uri, const SLV2Value value); -/** Destroy the world, mwahaha. - * 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. - */ +/** + Destroy the world, mwahaha. + 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 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). - */ +/** + Load all installed LV2 bundles on the system. + 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/ - * - * Normal hosts should not need this function (use slv2_world_load_all). - * - * 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. - */ +/** + 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/ + + Normal hosts should not need this function (use slv2_world_load_all). + + 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 slv2_world_load_bundle(SLV2World world, SLV2Value bundle_uri); -/** Get the parent of all other plugin classes, lv2:Plugin. - */ +/** + Get the parent of all other plugin classes, lv2:Plugin. +*/ 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. - */ +/** + Return a list of all found plugin classes. + Returned list is owned by world and must not be freed by the caller. +*/ 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 - * a query (at which time the data is cached with the SLV2Plugin so future - * 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. - */ +/** + 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 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. +*/ 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 - * 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. - */ +/** + 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 + 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. +*/ SLV2_API SLV2Plugins slv2_world_get_plugins_by_filter(SLV2World world, bool (*include)(SLV2Plugin)); -/** Return the plugin with the given @a uri, or NULL if not found. - */ +/** + Return the plugin with the given @a uri, or NULL if not found. +*/ SLV2_API SLV2Plugin slv2_world_get_plugin_by_uri_string(SLV2World world, const char* uri); -/** @} */ -/** @name Plugin - * @{ - */ - -/** Check if @a plugin is valid. - * 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 iff @a plugin is valid. - */ +/** + @} + @name Plugin + @{ +*/ + +/** + Check if @a plugin is valid. + 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 iff @a plugin is valid. +*/ SLV2_API bool slv2_plugin_verify(SLV2Plugin 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. - * - * The URI is a globally unique identifier for one specific plugin. Two - * plugins with the same URI are compatible in port signature, and should - * be guaranteed to work in a compatible and consistent way. If a 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 URI value which must not be modified or freed. - */ +/** + 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. + + The URI is a globally unique identifier for one specific plugin. Two + plugins with the same URI are compatible in port signature, and should + be guaranteed to work in a compatible and consistent way. If a 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 URI value which must not be modified or freed. +*/ SLV2_API SLV2Value slv2_plugin_get_uri(SLV2Plugin plugin); -/** 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 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. - */ +/** + 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 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. +*/ 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", - * which is shared and must not be modified or freed. - */ +/** + 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", + which is shared and must not be modified or freed. +*/ SLV2_API SLV2Values slv2_plugin_get_data_uris(SLV2Plugin 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. - */ +/** + 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. +*/ SLV2_API SLV2Value slv2_plugin_get_library_uri(SLV2Plugin 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. - */ +/** + 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. +*/ SLV2_API SLV2Value slv2_plugin_get_name(SLV2Plugin plugin); -/** Get the class this plugin belongs to (ie Filters). - */ +/** + Get the class this plugin belongs to (ie Filters). +*/ SLV2_API 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: - * - * <plugin-uri> predicate ?object - * - * 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. - */ +/** + 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: + + <plugin-uri> predicate ?object + + 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. +*/ SLV2_API SLV2Values 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. - */ +/** + 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. +*/ SLV2_API SLV2Values 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: - * - * subject predicate ?object - * - * This can be used to investigate URIs returned by slv2_plugin_get_value - * (if information about it is contained in the plugin's data files). - * - * May return NULL if the property was not found, or if object is not - * sensibly represented as an SLV2Values (e.g. blank nodes). - * Return value must be freed by caller with slv2_values_free. - */ +/** + 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: + + subject predicate ?object + + This can be used to investigate URIs returned by slv2_plugin_get_value + (if information about it is contained in the plugin's data files). + + May return NULL if the property was not found, or if object is not + sensibly represented as an SLV2Values (e.g. blank nodes). + Return value must be freed by caller with slv2_values_free. +*/ SLV2_API SLV2Values slv2_plugin_get_value_for_subject(SLV2Plugin p, SLV2Value subject_uri, 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. - */ +/** + 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. +*/ SLV2_API bool 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 - * probably shouldn't be used by normal hosts. Using slv2_plugin_get_optional_features - * and slv2_plugin_get_required_features separately is best in most cases. - * - * Returned value must be freed by caller with slv2_values_free. - */ +/** + 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 + probably shouldn't be used by normal hosts. Using slv2_plugin_get_optional_features + and slv2_plugin_get_required_features separately is best in most cases. + * + Returned value must be freed by caller with slv2_values_free. +*/ 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. - * - * All values returned here MUST be passed to the plugin's instantiate method - * (along with data, if necessary, as defined by the feature specification) - * or plugin instantiation will fail. - * - * Return value must be freed by caller with slv2_values_free. - */ +/** + 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. + + All values returned here MUST be passed to the plugin's instantiate method + (along with data, if necessary, as defined by the feature specification) + or plugin instantiation will fail. + + Return value must be freed by caller with slv2_values_free. +*/ 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. - */ +/** + 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. +*/ SLV2_API SLV2Values slv2_plugin_get_optional_features(SLV2Plugin p); -/** Get the number of ports on this plugin. - */ +/** + Get the number of ports on this plugin. +*/ 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 - * 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, - * with array index corresponding to port index. If a port doesn't have a - * minimum, maximum or default value, or the port's type is not float, the - * corresponding array element will be set to NAN. - * - * This is a convenience method for the common case of getting the range of - * all float ports on a plugin, and may be significantly faster than - * repeated calls to slv2_port_get_range. - */ +/** + 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 + 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, + with array index corresponding to port index. If a port doesn't have a + minimum, maximum or default value, or the port's type is not float, the + corresponding array element will be set to NAN. + + This is a convenience method for the common case of getting the range of + all float ports on a plugin, and may be significantly faster than + repeated calls to slv2_port_get_range. +*/ SLV2_API void slv2_plugin_get_port_ranges_float(SLV2Plugin p, @@ -696,169 +766,188 @@ slv2_plugin_get_port_ranges_float(SLV2Plugin p, float* max_values, 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. - */ +/** + 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. +*/ SLV2_API uint32_t 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. - */ +/** + 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. +*/ 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. - */ +/** + 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. +*/ SLV2_API uint32_t slv2_plugin_get_latency_port_index(SLV2Plugin p); -/** Get a port on @a plugin by @a index. - */ +/** + 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 @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. - */ +/** + 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 slv2_plugin_get_port_by_symbol(SLV2Plugin plugin, SLV2Value symbol); -/** Get the full name of the plugin's author. - * Returns NULL if author name is not present. - * Returned value must be freed by caller. - */ +/** + Get the full name of the plugin's author. + Returns NULL if author name is not present. + Returned value must be freed by caller. +*/ 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. - */ +/** + 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. +*/ 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. - */ +/** + Get the email address of the plugin's author. + Returns NULL if author homepage is not present. + Returned value must be freed by caller. +*/ SLV2_API SLV2Value slv2_plugin_get_author_homepage(SLV2Plugin plugin); -/** @} */ -/** @name Port - * @{ - */ +/** + @} + @name Port + @{ +*/ -/** Port analog of slv2_plugin_get_value. - */ +/** + Port analog of slv2_plugin_get_value. +*/ SLV2_API SLV2Values slv2_port_get_value(SLV2Plugin plugin, SLV2Port port, SLV2Value predicate); -/** Port analog of slv2_plugin_get_value_by_qname. - */ +/** + Port analog of slv2_plugin_get_value_by_qname. +*/ SLV2_API SLV2Values slv2_port_get_value_by_qname(SLV2Plugin plugin, SLV2Port port, const char* predicate); -/** Return the LV2 port properties of a port. - */ +/** + Return the LV2 port properties of a port. +*/ SLV2_API SLV2Values slv2_port_get_properties(SLV2Plugin plugin, SLV2Port port); -/** Return whether a port has a certain property. - */ +/** + Return whether a port has a certain property. +*/ SLV2_API bool slv2_port_has_property(SLV2Plugin p, SLV2Port port, SLV2Value property_uri); -/** Return whether a port is an event port and supports a certain event type. - */ +/** + Return whether a port is an event port and supports a certain event type. +*/ SLV2_API bool slv2_port_supports_event(SLV2Plugin p, SLV2Port port, 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. - */ +/** + 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. +*/ SLV2_API SLV2Value 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. - */ +/** + 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. +*/ SLV2_API SLV2Value 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. - */ +/** + 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. +*/ SLV2_API SLV2Values 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. - */ +/** + 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. +*/ SLV2_API bool slv2_port_is_a(SLV2Plugin plugin, SLV2Port port, 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. - */ +/** + 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. +*/ SLV2_API void slv2_port_get_range(SLV2Plugin plugin, @@ -867,126 +956,140 @@ slv2_port_get_range(SLV2Plugin plugin, SLV2Value* min, 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. - */ +/** + 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. +*/ SLV2_API SLV2ScalePoints slv2_port_get_scale_points(SLV2Plugin plugin, SLV2Port port); -/** @} */ -/** @name Scale Point - * @{ - */ +/** + @} + @name Scale Point + @{ +*/ -/** Get the label of this scale point (enumeration value) - * Returned value is owned by @a point and must not be freed. - */ +/** + Get the label of this scale point (enumeration value) + 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. - */ +/** + Get the value of this scale point (enumeration value) + Returned value is owned by @a point and must not be freed. +*/ SLV2_API SLV2Value slv2_scale_point_get_value(SLV2ScalePoint point); -/** @} */ -/** @name Plugin Class - * @{ - */ +/** + @} + @name Plugin Class + @{ +*/ -/** Get the URI of this class' superclass. - * 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. - */ +/** + Get the URI of this class' superclass. + 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. +*/ 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. - */ +/** + Get the URI of this plugin class. + 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. - */ +/** + Get the label of this plugin class, ie "Oscillators". + 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. - */ +/** + Get the subclasses of this plugin class. + Returned value must be freed by caller with slv2_plugin_classes_free. +*/ SLV2_API SLV2PluginClasses slv2_plugin_class_get_children(SLV2PluginClass plugin_class); -/** @} */ -/** @name Plugin Instance - * @{ - */ +/** + @} + @name Plugin Instance + @{ +*/ typedef struct _SLV2InstanceImpl* SLV2InstanceImpl; /* Instance of a plugin. - * This is exposed in the ABI to allow inlining of performance critical - * functions like slv2_instance_run (simple wrappers of functions in lv2.h). - * This is for performance reasons, user code should not use this definition - * in any way (which is why it is not machine documented). - * Truly private implementation details are hidden via @a ref pimpl. - */ + This is exposed in the ABI to allow inlining of performance critical + functions like slv2_instance_run (simple wrappers of functions in lv2.h). + This is for performance reasons, user code should not use this definition + in any way (which is why it is not machine documented). + Truly private implementation details are hidden via @a ref pimpl. +*/ typedef struct _Instance { const LV2_Descriptor* lv2_descriptor; LV2_Handle lv2_handle; SLV2InstanceImpl pimpl; ///< Private implementation }* SLV2Instance; -/** Instantiate a plugin. - * The returned value is a lightweight handle for an LV2 plugin instance, - * it does not refer to @a plugin, or any other SLV2 state. The caller must - * eventually free it with slv2_instance_free. - * @a features is a NULL-terminated array of features the host supports. - * NULL may be passed if the host supports no additional features. - * @return NULL if instantiation failed. - */ +/** + Instantiate a plugin. + The returned value is a lightweight handle for an LV2 plugin instance, + it does not refer to @a plugin, or any other SLV2 state. The caller must + eventually free it with slv2_instance_free. + @a features is a NULL-terminated array of features the host supports. + NULL may be passed if the host supports no additional features. + @return NULL if instantiation failed. +*/ SLV2_API SLV2Instance slv2_plugin_instantiate(SLV2Plugin plugin, double sample_rate, const LV2_Feature*const* features); -/** Free a plugin instance. - * @a instance is invalid after this call. - */ +/** + Free a plugin instance. + @a instance is invalid after this call. +*/ SLV2_API void slv2_instance_free(SLV2Instance instance); #ifndef SLV2_INTERNAL -/** Get the URI of the plugin which @a instance is an instance of. - * Returned string is shared and must not be modified or deleted. - */ +/** + 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* slv2_instance_get_uri(SLV2Instance instance) { return instance->lv2_descriptor->URI; } -/** 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. - */ +/** + 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. +*/ static inline void slv2_instance_connect_port(SLV2Instance instance, uint32_t port_index, @@ -996,11 +1099,12 @@ slv2_instance_connect_port(SLV2Instance instance, (instance->lv2_handle, port_index, data_location); } -/** 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. - */ +/** + 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. +*/ static inline void slv2_instance_activate(SLV2Instance instance) { @@ -1008,10 +1112,11 @@ slv2_instance_activate(SLV2Instance instance) instance->lv2_descriptor->activate(instance->lv2_handle); } -/** 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. - */ +/** + 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. +*/ static inline void slv2_instance_run(SLV2Instance instance, uint32_t sample_count) @@ -1019,10 +1124,11 @@ slv2_instance_run(SLV2Instance instance, 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). - */ +/** + 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). +*/ static inline void slv2_instance_deactivate(SLV2Instance instance) { @@ -1030,10 +1136,11 @@ slv2_instance_deactivate(SLV2Instance instance) instance->lv2_descriptor->deactivate(instance->lv2_handle); } -/** 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. - */ +/** + 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. +*/ static inline const void* slv2_instance_get_extension_data(SLV2Instance instance, const char* uri) @@ -1044,24 +1151,26 @@ slv2_instance_get_extension_data(SLV2Instance instance, return NULL; } -/** Get the LV2_Descriptor of the plugin instance. - * Normally hosts should not need to access the LV2_Descriptor directly, - * use the slv2_instance_* functions. - * - * The returned descriptor is shared and must not be deleted. - */ +/** + Get the LV2_Descriptor of the plugin instance. + Normally hosts should not need to access the LV2_Descriptor directly, + use the slv2_instance_* functions. + + The returned descriptor is shared and must not be deleted. +*/ static inline const LV2_Descriptor* slv2_instance_get_descriptor(SLV2Instance instance) { return instance->lv2_descriptor; } -/** Get the LV2_Handle of the plugin instance. - * Normally hosts should not need to access the LV2_Handle directly, - * use the slv2_instance_* functions. - * - * The returned handle is shared and must not be deleted. - */ +/** + Get the LV2_Handle of the plugin instance. + Normally hosts should not need to access the LV2_Handle directly, + use the slv2_instance_* functions. + + The returned handle is shared and must not be deleted. +*/ static inline LV2_Handle slv2_instance_get_handle(SLV2Instance instance) { @@ -1070,108 +1179,116 @@ slv2_instance_get_handle(SLV2Instance instance) #endif /* SLV2_INTERNAL */ -/** @} */ -/** @name Plugin UI - * @{ - */ +/** + @} + @name Plugin UI + @{ +*/ -/** 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. - * @return NULL if no UI with @a uri is found in @a list. - */ +/** + 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. + @return NULL if no UI with @a uri is found in @a list. +*/ SLV2_API SLV2UI slv2_uis_get_by_uri(SLV2UIs uis, SLV2Value uri); -/** Get all UIs for @a plugin. - * Returned value must be freed by caller using slv2_uis_free. - */ +/** + Get all UIs for @a plugin. + Returned value must be freed by caller using slv2_uis_free. +*/ SLV2_API SLV2UIs slv2_plugin_get_uis(SLV2Plugin plugin); -/** Get the default UI for @a plugin. - * This function makes a best effort at choosing a default UI for the given - * widget type. A native UI for the given widget type will be returned if one - * exists, otherwise a UI which can be wrapped by SLV2 will be returned. - * - * This function makes the common case (a plugin with a single UI, or a single - * UI per toolkit) simple, but is not fully powerful since a plugin may have - * several usable UIs. To support multiple UIs per plugin, use - * @ref slv2_ui_supported to determine which UIs are usable and choose a UI - * to instantiate from among them. - * - * @return NULL if there is no suitable UI. - */ +/** + Get the default UI for @a plugin. + This function makes a best effort at choosing a default UI for the given + widget type. A native UI for the given widget type will be returned if one + exists, otherwise a UI which can be wrapped by SLV2 will be returned. + + This function makes the common case (a plugin with a single UI, or a single + UI per toolkit) simple, but is not fully powerful since a plugin may have + several usable UIs. To support multiple UIs per plugin, use + @ref slv2_ui_supported to determine which UIs are usable and choose a UI + to instantiate from among them. + + @return NULL if there is no suitable UI. +*/ SLV2_API SLV2UI slv2_plugin_get_default_ui(SLV2Plugin plugin, SLV2Value widget_type_uri); -/** @name Plugin UI - * @{ - */ - -/** Get the URI of a Plugin UI. - * @param ui The Plugin UI - * @return a shared value which must not be modified or freed. - */ +/** + Get the URI of a Plugin UI. + @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); -/** Return true iff @a ui can be instantiated to a widget of the given type. - */ +/** + Return true iff @a ui can be instantiated to a widget of the given type. +*/ SLV2_API bool slv2_ui_supported(SLV2UI ui, SLV2Value widget_type_uri); -/** 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. - */ +/** + 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. +*/ 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 - */ +/** + 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 +*/ 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. - */ +/** + 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. +*/ 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. - */ +/** + 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. +*/ SLV2_API SLV2Value slv2_ui_get_binary_uri(SLV2UI ui); -/** @} */ -/** @name Plugin UI Instance - * @{ - */ +/** + @} + @name Plugin UI Instance + @{ +*/ typedef struct _SLV2UIInstance* SLV2UIInstance; -/** DEPRECATED: Instantiate a plugin UI. - * This function is deprecated, it does not support widget wrapping. - * Use @ref slv2_ui_instance_new instead. - */ +/** + DEPRECATED: Instantiate a plugin UI. + This function is deprecated, it does not support widget wrapping. + Use @ref slv2_ui_instance_new instead. +*/ SLV2_DEPRECATED SLV2_API SLV2UIInstance @@ -1181,16 +1298,17 @@ slv2_ui_instantiate(SLV2Plugin plugin, LV2UI_Controller controller, const LV2_Feature* const* features); -/** 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. - * - * @param features NULL-terminated array of features the host supports. - * NULL may be passed if the host supports no additional features. - * - * @return NULL if instantiation failed. - */ +/** + 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. + + @param features NULL-terminated array of features the host supports. + NULL may be passed if the host supports no additional features. + + @return NULL if instantiation failed. +*/ SLV2_API SLV2UIInstance slv2_ui_instance_new(SLV2Plugin plugin, @@ -1200,24 +1318,27 @@ slv2_ui_instance_new(SLV2Plugin plugin, LV2UI_Controller controller, 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. - */ +/** + 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. +*/ SLV2_API void slv2_ui_instance_free(SLV2UIInstance instance); -/** Get the widget for the UI instance. - */ +/** + Get the widget for the UI instance. +*/ SLV2_API LV2UI_Widget slv2_ui_instance_get_widget(SLV2UIInstance instance); -/** Notify a UI about a change in a plugin port. - */ +/** + Notify a UI about a change in a plugin port. +*/ SLV2_API void slv2_ui_instance_port_event(SLV2UIInstance instance, @@ -1226,38 +1347,43 @@ slv2_ui_instance_port_event(SLV2UIInstance instance, uint32_t format, const void* buffer); -/** Return a data structure defined by some LV2 extension URI. - */ +/** + Return a data structure defined by some LV2 extension URI. +*/ SLV2_API const void* slv2_ui_instance_extension_data(SLV2UIInstance instance, const char* uri); -/** 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. - * - * The returned descriptor is shared and must not be deleted. - */ +/** + 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. + + The returned descriptor is shared and must not be deleted. +*/ SLV2_API 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. - * - * The returned handle is shared and must not be deleted. - */ +/** + 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. + + The returned handle is shared and must not be deleted. +*/ SLV2_API LV2UI_Handle slv2_ui_instance_get_handle(SLV2UIInstance instance); -/** @} */ -/** @} */ +/** + @} + @} +*/ #ifdef __cplusplus } /* extern "C" */ #endif -#endif /* SLV2_SLV2_H__ */ +#endif /* SLV2_SLV2_H */ -- cgit v1.2.1