Suil module
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:/
Enums
- enum SuilArg { SUIL_ARG_NONE }
- Initialization argument.
Typedefs
- using SuilHost = struct SuilHostImpl
- UI host descriptor.
- using SuilInstance = struct SuilInstanceImpl
- An instance of an LV2 plugin UI.
- using SuilHandle = void*
- Opaque pointer to a UI handle.
- using SuilWidget = void*
- Opaque pointer to a UI widget.
- using SuilController = void*
- UI controller.
- using SuilPortWriteFunc = void(*)(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.
- using SuilPortIndexFunc = uint32_t(*)(SuilController controller, const char*port_symbol)
- Function to return the index for a port by symbol.
- using SuilPortSubscribeFunc = uint32_t(*)(SuilController controller, uint32_t port_index, uint32_t protocol, const LV2_Feature*const*features)
- Function to subscribe to notifications for a port.
- using SuilPortUnsubscribeFunc = uint32_t(*)(SuilController controller, uint32_t port_index, uint32_t protocol, const LV2_Feature*const*features)
- Function to unsubscribe from notifications for a port.
- using SuilTouchFunc = void(*)(SuilController controller, uint32_t port_index, bool grabbed)
- Function called when a control is grabbed or released.
Functions
- void suil_init(int* argc, char*** argv, SuilArg key, ...)
- Initialize suil.
- auto suil_host_new(SuilPortWriteFunc write_func, SuilPortIndexFunc index_func, SuilPortSubscribeFunc subscribe_func, SuilPortUnsubscribeFunc unsubscribe_func) -> SuilHost*
- 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. - auto suil_ui_supported(const char* host_type_uri, const char* ui_type_uri) -> unsigned
- Check if suil can wrap a UI type.
- auto 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) -> SuilInstance*
- Instantiate a UI for an LV2 plugin.
- void suil_instance_free(SuilInstance* instance)
- Free a plugin UI instance.
- auto suil_instance_get_handle(SuilInstance* instance) -> SuilHandle
- Get the handle for a UI instance.
- auto suil_instance_get_widget(SuilInstance* instance) -> SuilWidget
- 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.
- auto suil_instance_extension_data(SuilInstance* instance, const char* uri) -> const void*
- Return a data structure defined by some LV2 extension URI.
Enum documentation
enum SuilArg
#include <plugins/lv2/suil/suil.h>
Initialization argument.
Typedef documentation
typedef struct SuilHostImpl SuilHost
#include <plugins/lv2/suil/suil.h>
UI host descriptor.
This contains the various functions that a plugin UI may use to communicate with the plugin. It is passed to suil_
typedef struct SuilInstanceImpl SuilInstance
#include <plugins/lv2/suil/suil.h>
An instance of an LV2 plugin UI.
typedef void* SuilHandle
#include <plugins/lv2/suil/suil.h>
Opaque pointer to a UI handle.
typedef void* SuilWidget
#include <plugins/lv2/suil/suil.h>
Opaque pointer to a UI widget.
typedef void* SuilController
#include <plugins/lv2/suil/suil.h>
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.
typedef void(*SuilPortWriteFunc)(SuilController controller, uint32_t port_index, uint32_t buffer_size, uint32_t protocol, void const*buffer)
#include <plugins/lv2/suil/suil.h>
Function to write/send a value to a port.
typedef uint32_t(*SuilPortIndexFunc)(SuilController controller, const char*port_symbol)
#include <plugins/lv2/suil/suil.h>
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)
#include <plugins/lv2/suil/suil.h>
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)
#include <plugins/lv2/suil/suil.h>
Function to unsubscribe from notifications for a port.
typedef void(*SuilTouchFunc)(SuilController controller, uint32_t port_index, bool grabbed)
#include <plugins/lv2/suil/suil.h>
Function called when a control is grabbed or released.
Function documentation
void suil_init(int* argc,
char*** argv,
SuilArg key,
...)
#include <plugins/lv2/suil/suil.h>
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.
SuilHost* suil_host_new(SuilPortWriteFunc write_func,
SuilPortIndexFunc index_func,
SuilPortSubscribeFunc subscribe_func,
SuilPortUnsubscribeFunc unsubscribe_func)
#include <plugins/lv2/suil/suil.h>
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. |
void suil_host_set_touch_func(SuilHost* host,
SuilTouchFunc touch_func)
#include <plugins/lv2/suil/suil.h>
Set a touch function for a host descriptor.
Note this function will only be called if the UI supports it.
void suil_host_free(SuilHost* host)
#include <plugins/lv2/suil/suil.h>
Free host.
unsigned suil_ui_supported(const char* host_type_uri,
const char* ui_type_uri)
#include <plugins/lv2/suil/suil.h>
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_ |
| 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. |
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)
#include <plugins/lv2/suil/suil.h>
Instantiate a UI for an LV2 plugin.
| 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. |
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:/
void suil_instance_free(SuilInstance* instance)
#include <plugins/lv2/suil/suil.h>
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)
#include <plugins/lv2/suil/suil.h>
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)
#include <plugins/lv2/suil/suil.h>
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_
void suil_instance_port_event(SuilInstance* instance,
uint32_t port_index,
uint32_t buffer_size,
uint32_t format,
const void* buffer)
#include <plugins/lv2/suil/suil.h>
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.
const void* suil_instance_extension_data(SuilInstance* instance,
const char* uri)
#include <plugins/lv2/suil/suil.h>
Return a data structure defined by some LV2 extension URI.