SLV2 is a simple yet powerful C API for using LV2 plugins. More...

Value
const char *	slv2_uri_to_path (const char *uri)
SLV2Value	slv2_value_new_uri (SLV2World world, const char *uri)
SLV2Value	slv2_value_new_string (SLV2World world, const char *str)
SLV2Value	slv2_value_new_int (SLV2World world, int val)
SLV2Value	slv2_value_new_float (SLV2World world, float val)
SLV2Value	slv2_value_new_bool (SLV2World world, bool val)
void	slv2_value_free (SLV2Value val)
SLV2Value	slv2_value_duplicate (SLV2Value val)
bool	slv2_value_equals (SLV2Value value, SLV2Value other)
char *	slv2_value_get_turtle_token (SLV2Value value)
bool	slv2_value_is_uri (SLV2Value value)
const char *	slv2_value_as_uri (SLV2Value value)
bool	slv2_value_is_blank (SLV2Value value)
const char *	slv2_value_as_blank (SLV2Value value)
bool	slv2_value_is_literal (SLV2Value value)
bool	slv2_value_is_string (SLV2Value value)
const char *	slv2_value_as_string (SLV2Value value)
bool	slv2_value_is_float (SLV2Value value)
float	slv2_value_as_float (SLV2Value value)
bool	slv2_value_is_int (SLV2Value value)
int	slv2_value_as_int (SLV2Value value)
bool	slv2_value_is_bool (SLV2Value value)
bool	slv2_value_as_bool (SLV2Value value)
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)
typedef void *	SLV2Iter
typedef void *	SLV2Collection
SLV2Iter	slv2_iter_next (SLV2Iter i)
bool	slv2_iter_end (SLV2Iter i)
SLV2Iter	slv2_collection_begin (SLV2Collection collection)
void *	slv2_collection_get (SLV2Collection collection, SLV2Iter i)
void	slv2_plugin_classes_free (SLV2PluginClasses collection)
unsigned	slv2_plugin_classes_size (SLV2PluginClasses collection)
SLV2Iter	slv2_plugin_classes_begin (SLV2PluginClasses collection)
SLV2PluginClass	slv2_plugin_classes_get (SLV2PluginClasses collection, SLV2Iter i)
SLV2PluginClass	slv2_plugin_classes_get_at (SLV2PluginClasses collection, unsigned index)
SLV2ScalePoints	slv2_scale_points_new (void)
void	slv2_scale_points_free (SLV2ScalePoints collection)
unsigned	slv2_scale_points_size (SLV2ScalePoints collection)
SLV2Iter	slv2_scale_points_begin (SLV2ScalePoints collection)
SLV2ScalePoint	slv2_scale_points_get (SLV2ScalePoints collection, SLV2Iter i)
SLV2ScalePoint	slv2_scale_points_get_at (SLV2ScalePoints collection, unsigned index)
void	slv2_uis_free (SLV2UIs collection)
unsigned	slv2_uis_size (SLV2UIs collection)
SLV2Iter	slv2_uis_begin (SLV2UIs collection)
SLV2UI	slv2_uis_get (SLV2UIs collection, SLV2Iter i)
SLV2UI	slv2_uis_get_at (SLV2UIs collection, unsigned index)
SLV2ScalePoints	slv2_values_new (void)
void	slv2_values_free (SLV2Values collection)
unsigned	slv2_values_size (SLV2Values collection)
SLV2Iter	slv2_values_begin (SLV2Values collection)
SLV2Value	slv2_values_get (SLV2Values collection, SLV2Iter i)
SLV2Value	slv2_values_get_first (SLV2Values collection)
SLV2Value	slv2_values_get_at (SLV2Values collection, unsigned index)
unsigned	slv2_plugins_size (SLV2Plugins collection)
SLV2Iter	slv2_plugins_begin (SLV2Plugins collection)
SLV2Plugin	slv2_plugins_get (SLV2Plugins collection, SLV2Iter i)
SLV2Plugin	slv2_plugins_get_at (SLV2Plugins collection, unsigned index)
void	slv2_plugins_free (SLV2World world, SLV2Plugins plugins)
SLV2Plugin	slv2_plugins_get_by_uri (SLV2Plugins plugins, SLV2Value uri)
SLV2PluginClass	slv2_plugin_classes_get_by_uri (SLV2PluginClasses classes, SLV2Value uri)
bool	slv2_values_contains (SLV2Values values, SLV2Value value)
#define	SLV2_FOREACH(iter, collection)
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 slv2_world_load_all to discover/load the system's LV2 resources.
SLV2World	slv2_world_new (void)
void	slv2_world_set_option (SLV2World world, const char *uri, const SLV2Value value)
void	slv2_world_free (SLV2World world)
void	slv2_world_load_all (SLV2World world)
void	slv2_world_load_bundle (SLV2World world, SLV2Value bundle_uri)
SLV2PluginClass	slv2_world_get_plugin_class (SLV2World world)
SLV2PluginClasses	slv2_world_get_plugin_classes (SLV2World world)
SLV2Plugins	slv2_world_get_all_plugins (SLV2World world)
SLV2Plugin	slv2_world_get_plugin_by_uri_string (SLV2World world, const char *uri)
#define	SLV2_OPTION_FILTER_LANG "http://drobilla.net/ns/slv2#filter-lang"
#define	SLV2_OPTION_DYN_MANIFEST "http://drobilla.net/ns/slv2#dyn-manifest"
Plugin
bool	slv2_plugin_verify (SLV2Plugin plugin)
SLV2Value	slv2_plugin_get_uri (SLV2Plugin plugin)
SLV2Value	slv2_plugin_get_bundle_uri (SLV2Plugin plugin)
SLV2Values	slv2_plugin_get_data_uris (SLV2Plugin plugin)
SLV2Value	slv2_plugin_get_library_uri (SLV2Plugin plugin)
SLV2Value	slv2_plugin_get_name (SLV2Plugin plugin)
SLV2PluginClass	slv2_plugin_get_class (SLV2Plugin plugin)
SLV2Values	slv2_plugin_get_value (SLV2Plugin p, SLV2Value predicate)
SLV2Values	slv2_plugin_get_value_by_qname (SLV2Plugin p, const char *predicate)
SLV2Values	slv2_plugin_get_value_for_subject (SLV2Plugin p, SLV2Value subject_uri, SLV2Value predicate_uri)
bool	slv2_plugin_has_feature (SLV2Plugin p, SLV2Value feature_uri)
SLV2Values	slv2_plugin_get_supported_features (SLV2Plugin p)
SLV2Values	slv2_plugin_get_required_features (SLV2Plugin p)
SLV2Values	slv2_plugin_get_optional_features (SLV2Plugin p)
uint32_t	slv2_plugin_get_num_ports (SLV2Plugin p)
void	slv2_plugin_get_port_ranges_float (SLV2Plugin p, float min_values, float max_values, float *def_values)
uint32_t	slv2_plugin_get_num_ports_of_class (SLV2Plugin p, SLV2Value class_1,...)
bool	slv2_plugin_has_latency (SLV2Plugin p)
uint32_t	slv2_plugin_get_latency_port_index (SLV2Plugin p)
SLV2Port	slv2_plugin_get_port_by_index (SLV2Plugin plugin, uint32_t index)
SLV2Port	slv2_plugin_get_port_by_symbol (SLV2Plugin plugin, SLV2Value symbol)
SLV2Value	slv2_plugin_get_author_name (SLV2Plugin plugin)
SLV2Value	slv2_plugin_get_author_email (SLV2Plugin plugin)
SLV2Value	slv2_plugin_get_author_homepage (SLV2Plugin plugin)
bool	slv2_plugin_is_replaced (SLV2Plugin plugin)
Port
SLV2Values	slv2_port_get_value (SLV2Plugin plugin, SLV2Port port, SLV2Value predicate)
SLV2Values	slv2_port_get_value_by_qname (SLV2Plugin plugin, SLV2Port port, const char *predicate)
SLV2Values	slv2_port_get_properties (SLV2Plugin plugin, SLV2Port port)
bool	slv2_port_has_property (SLV2Plugin p, SLV2Port port, SLV2Value property_uri)
bool	slv2_port_supports_event (SLV2Plugin p, SLV2Port port, SLV2Value event_uri)
SLV2Value	slv2_port_get_symbol (SLV2Plugin plugin, SLV2Port port)
SLV2Value	slv2_port_get_name (SLV2Plugin plugin, SLV2Port port)
SLV2Values	slv2_port_get_classes (SLV2Plugin plugin, SLV2Port port)
bool	slv2_port_is_a (SLV2Plugin plugin, SLV2Port port, SLV2Value port_class)
void	slv2_port_get_range (SLV2Plugin plugin, SLV2Port port, SLV2Value deflt, SLV2Value min, SLV2Value *max)
SLV2ScalePoints	slv2_port_get_scale_points (SLV2Plugin plugin, SLV2Port port)
Scale Point
SLV2Value	slv2_scale_point_get_label (SLV2ScalePoint point)
SLV2Value	slv2_scale_point_get_value (SLV2ScalePoint point)
Plugin Class
SLV2Value	slv2_plugin_class_get_parent_uri (SLV2PluginClass plugin_class)
SLV2Value	slv2_plugin_class_get_uri (SLV2PluginClass plugin_class)
SLV2Value	slv2_plugin_class_get_label (SLV2PluginClass plugin_class)
SLV2PluginClasses	slv2_plugin_class_get_children (SLV2PluginClass plugin_class)
Plugin Instance
typedef struct _SLV2InstanceImpl *	SLV2InstanceImpl
SLV2Instance	slv2_plugin_instantiate (SLV2Plugin plugin, double sample_rate, const LV2_Feature const features)
void	slv2_instance_free (SLV2Instance instance)
static const char *	slv2_instance_get_uri (SLV2Instance instance)
static void	slv2_instance_connect_port (SLV2Instance instance, uint32_t port_index, void *data_location)
static void	slv2_instance_activate (SLV2Instance instance)
static void	slv2_instance_run (SLV2Instance instance, uint32_t sample_count)
static void	slv2_instance_deactivate (SLV2Instance instance)
static const void *	slv2_instance_get_extension_data (SLV2Instance instance, const char *uri)
static const LV2_Descriptor *	slv2_instance_get_descriptor (SLV2Instance instance)
static LV2_Handle	slv2_instance_get_handle (SLV2Instance instance)
Plugin UI
SLV2UI	slv2_uis_get_by_uri (SLV2UIs uis, SLV2Value uri)
SLV2UIs	slv2_plugin_get_uis (SLV2Plugin plugin)
SLV2UI	slv2_plugin_get_default_ui (SLV2Plugin plugin, SLV2Value widget_type_uri)
SLV2Value	slv2_ui_get_uri (SLV2UI ui)
bool	slv2_ui_supported (SLV2UI ui, SLV2Value widget_type_uri)
SLV2Values	slv2_ui_get_classes (SLV2UI ui)
bool	slv2_ui_is_a (SLV2UI ui, SLV2Value class_uri)
SLV2Value	slv2_ui_get_bundle_uri (SLV2UI ui)
SLV2Value	slv2_ui_get_binary_uri (SLV2UI ui)
Plugin UI Instance
typedef uint32_t(*	SLV2PortIndexFunction )(LV2UI_Controller controller, const char *port_symbol)
typedef uint32_t(*	SLV2PortSubscribeFunction )(LV2UI_Controller controller, uint32_t port_index, uint32_t protocol)
typedef uint32_t(*	SLV2PortUnsubscribeFunction )(LV2UI_Controller controller, uint32_t port_index, uint32_t protocol)
SLV2UIInstance	slv2_ui_instantiate (SLV2Plugin plugin, SLV2UI ui, LV2UI_Write_Function write_function, LV2UI_Controller controller, const LV2_Feature const features)
SLV2UIHost	slv2_ui_host_new (LV2UI_Write_Function write_function, SLV2PortIndexFunction port_index_function, SLV2PortSubscribeFunction port_subscribe_function, SLV2PortUnsubscribeFunction port_unsubscribe_function)
void	slv2_ui_host_free (SLV2UIHost ui_host)
SLV2UIInstance	slv2_ui_instance_new (SLV2Plugin plugin, SLV2UI ui, SLV2Value widget_type_uri, SLV2UIHost ui_host, LV2UI_Controller controller, const LV2_Feature const features)
void	slv2_ui_instance_free (SLV2UIInstance instance)
LV2UI_Widget	slv2_ui_instance_get_widget (SLV2UIInstance instance)
void	slv2_ui_instance_port_event (SLV2UIInstance instance, uint32_t port_index, uint32_t buffer_size, uint32_t format, const void *buffer)
const void *	slv2_ui_instance_extension_data (SLV2UIInstance instance, const char *uri)
const LV2UI_Descriptor *	slv2_ui_instance_get_descriptor (SLV2UIInstance instance)
LV2UI_Handle	slv2_ui_instance_get_handle (SLV2UIInstance instance)

