improve surround extension
#include "../../plugin.h"
+// This extension can be used to specify the channel mapping used by the plugin.
+//
+// To have a consistent surround features across all the plugin instances,
+// here is the proposed workflow:
+// 1. the plugin queries the host preferred channel mapping and
+// adjusts its configuration to match it.
+// 2. the host checks how the plugin is effectively configured and honors it.
+//
+// If the host decides to change the project's surround setup:
+// 1. deactivate the plugin
+// 2. host calls clap_plugin_surround->changed()
+// 3. plugin calls clap_host_surround->get_preferred_channel_map()
+// 4. plugin eventualy calls clap_host_surround->changed()
+// 5. host calls clap_plugin_surround->get_channel_map() if changed
+// 6. host activates the plugin and can start processing audio
+//
+// If the plugin wants to change its surround setup:
+// 1. call host->request_restart() if the plugin is active
+// 2. once deactivated plugin calls clap_host_surround->changed()
+// 3. host calls clap_plugin_surround->get_channel_map()
+// 4. host activates the plugin and can start processing audio
+
static CLAP_CONSTEXPR const char CLAP_EXT_SURROUND[] = "clap.surround.draft/1";
#ifdef __cplusplus
@@ -40,12 +62,24 @@ typedef struct clap_plugin_surround {
uint32_t port_index,
uint8_t *channel_map,
uint32_t channel_map_capacity);
+
+ // Informs the plugin that the host preferred channel map has changed.
+ // [main-thread]
+ void (*changed)(const clap_plugin_t *plugin);
} clap_plugin_surround_t;
typedef struct clap_host_surround {
- // Informs the host that the channel type have changed.
+ // Informs the host that the channel map have changed.
+ // The channel map can only change when the plugin is de-activated.
// [main-thread]
void (*changed)(const clap_host_t *host);
+
+ // Ask the host what is the prefered/project surround channel map.
+ // [main-thread]
+ void (*get_preferred_channel_map)(const clap_host_t *host,
+ uint8_t *channel_map,
+ uint32_t channel_map_capacity,
+ uint32_t *channel_count);
} clap_host_surround_t;
#pragma pack(pop)
