commit 40843f0e86ff2e33bc1609044bd6157c54f19726
parent 5125342f0bcf350cc7ce00653bcae5447c459d67
Author: Alexandre BIQUE <bique.alexandre@gmail.com>
Date: Thu, 10 Jun 2021 14:30:39 +0200
Improve the documentation
Diffstat:
5 files changed, 29 insertions(+), 17 deletions(-)
diff --git a/include/clap/ext/gui.h b/include/clap/ext/gui.h
@@ -18,7 +18,10 @@ typedef struct clap_plugin_gui {
// [main-thread]
void (*set_scale)(const clap_plugin *plugin, double scale);
+ // [main-thread]
void (*show)(const clap_plugin *plugin);
+
+ // [main-thread]
void (*hide)(const clap_plugin *plugin);
// [main-thread]
diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h
@@ -42,17 +42,24 @@ extern "C" {
/// The parameter automation will always target the same parameter because the param_id is stable.
/// The MIDI CC may have a different mapping in the future and may result in a different playback.
///
-/// It is highly recommanded to use @ref clap_plugin_midi_mappings to let the host solve
+/// It is recommanded to use @ref clap_plugin_midi_mappings to let the host solve
/// this problem and offer a consistent experience to the user across different plugins.
///
+/// There is an other option to handle MIDI CC if you don't want to use @ref clap_midi_mappings,
+/// which is to set @ref clap_event_param.should_record to false. Then the host will record the
+/// MIDI CC automation, but not the parameter change and there won't be conflict at playback.
+///
/// Scenarios:
///
/// I. Loading a preset
-/// - load the preset in a temporary state, if the plugin is activated and preset will introduce
-/// breaking change like latency, audio ports change, new parameters, ...
-/// report those to the host and wait for the host to deactivate the plugin
-/// to apply those changes. If there are no breaking changes, the plugin can apply them
-/// them right away.
+/// - load the preset in a temporary state
+/// - call @ref clap_host_params.changed() if anything changed
+/// - call @ref clap_host_latency.changed() if latency changed
+/// - invalidate any other info that may be cached by the host
+/// - if the plugin is activated and the preset will introduce breaking change
+/// (latency, audio ports, new parameters, ...) be sure to wait for the host
+/// to deactivate the plugin to apply those changes.
+/// If there are no breaking changes, the plugin can apply them them right away.
/// The plugin is resonsible to update both its audio processor and its gui.
///
/// II. Turning a knob on the DAW interface
@@ -65,7 +72,7 @@ extern "C" {
/// - host_params->adjust(...) many times -> updates host's knob and record automation
/// - host_params->end_adjust(...)
/// - if the plugin is active
-/// - send CLAP_PARAM_SET event and don't forget to set begin_adjust and end_adjust attributes
+/// - send CLAP_PARAM_SET event and don't forget to set begin_adjust, end_adjust and should_record attributes
/// - the plugin is responsible to send the parameter value to its audio processor
///
/// IV. Turning a knob via automation
diff --git a/include/clap/ext/render.h b/include/clap/ext/render.h
@@ -9,10 +9,10 @@ extern "C" {
#endif
enum {
- /* Default setting, used to play "realtime". */
+ // Default setting, used to play "realtime"
CLAP_RENDER_REALTIME = 0,
- /* Render setting, used while rendering the song. */
+ // Used while rendering the song; no realtime pressure
CLAP_RENDER_OFFLINE = 1,
};
typedef int32_t clap_plugin_render_mode;
diff --git a/include/clap/ext/state.h b/include/clap/ext/state.h
@@ -10,12 +10,14 @@ extern "C" {
#endif
typedef struct clap_plugin_state {
- /* Saves the plugin state into stream.
- * [main-thread] */
+ // Saves the plugin state into stream.
+ // Returns true if the state was correctly saved.
+ // [main-thread]
bool (*save)(const clap_plugin *plugin, clap_ostream *stream);
- /* Loads the plugin state from stream.
- * [main-thread] */
+ // Loads the plugin state from stream.
+ // Returns true if the state was correctly restored.
+ // [main-thread]
bool (*load)(const clap_plugin *plugin, clap_istream *stream);
// [main-thread]
@@ -23,8 +25,8 @@ typedef struct clap_plugin_state {
} clap_plugin_state;
typedef struct clap_host_state {
- /* Tell the host that the plugin state has changed.
- * [thread-safe] */
+ // Tell the host that the plugin state has changed and should be saved again.
+ // [thread-safe]
void (*mark_dirty)(const clap_host *host);
} clap_host_state;
diff --git a/include/clap/ext/thread-check.h b/include/clap/ext/thread-check.h
@@ -12,11 +12,11 @@ extern "C" {
// sure that the functions are called on the correct threads.
// It is highly recommended to implement this extension
typedef struct clap_host_thread_check {
- // Returns true if the "this" thread is the main thread.
+ // Returns true if "this" thread is the main thread.
// [thread-safe]
bool (*is_main_thread)(const clap_host *host);
- // Returns true if the "this" thread is one of the audio threads.
+ // Returns true if "this" thread is one of the audio threads.
// [thread-safe]
bool (*is_audio_thread)(const clap_host *host);
} clap_host_thread_check;
