Suil

Typedefs
typedef void *	SuilHandle
	Opaque pointer to a UI handle.
typedef void *	SuilWidget
	Opaque pointer to a UI widget.
typedef void *	SuilController
	UI controller.
typedef void(*	SuilPortWriteFunc) (SuilController controller, uint32_t port_index, uint32_t buffer_size, uint32_t protocol, void const *buffer)
	Function to write/send a value to a port.
typedef uint32_t(*	SuilPortIndexFunc) (SuilController controller, const char *port_symbol)
	Function to return the index for a port by symbol.
typedef uint32_t(*	SuilPortSubscribeFunc) (SuilController controller, uint32_t port_index, uint32_t protocol, const LV2_Feature *const *features)
	Function to subscribe to notifications for a port.
typedef uint32_t(*	SuilPortUnsubscribeFunc) (SuilController controller, uint32_t port_index, uint32_t protocol, const LV2_Feature *const *features)
	Function to unsubscribe from notifications for a port.
typedef void(*	SuilTouchFunc) (SuilController controller, uint32_t port_index, bool grabbed)
	Function called when a control is grabbed or released.

Enumerations
enum	SuilArg { SUIL_ARG_NONE }
	Initialization argument. More...

Functions
void	suil_init (int *argc, char ***argv, SuilArg key,...)
	Initialize suil.
SuilHost *	suil_host_new (SuilPortWriteFunc write_func, SuilPortIndexFunc index_func, SuilPortSubscribeFunc subscribe_func, SuilPortUnsubscribeFunc unsubscribe_func)
	Create a new UI host descriptor.
void	suil_host_set_touch_func (SuilHost *host, SuilTouchFunc touch_func)
	Set a touch function for a host descriptor.
void	suil_host_free (SuilHost *host)
	Free host.
unsigned	suil_ui_supported (const char *host_type_uri, const char *ui_type_uri)
	Check if suil can wrap a UI type.
SuilInstance *	suil_instance_new (SuilHost *host, SuilController controller, const char *container_type_uri, const char *plugin_uri, const char *ui_uri, const char *ui_type_uri, const char *ui_bundle_path, const char *ui_binary_path, const LV2_Feature *const *features)
	Instantiate a UI for an LV2 plugin.
void	suil_instance_free (SuilInstance *instance)
	Free a plugin UI instance.
SuilHandle	suil_instance_get_handle (SuilInstance *instance)
	Get the handle for a UI instance.
SuilWidget	suil_instance_get_widget (SuilInstance *instance)
	Get the widget for a UI instance.
void	suil_instance_port_event (SuilInstance *instance, uint32_t port_index, uint32_t buffer_size, uint32_t format, const void *buffer)
	Notify the UI about a change in a plugin port.
const void *	suil_instance_extension_data (SuilInstance *instance, const char *uri)
	Return a data structure defined by some LV2 extension URI.

Detailed Description

Suil is a library for loading and wrapping LV2 plugin UIs. With Suil, a host written in one supported toolkit can embed a plugin UI written in a different supported toolkit. Suil insulates hosts from toolkit libraries used by plugin UIs. For example, a Gtk host can embed a Qt UI without linking against Qt at compile time.

Visit http://drobilla.net/software/suil for more information.

Typedef Documentation

SuilController

typedef void* SuilController

UI controller.

This is an opaque pointer passed by the user which is passed to the various UI control functions (e.g. SuilPortWriteFunc). It is typically used to pass a pointer to some controller object the host uses to communicate with plugins.

Definition at line 100 of file suil.h.

SuilHandle

typedef void* SuilHandle

Opaque pointer to a UI handle.

Definition at line 87 of file suil.h.

SuilPortIndexFunc

typedef uint32_t(* SuilPortIndexFunc) (SuilController controller, const char *port_symbol)

Function to return the index for a port by symbol.

Definition at line 111 of file suil.h.

SuilPortSubscribeFunc

typedef uint32_t(* SuilPortSubscribeFunc) (SuilController controller, uint32_t port_index, uint32_t protocol, const LV2_Feature *const *features)

Function to subscribe to notifications for a port.

Definition at line 116 of file suil.h.

SuilPortUnsubscribeFunc

typedef uint32_t(* SuilPortUnsubscribeFunc) (SuilController controller, uint32_t port_index, uint32_t protocol, const LV2_Feature *const *features)

Function to unsubscribe from notifications for a port.

Definition at line 123 of file suil.h.

SuilPortWriteFunc

typedef void(* SuilPortWriteFunc) (SuilController controller, uint32_t port_index, uint32_t buffer_size, uint32_t protocol, void const *buffer)

Function to write/send a value to a port.

Definition at line 103 of file suil.h.

SuilTouchFunc

typedef void(* SuilTouchFunc) (SuilController controller, uint32_t port_index, bool grabbed)

Function called when a control is grabbed or released.

Definition at line 130 of file suil.h.

SuilWidget

