This extension adds a way to write custom UIs for plugins. Each UI will consist of a shared object file containing the implementation and some data in the plugin's RDF files, much like the plugins themselves. The details are in this header file.
Additional extensions
The UI extension itself is just a generic framework for UIs - each UI needs to have a RDF type (specified by an URI) that defines how the host should handle it. Also, UIs, just like plugins, allow for required or optional Features to be listed in their RDF data that a host may choose to implement or not implement. Some Features are listed in the header linked above, but anyone can specify their own. Below are some additional extensions that are not officially part of the UI extension itself but may be useful to implement on top of it.
UI types
http://lv2plug.in/ns/extensions/ui#GtkUI
specifies an UI type where the LV2_Widget type is a pointer to a Gtk+ 2.0 compatible GtkWidget, and the host guarantees that the Gtk+ library has been initialised and the Glib main loop is running before an UI of this type is instantiated.
Features
http://lv2plug.in/ns/extensions/ui#ext_presets
specifies a Feature that adds functions to the UI and host that allow the UI to list any available presets that the host has for the plugin. Details are in this header file. Note that this extension does not say anything at all about how the host stores the presets or what the presets do, just how the host and UI can talk about them. This may be useful e.g. for a synth plugin UI that is running in a "stand alone" host that only displays a single window containing nothing but the UI widget - the UI can then present the available presets in a list box and let the user choose among them.
http://lv2plug.in/ns/extensions/ui#Events
specifies a Feature that defines how to send buffers of events between the GUI and the plugin (via the host). This is a Transfer Mechanism Feature (see lv2_ui.h). The rules are as follows:
- The data buffer pointer in the port_event() and write_port() functions is a pointer to a const LV2_Event_Buffer, as specified in the Event Port extension. The stamp_type should be ignored. The frames and subframes fields in any events in the buffer should be ignored by the UI (if it's reading the buffer) or set to 0 by the UI (if it's writing the buffer).
- Any host that supports this feature must pass an LV2_Feature to the UIs instantiation function with the URI http://lv2plug.in/ns/extensions/ui#Events and a NULL pointer as data.
- The URI map function provided by a host that supports this extension must either return identical numerical IDs to the UI and its controlled plugin for identical event type URIs (with the map URI http://lv2plug.in/ns/ext/event) or make sure that the event types get translated to the expected values when event buffers are passed between the UI and the plugin.
- The UI should ignore any type 0 events in buffers passed to it, and should never write any type 0 events into event buffers itself.
- The UIs event_port() callback should be called by the host whenever there are available events in a port that the UI has asked to be notified about, but there are no timing requirements - the UI should just try to get the events to the UI in reasonable time. The same goes in the other direction, with write_port().
- The event buffer is owned by the caller and is only guaranteed to be valid for the duration of the call to event_port() or write_port(). If the callee wants to keep it it has to make a copy.