Merge branch 'free-audio:main' into Bremmers-midici-profiles

ChangeLog.md

@@ -1,14 +1,19 @@
 # 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
 * [surround.h](include/clap/ext/draft/surround.h): simplify the design
 * [ambisonic.h](include/clap/ext/draft/ambisonic.h): simplify the design
 * [configurable-audio-ports.h](include/clap/ext/draft/configurable-audio-ports.h): simplify the design
 * [gui.h](include/clap/ext/gui.h): documentation clarifications
 * [entry.h](include/clap/entry.h): documentation clarifications
-
-# Changes in 1.1.9
-
-* [entry.h](include/clap/entry.h): clarify what the `plugin_path` is on macOS
+* [audio-ports-activation.h](include/clap/ext/draft/audio-ports-activation.h): specify the sample size to be used when activating the audio port.
 
 # Changes in 1.1.8
 
@@ -138,7 +143,7 @@
   it is now **required** to deactivate the plugin before destroying it.
 * [params.h](include/clap/ext/params.h): improve documentation for `clap_host_params->request_flush()`.
 * [entry.h](include/clap/entry.h): improve documentation regarding `init()`, `deinit()` and CLAP search path.
-* [gui.h](inclued/clap/gui.h): fix typo `clap_gui_resize_hints.preserve_aspect_ratio`
+* [gui.h](include/clap/gui.h): fix typo `clap_gui_resize_hints.preserve_aspect_ratio`
 * [plugin-template](src/plugin-template.c): missing impl of plugin destroy.
 * various documentation improvements
 

README.md

@@ -22,8 +22,14 @@
 
 # Learn about CLAP
 
-CLAP stands for **CL**ever **A**udio **P**lugin.
-It is an audio plugin ABI which defines a standard for *Digital Audio Workstations* and audio plugins (synthesizers, audio effects, ...) to work together.
+CLAP stands for **CL**ever **A**udio **P**lugin. It is an interface that
+provides a stable ABI to define a standard for *Digital Audio Workstations* and
+audio plugins (synthesizers, audio effects, ...) to work together.
+
+The ABI, or **A**pplication **B**inary **I**nterface, serves as a means of
+communication between a host and a plugin. It provides backwards compatibility,
+that is, a plugin binary compiled with CLAP 1.x can be loaded by any other
+CLAP 1.y.
 
 To work with CLAP, include [clap/clap.h](include/clap/clap.h).
 

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,

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,

include/clap/ext/draft/ambisonic.h

