clap

commit 46a2d79f8db353554e4d688cb198fff4758a6dec
parent 2f8a40797f71ba3a15fcb1bf61bd85791a552541
Author: Alexandre BIQUE <bique.alexandre@gmail.com>
Date:   Wed, 22 Dec 2021 18:46:58 +0100

improve surround extension

Diffstat:
M
include/clap/ext/draft/surround.h
 | 
36
+++++++++++++++++++++++++++++++++++-

1 file changed, 35 insertions(+), 1 deletion(-)
diff --git a/include/clap/ext/draft/surround.h b/include/clap/ext/draft/surround.h
@@ -2,6 +2,28 @@
 
 #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)