commit a4e1605d37dae9c6943b288ea6a73bbbccb53f7e
parent d2cf8b1d26ba3509de52980523a4a7f2f2a62206
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date: Fri, 7 Jul 2023 16:06:37 +0200
Introduce incremental state
Diffstat:
3 files changed, 55 insertions(+), 0 deletions(-)
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -6,6 +6,10 @@
* [gui.h](include/clap/ext/gui.h): documentation clarifications
* [entry.h](include/clap/entry.h): documentation clarifications
+## Draft Extensions
+
+* [incremental-state.h](include/clap/ext/draft/incremental-state.h): incremental state
+
# Changes in 1.1.9
* [entry.h](include/clap/entry.h): clarify what the `plugin_path` is on macOS
diff --git a/include/clap/clap.h b/include/clap/clap.h
@@ -69,3 +69,4 @@
#include "ext/draft/tuning.h"
#include "ext/draft/configurable-audio-ports.h"
#include "ext/draft/extensible-audio-ports.h"
+#include "ext/draft/incremental-state.h"
diff --git a/include/clap/ext/draft/incremental-state.h b/include/clap/ext/draft/incremental-state.h
@@ -0,0 +1,50 @@
+#pragma once
+
+#include "../../plugin.h"
+
+static CLAP_CONSTEXPR const char CLAP_EXT_INCREMENTAL_STATE[] = "clap.incremental-state.draft/0";
+
+// This extension is useful for the host to collect incremental changes instead of saving the plugin
+// state after each changes.
+//
+// The typical use case is for crash recovery:
+// 1. the host saves the entire project (expensive)
+// 2. many things, happens and the host saves little delta operations to disk (cheap)
+// 3. the application crashes
+//
+// Then once the application is restarted, the user can decide to recover the project which will
+// work as follow:
+// 1. open the last project state
+// 2. apply all the deltas in sequence
+// 3. project is ready and should be in the same state as it was before the crash
+//
+// Saving a project, can be an expensive task especially for large project and can
+// cause playback performance issues.
+// This is why saving deltas is interesting because it is lightweight.
+//
+// This interface is not meant to replace saving the entire project.
+//
+// If the plugin decides to implement this interface, it should then be able to encode
+// the deltas in a space efficient way.
+//
+// The plugin can assume that the delta will be applied on the same computer as the
+// one used to produce it. Meaning that it doesn't have to take care of endianness
+// and can store path to files on the computer.
+
+typedef struct clap_plugin_incremental_state {
+ // [main-thread]
+ bool (*apply_delta)(clap_plugin_t *plugin, const char *data, size_t size);
+} clap_plugin_incremental_state_t;
+
+typedef struct clap_host_incremental_state {
+ // Adds a delta, its size should be reasonably small.
+ //
+ // [main-thread]
+ void (*add_delta)(clap_host_t *host, const char *data, size_t size);
+
+ // One change happened which can't be encoded as a delta, and requires
+ // the host to save the entire state again.
+ //
+ // [main-thread]
+ void (*save_is_required)(clap_host_t *host);
+} clap_host_incremental_state_t;
