clap

commit c1c491062044c6c6ac71ac1602fb9245df854a17
parent c56eaa9aee042031ebb31f073a416f13d5d12bb2
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date:   Tue, 15 Aug 2023 11:17:13 +0200

Merge pull request #335 from abique/incremental-state

Introduce incremental state
Diffstat:
M
ChangeLog.md
 | 
4
++++
M
include/clap/clap.h
 | 
1
+
A
include/clap/ext/draft/incremental-state.h
 | 
50
++++++++++++++++++++++++++++++++++++++++++++++++++

3 files changed, 55 insertions(+), 0 deletions(-)
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -11,6 +11,10 @@
 
 * [undo.h](include/clap/ext/draft/undo.h): undo support
 
+## 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,4 +69,5 @@
 #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"
 #include "ext/draft/undo.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;