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:
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
