#include <lv2-gui.h>
Data Fields | |
const char * | URI |
The URI for this GUI (not for the plugin it controls). | |
LV2UI_Handle(* | instantiate )(const struct _LV2UI_Descriptor *descriptor, const char *plugin_uri, const char *bundle_path, LV2UI_Write_Function write_function, LV2UI_Controller controller, LV2UI_Widget *widget, const LV2_Feature *const *features) |
Create a new GUI object and return a handle to it. | |
void(* | cleanup )(LV2UI_Handle gui) |
Destroy the GUI object and the associated widget. | |
void(* | port_event )(LV2UI_Handle gui, uint32_t port, uint32_t buffer_size, const void *buffer) |
Tell the GUI that something interesting has happened at a plugin port. | |
const void *(* | extension_data )(const char *uri) |
Returns a data structure associated with an extension URI, for example a struct containing additional function pointers. |
const char* LV2UI_Descriptor::URI |
The URI for this GUI (not for the plugin it controls).
LV2UI_Handle(* LV2UI_Descriptor::instantiate)(const struct _LV2UI_Descriptor *descriptor, const char *plugin_uri, const char *bundle_path, LV2UI_Write_Function write_function, LV2UI_Controller controller, LV2UI_Widget *widget, const LV2_Feature *const *features) |
Create a new GUI object and return a handle to it.
This function works similarly to the instantiate() member in LV2_Descriptor.
descriptor | The descriptor for the GUI that you want to instantiate. | |
plugin_uri | The URI of the plugin that this GUI will control. | |
bundle_path | The path to the bundle containing the RDF data file that references this shared object file, including the trailing '/'. | |
write_function | A function provided by the host that the GUI can use to send data to the plugin's input ports. | |
controller | A handle for the plugin instance that should be passed as the first parameter of write_function . | |
widget | A pointer to an LV2UI_Widget. The GUI will write a widget pointer to this location (what type of widget depends on the RDF class of the GUI) that will be the main GUI widget. | |
features | An array of LV2_Feature pointers. The host must pass all feature URIs that it and the plugin supports and any additional data, just like in the LV2 plugin instantiate() function. |
void(* LV2UI_Descriptor::cleanup)(LV2UI_Handle gui) |
Destroy the GUI object and the associated widget.
The host must not try to access the widget after calling this function.
void(* LV2UI_Descriptor::port_event)(LV2UI_Handle gui, uint32_t port, uint32_t buffer_size, const void *buffer) |
Tell the GUI that something interesting has happened at a plugin port.
What is interesting and how it is written to the buffer passed to this function is defined by the specified transfer mechanism for that port class (see LV2UI_Write_Function). The only exception is ports of the class lv2:ControlPort, for which this function should be called when the port value changes (it must not be called for every single change if the host's GUI thread has problems keeping up with the thread the plugin is running in), buffer_size
should be 4 and the buffer should contain a single IEEE-754 float.
By default, the host should only call this function for input ports of the lv2:ControlPort class. However, the default setting can be modified by using the following URIs in the GUI's RDF data:
guiext:portNotification guiext:noPortNotification guiext:plugin guiext:portIndexFor example, if you want the GUI with uri
<http://my.plugingui>
for the plugin with URI <http://my.plugin>
to get notified when the value of the output control port with index 4 changes, you would use the following in the RDF for your GUI: <http://my.plugingui> guiext:portNotification [ guiext:plugin <http://my.plugin> ; guiext:portIndex 4 ] .and similarly with
guiext:noPortNotification
if you wanted to prevent notifications for a port for which it would be on by default otherwise. The GUI is not allowed to request notifications for ports for which no transfer mechanism is specified, if it does it should be considered broken and the host should not load it. Also, a GUI should not expect to receive notifications for a port for which it has listed an optional transfer mechanism that the host does not support.
The buffer
is only valid during the time of this function call, so if the GUI wants to keep it for later use it has to copy the contents to an internal buffer.
This member may be set to NULL if the GUI is not interested in any port events.
const void*(* LV2UI_Descriptor::extension_data)(const char *uri) |
Returns a data structure associated with an extension URI, for example a struct containing additional function pointers.
Avoid returning function pointers directly since standard C++ has no valid way of casting a void* to a function pointer. This member may be set to NULL if the GUI is not interested in supporting any extensions. This is similar to the extension_data() member in LV2_Descriptor.