diff --git a/ChangeLog.md b/ChangeLog.md index 7787b128..a3342bd5 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'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 index c07b22a0..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. -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 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..d7bf4fc5 100644 --- 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 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..f9c8e434 100644 --- 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