Merge pull request #270 from free-audio/next

1.1.7

CMakeLists.txt

@@ -72,7 +72,11 @@ if (${CLAP_BUILD_TESTS})
     clap_compile_cpp(c11    c 11 11)
     clap_compile_cpp(cpp11 cc 11 11)
     clap_compile_cpp(cpp14 cc 11 14)
-    clap_compile_cpp(c17    c 17 17)
+    if(${CMAKE_VERSION} VERSION_LESS "3.21")
+       message(STATUS "Skipping C17 tests due to older CMAKE_VERSION ${CMAKE_VERSION}")
+    else()
+      clap_compile_cpp(c17    c 17 17)
+    endif()
     clap_compile_cpp(cpp17 cc 17 17)
     clap_compile_cpp(cpp20 cc 17 20)
 

ChangeLog.md

@@ -1,3 +1,24 @@
+# Changes in 1.1.7
+
+* Add a [factory](include/clap/factory) folder for better organization and move our factories there
+* [params.h](include/clap/ext/params.h): fix typos
+* CMake: disable C17 targets for CMake < 3.21
+* [plugin-features.h](include/clap/plugin-features.h): adds `note-detector` category for plugins which converts audio to notes
+
+## Draft extensions
+
+* [context-menu.h](include/clap/ext/draft/context-menu.h): add "title" menu entry
+* [preset-load.h](include/clap/ext/draft/preset-load.h): load from URI instead of path, making the extension more powerful
+* [remote-controls.h](include/clap/ext/draft/remote-controls.h): distinguish between device pages and preset pages
+* [audio-ports-activation.h](include/clap/ext/draft/audio-ports-activation.h): `set_active()` now returns bool instead of void, this helps catching problems earlier especially with invalid arguments
+* [audio-ports-config.h](include/clap/ext/audio-ports-config.h): add new draft extension: `clap_plugin_audio_ports_config_info` which lets the host query detailed port information in a given configuration.
+* [surround.h](include/clap/ext/draft/surround.h): add `config_id` parameter when fetching port info
+* [ambisonic.h](include/clap/ext/draft/ambisonic.h): add `config_id` parameter when fetching port info
+
+## Draft factories
+
+* [preset-discovery.h](include/clap/factory/draft/preset-discovery.h): new factory which allows the host to index the plugin presets which are stored on disk.
+
 # Changes in 1.1.6
 
 * [version.h](include/clap/version.h) `CLAP_VERSION_LT` was backwards (comparing current with arg

README.md

@@ -37,7 +37,7 @@ The entry point is declared in [entry.h](include/clap/entry.h).
 
 ## Extensions
 
-Most features comes from extensions, which are in fact C interfaces.
+Most features come from extensions, which are in fact C interfaces.
 ```C
 // host extension
 const clap_host_log *log = host->extension(host, CLAP_EXT_LOG);

include/clap/clap.h

@@ -26,11 +26,13 @@
 #pragma once
 
 #include "entry.h"
-#include "plugin-factory.h"
-#include "plugin-invalidation.h"
-#include "plugin-features.h"
+
+#include "factory/plugin-factory.h"
+#include "factory/draft/plugin-invalidation.h"
+#include "factory/draft/preset-discovery.h"
 
 #include "plugin.h"
+#include "plugin-features.h"
 #include "host.h"
 
 #include "ext/audio-ports-config.h"

include/clap/entry.h

@@ -53,7 +53,7 @@ typedef struct clap_plugin_entry {
    // No more calls into the DSO must be made after calling deinit().
    void(CLAP_ABI *deinit)(void);
 
-   // Get the pointer to a factory. See plugin-factory.h for an example.
+   // Get the pointer to a factory. See factory/plugin-factory.h for an example.
    //
    // Returns null if the factory is not provided.
    // The returned pointer must *not* be freed by the caller.

include/clap/events.h

@@ -83,14 +83,14 @@ enum {
    //    Plugin->Host NoteEnd(port:0, channel:0, key:16, time:ignored)
    //
    // These four events use clap_event_note.
-   CLAP_EVENT_NOTE_ON,
-   CLAP_EVENT_NOTE_OFF,
-   CLAP_EVENT_NOTE_CHOKE,
-   CLAP_EVENT_NOTE_END,
+   CLAP_EVENT_NOTE_ON = 0,
+   CLAP_EVENT_NOTE_OFF = 1,
+   CLAP_EVENT_NOTE_CHOKE = 2,
+   CLAP_EVENT_NOTE_END = 3,
 
    // Represents a note expression.
    // Uses clap_event_note_expression.
-   CLAP_EVENT_NOTE_EXPRESSION,
+   CLAP_EVENT_NOTE_EXPRESSION = 4,
 
    // PARAM_VALUE sets the parameter's value; uses clap_event_param_value.
    // PARAM_MOD sets the parameter's modulation amount; uses clap_event_param_mod.
@@ -100,20 +100,20 @@ enum {
    // In case of a concurrent global value/modulation versus a polyphonic one,
    // the voice should only use the polyphonic one and the polyphonic modulation
    // amount will already include the monophonic signal.
-   CLAP_EVENT_PARAM_VALUE,
-   CLAP_EVENT_PARAM_MOD,
+   CLAP_EVENT_PARAM_VALUE = 5,
+   CLAP_EVENT_PARAM_MOD = 6,
 
    // Indicates that the user started or finished adjusting a knob.
    // This is not mandatory to wrap parameter changes with gesture events, but this improves
    // the user experience a lot when recording automation or overriding automation playback.
    // Uses clap_event_param_gesture.
-   CLAP_EVENT_PARAM_GESTURE_BEGIN,
-   CLAP_EVENT_PARAM_GESTURE_END,
+   CLAP_EVENT_PARAM_GESTURE_BEGIN = 7,
+   CLAP_EVENT_PARAM_GESTURE_END = 8,
 
-   CLAP_EVENT_TRANSPORT,  // update the transport info; clap_event_transport
-   CLAP_EVENT_MIDI,       // raw midi event; clap_event_midi
-   CLAP_EVENT_MIDI_SYSEX, // raw midi sysex event; clap_event_midi_sysex
-   CLAP_EVENT_MIDI2,      // raw midi 2 event; clap_event_midi2
+   CLAP_EVENT_TRANSPORT = 9,   // update the transport info; clap_event_transport
+   CLAP_EVENT_MIDI = 10,       // raw midi event; clap_event_midi
+   CLAP_EVENT_MIDI_SYSEX = 11, // raw midi sysex event; clap_event_midi_sysex
+   CLAP_EVENT_MIDI2 = 12,      // raw midi 2 event; clap_event_midi2
 };
 
 // Note on, off, end and choke events.
@@ -132,19 +132,19 @@ typedef struct clap_event_note {
 
 enum {
    // with 0 < x <= 4, plain = 20 * log(x)
-   CLAP_NOTE_EXPRESSION_VOLUME,
+   CLAP_NOTE_EXPRESSION_VOLUME = 0,
 
    // pan, 0 left, 0.5 center, 1 right
-   CLAP_NOTE_EXPRESSION_PAN,
+   CLAP_NOTE_EXPRESSION_PAN = 1,
 
    // relative tuning in semitone, from -120 to +120
-   CLAP_NOTE_EXPRESSION_TUNING,
+   CLAP_NOTE_EXPRESSION_TUNING = 2,
 
    // 0..1
-   CLAP_NOTE_EXPRESSION_VIBRATO,
-   CLAP_NOTE_EXPRESSION_EXPRESSION,
-   CLAP_NOTE_EXPRESSION_BRIGHTNESS,
-   CLAP_NOTE_EXPRESSION_PRESSURE,
+   CLAP_NOTE_EXPRESSION_VIBRATO = 3,
+   CLAP_NOTE_EXPRESSION_EXPRESSION = 4,
+   CLAP_NOTE_EXPRESSION_BRIGHTNESS = 5,
+   CLAP_NOTE_EXPRESSION_PRESSURE = 6,
 };
 typedef int32_t clap_note_expression;
 

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

@@ -2,6 +2,7 @@
 
 #include "../string-sizes.h"
 #include "../plugin.h"
+#include "audio-ports.h"
 
 /// @page Audio Ports Config
 ///
@@ -20,8 +21,13 @@
 ///
 /// Plugins with very complex configuration possibilities should let the user configure the ports
 /// from the plugin GUI, and call @ref clap_host_audio_ports.rescan(CLAP_AUDIO_PORTS_RESCAN_ALL).
+///
+/// To inquire the exact bus layout, the plugin implements the clap_plugin_audio_ports_config_info_t
+/// extension where all busses can be retrieved in the same way as in the audio-port extension.
 
 static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_CONFIG[] = "clap.audio-ports-config";
+static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_CONFIG_INFO[] =
+   "clap.audio-ports-config-info/draft-0";
 
 #ifdef __cplusplus
 extern "C" {
@@ -65,6 +71,25 @@ typedef struct clap_plugin_audio_ports_config {
    bool(CLAP_ABI *select)(const clap_plugin_t *plugin, clap_id config_id);
 } clap_plugin_audio_ports_config_t;
 
+// Extended config info
+typedef struct clap_plugin_audio_ports_config_info {
+
+   // Gets the id of the currently selected config, or CLAP_INVALID_ID if the current port
+   // layout isn't part of the config list.
+   //
+   // [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.
+   // This is analogous to clap_plugin_audio_ports.get().
+   // [main-thread]
+   bool(CLAP_ABI *get)(const clap_plugin_t    *plugin,
+                       clap_id                 config_id,
+                       uint32_t                port_index,
+                       bool                    is_input,
+                       clap_audio_port_info_t *info);
+} clap_plugin_audio_ports_config_info_t;
+
 typedef struct clap_host_audio_ports_config {
    // Rescan the full list of configs.
    // [main-thread]

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/0";
+static CLAP_CONSTEXPR const char CLAP_EXT_AMBISONIC[] = "clap.ambisonic.draft/1";
 
 static CLAP_CONSTEXPR const char CLAP_PORT_AMBISONIC[] = "ambisonic";
 
@@ -35,8 +35,12 @@ typedef struct clap_ambisonic_info {
 
 typedef struct clap_plugin_ambisonic {
    // Returns true on success
+   //
+   // 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]
    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/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-0";
+   "clap.audio-ports-activation/draft-1";
 
 #ifdef __cplusplus
 extern "C" {
@@ -42,8 +42,9 @@ 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.
    //
+   // returns false if failed, or invalid parameters
    // [active ? audio-thread : main-thread]
-   void(CLAP_ABI *set_active)(const clap_plugin_t *plugin,
+   bool(CLAP_ABI *set_active)(const clap_plugin_t *plugin,
                               bool                 is_input,
                               uint32_t             port_index,
                               bool                 is_active);

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

@@ -44,6 +44,10 @@ enum {
    // Ends the current sub menu.
    // data: NULL
    CLAP_CONTEXT_MENU_ITEM_END_SUBMENU,
+
+   // Adds a title entry
+   // data: const clap_context_menu_item_title_t *
+   CLAP_CONTEXT_MENU_ITEM_TITLE,
 };
 typedef uint32_t clap_context_menu_item_kind_t;
 
@@ -68,6 +72,14 @@ typedef struct clap_context_menu_check_entry {
    clap_id     action_id;
 } clap_context_menu_check_entry_t;
 
+typedef struct clap_context_menu_item_title {
+   // text to be displayed
+   const char *title;
+
+   // if false, then the menu entry is greyed out
+   bool        is_enabled;
+} clap_context_menu_item_title_t;
+
 typedef struct clap_context_menu_submenu {
    // text to be displayed
    const char *label;

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

@@ -2,18 +2,43 @@
 
 #include "../../plugin.h"
 
-static const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load.draft/0";
+static const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load.draft/1";
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 typedef struct clap_plugin_preset_load {
-   // Loads a preset in the plugin native preset file format from a path.
+   // 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.
+   //
    // [main-thread]
-   bool(CLAP_ABI *from_file)(const clap_plugin_t *plugin, const char *path);
+   bool(CLAP_ABI *from_uri)(const clap_plugin_t *plugin, const char *uri, const char *load_key);
 } clap_plugin_preset_load_t;
 
+typedef struct clap_host_preset_load {
+   // Called if clap_plugin_preset_load.load() failed.
+   // os_error: the operating system error, if applicable. If not applicable set it to a non-error
+   // value, eg: 0 on unix and Windows.
+   //
+   // [main-thread]
+   void(CLAP_ABI *on_error)(const clap_host_t *host,
+                            const char        *uri,
+                            int32_t            os_error,
+                            const char        *msg);
+
+   // Informs the host that the following preset has been loaded.
+   // This contributes to keep in sync the host preset browser and plugin preset browser.
+   // If the preset was loaded from a container file, then the load_key must be set, otherwise it
+   // must be null.
+   //
+   // [main-thread]
+   void(CLAP_ABI *loaded)(const clap_host_t *host, const char *uri, const char *load_key);
+} clap_host_preset_load_t;
+
 #ifdef __cplusplus
 }
 #endif

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

@@ -31,7 +31,7 @@
 // Pressing that button once gets you to the first page of the section.
 // Press it again to cycle through the section's pages.
 
-static CLAP_CONSTEXPR const char CLAP_EXT_REMOTE_CONTROLS[] = "clap.remote-controls.draft/1";
+static CLAP_CONSTEXPR const char CLAP_EXT_REMOTE_CONTROLS[] = "clap.remote-controls.draft/2";
 
 #ifdef __cplusplus
 extern "C" {
@@ -44,6 +44,10 @@ typedef struct clap_remote_controls_page {
    clap_id page_id;
    char    page_name[CLAP_NAME_SIZE];
    clap_id param_ids[CLAP_REMOTE_CONTROLS_COUNT];
+
+   // This is used to separate device pages versus preset pages.
+   // If true, then this page is specific to this preset.
+   bool is_for_preset;
 } clap_remote_controls_page_t;
 
 typedef struct clap_plugin_remote_controls {

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/1";
+static CLAP_CONSTEXPR const char CLAP_EXT_SURROUND[] = "clap.surround.draft/2";
 
 static CLAP_CONSTEXPR const char CLAP_PORT_SURROUND[] = "surround";
 
@@ -55,9 +55,13 @@ enum {
 
 typedef struct clap_plugin_surround {
    // Stores into the channel_map array, the surround identifer of each channels.
-   // Returns the number of elements stored in channel_map
+   // 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,

include/clap/ext/params.h

@@ -46,7 +46,7 @@
 ///   (latency, audio ports, new parameters, ...) be sure to wait for the host
 ///   to deactivate the plugin to apply those changes.
 ///   If there are no breaking changes, the plugin can apply them them right away.
-///   The plugin is resonsible for updating both its audio processor and its gui.
+///   The plugin is responsible for updating both its audio processor and its gui.
 ///
 /// II. Turning a knob on the DAW interface
 /// - the host will send an automation event to the plugin via a process() or flush()
@@ -63,8 +63,8 @@
 /// - the plugin is responsible for updating its GUI
 ///
 /// V. Turning a knob via plugin's internal MIDI mapping
-/// - the plugin sends a CLAP_EVENT_PARAM_SET output event, set should_record to false
-/// - the plugin is responsible to update its GUI
+/// - the plugin sends a CLAP_EVENT_PARAM_VALUE output event, set should_record to false
+/// - the plugin is responsible for updating its GUI
 ///
 /// VI. Adding or removing parameters
 /// - if the plugin is activated call clap_host->restart()