1 /* 2 LV2 UI Extension 3 Copyright 2009-2016 David Robillard <d@drobilla.net> 4 Copyright 2006-2011 Lars Luthman <lars.luthman@gmail.com> 5 Copyright 2018 Ethan Reker <http://cutthroughrecordings.com> 6 7 Permission to use, copy, modify, and/or distribute this software for any 8 purpose with or without fee is hereby granted, provided that the above 9 copyright notice and this permission notice appear in all copies. 10 11 THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18 */ 19 module dplug.lv2.ui; 20 21 version(LV2): 22 23 /** 24 @defgroup ui User Interfaces 25 26 User interfaces of any type for plugins, 27 <http://lv2plug.in/ns/extensions/ui> for details. 28 29 @{ 30 */ 31 32 import core.stdc.stdint; 33 34 import dplug.lv2.lv2; 35 36 enum LV2_UI_URI = "http://lv2plug.in/ns/extensions/ui"; ///< http://lv2plug.in/ns/extensions/ui 37 enum LV2_UI_PREFIX = LV2_UI_URI ~ "#"; ///< http://lv2plug.in/ns/extensions/ui# 38 enum LV2_UI__CocoaUI = LV2_UI_PREFIX ~ "CocoaUI"; ///< http://lv2plug.in/ns/extensions/ui#CocoaUI 39 enum LV2_UI__Gtk3UI = LV2_UI_PREFIX ~ "Gtk3UI"; ///< http://lv2plug.in/ns/extensions/ui#Gtk3UI 40 enum LV2_UI__GtkUI = LV2_UI_PREFIX ~ "GtkUI"; ///< http://lv2plug.in/ns/extensions/ui#GtkUI 41 enum LV2_UI__PortNotification = LV2_UI_PREFIX ~ "PortNotification"; ///< http://lv2plug.in/ns/extensions/ui#PortNotification 42 enum LV2_UI__PortProtocol = LV2_UI_PREFIX ~ "PortProtocol"; ///< http://lv2plug.in/ns/extensions/ui#PortProtocol 43 enum LV2_UI__Qt4UI = LV2_UI_PREFIX ~ "Qt4UI"; ///< http://lv2plug.in/ns/extensions/ui#Qt4UI 44 enum LV2_UI__Qt5UI = LV2_UI_PREFIX ~ "Qt5UI"; ///< http://lv2plug.in/ns/extensions/ui#Qt5UI 45 enum LV2_UI__UI = LV2_UI_PREFIX ~ "UI"; ///< http://lv2plug.in/ns/extensions/ui#UI 46 enum LV2_UI__WindowsUI = LV2_UI_PREFIX ~ "WindowsUI"; ///< http://lv2plug.in/ns/extensions/ui#WindowsUI 47 enum LV2_UI__X11UI = LV2_UI_PREFIX ~ "X11UI"; ///< http://lv2plug.in/ns/extensions/ui#X11UI 48 enum LV2_UI__binary = LV2_UI_PREFIX ~ "binary"; ///< http://lv2plug.in/ns/extensions/ui#binary 49 enum LV2_UI__fixedSize = LV2_UI_PREFIX ~ "fixedSize"; ///< http://lv2plug.in/ns/extensions/ui#fixedSize 50 enum LV2_UI__idleInterface = LV2_UI_PREFIX ~ "idleInterface"; ///< http://lv2plug.in/ns/extensions/ui#idleInterface 51 enum LV2_UI__noUserResize = LV2_UI_PREFIX ~ "noUserResize"; ///< http://lv2plug.in/ns/extensions/ui#noUserResize 52 enum LV2_UI__notifyType = LV2_UI_PREFIX ~ "notifyType"; ///< http://lv2plug.in/ns/extensions/ui#notifyType 53 enum LV2_UI__parent = LV2_UI_PREFIX ~ "parent"; ///< http://lv2plug.in/ns/extensions/ui#parent 54 enum LV2_UI__plugin = LV2_UI_PREFIX ~ "plugin"; ///< http://lv2plug.in/ns/extensions/ui#plugin 55 enum LV2_UI__portIndex = LV2_UI_PREFIX ~ "portIndex"; ///< http://lv2plug.in/ns/extensions/ui#portIndex 56 enum LV2_UI__portMap = LV2_UI_PREFIX ~ "portMap"; ///< http://lv2plug.in/ns/extensions/ui#portMap 57 enum LV2_UI__portNotification = LV2_UI_PREFIX ~ "portNotification"; ///< http://lv2plug.in/ns/extensions/ui#portNotification 58 enum LV2_UI__portSubscribe = LV2_UI_PREFIX ~ "portSubscribe"; ///< http://lv2plug.in/ns/extensions/ui#portSubscribe 59 enum LV2_UI__protocol = LV2_UI_PREFIX ~ "protocol"; ///< http://lv2plug.in/ns/extensions/ui#protocol 60 enum LV2_UI__floatProtocol = LV2_UI_PREFIX ~ "floatProtocol"; ///< http://lv2plug.in/ns/extensions/ui#floatProtocol 61 enum LV2_UI__peakProtocol = LV2_UI_PREFIX ~ "peakProtocol"; ///< http://lv2plug.in/ns/extensions/ui#peakProtocol 62 enum LV2_UI__resize = LV2_UI_PREFIX ~ "resize"; ///< http://lv2plug.in/ns/extensions/ui#resize 63 enum LV2_UI__showInterface = LV2_UI_PREFIX ~ "showInterface"; ///< http://lv2plug.in/ns/extensions/ui#showInterface 64 enum LV2_UI__touch = LV2_UI_PREFIX ~ "touch"; ///< http://lv2plug.in/ns/extensions/ui#touch 65 enum LV2_UI__ui = LV2_UI_PREFIX ~ "ui"; ///< http://lv2plug.in/ns/extensions/ui#ui 66 enum LV2_UI__updateRate = LV2_UI_PREFIX ~ "updateRate"; ///< http://lv2plug.in/ns/extensions/ui#updateRate 67 enum LV2_UI__windowTitle = LV2_UI_PREFIX ~ "windowTitle"; ///< http://lv2plug.in/ns/extensions/ui#windowTitle 68 69 /** 70 The index returned by LV2UI_Port_Map::port_index() for unknown ports. 71 */ 72 enum LV2UI_INVALID_PORT_INDEX = cast(uint32_t)(-1); 73 74 extern(C): 75 nothrow: 76 @nogc: 77 78 /** 79 A pointer to some widget or other type of UI handle. 80 81 The actual type is defined by the type of the UI. 82 */ 83 alias LV2UI_Widget = void*; 84 85 /** 86 A pointer to UI instance internals. 87 88 The host may compare this to NULL, but otherwise MUST NOT interpret it. 89 */ 90 alias LV2UI_Handle = void*; 91 92 /** 93 A pointer to a controller provided by the host. 94 95 The UI may compare this to NULL, but otherwise MUST NOT interpret it. 96 */ 97 alias LV2UI_Controller = void*; 98 99 /** 100 A pointer to opaque data for a feature. 101 */ 102 alias LV2UI_Feature_Handle = void*; 103 104 /** 105 A host-provided function that sends data to a plugin's input ports. 106 107 @param controller The opaque controller pointer passed to 108 LV2UI_Descriptor::instantiate(). 109 110 @param port_index Index of the port to update. 111 112 @param buffer Buffer containing `buffer_size` bytes of data. 113 114 @param buffer_size Size of `buffer` in bytes. 115 116 @param port_protocol Either 0 or the URID for a ui:PortProtocol. If 0, the 117 protocol is implicitly ui:floatProtocol, the port MUST be an lv2:ControlPort 118 input, `buffer` MUST point to a single float value, and `buffer_size` MUST 119 be sizeof(float). The UI SHOULD NOT use a protocol not supported by the 120 host, but the host MUST gracefully ignore any protocol it does not 121 understand. 122 */ 123 alias LV2UI_Write_Function = void function(LV2UI_Controller controller, 124 uint32_t port_index, 125 uint32_t buffer_size, 126 uint32_t port_protocol, 127 const void* buffer); 128 129 /** 130 A plugin UI. 131 132 A pointer to an object of this type is returned by the lv2ui_descriptor() 133 function. 134 */ 135 struct LV2UI_Descriptor 136 { 137 nothrow: 138 @nogc: 139 extern(C): 140 /** 141 The URI for this UI (not for the plugin it controls). 142 */ 143 char* URI; 144 145 /** 146 Create a new UI and return a handle to it. This function works 147 similarly to LV2_Descriptor::instantiate(). 148 149 @param descriptor The descriptor for the UI to instantiate. 150 151 @param plugin_uri The URI of the plugin that this UI will control. 152 153 @param bundle_path The path to the bundle containing this UI, including 154 the trailing directory separator. 155 156 @param write_function A function that the UI can use to send data to the 157 plugin's input ports. 158 159 @param controller A handle for the UI instance to be passed as the 160 first parameter of UI methods. 161 162 @param widget (output) widget pointer. The UI points this at its main 163 widget, which has the type defined by the UI type in the data file. 164 165 @param features An array of LV2_Feature pointers. The host must pass 166 all feature URIs that it and the UI supports and any additional data, as 167 in LV2_Descriptor::instantiate(). Note that UI features and plugin 168 features are not necessarily the same. 169 170 */ 171 LV2UI_Handle function(const LV2UI_Descriptor* descriptor, 172 const char* plugin_uri, 173 const char* bundle_path, 174 LV2UI_Write_Function write_function, 175 LV2UI_Controller controller, 176 LV2UI_Widget* widget, 177 const (LV2_Feature*)* features) instantiate; 178 179 180 /** 181 Destroy the UI. The host must not try to access the widget after 182 calling this function. 183 */ 184 void function(LV2UI_Handle ui) cleanup; 185 186 /** 187 Tell the UI that something interesting has happened at a plugin port. 188 189 What is "interesting" and how it is written to `buffer` is defined by 190 `format`, which has the same meaning as in LV2UI_Write_Function(). 191 Format 0 is a special case for lv2:ControlPort, where this function 192 should be called when the port value changes (but not necessarily for 193 every change), `buffer_size` must be sizeof(float), and `buffer` 194 points to a single IEEE-754 float. 195 196 By default, the host should only call this function for lv2:ControlPort 197 inputs. However, the UI can request updates for other ports statically 198 with ui:portNotification or dynamicaly with ui:portSubscribe. 199 200 The UI MUST NOT retain any reference to `buffer` after this function 201 returns, it is only valid for the duration of the call. 202 203 This member may be NULL if the UI is not interested in any port events. 204 */ 205 void function(LV2UI_Handle ui, 206 uint32_t port_index, 207 uint32_t buffer_size, 208 uint32_t format, 209 const void* buffer) port_event; 210 211 /** 212 Return a data structure associated with an extension URI, typically an 213 interface struct with additional function pointers 214 215 This member may be set to NULL if the UI is not interested in supporting 216 any extensions. This is similar to LV2_Descriptor::extension_data(). 217 218 */ 219 const (void)* function(const char* uri) extension_data; 220 } 221 222 /** 223 Feature/interface for resizable UIs (LV2_UI__resize). 224 225 This structure is used in two ways: as a feature passed by the host via 226 LV2UI_Descriptor::instantiate(), or as an interface provided by a UI via 227 LV2UI_Descriptor::extension_data()). 228 */ 229 struct LV2UI_Resize 230 { 231 nothrow: 232 @nogc: 233 extern(C): 234 235 /** 236 Pointer to opaque data which must be passed to ui_resize(). 237 */ 238 LV2UI_Feature_Handle handle; 239 240 /** 241 Request/advertise a size change. 242 243 When provided by the host, the UI may call this function to inform the 244 host about the size of the UI. 245 246 When provided by the UI, the host may call this function to notify the 247 UI that it should change its size accordingly. In this case, the host 248 must pass the LV2UI_Handle to provide access to the UI instance. 249 250 @return 0 on success. 251 */ 252 int function(LV2UI_Feature_Handle handle, int width, int height) ui_resize; 253 } 254 255 /** 256 Feature to map port symbols to UIs. 257 258 This can be used by the UI to get the index for a port with the given 259 symbol. This makes it possible to implement and distribute a UI separately 260 from the plugin (since symbol, unlike index, is a stable port identifier). 261 */ 262 struct LV2UI_Port_Map 263 { 264 nothrow: 265 @nogc: 266 extern(C): 267 /** 268 Pointer to opaque data which must be passed to port_index(). 269 */ 270 LV2UI_Feature_Handle handle; 271 272 /** 273 Get the index for the port with the given `symbol`. 274 275 @return The index of the port, or LV2UI_INVALID_PORT_INDEX if no such 276 port is found. 277 */ 278 uint32_t function(LV2UI_Feature_Handle handle, const char* symbol) port_index; 279 } 280 281 /** 282 Feature to subscribe to port updates (LV2_UI__portSubscribe). 283 */ 284 struct LV2UI_Port_Subscribe 285 { 286 extern(C): 287 nothrow: 288 @nogc: 289 /** 290 Pointer to opaque data which must be passed to subscribe() and 291 unsubscribe(). 292 */ 293 LV2UI_Feature_Handle handle; 294 295 /** 296 Subscribe to updates for a port. 297 298 This means that the host will call the UI's port_event() function when 299 the port value changes (as defined by protocol). 300 301 Calling this function with the same `port_index` and `port_protocol` 302 as an already active subscription has no effect. 303 304 @param handle The handle field of this struct. 305 @param port_index The index of the port. 306 @param port_protocol The URID of the ui:PortProtocol. 307 @param features Features for this subscription. 308 @return 0 on success. 309 */ 310 uint32_t function(LV2UI_Feature_Handle handle, 311 uint32_t port_index, 312 uint32_t port_protocol, 313 const (LV2_Feature*)* features) subscribe; 314 315 /** 316 Unsubscribe from updates for a port. 317 318 This means that the host will cease calling calling port_event() when 319 the port value changes. 320 321 Calling this function with a `port_index` and `port_protocol` that 322 does not refer to an active port subscription has no effect. 323 324 @param handle The handle field of this struct. 325 @param port_index The index of the port. 326 @param port_protocol The URID of the ui:PortProtocol. 327 @param features Features for this subscription. 328 @return 0 on success. 329 */ 330 uint32_t function(LV2UI_Feature_Handle handle, 331 uint32_t port_index, 332 uint32_t port_protocol, 333 const (LV2_Feature*)* features) unsubscribe; 334 } 335 336 /** 337 A feature to notify the host that the user has grabbed a UI control. 338 */ 339 struct LV2UI_Touch 340 { 341 nothrow: 342 @nogc: 343 extern(C): 344 345 /** 346 Pointer to opaque data which must be passed to ui_resize(). 347 */ 348 LV2UI_Feature_Handle handle; 349 350 /** 351 Notify the host that a control has been grabbed or released. 352 353 The host should cease automating the port or otherwise manipulating the 354 port value until the control has been ungrabbed. 355 356 @param handle The handle field of this struct. 357 @param port_index The index of the port associated with the control. 358 @param grabbed If true, the control has been grabbed, otherwise the 359 control has been released. 360 */ 361 void function(LV2UI_Feature_Handle handle, 362 uint32_t port_index, 363 bool grabbed) touch; 364 } 365 366 /** 367 UI Idle Interface (LV2_UI__idleInterface) 368 369 UIs can provide this interface to have an idle() callback called by the host 370 rapidly to update the UI. 371 */ 372 struct LV2UI_Idle_Interface 373 { 374 nothrow: 375 @nogc: 376 extern(C): 377 /** 378 Run a single iteration of the UI's idle loop. 379 380 This will be called rapidly in the UI thread at a rate appropriate 381 for a toolkit main loop. There are no precise timing guarantees, but 382 the host should attempt to call idle() at a high enough rate for smooth 383 animation, at least 30Hz. 384 385 @return non-zero if the UI has been closed, in which case the host 386 should stop calling idle(), and can either completely destroy the UI, or 387 re-show it and resume calling idle(). 388 */ 389 int function(LV2UI_Handle ui) idle; 390 } 391 392 /** 393 UI Show Interface (LV2_UI__showInterface) 394 395 UIs can provide this interface to show and hide a window, which allows them 396 to function in hosts unable to embed their widget. This allows any UI to 397 provide a fallback for embedding that works in any host. 398 399 If used: 400 - The host MUST use LV2UI_Idle_Interface to drive the UI. 401 - The UI MUST return non-zero from LV2UI_Idle_Interface::idle() when it has been closed. 402 - If idle() returns non-zero, the host MUST call hide() and stop calling 403 idle(). It MAY later call show() then resume calling idle(). 404 */ 405 struct LV2UI_Show_Interface 406 { 407 nothrow: 408 @nogc: 409 extern(C): 410 /** 411 Show a window for this UI. 412 413 The window title MAY have been passed by the host to 414 LV2UI_Descriptor::instantiate() as an LV2_Options_Option with key 415 LV2_UI__windowTitle. 416 417 @return 0 on success, or anything else to stop being called. 418 */ 419 int function(LV2UI_Handle ui) show; 420 421 /** 422 Hide the window for this UI. 423 424 @return 0 on success, or anything else to stop being called. 425 */ 426 int function(LV2UI_Handle ui) hide; 427 } 428 429 /** 430 Peak data for a slice of time, the update format for ui:peakProtocol. 431 */ 432 struct LV2UI_Peak_Data 433 { 434 /** 435 The start of the measurement period. This is just a running counter 436 that is only meaningful in comparison to previous values and must not be 437 interpreted as an absolute time. 438 */ 439 uint32_t period_start; 440 441 /** 442 The size of the measurement period, in the same units as period_start. 443 */ 444 uint32_t period_size; 445 446 /** 447 The peak value for the measurement period. This should be the maximal 448 value for abs(sample) over all the samples in the period. 449 */ 450 float peak; 451 } 452 453 /** 454 The type of the lv2ui_descriptor() function. 455 */ 456 // typedef const LV2UI_Descriptor* (*LV2UI_DescriptorFunction)(uint32_t index); 457 alias LV2UI_DescriptorFunction = const LV2UI_Descriptor function(uint32_t index);