Detailed Description

SLV2 is a simple yet powerful C API for using LV2 plugins.

For more information about LV2, see <http://lv2plug.in>. For more information about SLV2, see <http://drobilla.net/software/slv2>.

Define Documentation

#define SLV2_FOREACH	(	iter,
		collection
	)

Value:

for (SLV2Iter (iter) = slv2_collection_begin(collection); \
         !slv2_iter_end(iter); \
         (iter) = slv2_iter_next(iter))

#define SLV2_OPTION_FILTER_LANG "http://drobilla.net/ns/slv2#filter-lang"

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_DYN_MANIFEST "http://drobilla.net/ns/slv2#dyn-manifest"

Enable/disable dynamic manifest support.

Dynamic manifest data will only be loaded if this option is true.

Typedef Documentation

typedef void* SLV2Iter

typedef void* SLV2Collection

typedef struct _SLV2InstanceImpl* SLV2InstanceImpl

typedef uint32_t(* SLV2PortIndexFunction)(LV2UI_Controller controller, const char *port_symbol)

typedef uint32_t(* SLV2PortSubscribeFunction)(LV2UI_Controller controller, uint32_t port_index, uint32_t protocol)

typedef uint32_t(* SLV2PortUnsubscribeFunction)(LV2UI_Controller controller, uint32_t port_index, uint32_t protocol)

