Suil  0.10.8
Typedefs | Enumerations | Functions
Suil

Detailed Description

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.

Typedefs

typedef struct SuilHostImpl SuilHost
 
typedef struct SuilInstanceImpl SuilInstance
 
typedef void * SuilHandle
 
typedef void * SuilWidget
 
typedef void * SuilController
 
typedef void(* SuilPortWriteFunc) (SuilController controller, uint32_t port_index, uint32_t buffer_size, uint32_t protocol, void const *buffer)
 
typedef uint32_t(* SuilPortIndexFunc) (SuilController controller, const char *port_symbol)
 
typedef uint32_t(* SuilPortSubscribeFunc) (SuilController controller, uint32_t port_index, uint32_t protocol, const LV2_Feature *const *features)
 
typedef uint32_t(* SuilPortUnsubscribeFunc) (SuilController controller, uint32_t port_index, uint32_t protocol, const LV2_Feature *const *features)
 
typedef void(* SuilTouchFunc) (SuilController controller, uint32_t port_index, bool grabbed)
 

Enumerations

enum  SuilArg { SUIL_ARG_NONE }
 

Functions

SUIL_API void suil_init (int *argc, char ***argv, SuilArg key,...)
 
SUIL_API SuilHostsuil_host_new (SuilPortWriteFunc write_func, SuilPortIndexFunc index_func, SuilPortSubscribeFunc subscribe_func, SuilPortUnsubscribeFunc unsubscribe_func)
 
SUIL_API void suil_host_set_touch_func (SuilHost *host, SuilTouchFunc touch_func)
 
SUIL_API void suil_host_free (SuilHost *host)
 
SUIL_API unsigned suil_ui_supported (const char *host_type_uri, const char *ui_type_uri)
 
SUIL_API SuilInstancesuil_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)
 
SUIL_API void suil_instance_free (SuilInstance *instance)
 
SUIL_API SuilHandle suil_instance_get_handle (SuilInstance *instance)
 
SUIL_API SuilWidget suil_instance_get_widget (SuilInstance *instance)
 
SUIL_API void suil_instance_port_event (SuilInstance *instance, uint32_t port_index, uint32_t buffer_size, uint32_t format, const void *buffer)
 
SUIL_API const void * suil_instance_extension_data (SuilInstance *instance, const char *uri)
 

Typedef Documentation

◆ SuilHost

typedef struct SuilHostImpl SuilHost

UI host descriptor.

This contains the various functions that a plugin UI may use to communicate with the plugin. It is passed to suil_instance_new() to provide these functions to the UI.

◆ SuilInstance

typedef struct SuilInstanceImpl SuilInstance

An instance of an LV2 plugin UI.

◆ SuilHandle

typedef void* SuilHandle

Opaque pointer to a UI handle.

◆ SuilWidget

typedef void* SuilWidget

Opaque pointer to a UI widget.

◆ 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.

◆ 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.

◆ SuilPortIndexFunc

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

Function to return the index for a port by symbol.

◆ 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.

◆ 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.

◆ SuilTouchFunc

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

Function called when a control is grabbed or released.

Enumeration Type Documentation

◆ SuilArg

enum SuilArg

Initialization argument.

Enumerator
SUIL_ARG_NONE 

Function Documentation

◆ suil_init()

SUIL_API 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_host_new()

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

Create a new UI host descriptor.

Parameters
write_funcFunction to send a value to a plugin port.
index_funcFunction to get the index for a port by symbol.
subscribe_funcFunction to subscribe to port updates.
unsubscribe_funcFunction to unsubscribe from port updates.

◆ suil_host_set_touch_func()

SUIL_API 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_host_free()

SUIL_API void suil_host_free ( SuilHost host)

Free host.

◆ suil_ui_supported()

SUIL_API 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_uriThe URI of the desired widget type of the host, corresponding to the type_uri parameter of suil_instance_new().
ui_type_uriThe 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.

◆ suil_instance_new()

SUIL_API 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 funcion 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
hostHost descriptor.
controllerOpaque host controller pointer.
container_type_uriURI of the desired host container widget type.
plugin_uriURI of the plugin to instantiate this UI for.
ui_uriURI of the specifically desired UI.
ui_type_uriURI of the actual UI widget type.
ui_bundle_pathPath of the UI bundle.
ui_binary_pathPath of the UI binary.
featuresNULL-terminated array of supported features, or NULL.
Returns
A new UI instance, or NULL if instantiation failed.

◆ suil_instance_free()

SUIL_API 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()

SUIL_API 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()

SUIL_API 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_port_event()

SUIL_API 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
instanceUI instance.
port_indexIndex of the port which has changed.
buffer_sizeSize of buffer in bytes.
formatFormat of buffer (mapped URI, or 0 for float).
bufferChange 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_instance_extension_data()

SUIL_API const void* suil_instance_extension_data ( SuilInstance instance,
const char *  uri 
)

Return a data structure defined by some LV2 extension URI.

suil_instance_new
SUIL_API 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.
SuilWidget
void * SuilWidget
Opaque pointer to a UI widget.
Definition: suil.h:81
SuilPortSubscribeFunc
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: suil.h:107
SuilInstance
struct SuilInstanceImpl SuilInstance
An instance of an LV2 plugin UI.
Definition: suil.h:75
suil_instance_extension_data
SUIL_API const void * suil_instance_extension_data(SuilInstance *instance, const char *uri)
Return a data structure defined by some LV2 extension URI.
suil_instance_free
SUIL_API void suil_instance_free(SuilInstance *instance)
Free a plugin UI instance.
SuilController
void * SuilController
UI controller.
Definition: suil.h:91
suil_host_new
SUIL_API SuilHost * suil_host_new(SuilPortWriteFunc write_func, SuilPortIndexFunc index_func, SuilPortSubscribeFunc subscribe_func, SuilPortUnsubscribeFunc unsubscribe_func)
Create a new UI host descriptor.
suil_instance_port_event
SUIL_API 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.
suil_ui_supported
SUIL_API unsigned suil_ui_supported(const char *host_type_uri, const char *ui_type_uri)
Check if suil can wrap a UI type.
SuilPortUnsubscribeFunc
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: suil.h:114
suil_instance_get_widget
SUIL_API SuilWidget suil_instance_get_widget(SuilInstance *instance)
Get the widget for a UI instance.
suil_host_free
SUIL_API void suil_host_free(SuilHost *host)
Free host.
SUIL_ARG_NONE
@ SUIL_ARG_NONE
Definition: suil.h:128
SuilArg
SuilArg
Initialization argument.
Definition: suil.h:127
SuilHost
struct SuilHostImpl SuilHost
UI host descriptor.
Definition: suil.h:72
suil_init
SUIL_API void suil_init(int *argc, char ***argv, SuilArg key,...)
Initialize suil.
SuilHandle
void * SuilHandle
Opaque pointer to a UI handle.
Definition: suil.h:78
SuilPortWriteFunc
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: suil.h:94
suil_instance_get_handle
SUIL_API SuilHandle suil_instance_get_handle(SuilInstance *instance)
Get the handle for a UI instance.
suil_host_set_touch_func
SUIL_API void suil_host_set_touch_func(SuilHost *host, SuilTouchFunc touch_func)
Set a touch function for a host descriptor.
SuilTouchFunc
void(* SuilTouchFunc)(SuilController controller, uint32_t port_index, bool grabbed)
Function called when a control is grabbed or released.
Definition: suil.h:121
SuilPortIndexFunc
uint32_t(* SuilPortIndexFunc)(SuilController controller, const char *port_symbol)
Function to return the index for a port by symbol.
Definition: suil.h:102