Merge pull request #291 from free-audio/next

1.1.8

ChangeLog.md

@@ -1,3 +1,26 @@
+# Changes in 1.1.8
+
+* [params.h](include/clap/ext/params.h): document how persisting parameter values between sessions should be implemented
+* [state.h](include/clap/ext/state.h): add basic documentation regarding what state should be saved and how plugins should interact with buffers
+* various documentation fixes (essentially typos)
+
+## Draft extensions
+
+* [extensible-audio-ports.h](include/clap/ext/draft/extensible-audio-ports.h): new extension which lets the host add ports to a plugin
+* [configurable-audio-ports.h](include/clap/ext/draft/configurable-audio-ports.h): new extension allowing the host to **push** an audio ports configuration request, resulting in a simpler workflow for surround host and plugins
+* [surround.h](include/clap/ext/draft/surround.h):
+  * remove `get_preferred_channel_map()` in favor of the push approach via [configurable-audio-ports.h](include/clap/ext/draft/configurable-audio-ports.h)
+  * remove `config_id` argument from `get_info()`
+* [ambisonic.h](include/clap/ext/draft/ambisonic.h): remove `config_id` argument from `get_info()`
+* [preset-load.h](include/clap/ext/draft/preset-load.h): use a location_kind + location approach instead of URI
+
+## Draft factories
+
+* [preset-discovery.h](include/clap/factory/draft/preset-discovery.h):
+  * use a location_kind + location approach instead of URI
+  * document which descriptor fields are optional
+  * allow optional preset names in the metadata for non-container presets
+
 # Changes in 1.1.7
 
 * Add a [factory](include/clap/factory) folder for better organization and move our factories there

include/clap/clap.h

@@ -67,3 +67,5 @@
 #include "ext/draft/track-info.h"
 #include "ext/draft/triggers.h"
 #include "ext/draft/tuning.h"
+#include "ext/draft/configurable-audio-ports.h"
+#include "ext/draft/extensible-audio-ports.h"

include/clap/events.h

