src/calf/lv2_ui.h

   1 /************************************************************************
   2  *
   3  * In-process UI extension for LV2
   4  *
   5  * Copyright (C) 2006-2008 Lars Luthman <lars.luthman@gmail.com>
   6  *
   7  * Based on lv2.h, which was
   8  *
   9  * Copyright (C) 2000-2002 Richard W.E. Furse, Paul Barton-Davis,
  10  *                         Stefan Westerfeld
  11  * Copyright (C) 2006 Steve Harris, Dave Robillard.
  12  *
  13  * This header is free software; you can redistribute it and/or modify it
  14  * under the terms of the GNU Lesser General Public License as published
  15  * by the Free Software Foundation; either version 2.1 of the License,
  16  * or (at your option) any later version.
  17  *
  18  * This header is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21  * Lesser General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU Lesser General Public
  24  * License along with this library; if not, write to the Free Software
  25  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
  26  * USA.
  27  *
  28  ***********************************************************************/
  29
  30 /** @file
  31     This extension defines an interface that can be used in LV2 plugins and
  32     hosts to create UIs for plugins. The UIs are plugins that reside in
  33     shared object files in an LV2 bundle and are referenced in the RDF data
  34     using the triples (Turtle shown)
  35 <pre>
  36     @@prefix uiext: <http://lv2plug.in/ns/extensions/ui#> .
  37     <http://my.plugin>    uiext:ui     <http://my.pluginui> .
  38     <http://my.plugin>    a            uiext:GtkUI .
  39     <http://my.pluginui>  uiext:binary <myui.so> .
  40 </pre>
  41     where <http://my.plugin> is the URI of the plugin, <http://my.pluginui> is
  42     the URI of the plugin UI and <myui.so> is the relative URI to the shared
  43     object file. While it is possible to have the plugin UI and the plugin in
  44     the same shared object file it is probably a good idea to keep them
  45     separate so that hosts that don't want UIs don't have to load the UI code.
  46     A UI MUST specify its class in the RDF data. In this case the class is
  47     uiext:GtkUI, which is the only class defined by this extension.
  48
  49     (Note: the prefix above is used throughout this file for the same URI)
  50
  51     It's entirely possible to have multiple UIs for the same plugin, or to have
  52     the UI for a plugin in a different bundle from the actual plugin - this
  53     way people other than the plugin author can write plugin UIs independently
  54     without editing the original plugin bundle.
  55
  56     Note that the process that loads the shared object file containing the UI
  57     code and the process that loads the shared object file containing the
  58     actual plugin implementation does not have to be the same. There are many
  59     valid reasons for having the plugin and the UI in different processes, or
  60     even on different machines. This means that you can _not_ use singletons
  61     and global variables and expect them to refer to the same objects in the
  62     UI and the actual plugin. The function callback interface defined in this
  63     header is all you can expect to work.
  64
  65     Since the LV2 specification itself allows for extensions that may add
  66     new types of data and configuration parameters that plugin authors may
  67     want to control with a UI, this extension allows for meta-extensions that
  68     can extend the interface between the UI and the host. These extensions
  69     mirror the extensions used for plugins - there are required and optional
  70     "features" that you declare in the RDF data for the UI as
  71 <pre>
  72     <http://my.pluginui> uiext:requiredFeature <http://my.feature> .
  73     <http://my.pluginui> uiext:optionalFeature <http://my.feature> .
  74 </pre>
  75     These predicates have the same semantics as lv2:requiredFeature and
  76     lv2:optionalFeature - if a UI is declaring a feature as required, the
  77     host is NOT allowed to load it unless it supports that feature, and if it
  78     does support a feature (required or optional) it MUST pass that feature's
  79     URI and any additional data (specified by the meta-extension that defines
  80     the feature) to the UI's instantiate() function.
  81
  82     These features may be used to specify how to pass data between the UI
  83     and the plugin port buffers - see LV2UI_Write_Function for details.
  84
  85     There are two features defined in this extension that hosts may want to
  86     implement:
  87 <pre>
  88     uiext:makeResident
  89     uiext:makeSONameResident
  90 </pre>
  91     If the first feature, @c uiext:makeResident, is required by a UI the host
  92     MUST never unload the shared library containing the UI implementation
  93     during the lifetime of the host process (e.g. never calling dlclose() on
  94     Linux). This feature may be needed by e.g. a uiext:GtkUI that registers
  95     its own Glib types using g_type_register_static() - if it gets unloaded
  96     and then loaded again the type registration will break, since there is no
  97     way to unregister the types when the library is unloaded.
  98
  99     The second feature, @c uiext:makeSONameResident, is ELF specific
 100     and if it is required by an UI the UI should also list a number of
 101     SO names (shared object names) for libraries that the UI shared object
 102     depends on and that may not be unloaded during the lifetime of the host
 103     process, using the predicate @c uiext:residentSONames, like this:
 104 <pre>
 105     <http://my.pluginui> uiext:residentSONames "libgtkmm-2.4.so.1", "libfoo.so.0"
 106 </pre>
 107     The host MUST then make sure that the shared libraries with the given ELF
 108     SO names are not unloaded when the plugin UI is, but stay loaded during
 109     the entire lifetime of the host process. On Linux this can be accomplished
 110     by calling dlopen() on the shared library file with that SO name and never
 111     calling a matching dlclose(). However, if a plugin UI requires the
 112     @c uiext:makeSONameResident feature, it MUST always be safe for the host to
 113     just never unload the shared object containing the UI implementation, i.e.
 114     act as if the UI required the @c uiext:makeResident feature instead. Thus
 115     the host only needs to find the shared library files corresponding to the
 116     given SO names if it wants to save RAM by unloading the UI shared object
 117     file when it is no longer needed.
 118
 119     UIs written to this specification do not need to be threadsafe - the
 120     functions defined below may only be called in the same thread as the UI
 121     main loop is running in.
 122
 123     Note that this UI extension is NOT a lv2:Feature. There is no way for a
 124     plugin to know whether the host that loads it supports UIs or not, and
 125     the plugin must ALWAYS work without the UI (although it may be rather
 126     useless unless it has been configured using the UI in a previous session).
 127
 128     A UI does not have to be a graphical widget, it could just as well be a
 129     server listening for OSC input or an interface to some sort of hardware
 130     device, depending on the RDF class of the UI.
 131 */
 132
 133 #ifndef LV2_UI_H
 134 #define LV2_UI_H
 135
 136 #include <lv2.h>
 137
 138 #define LV2_UI_URI "http://lv2plug.in/ns/extensions/ui"
 139
 140
 141 #ifdef __cplusplus
 142 extern "C" {
 143 #endif
 144
 145
 146 /** A pointer to some widget or other type of UI handle.
 147     The actual type is defined by the type URI of the UI, e.g. if
 148     "<http://example.org/someui> a uiext:GtkUI", this is a pointer
 149     to a GtkWidget compatible with GTK+ 2.0 and the UI can expect the GTK+
 150     main loop to be running during the entire lifetime of all instances of that
 151     UI. All the functionality provided by this extension is toolkit
 152     independent, the host only needs to pass the necessary callbacks and
 153     display the widget, if possible. Plugins may have several UIs, in various
 154     toolkits, but uiext:GtkUI is the only type that is defined in this
 155     extension. */
 156 typedef void* LV2UI_Widget;
 157
 158
 159 /** A pointer to some host data required to instantiate a UI.
 160     Like the type of the widget, the actual type of this pointer is defined by
 161     the type URI of the UI.  Hosts can use this to pass toolkit specific data
 162     to a UI it needs to instantiate (type map, drawing context, etc). For the
 163     uiext:GtkUI type this should be NULL. */
 164 typedef void* LV2UI_Host_Data;
 165
 166
 167 /** This handle indicates a particular instance of a UI.
 168     It is valid to compare this to NULL (0 for C++) but otherwise the
 169     host MUST not attempt to interpret it. The UI plugin may use it to
 170     reference internal instance data. */
 171 typedef void* LV2UI_Handle;
 172
 173
 174 /** This handle indicates a particular plugin instance, provided by the host.
 175     It is valid to compare this to NULL (0 for C++) but otherwise the
 176     UI plugin MUST not attempt to interpret it. The host may use it to
 177     reference internal plugin instance data. */
 178 typedef void* LV2UI_Controller;
 179
 180
 181 /** This is the type of the host-provided function that the UI can use to
 182     send data to a plugin's input ports. The @c buffer parameter must point
 183     to a block of data, @c buffer_size bytes large. The contents of this buffer
 184     will depend on the class of the port it's being sent to, and the transfer
 185     mechanism specified for that port class.
 186
 187     Transfer mechanisms are Features and may be defined in meta-extensions.
 188     They specify how to translate the data buffers passed to this function
 189     to input data for the plugin ports. If a UI wishes to write data to an
 190     input port, it must list a transfer mechanism Feature for that port's
 191     class as an optional or required feature (depending on whether the UI
 192     will work without being able to write to that port or not). The only
 193     exception is ports of the class lv2:ControlPort, for which @c buffer_size
 194     should always be 4 and the buffer should always contain a single IEEE-754
 195     float.
 196
 197     The UI MUST NOT try to write to a port for which there is no specified
 198     transfer mechanism, or to an output port. The UI is responsible for
 199     allocating the buffer and deallocating it after the call. A function
 200     pointer of this type will be provided to the UI by the host in the
 201     instantiate() function.
 202
 203     An UI may list multiple transfer mechanisms for the same port type.
 204     To tell the host which mechanism is to be used, it passes an integer ID
 205     for the mechanism in the @c format parameter. This ID is retrieved from
 206     a URI-to-integer mapping function provided by the host, using the URI Map
 207     feature <http://lv2plug.in/ns/ext/uri-map> with the map URI
 208     "http://lv2plug.in/ns/extensions/ui". Thus a UI that requires transfer
 209     mechanism features MUST also require the URI Map feature. A @c format
 210     value of 0 is a special case that always means that the buffer should
 211     be interpreted as a single IEEE-754 float, and may only be written to
 212     a control port.
 213
 214     An UI MUST NOT pass a @c format parameter value (except 0) that has not
 215     been returned by the host-provided URI mapping function for a
 216     host-supported transfer mechanism feature URI.
 217 */
 218 typedef void (*LV2UI_Write_Function)(LV2UI_Controller controller,
 219                                      uint32_t         port_index,
 220                                      uint32_t         buffer_size,
 221                                      uint32_t         format,
 222                                      const void*      buffer);
 223
 224
 225 /** */
 226 typedef struct _LV2UI_Descriptor {
 227
 228   /** The URI for this UI (not for the plugin it controls). */
 229   const char* URI;
 230
 231   /** Create a new UI object and return a handle to it. This function works
 232       similarly to the instantiate() member in LV2_Descriptor.
 233
 234       @param descriptor The descriptor for the UI that you want to instantiate.
 235       @param plugin_uri The URI of the plugin that this UI will control.
 236       @param bundle_path The path to the bundle containing the RDF data file
 237                          that references this shared object file, including the
 238                          trailing '/'.
 239       @param write_function A function provided by the host that the UI can
 240                             use to send data to the plugin's input ports.
 241       @param controller A handle for the plugin instance that should be passed
 242                         as the first parameter of @c write_function.
 243       @param widget     A pointer to an LV2UI_Widget. The UI will write a
 244                         widget pointer to this location (what type of widget
 245                         depends on the RDF class of the UI) that will be the
 246                         main UI widget.
 247       @param features   An array of LV2_Feature pointers. The host must pass
 248                         all feature URIs that it and the plugin supports and any
 249                         additional data, just like in the LV2 plugin
 250                         instantiate() function.
 251   */
 252   LV2UI_Handle (*instantiate)(const struct _LV2UI_Descriptor* descriptor,
 253                               const char*                     plugin_uri,
 254                               const char*                     bundle_path,
 255                               LV2UI_Write_Function            write_function,
 256                               LV2UI_Controller                controller,
 257                               LV2UI_Widget*                   widget,
 258                               const LV2_Feature* const*       features);
 259
 260
 261   /** Destroy the UI object and the associated widget. The host must not try
 262       to access the widget after calling this function.
 263    */
 264   void (*cleanup)(LV2UI_Handle ui);
 265
 266   /** Tell the UI that something interesting has happened at a plugin port.
 267       What is interesting and how it is written to the buffer passed to this
 268       function is defined by  transfer mechanism extensions (see
 269       LV2UI_Write_Function). The only exception is ports of the class
 270       lv2:ControlPort, for which this function should be called
 271       when the port value changes (it does not have to be called for every
 272       single change if the host's UI thread has problems keeping up with
 273       the thread the plugin is running in), @c buffer_size should be 4 and the
 274       buffer should contain a single IEEE-754 float. In this case the @c format
 275       parameter should be 0.
 276
 277       By default, the host should only call this function for input ports of
 278       the lv2:ControlPort class. However, the default setting can be modified
 279       by using the following URIs in the UI's RDF data:
 280       <pre>
 281       uiext:portNotification
 282       uiext:noPortNotification
 283       uiext:plugin
 284       uiext:portIndex
 285       </pre>
 286       For example, if you want the UI with uri
 287       <code><http://my.pluginui></code> for the plugin with URI
 288       <code><http://my.plugin></code> to get notified when the value of the
 289       output control port with index 4 changes, you would use the following
 290       in the RDF for your UI:
 291       <pre>
 292       <http://my.pluginui> uiext:portNotification [ uiext:plugin <http://my.plugin> ;
 293                                                       uiext:portIndex 4 ] .
 294       </pre>
 295       and similarly with <code>uiext:noPortNotification</code> if you wanted
 296       to prevent notifications for a port for which it would be on by default
 297       otherwise. The UI is not allowed to request notifications for ports
 298       for which no transfer mechanism is specified, if it does it should be
 299       considered broken and the host should not load it.
 300
 301       The @c buffer is only valid during the time of this function call, so if
 302       the UI wants to keep it for later use it has to copy the contents to an
 303       internal buffer.
 304
 305       This member may be set to NULL if the UI is not interested in any
 306       port events.
 307
 308       The @c format parameter is used to specify the format of the buffer
 309       contents, with the same restrictions as in LV2_Write_Function.
 310   */
 311   void (*port_event)(LV2UI_Handle ui,
 312                      uint32_t     port_index,
 313                      uint32_t     buffer_size,
 314                      uint32_t     format,
 315                      const void*  buffer);
 316
 317   /** Returns a data structure associated with an extension URI, for example
 318       a struct containing additional function pointers. Avoid returning
 319       function pointers directly since standard C++ has no valid way of
 320       casting a void* to a function pointer. This member may be set to NULL
 321       if the UI is not interested in supporting any extensions. This is similar
 322       to the extension_data() member in LV2_Descriptor.
 323   */
 324   const void* (*extension_data)(const char*  uri);
 325
 326 } LV2UI_Descriptor;
 327
 328
 329
 330 /** A plugin UI programmer must include a function called "lv2ui_descriptor"
 331     with the following function prototype within the shared object
 332     file. This function will have C-style linkage (if you are using
 333     C++ this is taken care of by the 'extern "C"' clause at the top of
 334     the file). This function will be accessed by the UI host using the
 335     @c dlsym() function and called to get a LV2UI_UIDescriptor for the
 336     wanted plugin.
 337
 338     Just like lv2_descriptor(), this function takes an index parameter. The
 339     index should only be used for enumeration and not as any sort of ID number -
 340     the host should just iterate from 0 and upwards until the function returns
 341     NULL, or a descriptor with an URI matching the one the host is looking for
 342     is returned.
 343 */
 344 const LV2UI_Descriptor* lv2ui_descriptor(uint32_t index);
 345
 346
 347 /** This is the type of the lv2ui_descriptor() function. */
 348 typedef const LV2UI_Descriptor* (*LV2UI_DescriptorFunction)(uint32_t index);
 349
 350
 351
 352 #ifdef __cplusplus
 353 }
 354 #endif
 355
 356
 357 #endif