From d5a81b9facbfc7bd80ac85c9c1178de1a8a4f869 Mon Sep 17 00:00:00 2001 From: Adrien Prokopowicz Date: Tue, 28 Nov 2023 05:27:05 +0100 Subject: [PATCH 01/85] Clarify the allowed usages of clap_plugin_entry's init() and deinit() --- include/clap/entry.h | 44 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 36 insertions(+), 8 deletions(-) diff --git a/include/clap/entry.h b/include/clap/entry.h index c1f9d9c3..19cdea8a 100644 --- a/include/clap/entry.h +++ b/include/clap/entry.h @@ -30,35 +30,63 @@ extern "C" { // // Each directory should be recursively searched for files and/or bundles as appropriate in your OS // ending with the extension `.clap`. -// -// Every method must be thread-safe. typedef struct clap_plugin_entry { clap_version_t clap_version; // initialized to CLAP_VERSION - // This function must be called first, and can only be called once. + // Initializes the DSO. + // + // This function must be called first, before any-other CLAP-related function or symbol from this + // DSO. + // + // It also must only be called once, until a later call to deinit() is made, after which init() + // can be called once more to re-initialize the DSO. + // This enables hosts to e.g. quickly load and unload a DSO for scanning its plugins, and then + // load it again later to actually use the plugins if needed. // // It should be as fast as possible, in order to perform a very quick scan of the plugin // descriptors. // - // It is forbidden to display graphical user interface in this call. - // It is forbidden to perform user interaction in this call. + // It is forbidden to display graphical user interfaces in this call. + // It is forbidden to perform any user interaction in this call. // // If the initialization depends upon expensive computation, maybe try to do them ahead of time // and cache the result. // - // If init() returns false, then the host must not call deinit() nor any other clap - // related symbols from the DSO. + // Returns true on success. If init() returns false, then the DSO must be considered + // uninitialized, and the host must not call deinit() nor any other CLAP-related symbols from the + // DSO. // // plugin_path is the path to the DSO (Linux, Windows), or the bundle (macOS). + // + // This function may be called on any thread, including a different one from the one a later call + // to deinit() (or a later init()) can be made. + // However, it is forbidden to call this function simultaneously from multiple threads. + // It is also forbidden to call it simultaneously with *any* other CLAP-related symbols from the + // DSO, including (but not limited to) deinit(). bool(CLAP_ABI *init)(const char *plugin_path); - // No more calls into the DSO must be made after calling deinit(). + // De-initializes the DSO, freeing any resources allocated or initialized by init(). + // + // After this function is called, no more calls into the DSO must be made, except calling init() + // again to re-initialize the DSO. + // This means that after deinit() is called, the DSO can be considered to be in the same state + // as if init() was never called at all yet, enabling it to be re-initialized as needed. + // + // Just like init(), this function may be called on any thread, including a different one from + // the one init() was called from, or from the one a later init() call can be made. + // However, it is forbidden to call this function simultaneously from multiple threads. + // It is also forbidden to call it simultaneously with *any* other CLAP-related symbols from the + // DSO, including (but not limited to) deinit(). void(CLAP_ABI *deinit)(void); // 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. + // + // Unlike init() and deinit(), this function can be called simultaneously by multiple threads. + // + // [thread-safe] const void *(CLAP_ABI *get_factory)(const char *factory_id); } clap_plugin_entry_t; From 2b5f760ccd3f654d8d1637f348122a7ffbdd0507 Mon Sep 17 00:00:00 2001 From: Adrien Prokopowicz Date: Tue, 28 Nov 2023 21:08:58 +0100 Subject: [PATCH 02/85] Require plugins to support clap_plugin_entry's init() and deinit() being called multiple times --- include/clap/entry.h | 47 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/include/clap/entry.h b/include/clap/entry.h index 19cdea8a..877dc941 100644 --- a/include/clap/entry.h +++ b/include/clap/entry.h @@ -30,6 +30,43 @@ extern "C" { // // Each directory should be recursively searched for files and/or bundles as appropriate in your OS // ending with the extension `.clap`. +// +// As detailed in the respective functions' documentations below, the host is forbidden from calling +// either init() or deinit() multiple times, without calling the other first. This is to enforce +// a "normal" initialization pattern, where one can't construct or destroy an object multiple times. +// +// However, there are a few cases where the host may not be able to reliably prevent this from +// happening, such as when multiple, separate hosts co-exist within the same address space (e.g. +// Meta-Plugins, plugins that can host other plugins inside them). It may also happen when a VST +// compatibility layer is used to wrap a CLAP plugin, for instance. +// +// In those cases, the init() and deinit() pair of functions can happen to be called multiple times, +// either in a row or even simultaneously, from different threads, by multiple non-synchronized +// hosts, or by a single host that is presented multiple interfaces to a same DSO. This can happen +// even though this is forbidden behavior from the host by this specification, and despite a +// compliant host's best efforts. +// +// Despite those issues, hosts *must* ensure that each successful call to init() is only followed by +// a single call to deinit() at most. As long as a single successful init() call did not have its +// matching deinit() called, the DSO *must* remain in a fully operational state, as if deinit() had +// not yet been called. +// +// Therefore, init() and deinit() functions *should* be implemented in a way that allows for init() +// to be called any number of times in a row (possibly simultaneously, from multiple threads), and +// for deinit() to be called at most that same number of times (also simultaneously, from multiple, +// possibly different threads from the init() called). As of CLAP 1.11, this *must* be the case for +// all plugin implementations. +// +// This is already trivially the case if there is no (de)initialization work in the entry at all, +// or if the initialization work is thread safe and idempotent, and there is no de-initialization +// work to be done. Those implementations already are and remain valid, and require no additional +// consideration. +// +// If that is not the case, then using a global, refcount-like locked initialization counter can be +// used to keep track of init() and deinit() calls. Then the initialization work can be done only +// when the counter goes from 0 to 1 in init(), and de-initialization can be done when the counter +// goes to 0 in deinit(). Any subsequent calls to init() and deinit() can just increase or decrease +// the counter, respectively. typedef struct clap_plugin_entry { clap_version_t clap_version; // initialized to CLAP_VERSION @@ -43,6 +80,10 @@ typedef struct clap_plugin_entry { // This enables hosts to e.g. quickly load and unload a DSO for scanning its plugins, and then // load it again later to actually use the plugins if needed. // + // As stated above, even though hosts are forbidden to do so directly, multiple calls before any + // deinit() call may still happen. Implementations *should* take this into account, and *must* + // do so as of CLAP 1.11. + // // It should be as fast as possible, in order to perform a very quick scan of the plugin // descriptors. // @@ -55,6 +96,8 @@ typedef struct clap_plugin_entry { // Returns true on success. If init() returns false, then the DSO must be considered // uninitialized, and the host must not call deinit() nor any other CLAP-related symbols from the // DSO. + // This function also returns true in the case where the DSO is already initialized, and no + // actual initialization work is done in this call, as explain above. // // plugin_path is the path to the DSO (Linux, Windows), or the bundle (macOS). // @@ -72,6 +115,10 @@ typedef struct clap_plugin_entry { // This means that after deinit() is called, the DSO can be considered to be in the same state // as if init() was never called at all yet, enabling it to be re-initialized as needed. // + // As stated above, even though hosts are forbidden to do so directly, multiple calls before any + // new init() call may still happen. Implementations *should* take this into account, and *must* + // do so as of CLAP 1.11. + // // Just like init(), this function may be called on any thread, including a different one from // the one init() was called from, or from the one a later init() call can be made. // However, it is forbidden to call this function simultaneously from multiple threads. From b8c2e1daea8d6a029a458c3ab18a4af76672c950 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Thu, 30 Nov 2023 12:23:05 +0100 Subject: [PATCH 03/85] require the plugin to be activated to get the latency --- ChangeLog.md | 4 ++++ include/clap/ext/latency.h | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/ChangeLog.md b/ChangeLog.md index f3f3a81c..293ab144 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,3 +1,7 @@ +# Changes in 1.1.11 + +* [latency.h](include/clap/ext/latency.h): require the plugin to be activated to get the latency + # Changes in 1.1.10 * [params.h](include/clap/ext/params.h): add `CLAP_PARAM_IS_ENUM` flag. diff --git a/include/clap/ext/latency.h b/include/clap/ext/latency.h index 862b3341..b66dd8f7 100644 --- a/include/clap/ext/latency.h +++ b/include/clap/ext/latency.h @@ -11,7 +11,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 in samples. - // [main-thread] + // [main-thread & active] uint32_t(CLAP_ABI *get)(const clap_plugin_t *plugin); } clap_plugin_latency_t; From 9a6e997bcaf97936193900c2aa46d4818d4462e0 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Thu, 30 Nov 2023 12:54:43 +0100 Subject: [PATCH 04/85] Implement entry init counter for the plugin template --- ChangeLog.md | 1 + src/plugin-template.c | 60 ++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 57 insertions(+), 4 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 293ab144..d924bd9e 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,6 +1,7 @@ # Changes in 1.1.11 * [latency.h](include/clap/ext/latency.h): require the plugin to be activated to get the latency +* [plugin-template.c](src/plugin-template.c): implement thread-safe entry init counter # Changes in 1.1.10 diff --git a/src/plugin-template.c b/src/plugin-template.c index 97f4b1ff..679e8b92 100644 --- a/src/plugin-template.c +++ b/src/plugin-template.c @@ -6,6 +6,8 @@ #include #include #include +#include +#include #include @@ -357,15 +359,65 @@ static const clap_plugin_factory_t s_plugin_factory = { //////////////// static bool entry_init(const char *plugin_path) { - // called only once, and very first + // perform the plugin initialization return true; } static void entry_deinit(void) { - // called before unloading the DSO + // perform the plugin de-initialization +} + +static mtx_t g_entry_lock; +static once_flag g_entry_once = ONCE_FLAG_INIT; +static int g_entry_init_counter = 0; + +// Initializes the necessary mutex for the entry guard +static void entry_init_guard_init(void) { + mtx_init(&g_entry_lock, mtx_plain); +} + +// Thread safe init counter +static bool entry_init_guard(const char *plugin_path) { + call_once(&g_entry_once, entry_init_guard_init); + + mtx_lock(&g_entry_lock); + const int cnt = ++g_entry_init_counter; + assert(cnt > 0); + + bool succeed = true; + if (cnt == 1) { + succeed = entry_init(plugin_path); + if (!succeed) + g_entry_init_counter = 0; + } + + mtx_unlock(&g_entry_lock); + + return succeed; +} + +// Thread safe deinit counter +static void entry_deinit_guard(void) { + call_once(&g_entry_once, entry_init_guard_init); + + mtx_lock(&g_entry_lock); + const int cnt = --g_entry_init_counter; + assert(cnt > 0); + + bool succeed = true; + if (cnt == 0) + entry_deinit(); + + mtx_unlock(&g_entry_lock); } static const void *entry_get_factory(const char *factory_id) { + call_once(&g_entry_once, entry_init_guard_init); + + assert(g_entry_init_counter > 0); + if (g_entry_init_counter <= 0) + return NULL; + if (!strcmp(factory_id, CLAP_PLUGIN_FACTORY_ID)) return &s_plugin_factory; return NULL; @@ -374,7 +426,7 @@ static const void *entry_get_factory(const char *factory_id) { // This symbol will be resolved by the host CLAP_EXPORT const clap_plugin_entry_t clap_entry = { .clap_version = CLAP_VERSION_INIT, - .init = entry_init, - .deinit = entry_deinit, + .init = entry_init_guard, + .deinit = entry_deinit_guard, .get_factory = entry_get_factory, }; From 0eb701a9f2b15ddc9eab7866bc07e65ac5ae1fcf Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Thu, 30 Nov 2023 13:36:47 +0100 Subject: [PATCH 05/85] Add some preprocessor checks before using threads.h --- src/plugin-template.c | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/src/plugin-template.c b/src/plugin-template.c index 679e8b92..b04f18a4 100644 --- a/src/plugin-template.c +++ b/src/plugin-template.c @@ -6,9 +6,13 @@ #include #include #include -#include #include +#if __STDC_VERSION__ >= 201112L && !defined(__STDC_NO_THREADS__) +# define CLAP_HAS_THREAD +# include +#endif + #include static const clap_plugin_descriptor_t s_my_plug_desc = { @@ -367,20 +371,28 @@ static void entry_deinit(void) { // perform the plugin de-initialization } +#ifdef CLAP_HAS_THREAD static mtx_t g_entry_lock; static once_flag g_entry_once = ONCE_FLAG_INIT; +#endif + static int g_entry_init_counter = 0; +#ifdef CLAP_HAS_THREAD // Initializes the necessary mutex for the entry guard static void entry_init_guard_init(void) { mtx_init(&g_entry_lock, mtx_plain); } +#endif // Thread safe init counter static bool entry_init_guard(const char *plugin_path) { +#ifdef CLAP_HAS_THREAD call_once(&g_entry_once, entry_init_guard_init); mtx_lock(&g_entry_lock); +#endif + const int cnt = ++g_entry_init_counter; assert(cnt > 0); @@ -391,16 +403,21 @@ static bool entry_init_guard(const char *plugin_path) { g_entry_init_counter = 0; } +#ifdef CLAP_HAS_THREAD mtx_unlock(&g_entry_lock); +#endif return succeed; } // Thread safe deinit counter static void entry_deinit_guard(void) { +#ifdef CLAP_HAS_THREAD call_once(&g_entry_once, entry_init_guard_init); mtx_lock(&g_entry_lock); +#endif + const int cnt = --g_entry_init_counter; assert(cnt > 0); @@ -408,11 +425,15 @@ static void entry_deinit_guard(void) { if (cnt == 0) entry_deinit(); +#ifdef CLAP_HAS_THREAD mtx_unlock(&g_entry_lock); +#endif } static const void *entry_get_factory(const char *factory_id) { +#ifdef CLAP_HAS_THREAD call_once(&g_entry_once, entry_init_guard_init); +#endif assert(g_entry_init_counter > 0); if (g_entry_init_counter <= 0) From 4e57e1f4c07500f40cb5c146b75987382884fc8d Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Thu, 30 Nov 2023 14:15:58 +0100 Subject: [PATCH 06/85] msvc still doesn't know thread.h??? --- src/plugin-template.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/plugin-template.c b/src/plugin-template.c index b04f18a4..de9620b2 100644 --- a/src/plugin-template.c +++ b/src/plugin-template.c @@ -8,7 +8,7 @@ #include #include -#if __STDC_VERSION__ >= 201112L && !defined(__STDC_NO_THREADS__) +#if __STDC_VERSION__ >= 201112L && !defined(__STDC_NO_THREADS__) && !defined(_MSC_VER) # define CLAP_HAS_THREAD # include #endif From 1e09a9944b31e4a59202cb24aac812c9a751f7d2 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Thu, 30 Nov 2023 14:37:30 +0100 Subject: [PATCH 07/85] Let cmake find out if threads.h is available --- CMakeLists.txt | 7 +++++++ src/plugin-template.c | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 8773c35f..3581cdde 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -50,6 +50,7 @@ add_custom_target(clap-tests) if (${CLAP_BUILD_TESTS}) message(STATUS "Including CLAP tests, compile tests, and versions") + include(CheckIncludeFile) macro(clap_compile_cpp SUFFIX EXT STDC STDCPP) add_executable(clap-compile-${SUFFIX} EXCLUDE_FROM_ALL src/main.${EXT}) @@ -84,11 +85,17 @@ if (${CLAP_BUILD_TESTS}) clap_compile_cpp(cpp17 cc 17 17) clap_compile_cpp(cpp20 cc 17 20) + check_include_file(threads.h CLAP_HAS_THREADS_H) + add_library(clap-plugin-template MODULE EXCLUDE_FROM_ALL src/plugin-template.c) target_link_libraries(clap-plugin-template PRIVATE clap) set_target_properties(clap-plugin-template PROPERTIES C_STANDARD 11) add_dependencies(clap-tests clap-plugin-template) + if(CLAP_HAS_THREADS_H) + target_compile_definitions(clap-plugin-template PRIVATE CLAP_HAS_THREADS_H) + endif() + if(CMAKE_SYSTEM_NAME STREQUAL "Linux") target_link_libraries(clap-plugin-template PRIVATE -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/src/linux-my_plug.version) target_link_libraries(clap-plugin-template PRIVATE -Wl,-z,defs) diff --git a/src/plugin-template.c b/src/plugin-template.c index de9620b2..8436815c 100644 --- a/src/plugin-template.c +++ b/src/plugin-template.c @@ -8,7 +8,7 @@ #include #include -#if __STDC_VERSION__ >= 201112L && !defined(__STDC_NO_THREADS__) && !defined(_MSC_VER) +#if __STDC_VERSION__ >= 201112L && !defined (__STDC_NO_THREADS__) && defined (CLAP_HAS_THREADS_H) # define CLAP_HAS_THREAD # include #endif From 80ed37b9b1671d55c75d04dd5e6d11ba8a57c472 Mon Sep 17 00:00:00 2001 From: trinitou Date: Tue, 5 Dec 2023 14:28:26 +0100 Subject: [PATCH 08/85] Clean up active and processing state method labels in plugin.h --- include/clap/plugin.h | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/include/clap/plugin.h b/include/clap/plugin.h index 97ead816..7c379d40 100644 --- a/include/clap/plugin.h +++ b/include/clap/plugin.h @@ -60,21 +60,21 @@ typedef struct clap_plugin { // 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] + // [main-thread & !active] bool(CLAP_ABI *activate)(const struct clap_plugin *plugin, double sample_rate, uint32_t min_frames_count, uint32_t max_frames_count); - // [main-thread & active_state] + // [main-thread & active] void(CLAP_ABI *deactivate)(const struct clap_plugin *plugin); // Call start processing before processing. // Returns true on success. - // [audio-thread & active_state & !processing_state] + // [audio-thread & active & !processing] bool(CLAP_ABI *start_processing)(const struct clap_plugin *plugin); // Call stop processing before sending the plugin to sleep. - // [audio-thread & active_state & processing_state] + // [audio-thread & active & processing] void(CLAP_ABI *stop_processing)(const struct clap_plugin *plugin); // - Clears all buffers, performs a full reset of the processing state (filters, oscillators, @@ -82,13 +82,13 @@ typedef struct clap_plugin { // - The parameter's value remain unchanged. // - clap_process.steady_time may jump backward. // - // [audio-thread & active_state] + // [audio-thread & active] void(CLAP_ABI *reset)(const struct clap_plugin *plugin); // process audio, events, ... // All the pointers coming from clap_process_t and its nested attributes, // are valid until process() returns. - // [audio-thread & active_state & processing_state] + // [audio-thread & active & processing] clap_process_status(CLAP_ABI *process)(const struct clap_plugin *plugin, const clap_process_t *process); From 7300c18eb589de2a9e14a74b1b544da2b0715db1 Mon Sep 17 00:00:00 2001 From: era Date: Sun, 17 Dec 2023 19:56:29 -0500 Subject: [PATCH 09/85] Update referenced function name in comment --- include/clap/ext/params.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h index 2ec7e025..33602634 100644 --- a/include/clap/ext/params.h +++ b/include/clap/ext/params.h @@ -12,7 +12,7 @@ /// The plugin is responsible for keeping its audio processor and its GUI in sync. /// /// The host can at any time read parameters' value on the [main-thread] using -/// @ref clap_plugin_params.value(). +/// @ref clap_plugin_params.get_value(). /// /// There are two options to communicate parameter value changes, and they are not concurrent. /// - send automation points during clap_plugin.process() From 3b798541098bc7bca656caa2c74a1a24e8978eab Mon Sep 17 00:00:00 2001 From: Paul Walker Date: Mon, 18 Dec 2023 09:28:54 -0500 Subject: [PATCH 10/85] Expanded discussion of -1 wildcard note address mechanism Explaning how the wildcard voice lookup works --- include/clap/events.h | 39 +++++++++++++++++++++++++++++++++++---- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/include/clap/events.h b/include/clap/events.h index 3a587bec..a3099a72 100644 --- a/include/clap/events.h +++ b/include/clap/events.h @@ -117,9 +117,37 @@ enum { }; // Note on, off, end and choke events. +// +// Clap addresses notes and voices using the 4-value tuple +// (port, channel, key, note_id). note on/off/end/choke +// events and parameter modulation messages are delivered with +// these values populated. +// +// Values in a note and voice address are either >= 0 if they +// are specified, or -1 to indicated a wildcard. A wildcard +// means a voice with any value in that part of the tuple +// matches the message. +// +// For instance, a (PCKN) of (0, 3, -1, -1) will match all voices +// on channel 3 of port 0. And a PCKN of (-1, 0, 60, -1) will match +// all channel 0 key 60 voices, independent of port or note id. +// +// Especially in the case of note-on note-off pairs, and in the +// absence of voice stacking or polyphonic modulation, a host may +// choose to issue a note id only at note on. So you may see a +// message stream like +// +// CLAP_EVENT_NOTE_ON [0,0,60,184] +// CLAP_EVENT_NOTE_OFF [0,0,60,-1] +// +// and the host will expect the first voice to be released. +// Well constructed plugins will search for voices and notes using +// the entire tuple. +// // In the case of note choke or end events: // - the velocity is ignored. -// - key and channel are used to match active notes, a value of -1 matches all. +// - key and channel are used to match active notes +// - note_id is optionally provided by the host typedef struct clap_event_note { clap_event_header_t header; @@ -153,7 +181,8 @@ typedef struct clap_event_note_expression { clap_note_expression expression_id; - // target a specific note_id, port, key and channel, -1 for global + // target a specific note_id, port, key and channel, with + // -1 meaning wildcard, per the wildcard discussion above int32_t note_id; int16_t port_index; int16_t channel; @@ -169,7 +198,8 @@ typedef struct clap_event_param_value { clap_id param_id; // @ref clap_param_info.id void *cookie; // @ref clap_param_info.cookie - // target a specific note_id, port, key and channel, -1 for global + // target a specific note_id, port, key and channel, with + // -1 meaning wildcard, per the wildcard discussion above int32_t note_id; int16_t port_index; int16_t channel; @@ -185,7 +215,8 @@ typedef struct clap_event_param_mod { clap_id param_id; // @ref clap_param_info.id void *cookie; // @ref clap_param_info.cookie - // target a specific note_id, port, key and channel, -1 for global + // target a specific note_id, port, key and channel, with + // -1 meaning wildcard, per the wildcard discussion above int32_t note_id; int16_t port_index; int16_t channel; From 12c60948c98c5f4e88b1aab23cc58fc27d994d95 Mon Sep 17 00:00:00 2001 From: Paul Walker Date: Mon, 18 Dec 2023 10:22:44 -0500 Subject: [PATCH 11/85] Address review feedback --- include/clap/events.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/clap/events.h b/include/clap/events.h index a3099a72..f4ba5a8a 100644 --- a/include/clap/events.h +++ b/include/clap/events.h @@ -124,7 +124,7 @@ enum { // these values populated. // // Values in a note and voice address are either >= 0 if they -// are specified, or -1 to indicated a wildcard. A wildcard +// are specified, or -1 to indicate a wildcard. A wildcard // means a voice with any value in that part of the tuple // matches the message. // @@ -133,7 +133,7 @@ enum { // all channel 0 key 60 voices, independent of port or note id. // // Especially in the case of note-on note-off pairs, and in the -// absence of voice stacking or polyphonic modulation, a host may +// absence of voice stacking or polyphonic modulation, a host may // choose to issue a note id only at note on. So you may see a // message stream like // From 841527300b1e3a9fce48c29425c7c2da30777095 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 20 Dec 2023 11:18:55 +0100 Subject: [PATCH 12/85] Typo --- include/clap/events.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/events.h b/include/clap/events.h index f4ba5a8a..0839e961 100644 --- a/include/clap/events.h +++ b/include/clap/events.h @@ -119,7 +119,7 @@ enum { // Note on, off, end and choke events. // // Clap addresses notes and voices using the 4-value tuple -// (port, channel, key, note_id). note on/off/end/choke +// (port, channel, key, note_id). Note on/off/end/choke // events and parameter modulation messages are delivered with // these values populated. // From bd62a2949498805ea371f32364fcf9f6eda96769 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 20 Dec 2023 11:26:10 +0100 Subject: [PATCH 13/85] Move extensions out of draft --- include/clap/clap.h | 21 ++++++++++--------- .../ext/{draft => }/audio-ports-activation.h | 2 +- .../{draft => }/configurable-audio-ports.h | 2 +- include/clap/ext/{draft => }/context-menu.h | 2 +- .../clap/ext/{draft => }/param-indication.h | 4 ++-- include/clap/ext/{draft => }/preset-load.h | 2 +- .../clap/ext/{draft => }/remote-controls.h | 4 ++-- include/clap/ext/{draft => }/state-context.h | 4 ++-- include/clap/ext/{draft => }/surround.h | 2 +- include/clap/ext/{draft => }/track-info.h | 6 +++--- .../factory/{draft => }/preset-discovery.h | 6 +++--- 11 files changed, 28 insertions(+), 27 deletions(-) rename include/clap/ext/{draft => }/audio-ports-activation.h (98%) rename include/clap/ext/{draft => }/configurable-audio-ports.h (98%) rename include/clap/ext/{draft => }/context-menu.h (99%) rename include/clap/ext/{draft => }/param-indication.h (98%) rename include/clap/ext/{draft => }/preset-load.h (98%) rename include/clap/ext/{draft => }/remote-controls.h (97%) rename include/clap/ext/{draft => }/state-context.h (97%) rename include/clap/ext/{draft => }/surround.h (99%) rename include/clap/ext/{draft => }/track-info.h (95%) rename include/clap/factory/{draft => }/preset-discovery.h (99%) diff --git a/include/clap/clap.h b/include/clap/clap.h index e57dbf44..868188b3 100644 --- a/include/clap/clap.h +++ b/include/clap/clap.h @@ -28,44 +28,45 @@ #include "entry.h" #include "factory/plugin-factory.h" +#include "factory/preset-discovery.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-activation.h" #include "ext/audio-ports-config.h" #include "ext/audio-ports.h" +#include "ext/configurable-audio-ports.h" +#include "ext/context-menu.h" #include "ext/event-registry.h" #include "ext/gui.h" #include "ext/latency.h" #include "ext/log.h" #include "ext/note-name.h" #include "ext/note-ports.h" +#include "ext/param-indication.h" #include "ext/params.h" #include "ext/posix-fd-support.h" +#include "ext/preset-load.h" +#include "ext/remote-controls.h" #include "ext/render.h" +#include "ext/state-context.h" #include "ext/state.h" +#include "ext/surround.h" #include "ext/tail.h" #include "ext/thread-check.h" #include "ext/thread-pool.h" #include "ext/timer-support.h" +#include "ext/track-info.h" #include "ext/voice-info.h" #include "ext/draft/ambisonic.h" -#include "ext/draft/audio-ports-activation.h" -#include "ext/draft/context-menu.h" #include "ext/draft/cv.h" #include "ext/draft/midi-mappings.h" -#include "ext/draft/param-indication.h" -#include "ext/draft/preset-load.h" -#include "ext/draft/remote-controls.h" #include "ext/draft/resource-directory.h" -#include "ext/draft/state-context.h" -#include "ext/draft/surround.h" -#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" diff --git a/include/clap/ext/draft/audio-ports-activation.h b/include/clap/ext/audio-ports-activation.h similarity index 98% rename from include/clap/ext/draft/audio-ports-activation.h rename to include/clap/ext/audio-ports-activation.h index f451c005..a3c1184b 100644 --- a/include/clap/ext/draft/audio-ports-activation.h +++ b/include/clap/ext/audio-ports-activation.h @@ -1,6 +1,6 @@ #pragma once -#include "../../plugin.h" +#include "../plugin.h" /// @page Audio Ports Activation /// diff --git a/include/clap/ext/draft/configurable-audio-ports.h b/include/clap/ext/configurable-audio-ports.h similarity index 98% rename from include/clap/ext/draft/configurable-audio-ports.h rename to include/clap/ext/configurable-audio-ports.h index 4fe60cd1..9b0ffffb 100644 --- a/include/clap/ext/draft/configurable-audio-ports.h +++ b/include/clap/ext/configurable-audio-ports.h @@ -1,6 +1,6 @@ #pragma once -#include "../audio-ports.h" +#include "audio-ports.h" #ifdef __cplusplus extern "C" { diff --git a/include/clap/ext/draft/context-menu.h b/include/clap/ext/context-menu.h similarity index 99% rename from include/clap/ext/draft/context-menu.h rename to include/clap/ext/context-menu.h index 85c3abbc..f27c801f 100644 --- a/include/clap/ext/draft/context-menu.h +++ b/include/clap/ext/context-menu.h @@ -1,6 +1,6 @@ #pragma once -#include "../../plugin.h" +#include "../plugin.h" // This extension lets the host and plugin exchange menu items and let the plugin ask the host to // show its context menu. diff --git a/include/clap/ext/draft/param-indication.h b/include/clap/ext/param-indication.h similarity index 98% rename from include/clap/ext/draft/param-indication.h rename to include/clap/ext/param-indication.h index 5ec45f75..1d804aa1 100644 --- a/include/clap/ext/draft/param-indication.h +++ b/include/clap/ext/param-indication.h @@ -1,7 +1,7 @@ #pragma once -#include "../params.h" -#include "../../color.h" +#include "params.h" +#include "../color.h" // This extension lets the host tell the plugin to display a little color based indication on the // parameter. This can be used to indicate: diff --git a/include/clap/ext/draft/preset-load.h b/include/clap/ext/preset-load.h similarity index 98% rename from include/clap/ext/draft/preset-load.h rename to include/clap/ext/preset-load.h index 92263f11..ddd805de 100644 --- a/include/clap/ext/draft/preset-load.h +++ b/include/clap/ext/preset-load.h @@ -1,6 +1,6 @@ #pragma once -#include "../../plugin.h" +#include "../plugin.h" static const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load.draft/2"; diff --git a/include/clap/ext/draft/remote-controls.h b/include/clap/ext/remote-controls.h similarity index 97% rename from include/clap/ext/draft/remote-controls.h rename to include/clap/ext/remote-controls.h index 07566d0a..f467d70a 100644 --- a/include/clap/ext/draft/remote-controls.h +++ b/include/clap/ext/remote-controls.h @@ -1,7 +1,7 @@ #pragma once -#include "../../plugin.h" -#include "../../string-sizes.h" +#include "../plugin.h" +#include "../string-sizes.h" // This extension let the plugin provide a structured way of mapping parameters to an hardware // controller. diff --git a/include/clap/ext/draft/state-context.h b/include/clap/ext/state-context.h similarity index 97% rename from include/clap/ext/draft/state-context.h rename to include/clap/ext/state-context.h index 4912a6e0..4ab5f6f4 100644 --- a/include/clap/ext/draft/state-context.h +++ b/include/clap/ext/state-context.h @@ -1,7 +1,7 @@ #pragma once -#include "../../plugin.h" -#include "../../stream.h" +#include "../plugin.h" +#include "../stream.h" /// @page state-context extension /// @brief extended state handling diff --git a/include/clap/ext/draft/surround.h b/include/clap/ext/surround.h similarity index 99% rename from include/clap/ext/draft/surround.h rename to include/clap/ext/surround.h index 82f4e888..77348f6a 100644 --- a/include/clap/ext/draft/surround.h +++ b/include/clap/ext/surround.h @@ -1,6 +1,6 @@ #pragma once -#include "../../plugin.h" +#include "../plugin.h" // This extension can be used to specify the channel mapping used by the plugin. // diff --git a/include/clap/ext/draft/track-info.h b/include/clap/ext/track-info.h similarity index 95% rename from include/clap/ext/draft/track-info.h rename to include/clap/ext/track-info.h index a79e67c3..2d96473c 100644 --- a/include/clap/ext/draft/track-info.h +++ b/include/clap/ext/track-info.h @@ -1,8 +1,8 @@ #pragma once -#include "../../plugin.h" -#include "../../color.h" -#include "../../string-sizes.h" +#include "../plugin.h" +#include "../color.h" +#include "../string-sizes.h" // 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) diff --git a/include/clap/factory/draft/preset-discovery.h b/include/clap/factory/preset-discovery.h similarity index 99% rename from include/clap/factory/draft/preset-discovery.h rename to include/clap/factory/preset-discovery.h index 05223d9d..9164ff2b 100644 --- a/include/clap/factory/draft/preset-discovery.h +++ b/include/clap/factory/preset-discovery.h @@ -41,9 +41,9 @@ #pragma once -#include "../../private/std.h" -#include "../../private/macros.h" -#include "../../version.h" +#include "../private/std.h" +#include "../private/macros.h" +#include "../version.h" // Use it to retrieve const clap_preset_discovery_factory_t* from // clap_plugin_entry.get_factory() From 1553a233ac207e15a6dcbfcd5185b8eae159e5c7 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 20 Dec 2023 11:33:05 +0100 Subject: [PATCH 14/85] Update ChangeLog --- ChangeLog.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/ChangeLog.md b/ChangeLog.md index d924bd9e..da0edf3c 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,3 +1,28 @@ +# Changes in 1.2.0 + +## Stabilize extensions + +* `CLAP_EXT_AUDIO_PORTS_ACTIVATION` +* `CLAP_EXT_CONFIGURABLE_AUDIO_PORTS` +* `CLAP_EXT_CONTEXT_MENU` +* `CLAP_EXT_PARAM_INDICATION` +* `CLAP_EXT_PRESET_LOAD` +* `CLAP_EXT_REMOTE_CONTROLS` +* `CLAP_EXT_STATE_CONTEXT` +* `CLAP_EXT_SURROUND` +* `CLAP_EXT_TRACK_INFO` + +Note: we kept the last draft extension ID in order to not break plugin already using it. + +## Stabilize factory +* `CLAP_PRESET_DISCOVERY_FACTORY_ID` + +Note: we kept the last draft factory ID in order to not break plugin already using it. + +## Documentation + +* [events.h](include/clap/events.h): Clarify how "Port Channel Key NoteID" matching works + # Changes in 1.1.11 * [latency.h](include/clap/ext/latency.h): require the plugin to be activated to get the latency From 939278819c136c29029d59941b55b12ecc048bad Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 20 Dec 2023 11:39:29 +0100 Subject: [PATCH 15/85] ChangeLog update --- ChangeLog.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/ChangeLog.md b/ChangeLog.md index da0edf3c..4feb9db9 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -22,6 +22,13 @@ Note: we kept the last draft factory ID in order to not break plugin already usi ## Documentation * [events.h](include/clap/events.h): Clarify how "Port Channel Key NoteID" matching works +* [plugin.h](include/clap/plugin.h): Style cleanup +* [params.h](include/clap/ext/params.h): Fix incorrect function name reference +* [latency.h](include/clap/ext/latency.h): Precise that the latency can only be fetched when the plugin is activated + +## Plugin Template + +* [plugin-template.c](src/plugin-template.c): Add exemple code for safer clap entry initialization # Changes in 1.1.11 From 48395657c1cc94046c2c2449b95934336c1a177a Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 20 Dec 2023 11:53:32 +0100 Subject: [PATCH 16/85] Add a convention file for the extension id --- conventions/extension-id.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 conventions/extension-id.md diff --git a/conventions/extension-id.md b/conventions/extension-id.md new file mode 100644 index 00000000..b92afd52 --- /dev/null +++ b/conventions/extension-id.md @@ -0,0 +1,22 @@ +# Extension ID + +## Naming + +The extension shall be named in the form: `clap.$NAME/$REV`. +Where: +- `$NAME` is the name of the exension. +- `$REV` is the revision of the extension. This is an integer that is incremented for each iteration. + +## Draft + +An extension is considered a draft extension if it is in the [draft](../include/clap/ext/draft/) folder. + +When the extension is migrating from draft to stable, its extension ID must not change. + +All extensions must go first though a draft phase. + +## History + +Before this document was written, existing extension didn't honor those rules. +Some stable extension include the string `draft` in their ID. +We decided to keep those in order to maintain the binary compatibility. \ No newline at end of file From 252e9d71e3660bfa09a4ceedf05a7dd16ea06517 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 20 Dec 2023 12:00:19 +0100 Subject: [PATCH 17/85] Update the extension id convention --- conventions/extension-id.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/conventions/extension-id.md b/conventions/extension-id.md index b92afd52..05dcfc69 100644 --- a/conventions/extension-id.md +++ b/conventions/extension-id.md @@ -7,6 +7,10 @@ Where: - `$NAME` is the name of the exension. - `$REV` is the revision of the extension. This is an integer that is incremented for each iteration. +For extensions made by third-parties and not officially published by the CLAP project, please use the following form: `$REVERSE_URI.$NAME/$REV`. +Where: +- `$REVERSE_URI` would be something like `com.bitwig`. + ## Draft An extension is considered a draft extension if it is in the [draft](../include/clap/ext/draft/) folder. @@ -15,6 +19,10 @@ When the extension is migrating from draft to stable, its extension ID must not All extensions must go first though a draft phase. +## For factory ID + +Everything about the extension id simetrically applies to factory id. + ## History Before this document was written, existing extension didn't honor those rules. From 9029824b5b48aff40b00cf69fa2595e4459a99e6 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 20 Dec 2023 12:03:09 +0100 Subject: [PATCH 18/85] Update ChangeLog --- ChangeLog.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/ChangeLog.md b/ChangeLog.md index 4feb9db9..d76f2713 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -26,6 +26,10 @@ Note: we kept the last draft factory ID in order to not break plugin already usi * [params.h](include/clap/ext/params.h): Fix incorrect function name reference * [latency.h](include/clap/ext/latency.h): Precise that the latency can only be fetched when the plugin is activated +## Conventions + +* [extension-id](conventions/extension-id.md): introduce some rules about extension ID naming. + ## Plugin Template * [plugin-template.c](src/plugin-template.c): Add exemple code for safer clap entry initialization From 73ee4148455519708ed4fe4d09b5efc42a925efa Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 20 Dec 2023 12:39:26 +0100 Subject: [PATCH 19/85] ChangeLog: fix typo --- ChangeLog.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index d76f2713..19be8cc8 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -12,12 +12,12 @@ * `CLAP_EXT_SURROUND` * `CLAP_EXT_TRACK_INFO` -Note: we kept the last draft extension ID in order to not break plugin already using it. +Note: we kept the last draft extension ID in order to not break plugins already using it. ## Stabilize factory * `CLAP_PRESET_DISCOVERY_FACTORY_ID` -Note: we kept the last draft factory ID in order to not break plugin already using it. +Note: we kept the last draft factory ID in order to not break plugins already using it. ## Documentation From 2d1ae7dedcfaf9bc03e4a44accf15d7eef7639e8 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 20 Dec 2023 12:41:33 +0100 Subject: [PATCH 20/85] Various language fixes --- ChangeLog.md | 4 ++-- conventions/extension-id.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 19be8cc8..3dd61a8c 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -24,7 +24,7 @@ Note: we kept the last draft factory ID in order to not break plugins already us * [events.h](include/clap/events.h): Clarify how "Port Channel Key NoteID" matching works * [plugin.h](include/clap/plugin.h): Style cleanup * [params.h](include/clap/ext/params.h): Fix incorrect function name reference -* [latency.h](include/clap/ext/latency.h): Precise that the latency can only be fetched when the plugin is activated +* [latency.h](include/clap/ext/latency.h): Clarify that the latency can only be fetched when the plugin is activated ## Conventions @@ -32,7 +32,7 @@ Note: we kept the last draft factory ID in order to not break plugins already us ## Plugin Template -* [plugin-template.c](src/plugin-template.c): Add exemple code for safer clap entry initialization +* [plugin-template.c](src/plugin-template.c): Add example code for safer clap entry initialization # Changes in 1.1.11 diff --git a/conventions/extension-id.md b/conventions/extension-id.md index 05dcfc69..590e58d3 100644 --- a/conventions/extension-id.md +++ b/conventions/extension-id.md @@ -17,7 +17,7 @@ An extension is considered a draft extension if it is in the [draft](../include/ When the extension is migrating from draft to stable, its extension ID must not change. -All extensions must go first though a draft phase. +All extensions must go though the draft phase first. ## For factory ID From 6d59db2009e51938e3f3e870ea37c28e3ee9cbc8 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 20 Dec 2023 13:07:37 +0100 Subject: [PATCH 21/85] Remove a TODO --- include/clap/ext/context-menu.h | 1 - 1 file changed, 1 deletion(-) diff --git a/include/clap/ext/context-menu.h b/include/clap/ext/context-menu.h index f27c801f..0864e3a2 100644 --- a/include/clap/ext/context-menu.h +++ b/include/clap/ext/context-menu.h @@ -15,7 +15,6 @@ extern "C" { enum { CLAP_CONTEXT_MENU_TARGET_KIND_GLOBAL = 0, CLAP_CONTEXT_MENU_TARGET_KIND_PARAM = 1, - // TODO: kind trigger once the trigger ext is marked as stable }; // Describes the context menu target From f52dd8639624a723d6db45af70c73cf68b16ef5f Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 20 Dec 2023 14:17:15 +0100 Subject: [PATCH 22/85] This should be gone --- include/clap/ext/latency.h | 1 - 1 file changed, 1 deletion(-) diff --git a/include/clap/ext/latency.h b/include/clap/ext/latency.h index b66dd8f7..6c9df1b1 100644 --- a/include/clap/ext/latency.h +++ b/include/clap/ext/latency.h @@ -8,7 +8,6 @@ static CLAP_CONSTEXPR const char CLAP_EXT_LATENCY[] = "clap.latency"; extern "C" { #endif -// The audio ports scan has to be done while the plugin is deactivated. typedef struct clap_plugin_latency { // Returns the plugin latency in samples. // [main-thread & active] From 56fa0195aaf47b8b81275e3e3996ecf80660c402 Mon Sep 17 00:00:00 2001 From: Paul Walker Date: Thu, 21 Dec 2023 10:08:21 -0500 Subject: [PATCH 23/85] Expand a bit on the difference between init and create This documentation was by create, but it wasn't by init, so make it clear in both locations. --- include/clap/plugin.h | 3 +++ 1 file changed, 3 insertions(+) diff --git a/include/clap/plugin.h b/include/clap/plugin.h index 7c379d40..7e83074b 100644 --- a/include/clap/plugin.h +++ b/include/clap/plugin.h @@ -46,6 +46,9 @@ typedef struct clap_plugin { // Must be called after creating the plugin. // If init returns false, the host must destroy the plugin instance. // If init returns true, then the plugin is initialized and in the deactivated state. + // Unlike in `plugin-factory::create_plugin`, in init you have complete access to the host + // and host extensions, so clap related setup activities should be done here rather than in + // create_plugin. // [main-thread] bool(CLAP_ABI *init)(const struct clap_plugin *plugin); From cd540843901142314a50d0e07314c85ae54d2454 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 22 Dec 2023 09:07:59 +0100 Subject: [PATCH 24/85] Fix typo in conventions/extension-id.md Co-authored-by: Dalton Messmer --- conventions/extension-id.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conventions/extension-id.md b/conventions/extension-id.md index 590e58d3..64173556 100644 --- a/conventions/extension-id.md +++ b/conventions/extension-id.md @@ -21,7 +21,7 @@ All extensions must go though the draft phase first. ## For factory ID -Everything about the extension id simetrically applies to factory id. +Everything about the extension id symmetrically applies to factory id. ## History From 357f5bde863f89e567b0a658309465af019d9515 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 22 Dec 2023 10:52:36 +0100 Subject: [PATCH 25/85] Move clap_plugin_id_t to its own file --- include/clap/clap.h | 1 + include/clap/factory/preset-discovery.h | 11 ----------- include/clap/plugin-id.h | 13 +++++++++++++ 3 files changed, 14 insertions(+), 11 deletions(-) create mode 100644 include/clap/plugin-id.h diff --git a/include/clap/clap.h b/include/clap/clap.h index 868188b3..d20def5d 100644 --- a/include/clap/clap.h +++ b/include/clap/clap.h @@ -35,6 +35,7 @@ #include "plugin.h" #include "plugin-features.h" #include "host.h" +#include "plugin-id.h" #include "ext/audio-ports-activation.h" #include "ext/audio-ports-config.h" diff --git a/include/clap/factory/preset-discovery.h b/include/clap/factory/preset-discovery.h index 9164ff2b..48c70a14 100644 --- a/include/clap/factory/preset-discovery.h +++ b/include/clap/factory/preset-discovery.h @@ -93,17 +93,6 @@ typedef uint64_t clap_timestamp_t; // Value for unknown timestamp. static const clap_timestamp_t CLAP_TIMESTAMP_UNKNOWN = 0; -// Pair of plugin ABI and plugin identifier -typedef struct clap_plugin_id { - // The plugin ABI name, in lowercase. - // eg: "clap" - const char *abi; - - // The plugin ID, for example "com.u-he.Diva". - // If the ABI rely upon binary plugin ids, then they shall be hex encoded (lower case). - const char *id; -} clap_plugin_id_t; - // Receiver that receives the metadata for a single preset file. // The host would define the various callbacks in this interface and the preset parser function // would then call them. diff --git a/include/clap/plugin-id.h b/include/clap/plugin-id.h new file mode 100644 index 00000000..962eab8f --- /dev/null +++ b/include/clap/plugin-id.h @@ -0,0 +1,13 @@ +#pragma once + +// Pair of plugin ABI and plugin identifier. +typedef struct clap_plugin_id { + // The plugin ABI name, in lowercase. + // eg: "clap" + const char *abi; + + // The plugin ID, for example "com.u-he.Diva". + // If the ABI rely upon binary plugin ids, then they shall be hex encoded (lower case). + const char *id; +} clap_plugin_id_t; + From 992da92ba910f12f701477a1fb146d5f693bad9f Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 22 Dec 2023 10:52:59 +0100 Subject: [PATCH 26/85] Add a plugin state converter factory --- .../factory/draft/plugin-state-converter.h | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 include/clap/factory/draft/plugin-state-converter.h diff --git a/include/clap/factory/draft/plugin-state-converter.h b/include/clap/factory/draft/plugin-state-converter.h new file mode 100644 index 00000000..a1a3d21d --- /dev/null +++ b/include/clap/factory/draft/plugin-state-converter.h @@ -0,0 +1,63 @@ +#pragma once + +#include "../../id.h" +#include "../../plugin-id.h" +#include "../../stream.h" + +#ifdef __cplusplus +extern "C" { +#endif + +// This interface provides helps the host to convert a plugin state and its automation +// points to a new plugin. +// +// This is useful to convert from one plugin ABI to another one. +// This is also useful to offer an upgrade path: from EQ version 1 to EQ version 2. +// This can also be used to convert the state of a plugin that isn't maintained anymore into +// another plugin that would be similar. +typedef struct clap_plugin_state_converter { + const clap_plugin_id_t *src_plugin_id; + const clap_plugin_id_t *dst_plugin_id; + + // Converts the input state to a state usable by the destination plugin. + // [thread-safe] + bool (*convert_state)(const struct clap_plugin_state_converter *converter, + const clap_istream_t *src, + const clap_ostream_t *dst); + + // Converts a normalized value. + // [thread-safe] + bool (*convert_normalized_value)(const struct clap_plugin_state_converter *converter, + clap_id src_param_id, + double src_normalized_value, + clap_id *dst_param_id, + double *dst_normalized_value); + + // Converts a plain value. + // [thread-safe] + bool (*convert_plain_value)(const struct clap_plugin_state_converter *converter, + clap_id src_param_id, + double src_plain_value, + clap_id *dst_param_id, + double *dst_plain_value); +} clap_plugin_state_converter_t; + +// Factory identifier +static CLAP_CONSTEXPR const char CLAP_CLAP_CONVERTER_FACTORY_ID[] = + "clap.plugin-state-converter-factory/1"; + +// List all the plugin state converters available in the current DSO. +typedef struct clap_plugin_state_converter_factory { + // Get the number of converters. + // [thread-safe] + uint32_t (*count)(const struct clap_plugin_state_converter_factory *factory); + + // Get the converter at the given index. + // [thread-safe] + const clap_plugin_state_converter_t *(*get)( + const struct clap_plugin_state_converter_factory *factory, uint32_t index); +} clap_clap_converter_factory_t; + +#ifdef __cplusplus +} +#endif From c02f7047971d5f2b6f889fd111cd34c264dd2291 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 22 Dec 2023 10:55:51 +0100 Subject: [PATCH 27/85] Update changelog --- ChangeLog.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/ChangeLog.md b/ChangeLog.md index 3dd61a8c..ebdea119 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -19,6 +19,10 @@ Note: we kept the last draft extension ID in order to not break plugins already Note: we kept the last draft factory ID in order to not break plugins already using it. +## Plugin State Converter + +* Introduction of a new factory which provides a plugin state convertion mechanism. + ## Documentation * [events.h](include/clap/events.h): Clarify how "Port Channel Key NoteID" matching works From c306c1d05207884fa41284407790d1634e800f4c Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 22 Dec 2023 10:58:05 +0100 Subject: [PATCH 28/85] Missing include --- include/clap/factory/preset-discovery.h | 1 + 1 file changed, 1 insertion(+) diff --git a/include/clap/factory/preset-discovery.h b/include/clap/factory/preset-discovery.h index 48c70a14..752b3a4b 100644 --- a/include/clap/factory/preset-discovery.h +++ b/include/clap/factory/preset-discovery.h @@ -44,6 +44,7 @@ #include "../private/std.h" #include "../private/macros.h" #include "../version.h" +#include "../plugin-id.h" // Use it to retrieve const clap_preset_discovery_factory_t* from // clap_plugin_entry.get_factory() From b312b47bfd04b74e5e787a0280333b0b66614620 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 22 Dec 2023 11:01:52 +0100 Subject: [PATCH 29/85] Update changelog as 1.1.11 was never released --- ChangeLog.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index ebdea119..b70d2dd8 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -28,7 +28,7 @@ Note: we kept the last draft factory ID in order to not break plugins already us * [events.h](include/clap/events.h): Clarify how "Port Channel Key NoteID" matching works * [plugin.h](include/clap/plugin.h): Style cleanup * [params.h](include/clap/ext/params.h): Fix incorrect function name reference -* [latency.h](include/clap/ext/latency.h): Clarify that the latency can only be fetched when the plugin is activated +* [latency.h](include/clap/ext/latency.h): Require the plugin to be activated to get the latency and clarify that the latency can only be fetched when the plugin is activated ## Conventions @@ -36,12 +36,7 @@ Note: we kept the last draft factory ID in order to not break plugins already us ## Plugin Template -* [plugin-template.c](src/plugin-template.c): Add example code for safer clap entry initialization - -# Changes in 1.1.11 - -* [latency.h](include/clap/ext/latency.h): require the plugin to be activated to get the latency -* [plugin-template.c](src/plugin-template.c): implement thread-safe entry init counter +* [plugin-template.c](src/plugin-template.c): implement thread-safe plugin entry init counter # Changes in 1.1.10 From b627a555177d415a72f4faafc364cc2a47f13239 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 22 Dec 2023 11:02:55 +0100 Subject: [PATCH 30/85] Update version.h to 1.2.0 --- include/clap/version.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/clap/version.h b/include/clap/version.h index 33072a2d..6a3e782c 100644 --- a/include/clap/version.h +++ b/include/clap/version.h @@ -21,8 +21,8 @@ typedef struct clap_version { #endif #define CLAP_VERSION_MAJOR 1 -#define CLAP_VERSION_MINOR 1 -#define CLAP_VERSION_REVISION 10 +#define CLAP_VERSION_MINOR 2 +#define CLAP_VERSION_REVISION 0 #define CLAP_VERSION_INIT \ { (uint32_t)CLAP_VERSION_MAJOR, (uint32_t)CLAP_VERSION_MINOR, (uint32_t)CLAP_VERSION_REVISION } From b00a04e9c865bc2cc356d83ecb34e137ebc36b58 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 22 Dec 2023 11:06:42 +0100 Subject: [PATCH 31/85] Clarify that the extension's revision number should start at 1. --- conventions/extension-id.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conventions/extension-id.md b/conventions/extension-id.md index 64173556..14c489a9 100644 --- a/conventions/extension-id.md +++ b/conventions/extension-id.md @@ -5,7 +5,7 @@ The extension shall be named in the form: `clap.$NAME/$REV`. Where: - `$NAME` is the name of the exension. -- `$REV` is the revision of the extension. This is an integer that is incremented for each iteration. +- `$REV` is the revision of the extension. This is an integer that is incremented for each iteration. It should start at 1. For extensions made by third-parties and not officially published by the CLAP project, please use the following form: `$REVERSE_URI.$NAME/$REV`. Where: From 37bab41b681f8c91644b52baad86af97653eef3e Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 22 Dec 2023 11:08:49 +0100 Subject: [PATCH 32/85] Fix typedef and doc the return value --- include/clap/factory/draft/plugin-state-converter.h | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/include/clap/factory/draft/plugin-state-converter.h b/include/clap/factory/draft/plugin-state-converter.h index a1a3d21d..f9cdd816 100644 --- a/include/clap/factory/draft/plugin-state-converter.h +++ b/include/clap/factory/draft/plugin-state-converter.h @@ -20,12 +20,14 @@ typedef struct clap_plugin_state_converter { const clap_plugin_id_t *dst_plugin_id; // Converts the input state to a state usable by the destination plugin. + // Returns true on success. // [thread-safe] bool (*convert_state)(const struct clap_plugin_state_converter *converter, const clap_istream_t *src, const clap_ostream_t *dst); // Converts a normalized value. + // Returns true on success. // [thread-safe] bool (*convert_normalized_value)(const struct clap_plugin_state_converter *converter, clap_id src_param_id, @@ -34,6 +36,7 @@ typedef struct clap_plugin_state_converter { double *dst_normalized_value); // Converts a plain value. + // Returns true on success. // [thread-safe] bool (*convert_plain_value)(const struct clap_plugin_state_converter *converter, clap_id src_param_id, @@ -56,7 +59,7 @@ typedef struct clap_plugin_state_converter_factory { // [thread-safe] const clap_plugin_state_converter_t *(*get)( const struct clap_plugin_state_converter_factory *factory, uint32_t index); -} clap_clap_converter_factory_t; +} clap_plugin_state_converter_factory_t; #ifdef __cplusplus } From 40bb780c0a6312aef537e81022e5d863981c2f4e Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 22 Dec 2023 11:14:16 +0100 Subject: [PATCH 33/85] Add error message to convert_state() --- include/clap/factory/draft/plugin-state-converter.h | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/include/clap/factory/draft/plugin-state-converter.h b/include/clap/factory/draft/plugin-state-converter.h index f9cdd816..63fc35f7 100644 --- a/include/clap/factory/draft/plugin-state-converter.h +++ b/include/clap/factory/draft/plugin-state-converter.h @@ -20,11 +20,17 @@ typedef struct clap_plugin_state_converter { const clap_plugin_id_t *dst_plugin_id; // Converts the input state to a state usable by the destination plugin. + // + // error_buffer is a place holder of error_buffer_size bytes for storing a null-terminated + // error message in case of failure, which can be displayed to the user. + // // Returns true on success. // [thread-safe] bool (*convert_state)(const struct clap_plugin_state_converter *converter, const clap_istream_t *src, - const clap_ostream_t *dst); + const clap_ostream_t *dst, + char *error_buffer, + size_t error_buffer_size); // Converts a normalized value. // Returns true on success. From 64addfb3e1ecaac9b32bddec9fb3600a7b4ac478 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 22 Dec 2023 11:15:57 +0100 Subject: [PATCH 34/85] Fix doc. --- include/clap/factory/draft/plugin-state-converter.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/factory/draft/plugin-state-converter.h b/include/clap/factory/draft/plugin-state-converter.h index 63fc35f7..8d6186f9 100644 --- a/include/clap/factory/draft/plugin-state-converter.h +++ b/include/clap/factory/draft/plugin-state-converter.h @@ -8,7 +8,7 @@ extern "C" { #endif -// This interface provides helps the host to convert a plugin state and its automation +// This interface provides a mechanism for the host to convert a plugin state and its automation // points to a new plugin. // // This is useful to convert from one plugin ABI to another one. From df6fc7b2c725043caefd4679251048ae40ad5b9f Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Sat, 23 Dec 2023 21:51:38 +0100 Subject: [PATCH 35/85] Rework the plugin state converter --- .../factory/draft/plugin-state-converter.h | 64 +++++++++++++------ 1 file changed, 45 insertions(+), 19 deletions(-) diff --git a/include/clap/factory/draft/plugin-state-converter.h b/include/clap/factory/draft/plugin-state-converter.h index 8d6186f9..1c18c266 100644 --- a/include/clap/factory/draft/plugin-state-converter.h +++ b/include/clap/factory/draft/plugin-state-converter.h @@ -3,11 +3,24 @@ #include "../../id.h" #include "../../plugin-id.h" #include "../../stream.h" +#include "../../version.h" #ifdef __cplusplus extern "C" { #endif +typedef struct clap_plugin_state_converter_descriptor { + clap_version_t clap_version; + + clap_plugin_id_t src_plugin_id; + clap_plugin_id_t dst_plugin_id; + + const char *name; + const char *vendor; + const char *version; + const char *description; +} clap_plugin_state_converter_descriptor_t; + // This interface provides a mechanism for the host to convert a plugin state and its automation // points to a new plugin. // @@ -16,8 +29,12 @@ extern "C" { // This can also be used to convert the state of a plugin that isn't maintained anymore into // another plugin that would be similar. typedef struct clap_plugin_state_converter { - const clap_plugin_id_t *src_plugin_id; - const clap_plugin_id_t *dst_plugin_id; + const clap_plugin_state_converter_descriptor_t *desc; + + void *converter_data; + + // Destroy the converter. + void (*destroy)(struct clap_plugin_state_converter *converter); // Converts the input state to a state usable by the destination plugin. // @@ -26,29 +43,29 @@ typedef struct clap_plugin_state_converter { // // Returns true on success. // [thread-safe] - bool (*convert_state)(const struct clap_plugin_state_converter *converter, - const clap_istream_t *src, - const clap_ostream_t *dst, - char *error_buffer, - size_t error_buffer_size); + bool (*convert_state)(struct clap_plugin_state_converter *converter, + const clap_istream_t *src, + const clap_ostream_t *dst, + char *error_buffer, + size_t error_buffer_size); // Converts a normalized value. // Returns true on success. // [thread-safe] - bool (*convert_normalized_value)(const struct clap_plugin_state_converter *converter, - clap_id src_param_id, - double src_normalized_value, - clap_id *dst_param_id, - double *dst_normalized_value); + bool (*convert_normalized_value)(struct clap_plugin_state_converter *converter, + clap_id src_param_id, + double src_normalized_value, + clap_id *dst_param_id, + double *dst_normalized_value); // Converts a plain value. // Returns true on success. // [thread-safe] - bool (*convert_plain_value)(const struct clap_plugin_state_converter *converter, - clap_id src_param_id, - double src_plain_value, - clap_id *dst_param_id, - double *dst_plain_value); + bool (*convert_plain_value)(struct clap_plugin_state_converter *converter, + clap_id src_param_id, + double src_plain_value, + clap_id *dst_param_id, + double *dst_plain_value); } clap_plugin_state_converter_t; // Factory identifier @@ -61,9 +78,18 @@ typedef struct clap_plugin_state_converter_factory { // [thread-safe] uint32_t (*count)(const struct clap_plugin_state_converter_factory *factory); - // Get the converter at the given index. + // Retrieves a plugin state converter descriptor by its index. + // Returns null in case of error. + // The descriptor must not be freed. + // [thread-safe] + const clap_plugin_state_converter_descriptor_t *(*get_descriptor)( + const struct clap_plugin_state_converter_factory *factory, uint32_t index); + + // Create a plugin state converter by its index. + // The returned pointer must be freed by calling converter->destroy(converter); + // Returns null in case of error. // [thread-safe] - const clap_plugin_state_converter_t *(*get)( + clap_plugin_state_converter_t *(*create)( const struct clap_plugin_state_converter_factory *factory, uint32_t index); } clap_plugin_state_converter_factory_t; From 5e20b73fa854eacf4a94f74b90764fd84d098b65 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Sat, 23 Dec 2023 21:52:27 +0100 Subject: [PATCH 36/85] Include the state converter --- include/clap/clap.h | 1 + 1 file changed, 1 insertion(+) diff --git a/include/clap/clap.h b/include/clap/clap.h index d20def5d..b1d90614 100644 --- a/include/clap/clap.h +++ b/include/clap/clap.h @@ -31,6 +31,7 @@ #include "factory/preset-discovery.h" #include "factory/draft/plugin-invalidation.h" +#include "factory/draft/plugin-state-converter.h" #include "plugin.h" #include "plugin-features.h" From 71997ee2305752940d77440dc21f608bbd61741c Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Sat, 23 Dec 2023 22:27:23 +0100 Subject: [PATCH 37/85] Update conventions/extension-id.md Co-authored-by: Dalton Messmer --- conventions/extension-id.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/conventions/extension-id.md b/conventions/extension-id.md index 14c489a9..b725be8d 100644 --- a/conventions/extension-id.md +++ b/conventions/extension-id.md @@ -25,6 +25,6 @@ Everything about the extension id symmetrically applies to factory id. ## History -Before this document was written, existing extension didn't honor those rules. -Some stable extension include the string `draft` in their ID. -We decided to keep those in order to maintain the binary compatibility. \ No newline at end of file +Before this document was written, existing extensions didn't honor these rules. +Some stable extensions include the string `draft` in their ID. +We decided to keep those in order to maintain binary compatibility. \ No newline at end of file From 29a0b08ba6bd85133b4e86dd068b483689bc7048 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Sat, 23 Dec 2023 22:28:27 +0100 Subject: [PATCH 38/85] Fix factory id identifier name --- include/clap/factory/draft/plugin-state-converter.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/factory/draft/plugin-state-converter.h b/include/clap/factory/draft/plugin-state-converter.h index 1c18c266..19c96ad3 100644 --- a/include/clap/factory/draft/plugin-state-converter.h +++ b/include/clap/factory/draft/plugin-state-converter.h @@ -69,7 +69,7 @@ typedef struct clap_plugin_state_converter { } clap_plugin_state_converter_t; // Factory identifier -static CLAP_CONSTEXPR const char CLAP_CLAP_CONVERTER_FACTORY_ID[] = +static CLAP_CONSTEXPR const char CLAP_PLUGIN_STATE_CONVERTER_FACTORY_ID[] = "clap.plugin-state-converter-factory/1"; // List all the plugin state converters available in the current DSO. From 6f0a98e5ee9337df5cce1d57d532ed7900418d2c Mon Sep 17 00:00:00 2001 From: defiantnerd Date: Thu, 28 Dec 2023 09:39:56 +0100 Subject: [PATCH 39/85] added project load as explicit option --- include/clap/ext/state-context.h | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/include/clap/ext/state-context.h b/include/clap/ext/state-context.h index 4ab5f6f4..e27bcef1 100644 --- a/include/clap/ext/state-context.h +++ b/include/clap/ext/state-context.h @@ -10,7 +10,8 @@ /// on the context. /// /// Briefly, when loading a preset or duplicating a device, the plugin may want to partially load -/// the state and initialize certain things differently. +/// the state and initialize certain things differently, like handling limited resources or fixed +/// connections to external hardware resources. /// /// Save and Load operations may have a different context. /// All three operations should be equivalent: @@ -20,6 +21,8 @@ /// clap_plugin_state_context.save(CLAP_STATE_CONTEXT_FOR_PRESET), /// CLAP_STATE_CONTEXT_FOR_PRESET) /// +/// If in doubt, choose CLAP_STATE_CONTEXT_FOR_PRESET as option. +/// /// If the plugin implements CLAP_EXT_STATE_CONTEXT then it is mandatory to also implement /// CLAP_EXT_STATE. @@ -27,14 +30,18 @@ extern "C" { #endif -static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context.draft/1"; +static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context.draft/2"; enum clap_plugin_state_context_type { - // suitable for duplicating a plugin instance - CLAP_STATE_CONTEXT_FOR_DUPLICATE = 1, - // suitable for loading a state as a preset - CLAP_STATE_CONTEXT_FOR_PRESET = 2, + CLAP_STATE_CONTEXT_FOR_PRESET = 1, + + // suitable for duplicating a plugin instance + CLAP_STATE_CONTEXT_FOR_DUPLICATE = 2, + + // suitable for loading a state during loading a project/song + CLAP_STATE_CONTEXT_FOR_PROJECT = 3, + }; typedef struct clap_plugin_state_context { From 01296c46888bd22e65a50372a3c0701afacee035 Mon Sep 17 00:00:00 2001 From: defiantnerd Date: Thu, 28 Dec 2023 19:02:58 +0100 Subject: [PATCH 40/85] changing state-context id to 'clap.state-context/2' --- include/clap/ext/state-context.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/ext/state-context.h b/include/clap/ext/state-context.h index e27bcef1..f1cf1eff 100644 --- a/include/clap/ext/state-context.h +++ b/include/clap/ext/state-context.h @@ -30,7 +30,7 @@ extern "C" { #endif -static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context.draft/2"; +static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context/2"; enum clap_plugin_state_context_type { // suitable for loading a state as a preset From e8591df085031ffad1c823107acf415027c2a092 Mon Sep 17 00:00:00 2001 From: Micah Johnston Date: Sat, 6 Jan 2024 16:56:41 -0600 Subject: [PATCH 41/85] do not include draft headers from clap.h All includes of draft headers have been moved from clap.h to a separate draft.h header. --- ChangeLog.md | 4 ++++ include/clap/clap.h | 11 ----------- include/clap/draft.h | 12 ++++++++++++ src/main.c | 1 + src/main.cc | 1 + 5 files changed, 18 insertions(+), 11 deletions(-) create mode 100644 include/clap/draft.h diff --git a/ChangeLog.md b/ChangeLog.md index b70d2dd8..ccf8fc63 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -38,6 +38,10 @@ Note: we kept the last draft factory ID in order to not break plugins already us * [plugin-template.c](src/plugin-template.c): implement thread-safe plugin entry init counter +## Organization + +* `clap.h` no longer includes headers from `ext/draft` or `factory/draft`. Draft extension and factory headers must now be explicitly included, either individually or via the `draft.h` header. + # Changes in 1.1.10 * [params.h](include/clap/ext/params.h): add `CLAP_PARAM_IS_ENUM` flag. diff --git a/include/clap/clap.h b/include/clap/clap.h index b1d90614..a9874878 100644 --- a/include/clap/clap.h +++ b/include/clap/clap.h @@ -30,9 +30,6 @@ #include "factory/plugin-factory.h" #include "factory/preset-discovery.h" -#include "factory/draft/plugin-invalidation.h" -#include "factory/draft/plugin-state-converter.h" - #include "plugin.h" #include "plugin-features.h" #include "host.h" @@ -64,11 +61,3 @@ #include "ext/timer-support.h" #include "ext/track-info.h" #include "ext/voice-info.h" - -#include "ext/draft/ambisonic.h" -#include "ext/draft/cv.h" -#include "ext/draft/midi-mappings.h" -#include "ext/draft/resource-directory.h" -#include "ext/draft/triggers.h" -#include "ext/draft/tuning.h" -#include "ext/draft/extensible-audio-ports.h" diff --git a/include/clap/draft.h b/include/clap/draft.h new file mode 100644 index 00000000..7d5f6a34 --- /dev/null +++ b/include/clap/draft.h @@ -0,0 +1,12 @@ +#pragma once + +#include "factory/draft/plugin-invalidation.h" +#include "factory/draft/plugin-state-converter.h" + +#include "ext/draft/ambisonic.h" +#include "ext/draft/cv.h" +#include "ext/draft/midi-mappings.h" +#include "ext/draft/resource-directory.h" +#include "ext/draft/triggers.h" +#include "ext/draft/tuning.h" +#include "ext/draft/extensible-audio-ports.h" diff --git a/src/main.c b/src/main.c index c1d6f593..f4db6b79 100644 --- a/src/main.c +++ b/src/main.c @@ -1,4 +1,5 @@ #include +#include // The purpose of this file is to check that all headers compile int main(int argc, char **argv) { diff --git a/src/main.cc b/src/main.cc index 80febfba..1071d67d 100644 --- a/src/main.cc +++ b/src/main.cc @@ -1,4 +1,5 @@ #include +#include // The purpose of this file is to check that all headers compile From aa670d1f007cc4d1963869ffaf26ce32ec7ed5e2 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Mon, 8 Jan 2024 09:17:35 +0100 Subject: [PATCH 42/85] Adjust state context's documentation --- include/clap/ext/state-context.h | 11 ++++++----- include/clap/ext/state.h | 4 ++++ 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/include/clap/ext/state-context.h b/include/clap/ext/state-context.h index f1cf1eff..20248b37 100644 --- a/include/clap/ext/state-context.h +++ b/include/clap/ext/state-context.h @@ -21,10 +21,12 @@ /// clap_plugin_state_context.save(CLAP_STATE_CONTEXT_FOR_PRESET), /// CLAP_STATE_CONTEXT_FOR_PRESET) /// -/// If in doubt, choose CLAP_STATE_CONTEXT_FOR_PRESET as option. -/// +/// If in doubt, fallback to clap_plugin_state. +/// /// If the plugin implements CLAP_EXT_STATE_CONTEXT then it is mandatory to also implement /// CLAP_EXT_STATE. +/// +/// It is unspecified which context is equivalent to clap_plugin_state.{save,load}() #ifdef __cplusplus extern "C" { @@ -33,15 +35,14 @@ extern "C" { static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context/2"; enum clap_plugin_state_context_type { - // suitable for loading a state as a preset + // suitable for storing and loading a state as a preset CLAP_STATE_CONTEXT_FOR_PRESET = 1, // suitable for duplicating a plugin instance CLAP_STATE_CONTEXT_FOR_DUPLICATE = 2, - // suitable for loading a state during loading a project/song + // suitable for storing and loading a state within a project/song CLAP_STATE_CONTEXT_FOR_PROJECT = 3, - }; typedef struct clap_plugin_state_context { diff --git a/include/clap/ext/state.h b/include/clap/ext/state.h index 8d028e1b..b8b698c0 100644 --- a/include/clap/ext/state.h +++ b/include/clap/ext/state.h @@ -10,6 +10,10 @@ /// values and non-parameter state. This is used to persist a plugin's state /// between project reloads, when duplicating and copying plugin instances, and /// for host-side preset management. +/// +/// If you need to know if the save/load operation is meant for duplicating a plugin +/// instance, for saving/loading a plugin preset or while saving/loading the project +/// then have a look at clap_plugin_state_context_t. static CLAP_CONSTEXPR const char CLAP_EXT_STATE[] = "clap.state"; From ad76eb5cc44154055ce8060e5df9281cfadde6e2 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Mon, 8 Jan 2024 09:29:26 +0100 Subject: [PATCH 43/85] Update the documentation according to the latest discussions --- include/clap/entry.h | 51 ++++++++++++++++++-------------------------- 1 file changed, 21 insertions(+), 30 deletions(-) diff --git a/include/clap/entry.h b/include/clap/entry.h index 877dc941..44747224 100644 --- a/include/clap/entry.h +++ b/include/clap/entry.h @@ -31,42 +31,33 @@ extern "C" { // Each directory should be recursively searched for files and/or bundles as appropriate in your OS // ending with the extension `.clap`. // -// As detailed in the respective functions' documentations below, the host is forbidden from calling -// either init() or deinit() multiple times, without calling the other first. This is to enforce -// a "normal" initialization pattern, where one can't construct or destroy an object multiple times. +// init and deinit in most cases are called once, in a matched pair, when the dso is loaded / unloaded. +// In some rare situations it may be called multiple times in a process, so the functions must be defensive, +// mutex locking and counting calls if undertaking non trivial non idempotent actions. // -// However, there are a few cases where the host may not be able to reliably prevent this from -// happening, such as when multiple, separate hosts co-exist within the same address space (e.g. -// Meta-Plugins, plugins that can host other plugins inside them). It may also happen when a VST -// compatibility layer is used to wrap a CLAP plugin, for instance. +// Rationale: // -// In those cases, the init() and deinit() pair of functions can happen to be called multiple times, -// either in a row or even simultaneously, from different threads, by multiple non-synchronized -// hosts, or by a single host that is presented multiple interfaces to a same DSO. This can happen -// even though this is forbidden behavior from the host by this specification, and despite a -// compliant host's best efforts. +// The intent of the init() and deinit() functions is to provide a "normal" initialization patterh +// which occurs when the shared object is loaded or unloaded. As such, hosts will call each once and +// in matched pairs. In clap specifications prior to 1.1.11, this single-call was documented as a +// requirement. // -// Despite those issues, hosts *must* ensure that each successful call to init() is only followed by -// a single call to deinit() at most. As long as a single successful init() call did not have its -// matching deinit() called, the DSO *must* remain in a fully operational state, as if deinit() had -// not yet been called. +// We realized, though, that this is not a requirement hosts can meet. If hosts load a plugin +// which itself wraps another CLAP for instance, while also loading that same clap in its memory +// space, both the host and the wrapper will call init() and deinit() and have no means to communicate +// the state. // -// Therefore, init() and deinit() functions *should* be implemented in a way that allows for init() -// to be called any number of times in a row (possibly simultaneously, from multiple threads), and -// for deinit() to be called at most that same number of times (also simultaneously, from multiple, -// possibly different threads from the init() called). As of CLAP 1.11, this *must* be the case for -// all plugin implementations. +// With clap 1.1.11 and beyond we are changing the spec to indicate that a host should make an +// absolute best effort to call init() and deinit() once, and always in matched pairs (for every +// init() which returns true, one deinit() should be called). // -// This is already trivially the case if there is no (de)initialization work in the entry at all, -// or if the initialization work is thread safe and idempotent, and there is no de-initialization -// work to be done. Those implementations already are and remain valid, and require no additional -// consideration. +// This takes the de-facto burden on plugin writers to deal with multiple calls into a hard requirement. // -// If that is not the case, then using a global, refcount-like locked initialization counter can be -// used to keep track of init() and deinit() calls. Then the initialization work can be done only -// when the counter goes from 0 to 1 in init(), and de-initialization can be done when the counter -// goes to 0 in deinit(). Any subsequent calls to init() and deinit() can just increase or decrease -// the counter, respectively. +// Most init() / deinit() pairs we have seen are the relatively trivial {return true;} and {}. But +// if your init() function does non-trivial one time work, the plugin author must maintain a counter +// and must manage a mutex lock. The most obvious implementation will maintain a static counter and a +// global mutex, increment the counter on each init, decrement it on each deinit, and only undertake +// the init or deinit action when the counter is zero. typedef struct clap_plugin_entry { clap_version_t clap_version; // initialized to CLAP_VERSION From 863055d5cb568764a87d26d0b6d88a21f4cb3b61 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Mon, 8 Jan 2024 10:10:03 +0100 Subject: [PATCH 44/85] Remove check for update extension --- ChangeLog.md | 4 +++ README.md | 1 - include/clap/ext/draft/check-for-update.h | 32 ----------------------- 3 files changed, 4 insertions(+), 33 deletions(-) delete mode 100644 include/clap/ext/draft/check-for-update.h diff --git a/ChangeLog.md b/ChangeLog.md index b70d2dd8..c0cba488 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -14,6 +14,10 @@ Note: we kept the last draft extension ID in order to not break plugins already using it. +## Removed draft extension + +* `CLAP_EXT_CHECK_FOR_UPDATE` was removed because it wasn't used and it's design needed more thought. + ## Stabilize factory * `CLAP_PRESET_DISCOVERY_FACTORY_ID` diff --git a/README.md b/README.md index 52dc263c..4354567e 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,6 @@ and use to get a basic plugin experience: - [track-info](include/clap/ext/draft/track-info.h) - [quick-controls](include/clap/ext/draft/quick-controls.h), bank of controls that can be mapped on a controlles with 8 knobs - [file-reference](include/clap/ext/draft/file-reference.h), let the host know about the plugin's file reference, and perform "Collect & Save" -- [check-for-update](include/clap/ext/draft/check-for-update.h), check if there is a new version of a plugin - [audio-ports-config](include/clap/ext/audio-ports-config.h), simple list of possible configurations - [surround](include/clap/ext/draft/surround.h), inspect surround channel mapping - [ambisonic](include/clap/ext/draft/ambisonic.h), inspect ambisonic channel mapping diff --git a/include/clap/ext/draft/check-for-update.h b/include/clap/ext/draft/check-for-update.h deleted file mode 100644 index 71ebe81c..00000000 --- a/include/clap/ext/draft/check-for-update.h +++ /dev/null @@ -1,32 +0,0 @@ -#pragma once - -#include "../../plugin.h" - -static CLAP_CONSTEXPR const char CLAP_EXT_CHECK_FOR_UPDATE[] = "clap.check_for_update.draft/0"; - -#ifdef __cplusplus -extern "C" { -#endif - -typedef struct clap_check_for_update_info { - const char *version; // latest version - const char *release_date; // YYYY-MM-DD - const char *url; // url to a download page which the user can visit - - bool is_preview; // true if this version is a preview release -} clap_check_for_update_info_t; - -typedef struct clap_plugin_check_for_update { - // [main-thread] - void(CLAP_ABI *check)(const clap_plugin_t *plugin, bool include_preview); -} clap_plugin_check_for_update_t; - -typedef struct clap_host_check_for_update { - // [main-thread] - void(CLAP_ABI *on_new_version)(const clap_host_t *host, - const clap_check_for_update_info_t *update_info); -} clap_host_check_for_update_t; - -#ifdef __cplusplus -} -#endif From 5cdb92c2b9b149954ea97534b7af7f42222bc4cd Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Mon, 8 Jan 2024 12:18:10 +0100 Subject: [PATCH 45/85] Remove midi mapping extension --- ChangeLog.md | 5 ++-- include/clap/clap.h | 1 - include/clap/ext/draft/midi-mappings.h | 41 -------------------------- 3 files changed, 3 insertions(+), 44 deletions(-) delete mode 100644 include/clap/ext/draft/midi-mappings.h diff --git a/ChangeLog.md b/ChangeLog.md index c0cba488..0584239a 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -14,9 +14,10 @@ Note: we kept the last draft extension ID in order to not break plugins already using it. -## Removed draft extension +## Removed draft extensions -* `CLAP_EXT_CHECK_FOR_UPDATE` was removed because it wasn't used and it's design needed more thought. +* `CLAP_EXT_CHECK_FOR_UPDATE` wasn't used and it's design needed more thought. +* `CLAP_EXT_MIDI_MAPPING` wasn't used. MIDI2 seems to do it better, and the interface wasn't satisfying. ## Stabilize factory * `CLAP_PRESET_DISCOVERY_FACTORY_ID` diff --git a/include/clap/clap.h b/include/clap/clap.h index b1d90614..ad95ff33 100644 --- a/include/clap/clap.h +++ b/include/clap/clap.h @@ -67,7 +67,6 @@ #include "ext/draft/ambisonic.h" #include "ext/draft/cv.h" -#include "ext/draft/midi-mappings.h" #include "ext/draft/resource-directory.h" #include "ext/draft/triggers.h" #include "ext/draft/tuning.h" diff --git a/include/clap/ext/draft/midi-mappings.h b/include/clap/ext/draft/midi-mappings.h deleted file mode 100644 index c584e9d8..00000000 --- a/include/clap/ext/draft/midi-mappings.h +++ /dev/null @@ -1,41 +0,0 @@ -#pragma once - -#include "../../plugin.h" - -static CLAP_CONSTEXPR const char CLAP_EXT_MIDI_MAPPINGS[] = "clap.midi-mappings.draft/0"; - -#ifdef __cplusplus -extern "C" { -#endif - -enum { - CLAP_MIDI_MAPPING_CC7, - CLAP_MIDI_MAPPING_CC14, - CLAP_MIDI_MAPPING_RPN, - CLAP_MIDI_MAPPING_NRPN, -}; -typedef int32_t clap_midi_mapping_type; - -typedef struct clap_midi_mapping { - int32_t channel; - int32_t number; - clap_id param_id; -} clap_midi_mapping_t; - -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; - -typedef struct clap_host_midi_mappings { - // [main-thread] - void(CLAP_ABI *changed)(const clap_host_t *host); -} clap_host_midi_mappings_t; - -#ifdef __cplusplus -} -#endif From a44b93b32120d764014e7284e738228b43dbc669 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Mon, 8 Jan 2024 12:46:20 +0100 Subject: [PATCH 46/85] Rework the extension list in the readme --- README.md | 42 +++++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 4354567e..0d3a99b9 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ - [Extensions](#extensions) - [Fundamental extensions](#fundamental-extensions) - [Support extensions](#support-extensions) - - [Extra extensions](#extra-extensions) + - [Deeper Host integration](#deeper-host-integration) - [Third-party extensions](#third-party-extensions) - [Adapters](#adapters) - [Resources](#resources) @@ -81,33 +81,45 @@ You can create your own extensions and share them. Make sure that the extension This is a list of the extensions that you most likely want to implement and use to get a basic plugin experience: -- [log](include/clap/ext/log.h), lets the host aggregate plugin logs -- [thread-check](include/clap/ext/thread-check.h), check which thread you are currently on, useful for correctness validation -- [audio-ports](include/clap/ext/audio-ports.h), define the audio ports -- [note-ports](include/clap/ext/note-ports.h), define the note ports +- [state](include/clap/ext/state.h), save and load the plugin state + - [state-context](include/clap/ext/state-context.h), same as state but with additional context info (preset, duplicate, project) + - [resource-directory](include/clap/ext/draft/resource-directory.h), host provided folder for the plugin to save extra resource like multi-samples, ... (draft) - [params](include/clap/ext/params.h), parameters management -- [latency](include/clap/ext/latency.h), report the plugin latency +- [note-ports](include/clap/ext/note-ports.h), define the note ports +- [audio-ports](include/clap/ext/audio-ports.h), define the audio ports + - [surround](include/clap/ext/surround.h), inspect surround channel mapping + - [ambisonic](include/clap/ext/draft/ambisonic.h), inspect ambisonic channel mapping (draft) + - [cv](include/clap/ext/draft/cv.h), inspect CV channel mapping (draft) + - [configurable-audio-ports](include/clap/ext/configurable-audio-ports.h), request the plugin to apply a given configuration + - [audio-ports-config](include/clap/ext/audio-ports-config.h), simple list of pre-defined audio ports configurations + - [audio-ports-activation](include/clap/ext/audio-ports-activation.h), activate and deactivate a given audio port + - [extensible-audio-ports](include/clap/ext/draft/extensible-audio-ports.h), let the host add audio ports to the plugin, this is useful for dynamic number of audio inputs (draft) - [render](include/clap/ext/render.h), renders realtime or offline +- [latency](include/clap/ext/latency.h), report the plugin latency - [tail](include/clap/ext/tail.h), processing tail length -- [state](include/clap/ext/state.h), save and load the plugin state - [gui](include/clap/ext/gui.h), generic gui controller +- [voice-info](include/clap/ext/voice-info.h), let the host know how many voices the plugin has, this is important for polyphonic modulations +- [track-info](include/clap/ext/track-info.h), give some info to the plugin about the track it belongs to +- [tuning](include/clap/ext/draft/tuning.h), host provided microtuning (draft) +- [triggers](include/clap/ext/draft/triggers.h), plugin's triggers, similar to parameters but stateless ## Support extensions +- [thread-check](include/clap/ext/thread-check.h), check which thread you are currently on, useful for correctness validation - [thread-pool](include/clap/ext/thread-pool.h), use the host thread pool +- [log](include/clap/ext/log.h), lets the host aggregate plugin logs - [timer-support](include/clap/ext/timer-support.h), lets the plugin register timer handlers - [posix-fd-support](include/clap/ext/posix-fd-support.h), lets the plugin register I/O handlers -## Extra extensions +## Deeper Host integration +- [remote-controls](include/clap/ext/remote-controls.h), bank of controls that can be mapped on a controlles with 8 knobs +- [preset-discovery](include/clap/factory/preset-discovery.h), let the host index the plugin's preset in their native file format +- [preset-load](include/clap/ext/preset-load.h), let the host ask the plugin to load a preset +- [param-indication](include/clap/ext/param-indication.h), let the plugin know when a physical control is mapped to a parameter and if there is automation data - [note-name](include/clap/ext/note-name.h), give a name to notes, useful for drum machines -- [tuning](include/clap/ext/draft/tuning.h), host provided microtuning -- [track-info](include/clap/ext/draft/track-info.h) -- [quick-controls](include/clap/ext/draft/quick-controls.h), bank of controls that can be mapped on a controlles with 8 knobs -- [file-reference](include/clap/ext/draft/file-reference.h), let the host know about the plugin's file reference, and perform "Collect & Save" -- [audio-ports-config](include/clap/ext/audio-ports-config.h), simple list of possible configurations -- [surround](include/clap/ext/draft/surround.h), inspect surround channel mapping -- [ambisonic](include/clap/ext/draft/ambisonic.h), inspect ambisonic channel mapping +- [transport-control](include/clap/ext/draft/transport-control.h), let the plugin control the host's transport (draft) +- [context-menu](include/clap/ext/context-menu.h), exchange context menu entries between host and plugin, let the plugin ask the host to popup its own context menu ## Third-party extensions From e11e63b2090f25f5cab19278437003a90faf4377 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Mon, 8 Jan 2024 12:57:35 +0100 Subject: [PATCH 47/85] Finish the exclusion of drafts from `clap.h` --- README.md | 1 + conventions/extension-id.md | 2 ++ include/clap/{draft.h => all.h} | 6 ++++-- src/main.c | 3 +-- src/main.cc | 3 +-- 5 files changed, 9 insertions(+), 6 deletions(-) rename include/clap/{draft.h => all.h} (84%) diff --git a/README.md b/README.md index 0d3a99b9..c8af6ecc 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ 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). +To also include the draft extensions, include [clap/all.h](include/clap/all.h). The two most important objects are `clap_host` and `clap_plugin`. diff --git a/conventions/extension-id.md b/conventions/extension-id.md index b725be8d..c07b22a0 100644 --- a/conventions/extension-id.md +++ b/conventions/extension-id.md @@ -14,8 +14,10 @@ Where: ## Draft An extension is considered a draft extension if it is in the [draft](../include/clap/ext/draft/) folder. +Make sure to also include it in [all.h](../include/clap/all.h). When the extension is migrating from draft to stable, its extension ID must not change. +Move its inclusion from [all.h](../include/clap/all.h) into [clap.h](../include/clap/clap.h). All extensions must go though the draft phase first. diff --git a/include/clap/draft.h b/include/clap/all.h similarity index 84% rename from include/clap/draft.h rename to include/clap/all.h index 7d5f6a34..40e83469 100644 --- a/include/clap/draft.h +++ b/include/clap/all.h @@ -1,12 +1,14 @@ #pragma once +#include "clap.h" + #include "factory/draft/plugin-invalidation.h" #include "factory/draft/plugin-state-converter.h" #include "ext/draft/ambisonic.h" #include "ext/draft/cv.h" -#include "ext/draft/midi-mappings.h" +#include "ext/draft/extensible-audio-ports.h" #include "ext/draft/resource-directory.h" +#include "ext/draft/transport-control.h" #include "ext/draft/triggers.h" #include "ext/draft/tuning.h" -#include "ext/draft/extensible-audio-ports.h" diff --git a/src/main.c b/src/main.c index f4db6b79..eaeb5251 100644 --- a/src/main.c +++ b/src/main.c @@ -1,5 +1,4 @@ -#include -#include +#include // The purpose of this file is to check that all headers compile int main(int argc, char **argv) { diff --git a/src/main.cc b/src/main.cc index 1071d67d..fcf64a69 100644 --- a/src/main.cc +++ b/src/main.cc @@ -1,5 +1,4 @@ -#include -#include +#include // The purpose of this file is to check that all headers compile From 190771aee220777e6dc997baaf7b5ca28365ca9d Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Mon, 8 Jan 2024 13:02:00 +0100 Subject: [PATCH 48/85] Remove the cv ext --- ChangeLog.md | 1 + README.md | 1 - include/clap/all.h | 1 - include/clap/ext/audio-ports.h | 1 - include/clap/ext/draft/cv.h | 44 ---------------------------------- 5 files changed, 1 insertion(+), 47 deletions(-) delete mode 100644 include/clap/ext/draft/cv.h diff --git a/ChangeLog.md b/ChangeLog.md index 6aa544f5..7c511c90 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -18,6 +18,7 @@ Note: we kept the last draft extension ID in order to not break plugins already * `CLAP_EXT_CHECK_FOR_UPDATE` wasn't used and it's design needed more thought. * `CLAP_EXT_MIDI_MAPPING` wasn't used. MIDI2 seems to do it better, and the interface wasn't satisfying. +* `CLAP_EXT_CV` the interface wasn't satisfying. ## Stabilize factory * `CLAP_PRESET_DISCOVERY_FACTORY_ID` diff --git a/README.md b/README.md index c8af6ecc..54da3ab0 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,6 @@ and use to get a basic plugin experience: - [audio-ports](include/clap/ext/audio-ports.h), define the audio ports - [surround](include/clap/ext/surround.h), inspect surround channel mapping - [ambisonic](include/clap/ext/draft/ambisonic.h), inspect ambisonic channel mapping (draft) - - [cv](include/clap/ext/draft/cv.h), inspect CV channel mapping (draft) - [configurable-audio-ports](include/clap/ext/configurable-audio-ports.h), request the plugin to apply a given configuration - [audio-ports-config](include/clap/ext/audio-ports-config.h), simple list of pre-defined audio ports configurations - [audio-ports-activation](include/clap/ext/audio-ports-activation.h), activate and deactivate a given audio port diff --git a/include/clap/all.h b/include/clap/all.h index 40e83469..0b3cc230 100644 --- a/include/clap/all.h +++ b/include/clap/all.h @@ -6,7 +6,6 @@ #include "factory/draft/plugin-state-converter.h" #include "ext/draft/ambisonic.h" -#include "ext/draft/cv.h" #include "ext/draft/extensible-audio-ports.h" #include "ext/draft/resource-directory.h" #include "ext/draft/transport-control.h" diff --git a/include/clap/ext/audio-ports.h b/include/clap/ext/audio-ports.h index 74b94c32..39880493 100644 --- a/include/clap/ext/audio-ports.h +++ b/include/clap/ext/audio-ports.h @@ -54,7 +54,6 @@ typedef struct clap_audio_port_info { // - CLAP_PORT_STEREO // - CLAP_PORT_SURROUND (defined in the surround extension) // - CLAP_PORT_AMBISONIC (defined in the ambisonic extension) - // - CLAP_PORT_CV (defined in the cv extension) // // An extension can provide its own port type and way to inspect the channels. const char *port_type; diff --git a/include/clap/ext/draft/cv.h b/include/clap/ext/draft/cv.h deleted file mode 100644 index 343c836c..00000000 --- a/include/clap/ext/draft/cv.h +++ /dev/null @@ -1,44 +0,0 @@ -#pragma once - -#include "../../plugin.h" - -// This extension can be used to specify the cv channel type used by the plugin. -// Work in progress, suggestions are welcome - -static CLAP_CONSTEXPR const char CLAP_EXT_CV[] = "clap.cv.draft/0"; -static CLAP_CONSTEXPR const char CLAP_PORT_CV[] = "cv"; - -#ifdef __cplusplus -extern "C" { -#endif - -enum { - // TODO: standardize values? - CLAP_CV_VALUE = 0, - CLAP_CV_GATE = 1, - CLAP_CV_PITCH = 2, -}; - -// TODO: maybe we want a channel_info instead, where we could have more details about the supported -// ranges? - -typedef struct clap_plugin_cv { - // Returns true on success. - // [main-thread] - bool(CLAP_ABI *get_channel_type)(const clap_plugin_t *plugin, - bool is_input, - uint32_t port_index, - uint32_t channel_index, - uint32_t *channel_type); -} clap_plugin_cv_t; - -typedef struct clap_host_cv { - // Informs the host that the channels type have changed. - // The channels type can only change when the plugin is de-activated. - // [main-thread,!active] - void(CLAP_ABI *changed)(const clap_host_t *host); -} clap_host_cv_t; - -#ifdef __cplusplus -} -#endif From cbe6b6b7a05811b730075d5c6697be52fdfe30fe Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Mon, 8 Jan 2024 13:06:13 +0100 Subject: [PATCH 49/85] Update remaining drafts to use the new convention for extension id --- ChangeLog.md | 1 + include/clap/ext/draft/ambisonic.h | 2 +- include/clap/ext/draft/extensible-audio-ports.h | 2 +- include/clap/ext/draft/resource-directory.h | 2 +- include/clap/ext/draft/transport-control.h | 2 +- include/clap/ext/draft/triggers.h | 2 +- include/clap/ext/draft/tuning.h | 2 +- include/clap/factory/draft/plugin-invalidation.h | 2 +- 8 files changed, 8 insertions(+), 7 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 7c511c90..b4f5f47c 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -13,6 +13,7 @@ * `CLAP_EXT_TRACK_INFO` Note: we kept the last draft extension ID in order to not break plugins already using it. +Note: remaining draft extension ID as been updated to follow the new convention. ## Removed draft extensions diff --git a/include/clap/ext/draft/ambisonic.h b/include/clap/ext/draft/ambisonic.h index 556af9a6..cf335c49 100644 --- a/include/clap/ext/draft/ambisonic.h +++ b/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/3"; +static CLAP_CONSTEXPR const char CLAP_EXT_AMBISONIC[] = "clap.ambisonic/3"; static CLAP_CONSTEXPR const char CLAP_PORT_AMBISONIC[] = "ambisonic"; diff --git a/include/clap/ext/draft/extensible-audio-ports.h b/include/clap/ext/draft/extensible-audio-ports.h index 278594b5..8f97b0c9 100644 --- a/include/clap/ext/draft/extensible-audio-ports.h +++ b/include/clap/ext/draft/extensible-audio-ports.h @@ -8,7 +8,7 @@ extern "C" { // 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"; + "clap.extensible-audio-ports/1"; 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. diff --git a/include/clap/ext/draft/resource-directory.h b/include/clap/ext/draft/resource-directory.h index fc65eaa8..6b8bd57e 100644 --- a/include/clap/ext/draft/resource-directory.h +++ b/include/clap/ext/draft/resource-directory.h @@ -2,7 +2,7 @@ #include "../../plugin.h" -static CLAP_CONSTEXPR const char CLAP_EXT_RESOURCE_DIRECTORY[] = "clap.resource-directory.draft/0"; +static CLAP_CONSTEXPR const char CLAP_EXT_RESOURCE_DIRECTORY[] = "clap.resource-directory/1"; #ifdef __cplusplus extern "C" { diff --git a/include/clap/ext/draft/transport-control.h b/include/clap/ext/draft/transport-control.h index 8a7e7b51..8085ceea 100644 --- a/include/clap/ext/draft/transport-control.h +++ b/include/clap/ext/draft/transport-control.h @@ -6,7 +6,7 @@ // The host has no obligation to execute these requests, so the interface may be // partially working. -static CLAP_CONSTEXPR const char CLAP_EXT_TRANSPORT_CONTROL[] = "clap.transport-control.draft/0"; +static CLAP_CONSTEXPR const char CLAP_EXT_TRANSPORT_CONTROL[] = "clap.transport-control/1"; #ifdef __cplusplus extern "C" { diff --git a/include/clap/ext/draft/triggers.h b/include/clap/ext/draft/triggers.h index fa1e83a9..bf85dee5 100644 --- a/include/clap/ext/draft/triggers.h +++ b/include/clap/ext/draft/triggers.h @@ -4,7 +4,7 @@ #include "../../events.h" #include "../../string-sizes.h" -static CLAP_CONSTEXPR const char CLAP_EXT_TRIGGERS[] = "clap.triggers.draft/0"; +static CLAP_CONSTEXPR const char CLAP_EXT_TRIGGERS[] = "clap.triggers/1"; #ifdef __cplusplus extern "C" { diff --git a/include/clap/ext/draft/tuning.h b/include/clap/ext/draft/tuning.h index db8d9764..ae668b13 100644 --- a/include/clap/ext/draft/tuning.h +++ b/include/clap/ext/draft/tuning.h @@ -4,7 +4,7 @@ #include "../../events.h" #include "../../string-sizes.h" -static CLAP_CONSTEXPR const char CLAP_EXT_TUNING[] = "clap.tuning.draft/2"; +static CLAP_CONSTEXPR const char CLAP_EXT_TUNING[] = "clap.tuning/2"; #ifdef __cplusplus extern "C" { diff --git a/include/clap/factory/draft/plugin-invalidation.h b/include/clap/factory/draft/plugin-invalidation.h index ea698e55..7f65dd04 100644 --- a/include/clap/factory/draft/plugin-invalidation.h +++ b/include/clap/factory/draft/plugin-invalidation.h @@ -6,7 +6,7 @@ // Use it to retrieve const clap_plugin_invalidation_factory_t* from // clap_plugin_entry.get_factory() static const CLAP_CONSTEXPR char CLAP_PLUGIN_INVALIDATION_FACTORY_ID[] = - "clap.plugin-invalidation-factory/draft0"; + "clap.plugin-invalidation-factory/1"; #ifdef __cplusplus extern "C" { From a898dee7734edbd1982932f795865766a38930aa Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 10 Jan 2024 09:21:28 +0100 Subject: [PATCH 50/85] Update include/clap/entry.h Co-authored-by: Dalton Messmer --- include/clap/entry.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/entry.h b/include/clap/entry.h index 44747224..3d148a6d 100644 --- a/include/clap/entry.h +++ b/include/clap/entry.h @@ -47,7 +47,7 @@ extern "C" { // space, both the host and the wrapper will call init() and deinit() and have no means to communicate // the state. // -// With clap 1.1.11 and beyond we are changing the spec to indicate that a host should make an +// With CLAP 1.2.0 and beyond we are changing the spec to indicate that a host should make an // absolute best effort to call init() and deinit() once, and always in matched pairs (for every // init() which returns true, one deinit() should be called). // From 56f7f36460c40c60ed8d40b6903bf83b950c25e7 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 10 Jan 2024 09:23:41 +0100 Subject: [PATCH 51/85] Update include/clap/entry.h Co-authored-by: Dalton Messmer --- include/clap/entry.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/entry.h b/include/clap/entry.h index 3d148a6d..1fbf154e 100644 --- a/include/clap/entry.h +++ b/include/clap/entry.h @@ -39,7 +39,7 @@ extern "C" { // // The intent of the init() and deinit() functions is to provide a "normal" initialization patterh // which occurs when the shared object is loaded or unloaded. As such, hosts will call each once and -// in matched pairs. In clap specifications prior to 1.1.11, this single-call was documented as a +// in matched pairs. In CLAP specifications prior to 1.2.0, this single-call was documented as a // requirement. // // We realized, though, that this is not a requirement hosts can meet. If hosts load a plugin From fb4937c5d1ca75a9f9c2e5c4b2b5b9b0e7aca4d6 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 10 Jan 2024 09:23:51 +0100 Subject: [PATCH 52/85] Update include/clap/entry.h Co-authored-by: Dalton Messmer --- include/clap/entry.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/entry.h b/include/clap/entry.h index 1fbf154e..ebc75447 100644 --- a/include/clap/entry.h +++ b/include/clap/entry.h @@ -108,7 +108,7 @@ typedef struct clap_plugin_entry { // // As stated above, even though hosts are forbidden to do so directly, multiple calls before any // new init() call may still happen. Implementations *should* take this into account, and *must* - // do so as of CLAP 1.11. + // do so as of CLAP 1.2.0. // // Just like init(), this function may be called on any thread, including a different one from // the one init() was called from, or from the one a later init() call can be made. From d850a7cc57ef4f0ce2a3dd32707adaabddb911a9 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 10 Jan 2024 09:23:59 +0100 Subject: [PATCH 53/85] Update include/clap/entry.h Co-authored-by: Dalton Messmer --- include/clap/entry.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/entry.h b/include/clap/entry.h index ebc75447..abb92f30 100644 --- a/include/clap/entry.h +++ b/include/clap/entry.h @@ -73,7 +73,7 @@ typedef struct clap_plugin_entry { // // As stated above, even though hosts are forbidden to do so directly, multiple calls before any // deinit() call may still happen. Implementations *should* take this into account, and *must* - // do so as of CLAP 1.11. + // do so as of CLAP 1.2.0. // // It should be as fast as possible, in order to perform a very quick scan of the plugin // descriptors. From ea9cecf94ddd8f97c0da6e68a34fe329fa0b575c Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 10 Jan 2024 09:56:34 +0100 Subject: [PATCH 54/85] Make ambisonic stable --- ChangeLog.md | 1 + README.md | 4 ++-- include/clap/all.h | 1 - include/clap/clap.h | 1 + include/clap/ext/{draft => }/ambisonic.h | 2 +- include/clap/ext/track-info.h | 4 +++- 6 files changed, 8 insertions(+), 5 deletions(-) rename include/clap/ext/{draft => }/ambisonic.h (98%) diff --git a/ChangeLog.md b/ChangeLog.md index b4f5f47c..7787b128 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -2,6 +2,7 @@ ## Stabilize extensions +* `CLAP_EXT_AMBISONIC` * `CLAP_EXT_AUDIO_PORTS_ACTIVATION` * `CLAP_EXT_CONFIGURABLE_AUDIO_PORTS` * `CLAP_EXT_CONTEXT_MENU` diff --git a/README.md b/README.md index 54da3ab0..78c628d6 100644 --- a/README.md +++ b/README.md @@ -89,9 +89,9 @@ and use to get a basic plugin experience: - [note-ports](include/clap/ext/note-ports.h), define the note ports - [audio-ports](include/clap/ext/audio-ports.h), define the audio ports - [surround](include/clap/ext/surround.h), inspect surround channel mapping - - [ambisonic](include/clap/ext/draft/ambisonic.h), inspect ambisonic channel mapping (draft) + - [ambisonic](include/clap/ext/draft/ambisonic.h), inspect ambisonic channel mapping - [configurable-audio-ports](include/clap/ext/configurable-audio-ports.h), request the plugin to apply a given configuration - - [audio-ports-config](include/clap/ext/audio-ports-config.h), simple list of pre-defined audio ports configurations + - [audio-ports-config](include/clap/ext/audio-ports-config.h), simple list of pre-defined audio ports configurations, meant to be exposed to the user - [audio-ports-activation](include/clap/ext/audio-ports-activation.h), activate and deactivate a given audio port - [extensible-audio-ports](include/clap/ext/draft/extensible-audio-ports.h), let the host add audio ports to the plugin, this is useful for dynamic number of audio inputs (draft) - [render](include/clap/ext/render.h), renders realtime or offline diff --git a/include/clap/all.h b/include/clap/all.h index 0b3cc230..45412475 100644 --- a/include/clap/all.h +++ b/include/clap/all.h @@ -5,7 +5,6 @@ #include "factory/draft/plugin-invalidation.h" #include "factory/draft/plugin-state-converter.h" -#include "ext/draft/ambisonic.h" #include "ext/draft/extensible-audio-ports.h" #include "ext/draft/resource-directory.h" #include "ext/draft/transport-control.h" diff --git a/include/clap/clap.h b/include/clap/clap.h index a9874878..b37328a2 100644 --- a/include/clap/clap.h +++ b/include/clap/clap.h @@ -35,6 +35,7 @@ #include "host.h" #include "plugin-id.h" +#include "ext/ambisonic.h" #include "ext/audio-ports-activation.h" #include "ext/audio-ports-config.h" #include "ext/audio-ports.h" diff --git a/include/clap/ext/draft/ambisonic.h b/include/clap/ext/ambisonic.h similarity index 98% rename from include/clap/ext/draft/ambisonic.h rename to include/clap/ext/ambisonic.h index cf335c49..b213b41a 100644 --- a/include/clap/ext/draft/ambisonic.h +++ b/include/clap/ext/ambisonic.h @@ -1,6 +1,6 @@ #pragma once -#include "../../plugin.h" +#include "../plugin.h" // This extension can be used to specify the channel mapping used by the plugin. diff --git a/include/clap/ext/track-info.h b/include/clap/ext/track-info.h index 2d96473c..7114a6be 100644 --- a/include/clap/ext/track-info.h +++ b/include/clap/ext/track-info.h @@ -7,7 +7,9 @@ // 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 configuration regarding audio port type and channel count. - +// +// This extension ID contains `draft', yet it is stable. +// See conventions/extension-id.md for more info. static CLAP_CONSTEXPR const char CLAP_EXT_TRACK_INFO[] = "clap.track-info.draft/1"; #ifdef __cplusplus From 12ca18f99c77d480eb0d5a71353ee0974ae8204f Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 10 Jan 2024 10:13:20 +0100 Subject: [PATCH 55/85] Add a note regarding the extension id containing draft --- include/clap/ext/ambisonic.h | 6 ++++-- include/clap/ext/audio-ports-activation.h | 2 ++ include/clap/ext/audio-ports-config.h | 3 +++ include/clap/ext/configurable-audio-ports.h | 3 +++ include/clap/ext/context-menu.h | 2 ++ include/clap/ext/param-indication.h | 2 ++ include/clap/ext/preset-load.h | 2 ++ include/clap/ext/remote-controls.h | 2 ++ include/clap/ext/surround.h | 2 ++ 9 files changed, 22 insertions(+), 2 deletions(-) diff --git a/include/clap/ext/ambisonic.h b/include/clap/ext/ambisonic.h index b213b41a..7ac1bfd6 100644 --- a/include/clap/ext/ambisonic.h +++ b/include/clap/ext/ambisonic.h @@ -3,8 +3,10 @@ #include "../plugin.h" // This extension can be used to specify the channel mapping used by the plugin. - -static CLAP_CONSTEXPR const char CLAP_EXT_AMBISONIC[] = "clap.ambisonic/3"; +// +// This extension ID contains `draft', yet it is stable. +// See conventions/extension-id.md for more info. +static CLAP_CONSTEXPR const char CLAP_EXT_AMBISONIC[] = "clap.ambisonic.draft/3"; static CLAP_CONSTEXPR const char CLAP_PORT_AMBISONIC[] = "ambisonic"; diff --git a/include/clap/ext/audio-ports-activation.h b/include/clap/ext/audio-ports-activation.h index a3c1184b..a138a63d 100644 --- a/include/clap/ext/audio-ports-activation.h +++ b/include/clap/ext/audio-ports-activation.h @@ -25,6 +25,8 @@ /// Audio ports state is invalidated by clap_plugin_audio_ports_config.select() and /// clap_host_audio_ports.rescan(CLAP_AUDIO_PORTS_RESCAN_LIST). +// This extension ID contains `draft', yet it is stable. +// See conventions/extension-id.md for more info. static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_ACTIVATION[] = "clap.audio-ports-activation/draft-2"; diff --git a/include/clap/ext/audio-ports-config.h b/include/clap/ext/audio-ports-config.h index 4627154c..0f56f1dc 100644 --- a/include/clap/ext/audio-ports-config.h +++ b/include/clap/ext/audio-ports-config.h @@ -26,6 +26,9 @@ /// 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"; + +// This extension ID contains `draft', yet it is stable. +// See conventions/extension-id.md for more info. static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_CONFIG_INFO[] = "clap.audio-ports-config-info/draft-0"; diff --git a/include/clap/ext/configurable-audio-ports.h b/include/clap/ext/configurable-audio-ports.h index 9b0ffffb..56a462bd 100644 --- a/include/clap/ext/configurable-audio-ports.h +++ b/include/clap/ext/configurable-audio-ports.h @@ -8,6 +8,9 @@ extern "C" { // This extension lets the host configure the plugin's input and output audio ports. // This is a "push" approach to audio ports configuration. + +// This extension ID contains `draft', yet it is stable. +// See conventions/extension-id.md for more info. static CLAP_CONSTEXPR const char CLAP_EXT_CONFIGURABLE_AUDIO_PORTS[] = "clap.configurable-audio-ports.draft1"; diff --git a/include/clap/ext/context-menu.h b/include/clap/ext/context-menu.h index 0864e3a2..1ef40023 100644 --- a/include/clap/ext/context-menu.h +++ b/include/clap/ext/context-menu.h @@ -5,6 +5,8 @@ // This extension lets the host and plugin exchange menu items and let the plugin ask the host to // show its context menu. +// This extension ID contains `draft', yet it is stable. +// See conventions/extension-id.md for more info. static CLAP_CONSTEXPR const char CLAP_EXT_CONTEXT_MENU[] = "clap.context-menu.draft/0"; #ifdef __cplusplus diff --git a/include/clap/ext/param-indication.h b/include/clap/ext/param-indication.h index 1d804aa1..a2d8d685 100644 --- a/include/clap/ext/param-indication.h +++ b/include/clap/ext/param-indication.h @@ -13,6 +13,8 @@ // The color semantic depends upon the host here and the goal is to have a consistent experience // across all plugins. +// This extension ID contains `draft', yet it is stable. +// See conventions/extension-id.md for more info. static CLAP_CONSTEXPR const char CLAP_EXT_PARAM_INDICATION[] = "clap.param-indication.draft/4"; #ifdef __cplusplus diff --git a/include/clap/ext/preset-load.h b/include/clap/ext/preset-load.h index ddd805de..8b76a0a7 100644 --- a/include/clap/ext/preset-load.h +++ b/include/clap/ext/preset-load.h @@ -2,6 +2,8 @@ #include "../plugin.h" +// This extension ID contains `draft', yet it is stable. +// See conventions/extension-id.md for more info. static const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load.draft/2"; #ifdef __cplusplus diff --git a/include/clap/ext/remote-controls.h b/include/clap/ext/remote-controls.h index f467d70a..ad045faa 100644 --- a/include/clap/ext/remote-controls.h +++ b/include/clap/ext/remote-controls.h @@ -31,6 +31,8 @@ // Pressing that button once gets you to the first page of the section. // Press it again to cycle through the section's pages. +// This extension ID contains `draft', yet it is stable. +// See conventions/extension-id.md for more info. static CLAP_CONSTEXPR const char CLAP_EXT_REMOTE_CONTROLS[] = "clap.remote-controls.draft/2"; #ifdef __cplusplus diff --git a/include/clap/ext/surround.h b/include/clap/ext/surround.h index 77348f6a..ce85886c 100644 --- a/include/clap/ext/surround.h +++ b/include/clap/ext/surround.h @@ -24,6 +24,8 @@ // 3. host calls clap_plugin_surround->get_channel_map() // 4. host activates the plugin and can start processing audio +// This extension ID contains `draft', yet it is stable. +// See conventions/extension-id.md for more info. static CLAP_CONSTEXPR const char CLAP_EXT_SURROUND[] = "clap.surround.draft/4"; static CLAP_CONSTEXPR const char CLAP_PORT_SURROUND[] = "surround"; From 3aa3165fe9c23b71cf31b914450a5cd1a2fd4805 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 12 Jan 2024 10:19:00 +0100 Subject: [PATCH 56/85] Remove draft from the extension id --- conventions/extension-id.md | 5 +++-- include/clap/ext/audio-ports-activation.h | 7 +++++-- include/clap/ext/audio-ports-config.h | 7 +++++-- include/clap/ext/configurable-audio-ports.h | 7 +++++-- include/clap/ext/context-menu.h | 8 +++++--- include/clap/ext/preset-load.h | 8 +++++--- include/clap/ext/remote-controls.h | 7 ++++--- include/clap/ext/state-context.h | 6 +++++- include/clap/ext/surround.h | 8 +++++--- include/clap/ext/track-info.h | 10 ++++++---- include/clap/factory/preset-discovery.h | 4 ++++ 11 files changed, 52 insertions(+), 25 deletions(-) diff --git a/conventions/extension-id.md b/conventions/extension-id.md index c07b22a0..2ec9399d 100644 --- a/conventions/extension-id.md +++ b/conventions/extension-id.md @@ -28,5 +28,6 @@ Everything about the extension id symmetrically applies to factory id. ## History Before this document was written, existing extensions didn't honor these rules. -Some stable extensions include the string `draft` in their ID. -We decided to keep those in order to maintain binary compatibility. \ No newline at end of file +We wanted to stabilize some extension without breaking the compatibility, yet the extension ID contained the string `draft`. +While this isn't user facing, we wanted to get rid of it, so we updated the extension ID according to this document and +introduced a `XXX_COMPAT` ID to provide backward compatibility with the draft version. diff --git a/include/clap/ext/audio-ports-activation.h b/include/clap/ext/audio-ports-activation.h index a138a63d..f63085c5 100644 --- a/include/clap/ext/audio-ports-activation.h +++ b/include/clap/ext/audio-ports-activation.h @@ -25,9 +25,12 @@ /// Audio ports state is invalidated by clap_plugin_audio_ports_config.select() and /// clap_host_audio_ports.rescan(CLAP_AUDIO_PORTS_RESCAN_LIST). -// This extension ID contains `draft', yet it is stable. -// See conventions/extension-id.md for more info. static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_ACTIVATION[] = + "clap.audio-ports-activation/2"; + +// The latest draft is 100% compatible. +// This compat ID may be removed in 2026. +static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_ACTIVATION_COMPAT[] = "clap.audio-ports-activation/draft-2"; #ifdef __cplusplus diff --git a/include/clap/ext/audio-ports-config.h b/include/clap/ext/audio-ports-config.h index 0f56f1dc..2ab86573 100644 --- a/include/clap/ext/audio-ports-config.h +++ b/include/clap/ext/audio-ports-config.h @@ -27,9 +27,12 @@ static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_CONFIG[] = "clap.audio-ports-config"; -// This extension ID contains `draft', yet it is stable. -// See conventions/extension-id.md for more info. static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_CONFIG_INFO[] = + "clap.audio-ports-config-info/1"; + +// The latest draft is 100% compatible. +// This compat ID may be removed in 2026. +static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_CONFIG_INFO_COMPAT[] = "clap.audio-ports-config-info/draft-0"; #ifdef __cplusplus diff --git a/include/clap/ext/configurable-audio-ports.h b/include/clap/ext/configurable-audio-ports.h index 56a462bd..86688e71 100644 --- a/include/clap/ext/configurable-audio-ports.h +++ b/include/clap/ext/configurable-audio-ports.h @@ -9,9 +9,12 @@ extern "C" { // This extension lets the host configure the plugin's input and output audio ports. // This is a "push" approach to audio ports configuration. -// This extension ID contains `draft', yet it is stable. -// See conventions/extension-id.md for more info. static CLAP_CONSTEXPR const char CLAP_EXT_CONFIGURABLE_AUDIO_PORTS[] = + "clap.configurable-audio-ports/1"; + +// The latest draft is 100% compatible. +// This compat ID may be removed in 2026. +static CLAP_CONSTEXPR const char CLAP_EXT_CONFIGURABLE_AUDIO_PORTS_COMPAT[] = "clap.configurable-audio-ports.draft1"; typedef struct clap_audio_port_configuration_request { diff --git a/include/clap/ext/context-menu.h b/include/clap/ext/context-menu.h index 1ef40023..293f59a8 100644 --- a/include/clap/ext/context-menu.h +++ b/include/clap/ext/context-menu.h @@ -5,9 +5,11 @@ // This extension lets the host and plugin exchange menu items and let the plugin ask the host to // show its context menu. -// This extension ID contains `draft', yet it is stable. -// See conventions/extension-id.md for more info. -static CLAP_CONSTEXPR const char CLAP_EXT_CONTEXT_MENU[] = "clap.context-menu.draft/0"; +static CLAP_CONSTEXPR const char CLAP_EXT_CONTEXT_MENU[] = "clap.context-menu/1"; + +// The latest draft is 100% compatible. +// This compat ID may be removed in 2026. +static CLAP_CONSTEXPR const char CLAP_EXT_CONTEXT_MENU_COMPAT[] = "clap.context-menu.draft/0"; #ifdef __cplusplus extern "C" { diff --git a/include/clap/ext/preset-load.h b/include/clap/ext/preset-load.h index 8b76a0a7..3dbf7375 100644 --- a/include/clap/ext/preset-load.h +++ b/include/clap/ext/preset-load.h @@ -2,9 +2,11 @@ #include "../plugin.h" -// This extension ID contains `draft', yet it is stable. -// See conventions/extension-id.md for more info. -static const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load.draft/2"; +static const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load/2"; + +// The latest draft is 100% compatible. +// This compat ID may be removed in 2026. +static const char CLAP_EXT_PRESET_LOAD_COMPAT[] = "clap.preset-load.draft/2"; #ifdef __cplusplus extern "C" { diff --git a/include/clap/ext/remote-controls.h b/include/clap/ext/remote-controls.h index ad045faa..2d4a7d0b 100644 --- a/include/clap/ext/remote-controls.h +++ b/include/clap/ext/remote-controls.h @@ -31,9 +31,10 @@ // Pressing that button once gets you to the first page of the section. // Press it again to cycle through the section's pages. -// This extension ID contains `draft', yet it is stable. -// See conventions/extension-id.md for more info. -static CLAP_CONSTEXPR const char CLAP_EXT_REMOTE_CONTROLS[] = "clap.remote-controls.draft/2"; +static CLAP_CONSTEXPR const char CLAP_EXT_REMOTE_CONTROLS[] = "clap.remote-controls/2"; + +// The latest draft is 100% compatible +static CLAP_CONSTEXPR const char CLAP_EXT_REMOTE_CONTROLS_COMPAT[] = "clap.remote-controls.draft/2"; #ifdef __cplusplus extern "C" { diff --git a/include/clap/ext/state-context.h b/include/clap/ext/state-context.h index 20248b37..d4c05930 100644 --- a/include/clap/ext/state-context.h +++ b/include/clap/ext/state-context.h @@ -32,7 +32,11 @@ extern "C" { #endif -static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context/2"; +static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context/1"; + +// The latest draft is 100% compatible. +// This compat ID may be removed in 2026. +static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT_COMPAT[] = "clap.state-context.draft/1"; enum clap_plugin_state_context_type { // suitable for storing and loading a state as a preset diff --git a/include/clap/ext/surround.h b/include/clap/ext/surround.h index ce85886c..7e57c051 100644 --- a/include/clap/ext/surround.h +++ b/include/clap/ext/surround.h @@ -24,9 +24,11 @@ // 3. host calls clap_plugin_surround->get_channel_map() // 4. host activates the plugin and can start processing audio -// This extension ID contains `draft', yet it is stable. -// See conventions/extension-id.md for more info. -static CLAP_CONSTEXPR const char CLAP_EXT_SURROUND[] = "clap.surround.draft/4"; +static CLAP_CONSTEXPR const char CLAP_EXT_SURROUND[] = "clap.surround/4"; + +// The latest draft is 100% compatible. +// This compat ID may be removed in 2026. +static CLAP_CONSTEXPR const char CLAP_EXT_SURROUND_COMPAT[] = "clap.surround.draft/4"; static CLAP_CONSTEXPR const char CLAP_PORT_SURROUND[] = "surround"; diff --git a/include/clap/ext/track-info.h b/include/clap/ext/track-info.h index 7114a6be..3e1a5559 100644 --- a/include/clap/ext/track-info.h +++ b/include/clap/ext/track-info.h @@ -7,10 +7,12 @@ // 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 configuration regarding audio port type and channel count. -// -// This extension ID contains `draft', yet it is stable. -// See conventions/extension-id.md for more info. -static CLAP_CONSTEXPR const char CLAP_EXT_TRACK_INFO[] = "clap.track-info.draft/1"; + +static CLAP_CONSTEXPR const char CLAP_EXT_TRACK_INFO[] = "clap.track-info/1"; + +// The latest draft is 100% compatible. +// This compat ID may be removed in 2026. +static CLAP_CONSTEXPR const char CLAP_EXT_TRACK_INFO_COMPAT[] = "clap.track-info.draft/1"; #ifdef __cplusplus extern "C" { diff --git a/include/clap/factory/preset-discovery.h b/include/clap/factory/preset-discovery.h index 752b3a4b..90be92ef 100644 --- a/include/clap/factory/preset-discovery.h +++ b/include/clap/factory/preset-discovery.h @@ -49,6 +49,10 @@ // Use it to retrieve const clap_preset_discovery_factory_t* from // clap_plugin_entry.get_factory() static const CLAP_CONSTEXPR char CLAP_PRESET_DISCOVERY_FACTORY_ID[] = + "clap.preset-discovery-factory"; + +// The latest draft is 100% compatible +static const CLAP_CONSTEXPR char CLAP_PRESET_DISCOVERY_FACTORY_ID_COMPAT[] = "clap.preset-discovery-factory/draft-2"; #ifdef __cplusplus From 42a9ee2b329e8ea3eef6569f00295ad20a9600d4 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 12 Jan 2024 10:22:30 +0100 Subject: [PATCH 57/85] Update changelog --- ChangeLog.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 7787b128..0b61686e 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,5 +1,9 @@ # Changes in 1.2.0 +## New conventions + +* [extension-id](conventions/extension-id.md): introduce some rules about extension ID naming. + ## Stabilize extensions * `CLAP_EXT_AMBISONIC` @@ -13,8 +17,17 @@ * `CLAP_EXT_SURROUND` * `CLAP_EXT_TRACK_INFO` -Note: we kept the last draft extension ID in order to not break plugins already using it. -Note: remaining draft extension ID as been updated to follow the new convention. +### Notes regarding extension ID change after draft stabilization + +We changed the extension ID in the process of stabilization which leads to a **break**. + +To mitigate this transition, we provide a compatibily extension ID which can be used to match and use the draft extension as they are 100% compatible. + +For example, `CLAP_EXT_CONTEXT_MENU` for the stable ID and `CLAP_EXT_CONTEXT_MENU_COMPAT` for the draft ID. + +As you can see in [extension-id](conventions/extension-id.md), we introduce some rules, so this kind of breaks won't happen again. + +We may decide to remove `CLAP_EXT_CONTEXT_MENU_COMPAT` in the future once their usage becomes anecdotic. ## Removed draft extensions @@ -38,10 +51,6 @@ Note: we kept the last draft factory ID in order to not break plugins already us * [params.h](include/clap/ext/params.h): Fix incorrect function name reference * [latency.h](include/clap/ext/latency.h): Require the plugin to be activated to get the latency and clarify that the latency can only be fetched when the plugin is activated -## Conventions - -* [extension-id](conventions/extension-id.md): introduce some rules about extension ID naming. - ## Plugin Template * [plugin-template.c](src/plugin-template.c): implement thread-safe plugin entry init counter From abcd29bdbe6b25243abc9b1091dce72dce9dd832 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 12 Jan 2024 10:23:05 +0100 Subject: [PATCH 58/85] Update preset-discovery extension id to follow the convention. --- include/clap/factory/preset-discovery.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/factory/preset-discovery.h b/include/clap/factory/preset-discovery.h index 90be92ef..2f788c7b 100644 --- a/include/clap/factory/preset-discovery.h +++ b/include/clap/factory/preset-discovery.h @@ -49,7 +49,7 @@ // Use it to retrieve const clap_preset_discovery_factory_t* from // clap_plugin_entry.get_factory() static const CLAP_CONSTEXPR char CLAP_PRESET_DISCOVERY_FACTORY_ID[] = - "clap.preset-discovery-factory"; + "clap.preset-discovery-factory/2"; // The latest draft is 100% compatible static const CLAP_CONSTEXPR char CLAP_PRESET_DISCOVERY_FACTORY_ID_COMPAT[] = From 522e69d50fbd0bec8268ef997d8da82f9f5fa9e6 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 12 Jan 2024 10:25:41 +0100 Subject: [PATCH 59/85] Missing deprecation notice --- include/clap/factory/preset-discovery.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/include/clap/factory/preset-discovery.h b/include/clap/factory/preset-discovery.h index 2f788c7b..f9c8e434 100644 --- a/include/clap/factory/preset-discovery.h +++ b/include/clap/factory/preset-discovery.h @@ -51,7 +51,8 @@ static const CLAP_CONSTEXPR char CLAP_PRESET_DISCOVERY_FACTORY_ID[] = "clap.preset-discovery-factory/2"; -// The latest draft is 100% compatible +// The latest draft is 100% compatible. +// This compat ID may be removed in 2026. static const CLAP_CONSTEXPR char CLAP_PRESET_DISCOVERY_FACTORY_ID_COMPAT[] = "clap.preset-discovery-factory/draft-2"; From 17e1b524c2e3b812b33df943227ddccd3029239f Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Sat, 13 Jan 2024 10:34:30 +0100 Subject: [PATCH 60/85] Update ChangeLog.md Co-authored-by: Dalton Messmer --- ChangeLog.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 0b61686e..a3342bd5 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -21,13 +21,13 @@ We changed the extension ID in the process of stabilization which leads to a **break**. -To mitigate this transition, we provide a compatibily extension ID which can be used to match and use the draft extension as they are 100% compatible. +To mitigate this transition, we've provided compatibility extension IDs which can be used to match and use the latest draft extensions as they are 100% compatible. For example, `CLAP_EXT_CONTEXT_MENU` for the stable ID and `CLAP_EXT_CONTEXT_MENU_COMPAT` for the draft ID. -As you can see in [extension-id](conventions/extension-id.md), we introduce some rules, so this kind of breaks won't happen again. +As you can see in [extension-id](conventions/extension-id.md), we introduced some rules, so this kind of break won't happen again. -We may decide to remove `CLAP_EXT_CONTEXT_MENU_COMPAT` in the future once their usage becomes anecdotic. +We may decide to remove the `*_COMPAT` IDs in the future once their usage becomes antiquated. ## Removed draft extensions From 11ef4a15b43fbfb030a1660571c8ee32e0aa586a Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Sat, 13 Jan 2024 10:35:49 +0100 Subject: [PATCH 61/85] Update conventions/extension-id.md Co-authored-by: Dalton Messmer --- conventions/extension-id.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/conventions/extension-id.md b/conventions/extension-id.md index 2ec9399d..ab397895 100644 --- a/conventions/extension-id.md +++ b/conventions/extension-id.md @@ -28,6 +28,5 @@ Everything about the extension id symmetrically applies to factory id. ## History Before this document was written, existing extensions didn't honor these rules. -We wanted to stabilize some extension without breaking the compatibility, yet the extension ID contained the string `draft`. -While this isn't user facing, we wanted to get rid of it, so we updated the extension ID according to this document and -introduced a `XXX_COMPAT` ID to provide backward compatibility with the draft version. +We wanted to stabilize some draft extensions without breaking compatibility, yet their extension IDs contained the string `draft`. +While these strings weren't user-facing, we still wanted to remove them, so we updated the extension IDs according to this document and introduced IDs with `_COMPAT` suffixes to provide backward compatibility with the draft versions. From 5373d31fceb6218daf63cdccc9d1c18941212da0 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Sat, 13 Jan 2024 10:36:38 +0100 Subject: [PATCH 62/85] Update include/clap/ext/remote-controls.h Co-authored-by: Dalton Messmer --- include/clap/ext/remote-controls.h | 1 + 1 file changed, 1 insertion(+) diff --git a/include/clap/ext/remote-controls.h b/include/clap/ext/remote-controls.h index 2d4a7d0b..d7bf4fc5 100644 --- a/include/clap/ext/remote-controls.h +++ b/include/clap/ext/remote-controls.h @@ -34,6 +34,7 @@ static CLAP_CONSTEXPR const char CLAP_EXT_REMOTE_CONTROLS[] = "clap.remote-controls/2"; // The latest draft is 100% compatible +// This compat ID may be removed in 2026. static CLAP_CONSTEXPR const char CLAP_EXT_REMOTE_CONTROLS_COMPAT[] = "clap.remote-controls.draft/2"; #ifdef __cplusplus From 5c52b38d7e69256ba1d7a654be0ed043107a692a Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Sat, 13 Jan 2024 10:40:57 +0100 Subject: [PATCH 63/85] Update extension-id.md Apply changes suggested by @messmerd --- conventions/extension-id.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conventions/extension-id.md b/conventions/extension-id.md index ab397895..4b0b5c11 100644 --- a/conventions/extension-id.md +++ b/conventions/extension-id.md @@ -27,6 +27,6 @@ Everything about the extension id symmetrically applies to factory id. ## History -Before this document was written, existing extensions didn't honor these rules. +Before version 1.2.0 when this document was written, existing extensions didn't honor these rules. We wanted to stabilize some draft extensions without breaking compatibility, yet their extension IDs contained the string `draft`. While these strings weren't user-facing, we still wanted to remove them, so we updated the extension IDs according to this document and introduced IDs with `_COMPAT` suffixes to provide backward compatibility with the draft versions. From fa2beac3d9b4242d01741635c4572b015251cd3f Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Mon, 15 Jan 2024 12:08:36 +0100 Subject: [PATCH 64/85] Missed ext id cleanup --- include/clap/ext/param-indication.h | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/include/clap/ext/param-indication.h b/include/clap/ext/param-indication.h index a2d8d685..643a9534 100644 --- a/include/clap/ext/param-indication.h +++ b/include/clap/ext/param-indication.h @@ -13,9 +13,11 @@ // The color semantic depends upon the host here and the goal is to have a consistent experience // across all plugins. -// This extension ID contains `draft', yet it is stable. -// See conventions/extension-id.md for more info. -static CLAP_CONSTEXPR const char CLAP_EXT_PARAM_INDICATION[] = "clap.param-indication.draft/4"; +static CLAP_CONSTEXPR const char CLAP_EXT_PARAM_INDICATION[] = "clap.param-indication/4"; + +// The latest draft is 100% compatible. +// This compat ID may be removed in 2026. +static CLAP_CONSTEXPR const char CLAP_EXT_PARAM_INDICATION_COMPAT[] = "clap.param-indication.draft/4"; #ifdef __cplusplus extern "C" { From 0fc394f0a764d42ec7d3edf6d3c17153db4ebf3b Mon Sep 17 00:00:00 2001 From: Paul Walker Date: Mon, 15 Jan 2024 07:30:39 -0500 Subject: [PATCH 65/85] Expand some note and note expression doc The comments in #380 showed some places where our note and note expression doc had too much implicit knowledge. Try to address that with a few short paragraphs explainign the protocol --- include/clap/events.h | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/include/clap/events.h b/include/clap/events.h index 0839e961..3b451e29 100644 --- a/include/clap/events.h +++ b/include/clap/events.h @@ -151,13 +151,28 @@ enum { typedef struct clap_event_note { clap_event_header_t header; - int32_t note_id; // -1 if unspecified, otherwise >=0 - int16_t port_index; - int16_t channel; // 0..15 - int16_t key; // 0..127 + int32_t note_id; // host provided note id, -1 if unspecified or wildcard + int16_t port_index; // Port index from ext/note-ports; -1 for wildcard + int16_t channel; // 0..15, same as MIDI1 Channel Number, -1 for wildcard + int16_t key; // 0..127, same as MIDI1 Key Number (60==Middle C), -1 for wildcard double velocity; // 0..1 } clap_event_note_t; +// Note Expressions are well named modifications of a voice targeted to +// voices using the same wildcard rules described above. Note Expressions are delivered +// as sample accurate events and should be applied at the sample when received. +// +// Note expressions are a statement of value, not cumulative. A PAN event of 0 followed by 1 +// followed by 0.5 would pan hard left, hard right, and center. They are intended as +// an offset from the non-note-expression voice default. A voice which had a volume of +// -20db absent note expressions which received a +4db note expression would move the +// voice to -16db. +// +// A plugin which receives a note expression at the same sample as a NOTE_ON event +// should apply that expression to all generated samples. A plugin which receives +// a note expression after a NOTE_ON event should initiate the voice with default +// values and then apply the note expression when received. A plugin may make a choice +// to smooth note expression streams. enum { // with 0 < x <= 4, plain = 20 * log(x) CLAP_NOTE_EXPRESSION_VOLUME = 0, @@ -165,7 +180,7 @@ enum { // pan, 0 left, 0.5 center, 1 right CLAP_NOTE_EXPRESSION_PAN = 1, - // relative tuning in semitone, from -120 to +120 + // relative tuning in semitone, from -120 to +120, in equal temperament CLAP_NOTE_EXPRESSION_TUNING = 2, // 0..1 From a0f68596be3edd8c8f5dbf0b23a89b8497510a64 Mon Sep 17 00:00:00 2001 From: Paul Walker Date: Mon, 15 Jan 2024 07:32:33 -0500 Subject: [PATCH 66/85] small tweak --- include/clap/events.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/clap/events.h b/include/clap/events.h index 3b451e29..84978ad0 100644 --- a/include/clap/events.h +++ b/include/clap/events.h @@ -151,8 +151,8 @@ enum { typedef struct clap_event_note { clap_event_header_t header; - int32_t note_id; // host provided note id, -1 if unspecified or wildcard - int16_t port_index; // Port index from ext/note-ports; -1 for wildcard + int32_t note_id; // host provided note id >= 0, or -1 if unspecified or wildcard + int16_t port_index; // port index from ext/note-ports; -1 for wildcard int16_t channel; // 0..15, same as MIDI1 Channel Number, -1 for wildcard int16_t key; // 0..127, same as MIDI1 Key Number (60==Middle C), -1 for wildcard double velocity; // 0..1 From 1e41950725d066fef19175c3dcf01324c6b5c380 Mon Sep 17 00:00:00 2001 From: Paul Walker Date: Mon, 15 Jan 2024 07:59:52 -0500 Subject: [PATCH 67/85] Update changelog per abique request --- ChangeLog.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ChangeLog.md b/ChangeLog.md index a3342bd5..2cbdf2e3 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -47,6 +47,8 @@ Note: we kept the last draft factory ID in order to not break plugins already us ## Documentation * [events.h](include/clap/events.h): Clarify how "Port Channel Key NoteID" matching works +* [events.h](include/clap/events.h): Clarify how `clap_event_note` fields map to MIDI, Host, etc... +* [events.h](include/clap/events.h): Expand clap note expression documentation * [plugin.h](include/clap/plugin.h): Style cleanup * [params.h](include/clap/ext/params.h): Fix incorrect function name reference * [latency.h](include/clap/ext/latency.h): Require the plugin to be activated to get the latency and clarify that the latency can only be fetched when the plugin is activated From b2371860aa2c1cb50937d7a50936a73e069ae09d Mon Sep 17 00:00:00 2001 From: Paul Walker Date: Mon, 15 Jan 2024 08:23:28 -0500 Subject: [PATCH 68/85] Expand note expression tuning description just a bit 1. fix a small grammar mistake 2. crystal clear on what semitone means --- include/clap/events.h | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/include/clap/events.h b/include/clap/events.h index 84978ad0..94ce1065 100644 --- a/include/clap/events.h +++ b/include/clap/events.h @@ -180,7 +180,9 @@ enum { // pan, 0 left, 0.5 center, 1 right CLAP_NOTE_EXPRESSION_PAN = 1, - // relative tuning in semitone, from -120 to +120, in equal temperament + // relative tuning in semitones, from -120 to +120. Semitones are in + // equal temperament and are doubles; The resulting note would be + // retuned by `100 * evt->value` cents CLAP_NOTE_EXPRESSION_TUNING = 2, // 0..1 From c52aeb2715aff99304bb41f113c35f724f2dfefe Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Mon, 15 Jan 2024 14:32:05 +0100 Subject: [PATCH 69/85] Typo --- include/clap/events.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/include/clap/events.h b/include/clap/events.h index 94ce1065..5086b4df 100644 --- a/include/clap/events.h +++ b/include/clap/events.h @@ -180,9 +180,9 @@ enum { // pan, 0 left, 0.5 center, 1 right CLAP_NOTE_EXPRESSION_PAN = 1, - // relative tuning in semitones, from -120 to +120. Semitones are in - // equal temperament and are doubles; The resulting note would be - // retuned by `100 * evt->value` cents + // Relative tuning in semitones, from -120 to +120. Semitones are in + // equal temperament and are doubles; the resulting note would be + // retuned by `100 * evt->value` cents. CLAP_NOTE_EXPRESSION_TUNING = 2, // 0..1 From f45f18cf1e2879eef015eaabd94057a59f5805a5 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Mon, 15 Jan 2024 15:24:39 +0100 Subject: [PATCH 70/85] Cleanups for state context so we're compat with pre 1.2.0 --- include/clap/ext/state-context.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/include/clap/ext/state-context.h b/include/clap/ext/state-context.h index d4c05930..6a0dd5a2 100644 --- a/include/clap/ext/state-context.h +++ b/include/clap/ext/state-context.h @@ -40,12 +40,13 @@ static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT_COMPAT[] = "clap.state-c enum clap_plugin_state_context_type { // suitable for storing and loading a state as a preset - CLAP_STATE_CONTEXT_FOR_PRESET = 1, + CLAP_STATE_CONTEXT_FOR_PRESET = 2, // suitable for duplicating a plugin instance - CLAP_STATE_CONTEXT_FOR_DUPLICATE = 2, + CLAP_STATE_CONTEXT_FOR_DUPLICATE = 1, // suitable for storing and loading a state within a project/song + // Available since CLAP 1.2.0. CLAP_STATE_CONTEXT_FOR_PROJECT = 3, }; From dd97ce310e14e81b033d3eda1f93d367941ad63d Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Tue, 16 Jan 2024 09:53:29 +0100 Subject: [PATCH 71/85] Missing ID cleanup for ambisonic --- include/clap/ext/ambisonic.h | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/include/clap/ext/ambisonic.h b/include/clap/ext/ambisonic.h index 7ac1bfd6..c9775171 100644 --- a/include/clap/ext/ambisonic.h +++ b/include/clap/ext/ambisonic.h @@ -3,10 +3,11 @@ #include "../plugin.h" // This extension can be used to specify the channel mapping used by the plugin. -// -// This extension ID contains `draft', yet it is stable. -// See conventions/extension-id.md for more info. -static CLAP_CONSTEXPR const char CLAP_EXT_AMBISONIC[] = "clap.ambisonic.draft/3"; +static CLAP_CONSTEXPR const char CLAP_EXT_AMBISONIC[] = "clap.ambisonic/3"; + +// The latest draft is 100% compatible. +// This compat ID may be removed in 2026. +static CLAP_CONSTEXPR const char CLAP_EXT_AMBISONIC_COMPAT[] = "clap.ambisonic.draft/3"; static CLAP_CONSTEXPR const char CLAP_PORT_AMBISONIC[] = "ambisonic"; From a8b3f1e0bdb21df8b6dd52eb4619981e0b82b261 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Tue, 16 Jan 2024 09:55:17 +0100 Subject: [PATCH 72/85] state-context: we changed the enum values so no COMPAT here --- include/clap/ext/state-context.h | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/include/clap/ext/state-context.h b/include/clap/ext/state-context.h index 6a0dd5a2..20248b37 100644 --- a/include/clap/ext/state-context.h +++ b/include/clap/ext/state-context.h @@ -32,21 +32,16 @@ extern "C" { #endif -static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context/1"; - -// The latest draft is 100% compatible. -// This compat ID may be removed in 2026. -static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT_COMPAT[] = "clap.state-context.draft/1"; +static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context/2"; enum clap_plugin_state_context_type { // suitable for storing and loading a state as a preset - CLAP_STATE_CONTEXT_FOR_PRESET = 2, + CLAP_STATE_CONTEXT_FOR_PRESET = 1, // suitable for duplicating a plugin instance - CLAP_STATE_CONTEXT_FOR_DUPLICATE = 1, + CLAP_STATE_CONTEXT_FOR_DUPLICATE = 2, // suitable for storing and loading a state within a project/song - // Available since CLAP 1.2.0. CLAP_STATE_CONTEXT_FOR_PROJECT = 3, }; From 71f05a7526a640429dbc9b798b84aad55a03faf5 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Tue, 16 Jan 2024 09:59:49 +0100 Subject: [PATCH 73/85] doc --- include/clap/ext/state.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/ext/state.h b/include/clap/ext/state.h index b8b698c0..540246b3 100644 --- a/include/clap/ext/state.h +++ b/include/clap/ext/state.h @@ -13,7 +13,7 @@ /// /// If you need to know if the save/load operation is meant for duplicating a plugin /// instance, for saving/loading a plugin preset or while saving/loading the project -/// then have a look at clap_plugin_state_context_t. +/// then consider implementing CLAP_EXT_STATE_CONTEXT in addition to CLAP_EXT_STATE. static CLAP_CONSTEXPR const char CLAP_EXT_STATE[] = "clap.state"; From 955046cd0f36da65732f9a299db8edbf17ebce6d Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Tue, 16 Jan 2024 10:09:31 +0100 Subject: [PATCH 74/85] Add clarifications regarding foreign plugin id --- include/clap/plugin-id.h | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/include/clap/plugin-id.h b/include/clap/plugin-id.h index 962eab8f..a440321d 100644 --- a/include/clap/plugin-id.h +++ b/include/clap/plugin-id.h @@ -3,11 +3,15 @@ // Pair of plugin ABI and plugin identifier. typedef struct clap_plugin_id { // The plugin ABI name, in lowercase. - // eg: "clap" + // eg: "clap", "vst3", "vst2", "au", "lv2", ... const char *abi; // The plugin ID, for example "com.u-he.Diva". // If the ABI rely upon binary plugin ids, then they shall be hex encoded (lower case). + // eg: + // T binary_id; + // const uint8_t * data = (const uint8_t *)&binary_id; + // char *buffer = malloc(2 * sizeof(binary_id) + 1); + // hex_encode(data, sizeof (binary_id), buffer); const char *id; } clap_plugin_id_t; - From 583177dff0aa25d6ecbfac23783534e89aac4d3f Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Tue, 16 Jan 2024 10:22:02 +0100 Subject: [PATCH 75/85] Leave a note regarding endianness --- include/clap/plugin-id.h | 3 +++ 1 file changed, 3 insertions(+) diff --git a/include/clap/plugin-id.h b/include/clap/plugin-id.h index a440321d..fbc2e050 100644 --- a/include/clap/plugin-id.h +++ b/include/clap/plugin-id.h @@ -13,5 +13,8 @@ typedef struct clap_plugin_id { // const uint8_t * data = (const uint8_t *)&binary_id; // char *buffer = malloc(2 * sizeof(binary_id) + 1); // hex_encode(data, sizeof (binary_id), buffer); + // + // Note: if the binary id is sensible to the CPU endianness, the encoded id will be too. + // As a result, the id should be decoded immediately by the consumer. const char *id; } clap_plugin_id_t; From 498af28c47d09216d64db9900634254df7456b29 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Tue, 16 Jan 2024 10:23:51 +0100 Subject: [PATCH 76/85] Make the example code more robust --- include/clap/plugin-id.h | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/include/clap/plugin-id.h b/include/clap/plugin-id.h index fbc2e050..384a0e9e 100644 --- a/include/clap/plugin-id.h +++ b/include/clap/plugin-id.h @@ -11,8 +11,10 @@ typedef struct clap_plugin_id { // eg: // T binary_id; // const uint8_t * data = (const uint8_t *)&binary_id; - // char *buffer = malloc(2 * sizeof(binary_id) + 1); + // const size_t buffer_size = 2 * sizeof(binary_id) + 1; + // char *buffer = malloc(buffer_size); // hex_encode(data, sizeof (binary_id), buffer); + // buffer[buffer_size - 1] = '\0'; // // Note: if the binary id is sensible to the CPU endianness, the encoded id will be too. // As a result, the id should be decoded immediately by the consumer. From c53c0a7f65e322f120788ec8b573a2f1b05cb3f4 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 17 Jan 2024 12:20:02 +0100 Subject: [PATCH 77/85] Specify how to format foreign plugin id --- include/clap/plugin-id.h | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/include/clap/plugin-id.h b/include/clap/plugin-id.h index 384a0e9e..38c0da44 100644 --- a/include/clap/plugin-id.h +++ b/include/clap/plugin-id.h @@ -6,17 +6,18 @@ typedef struct clap_plugin_id { // eg: "clap", "vst3", "vst2", "au", "lv2", ... const char *abi; - // The plugin ID, for example "com.u-he.Diva". - // If the ABI rely upon binary plugin ids, then they shall be hex encoded (lower case). - // eg: - // T binary_id; - // const uint8_t * data = (const uint8_t *)&binary_id; - // const size_t buffer_size = 2 * sizeof(binary_id) + 1; - // char *buffer = malloc(buffer_size); - // hex_encode(data, sizeof (binary_id), buffer); - // buffer[buffer_size - 1] = '\0'; + // The plugin ID, formatted as follow: // - // Note: if the binary id is sensible to the CPU endianness, the encoded id will be too. - // As a result, the id should be decoded immediately by the consumer. + // CLAP: use the plugin id + // eg: "com.u-he.diva" + // + // AU: format the string like "manu:type:subt" + // eg: "aumu:SgXT:VmbA" + // + // VST2: print the id as a signed 32-bits integer + // eg: "-4382976" + // + // VST3: print the id as a standard UUID + // eg: "123e4567-e89b-12d3-a456-426614174000" const char *id; } clap_plugin_id_t; From 43d80c5faf90e3d87546a321f1528a3418c21846 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 17 Jan 2024 13:24:44 +0100 Subject: [PATCH 78/85] use "type:subt:manu" --- include/clap/plugin-id.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/plugin-id.h b/include/clap/plugin-id.h index 38c0da44..438cbfe8 100644 --- a/include/clap/plugin-id.h +++ b/include/clap/plugin-id.h @@ -11,7 +11,7 @@ typedef struct clap_plugin_id { // CLAP: use the plugin id // eg: "com.u-he.diva" // - // AU: format the string like "manu:type:subt" + // AU: format the string like "type:subt:manu" // eg: "aumu:SgXT:VmbA" // // VST2: print the id as a signed 32-bits integer From fd83c02be8d9e05f40a8e62eaaf882342d529936 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Wed, 17 Jan 2024 17:46:31 +0100 Subject: [PATCH 79/85] Rename clap_plugin_id_t to clap_universal_plugin_id_t --- ChangeLog.md | 5 +++++ include/clap/clap.h | 2 +- include/clap/factory/draft/plugin-state-converter.h | 6 +++--- include/clap/factory/preset-discovery.h | 4 ++-- include/clap/{plugin-id.h => universal-plugin-id.h} | 9 ++++++--- 5 files changed, 17 insertions(+), 9 deletions(-) rename include/clap/{plugin-id.h => universal-plugin-id.h} (66%) diff --git a/ChangeLog.md b/ChangeLog.md index 2cbdf2e3..8f021deb 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -36,6 +36,7 @@ We may decide to remove the `*_COMPAT` IDs in the future once their usage become * `CLAP_EXT_CV` the interface wasn't satisfying. ## Stabilize factory + * `CLAP_PRESET_DISCOVERY_FACTORY_ID` Note: we kept the last draft factory ID in order to not break plugins already using it. @@ -44,6 +45,10 @@ Note: we kept the last draft factory ID in order to not break plugins already us * Introduction of a new factory which provides a plugin state convertion mechanism. +## Refactoring + +* `clap_plugin_id_t` was renamed to `clap_universal_plugin_id_t` to make it clear that it can describe more than just a CLAP plugin ID. + ## Documentation * [events.h](include/clap/events.h): Clarify how "Port Channel Key NoteID" matching works diff --git a/include/clap/clap.h b/include/clap/clap.h index b37328a2..6da56764 100644 --- a/include/clap/clap.h +++ b/include/clap/clap.h @@ -33,7 +33,7 @@ #include "plugin.h" #include "plugin-features.h" #include "host.h" -#include "plugin-id.h" +#include "universal-plugin-id.h" #include "ext/ambisonic.h" #include "ext/audio-ports-activation.h" diff --git a/include/clap/factory/draft/plugin-state-converter.h b/include/clap/factory/draft/plugin-state-converter.h index 19c96ad3..315926e7 100644 --- a/include/clap/factory/draft/plugin-state-converter.h +++ b/include/clap/factory/draft/plugin-state-converter.h @@ -1,7 +1,7 @@ #pragma once #include "../../id.h" -#include "../../plugin-id.h" +#include "../../universal-plugin-id.h" #include "../../stream.h" #include "../../version.h" @@ -12,8 +12,8 @@ extern "C" { typedef struct clap_plugin_state_converter_descriptor { clap_version_t clap_version; - clap_plugin_id_t src_plugin_id; - clap_plugin_id_t dst_plugin_id; + clap_universal_plugin_id_t src_plugin_id; + clap_universal_plugin_id_t dst_plugin_id; const char *name; const char *vendor; diff --git a/include/clap/factory/preset-discovery.h b/include/clap/factory/preset-discovery.h index f9c8e434..794f4967 100644 --- a/include/clap/factory/preset-discovery.h +++ b/include/clap/factory/preset-discovery.h @@ -44,7 +44,7 @@ #include "../private/std.h" #include "../private/macros.h" #include "../version.h" -#include "../plugin-id.h" +#include "../universal-plugin-id.h" // Use it to retrieve const clap_preset_discovery_factory_t* from // clap_plugin_entry.get_factory() @@ -133,7 +133,7 @@ typedef struct clap_preset_discovery_metadata_receiver { // Adds a plug-in id that this preset can be used with. void(CLAP_ABI *add_plugin_id)(const struct clap_preset_discovery_metadata_receiver *receiver, - const clap_plugin_id_t *plugin_id); + const clap_universal_plugin_id_t *plugin_id); // Sets the sound pack to which the preset belongs to. void(CLAP_ABI *set_soundpack_id)(const struct clap_preset_discovery_metadata_receiver *receiver, diff --git a/include/clap/plugin-id.h b/include/clap/universal-plugin-id.h similarity index 66% rename from include/clap/plugin-id.h rename to include/clap/universal-plugin-id.h index 438cbfe8..dda0cab2 100644 --- a/include/clap/plugin-id.h +++ b/include/clap/universal-plugin-id.h @@ -1,9 +1,12 @@ #pragma once // Pair of plugin ABI and plugin identifier. -typedef struct clap_plugin_id { +// +// If you want to represent other formats please send us an update to the comment with the +// name of the abi and the representation of the id. +typedef struct clap_universal_plugin_id { // The plugin ABI name, in lowercase. - // eg: "clap", "vst3", "vst2", "au", "lv2", ... + // eg: "clap", "vst3", "vst2", "au", ... const char *abi; // The plugin ID, formatted as follow: @@ -20,4 +23,4 @@ typedef struct clap_plugin_id { // VST3: print the id as a standard UUID // eg: "123e4567-e89b-12d3-a456-426614174000" const char *id; -} clap_plugin_id_t; +} clap_universal_plugin_id_t; From 5e25da6c73d4a7c4bd70431b5ef73c73b6c61918 Mon Sep 17 00:00:00 2001 From: Paul Walker Date: Wed, 17 Jan 2024 12:41:33 -0500 Subject: [PATCH 80/85] Add CLAP_CONSTEXPR to voice-info and preset-load id declarations To be consistent with all the other extensions --- ChangeLog.md | 5 +++++ include/clap/ext/preset-load.h | 4 ++-- include/clap/ext/voice-info.h | 2 +- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 8f021deb..cc1410bb 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -66,6 +66,11 @@ Note: we kept the last draft factory ID in order to not break plugins already us * `clap.h` no longer includes headers from `ext/draft` or `factory/draft`. Draft extension and factory headers must now be explicitly included, either individually or via the `draft.h` header. +## Other changes + +* [voice-info.h](include/clap/ext/voice-info.h): Make the voice info id `CLAP_CONSTEXPR` like all other ids +* [preset-load.h](include/clap/ext/preset-load.h): Make the preset load id and compat id `CLAP_CONSTEXPR` like all other ids + # Changes in 1.1.10 * [params.h](include/clap/ext/params.h): add `CLAP_PARAM_IS_ENUM` flag. diff --git a/include/clap/ext/preset-load.h b/include/clap/ext/preset-load.h index 3dbf7375..1e4122e2 100644 --- a/include/clap/ext/preset-load.h +++ b/include/clap/ext/preset-load.h @@ -2,11 +2,11 @@ #include "../plugin.h" -static const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load/2"; +static CLAP_CONSTEXPR const char CLAP_EXT_PRESET_LOAD[] = "clap.preset-load/2"; // The latest draft is 100% compatible. // This compat ID may be removed in 2026. -static const char CLAP_EXT_PRESET_LOAD_COMPAT[] = "clap.preset-load.draft/2"; +static CLAP_CONSTEXPR const char CLAP_EXT_PRESET_LOAD_COMPAT[] = "clap.preset-load.draft/2"; #ifdef __cplusplus extern "C" { diff --git a/include/clap/ext/voice-info.h b/include/clap/ext/voice-info.h index 344ed8ab..038baecb 100644 --- a/include/clap/ext/voice-info.h +++ b/include/clap/ext/voice-info.h @@ -9,7 +9,7 @@ // - make the host's voice pool coherent with what the plugin has // - turn the host's voice management to mono when the plugin is mono -static const char CLAP_EXT_VOICE_INFO[] = "clap.voice-info"; +static CLAP_CONSTEXPR const char CLAP_EXT_VOICE_INFO[] = "clap.voice-info"; #ifdef __cplusplus extern "C" { From 03acdaa8be5ac1509658c5af5e44a2916872676f Mon Sep 17 00:00:00 2001 From: trinitou Date: Thu, 18 Jan 2024 07:03:35 +0100 Subject: [PATCH 81/85] Move clap_timestamp_t definition to separate header --- include/clap/factory/preset-discovery.h | 11 +---------- include/clap/timestamp.h | 11 +++++++++++ 2 files changed, 12 insertions(+), 10 deletions(-) create mode 100644 include/clap/timestamp.h diff --git a/include/clap/factory/preset-discovery.h b/include/clap/factory/preset-discovery.h index 794f4967..7eaba6e6 100644 --- a/include/clap/factory/preset-discovery.h +++ b/include/clap/factory/preset-discovery.h @@ -43,6 +43,7 @@ #include "../private/std.h" #include "../private/macros.h" +#include "../timestamp.h" #include "../version.h" #include "../universal-plugin-id.h" @@ -89,16 +90,6 @@ enum clap_preset_discovery_flags { CLAP_PRESET_DISCOVERY_IS_FAVORITE = 1 << 3, }; -// TODO: move clap_timestamp_t, CLAP_TIMESTAMP_UNKNOWN and clap_plugin_id_t to parent files once we -// settle with preset discovery - -// This type defines a timestamp: the number of seconds since UNIX EPOCH. -// See C's time_t time(time_t *). -typedef uint64_t clap_timestamp_t; - -// Value for unknown timestamp. -static const clap_timestamp_t CLAP_TIMESTAMP_UNKNOWN = 0; - // Receiver that receives the metadata for a single preset file. // The host would define the various callbacks in this interface and the preset parser function // would then call them. diff --git a/include/clap/timestamp.h b/include/clap/timestamp.h new file mode 100644 index 00000000..d06d1131 --- /dev/null +++ b/include/clap/timestamp.h @@ -0,0 +1,11 @@ +#pragma once + +#include "private/std.h" +#include "private/macros.h" + +// This type defines a timestamp: the number of seconds since UNIX EPOCH. +// See C's time_t time(time_t *). +typedef uint64_t clap_timestamp_t; + +// Value for unknown timestamp. +static const CLAP_CONSTEXPR clap_timestamp_t CLAP_TIMESTAMP_UNKNOWN = 0; From 897dac406485fd9a4bdb62ef3f46ef53e5d1dfe9 Mon Sep 17 00:00:00 2001 From: trinitou Date: Thu, 18 Jan 2024 07:05:34 +0100 Subject: [PATCH 82/85] Rename timestamp typedef to be consistent with clap_id etc. --- ChangeLog.md | 1 + include/clap/factory/preset-discovery.h | 20 ++++++++++---------- include/clap/timestamp.h | 4 ++-- 3 files changed, 13 insertions(+), 12 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 8f021deb..bfdb7e6e 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -48,6 +48,7 @@ Note: we kept the last draft factory ID in order to not break plugins already us ## Refactoring * `clap_plugin_id_t` was renamed to `clap_universal_plugin_id_t` to make it clear that it can describe more than just a CLAP plugin ID. +* `clap_timestamp_t` was renamed to `clap_timestamp` to be consistent with other types, like e.g. `clap_id`. Also it was moved to a separate header as `CLAP_PRESET_DISCOVERY_FACTORY_ID` was stabilized. ## Documentation diff --git a/include/clap/factory/preset-discovery.h b/include/clap/factory/preset-discovery.h index 7eaba6e6..fbb0244a 100644 --- a/include/clap/factory/preset-discovery.h +++ b/include/clap/factory/preset-discovery.h @@ -148,8 +148,8 @@ typedef struct clap_preset_discovery_metadata_receiver { // If this function is not called, then the indexer may look at the file's creation and // modification time. void(CLAP_ABI *set_timestamps)(const struct clap_preset_discovery_metadata_receiver *receiver, - clap_timestamp_t creation_time, - clap_timestamp_t modification_time); + clap_timestamp creation_time, + clap_timestamp modification_time); // Adds a feature to the preset. // @@ -195,14 +195,14 @@ typedef struct clap_preset_discovery_location { // Describes an installed sound pack. typedef struct clap_preset_discovery_soundpack { - uint32_t flags; // see enum clap_preset_discovery_flags - const char *id; // sound pack identifier - const char *name; // name of this sound pack - const char *description; // optional, reasonably short description of the sound pack - const char *homepage_url; // optional, url to the pack's homepage - const char *vendor; // optional, sound pack's vendor - const char *image_path; // optional, an image on disk - clap_timestamp_t release_timestamp; // release date, CLAP_TIMESTAMP_UNKNOWN if unavailable + uint32_t flags; // see enum clap_preset_discovery_flags + const char *id; // sound pack identifier + const char *name; // name of this sound pack + const char *description; // optional, reasonably short description of the sound pack + const char *homepage_url; // optional, url to the pack's homepage + const char *vendor; // optional, sound pack's vendor + const char *image_path; // optional, an image on disk + clap_timestamp release_timestamp; // release date, CLAP_TIMESTAMP_UNKNOWN if unavailable } clap_preset_discovery_soundpack_t; // Describes a preset provider diff --git a/include/clap/timestamp.h b/include/clap/timestamp.h index d06d1131..63d2caba 100644 --- a/include/clap/timestamp.h +++ b/include/clap/timestamp.h @@ -5,7 +5,7 @@ // This type defines a timestamp: the number of seconds since UNIX EPOCH. // See C's time_t time(time_t *). -typedef uint64_t clap_timestamp_t; +typedef uint64_t clap_timestamp; // Value for unknown timestamp. -static const CLAP_CONSTEXPR clap_timestamp_t CLAP_TIMESTAMP_UNKNOWN = 0; +static const CLAP_CONSTEXPR clap_timestamp CLAP_TIMESTAMP_UNKNOWN = 0; From 6055daa60525ca3e903344c1d0f9c80b0e78e293 Mon Sep 17 00:00:00 2001 From: trinitou Date: Thu, 18 Jan 2024 19:16:58 +0100 Subject: [PATCH 83/85] Document null-terminated string members of clap_universal_plugin_id --- include/clap/universal-plugin-id.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/clap/universal-plugin-id.h b/include/clap/universal-plugin-id.h index dda0cab2..b039d035 100644 --- a/include/clap/universal-plugin-id.h +++ b/include/clap/universal-plugin-id.h @@ -5,11 +5,11 @@ // If you want to represent other formats please send us an update to the comment with the // name of the abi and the representation of the id. typedef struct clap_universal_plugin_id { - // The plugin ABI name, in lowercase. + // The plugin ABI name, in lowercase and null-terminated. // eg: "clap", "vst3", "vst2", "au", ... const char *abi; - // The plugin ID, formatted as follow: + // The plugin ID, null-terminated and formatted as follows: // // CLAP: use the plugin id // eg: "com.u-he.diva" From 7feb350fe23bc2a85554dc2fd34687a82c7a1ec7 Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 19 Jan 2024 16:58:51 +0100 Subject: [PATCH 84/85] Polish the plugin state converter --- include/clap/factory/draft/plugin-state-converter.h | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/include/clap/factory/draft/plugin-state-converter.h b/include/clap/factory/draft/plugin-state-converter.h index 315926e7..cfc9ad1d 100644 --- a/include/clap/factory/draft/plugin-state-converter.h +++ b/include/clap/factory/draft/plugin-state-converter.h @@ -15,10 +15,11 @@ typedef struct clap_plugin_state_converter_descriptor { clap_universal_plugin_id_t src_plugin_id; clap_universal_plugin_id_t dst_plugin_id; - const char *name; - const char *vendor; - const char *version; - const char *description; + const char *id; // eg: "com.u-he.diva-converter", mandatory + const char *name; // eg: "Diva Converter", mandatory + const char *vendor; // eg: "u-he" + const char *version; // eg: 1.1.5 + const char *description; // eg: "Official state converter for u-he Diva." } clap_plugin_state_converter_descriptor_t; // This interface provides a mechanism for the host to convert a plugin state and its automation @@ -85,12 +86,12 @@ typedef struct clap_plugin_state_converter_factory { const clap_plugin_state_converter_descriptor_t *(*get_descriptor)( const struct clap_plugin_state_converter_factory *factory, uint32_t index); - // Create a plugin state converter by its index. + // Create a plugin state converter by its converter_id. // The returned pointer must be freed by calling converter->destroy(converter); // Returns null in case of error. // [thread-safe] clap_plugin_state_converter_t *(*create)( - const struct clap_plugin_state_converter_factory *factory, uint32_t index); + const struct clap_plugin_state_converter_factory *factory, const char *converter_id); } clap_plugin_state_converter_factory_t; #ifdef __cplusplus From a4706628275676f49ecdd00c639a10343760b49f Mon Sep 17 00:00:00 2001 From: Alexandre Bique Date: Fri, 19 Jan 2024 17:10:25 +0100 Subject: [PATCH 85/85] It is all.h, not draft.h --- ChangeLog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ChangeLog.md b/ChangeLog.md index 69af0cf4..1f5f511b 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -65,7 +65,7 @@ Note: we kept the last draft factory ID in order to not break plugins already us ## Organization -* `clap.h` no longer includes headers from `ext/draft` or `factory/draft`. Draft extension and factory headers must now be explicitly included, either individually or via the `draft.h` header. +* `clap.h` no longer includes headers from `ext/draft` or `factory/draft`. Draft extension and factory headers must now be explicitly included, either individually or via the `all.h` header. ## Other changes