Function Documentation

const char* slv2_uri_to_path ( const char * uri )

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.

Returns:: uri converted to a path, or NULL on failure (URI is not local).

SLV2Value slv2_value_new_uri	(	SLV2World	world,
		const char *	uri
	)

Create a new URI value.

Returned value must be freed by caller with slv2_value_free.

SLV2Value slv2_value_new_string	(	SLV2World	world,
		const char *	str
	)

Create a new string value (with no language).

Returned value must be freed by caller with slv2_value_free.

SLV2Value slv2_value_new_int	(	SLV2World	world,
		int	val
	)

Create a new integer value.

Returned value must be freed by caller with slv2_value_free.

SLV2Value slv2_value_new_float	(	SLV2World	world,
		float	val
	)

Create a new floating point value.

Returned value must be freed by caller with slv2_value_free.

SLV2Value slv2_value_new_bool	(	SLV2World	world,
		bool	val
	)

Create a new boolean value.

Returned value must be freed by caller with slv2_value_free.

void slv2_value_free ( SLV2Value val )

Free an SLV2Value.

SLV2Value slv2_value_duplicate ( SLV2Value val )

Duplicate an SLV2Value.

bool slv2_value_equals	(	SLV2Value	value,
		SLV2Value	other
	)

Return whether two values are equivalent.

