clap

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

commit 77dceb8fd48a4db9bf870fa7dfb90b7d6e972e6d
parent f63add06bb1137e3211b7ca06dffd1e27051f798
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date:   Wed,  1 Feb 2023 16:39:32 +0100

Merge pull request #294 from robbert-vdh/fix/params-state-relation

Document the relationship between the params and state extensions
Diffstat:
MChangeLog.md | 5+++++
Minclude/clap/ext/params.h | 14++++++++++++++
Minclude/clap/ext/state.h | 18++++++++++++++++++
3 files changed, 37 insertions(+), 0 deletions(-)

diff --git a/ChangeLog.md b/ChangeLog.md @@ -1,3 +1,8 @@ +# Changes in 1.1.8 + +* [params.h](include/clap/ext/params.h): document how persisting parameter values between sessions should be implemented +* [state.h](include/clap/ext/state.h): add basic documentation regarding what state should be saved and how plugins should interact with buffers + # Changes in 1.1.7 * Add a [factory](include/clap/factory) folder for better organization and move our factories there diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h @@ -97,15 +97,29 @@ /// ..... . . /// before: . . and after: . . /// +/// Persisting parameter values: +/// +/// Plugins are responsible for persisting their parameter's values between +/// sessions by implementing the state extension. Otherwise parameter value will +/// not be recalled when reloading a project. Hosts should _not_ try to save and +/// restore parameter values for plugins that don't implement the state +/// extension. +/// /// Advice for the host: +/// /// - store plain values in the document (automation) /// - store modulation amount in plain value delta, not in percentage /// - when you apply a CC mapping, remember the min/max plain values so you can adjust +/// - do not implement a parameter saving fall back for plugins that don't +/// implement the state extension /// /// Advice for the plugin: +/// /// - think carefully about your parameter range when designing your DSP /// - avoid shrinking parameter ranges, they are very likely to change the sound /// - consider changing the parameter range as a tradeoff: what you improve vs what you break +/// - make sure to implement saving and loading the parameter values using the +/// state extension /// - if you plan to use adapters for other plugin formats, then you need to pay extra /// attention to the adapter requirements diff --git a/include/clap/ext/state.h b/include/clap/ext/state.h @@ -3,6 +3,24 @@ #include "../plugin.h" #include "../stream.h" +/// @page State +/// @brief state management +/// +/// Plugins can implement this extension to save and restore both parameter +/// values and non-parameter state. This is used to persist a plugin's state +/// between project reloads, when duplicating and copying plugin instances, and +/// for host-side preset management. +/// +/// ## Notes on using streams +/// +/// When working with `clap_istream` and `clap_ostream` objects to load and save +/// state, it is important to keep in mind that the host may limit the number of +/// bytes that can be read or written at a time. The return values for the +/// stream read and write functions indicate how many bytes were actually read +/// or written. You need to use a loop to ensure that you read or write the +/// entirety of your state. Don't forget to also consider the negative return +/// values for the end of file and IO error codes. + static CLAP_CONSTEXPR const char CLAP_EXT_STATE[] = "clap.state"; #ifdef __cplusplus