clap

CLAP Audio Plugin API
Log | Files | Refs | README | LICENSE

commit 7929297cd6988e34bacd943674e1acf5d70905f3
parent 60cd584844a4582f0ee6ff3cd9e4bf7cbe5bcec5
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date:   Mon, 17 Oct 2022 16:32:39 +0200

Rephrase the cookie documentation

Diffstat:
Minclude/clap/ext/params.h | 57+++++++++++++++++++++++++++++----------------------------
1 file changed, 29 insertions(+), 28 deletions(-)

diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h @@ -155,42 +155,43 @@ typedef struct clap_param_info { clap_param_info_flags flags; - // 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. + // This value is optional and set by the plugin. + // Its purpose is to provide a fast access to the + // plugin parameter objects by caching its pointer. + // For instance: // - // 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 + // in clap_plugin_params.get_info(): // Parameter *p = findParameter(param_id); // param_info->cookie = p; // - // later, in clap_plugin.process: + // later, in clap_plugin.process(): + // + // Parameter *p = (Parameter *)event->cookie; + // if (!p) [[unlikely]] + // p = findParameter(event->param_id); + // + // 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. // - // Parameter *p{nullptr}; - // if (evt->cookie) [[likely]] - // p = (Parameter *)evt->cookie; - // else - // p = -- alternate mechanism -- + // 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. // - // where "alternate mechanism" is a mechanism the plugin implements - // to map parameter ids to internal objects. + // 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. + // 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 + // 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;