From 809f5ae5999901be62f9d0cc1eb8a2d0f4806780 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Thu, 28 Apr 2011 21:56:29 +0000 Subject: Rename slv2 to lilv. API breakage was proving too much of a hassle, and would be even further of a mess after release and packaging. Best to make a clean break now, and fix installation to support parallel installs and prevent this kind of problem in the future. git-svn-id: http://svn.drobilla.net/lad/trunk/lilv@3217 a436a847-0d15-0410-975c-d299462d15a1 --- slv2/slv2.h | 1401 ----------------------------------------------------------- 1 file changed, 1401 deletions(-) delete mode 100644 slv2/slv2.h (limited to 'slv2/slv2.h') diff --git a/slv2/slv2.h b/slv2/slv2.h deleted file mode 100644 index 9fbbae7..0000000 --- a/slv2/slv2.h +++ /dev/null @@ -1,1401 +0,0 @@ -/* - Copyright 2007-2011 David Robillard - - Permission to use, copy, modify, and/or distribute this software for any - purpose with or without fee is hereby granted, provided that the above - copyright notice and this permission notice appear in all copies. - - THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR - ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF - OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -*/ - -/** - @file slv2.h API for SLV2, a lightweight LV2 host library. -*/ - -#ifndef SLV2_SLV2_H -#define SLV2_SLV2_H - -#include -#include -#include - -#include "lv2/lv2plug.in/ns/lv2core/lv2.h" - -#ifdef SLV2_SHARED -# ifdef __WIN32__ -# 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 -# define SLV2_API -#endif - -#ifdef __GNUC__ -# ifdef SLV2_INTERNAL -# define SLV2_DEPRECATED -# else -# define SLV2_DEPRECATED __attribute__((__deprecated__)) -# endif -#else -# 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" -#define SLV2_PORT_CLASS_OUTPUT "http://lv2plug.in/ns/lv2core#OutputPort" -#define SLV2_PORT_CLASS_CONTROL "http://lv2plug.in/ns/lv2core#ControlPort" -#define SLV2_PORT_CLASS_AUDIO "http://lv2plug.in/ns/lv2core#AudioPort" -#define SLV2_PORT_CLASS_EVENT "http://lv2plug.in/ns/ext/event#EventPort" -#define SLV2_EVENT_CLASS_MIDI "http://lv2plug.in/ns/ext/midi#MidiEvent" - -typedef struct _SLV2Plugin* SLV2Plugin; /**< LV2 Plugin. */ -typedef struct _SLV2PluginClass* SLV2PluginClass; /**< Plugin Class. */ -typedef struct _SLV2Port* SLV2Port; /**< Port. */ -typedef struct _SLV2ScalePoint* SLV2ScalePoint; /**< Scale Point (Notch). */ -typedef struct _SLV2UI* SLV2UI; /**< Plugin UI. */ -typedef struct _SLV2Value* SLV2Value; /**< Typed Value. */ -typedef struct _SLV2World* SLV2World; /**< SLV2 World. */ -typedef struct _SLV2UIInstance* SLV2UIInstance; /**< Plugin UI Instance. */ - -typedef void* SLV2PluginClasses; /**< set. */ -typedef void* SLV2Plugins; /**< set. */ -typedef void* SLV2ScalePoints; /**< set. */ -typedef void* SLV2UIs; /**< set. */ -typedef void* SLV2Values; /**< set. */ - -/** - @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); - -/** - 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. -*/ -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. -*/ -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. -*/ -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. -*/ -SLV2_API -SLV2Value -slv2_value_new_bool(SLV2World world, bool val); - -/** - Free an SLV2Value. -*/ -SLV2_API -void -slv2_value_free(SLV2Value val); - -/** - Duplicate an SLV2Value. -*/ -SLV2_API -SLV2Value -slv2_value_duplicate(SLV2Value val); - -/** - Return whether two values are equivalent. -*/ -SLV2_API -bool -slv2_value_equals(SLV2Value value, SLV2Value other); - -/** - Return this value as a Turtle/SPARQL token. - Returned value must be freed by caller with slv2_value_free. - - - - - - - - -
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). -*/ -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. -*/ -SLV2_API -const char* -slv2_value_as_uri(SLV2Value value); - -/** - 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. -*/ -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. -*/ -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 value (and not numeric). -*/ -SLV2_API -bool -slv2_value_is_string(SLV2Value value); - -/** - Return @a value as a string. -*/ -SLV2_API -const char* -slv2_value_as_string(SLV2Value value); - -/** - 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. -*/ -SLV2_API -float -slv2_value_as_float(SLV2Value value); - -/** - 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. -*/ -SLV2_API -int -slv2_value_as_int(SLV2Value value); - -/** - 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. -*/ -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 a similar basic API: -
    -
  • void PREFIX_free (coll)
    • -
  • unsigned PREFIX_size (coll)
    • -
  • SLV2Iter PREFIX_begin (coll)
    • -
  • ELEM PREFIX_get_at (coll, index) (DEPRECATED)
    • -
