clap

commit 63ba64843e53f7fabd0548f1620526fe2c3015c6
parent 89bdda6fd3bff17d8e40fb514d15a7a74f50e025
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date:   Mon, 17 Oct 2022 18:14:49 +0200

Improvements to the param cookie documentation, after discussing with Paul

Diffstat:
M
include/clap/ext/params.h
 | 
31
++++++++++---------------------

1 file changed, 10 insertions(+), 21 deletions(-)
diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h
@@ -173,27 +173,16 @@ typedef struct clap_param_info {
    // where findParameter() is a function the plugin implements
    // to map parameter ids to internal objects.
    //
-   // The host will either provide the cookie as issued or nullptr
-   // in events addressing parameters.
-   //
-   // The plugin must gracefully handle the case of a cookie
-   // which is nullptr, but can safely assume any cookie
-   // which is not nullptr is the value it issued.
-   //
-   // The host should provide the cookie if its retrival is cheaper
-   // than an hastable lookup, otherwise the plugin may as well do
-   // the parameter lookup.
-   //
-   // TIP: the host may build a cached array of parameters info
-   // and internally work with parameter index, that way the retrival cost
-   // of the cookie is equivalent to an array access.
-   //
-   // The host should make no assumption about the value of the cookie
-   // other than passing it back to the plugin or replacing it with nullptr.
-   //
-   // Once set, the cookie is valid until invalidated by a call to
-   // clap_host_params->rescan(CLAP_PARAM_RESCAN_ALL) or when the plugin is
-   // destroyed.
+   // Important:
+   //  - The cookie is invalidated by a call to
+   //    clap_host_params->rescan(CLAP_PARAM_RESCAN_ALL) or when the plugin is
+   //    destroyed.
+   //  - The host will either provide the cookie as issued or nullptr
+   //    in events addressing parameters.
+   //  - The plugin must gracefully handle the case of a cookie
+   //    which is nullptr.
+   //  - Many plugins will deliver better performance if the host can provide
+   //    the cookie in a faster time than a hashmap lookup per param per event.
    void *cookie;
 
    // the display name