Using Suil

The complete API is declared in suil.h:

#include <suil/suil.h>

Library Setup

In order to work properly on certain platforms, suil must be set up by the application before any GUI toolkits are loaded. This is done with suil_init(), which takes command line arguments and an optional list of arguments, terminated by SUIL_ARG_NONE:

int main(int argc, char** argv)
{
  suil_init(&argc, &argv, SUIL_ARG_NONE);
  return 0;
}

There are currently no defined Suil arguments, the facility exists for future extensibility.

Host Setup

After the library is prepared, a SuilHost must be created. This represents the plugin UI host, in particular the callbacks that will fire when there is UI activity. There are five types of host callback:

• SuilPortWriteFunc

• SuilPortIndexFunc

• SuilPortSubscribeFunc

• SuilPortUnsubscribeFunc

• SuilTouchFunc

These callbacks all take a SuilController, which is an opaque pointer that can be used to describe the context (including which UI is responsible for the call), as well as extra arguments specific to the callback.

Assuming these are implemented in the host as my_write_func, my_port_index_func, my_port_subscribe_func, my_port_unsubscribe_func, and my_touch_func, respectively, the host can be allocated with suil_host_new():

SuilHost* host = suil_host_new(my_write_func,
                               my_index_func,
                               my_subscribe_func,
                               my_unsubscribe_func);

Touch functionality was added to the API later, so the touch function is set with the separate suil_host_set_touch_func():

suil_host_set_touch_func(host, my_touch_func);

Finding Supported UIs

Suil does not access data directly itself, so UI discovery is the responsibility of the application. Most hosts will use lilv_plugin_get_uis() to discover the available UIs for a particular plugin.

Suil provides suil_ui_supported(), which can be used to determine if a particular UI can be embedded in the host. It requires two URIs, one that describes the host UI type, and one that describes the plugin UI type. They are typically URIs defined in the LV2 UI extension, such as https://lv2plug.in/ns/extensions/ui#X11UI, which are defined for convenience with names like LV2_UI__X11UI.

If a specific UI type is already known, this can be used directly, for example an X11 host might do something like this:

if (suil_ui_supported(LV2_UI__X11UI, plugin_ui_type) > 0) {
  // Use this UI...
}

More commonly, this function is used as a utility along with lilv_ui_is_supported():

LilvUI*   ui        = this_plugin_ui();
LilvNode* host_type = lilv_new_uri(LV2_UI__X11UI);
LilvNode* ui_type   = NULL;

if (lilv_ui_is_supported(ui, suil_ui_supported, host_type, &ui_type)) {
  // Use this UI, which has type ui_type...
}

Loading a UI Instance

An instance of a plugin UI is represented by a SuilInstance, which can be created with suil_instance_new(). For example, given a LilvPlugin plugin, and a LilvUI ui:

SuilController*     controller = my_controller_for(ui);
const LV2_Feature** features   = my_features_for(ui);

const char* bundle_uri  = lilv_node_as_uri(lilv_ui_get_bundle_uri(ui));
const char* binary_uri  = lilv_node_as_uri(lilv_ui_get_binary_uri(ui));
char*       bundle_path = serd_parse_file_uri(bundle_uri, NULL);
char*       binary_path = serd_parse_file_uri(binary_uri, NULL);

SuilInstance* instance = suil_instance_new(
  host,
  controller,
  LV2_UI__X11UI,
  lilv_node_as_uri(lilv_plugin_get_uri(plugin)),
  lilv_node_as_uri(lilv_ui_get_uri(ui)),
  lilv_node_as_uri(ui_type),
  bundle_path,
  binary_path,
  ui_features);

Retrieving the Widget

With the UI instantiated, the actual widget can be retrieved with suil_instance_get_widget(). This returns a SuilWidget handle which has the container type passed to suil_instance_new(). In this example, the host is a LV2_UI__X11UI, so the returned widget is a Window:

Window window = (Window)suil_instance_get_widget(instance);

The host may be responsible for displaying or embedding the widget, depending on the windowing system or toolkit used.

Updating the UI

Updates can be sent to a UI instance with suil_instance_port_event(). This takes a port index, a value size and format, and a pointer to a value. For example, to update a control port, the special format 0 can be used:

const float value = 42.0f;

suil_instance_port_event(instance, 2, sizeof(float), 0, &value);

Cleanup

When the host is finished with the UI, and has removed any references to it in the windowing system or toolkit, it must destroy the UI with suil_instance_free():

suil_instance_free(instance);

When all UIs have been destroyed and the host is ready to shut down, it must free its description with suil_host_free():

suil_host_free(host);

Note that the host must outlive any UI instances that were created for it.