aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/lv2plug.in/ns/extensions
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2012-04-11 04:25:11 +0000
committerDavid Robillard <d@drobilla.net>2012-04-11 04:25:11 +0000
commit775326d1337b6a55d4533df3738d4b2ca779d217 (patch)
tree1d22e990b0e7ea76b7654749b3f3dfee1c38ea6c /lv2/lv2plug.in/ns/extensions
parente8532ba49f54d511c00fbd605645e3e1431fe138 (diff)
downloadlv2-775326d1337b6a55d4533df3738d4b2ca779d217.tar.xz
Update documentation and fix indentation.
Diffstat (limited to 'lv2/lv2plug.in/ns/extensions')
-rw-r--r--lv2/lv2plug.in/ns/extensions/ui/ui.h196
1 files changed, 88 insertions, 108 deletions
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:
- <pre>
- uiext:portNotification
- uiext:noPortNotification
- uiext:plugin
- uiext:portIndex
- </pre>
- For example, if you want the UI with uri
- <code><http://my.pluginui></code> for the plugin with URI
- <code><http://my.plugin></code> 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:
- <pre>
- <http://my.pluginui> uiext:portNotification [ uiext:plugin <http://my.plugin> ;
- uiext:portIndex 4 ] .
- </pre>
- and similarly with <code>uiext:noPortNotification</code> 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;
/**