ui.lv2/ui.h File Reference
#include "lv2.h"
Go to the source code of this file.
Data Structures | |
| struct | _LV2UI_Descriptor |
| This struct contains the implementation of an UI. More... | |
Defines | |
| #define | LV2_UI_URI "http://lv2plug.in/ns/extensions/ui" |
Typedefs | |
| typedef void * | LV2UI_Widget |
| A pointer to some widget or other type of UI handle. | |
| typedef void * | LV2UI_Handle |
| This handle indicates a particular instance of a UI. | |
| typedef void * | LV2UI_Controller |
| This handle indicates a particular plugin instance, provided by the host. | |
| typedef void(* | LV2UI_Write_Function )(LV2UI_Controller controller, uint32_t port_index, uint32_t buffer_size, uint32_t format, const void *buffer) |
| This is the type of the host-provided function that the UI can use to send data to a plugin's input ports. | |
| typedef struct _LV2UI_Descriptor | LV2UI_Descriptor |
| This struct contains the implementation of an UI. | |
| typedef const LV2UI_Descriptor *(* | LV2UI_DescriptorFunction )(uint32_t index) |
| This is the type of the lv2ui_descriptor() function. | |
Functions | |
| const LV2UI_Descriptor * | lv2ui_descriptor (uint32_t index) |
| A plugin UI programmer must include a function called "lv2ui_descriptor" with the following function prototype within the shared object file. | |
Define Documentation
| #define LV2_UI_URI "http://lv2plug.in/ns/extensions/ui" |
Typedef Documentation
| typedef void* LV2UI_Widget |
A pointer to some widget or other type of UI handle.
The actual type is defined by the type URI of the UI. All the functionality provided by this extension is toolkit independent, the host only needs to pass the necessary callbacks and display the widget, if possible. Plugins may have several UIs, in various toolkits.
| typedef void* LV2UI_Handle |
This handle indicates a particular instance of a UI.
It is valid to compare this to NULL (0 for C++) but otherwise the host MUST not attempt to interpret it. The UI plugin may use it to reference internal instance data.
| typedef void* LV2UI_Controller |
This handle indicates a particular plugin instance, provided by the host.
It is valid to compare this to NULL (0 for C++) but otherwise the UI plugin MUST not attempt to interpret it. The host may use it to reference internal plugin instance data.
| typedef void(* LV2UI_Write_Function)(LV2UI_Controller controller, uint32_t port_index, uint32_t buffer_size, uint32_t format, const void *buffer) |
This is the type of the host-provided function that the UI can use to send data to a plugin's input ports.
The buffer parameter must point to a block of data, buffer_size bytes large. The contents of this buffer and what the host should do with it depends on the value of the format parameter.
The format parameter should either be 0 or a numeric ID for a "Transfer
mechanism". Transfer mechanisms are Features and may be defined in meta-extensions. They specify how to translate the data buffers passed to this function to input data for the plugin ports. If a UI wishes to write data to an input port, it must list a transfer mechanism Feature for that port's class as an optional or required feature (depending on whether the UI will work without being able to write to that port or not). The only exception is when the UI wants to write single float values to input ports of the class lv2:ControlPort, in which case buffer_size should always be 4, the buffer should always contain a single IEEE-754 float, and format should be 0.
The numeric IDs for the transfer mechanisms are provided by a URI-to-integer mapping function provided by the host, using the URI Map feature <http://lv2plug.in/ns/ext/uri-map> with the map URI "http://lv2plug.in/ns/extensions/ui". Thus a UI that requires transfer mechanism features also requires the URI Map feature, but this is implicit - the UI does not have to list the URI map feature as a required or optional feature in it's RDF data.
An UI MUST NOT pass a format parameter value (except 0) that has not been returned by the host-provided URI mapping function for a host-supported transfer mechanism feature URI.
The UI MUST NOT try to write to a port for which there is no specified transfer mechanism, or to an output port. The UI is responsible for allocating the buffer and deallocating it after the call.
| typedef struct _LV2UI_Descriptor LV2UI_Descriptor |
This struct contains the implementation of an UI.
A pointer to an object of this type is returned by the lv2ui_descriptor() function.
| typedef const LV2UI_Descriptor*(* LV2UI_DescriptorFunction)(uint32_t index) |
This is the type of the lv2ui_descriptor() function.
Function Documentation
| const LV2UI_Descriptor* lv2ui_descriptor | ( | uint32_t | index | ) |
A plugin UI programmer must include a function called "lv2ui_descriptor" with the following function prototype within the shared object file.
This function will have C-style linkage (if you are using C++ this is taken care of by the 'extern "C"' clause at the top of the file). This function will be accessed by the UI host using the dlsym() function and called to get a LV2UI_UIDescriptor for the wanted plugin.
Just like lv2_descriptor(), this function takes an index parameter. The index should only be used for enumeration and not as any sort of ID number - the host should just iterate from 0 and upwards until the function returns NULL or a descriptor with an URI matching the one the host is looking for.
