gtk2_ardour/lv2_ui.h

   1 /* LV2 UI Extension
   2  * Copyright (C) 2006-2008 Lars Luthman <lars.luthman@gmail.com>
   3  * Copyright (C) 2009-2010 David Robillard <d@drobilla.net>
   4  *
   5  * Based on lv2.h, which was
   6  * Copyright (C) 2000-2002 Richard W.E. Furse, Paul Barton-Davis,
   7  *                         Stefan Westerfeld
   8  * Copyright (C) 2006 Steve Harris, David Robillard.
   9  *
  10  * This header is free software; you can redistribute it and/or modify it
  11  * under the terms of the GNU Lesser General Public License as published
  12  * by the Free Software Foundation; either version 2.1 of the License,
  13  * or (at your option) any later version.
  14  *
  15  * This header is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with this library; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
  23  * USA.
  24  *
  25  */
  26
  27 /** @file
  28  * C header for the LV2 UI extension <http://lv2plug.in/ns/extensions/ui>.
  29  */
  30
  31 #ifndef LV2_UI_H
  32 #define LV2_UI_H
  33
  34 #include "lv2.h"
  35
  36 #define LV2_UI_URI "http://lv2plug.in/ns/extensions/ui"
  37
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43
  44 /** A pointer to some widget or other type of UI handle.
  45     The actual type is defined by the type URI of the UI.
  46     All the functionality provided by this extension is toolkit
  47     independent, the host only needs to pass the necessary callbacks and
  48     display the widget, if possible. Plugins may have several UIs, in various
  49     toolkits. */
  50 typedef void* LV2UI_Widget;
  51
  52
  53 /** A pointer to a particular instance of a UI.
  54     It is valid to compare this to NULL (0 for C++) but otherwise the
  55     host MUST not attempt to interpret it. The UI plugin may use it to
  56     reference internal instance data. */
  57 typedef void* LV2UI_Handle;
  58
  59
  60 /** A pointer to a particular plugin controller, provided by the host.
  61     It is valid to compare this to NULL (0 for C++) but otherwise the
  62     UI plugin MUST not attempt to interpret it. The host may use it to
  63     reference internal instance data. */
  64 typedef void* LV2UI_Controller;
  65
  66
  67 /** The type of the host-provided function that the UI can use to
  68     send data to a plugin's input ports. The @c buffer parameter must point
  69     to a block of data, @c buffer_size bytes large. The contents of this buffer
  70     and what the host should do with it depends on the value of the @c format
  71     parameter.
  72
  73     The @c format parameter should either be 0 or a numeric ID for a "Transfer
  74     mechanism". Transfer mechanisms are Features and may be defined in
  75     meta-extensions. They specify how to translate the data buffers passed
  76     to this function to input data for the plugin ports. If a UI wishes to
  77     write data to an input port, it must list a transfer mechanism Feature
  78     for that port's class as an optional or required feature (depending on
  79     whether the UI will work without being able to write to that port or not).
  80     The only exception is when the UI wants to write single float values to
  81     input ports of the class lv2:ControlPort, in which case @c buffer_size
  82     should always be 4, the buffer should always contain a single IEEE-754
  83     float, and @c format should be 0.
  84
  85     The numeric IDs for the transfer mechanisms are provided by a
  86     URI-to-integer mapping function provided by the host, using the URI Map
  87     feature <http://lv2plug.in/ns/ext/uri-map> with the map URI
  88     "http://lv2plug.in/ns/extensions/ui". Thus a UI that requires transfer
  89     mechanism features also requires the URI Map feature, but this is
  90     implicit - the UI does not have to list the URI map feature as a required
  91     or optional feature in it's RDF data.
  92
  93     An UI MUST NOT pass a @c format parameter value (except 0) that has not
  94     been returned by the host-provided URI mapping function for a
  95     host-supported transfer mechanism feature URI.
  96
  97     The UI MUST NOT try to write to a port for which there is no specified
  98     transfer mechanism, or to an output port. The UI is responsible for
  99     allocating the buffer and deallocating it after the call.
 100 */
 101 typedef void (*LV2UI_Write_Function)(LV2UI_Controller controller,
 102                                      uint32_t         port_index,
 103                                      uint32_t         buffer_size,
 104                                      uint32_t         format,
 105                                      const void*      buffer);
 106
 107
 108 /** This struct contains the implementation of a UI. A pointer to an
 109     object of this type is returned by the lv2ui_descriptor() function.
 110 */
 111 typedef struct _LV2UI_Descriptor {
 112
 113   /** The URI for this UI (not for the plugin it controls). */
 114   const char* URI;
 115
 116   /** Create a new UI object and return a handle to it. This function works
 117       similarly to the instantiate() member in LV2_Descriptor.
 118
 119       @param descriptor The descriptor for the UI that you want to instantiate.
 120       @param plugin_uri The URI of the plugin that this UI will control.
 121       @param bundle_path The path to the bundle containing the RDF data file
 122                          that references this shared object file, including the
 123                          trailing '/'.
 124       @param write_function A function provided by the host that the UI can
 125                             use to send data to the plugin's input ports.
 126       @param controller A handle for the plugin instance that should be passed
 127                         as the first parameter of @c write_function.
 128       @param widget A pointer to an LV2UI_Widget. The UI will write a
 129                     widget pointer to this location (what type of widget
 130                     depends on the RDF class of the UI) that will be the
 131                     main UI widget.
 132       @param features An array of LV2_Feature pointers. The host must pass
 133                       all feature URIs that it and the UI supports and any
 134                       additional data, just like in the LV2 plugin
 135                       instantiate() function. Note that UI features and plugin
 136                       features are NOT necessarily the same, they just share
 137                       the same data structure - this will probably not be the
 138                       same array as the one the plugin host passes to a
 139                       plugin.
 140   */
 141   LV2UI_Handle (*instantiate)(const struct _LV2UI_Descriptor* descriptor,
 142                               const char*                     plugin_uri,
 143                               const char*                     bundle_path,
 144                               LV2UI_Write_Function            write_function,
 145                               LV2UI_Controller                controller,
 146                               LV2UI_Widget*                   widget,
 147                               const LV2_Feature* const*       features);
 148
 149
 150   /** Destroy the UI object and the associated widget. The host must not try
 151       to access the widget after calling this function.
 152    */
 153   void (*cleanup)(LV2UI_Handle ui);
 154
 155   /** Tell the UI that something interesting has happened at a plugin port.
 156       What is interesting and how it is written to the buffer passed to this
 157       function is defined by the @c format parameter, which has the same
 158       meaning as in LV2UI_Write_Function. The only exception is ports of the
 159       class lv2:ControlPort, for which this function should be called
 160       when the port value changes (it does not have to be called for every
 161       single change if the host's UI thread has problems keeping up with the
 162       thread the plugin is running in), @c buffer_size should be 4, the buffer
 163       should contain a single IEEE-754 float, and @c format should be 0.
 164
 165       By default, the host should only call this function for input ports of
 166       the lv2:ControlPort class. However, the default setting can be modified
 167       by using the following URIs in the UI's RDF data:
 168       <pre>
 169       uiext:portNotification
 170       uiext:noPortNotification
 171       uiext:plugin
 172       uiext:portIndex
 173       </pre>
 174       For example, if you want the UI with uri
 175       <code><http://my.pluginui></code> for the plugin with URI
 176       <code><http://my.plugin></code> to get notified when the value of the
 177       output control port with index 4 changes, you would use the following
 178       in the RDF for your UI:
 179       <pre>
 180       <http://my.pluginui> uiext:portNotification [ uiext:plugin <http://my.plugin> ;
 181                                                     uiext:portIndex 4 ] .
 182       </pre>
 183       and similarly with <code>uiext:noPortNotification</code> if you wanted
 184       to prevent notifications for a port for which it would be on by default
 185       otherwise. The UI is not allowed to request notifications for ports of
 186       types for which no transfer mechanism is specified, if it does it should
 187       be considered broken and the host should not load it.
 188
 189       The @c buffer is only valid during the time of this function call, so if
 190       the UI wants to keep it for later use it has to copy the contents to an
 191       internal buffer.
 192
 193       This member may be set to NULL if the UI is not interested in any
 194       port events.
 195   */
 196   void (*port_event)(LV2UI_Handle ui,
 197                      uint32_t     port_index,
 198                      uint32_t     buffer_size,
 199                      uint32_t     format,
 200                      const void*  buffer);
 201
 202   /** Returns a data structure associated with an extension URI, for example
 203       a struct containing additional function pointers. Avoid returning
 204       function pointers directly since standard C/C++ has no valid way of
 205       casting a void* to a function pointer. This member may be set to NULL
 206       if the UI is not interested in supporting any extensions. This is similar
 207       to the extension_data() member in LV2_Descriptor.
 208   */
 209   const void* (*extension_data)(const char* uri);
 210
 211 } LV2UI_Descriptor;
 212
 213
 214
 215 /** A plugin UI programmer must include a function called "lv2ui_descriptor"
 216     with the following function prototype within the shared object
 217     file. This function will have C-style linkage (if you are using
 218     C++ this is taken care of by the 'extern "C"' clause at the top of
 219     the file). This function will be accessed by the UI host using the
 220     @c dlsym() function and called to get a LV2UI_UIDescriptor for the
 221     wanted plugin.
 222
 223     Just like lv2_descriptor(), this function takes an index parameter. The
 224     index should only be used for enumeration and not as any sort of ID number -
 225     the host should just iterate from 0 and upwards until the function returns
 226     NULL or a descriptor with an URI matching the one the host is looking for.
 227 */
 228 const LV2UI_Descriptor* lv2ui_descriptor(uint32_t index);
 229
 230
 231 /** This is the type of the lv2ui_descriptor() function. */
 232 typedef const LV2UI_Descriptor* (*LV2UI_DescriptorFunction)(uint32_t index);
 233
 234
 235
 236 #ifdef __cplusplus
 237 }
 238 #endif
 239
 240
 241 #endif