LV2 UI

This extension defines an interface that can be used in LV2 plugins and hosts to create UIs for plugins. The UIs are similar to plugins and reside in shared object files in an LV2 bundle. UIs are associated with a plugin in RDF using the triples

    
@prefix ui: <http://lv2plug.in/ns/extensions/ui#> .

<http://my.plugin>   ui:ui     <http://my.pluginui> .
<http://my.pluginui> a         ui:GtkUI ;
                     ui:binary <myui.so> .

where <http://my.plugin> is the URI of the plugin, <http://my.pluginui> is the URI of the plugin UI and <myui.so> is the relative URI to the shared object file.

While it is possible to have the plugin UI and the plugin in the same shared object file it is probably a good idea to keep them separate so that hosts that don't want UIs don't have to load the UI code. A UI MUST specify its class in the RDF data, in this case ui:GtkUI. The class defines what type the UI is, e.g. what graphics toolkit it uses. Any type of UI class can be defined separately from this extension.

(Note: the prefix above is used throughout this file for the same URI)

It is possible to have multiple UIs for the same plugin, or to have the UI for a plugin in a different bundle from the actual plugin - this way people other than the plugin author can write plugin UIs independently without editing the original plugin bundle.

Note that the process that loads the shared object file containing the UI code and the process that loads the shared object file containing the actual plugin implementation does not have to be the same. There are many valid reasons for having the plugin and the UI in different processes, or even on different machines. This means that you can not use singletons and global variables and expect them to refer to the same objects in the UI and the actual plugin. The function callback interface defined in this header is all you can expect to work.

Since the LV2 specification itself allows for extensions that may add new functionality that could be useful to control with a UI, this extension allows for meta-extensions that can extend the interface between the UI and the host. These extensions mirror the extensions used for plugins - there are required and optional "features" that you declare in the RDF data for the UI as

    
<http://my.pluginui> ui:requiredFeature <http://my.feature> .
<http://my.pluginui> ui:optionalFeature <http://my.feature> .

These predicates have the same semantics as lv2:requiredFeature and lv2:optionalFeature - if a UI is declaring a feature as required, the host is NOT allowed to load it unless it supports that feature, and if it does support a feature (required or optional) it MUST pass that feature's URI and any additional data (specified by the meta-extension that defines the feature) in a LV2_Feature struct (as defined in lv2.h) to the UI's instantiate() function.

These features may be used to specify how to pass data between the UI and the plugin port buffers - see LV2UI_Write_Function for details.

UIs written to this specification do not need to be threadsafe - the functions defined below may only be called in the same thread as the UI main loop is running in.

Note that this UI extension is NOT a lv2:Feature. There is no way for a plugin to know whether the host that loads it supports UIs or not, and the plugin must ALWAYS work without the UI (although it may be rather useless unless it has been configured using the UI in a previous session).

A UI does not have to be a graphical widget, it could just as well be a server listening for OSC input or an interface to some sort of hardware device, depending on the RDF class of the UI.

<http://my.pluginui> ui:residentSONames "libgtkmm-2.4.so.1", "libfoo.so.0"

Automatically generated from ui.ttl by lv2specgen at 2009-11-12 01:12 UTC

This document is content-negotiated. If you request it with Accept: application/x-turtle you will get the description in Turtle. Also supported: application/rdf+xml, application/json, text/plain