From 775326d1337b6a55d4533df3738d4b2ca779d217 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Wed, 11 Apr 2012 04:25:11 +0000 Subject: Update documentation and fix indentation. --- lv2/lv2plug.in/ns/extensions/ui/ui.h | 196 ++++++++++++++++------------------- 1 file changed, 88 insertions(+), 108 deletions(-) (limited to 'lv2/lv2plug.in/ns/extensions/ui/ui.h') diff --git a/lv2/lv2plug.in/ns/extensions/ui/ui.h b/lv2/lv2plug.in/ns/extensions/ui/ui.h index a0ec2d3..7526a5a 100644 --- a/lv2/lv2plug.in/ns/extensions/ui/ui.h +++ b/lv2/lv2plug.in/ns/extensions/ui/ui.h @@ -120,114 +120,94 @@ typedef void (*LV2UI_Write_Function)(LV2UI_Controller controller, function. */ typedef struct _LV2UI_Descriptor { - /** - The URI for this UI (not for the plugin it controls). - */ - const char* URI; - - /** - Create a new UI object and return a handle to it. This function works - similarly to the instantiate() member in LV2_Descriptor. - - @param descriptor The descriptor for the UI that you want to instantiate. - - @param plugin_uri The URI of the plugin that this UI will control. - - @param bundle_path The path to the bundle containing the RDF data file - that references this shared object file, including the trailing '/'. - - @param write_function A function provided by the host that the UI can use - to send data to the plugin's input ports. - - @param controller A handle for the plugin instance that should be passed - as the first parameter of @c write_function. - - @param widget A pointer to an LV2UI_Widget. The UI will write a widget - pointer to this location (what type of widget depends on the RDF class of - the UI) that will be the main UI widget. - - @param features An array of LV2_Feature pointers. The host must pass all - feature URIs that it and the UI supports and any additional data, just - like in the LV2 plugin instantiate() function. Note that UI features and - plugin features are NOT necessarily the same, they just share the same - data structure - this will probably not be the same array as the one the - plugin host passes to a plugin. - - */ - 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); - - - /** - Destroy the UI object and the associated widget. The host must not try - to access the widget after calling this function. - */ - void (*cleanup)(LV2UI_Handle ui); - - /** - Tell the UI 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 @c format parameter, which has the same meaning - as in 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 does not have to be called for every single change if - the host's UI thread has problems keeping up with the thread the plugin is - running in), @c buffer_size should be 4, the buffer should contain a - single IEEE-754 float, and @c format should be 0. - - 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 UI's RDF data: - 
-     uiext:portNotification
-     uiext:noPortNotification
-     uiext:plugin
-     uiext:portIndex
-
- For example, if you want the UI with uri - for the plugin with URI - 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 UI: - 
-      uiext:portNotification [ uiext:plugin  ;
-     uiext:portIndex 4 ] .
-
- and similarly with uiext:noPortNotification if you wanted - to prevent notifications for a port for which it would be on by default - otherwise. The UI is not allowed to request notifications for ports of - types for which no transfer mechanism is specified, if it does it should - be considered broken and the host should not load it. - - The @c buffer is only valid during the time of this function call, so if - the UI 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 UI is not interested in any - port events. - */ - void (*port_event)(LV2UI_Handle ui, - uint32_t port_index, - uint32_t buffer_size, - uint32_t format, - const void* buffer); - - /** - Return a data structure associated with an extension URI, for example - a struct containing additional function pointers. - - Avoid returning function pointers directly since standard C/C++ has no - valid way of casting a void* to a function pointer. This member may be set - to NULL if the UI is not interested in supporting any extensions. This is - similar to the extension_data() member in LV2_Descriptor. - */ - const void* (*extension_data)(const char* uri); + /** + The URI for this UI (not for the plugin it controls). + */ + const char* URI; + + /** + Create a new UI object and return a handle to it. This function works + similarly to the instantiate() member in LV2_Descriptor. + + @param descriptor The descriptor for the UI that you want to instantiate. + + @param plugin_uri The URI of the plugin that this UI will control. + + @param bundle_path The path to the bundle containing the RDF data file + that references this shared object file, including the trailing '/'. + + @param write_function A function provided by the host that the UI can use + to send data to the plugin's input ports. + + @param controller A handle for the plugin instance that should be passed + as the first parameter of @c write_function. + + @param widget A pointer to an LV2UI_Widget. The UI will write a widget + pointer to this location (what type of widget depends on the RDF class of + the UI) that will be the main UI widget. + + @param features An array of LV2_Feature pointers. The host must pass all + feature URIs that it and the UI supports and any additional data, just + like in the LV2 plugin instantiate() function. Note that UI features and + plugin features are NOT necessarily the same, they just share the same + data structure - this will probably not be the same array as the one the + plugin host passes to a plugin. + + */ + 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); + + + /** + Destroy the UI object and the associated widget. The host must not try + to access the widget after calling this function. + */ + void (*cleanup)(LV2UI_Handle ui); + + /** + Tell the UI 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 @c format parameter, which has the same + meaning as in 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 does not have to be called for every single change + if the host's UI thread has problems keeping up with the thread the + plugin is running in), @c buffer_size should be 4, the buffer should + contain a single IEEE-754 float, and @c format should be 0. + + By default, the host should only call this function for input ports of + the lv2:ControlPort class. However, this can be modified by using + ui:portNotification in the UI data, or the ui:portSubscribe feature. + + The @c buffer is only valid during the time of this function call, so if + the UI 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 UI is not interested in any + port events. + */ + void (*port_event)(LV2UI_Handle ui, + uint32_t port_index, + uint32_t buffer_size, + uint32_t format, + const void* buffer); + + /** + Return a data structure associated with an extension URI, for example + a struct containing additional function pointers. + + Avoid returning function pointers directly since standard C/C++ has no + valid way of casting a void* to a function pointer. This member may be set + to NULL if the UI is not interested in supporting any extensions. This is + similar to the extension_data() member in LV2_Descriptor. + */ + const void* (*extension_data)(const char* uri); } LV2UI_Descriptor; /** -- cgit v1.2.1