char* slv2_value_get_turtle_token ( SLV2Value value )

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 >
QName	doap:name
String	"this is a string"
Float	1.0
Integer	1
Boolean	true

bool slv2_value_is_uri ( SLV2Value value )

Return whether the value is a URI (resource).

const char* slv2_value_as_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(value) returns true. Returned value is owned by value and must not be freed by caller.

bool slv2_value_is_blank ( SLV2Value value )

Return whether the value is a blank node (resource with no URI).

const char* slv2_value_as_blank ( SLV2Value value )

Return this value as a blank node identifier, e.g.

"genid03". Valid to call only if slv2_value_is_blank(value) returns true. Returned value is owned by value and must not be freed by caller.

bool slv2_value_is_literal ( SLV2Value value )

Return whether this value is a literal (i.e.

not a URI). Returns true if value is a string or numeric value.

bool slv2_value_is_string ( SLV2Value value )

Return whether this value is a string literal.

Returns true if value is a string value (and not numeric).

const char* slv2_value_as_string ( SLV2Value value )

Return value as a string.

bool slv2_value_is_float ( SLV2Value value )

Return whether this value is a decimal literal.

float slv2_value_as_float ( SLV2Value value )

Return value as a float.

Valid to call only if slv2_value_is_float(value) or slv2_value_is_int(value) returns true.

bool slv2_value_is_int ( SLV2Value value )

Return whether this value is an integer literal.

int slv2_value_as_int ( SLV2Value value )

Return value as an integer.

Valid to call only if slv2_value_is_int(value) returns true.

bool slv2_value_is_bool ( SLV2Value value )

Return whether this value is a boolean.

bool slv2_value_as_bool ( SLV2Value value )

Return value as a bool.

Valid to call only if slv2_value_is_bool(value) returns true.

SLV2Iter slv2_iter_next ( SLV2Iter i )

Increment i to point at the next element in the collection.

bool slv2_iter_end ( SLV2Iter i )

Return true iff i is at the end of the collection.

