commit d4b854be867b32215af623071a4f5baad8ec10f5 parent 467643440d2a7fe21ebe2ecfd2e429dd390c51bd Author: Alexandre Bique <bique.alexandre@gmail.com> Date: Tue, 11 Oct 2022 09:12:01 +0200 Merge pull request #180 from baconpaul/cookie-doc-take-2 Clarify Cookie Optionality Diffstat:
| M | include/clap/ext/params.h | | | 37 | ++++++++++++++++++++++++++++++++----- |
1 file changed, 32 insertions(+), 5 deletions(-)
diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h @@ -155,16 +155,43 @@ typedef struct clap_param_info { clap_param_info_flags flags; - // This value is optional and set by the plugin. - // Its purpose is to provide a fast access to the plugin parameter: + // This value is optional and set by the plugin. The host will + // set it on all subsequent events regarding this param_id + // or set the cookie to nullptr if the host chooses to + // not implement cookies. // + // 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. + // + // It is very strongly recommended that the host implement + // cookies. Some plugins may have noticably reduced + // performance when addressing params in hosts without cookies. + // + // The cookie's purpose is to provide a fast access to the + // plugin parameter objects. For instance: + // + // in clap_plugin_params.get_info // Parameter *p = findParameter(param_id); // param_info->cookie = p; // - // /* and later on */ - // Parameter *p = (Parameter *)cookie; + // later, in clap_plugin.process: + // + // Parameter *p{nullptr}; + // if (evt->cookie) [[likely]] + // p = (Parameter *)evt->cookie; + // else + // p = -- alternate mechanism -- + // + // where "alternate mechanism" is a mechanism the plugin implements + // to map parameter ids to internal objects. + // + // 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. // - // It is invalidated on clap_host_params->rescan(CLAP_PARAM_RESCAN_ALL) and when the plugin is + // 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. void *cookie;