commit eb73e48b72849650f7d59c2b886692171dd4340f parent c2cd585cc1deefd2a18ae5ce22a1df40c8e67da3 Author: Paul Walker <paul@pwjw.com> Date: Tue, 27 Sep 2022 20:50:51 -0400 Clarify Cookie Optionality Clarify Cookie Optionality. The documentation was ambiguous as to whether hosts can choose to ignore the plugin cookie. This change documents the fact that they can, and the plugin must react accordingly Diffstat:
| M | include/clap/ext/params.h | | | 27 | ++++++++++++++++++++++----- |
1 file changed, 22 insertions(+), 5 deletions(-)
diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h @@ -155,16 +155,33 @@ 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 or nullptr if the host chooses to + // not implement cookies. It is very strongly recommended + // that the host implement cookies and some plugins may ignore + // events which disregard their cookie. // + // Its 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. // - // 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;