SLV2Iter slv2_collection_begin ( SLV2Collection collection )

void* slv2_collection_get	(	SLV2Collection	collection,
		SLV2Iter	i
	)

void slv2_plugin_classes_free ( SLV2PluginClasses collection )

unsigned slv2_plugin_classes_size ( SLV2PluginClasses collection )

SLV2Iter slv2_plugin_classes_begin ( SLV2PluginClasses collection )

SLV2PluginClass slv2_plugin_classes_get	(	SLV2PluginClasses	collection,
		SLV2Iter	i
	)

SLV2PluginClass slv2_plugin_classes_get_at	(	SLV2PluginClasses	collection,
		unsigned	index
	)

SLV2ScalePoints slv2_scale_points_new ( void )

void slv2_scale_points_free ( SLV2ScalePoints collection )

unsigned slv2_scale_points_size ( SLV2ScalePoints collection )

SLV2Iter slv2_scale_points_begin ( SLV2ScalePoints collection )

SLV2ScalePoint slv2_scale_points_get	(	SLV2ScalePoints	collection,
		SLV2Iter	i
	)

SLV2ScalePoint slv2_scale_points_get_at	(	SLV2ScalePoints	collection,
		unsigned	index
	)

void slv2_uis_free ( SLV2UIs collection )

unsigned slv2_uis_size ( SLV2UIs collection )

SLV2Iter slv2_uis_begin ( SLV2UIs collection )

SLV2UI slv2_uis_get	(	SLV2UIs	collection,
		SLV2Iter	i
	)

SLV2UI slv2_uis_get_at	(	SLV2UIs	collection,
		unsigned	index
	)

SLV2ScalePoints slv2_values_new ( void )

void slv2_values_free ( SLV2Values collection )

unsigned slv2_values_size ( SLV2Values collection )

SLV2Iter slv2_values_begin ( SLV2Values collection )

SLV2Value slv2_values_get	(	SLV2Values	collection,
		SLV2Iter	i
	)

SLV2Value slv2_values_get_first ( SLV2Values collection )

SLV2Value slv2_values_get_at	(	SLV2Values	collection,
		unsigned	index
	)

unsigned slv2_plugins_size ( SLV2Plugins collection )

SLV2Iter slv2_plugins_begin ( SLV2Plugins collection )

SLV2Plugin slv2_plugins_get	(	SLV2Plugins	collection,
		SLV2Iter	i
	)

SLV2Plugin slv2_plugins_get_at	(	SLV2Plugins	collection,
		unsigned	index
	)

void slv2_plugins_free	(	SLV2World	world,
		SLV2Plugins	plugins
	)

This function is deprecated, it does nothing.

SLV2Plugin slv2_plugins_get_by_uri	(	SLV2Plugins	plugins,
		SLV2Value	uri
	)

Get a plugin from plugins by URI.

Return value is shared (stored in plugins) and must not be freed or modified by the caller in any way.

Returns:: NULL if no plugin with uri is found in plugins.

SLV2PluginClass slv2_plugin_classes_get_by_uri	(	SLV2PluginClasses	classes,
		SLV2Value	uri
	)

Get a plugin class from classes by URI.

Return value is shared (stored in classes) and must not be freed or modified by the caller in any way.

Returns:: NULL if no plugin class with uri is found in classes.

bool slv2_values_contains	(	SLV2Values	values,
		SLV2Value	value
	)

Return whether values contains value.

SLV2World slv2_world_new ( void )

Initialize a new, empty world.

If initialization fails, NULL is returned.

void slv2_world_set_option	(	SLV2World	world,
		const char *	uri,
		const SLV2Value	value
	)

Set an SLV2 option for world.

Currently recognized options: SLV2_OPTION_FILTER_LANG SLV2_OPTION_DYN_MANIFEST

void slv2_world_free ( SLV2World world )

Destroy the world, mwahaha.

Note that destroying 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.

void slv2_world_load_all ( 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).

void slv2_world_load_bundle	(	SLV2World	world,
		SLV2Value	bundle_uri
	)

Load a specific bundle.

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.

SLV2PluginClass slv2_world_get_plugin_class ( SLV2World world )

Get the parent of all other plugin classes, lv2:Plugin.

SLV2PluginClasses slv2_world_get_plugin_classes ( SLV2World world )

Return a list of all found plugin classes.

Returned list is owned by world and must not be freed by the caller.