@@ -54,8 +54,8 @@ enum {
    // cases:
    // - a plugin is inside a drum pad in Bitwig Studio's drum machine, and this pad is choked by
    //   another one
-   // - the user double clicks the DAW's stop button in the transport which then stops the sound on
-   //   every tracks
+   // - the user double-clicks the DAW's stop button in the transport which then stops the sound on
+   //   every track
    //
    // NOTE_END is sent by the plugin to the host. The port, channel, key and note_id are those given
    // by the host in the NOTE_ON event. In other words, this event is matched against the
@@ -221,7 +221,7 @@ typedef struct clap_event_transport {
    clap_sectime  song_pos_seconds; // position in seconds
 
    double tempo;     // in bpm
-   double tempo_inc; // tempo increment for each samples and until the next
+   double tempo_inc; // tempo increment for each sample and until the next
                      // time info event
 
    clap_beattime loop_start_beats;
@@ -260,7 +260,7 @@ typedef struct clap_event_midi2 {
    uint32_t data[4];
 } clap_event_midi2_t;
 
-// Input event list, events must be sorted by time.
+// Input event list. The host will deliver these sorted in sample order.
 typedef struct clap_input_events {
    void *ctx; // reserved pointer for the list
 
@@ -271,7 +271,7 @@ typedef struct clap_input_events {
    const clap_event_header_t *(CLAP_ABI *get)(const struct clap_input_events *list, uint32_t index);
 } clap_input_events_t;
 
-// Output event list, events must be sorted by time.
+// Output event list. The plugin must insert events in sample sorted order when inserting events
 typedef struct clap_output_events {
    void *ctx; // reserved pointer for the list
 

include/clap/ext/audio-ports-config.h

@@ -6,8 +6,8 @@
 
 /// @page Audio Ports Config
 ///
-/// This extension provides a way for the plugin to describe possible port configurations, for
-/// example mono, stereo, surround, ... and a way for the host to select a configuration.
+/// This extension let the plugin provide port configurations presets.
+/// For example mono, stereo, surround, ambisonic, ...
 ///
 /// After the plugin initialization, the host may scan the list of configurations and eventually
 /// select one that fits the plugin context. The host can only select a configuration if the plugin
@@ -80,7 +80,7 @@ typedef struct clap_plugin_audio_ports_config_info {
    // [main-thread]
    clap_id(CLAP_ABI *current_config)(const clap_plugin_t *plugin);
 
-   // Get info about about an audio port, for a given config_id.
+   // Get info about an audio port, for a given config_id.
    // This is analogous to clap_plugin_audio_ports.get().
    // [main-thread]
    bool(CLAP_ABI *get)(const clap_plugin_t    *plugin,

include/clap/ext/draft/ambisonic.h

@@ -4,7 +4,7 @@
 
 // This extension can be used to specify the channel mapping used by the plugin.
 
-static CLAP_CONSTEXPR const char CLAP_EXT_AMBISONIC[] = "clap.ambisonic.draft/1";
+static CLAP_CONSTEXPR const char CLAP_EXT_AMBISONIC[] = "clap.ambisonic.draft/2";
 
 static CLAP_CONSTEXPR const char CLAP_PORT_AMBISONIC[] = "ambisonic";
 
@@ -40,7 +40,6 @@ typedef struct clap_plugin_ambisonic {
    // If config_id is CLAP_INVALID_ID, then this function queries the current port info.
    // [main-thread]
    bool(CLAP_ABI *get_info)(const clap_plugin_t   *plugin,
-                            clap_id                config_id,
                             bool                   is_input,
                             uint32_t               port_index,
                             clap_ambisonic_info_t *info);

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

@@ -0,0 +1,58 @@
+#pragma once
+
+#include "../audio-ports.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// This extension lets the host configure the plugin's input and output audio ports.
+// This is a "push" approach to audio ports configuration.
+static CLAP_CONSTEXPR const char CLAP_EXT_CONFIGURABLE_AUDIO_PORTS[] =
+   "clap.configurable-audio-ports.draft0";
+
+typedef struct clap_audio_port_configuration_request {
+   // When true, allows the plugin to pick a similar port configuration instead
+   // if the requested one can't be applied.
+   bool is_best_effort;
+
+   // Identifies the port by is_input and port_index
+   bool     is_input;
+   uint32_t port_index;
+
+   // The requested number of channels.
+   uint32_t channel_count;
+
+   // The port type, see audio-ports.h, clap_audio_port_info.port_type for interpretation.
+   const char *port_type;
+
+   // cast port_details according to port_type:
+   // - CLAP_PORT_MONO: (discard)
+   // - CLAP_PORT_STEREO: (discard)
+   // - CLAP_PORT_SURROUND: const uint8_t *channel_map
+   // - CLAP_PORT_AMBISONIC: const clap_ambisonic_info_t *info
+   const void *port_details;
+} clap_audio_port_configuration_request_t;
+
+typedef struct clap_plugin_configurable_audio_ports {
+   // Some ports may not be configurable, or simply the result of another port configuration.
+   // For example if you have a simple delay plugin, then the output port must have the exact
+   // same type as the input port; in that example, we consider the output port type to be a
+   // function (identity) of the input port type.
+   // [main-thread && !active]
+   bool(CLAP_ABI *is_port_configurable)(const clap_plugin_t *plugin,
+                                        bool                 is_input,
+                                        uint32_t             port_index);
+
+   // Submit a bunch of configuration requests which will atomically be applied together,
+   // or discarded together.
+   // [main-thread && !active]
+   bool(CLAP_ABI *request_configuration)(
+      const clap_plugin_t                                *plugin,
+      const struct clap_audio_port_configuration_request *requests,
+      uint32_t                                            request_count);
+} clap_plugin_configurable_audio_ports_t;
+
+#ifdef __cplusplus
+}
+#endif

include/clap/ext/draft/context-menu.h

@@ -136,7 +136,7 @@ typedef struct clap_host_context_menu {
                            clap_id                           action_id);
 
    // Returns true if the host can display a popup menu for the plugin.
-   // This may depends upon the current windowing system used to display the plugin, so the
+   // This may depend upon the current windowing system used to display the plugin, so the
    // return value is invalidated after creating the plugin window.
    // [main-thread]
    bool(CLAP_ABI *can_popup)(const clap_host_t *host);

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

@@ -0,0 +1,33 @@
+#pragma once
+
+#include "../audio-ports.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// This extension lets the host add and remove audio ports to the plugin.
+static CLAP_CONSTEXPR const char CLAP_EXT_EXTENSIBLE_AUDIO_PORTS[] =
+   "clap.extensible-audio-ports.draft0";
+
+typedef struct clap_plugin_extensible_audio_ports {
+   // Asks the plugin to add a new port (at the end of the list), with the following settings.
+   // port_type: see clap_audio_port_info.port_type for interpretation.
+   // port_details: see clap_audio_port_configuration_request.port_details for interpretation.
+   // Returns true on success.
+   // [main-thread && !is_active]
+   bool(CLAP_ABI *add_port)(const clap_plugin_t *plugin,
+                            bool                 is_input,
+                            uint32_t             channel_count,
+                            const char          *port_type,
+                            const void          *port_details);
+
+   // Asks the plugin to remove a port.
+   // Returns true on success.
+   // [main-thread && !is_active]
+   bool(CLAP_ABI *remove_port)(const clap_plugin_t *plugin, bool is_input, uint32_t index);
+} clap_plugin_extensible_audio_ports_t;
+
+#ifdef __cplusplus
+}
+#endif

include/clap/ext/draft/param-indication.h

@@ -32,7 +32,7 @@ enum {
    // The host is recording an automation on this parameter
    CLAP_PARAM_INDICATION_AUTOMATION_RECORDING = 3,
 
-   // The host should play an automation for this parameter, but the user has started to ajust this
+   // The host should play an automation for this parameter, but the user has started to adjust this
    // parameter and is overriding the automation playback
    CLAP_PARAM_INDICATION_AUTOMATION_OVERRIDING = 4,
 };

include/clap/ext/draft/preset-load.h

@@ -2,21 +2,21 @@
 
 #include "../../plugin.h"
 
-static const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load.draft/1";
+static const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load.draft/2";
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 typedef struct clap_plugin_preset_load {
-   // Loads a preset in the plugin native preset file format from a URI. eg:
-   // - "file:///home/abique/.u-he/Diva/Presets/Diva/HS Bass Nine.h2p", load_key: null
-   // - "plugin://<plugin-id>", load_key: <XXX>
-   //
-   // The preset discovery provider defines the uri and load_key to be passed to this function.
+   // 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.
    //
    // [main-thread]
-   bool(CLAP_ABI *from_uri)(const clap_plugin_t *plugin, const char *uri, const char *load_key);
+   bool(CLAP_ABI *from_location)(const clap_plugin_t *plugin,
+                                 uint32_t             location_kind,
+                                 const char          *location,
+                                 const char          *load_key);
 } clap_plugin_preset_load_t;
 
 typedef struct clap_host_preset_load {
@@ -26,7 +26,9 @@ typedef struct clap_host_preset_load {
    //
    // [main-thread]
    void(CLAP_ABI *on_error)(const clap_host_t *host,
-                            const char        *uri,
+                            uint32_t           location_kind,
+                            const char        *location,
+                            const char        *load_key,
                             int32_t            os_error,
                             const char        *msg);
 
@@ -36,7 +38,10 @@ typedef struct clap_host_preset_load {
    // must be null.
    //
    // [main-thread]
-   void(CLAP_ABI *loaded)(const clap_host_t *host, const char *uri, const char *load_key);
+   void(CLAP_ABI *loaded)(const clap_host_t *host,
+                          uint32_t           location_kind,
+                          const char        *location,
+                          const char        *load_key);
 } clap_host_preset_load_t;
 
 #ifdef __cplusplus

include/clap/ext/draft/remote-controls.h

@@ -67,7 +67,7 @@ typedef struct clap_host_remote_controls {
    // [main-thread]
    void(CLAP_ABI *changed)(const clap_host_t *host);
 
-   // Suggest a page to the host because it correspond to what the user is currently editing in the
+   // Suggest a page to the host because it corresponds to what the user is currently editing in the
    // plugin's GUI.
    // [main-thread]
    void(CLAP_ABI *suggest_page)(const clap_host_t *host, clap_id page_id);

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

@@ -24,7 +24,7 @@ extern "C" {
 ///   -> suitable for read-write content
 ///
 /// Keeping the shared directory clean:
-/// - to avoid clashes in the shared directory, plugins are encourraged to organize their files in
+/// - to avoid clashes in the shared directory, plugins are encouraged to organize their files in
 ///   sub-folders, for example create one subdirectory using the vendor name
 /// - don't use symbolic links or hard links which points outside of the directory
 ///
@@ -35,7 +35,7 @@ extern "C" {
 ///   are removed from the project
 ///
 /// Note for the host
-/// - try to use the filesytem's copy-on-write feature when possible for reducing exclusive folder
+/// - try to use the filesystem's copy-on-write feature when possible for reducing exclusive folder
 ///   space usage on duplication
 /// - host can "garbage collect" the files in the shared folder using:
 ///     clap_plugin_resource_directory.get_files_count()
@@ -50,7 +50,7 @@ typedef struct clap_plugin_resource_directory {
    // [main-thread]
    void(CLAP_ABI *set_directory)(const clap_plugin_t *plugin, const char *path, bool is_shared);
 
-   // Asks the plugin to put its resources into the resources directory.
+   // Asks the plugin to put its resources into the resource directory.
    // It is not necessary to collect files which belongs to the plugin's
    // factory content unless the param all is true.
    // [main-thread]
@@ -60,7 +60,7 @@ typedef struct clap_plugin_resource_directory {
    // [main-thread]
    uint32_t(CLAP_ABI *get_files_count)(const clap_plugin_t *plugin);
 
-   // Retrieves relative file path to the resources directory.
+   // Retrieves relative file path to the resource directory.
    // @param path writable memory to store the path
    // @param path_size number of available bytes in path
    // Returns the number of bytes in the path, or -1 on error

include/clap/ext/draft/surround.h

@@ -24,7 +24,7 @@
 // 3. host calls clap_plugin_surround->get_channel_map()
 // 4. host activates the plugin and can start processing audio
 
-static CLAP_CONSTEXPR const char CLAP_EXT_SURROUND[] = "clap.surround.draft/2";
+static CLAP_CONSTEXPR const char CLAP_EXT_SURROUND[] = "clap.surround.draft/3";
 
 static CLAP_CONSTEXPR const char CLAP_PORT_SURROUND[] = "surround";
 
@@ -54,14 +54,13 @@ enum {
 };
 
 typedef struct clap_plugin_surround {
-   // Stores into the channel_map array, the surround identifer of each channels.
+   // Stores into the channel_map array, the surround identifier of each channel.
    // Returns the number of elements stored in channel_map.
    //
    // config_id: the configuration id, see clap_plugin_audio_ports_config.
    // If config_id is CLAP_INVALID_ID, then this function queries the current port info.
    // [main-thread]
    uint32_t(CLAP_ABI *get_channel_map)(const clap_plugin_t *plugin,
-                                       clap_id              config_id,
                                        bool                 is_input,
                                        uint32_t             port_index,
                                        uint8_t             *channel_map,
@@ -77,13 +76,6 @@ typedef struct clap_host_surround {
    // The channel map can only change when the plugin is de-activated.
    // [main-thread]
    void(CLAP_ABI *changed)(const clap_host_t *host);
-
-   // Ask the host what is the prefered/project surround channel map.
-   // [main-thread]
-   void(CLAP_ABI *get_preferred_channel_map)(const clap_host_t *host,
-                                             uint8_t           *channel_map,
-                                             uint32_t           channel_map_capacity,
-                                             uint32_t          *channel_count);
 } clap_host_surround_t;
 
 #ifdef __cplusplus

include/clap/ext/draft/track-info.h

@@ -4,9 +4,9 @@
 #include "../../color.h"
 #include "../../string-sizes.h"
 
-// This extensions let the plugin query info about the track it's in.
+// This extension let the plugin query info about the track it's in.
 // It is useful when the plugin is created, to initialize some parameters (mix, dry, wet)
-// and pick a suitable configuartion regarding audio port type and channel count.
+// and pick a suitable configuration regarding audio port type and channel count.
 
 static CLAP_CONSTEXPR const char CLAP_EXT_TRACK_INFO[] = "clap.track-info.draft/1";
 
@@ -38,7 +38,7 @@ typedef struct clap_track_info {
    // track color, available if flags contain CLAP_TRACK_INFO_HAS_TRACK_COLOR
    clap_color_t color;
 
-   // availabe if flags contain CLAP_TRACK_INFO_HAS_AUDIO_CHANNEL
+   // available if flags contain CLAP_TRACK_INFO_HAS_AUDIO_CHANNEL
    // see audio-ports.h, struct clap_audio_port_info to learn how to use channel count and port type
    int32_t     audio_channel_count;
    const char *audio_port_type;

include/clap/ext/draft/tuning.h

@@ -39,9 +39,9 @@ typedef struct clap_host_tuning {
    // The plugin may query the tuning at a rate that makes sense for *low* frequency modulations.
    //
    // If the tuning_id is not found or equals to CLAP_INVALID_ID,
-   // then the function shall gracefuly return a sensible value.
+   // then the function shall gracefully return a sensible value.
    //
-   // sample_offset is the sample offset from the begining of the current process block.
+   // sample_offset is the sample offset from the beginning of the current process block.
    //
    // should_play(...) should be checked before calling this function.
    //