Improvements to the param cookie documentation, after discussing with Paul
@@ -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
+ // 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
