commit e292447bd0dbb265ef091178bfed9e29617ebb5b
parent 094bb76c85366a13cc6c49292226d8608d6ae50c
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date: Mon, 6 Nov 2023 15:04:42 +0100
Merge pull request #359 from free-audio/next
CLAP 1.1.10
Diffstat:
19 files changed, 72 insertions(+), 36 deletions(-)
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -1,3 +1,10 @@
+# Changes in 1.1.10
+
+* [params.h](include/clap/ext/params.h): add `CLAP_PARAM_IS_ENUM` flag.
+* various documentation improvements:
+ * clarification on the return value of many functions
+ * typos
+
# Changes in 1.1.9
* [entry.h](include/clap/entry.h): clarify what the `plugin_path` is on macOS
diff --git a/include/clap/ext/audio-ports-config.h b/include/clap/ext/audio-ports-config.h
@@ -54,20 +54,21 @@ typedef struct clap_audio_ports_config {
// The audio ports config scan has to be done while the plugin is deactivated.
typedef struct clap_plugin_audio_ports_config {
- // gets the number of available configurations
+ // Gets the number of available configurations
// [main-thread]
uint32_t(CLAP_ABI *count)(const clap_plugin_t *plugin);
- // gets information about a configuration
+ // Gets information about a configuration
+ // Returns true on success and stores the result into config.
// [main-thread]
bool(CLAP_ABI *get)(const clap_plugin_t *plugin,
uint32_t index,
clap_audio_ports_config_t *config);
- // selects the configuration designated by id
- // returns true if the configuration could be applied.
+ // Selects the configuration designated by id
+ // Returns true if the configuration could be applied.
// Once applied the host should scan again the audio ports.
- // [main-thread,plugin-deactivated]
+ // [main-thread & plugin-deactivated]
bool(CLAP_ABI *select)(const clap_plugin_t *plugin, clap_id config_id);
} clap_plugin_audio_ports_config_t;
@@ -82,6 +83,7 @@ typedef struct clap_plugin_audio_ports_config_info {
// Get info about an audio port, for a given config_id.
// This is analogous to clap_plugin_audio_ports.get().
+ // Returns true on success and stores the result into info.
// [main-thread]
bool(CLAP_ABI *get)(const clap_plugin_t *plugin,
clap_id config_id,
diff --git a/include/clap/ext/audio-ports.h b/include/clap/ext/audio-ports.h
@@ -67,11 +67,12 @@ typedef struct clap_audio_port_info {
// The audio ports scan has to be done while the plugin is deactivated.
typedef struct clap_plugin_audio_ports {
- // number of ports, for either input or output
+ // Number of ports, for either input or output
// [main-thread]
uint32_t(CLAP_ABI *count)(const clap_plugin_t *plugin, bool is_input);
- // get info about about an audio port.
+ // Get info about an audio port.
+ // Returns true on success and stores the result into info.
// [main-thread]
bool(CLAP_ABI *get)(const clap_plugin_t *plugin,
uint32_t index,
diff --git a/include/clap/ext/draft/context-menu.h b/include/clap/ext/draft/context-menu.h
@@ -94,7 +94,8 @@ typedef struct clap_context_menu_builder {
void *ctx;
// Adds an entry to the menu.
- // entry_data type is determined by entry_kind.
+ // item_data type is determined by item_kind.
+ // Returns true on success.
bool(CLAP_ABI *add_item)(const struct clap_context_menu_builder *builder,
clap_context_menu_item_kind_t item_kind,
const void *item_data);
@@ -107,6 +108,7 @@ typedef struct clap_context_menu_builder {
typedef struct clap_plugin_context_menu {
// Insert plugin's menu items into the menu builder.
// If target is null, assume global context.
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *populate)(const clap_plugin_t *plugin,
const clap_context_menu_target_t *target,
@@ -114,6 +116,7 @@ typedef struct clap_plugin_context_menu {
// Performs the given action, which was previously provided to the host via populate().
// If target is null, assume global context.
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *perform)(const clap_plugin_t *plugin,
const clap_context_menu_target_t *target,
@@ -123,6 +126,7 @@ typedef struct clap_plugin_context_menu {
typedef struct clap_host_context_menu {
// Insert host's menu items into the menu builder.
// If target is null, assume global context.
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *populate)(const clap_host_t *host,
const clap_context_menu_target_t *target,
@@ -130,6 +134,7 @@ typedef struct clap_host_context_menu {
// Performs the given action, which was previously provided to the plugin via populate().
// If target is null, assume global context.
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *perform)(const clap_host_t *host,
const clap_context_menu_target_t *target,
@@ -145,6 +150,7 @@ typedef struct clap_host_context_menu {
// If the plugin is using embedded GUI, then x and y are relative to the plugin's window,
// otherwise they're absolute coordinate, and screen index might be set accordingly.
// If target is null, assume global context.
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *popup)(const clap_host_t *host,
const clap_context_menu_target_t *target,
diff --git a/include/clap/ext/draft/midi-mappings.h b/include/clap/ext/draft/midi-mappings.h
@@ -26,6 +26,7 @@ typedef struct clap_plugin_midi_mappings {
// [main-thread]
uint32_t(CLAP_ABI *count)(const clap_plugin_t *plugin);
+ // Returns true on success and stores the result into mapping.
// [main-thread]
bool(CLAP_ABI *get)(const clap_plugin_t *plugin, uint32_t index, clap_midi_mapping_t *mapping);
} clap_plugin_midi_mappings_t;
diff --git a/include/clap/ext/draft/preset-load.h b/include/clap/ext/draft/preset-load.h
@@ -11,7 +11,7 @@ extern "C" {
typedef struct clap_plugin_preset_load {
// Loads a preset in the plugin native preset file format from a location.
// The preset discovery provider defines the location and load_key to be passed to this function.
- //
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *from_location)(const clap_plugin_t *plugin,
uint32_t location_kind,
diff --git a/include/clap/ext/draft/remote-controls.h b/include/clap/ext/draft/remote-controls.h
@@ -56,6 +56,7 @@ typedef struct clap_plugin_remote_controls {
uint32_t(CLAP_ABI *count)(const clap_plugin_t *plugin);
// Get a page by index.
+ // Returns true on success and stores the result into page.
// [main-thread]
bool(CLAP_ABI *get)(const clap_plugin_t *plugin,
uint32_t page_index,
diff --git a/include/clap/ext/draft/track-info.h b/include/clap/ext/draft/track-info.h
@@ -52,6 +52,7 @@ typedef struct clap_plugin_track_info {
typedef struct clap_host_track_info {
// Get info about the track the plugin belongs to.
+ // Returns true on success and stores the result into info.
// [main-thread]
bool(CLAP_ABI *get)(const clap_host_t *host, clap_track_info_t *info);
} clap_host_track_info_t;
diff --git a/include/clap/ext/draft/triggers.h b/include/clap/ext/draft/triggers.h
@@ -88,7 +88,6 @@ typedef struct clap_plugin_triggers {
uint32_t(CLAP_ABI *count)(const clap_plugin_t *plugin);
// Copies the trigger's info to trigger_info and returns true on success.
- // Returns true on success.
// [main-thread]
bool(CLAP_ABI *get_info)(const clap_plugin_t *plugin,
uint32_t index,
diff --git a/include/clap/ext/draft/tuning.h b/include/clap/ext/draft/tuning.h
@@ -64,6 +64,7 @@ typedef struct clap_host_tuning {
uint32_t(CLAP_ABI *get_tuning_count)(const clap_host_t *host);
// Gets info about a tuning
+ // Returns true on success and stores the result into info.
// [main-thread]
bool(CLAP_ABI *get_info)(const clap_host_t *host,
uint32_t tuning_index,
diff --git a/include/clap/ext/event-registry.h b/include/clap/ext/event-registry.h
@@ -12,7 +12,7 @@ typedef struct clap_host_event_registry {
// Queries an event space id.
// The space id 0 is reserved for CLAP's core events. See CLAP_CORE_EVENT_SPACE.
//
- // Return false and sets *space to UINT16_MAX if the space name is unknown to the host.
+ // Return false and sets *space_id to UINT16_MAX if the space name is unknown to the host.
// [main-thread]
bool(CLAP_ABI *query)(const clap_host_t *host, const char *space_name, uint16_t *space_id);
} clap_host_event_registry_t;
diff --git a/include/clap/ext/gui.h b/include/clap/ext/gui.h
@@ -204,25 +204,24 @@ typedef struct clap_host_gui {
// [thread-safe & !floating]
void(CLAP_ABI *resize_hints_changed)(const clap_host_t *host);
- /* Request the host to resize the client area to width, height.
- * Return true if the new size is accepted, false otherwise.
- * The host doesn't have to call set_size().
- *
- * Note: if not called from the main thread, then a return value simply means that the host
- * acknowledged the request and will process it asynchronously. If the request then can't be
- * satisfied then the host will call set_size() to revert the operation.
- *
- * [thread-safe & !floating] */
+ // Request the host to resize the client area to width, height.
+ // Return true if the new size is accepted, false otherwise.
+ // The host doesn't have to call set_size().
+ //
+ // Note: if not called from the main thread, then a return value simply means that the host
+ // acknowledged the request and will process it asynchronously. If the request then can't be
+ // satisfied then the host will call set_size() to revert the operation.
+ // [thread-safe & !floating]
bool(CLAP_ABI *request_resize)(const clap_host_t *host, uint32_t width, uint32_t height);
- /* Request the host to show the plugin gui.
- * Return true on success, false otherwise.
- * [thread-safe] */
+ // Request the host to show the plugin gui.
+ // Return true on success, false otherwise.
+ // [thread-safe]
bool(CLAP_ABI *request_show)(const clap_host_t *host);
- /* Request the host to hide the plugin gui.
- * Return true on success, false otherwise.
- * [thread-safe] */
+ // Request the host to hide the plugin gui.
+ // Return true on success, false otherwise.
+ // [thread-safe]
bool(CLAP_ABI *request_hide)(const clap_host_t *host);
// The floating window has been closed, or the connection to the gui has been lost.
diff --git a/include/clap/ext/note-ports.h b/include/clap/ext/note-ports.h
@@ -40,11 +40,12 @@ typedef struct clap_note_port_info {
// The note ports scan has to be done while the plugin is deactivated.
typedef struct clap_plugin_note_ports {
- // number of ports, for either input or output
+ // Number of ports, for either input or output.
// [main-thread]
uint32_t(CLAP_ABI *count)(const clap_plugin_t *plugin, bool is_input);
- // get info about about a note port.
+ // Get info about a note port.
+ // Returns true on success and stores the result into info.
// [main-thread]
bool(CLAP_ABI *get)(const clap_plugin_t *plugin,
uint32_t index,
diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h
@@ -195,6 +195,11 @@ enum {
// A simple example would be a DC Offset, changing it will change the output signal and must be
// processed.
CLAP_PARAM_REQUIRES_PROCESS = 1 << 15,
+
+ // This parameter represents an enumerated value.
+ // If you set this flag, then you must set CLAP_PARAM_IS_STEPPED too.
+ // All values from min to max must not have a blank value_to_text().
+ CLAP_PARAM_IS_ENUM = 1 << 16,
};
typedef uint32_t clap_param_info_flags;
@@ -251,19 +256,23 @@ typedef struct clap_plugin_params {
// [main-thread]
uint32_t(CLAP_ABI *count)(const clap_plugin_t *plugin);
- // Copies the parameter's info to param_info. Returns true on success.
+ // Copies the parameter's info to param_info.
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *get_info)(const clap_plugin_t *plugin,
uint32_t param_index,
clap_param_info_t *param_info);
- // Writes the parameter's current value to out_value. Returns true on success.
+ // Writes the parameter's current value to out_value.
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *get_value)(const clap_plugin_t *plugin, clap_id param_id, double *out_value);
// Fills out_buffer with a null-terminated UTF-8 string that represents the parameter at the
- // given 'value' argument. eg: "2.3 kHz". Returns true on success. The host should always use
- // this to format parameter values before displaying it to the user. [main-thread]
+ // given 'value' argument. eg: "2.3 kHz". The host should always use this to format parameter
+ // values before displaying it to the user.
+ // Returns true on success.
+ // [main-thread]
bool(CLAP_ABI *value_to_text)(const clap_plugin_t *plugin,
clap_id param_id,
double value,
@@ -271,7 +280,8 @@ typedef struct clap_plugin_params {
uint32_t out_buffer_capacity);
// Converts the null-terminated UTF-8 param_value_text into a double and writes it to out_value.
- // Returns true on success. The host can use this to convert user input into a parameter value.
+ // The host can use this to convert user input into a parameter value.
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *text_to_value)(const clap_plugin_t *plugin,
clap_id param_id,
diff --git a/include/clap/ext/posix-fd-support.h b/include/clap/ext/posix-fd-support.h
@@ -31,12 +31,15 @@ typedef struct clap_plugin_posix_fd_support {
} clap_plugin_posix_fd_support_t;
typedef struct clap_host_posix_fd_support {
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *register_fd)(const clap_host_t *host, int fd, clap_posix_fd_flags_t flags);
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *modify_fd)(const clap_host_t *host, int fd, clap_posix_fd_flags_t flags);
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *unregister_fd)(const clap_host_t *host, int fd);
} clap_host_posix_fd_support_t;
diff --git a/include/clap/ext/timer-support.h b/include/clap/ext/timer-support.h
@@ -17,9 +17,11 @@ typedef struct clap_host_timer_support {
// Registers a periodic timer.
// The host may adjust the period if it is under a certain threshold.
// 30 Hz should be allowed.
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *register_timer)(const clap_host_t *host, uint32_t period_ms, clap_id *timer_id);
+ // Returns true on success.
// [main-thread]
bool(CLAP_ABI *unregister_timer)(const clap_host_t *host, clap_id timer_id);
} clap_host_timer_support_t;
diff --git a/include/clap/factory/draft/preset-discovery.h b/include/clap/factory/draft/preset-discovery.h
@@ -131,7 +131,7 @@ typedef struct clap_preset_discovery_metadata_receiver {
// the plugin wants but it could also be some other unique id like a database primary key or a
// binary offset. It's use is entirely up to the plug-in.
//
- // If the function returns false, the the provider must stop calling back into the receiver.
+ // If the function returns false, then the provider must stop calling back into the receiver.
bool(CLAP_ABI *begin_preset)(const struct clap_preset_discovery_metadata_receiver *receiver,
const char *name,
const char *load_key);
@@ -242,6 +242,7 @@ typedef struct clap_preset_discovery_provider {
void(CLAP_ABI *destroy)(const struct clap_preset_discovery_provider *provider);
// reads metadata from the given file and passes them to the metadata receiver
+ // Returns true on success.
bool(CLAP_ABI *get_metadata)(const struct clap_preset_discovery_provider *provider,
uint32_t location_kind,
const char *location,
diff --git a/include/clap/plugin.h b/include/clap/plugin.h
@@ -59,7 +59,7 @@ typedef struct clap_plugin {
// call. The process's sample rate will be constant and process's frame count will included in
// the [min, max] range, which is bounded by [1, INT32_MAX].
// Once activated the latency and port configuration must remain constant, until deactivation.
- //
+ // Returns true on success.
// [main-thread & !active_state]
bool(CLAP_ABI *activate)(const struct clap_plugin *plugin,
double sample_rate,
@@ -69,6 +69,7 @@ typedef struct clap_plugin {
void(CLAP_ABI *deactivate)(const struct clap_plugin *plugin);
// Call start processing before processing.
+ // Returns true on success.
// [audio-thread & active_state & !processing_state]
bool(CLAP_ABI *start_processing)(const struct clap_plugin *plugin);
diff --git a/include/clap/version.h b/include/clap/version.h
@@ -22,7 +22,7 @@ typedef struct clap_version {
#define CLAP_VERSION_MAJOR 1
#define CLAP_VERSION_MINOR 1
-#define CLAP_VERSION_REVISION 9
+#define CLAP_VERSION_REVISION 10
#define CLAP_VERSION_INIT \
{ (uint32_t)CLAP_VERSION_MAJOR, (uint32_t)CLAP_VERSION_MINOR, (uint32_t)CLAP_VERSION_REVISION }