typedef void* SuilWidget

Opaque pointer to a UI widget.

Definition at line 90 of file suil.h.

Enumeration Type Documentation

SuilArg

enum SuilArg

Initialization argument.

Definition at line 136 of file suil.h.

Function Documentation

suil_host_new()

SuilHost * suil_host_new	(	SuilPortWriteFunc	write_func,
		SuilPortIndexFunc	index_func,
		SuilPortSubscribeFunc	subscribe_func,
		SuilPortUnsubscribeFunc	unsubscribe_func )

Create a new UI host descriptor.

Parameters

write_func	Function to send a value to a plugin port.
index_func	Function to get the index for a port by symbol.
subscribe_func	Function to subscribe to port updates.
unsubscribe_func	Function to unsubscribe from port updates.

suil_host_set_touch_func()

void suil_host_set_touch_func	(	SuilHost *	host,
		SuilTouchFunc	touch_func )

Set a touch function for a host descriptor.

Note this function will only be called if the UI supports it.

suil_init()

void suil_init	(	int *	argc,
		char ***	argv,
		SuilArg	key,
			... )

Initialize suil.

This function should be called as early as possible, before any other GUI toolkit functions. The variable argument list is a sequence of SuilArg keys and corresponding value pairs for passing any necessary platform-specific information. It must be terminated with SUIL_ARG_NONE.

suil_instance_free()

void suil_instance_free

(

SuilInstance *

instance

)

Free a plugin UI instance.

The caller must ensure all references to the UI have been dropped before calling this function (e.g. it has been removed from its parent).

suil_instance_get_handle()

SuilHandle suil_instance_get_handle

(

SuilInstance *

instance

)

Get the handle for a UI instance.

Returns the handle to the UI instance. The returned handle has opaque type to insulate the Suil API from LV2 extensions, but in pactice it is currently of type LV2UI_Handle. This should not normally be needed.

The returned handle is shared and must not be deleted.

suil_instance_get_widget()

SuilWidget suil_instance_get_widget

(

SuilInstance *

instance

)

Get the widget for a UI instance.

Returns an opaque pointer to a widget, the type of which matches the container_type_uri parameter of suil_instance_new(). Note this may be a wrapper widget created by Suil, and not necessarily the widget directly implemented by the UI.

suil_instance_new()

SuilInstance * suil_instance_new	(	SuilHost *	host,
		SuilController	controller,
		const char *	container_type_uri,
		const char *	plugin_uri,
		const char *	ui_uri,
		const char *	ui_type_uri,
		const char *	ui_bundle_path,
		const char *	ui_binary_path,
		const LV2_Feature *const *	features )

Instantiate a UI for an LV2 plugin.

This function may load a suil module to adapt the UI to the desired toolkit. Suil is configured at compile time to load modules from the appropriate place, but this can be changed at run-time via the environment variable SUIL_MODULE_DIR. This makes it possible to bundle suil with an application.

Note that some situations (Gtk in Qt, Windows in Gtk) require a parent container to be passed as a feature with URI LV2_UI__parent (http://lv2plug.in/ns/extensions/ui#ui) in order to work correctly. The data must point to a single child container of the host widget set.

Parameters

host	Host descriptor.
controller	Opaque host controller pointer.
container_type_uri	URI of the desired host container widget type.
plugin_uri	URI of the plugin to instantiate this UI for.
ui_uri	URI of the specifically desired UI.
ui_type_uri	URI of the actual UI widget type.
ui_bundle_path	Path of the UI bundle.
ui_binary_path	Path of the UI binary.
features	NULL-terminated array of supported features, or NULL.

Returns

A new UI instance, or NULL if instantiation failed.

suil_instance_port_event()

void suil_instance_port_event	(	SuilInstance *	instance,
		uint32_t	port_index,
		uint32_t	buffer_size,
		uint32_t	format,
		const void *	buffer )

Notify the UI about a change in a plugin port.

Parameters

instance	UI instance.
port_index	Index of the port which has changed.
buffer_size	Size of buffer in bytes.
format	Format of buffer (mapped URI, or 0 for float).
buffer	Change data, e.g. the new port value.

This function can be used to notify the UI about any port change, but in the simplest case is used to set the value of lv2:ControlPort ports. For simplicity, this is a special case where format is 0, buffer_size is 4, and buffer should point to a single float.

The buffer must be valid only for the duration of this call, the UI must not keep a reference to it.

suil_ui_supported()

unsigned suil_ui_supported	(	const char *	host_type_uri,
		const char *	ui_type_uri )

Check if suil can wrap a UI type.

Parameters

host_type_uri	The URI of the desired widget type of the host, corresponding to the type_uri parameter of suil_instance_new().
ui_type_uri	The URI of the UI widget type.

Returns

0 if wrapping is unsupported, otherwise the quality of the wrapping where 1 is the highest quality (direct native embedding with no wrapping) and increasing values are of a progressively lower quality and/or stability.