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 another. 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.
Suil also handles the embedding of native platform UIs (which are recommended) in common toolkits, for example embedding an X11 UI in a Gtk host.
The complete API is declared in
This section contains the generated documentation for all symbols in the public API.
typedef void *SuilController¶
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.
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.
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 (*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 void (*SuilTouchFunc)(SuilController controller, uint32_t port_index, bool grabbed)¶
Function called when a control is grabbed or released.
SuilHost *suil_host_new(SuilPortWriteFunc write_func, SuilPortIndexFunc index_func, SuilPortSubscribeFunc subscribe_func, SuilPortUnsubscribeFunc unsubscribe_func)¶
Create a new UI host descriptor.
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.
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.
void suil_init(int *argc, char ***argv, SuilArg key, ...)¶
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.
const void *suil_instance_extension_data(SuilInstance *instance, const char *uri)¶
Return a data structure defined by some LV2 extension URI.
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).
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.
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
suil_instance_new(). Note this may be a wrapper widget created by Suil, and not necessarily the widget directly implemented by the UI.
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.
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.
A new UI instance, or NULL if instantiation failed.
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.
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
buffer_sizeis 4, and
buffershould point to a single float.
buffermust be valid only for the duration of this call, the UI must not keep a reference to it.
instance – UI instance.
port_index – Index of the port which has changed.
buffer_size – Size of
format – Format of
buffer(mapped URI, or 0 for float).
buffer – Change data, e.g. the new port value.
unsigned suil_ui_supported(const char *host_type_uri, const char *ui_type_uri)¶
Check if suil can wrap a UI type.
host_type_uri – The URI of the desired widget type of the host, corresponding to the
ui_type_uri – The URI of the UI widget type.
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.