Initial commit

tests/clap/ext/state-context.h

@@ -0,0 +1,72 @@
+#pragma once
+
+#include "../plugin.h"
+#include "../stream.h"
+
+/// @page state-context extension
+/// @brief extended state handling
+///
+/// This extension lets the host save and load the plugin state with different semantics depending
+/// on the context.
+///
+/// Briefly, when loading a preset or duplicating a device, the plugin may want to partially load
+/// the state and initialize certain things differently, like handling limited resources or fixed
+/// connections to external hardware resources.
+///
+/// Save and Load operations may have a different context.
+/// All three operations should be equivalent:
+/// 1. clap_plugin_state_context.load(clap_plugin_state.save(), CLAP_STATE_CONTEXT_FOR_PRESET)
+/// 2. clap_plugin_state.load(clap_plugin_state_context.save(CLAP_STATE_CONTEXT_FOR_PRESET))
+/// 3. clap_plugin_state_context.load(
+///        clap_plugin_state_context.save(CLAP_STATE_CONTEXT_FOR_PRESET),
+///        CLAP_STATE_CONTEXT_FOR_PRESET)
+///
+/// If in doubt, fallback to clap_plugin_state.
+///
+/// If the plugin implements CLAP_EXT_STATE_CONTEXT then it is mandatory to also implement
+/// CLAP_EXT_STATE.
+///
+/// It is unspecified which context is equivalent to clap_plugin_state.{save,load}()
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context/2";
+
+enum clap_plugin_state_context_type {
+   // suitable for storing and loading a state as a preset
+   CLAP_STATE_CONTEXT_FOR_PRESET = 1,
+
+  // suitable for duplicating a plugin instance
+   CLAP_STATE_CONTEXT_FOR_DUPLICATE = 2,
+
+   // suitable for storing and loading a state within a project/song
+   CLAP_STATE_CONTEXT_FOR_PROJECT = 3,
+};
+
+typedef struct clap_plugin_state_context {
+   // Saves the plugin state into stream, according to context_type.
+   // Returns true if the state was correctly saved.
+   //
+   // Note that the result may be loaded by both clap_plugin_state.load() and
+   // clap_plugin_state_context.load().
+   // [main-thread]
+   bool(CLAP_ABI *save)(const clap_plugin_t  *plugin,
+                        const clap_ostream_t *stream,
+                        uint32_t              context_type);
+
+   // Loads the plugin state from stream, according to context_type.
+   // Returns true if the state was correctly restored.
+   //
+   // Note that the state may have been saved by clap_plugin_state.save() or
+   // clap_plugin_state_context.save() with a different context_type.
+   // [main-thread]
+   bool(CLAP_ABI *load)(const clap_plugin_t  *plugin,
+                        const clap_istream_t *stream,
+                        uint32_t              context_type);
+} clap_plugin_state_context_t;
+
+#ifdef __cplusplus
+}
+#endif