Suil
0.10.0
|
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.
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 | |
void | suil_init (int *argc, char ***argv, SuilArg key,...) |
SuilHost * | suil_host_new (SuilPortWriteFunc write_func, SuilPortIndexFunc index_func, SuilPortSubscribeFunc subscribe_func, SuilPortUnsubscribeFunc unsubscribe_func) |
void | suil_host_set_touch_func (SuilHost *host, SuilTouchFunc touch_func) |
void | suil_host_free (SuilHost *host) |
unsigned | suil_ui_supported (const char *host_type_uri, const char *ui_type_uri) |
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) |
void | suil_instance_free (SuilInstance *instance) |
SuilHandle | suil_instance_get_handle (SuilInstance *instance) |
SuilWidget | suil_instance_get_widget (SuilInstance *instance) |
void | suil_instance_port_event (SuilInstance *instance, uint32_t port_index, uint32_t buffer_size, uint32_t format, const void *buffer) |
const void * | suil_instance_extension_data (SuilInstance *instance, const char *uri) |
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 struct SuilInstanceImpl SuilInstance |
An instance of an LV2 plugin UI.
typedef void* SuilHandle |
Opaque pointer to a UI handle.
typedef void* SuilWidget |
Opaque pointer to a UI widget.
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.
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.
enum SuilArg |
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.
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_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.
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. |
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. |
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 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.
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.
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 | ||
) |
Return a data structure defined by some LV2 extension URI.