aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/ui/ui.h
diff options
context:
space:
mode:
Diffstat (limited to 'lv2/ui/ui.h')
-rw-r--r--lv2/ui/ui.h579
1 files changed, 289 insertions, 290 deletions
diff --git a/lv2/ui/ui.h b/lv2/ui/ui.h
index ee3c47d..61b3b54 100644
--- a/lv2/ui/ui.h
+++ b/lv2/ui/ui.h
@@ -145,86 +145,85 @@ 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 and return a handle to it. This function works
- similarly to LV2_Descriptor::instantiate().
-
- @param descriptor The descriptor for the UI to instantiate.
-
- @param plugin_uri The URI of the plugin that this UI will control.
-
- @param bundle_path The path to the bundle containing this UI, including
- the trailing directory separator.
-
- @param write_function A function that the UI can use to send data to the
- plugin's input ports.
-
- @param controller A handle for the UI instance to be passed as the
- first parameter of UI methods.
-
- @param widget (output) widget pointer. The UI points this at its main
- widget, which has the type defined by the UI type in the data file.
-
- @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, as
- in LV2_Descriptor::instantiate(). Note that UI features and plugin
- features are not necessarily the same.
-
- */
- 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. 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 `buffer` is defined by
- `format`, which has the same meaning as in LV2UI_Write_Function().
- Format 0 is a special case for lv2:ControlPort, where this function
- should be called when the port value changes (but not necessarily for
- every change), `buffer_size` must be sizeof(float), and `buffer`
- points to a single IEEE-754 float.
-
- By default, the host should only call this function for lv2:ControlPort
- inputs. However, the UI can request updates for other ports statically
- with ui:portNotification or dynamicaly with ui:portSubscribe.
-
- The UI MUST NOT retain any reference to `buffer` after this function
- returns, it is only valid for the duration of the call.
-
- This member may be 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, typically an
- interface struct with additional function pointers
-
- This member may be set to NULL if the UI is not interested in supporting
- any extensions. This is similar to LV2_Descriptor::extension_data().
-
- */
- 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 and return a handle to it. This function works
+ similarly to LV2_Descriptor::instantiate().
+
+ @param descriptor The descriptor for the UI to instantiate.
+
+ @param plugin_uri The URI of the plugin that this UI will control.
+
+ @param bundle_path The path to the bundle containing this UI, including
+ the trailing directory separator.
+
+ @param write_function A function that the UI can use to send data to the
+ plugin's input ports.
+
+ @param controller A handle for the UI instance to be passed as the
+ first parameter of UI methods.
+
+ @param widget (output) widget pointer. The UI points this at its main
+ widget, which has the type defined by the UI type in the data file.
+
+ @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, as
+ in LV2_Descriptor::instantiate(). Note that UI features and plugin
+ features are not necessarily the same.
+
+ */
+ 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. 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 `buffer` is defined by
+ `format`, which has the same meaning as in LV2UI_Write_Function().
+ Format 0 is a special case for lv2:ControlPort, where this function
+ should be called when the port value changes (but not necessarily for
+ every change), `buffer_size` must be sizeof(float), and `buffer`
+ points to a single IEEE-754 float.
+
+ By default, the host should only call this function for lv2:ControlPort
+ inputs. However, the UI can request updates for other ports statically
+ with ui:portNotification or dynamicaly with ui:portSubscribe.
+
+ The UI MUST NOT retain any reference to `buffer` after this function
+ returns, it is only valid for the duration of the call.
+
+ This member may be 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, typically an
+ interface struct with additional function pointers
+
+ This member may be set to NULL if the UI is not interested in supporting
+ any extensions. This is similar to LV2_Descriptor::extension_data().
+
+ */
+ const void* (*extension_data)(const char* uri);
} LV2UI_Descriptor;
/**
@@ -235,24 +234,24 @@ typedef struct LV2UI_Descriptor {
LV2UI_Descriptor::extension_data()).
*/
typedef struct {
- /**
- Pointer to opaque data which must be passed to ui_resize().
- */
- LV2UI_Feature_Handle handle;
+ /**
+ Pointer to opaque data which must be passed to ui_resize().
+ */
+ LV2UI_Feature_Handle handle;
- /**
- Request/advertise a size change.
+ /**
+ Request/advertise a size change.
- When provided by the host, the UI may call this function to inform the
- host about the size of the UI.
+ When provided by the host, the UI may call this function to inform the
+ host about the size of the UI.
- When provided by the UI, the host may call this function to notify the
- UI that it should change its size accordingly. In this case, the host
- must pass the LV2UI_Handle to provide access to the UI instance.
+ When provided by the UI, the host may call this function to notify the
+ UI that it should change its size accordingly. In this case, the host
+ must pass the LV2UI_Handle to provide access to the UI instance.
- @return 0 on success.
- */
- int (*ui_resize)(LV2UI_Feature_Handle handle, int width, int height);
+ @return 0 on success.
+ */
+ int (*ui_resize)(LV2UI_Feature_Handle handle, int width, int height);
} LV2UI_Resize;
/**
@@ -263,181 +262,179 @@ typedef struct {
from the plugin (since symbol, unlike index, is a stable port identifier).
*/
typedef struct {
- /**
- Pointer to opaque data which must be passed to port_index().
- */
- LV2UI_Feature_Handle handle;
-
- /**
- Get the index for the port with the given `symbol`.
-
- @return The index of the port, or LV2UI_INVALID_PORT_INDEX if no such
- port is found.
- */
- uint32_t (*port_index)(LV2UI_Feature_Handle handle, const char* symbol);
+ /**
+ Pointer to opaque data which must be passed to port_index().
+ */
+ LV2UI_Feature_Handle handle;
+
+ /**
+ Get the index for the port with the given `symbol`.
+
+ @return The index of the port, or LV2UI_INVALID_PORT_INDEX if no such
+ port is found.
+ */
+ uint32_t (*port_index)(LV2UI_Feature_Handle handle, const char* symbol);
} LV2UI_Port_Map;
/**
Feature to subscribe to port updates (LV2_UI__portSubscribe).
*/
typedef struct {
- /**
- Pointer to opaque data which must be passed to subscribe() and
- unsubscribe().
- */
- LV2UI_Feature_Handle handle;
-
- /**
- Subscribe to updates for a port.
-
- This means that the host will call the UI's port_event() function when
- the port value changes (as defined by protocol).
-
- Calling this function with the same `port_index` and `port_protocol`
- as an already active subscription has no effect.
-
- @param handle The handle field of this struct.
- @param port_index The index of the port.
- @param port_protocol The URID of the ui:PortProtocol.
- @param features Features for this subscription.
- @return 0 on success.
- */
- uint32_t (*subscribe)(LV2UI_Feature_Handle handle,
- uint32_t port_index,
- uint32_t port_protocol,
- const LV2_Feature* const* features);
-
- /**
- Unsubscribe from updates for a port.
-
- This means that the host will cease calling calling port_event() when
- the port value changes.
-
- Calling this function with a `port_index` and `port_protocol` that
- does not refer to an active port subscription has no effect.
-
- @param handle The handle field of this struct.
- @param port_index The index of the port.
- @param port_protocol The URID of the ui:PortProtocol.
- @param features Features for this subscription.
- @return 0 on success.
- */
- uint32_t (*unsubscribe)(LV2UI_Feature_Handle handle,
- uint32_t port_index,
- uint32_t port_protocol,
- const LV2_Feature* const* features);
+ /**
+ Pointer to opaque data which must be passed to subscribe() and
+ unsubscribe().
+ */
+ LV2UI_Feature_Handle handle;
+
+ /**
+ Subscribe to updates for a port.
+
+ This means that the host will call the UI's port_event() function when
+ the port value changes (as defined by protocol).
+
+ Calling this function with the same `port_index` and `port_protocol`
+ as an already active subscription has no effect.
+
+ @param handle The handle field of this struct.
+ @param port_index The index of the port.
+ @param port_protocol The URID of the ui:PortProtocol.
+ @param features Features for this subscription.
+ @return 0 on success.
+ */
+ uint32_t (*subscribe)(LV2UI_Feature_Handle handle,
+ uint32_t port_index,
+ uint32_t port_protocol,
+ const LV2_Feature* const* features);
+
+ /**
+ Unsubscribe from updates for a port.
+
+ This means that the host will cease calling calling port_event() when
+ the port value changes.
+
+ Calling this function with a `port_index` and `port_protocol` that
+ does not refer to an active port subscription has no effect.
+
+ @param handle The handle field of this struct.
+ @param port_index The index of the port.
+ @param port_protocol The URID of the ui:PortProtocol.
+ @param features Features for this subscription.
+ @return 0 on success.
+ */
+ uint32_t (*unsubscribe)(LV2UI_Feature_Handle handle,
+ uint32_t port_index,
+ uint32_t port_protocol,
+ const LV2_Feature* const* features);
} LV2UI_Port_Subscribe;
/**
A feature to notify the host that the user has grabbed a UI control.
*/
typedef struct {
- /**
- Pointer to opaque data which must be passed to touch().
- */
- LV2UI_Feature_Handle handle;
-
- /**
- Notify the host that a control has been grabbed or released.
-
- The host should cease automating the port or otherwise manipulating the
- port value until the control has been ungrabbed.
-
- @param handle The handle field of this struct.
- @param port_index The index of the port associated with the control.
- @param grabbed If true, the control has been grabbed, otherwise the
- control has been released.
- */
- void (*touch)(LV2UI_Feature_Handle handle,
- uint32_t port_index,
- bool grabbed);
+ /**
+ Pointer to opaque data which must be passed to touch().
+ */
+ LV2UI_Feature_Handle handle;
+
+ /**
+ Notify the host that a control has been grabbed or released.
+
+ The host should cease automating the port or otherwise manipulating the
+ port value until the control has been ungrabbed.
+
+ @param handle The handle field of this struct.
+ @param port_index The index of the port associated with the control.
+ @param grabbed If true, the control has been grabbed, otherwise the
+ control has been released.
+ */
+ void (*touch)(LV2UI_Feature_Handle handle, uint32_t port_index, bool grabbed);
} LV2UI_Touch;
/**
A status code for LV2UI_Request_Value::request().
*/
typedef enum {
- /**
- Completed successfully.
-
- The host will set the parameter later if the user choses a new value.
- */
- LV2UI_REQUEST_VALUE_SUCCESS,
-
- /**
- Parameter already being requested.
-
- The host is already requesting a parameter from the user (for example, a
- dialog is visible), or the UI is otherwise busy and can not make this
- request.
- */
- LV2UI_REQUEST_VALUE_BUSY,
-
- /**
- Unknown parameter.
-
- The host is not aware of this parameter, and is not able to set a new
- value for it.
- */
- LV2UI_REQUEST_VALUE_ERR_UNKNOWN,
-
- /**
- Unsupported parameter.
-
- The host knows about this parameter, but does not support requesting a
- new value for it from the user. This is likely because the host does
- not have UI support for choosing a value with the appropriate type.
- */
- LV2UI_REQUEST_VALUE_ERR_UNSUPPORTED
+ /**
+ Completed successfully.
+
+ The host will set the parameter later if the user choses a new value.
+ */
+ LV2UI_REQUEST_VALUE_SUCCESS,
+
+ /**
+ Parameter already being requested.
+
+ The host is already requesting a parameter from the user (for example, a
+ dialog is visible), or the UI is otherwise busy and can not make this
+ request.
+ */
+ LV2UI_REQUEST_VALUE_BUSY,
+
+ /**
+ Unknown parameter.
+
+ The host is not aware of this parameter, and is not able to set a new
+ value for it.
+ */
+ LV2UI_REQUEST_VALUE_ERR_UNKNOWN,
+
+ /**
+ Unsupported parameter.
+
+ The host knows about this parameter, but does not support requesting a
+ new value for it from the user. This is likely because the host does
+ not have UI support for choosing a value with the appropriate type.
+ */
+ LV2UI_REQUEST_VALUE_ERR_UNSUPPORTED
} LV2UI_Request_Value_Status;
/**
A feature to request a new parameter value from the host.
*/
typedef struct {
- /**
- Pointer to opaque data which must be passed to request().
- */
- LV2UI_Feature_Handle handle;
-
- /**
- Request a value for a parameter from the host.
-
- This is mainly used by UIs to request values for complex parameters that
- don't change often, such as file paths, but it may be used to request
- any parameter value.
-
- This function returns immediately, and the return value indicates
- whether the host can fulfill the request. The host may notify the
- plugin about the new parameter value, for example when a file is
- selected by the user, via the usual mechanism. Typically, the host will
- send a message to the plugin that sets the new parameter value, and the
- plugin will notify the UI via a message as usual for any other parameter
- change.
-
- To provide an appropriate UI, the host can determine details about the
- parameter from the plugin data as usual. The additional parameters of
- this function provide support for more advanced use cases, but in the
- simple common case, the plugin will simply pass the key of the desired
- parameter and zero for everything else.
-
- @param handle The handle field of this struct.
-
- @param key The URID of the parameter.
-
- @param type The optional type of the value to request. This can be used
- to request a specific value type for parameters that support several.
- If non-zero, it must be the URID of an instance of rdfs:Class or
- rdfs:Datatype.
-
- @param features Additional features for this request, or NULL.
-
- @return A status code which is 0 on success.
- */
- LV2UI_Request_Value_Status (*request)(LV2UI_Feature_Handle handle,
- LV2_URID key,
- LV2_URID type,
- const LV2_Feature* const* features);
+ /**
+ Pointer to opaque data which must be passed to request().
+ */
+ LV2UI_Feature_Handle handle;
+
+ /**
+ Request a value for a parameter from the host.
+
+ This is mainly used by UIs to request values for complex parameters that
+ don't change often, such as file paths, but it may be used to request
+ any parameter value.
+
+ This function returns immediately, and the return value indicates
+ whether the host can fulfill the request. The host may notify the
+ plugin about the new parameter value, for example when a file is
+ selected by the user, via the usual mechanism. Typically, the host will
+ send a message to the plugin that sets the new parameter value, and the
+ plugin will notify the UI via a message as usual for any other parameter
+ change.
+
+ To provide an appropriate UI, the host can determine details about the
+ parameter from the plugin data as usual. The additional parameters of
+ this function provide support for more advanced use cases, but in the
+ simple common case, the plugin will simply pass the key of the desired
+ parameter and zero for everything else.
+
+ @param handle The handle field of this struct.
+
+ @param key The URID of the parameter.
+
+ @param type The optional type of the value to request. This can be used
+ to request a specific value type for parameters that support several.
+ If non-zero, it must be the URID of an instance of rdfs:Class or
+ rdfs:Datatype.
+
+ @param features Additional features for this request, or NULL.
+
+ @return A status code which is 0 on success.
+ */
+ LV2UI_Request_Value_Status (*request)(LV2UI_Feature_Handle handle,
+ LV2_URID key,
+ LV2_URID type,
+ const LV2_Feature* const* features);
} LV2UI_Request_Value;
@@ -448,19 +445,19 @@ typedef struct {
rapidly to update the UI.
*/
typedef struct {
- /**
- Run a single iteration of the UI's idle loop.
-
- This will be called rapidly in the UI thread at a rate appropriate
- for a toolkit main loop. There are no precise timing guarantees, but
- the host should attempt to call idle() at a high enough rate for smooth
- animation, at least 30Hz.
-
- @return non-zero if the UI has been closed, in which case the host
- should stop calling idle(), and can either completely destroy the UI, or
- re-show it and resume calling idle().
- */
- int (*idle)(LV2UI_Handle ui);
+ /**
+ Run a single iteration of the UI's idle loop.
+
+ This will be called rapidly in the UI thread at a rate appropriate
+ for a toolkit main loop. There are no precise timing guarantees, but
+ the host should attempt to call idle() at a high enough rate for smooth
+ animation, at least 30Hz.
+
+ @return non-zero if the UI has been closed, in which case the host
+ should stop calling idle(), and can either completely destroy the UI, or
+ re-show it and resume calling idle().
+ */
+ int (*idle)(LV2UI_Handle ui);
} LV2UI_Idle_Interface;
/**
@@ -472,51 +469,52 @@ typedef struct {
If used:
- The host MUST use LV2UI_Idle_Interface to drive the UI.
- - The UI MUST return non-zero from LV2UI_Idle_Interface::idle() when it has been closed.
+ - The UI MUST return non-zero from LV2UI_Idle_Interface::idle() when it has
+ been closed.
- If idle() returns non-zero, the host MUST call hide() and stop calling
idle(). It MAY later call show() then resume calling idle().
*/
typedef struct {
- /**
- Show a window for this UI.
+ /**
+ Show a window for this UI.
- The window title MAY have been passed by the host to
- LV2UI_Descriptor::instantiate() as an LV2_Options_Option with key
- LV2_UI__windowTitle.
+ The window title MAY have been passed by the host to
+ LV2UI_Descriptor::instantiate() as an LV2_Options_Option with key
+ LV2_UI__windowTitle.
- @return 0 on success, or anything else to stop being called.
- */
- int (*show)(LV2UI_Handle ui);
+ @return 0 on success, or anything else to stop being called.
+ */
+ int (*show)(LV2UI_Handle ui);
- /**
- Hide the window for this UI.
+ /**
+ Hide the window for this UI.
- @return 0 on success, or anything else to stop being called.
- */
- int (*hide)(LV2UI_Handle ui);
+ @return 0 on success, or anything else to stop being called.
+ */
+ int (*hide)(LV2UI_Handle ui);
} LV2UI_Show_Interface;
/**
Peak data for a slice of time, the update format for ui:peakProtocol.
*/
typedef struct {
- /**
- The start of the measurement period. This is just a running counter
- that is only meaningful in comparison to previous values and must not be
- interpreted as an absolute time.
- */
- uint32_t period_start;
-
- /**
- The size of the measurement period, in the same units as period_start.
- */
- uint32_t period_size;
-
- /**
- The peak value for the measurement period. This should be the maximal
- value for abs(sample) over all the samples in the period.
- */
- float peak;
+ /**
+ The start of the measurement period. This is just a running counter
+ that is only meaningful in comparison to previous values and must not be
+ interpreted as an absolute time.
+ */
+ uint32_t period_start;
+
+ /**
+ The size of the measurement period, in the same units as period_start.
+ */
+ uint32_t period_size;
+
+ /**
+ The peak value for the measurement period. This should be the maximal
+ value for abs(sample) over all the samples in the period.
+ */
+ float peak;
} LV2UI_Peak_Data;
/**
@@ -526,7 +524,8 @@ typedef struct {
lv2_descriptor() but for UIs rather than plugins.
*/
LV2_SYMBOL_EXPORT
-const LV2UI_Descriptor* lv2ui_descriptor(uint32_t index);
+const LV2UI_Descriptor*
+lv2ui_descriptor(uint32_t index);
/**
The type of the lv2ui_descriptor() function.