@@ -12,15 +12,15 @@ static CLAP_CONSTEXPR const char CLAP_PORT_AMBISONIC[] = "ambisonic";
 extern "C" {
 #endif
 
-enum {
+enum clap_ambisonic_ordering {
    // FuMa channel ordering
-   CLAP_AMBISONIC_FUMA = 0,
+   CLAP_AMBISONIC_ORDERING_FUMA = 0,
 
    // ACN channel ordering
-   CLAP_AMBISONIC_ACN = 1,
+   CLAP_AMBISONIC_ORDERING_ACN = 1,
 };
 
-enum {
+enum clap_ambisonic_normalization {
    CLAP_AMBISONIC_NORMALIZATION_MAXN = 0,
    CLAP_AMBISONIC_NORMALIZATION_SN3D = 1,
    CLAP_AMBISONIC_NORMALIZATION_N3D = 2,
@@ -29,8 +29,8 @@ enum {
 };
 
 typedef struct clap_ambisonic_config {
-   uint32_t ordering;
-   uint32_t normalization;
+   uint32_t ordering;      // see clap_ambisonic_ordering
+   uint32_t normalization; // see clap_ambisonic_normalization
 } clap_ambisonic_config_t;
 
 typedef struct clap_plugin_ambisonic {

include/clap/ext/draft/audio-ports-activation.h

@@ -26,7 +26,7 @@
 /// clap_host_audio_ports.rescan(CLAP_AUDIO_PORTS_RESCAN_LIST).
 
 static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_ACTIVATION[] =
-   "clap.audio-ports-activation/draft-1";
+   "clap.audio-ports-activation/draft-2";
 
 #ifdef __cplusplus
 extern "C" {
@@ -42,12 +42,16 @@ typedef struct clap_plugin_audio_ports_activation {
    // It is only possible to activate and de-activate on the audio-thread if
    // can_activate_while_processing() returns true.
    //
+   // sample_size indicate if the host will provide 32 bit audio buffers or 64 bits one.
+   // Possible values are: 32, 64 or 0 if unspecified.
+   //
    // returns false if failed, or invalid parameters
    // [active ? audio-thread : main-thread]
    bool(CLAP_ABI *set_active)(const clap_plugin_t *plugin,
                               bool                 is_input,
                               uint32_t             port_index,
-                              bool                 is_active);
+                              bool                 is_active,
+                              uint32_t             sample_size);
 } clap_plugin_audio_ports_activation_t;
 
 #ifdef __cplusplus

include/clap/ext/draft/configurable-audio-ports.h

@@ -31,14 +31,25 @@ typedef struct clap_audio_port_configuration_request {
 } clap_audio_port_configuration_request_t;
 
 typedef struct clap_plugin_configurable_audio_ports {
-   // If is_dry_run is true, then checks if the configuration can be applied.
-   // If is_dry_run is false, then applies the configuration.
+   // Returns true if the given configurations can be applied using apply_configuration().
+   // [main-thread && !active]
+   bool(CLAP_ABI *can_apply_configuration)(
+      const clap_plugin_t                                *plugin,
+      const struct clap_audio_port_configuration_request *requests,
+      uint32_t                                            request_count);
+
+   // Submit a bunch of configuration requests which will atomically be applied together,
+   // or discarded together.
+   //
+   // Once the configuration is successfully applied, it isn't necessary for the plugin to call
+   // clap_host_audio_ports->changed(); and it isn't necessary for the host to scan the
+   // audio ports.
+   //
    // Returns true if applied.
    // [main-thread && !active]
    bool(CLAP_ABI *apply_configuration)(const clap_plugin_t                                *plugin,
                                        const struct clap_audio_port_configuration_request *requests,
-                                       uint32_t request_count,
-                                       bool     is_dry_run);
+                                       uint32_t request_count);
 } clap_plugin_configurable_audio_ports_t;
 
 #ifdef __cplusplus

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,13 +108,15 @@ 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,
                             const clap_context_menu_builder_t *builder);
 
    // 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,13 +126,15 @@ 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,
                             const clap_context_menu_builder_t *builder);
 
    // 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,

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;

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,

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,

include/clap/ext/draft/resource-directory.h

@@ -44,7 +44,7 @@ extern "C" {
 
 typedef struct clap_plugin_resource_directory {
    // Sets the directory in which the plugin can save its resources.
-   // The directory remains valid until it is overriden or the plugin is destroyed.
+   // The directory remains valid until it is overridden or the plugin is destroyed.
    // If path is null or blank, it clears the directory location.
    // path must be absolute.
    // [main-thread]

include/clap/ext/draft/surround.h

@@ -62,7 +62,7 @@ typedef struct clap_plugin_surround {
 
    // Stores the surround identifier of each channel into the channel_map array.
    // Returns the number of elements stored in channel_map.
-   // channel_map_capacity should be greater or equal to the channel count of the given port.
+   // channel_map_capacity must be greater or equal to the channel count of the given port.
    // [main-thread]
    uint32_t(CLAP_ABI *get_channel_map)(const clap_plugin_t *plugin,
                                        bool                 is_input,

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;

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,

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,

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;

include/clap/ext/gui.h

@@ -118,7 +118,7 @@ typedef struct clap_plugin_gui {
    //
    // After this call, the GUI may not be visible yet; don't forget to call show().
    //
-   // Returns true if the GUI is successfuly created.
+   // Returns true if the GUI is successfully created.
    // [main-thread]
    bool(CLAP_ABI *create)(const clap_plugin_t *plugin, const char *api, bool is_floating);
 
@@ -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.

include/clap/ext/latency.h

@@ -10,7 +10,7 @@ extern "C" {
 
 // The audio ports scan has to be done while the plugin is deactivated.
 typedef struct clap_plugin_latency {
-   // Returns the plugin latency.
+   // Returns the plugin latency in samples.
    // [main-thread]
    uint32_t(CLAP_ABI *get)(const clap_plugin_t *plugin);
 } clap_plugin_latency_t;

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,