clap

CLAP Audio Plugin API
Log | Files | Refs | README | LICENSE

commit 3929e26150b883b9435206502ba15b5b1f90dadc
parent 5820476b02107b6e62592d1a8afb91d5185ade8c
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date:   Fri,  3 Nov 2023 06:11:54 +0100

Merge pull request #360 from messmerd/return-value-clarifications

Clarify the meaning of boolean return values
Diffstat:
Minclude/clap/ext/audio-ports-config.h | 12+++++++-----
Minclude/clap/ext/audio-ports.h | 5+++--
Minclude/clap/ext/draft/context-menu.h | 8+++++++-
Minclude/clap/ext/draft/midi-mappings.h | 1+
Minclude/clap/ext/draft/preset-load.h | 1+
Minclude/clap/ext/draft/remote-controls.h | 1+
Minclude/clap/ext/draft/track-info.h | 1+
Minclude/clap/ext/draft/triggers.h | 1-
Minclude/clap/ext/draft/tuning.h | 1+
Minclude/clap/ext/event-registry.h | 2+-
Minclude/clap/ext/gui.h | 30+++++++++++++++---------------
Minclude/clap/ext/note-ports.h | 5+++--
Minclude/clap/ext/posix-fd-support.h | 3+++
Minclude/clap/ext/timer-support.h | 2++
Minclude/clap/factory/draft/preset-discovery.h | 3++-
Minclude/clap/plugin.h | 2++
16 files changed, 50 insertions(+), 28 deletions(-)

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 @@ -27,6 +27,7 @@ typedef struct clap_plugin_midi_mappings { uint32_t(CLAP_ABI *count)(const clap_plugin_t *plugin); // [main-thread] + // Returns true on success and stores the result into mapping. 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,6 +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, 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,25 @@ 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/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,6 +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, @@ -69,6 +70,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);