commit 912420157631ac87ef65115507353b94c625653c
parent 4381e4b9cf817fa010066533783e2dca09ed8324
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date: Tue, 18 Oct 2016 19:18:31 +0200
Give some hints about threading
Diffstat:
13 files changed, 114 insertions(+), 41 deletions(-)
diff --git a/include/clap/clap.h b/include/clap/clap.h
@@ -254,19 +254,25 @@ struct clap_host
void *host_data; // reserved pointer for the host
- /* returns the size of the original string, 0 if not string */
+ char name[CLAP_NAME_SIZE]; // plugin name, eg: "BitwigStudio"
+ char version[CLAP_VERSION_SIZE]; // the plugin version, eg: "1.3.14"
+
+ /* returns the size of the original string, 0 if not string
+ * [thread-safe] */
int32_t (*get_attribute)(struct clap_host *host,
const char *attr,
char *buffer,
int32_t size);
- /* Log a message through the host. */
+ /* Log a message through the host.
+ * [thread-safe] */
void (*log)(struct clap_host *host,
struct clap_plugin *plugin,
enum clap_log_severity severity,
const char *msg);
- /* query an extension */
+ /* query an extension
+ * [thread-safe] */
const void *(*extension)(struct clap_host *host, const char *extention_id);
};
@@ -331,21 +337,25 @@ struct clap_plugin
/* Copy at most size of the attribute's value into buffer.
* This function must place a '\0' byte at the end of the string.
* Returns the size of the original string or 0 if there is no
- * value for this attributes. */
+ * value for this attributes.
+ * [thread-safe] */
int32_t (*get_attribute)(struct clap_plugin *plugin,
const char *attr,
char *buffer,
int32_t size);
- /* activation */
+ /* activation/deactivation
+ * [audio-thread] */
bool (*activate)(struct clap_plugin *plugin);
void (*deactivate)(struct clap_plugin *plugin);
- /* process audio, events, ... */
+ /* process audio, events, ...
+ * [audio-thread] */
enum clap_process_status (*process)(struct clap_plugin *plugin,
struct clap_process *process);
- /* query an extension */
+ /* query an extension
+ * [thread-safe] */
const void *(*extension)(struct clap_plugin *plugin, const char *id);
};
@@ -357,19 +367,22 @@ struct clap_plugin
* 176400, 192000. */
struct clap_plugin_factory
{
- /* Get the number of plugins available. */
+ /* Get the number of plugins available.
+ * [thread-safe] */
int32_t get_plugin_count(struct clap_plugin_factory *factory);
/* Create a clap_plugin by its index.
* Valid indexes are from 0 to get_plugin_count() - 1.
- * Returns null in case of error. */
+ * Returns null in case of error.
+ * [thread-safe] */
struct clap_plugin *create_plugin_by_index(struct clap_plugin_factory *factory,
struct clap_host *host,
int32_t sample_rate,
int32_t index);
/* Create a clap_plugin by its plugin_id.
- * Returns null in case of error. */
+ * Returns null in case of error.
+ * [thread-safe] */
struct clap_plugin *create_plugin_by_id(struct clap_plugin_factory *factory,
struct clap_host *host,
int32_t sample_rate,
diff --git a/include/clap/ext/audio-ports.h b/include/clap/ext/audio-ports.h
@@ -51,10 +51,12 @@ struct clap_audio_port
* deactivated. */
struct clap_plugin_audio_ports
{
- /* number of ports, including inputs and outputs */
+ /* number of ports, including inputs and outputs
+ * [audio-thread] */
int32_t (*get_count)(struct clap_plugin *plugin);
- /* get info about about an audio port. */
+ /* get info about about an audio port.
+ * [audio-thread] */
void (*get_info)(struct clap_plugin *plugin,
int32_t index,
struct clap_audio_port_info *info);
@@ -64,16 +66,20 @@ struct clap_plugin_audio_ports
* It can be useful especialy for repeatable ports.
* Returns the id of the port. In case of repeatable port,
* make sure that each connected port has a different id.
- * Returns -1 if the connection failed. */
+ * Returns -1 if the connection failed.
+ * [audio-thread] */
int32_t (*connect)(struct clap_plugin *plugin,
int32_t port_id,
const struct clap_audio_port *port,
const char *user_name);
+ /* Disconnects a port.
+ * [audio-thread] */
void (*disconnect)(struct clap_plugin *plugin,
int32_t port_id);
- /* Returns the absolute port latency in samples. */
+ /* Returns the absolute port latency in samples.
+ * [audio-thread] */
int32_t (*get_latency)(struct clap_plugin *plugin,
int32_t port_id);
};
@@ -82,12 +88,14 @@ struct clap_host_audio_ports
{
/* Tell the host that the plugin ports has changed.
* The host shall deactivate the plugin and then
- * scan the ports again. */
+ * scan the ports again.
+ * [thread-safe] */
void (*changed)(struct clap_host *host,
struct clap_plugin *plugin);
/* Tell the host that the latency changed. The host should
- * call get_port_latency on each ports. */
+ * call get_port_latency on each ports.
+ * [thread-safe] */
void (*latency_changed)(struct clap_host *host,
struct clap_plugin *plugin);
};
diff --git a/include/clap/ext/embed-cocoa.h b/include/clap/ext/embed-cocoa.h
@@ -8,17 +8,19 @@
struct clap_plugin_embed_cocoa
{
+ /* Get the size of the plugin UI.
+ * [thread-safe] */
void (*get_size)(struct clap_plugin *plugin,
int32_t *width,
int32_t *height);
- /* Note for the client, you can get a Display* by calling
- * XOpenDisplay(display_name).
- *
- * Note for the host, the display_name can be retrieved from your own
- * display->display_name. */
+ /* Attach the plugin UI.
+ * [thread-safe] */
bool (*attach)(struct clap_plugin *plugin,
void *nsView);
+
+ /* Detach the plugin UI.
+ * [thread-safe] */
bool (*detach)(struct clap_plugin *plugin);
};
diff --git a/include/clap/ext/embed-win32.h b/include/clap/ext/embed-win32.h
@@ -10,10 +10,18 @@
struct clap_plugin_embed_win32
{
+ /* Get the size of the plugin UI.
+ * [thread-safe] */
void (*get_size)(struct clap_plugin *plugin,
int32_t *width,
int32_t *height);
+
+ /* Attach the plugin UI.
+ * [thread-safe] */
bool (*attach)(struct clap_plugin *plugin, HWND window);
+
+ /* Detach the plugin UI.
+ * [thread-safe] */
bool (*detach)(struct clap_plugin *plugin);
};
diff --git a/include/clap/ext/embed-x11.h b/include/clap/ext/embed-x11.h
@@ -8,6 +8,8 @@
struct clap_plugin_embed_x11
{
+ /* Get the size of the plugin UI.
+ * [thread-safe] */
void (*get_size)(struct clap_plugin *plugin,
int32_t *width,
int32_t *height);
@@ -16,10 +18,15 @@ struct clap_plugin_embed_x11
* XOpenDisplay(display_name).
*
* Note for the host, the display_name can be retrieved from your own
- * display->display_name. */
+ * display->display_name.
+ *
+ * [thread-safe] */
bool (*attach)(struct clap_plugin *plugin,
const char *display_name,
unsigned long window);
+
+ /* Detach the plugin UI.
+ * [thread-safe] */
bool (*detach)(struct clap_plugin *plugin);
};
diff --git a/include/clap/ext/embed.h b/include/clap/ext/embed.h
@@ -8,7 +8,8 @@
struct clap_host_embed
{
/* Request the host to resize the client area to width, height.
- * Return true on success, false otherwise. */
+ * Return true on success, false otherwise.
+ * [thread-safe] */
bool (*resize)(struct clap_host *host, int32_t width, int32_t height);
};
diff --git a/include/clap/ext/event-ports.h b/include/clap/ext/event-ports.h
@@ -29,10 +29,12 @@ struct clap_audio_port_info
struct clap_plugin_event_ports
{
- /* number of ports, including inputs and outputs */
+ /* number of ports, including inputs and outputs
+ * [audio-thread] */
int32_t (*get_count)(struct clap_plugin *plugin);
- /* get info about about an event port. */
+ /* get info about about an event port.
+ * [audio-thread] */
void (*get_info)(struct clap_plugin *plugin,
int32_t index,
struct clap_event_port_info *info);
@@ -42,13 +44,16 @@ struct clap_plugin_event_ports
* On failure, returns -1.
* user_name is a string provided by the host to tell the
* plugin how to name the new cloned port.
+ *
+ * [audio-thread]
*/
int32_t (*clone_port)(struct clap_plugin *plugin,
int32_t port_id,
const char *user_name);
/* When the host is done with a cloned port, it can call
- * release_port() to release the resources. */
+ * release_port() to release the resources.
+ * [audio-thread]*/
int32_t (*release_port)(struct clap_plugin *plugin,
int32_t port_id);
};
diff --git a/include/clap/ext/gui.h b/include/clap/ext/gui.h
@@ -7,20 +7,28 @@
struct clap_plugin_gui
{
- /* gui */
+ /* Open the GUI
+ * [thread-safe] */
bool (*open)(struct clap_plugin *plugin);
+
+ /* [thread-safe] */
void (*hide)(struct clap_plugin *plugin);
+
+ /* [thread-safe] */
void (*close)(struct clap_plugin *plugin);
};
struct clap_host_gui
{
+ /* [thread-safe] */
void (*gui_opened)(struct clap_host *host,
struct clap_plugin *plugin);
+ /* [thread-safe] */
void (*gui_hidden)(struct clap_host *host,
struct clap_plugin *plugin);
+ /* [thread-safe] */
void (*gui_closed)(struct clap_host *host,
struct clap_plugin *plugin);
};
diff --git a/include/clap/ext/locale.h b/include/clap/ext/locale.h
@@ -7,7 +7,8 @@
struct clap_plugin_locale
{
- /* Sets the locale to use */
+ /* Sets the locale to use.
+ * [thread-safe] */
bool (*set_locale)(struct clap_plugin *plugin, const char *locale);
};
diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h
@@ -71,17 +71,20 @@ struct clap_param_module
struct clap_plugin_params
{
- /* Returns the number of parameters. */
+ /* Returns the number of parameters.
+ * [audio-thread] */
int32_t (*count)(struct clap_plugin *plugin);
/* Copies the parameter's info to param and returns true.
- * If index is greater or equal to the number then return false. */
+ * If index is greater or equal to the number then return false.
+ * [audio-thread] */
bool (*get_param)(struct clap_plugin *plugin,
int32_t index,
struct clap_param *param);
/* Copies the module's info to module and returns true.
- * If module_id is NULL or invalid then return false. */
+ * If module_id is NULL or invalid then return false.
+ * [audio-thread] */
bool (*get_module)(struct clap_plugin *plugin,
const char *module_id,
struct clap_param_module *module);
@@ -91,7 +94,8 @@ struct clap_plugin_params
* automation event shall be ignored in favor of the audio rate
* automation.
*
- * To disconnect the automation, set buffer to NULL. */
+ * To disconnect the automation, set buffer to NULL.
+ * [audio-thread] */
bool (*set_param_port)(struct clap_plugin *plugin,
int32_t param_index,
int32_t channel,
@@ -101,20 +105,24 @@ struct clap_plugin_params
struct clap_host_params
{
+ /* [thread-safe] */
void (*touch_begin)(struct clap_host *host,
struct clap_plugin *plugin,
int32_t index);
+ /* [thread-safe] */
void (*touch_end)(struct clap_host *host,
struct clap_plugin *plugin,
int32_t index);
+ /* [thread-safe] */
void (*changed)(struct clap_host *host,
struct clap_plugin *plugin,
int32_t index,
union clap_param_value value,
bool is_recordable);
+ /* [thread-safe] */
void (*rescan)(struct clap_host *host,
struct clap_plugin *plugin);
};
diff --git a/include/clap/ext/presets.h b/include/clap/ext/presets.h
@@ -23,14 +23,17 @@ struct clap_preset_info
* load a preset. */
struct clap_plugin_preset
{
- /* Create a preset library for this plugin */
+ /* Create a preset library for this plugin
+ * [thread-safe] */
struct clap_preset_library *(*create_preset_library)(struct clap_plugin *plugin);
- /* Get the current preset info */
+ /* Get the current preset info
+ * [thread-safe] */
bool (*get_current_preset_info)(struct clap_plugin *plugin,
struct clap_preset_info *preset);
- /* Load a preset from a bank file */
+ /* Load a preset from a bank file
+ * [audio-thread] */
bool (*load_preset)(struct clap_plugin *plugin,
const char *path,
const char *preset_id);
@@ -58,29 +61,34 @@ struct clap_preset_library
/* Copies at most *path_size bytes into path.
* If directory_index is bigger than the number of directories,
- * then return false. */
+ * then return false.
+ * [thread-safe] */
bool (*get_directory)(struct clap_preset_library *library,
int directory_index,
char *path,
int32_t *path_size);
+ /* [thread-safe] */
bool (*open_bank)(struct clap_preset_library *library,
const char *path,
struct clap_bank_handle **handle);
+ /* [thread-safe] */
void (*close_bank)(struct clap_preset_library *library,
struct clap_bank_handle *handle);
/* Returns the number of presets in the bank.
* If it is not known, return -2.
- * On error return -1. */
+ * On error return -1.
+ * [thread-safe] */
int32_t (*get_bank_size)(struct clap_preset_library *library,
struct clap_bank_handle *handle);
/* Get a preset info from its path and returns true.
* In case of a preset bank file, index is used, and *has_next
* should be set to false when index reaches the last preset.
- * If the preset is not found, then it should return false. */
+ * If the preset is not found, then it should return false.
+ * [thread-safe] */
bool (*get_bank_preset)(struct clap_preset_library *library,
struct clap_bank_handle *handle,
struct clap_preset_info *preset_info,
diff --git a/include/clap/ext/render.h b/include/clap/ext/render.h
@@ -27,11 +27,12 @@ struct clap_plugin_render
/* Sets the plugin render mode, while the plugin is deactivated.
* Returns true on success, false otherwise.
* On failure the render mode is unchanged.
- */
+ * [audio-thread] */
bool (*set_render_mode)(struct clap_plugin *plugin,
enum clap_plugin_render_mode mode);
- /* Gets the current rendering mode, can be set anytime. */
+ /* Gets the current rendering mode, can be set anytime.
+ * [audio-thread] */
enum clap_plugin_render_mode (*get_render_mode)(struct clap_plugin *plugin);
};
diff --git a/include/clap/ext/state.h b/include/clap/ext/state.h
@@ -9,8 +9,11 @@ struct clap_plugin_state
{
/* The plugin has to allocate and save its state into *buffer.
* The plugin is also responsible to free the buffer on the
- * next call to save() or when the plugin is destroyed. */
+ * next call to save() or when the plugin is destroyed.
+ * [audio-thread] */
bool (*save)(struct clap_plugin *plugin, void **buffer, int32_t *size);
+
+ /* [audio-thread] */
bool (*restore)(struct clap_plugin *plugin, const void *buffer, int32_t size);
};
