clap

commit 2fe3af4149b956062e8ccc9c91ea1f8983e7dae9
parent 4dcfb75b6d78b502144876bd02d9321032724e98
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date:   Tue,  7 Mar 2023 19:34:52 +0100

Improve documentation

Diffstat:
M
include/clap/ext/draft/configurable-audio-ports.h
 | 
24
+++++++++++++++---------

1 file changed, 15 insertions(+), 9 deletions(-)
diff --git a/include/clap/ext/draft/configurable-audio-ports.h b/include/clap/ext/draft/configurable-audio-ports.h
@@ -6,33 +6,39 @@
 extern "C" {
 #endif
 
-// This extension lets the host configure the plugin's input and output audio ports
+// This extension lets the host configure the plugin's input and output audio ports.
+// This is a "push" approach to audio ports configuration.
 static CLAP_CONSTEXPR const char CLAP_EXT_CONFIGURABLE_AUDIO_PORTS[] =
    "clap.configurable-audio-ports.draft0";
 
 typedef struct clap_audio_port_configuration_request {
-   uint32_t port_index;
+   // When true, allows the plugin to pick a similar port configuration instead
+   // if the requested one can't be applied.
+   bool is_best_effort;
+
+   // Identifies the port by is_input and port_index
    bool     is_input;
+   uint32_t port_index;
+
+   // The requested number of channels.
    uint32_t channel_count;
 
-   // If true and if the plugin can't apply the requested port configuration,
-   // then it is allowed to pick the closest possible port configuration.
-   bool is_best_effort;
+   // The port type, see audio-ports.h, clap_audio_port_info.port_type for interpretation.
+   const char *port_type;
 
    // cast port_details according to port_type:
    // - CLAP_PORT_MONO: (discard)
    // - CLAP_PORT_STEREO: (discard)
    // - CLAP_PORT_SURROUND: const uint8_t *channel_map
    // - CLAP_PORT_AMBISONIC: const clap_ambisonic_info_t *info
-   const char *port_type;
    const void *port_details;
 } clap_audio_port_configuration_request_t;
 
 typedef struct clap_plugin_configurable_audio_ports {
    // Some ports may not be configurable, or simply the result of another port configuration.
-   // For example if you have a simple delay plugin, and the output port must have the exact
-   // same type as the input port, then the output port configuration is a function (identity)
-   // of the input port configuration.
+   // For example if you have a simple delay plugin, then the output port must have the exact
+   // same type as the input port; in that example, we consider the output port type to be a
+   // function (identity) of the input port type.
    // [main-thread && !active]
    bool(CLAP_ABI *is_port_configurable)(const clap_plugin_t *plugin,
                                         bool                 is_input,