commit 4e7622d20751e34a845ee825295e38f60d3bf93f
parent 12ca18f99c77d480eb0d5a71353ee0974ae8204f
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date: Mon, 15 Jan 2024 11:58:00 +0100
Merge pull request #379 from abique/1.2.0/ext-id-cleanup
1.2.0 - Cleanup stabilized extension ID
Diffstat:
12 files changed, 69 insertions(+), 33 deletions(-)
diff --git 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'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 introduced some rules, so this kind of break won't happen again.
+
+We may decide to remove the `*_COMPAT` IDs in the future once their usage becomes antiquated.
## 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
diff --git 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.
-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
+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.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -31,9 +31,11 @@
// 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
+// 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
extern "C" {
diff --git 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
@@ -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
@@ -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
@@ -49,6 +49,11 @@
// 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/2";
+
+// 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";
#ifdef __cplusplus