- @{ -*/ - -/* Collections */ - -typedef void* SLV2Iter; -typedef void* SLV2Collection; - -/** - Iterate over each element of a collection. - @code - SLV2_FOREACH(plugin_classes, i, classes) { - SLV2PluginClass c = slv2_plugin_classes_get(classes, i); - // ... - } - @endcode -*/ -#define SLV2_FOREACH(colltype, iter, collection) \ - for (SLV2Iter (iter) = slv2_ ## colltype ## _begin(collection); \ - !slv2_ ## colltype ## _is_end(collection, iter); \ - (iter) = slv2_ ## colltype ## _next(collection, iter)) - -/* SLV2PluginClasses */ - -SLV2_API -void -slv2_plugin_classes_free(SLV2PluginClasses collection); - -SLV2_API -unsigned -slv2_plugin_classes_size(SLV2PluginClasses collection); - -SLV2_API -SLV2Iter -slv2_plugin_classes_begin(SLV2PluginClasses collection); - -SLV2_API -SLV2PluginClass -slv2_plugin_classes_get(SLV2PluginClasses collection, SLV2Iter i); - -SLV2_API -SLV2Iter -slv2_plugin_classes_next(SLV2PluginClasses collection, SLV2Iter i); - -SLV2_API -bool -slv2_plugin_classes_is_end(SLV2PluginClasses collection, SLV2Iter i); - -SLV2_DEPRECATED -SLV2_API -SLV2PluginClass -slv2_plugin_classes_get_at(SLV2PluginClasses collection, 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. -*/ -SLV2_API -SLV2PluginClass -slv2_plugin_classes_get_by_uri(SLV2PluginClasses classes, - SLV2Value uri); - -/* ScalePoints */ - -SLV2_API -void -slv2_scale_points_free(SLV2ScalePoints collection); - -SLV2_API -unsigned -slv2_scale_points_size(SLV2ScalePoints collection); - -SLV2_API -SLV2Iter -slv2_scale_points_begin(SLV2ScalePoints collection); - -SLV2_API -SLV2ScalePoint -slv2_scale_points_get(SLV2ScalePoints collection, SLV2Iter i); - -SLV2_API -SLV2Iter -slv2_scale_points_next(SLV2ScalePoints collection, SLV2Iter i); - -SLV2_API -bool -slv2_scale_points_is_end(SLV2ScalePoints collection, SLV2Iter i); - -SLV2_DEPRECATED -SLV2_API -SLV2ScalePoint -slv2_scale_points_get_at(SLV2ScalePoints collection, unsigned index); - -/* UIs */ - -SLV2_API -void -slv2_uis_free(SLV2UIs collection); - -SLV2_API -unsigned -slv2_uis_size(SLV2UIs collection); - -SLV2_API -SLV2Iter -slv2_uis_begin(SLV2UIs collection); - -SLV2_API -SLV2UI -slv2_uis_get(SLV2UIs collection, SLV2Iter i); - -SLV2_API -SLV2Iter -slv2_uis_next(SLV2UIs collection, SLV2Iter i); - -SLV2_API -bool -slv2_uis_is_end(SLV2UIs collection, SLV2Iter i); - -SLV2_DEPRECATED -SLV2_API -SLV2UI -slv2_uis_get_at(SLV2UIs collection, unsigned index); - -/** - 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); - -/* Values */ - -SLV2_API -void -slv2_values_free(SLV2Values collection); - -SLV2_API -unsigned -slv2_values_size(SLV2Values collection); - -SLV2_API -SLV2Iter -slv2_values_begin(SLV2Values collection); - -SLV2_API -SLV2Value -slv2_values_get(SLV2Values collection, SLV2Iter i); - -SLV2_API -SLV2Iter -slv2_values_next(SLV2Values collection, SLV2Iter i); - -SLV2_API -bool -slv2_values_is_end(SLV2Values collection, SLV2Iter i); - -SLV2_API -SLV2Value -slv2_values_get_first(SLV2Values collection); - -SLV2_DEPRECATED -SLV2_API -SLV2Value -slv2_values_get_at(SLV2Values collection, unsigned index); - -/** - Return whether @a values contains @a value. -*/ -SLV2_API -bool -slv2_values_contains(SLV2Values values, SLV2Value value); - -/* Plugins */ - -SLV2_API -unsigned -slv2_plugins_size(SLV2Plugins collection); - -SLV2_API -SLV2Iter -slv2_plugins_begin(SLV2Plugins collection); - -SLV2_API -SLV2Plugin -slv2_plugins_get(SLV2Plugins collection, SLV2Iter i); - -SLV2_API -SLV2Iter -slv2_plugins_next(SLV2Plugins collection, SLV2Iter i); - -SLV2_API -bool -slv2_plugins_is_end(SLV2Plugins collection, SLV2Iter i); - -SLV2_DEPRECATED -SLV2_API -SLV2Plugin -slv2_plugins_get_at(SLV2Plugins collection, unsigned index); - -SLV2_API -void -slv2_plugins_free(SLV2World world, 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. -*/ -SLV2_API -SLV2Plugin -slv2_plugins_get_by_uri(SLV2Plugins plugins, - SLV2Value uri); - -/** - @} - @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. -*/ -#define SLV2_OPTION_FILTER_LANG "http://drobilla.net/ns/slv2#filter-lang" - -/** - Enable/disable dynamic manifest support. - Dynamic manifest data will only be loaded if this option is true. -*/ -#define SLV2_OPTION_DYN_MANIFEST "http://drobilla.net/ns/slv2#dyn-manifest" - -/** - Set an SLV2 option for @a world. - - Currently recognized options: - @ref SLV2_OPTION_FILTER_LANG - @ref SLV2_OPTION_DYN_MANIFEST -*/ -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. -*/ -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). -*/ -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. -*/ -SLV2_API -void -slv2_world_load_bundle(SLV2World world, - SLV2Value bundle_uri); - -/** - 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. -*/ -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). - - The returned list and the plugins it contains are owned by @a world - and must not be freed by caller. -*/ -SLV2_API -SLV2Plugins -slv2_world_get_all_plugins(SLV2World world); - -/** - 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. -*/ -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. -*/ -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. -*/ -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. -*/ -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. -*/ -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. -*/ -SLV2_API -SLV2Value -slv2_plugin_get_name(SLV2Plugin plugin); - -/** - 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. -*/ -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. -*/ -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. -*/ -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. -*/ -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. -*/ -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. -*/ -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. -*/ -SLV2_API -SLV2Values -slv2_plugin_get_optional_features(SLV2Plugin p); - -/** - 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. -*/ -SLV2_API -void -slv2_plugin_get_port_ranges_float(SLV2Plugin p, - float* min_values, - 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. -*/ -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. -*/ -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. -*/ -SLV2_API -uint32_t -slv2_plugin_get_latency_port_index(SLV2Plugin p); - -/** - 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. -*/ -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. -*/ -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. -*/ -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. -*/ -SLV2_API -SLV2Value -slv2_plugin_get_author_homepage(SLV2Plugin plugin); - -/** - Return true iff @a plugin has been replaced by another plugin. - - The plugin will still be usable, but hosts should hide them from their - user interfaces to prevent users from using deprecated plugins. -*/ -SLV2_API -bool -slv2_plugin_is_replaced(SLV2Plugin plugin); - -/** - @} - @name Port - @{ -*/ - -/** - 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. -*/ -SLV2_API -SLV2Values -slv2_port_get_value_by_qname(SLV2Plugin plugin, - SLV2Port port, - const char* predicate); - -/** - 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. -*/ -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. -*/ -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. -*/ -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. -*/ -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. -*/ -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. -*/ -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. -*/ -SLV2_API -void -slv2_port_get_range(SLV2Plugin plugin, - SLV2Port port, - SLV2Value* deflt, - 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. -*/ -SLV2_API -SLV2ScalePoints -slv2_port_get_scale_points(SLV2Plugin plugin, - SLV2Port port); - -/** - @} - @name Scale Point - @{ -*/ - -/** - 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. -*/ -SLV2_API -SLV2Value -slv2_scale_point_get_value(SLV2ScalePoint point); - -/** - @} - @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. -*/ -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. -*/ -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. -*/ -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. -*/ -SLV2_API -SLV2PluginClasses -slv2_plugin_class_get_children(SLV2PluginClass plugin_class); - -/** - @} - @name Plugin Instance - @{ -*/ - -typedef struct _SLV2InstanceImpl* SLV2InstanceImpl; - -/** - @cond 0 -*/ - -/* 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. -*/ -typedef struct _Instance { - const LV2_Descriptor* lv2_descriptor; - LV2_Handle lv2_handle; - SLV2InstanceImpl pimpl; -}* SLV2Instance; - -/** - @endcond -*/ - -/** - 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. -*/ -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. -*/ -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. -*/ -static inline void -slv2_instance_connect_port(SLV2Instance instance, - uint32_t port_index, - void* data_location) -{ - instance->lv2_descriptor->connect_port - (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. -*/ -static inline void -slv2_instance_activate(SLV2Instance instance) -{ - if (instance->lv2_descriptor->activate) - 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. -*/ -static inline void -slv2_instance_run(SLV2Instance instance, - uint32_t 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). -*/ -static inline void -slv2_instance_deactivate(SLV2Instance instance) -{ - if (instance->lv2_descriptor->deactivate) - 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. -*/ -static inline const void* -slv2_instance_get_extension_data(SLV2Instance instance, - const char* uri) -{ - if (instance->lv2_descriptor->extension_data) - return instance->lv2_descriptor->extension_data(uri); - else - 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. -*/ -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. -*/ -static inline LV2_Handle -slv2_instance_get_handle(SLV2Instance instance) -{ - return instance->lv2_handle; -} - -#endif /* SLV2_INTERNAL */ - -/** - @} - @name Plugin UI - @{ -*/ - -/** - 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 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); - -/** - 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. - - Note that in most cases slv2_ui_is_supported should be used which finds the - UI type, avoding the need to use this function (and type specific logic). -*/ -SLV2_API -SLV2Values -slv2_ui_get_classes(SLV2UI ui); - -/** - Check whether a plugin UI has 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); - -/** - Function to determine whether a UI type is supported. - - This is provided by the user and must return non-zero iff using a UI of type - @c ui_type_uri in a container of type @c container_type_uri is supported. -*/ -typedef unsigned (*SLV2UISupportedFunc)(const char* container_type_uri, - const char* ui_type_uri); - -/** - Return true iff a Plugin UI is supported as a given widget type. - @param ui The Plugin UI - @param supported_func User provided supported predicate. - @param container_type The widget type to host the UI within. - @param ui_type (Output) If non-NULL, set to the native type of the UI - which the caller must free with slv2_value_free. - @return The embedding quality level returned by @c supported_func. -*/ -SLV2_API -unsigned -slv2_ui_is_supported(SLV2UI ui, - SLV2UISupportedFunc supported_func, - SLV2Value container_type, - SLV2Value* ui_type); - -/** - 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. -*/ -SLV2_API -SLV2Value -slv2_ui_get_binary_uri(SLV2UI ui); - -/** - @} - @} -*/ - -#ifdef __cplusplus -} /* extern "C" */ -#endif - -#endif /* SLV2_SLV2_H */ -- cgit v1.2.1