SLV2Plugins slv2_world_get_all_plugins ( 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 world and must not be freed by caller.

SLV2Plugin slv2_world_get_plugin_by_uri_string	(	SLV2World	world,
		const char *	uri
	)

Return the plugin with the given uri, or NULL if not found.

bool slv2_plugin_verify ( SLV2Plugin plugin )

Check if 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.

Returns:: true iff plugin is valid.

SLV2Value slv2_plugin_get_uri ( SLV2Plugin plugin )

Get the URI of 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.

Returns:: A shared URI value which must not be modified or freed.

SLV2Value slv2_plugin_get_bundle_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.

Returns:: a shared string which must not be modified or freed.

SLV2Values slv2_plugin_get_data_uris ( 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.

Returns:: a list of complete URLs eg. "file:///foo/ABundle.lv2/aplug.ttl", which is shared and must not be modified or freed.

SLV2Value slv2_plugin_get_library_uri ( SLV2Plugin plugin )

Get the (resolvable) URI of the shared library for plugin.

Note this always returns a fully qualified URI. If you want a local filesystem path, use slv2_uri_to_path.

Returns:: a shared string which must not be modified or freed.

SLV2Value slv2_plugin_get_name ( SLV2Plugin plugin )

Get the name of 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.

SLV2PluginClass slv2_plugin_get_class ( SLV2Plugin plugin )

Get the class this plugin belongs to (ie Filters).

SLV2Values slv2_plugin_get_value	(	SLV2Plugin	p,
		SLV2Value	predicate
	)

Get a value associated with the plugin in a plugin's data files.

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.

SLV2Values slv2_plugin_get_value_by_qname	(	SLV2Plugin	p,
		const char *	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.

SLV2Values slv2_plugin_get_value_for_subject	(	SLV2Plugin	p,
		SLV2Value	subject_uri,
		SLV2Value	predicate_uri
	)

Get a value associated with some subject in a plugin's data files.

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.

bool slv2_plugin_has_feature	(	SLV2Plugin	p,
		SLV2Value	feature_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.

SLV2Values slv2_plugin_get_supported_features ( SLV2Plugin p )

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.

SLV2Values slv2_plugin_get_required_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.

SLV2Values slv2_plugin_get_optional_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.

uint32_t slv2_plugin_get_num_ports ( SLV2Plugin p )

Get the number of ports on this plugin.

void slv2_plugin_get_port_ranges_float	(	SLV2Plugin	p,
		float *	min_values,
		float *	max_values,
		float *	def_values
	)

Get the port ranges (minimum, maximum and default values) for all ports.

min_values, max_values and 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.

uint32_t slv2_plugin_get_num_ports_of_class	(	SLV2Plugin	p,
		SLV2Value	class_1,
			...
	)

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.

bool slv2_plugin_has_latency ( SLV2Plugin p )

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.

uint32_t slv2_plugin_get_latency_port_index ( 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.

SLV2Port slv2_plugin_get_port_by_index	(	SLV2Plugin	plugin,
		uint32_t	index
	)

Get a port on plugin by index.

SLV2Port slv2_plugin_get_port_by_symbol	(	SLV2Plugin	plugin,
		SLV2Value	symbol
	)

Get a port on plugin by symbol.

Note this function is slower than slv2_plugin_get_port_by_index, especially on plugins with a very large number of ports.

SLV2Value slv2_plugin_get_author_name ( SLV2Plugin plugin )

Get the full name of the plugin's author.

Returns NULL if author name is not present. Returned value must be freed by caller.

SLV2Value slv2_plugin_get_author_email ( 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.

SLV2Value slv2_plugin_get_author_homepage ( 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.

bool slv2_plugin_is_replaced ( SLV2Plugin plugin )

Return true iff 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.

SLV2Values slv2_port_get_value	(	SLV2Plugin	plugin,
		SLV2Port	port,
		SLV2Value	predicate
	)

Port analog of slv2_plugin_get_value.

SLV2Values slv2_port_get_value_by_qname	(	SLV2Plugin	plugin,
		SLV2Port	port,
		const char *	predicate
	)

Port analog of slv2_plugin_get_value_by_qname.

SLV2Values slv2_port_get_properties	(	SLV2Plugin	plugin,
		SLV2Port	port
	)

Return the LV2 port properties of a port.

bool slv2_port_has_property	(	SLV2Plugin	p,
		SLV2Port	port,
		SLV2Value	property_uri
	)

Return whether a port has a certain property.

bool slv2_port_supports_event	(	SLV2Plugin	p,
		SLV2Port	port,
		SLV2Value	event_uri
	)

Return whether a port is an event port and supports a certain event type.

SLV2Value slv2_port_get_symbol	(	SLV2Plugin	plugin,
		SLV2Port	port
	)

Get the symbol of a port.

The 'symbol' is a short string, a valid C identifier. Returned value is owned by port and must not be freed.

SLV2Value slv2_port_get_name	(	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.

SLV2Values slv2_port_get_classes	(	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.

bool slv2_port_is_a	(	SLV2Plugin	plugin,
		SLV2Port	port,
		SLV2Value	port_class
	)

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.

void slv2_port_get_range	(	SLV2Plugin	plugin,
		SLV2Port	port,
		SLV2Value *	deflt,
		SLV2Value *	min,
		SLV2Value *	max
	)

Get the default, minimum, and maximum values of a port.

def, min, and 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.

SLV2ScalePoints slv2_port_get_scale_points	(	SLV2Plugin	plugin,
		SLV2Port	port
	)

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 port has no scale points, otherwise it must be freed by caller with slv2_scale_points_free.

SLV2Value slv2_scale_point_get_label ( SLV2ScalePoint point )

Get the label of this scale point (enumeration value) Returned value is owned by point and must not be freed.

SLV2Value slv2_scale_point_get_value ( SLV2ScalePoint point )

Get the value of this scale point (enumeration value) Returned value is owned by point and must not be freed.

SLV2Value slv2_plugin_class_get_parent_uri ( SLV2PluginClass plugin_class )

Get the URI of this class' superclass.

Returned value is owned by plugin_class and must not be freed by caller. Returned value may be NULL, if class has no parent.

SLV2Value slv2_plugin_class_get_uri ( SLV2PluginClass plugin_class )

Get the URI of this plugin class.

Returned value is owned by plugin_class and must not be freed by caller.

SLV2Value slv2_plugin_class_get_label ( SLV2PluginClass plugin_class )

Get the label of this plugin class, ie "Oscillators".

Returned value is owned by plugin_class and must not be freed by caller.

SLV2PluginClasses slv2_plugin_class_get_children ( SLV2PluginClass plugin_class )

Get the subclasses of this plugin class.

Returned value must be freed by caller with slv2_plugin_classes_free.

SLV2Instance slv2_plugin_instantiate	(	SLV2Plugin	plugin,
		double	sample_rate,
		const LV2_Feature const	features
	)

Instantiate a plugin.

The returned value is a lightweight handle for an LV2 plugin instance, it does not refer to plugin, or any other SLV2 state. The caller must eventually free it with slv2_instance_free. features is a NULL-terminated array of features the host supports. NULL may be passed if the host supports no additional features.

Returns:: NULL if instantiation failed.

void slv2_instance_free ( SLV2Instance instance )

Free a plugin instance.

instance is invalid after this call.

static const char* slv2_instance_get_uri ( SLV2Instance instance ) [inline, static]

Get the URI of the plugin which instance is an instance of.

Returned string is shared and must not be modified or deleted.

static void slv2_instance_connect_port	(	SLV2Instance	instance,
		uint32_t	port_index,
		void *	data_location
	)		`[inline, static]`

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 void slv2_instance_activate ( SLV2Instance instance ) [inline, static]

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 void slv2_instance_run	(	SLV2Instance	instance,
		uint32_t	sample_count
	)		`[inline, static]`

Run instance for sample_count frames.

If the hint lv2:hardRTCapable is set for this plugin, this function is guaranteed not to block.

static void slv2_instance_deactivate ( SLV2Instance instance ) [inline, static]

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 const void* slv2_instance_get_extension_data	(	SLV2Instance	instance,
		const char *	uri
	)		`[inline, static]`

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 const LV2_Descriptor* slv2_instance_get_descriptor ( SLV2Instance instance ) [inline, static]

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 LV2_Handle slv2_instance_get_handle ( SLV2Instance instance ) [inline, static]

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.

SLV2UI slv2_uis_get_by_uri	(	SLV2UIs	uis,
		SLV2Value	uri
	)

Get a UI from uis by URI.

Return value is shared (stored in uis) and must not be freed or modified by the caller in any way.

Returns:: NULL if no UI with uri is found in list.

SLV2UIs slv2_plugin_get_uis ( SLV2Plugin plugin )

Get all UIs for plugin.

Returned value must be freed by caller using slv2_uis_free.

SLV2UI slv2_plugin_get_default_ui	(	SLV2Plugin	plugin,
		SLV2Value	widget_type_uri
	)

Get the default UI for 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 slv2_ui_supported to determine which UIs are usable and choose a UI to instantiate from among them.

Returns:: NULL if there is no suitable UI.

SLV2Value slv2_ui_get_uri ( SLV2UI ui )

Get the URI of a Plugin UI.

Parameters:

ui	The Plugin UI

Returns:: a shared value which must not be modified or freed.

bool slv2_ui_supported	(	SLV2UI	ui,
		SLV2Value	widget_type_uri
	)

Return true iff ui can be instantiated to a widget of the given type.

SLV2Values slv2_ui_get_classes ( SLV2UI ui )

Get the types (URIs of RDF classes) of a Plugin UI.

Parameters:

ui	The Plugin UI

Returns:: a shared value which must not be modified or freed.

bool slv2_ui_is_a	(	SLV2UI	ui,
		SLV2Value	class_uri
	)

Check whether a plugin UI is a given type.

Parameters:

ui	The Plugin UI
class_uri	The URI of the LV2 UI type to check this UI against

SLV2Value slv2_ui_get_bundle_uri ( SLV2UI ui )

Get the URI for a Plugin UI's bundle.

Parameters:

ui	The Plugin UI

Returns:: a shared value which must not be modified or freed.

SLV2Value slv2_ui_get_binary_uri ( SLV2UI ui )

Get the URI for a Plugin UI's shared library.

Parameters:

ui	The Plugin UI

Returns:: a shared value which must not be modified or freed.

SLV2UIInstance slv2_ui_instantiate	(	SLV2Plugin	plugin,
		SLV2UI	ui,
		LV2UI_Write_Function	write_function,
		LV2UI_Controller	controller,
		const LV2_Feature const	features
	)

DEPRECATED: Instantiate a plugin UI.

This function is deprecated, it does not support widget wrapping. Use slv2_ui_instance_new instead.

SLV2UIHost slv2_ui_host_new	(	LV2UI_Write_Function	write_function,
		SLV2PortIndexFunction	port_index_function,
		SLV2PortSubscribeFunction	port_subscribe_function,
		SLV2PortUnsubscribeFunction	port_unsubscribe_function
	)

Create a new UI host descriptor.

Parameters:

write_function	Function to send a value to a plugin port.
port_index_function	Function to get the index for a port by symbol.
port_subscribe_function	Function to subscribe to port updates.
port_unsubscribe_function	Function to unsubscribe from port updates.

void slv2_ui_host_free ( SLV2UIHost ui_host )

Free ui_host.

SLV2UIInstance slv2_ui_instance_new	(	SLV2Plugin	plugin,
		SLV2UI	ui,
		SLV2Value	widget_type_uri,
		SLV2UIHost	ui_host,
		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. The returned object does not refer to ui_host directly (though it of course refers to the fields of ui_host themselves), so ui_host may safely be freed any time after this call.

Parameters:

plugin	The plugin this UI is for.
ui	The plugin UI to instantiate.
widget_type_uri	The type of the desired widget.
ui_host	UI host descriptor (callbacks).
controller	Opaque host pointer passed to each function.
features	NULL-terminated array of features the host supports. NULL may be passed if the host supports no additional features.

Returns:: NULL if instantiation failed.

void slv2_ui_instance_free ( SLV2UIInstance instance )

Free a plugin UI instance.

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.

LV2UI_Widget slv2_ui_instance_get_widget ( SLV2UIInstance instance )

Get the widget for the UI instance.

void slv2_ui_instance_port_event	(	SLV2UIInstance	instance,
		uint32_t	port_index,
		uint32_t	buffer_size,
		uint32_t	format,
		const void *	buffer
	)

Notify a UI about a change in a plugin port.

const void* slv2_ui_instance_extension_data	(	SLV2UIInstance	instance,
		const char *	uri
	)

Return a data structure defined by some LV2 extension URI.

const LV2UI_Descriptor* slv2_ui_instance_get_descriptor ( SLV2UIInstance instance )

Get the LV2UI_Descriptor of the plugin UI instance.

Normally hosts should not need to access the LV2UI_Descriptor directly, use the slv2_ui_instance_* functions.

The returned descriptor is shared and must not be deleted.

LV2UI_Handle slv2_ui_instance_get_handle ( 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.

SLV2

Value

Collections

World

Plugin

Port

Scale Point

Plugin Class

Plugin Instance

Plugin UI

Plugin UI Instance

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation