clap

CLAP Audio Plugin API
Log | Files | Refs | README | LICENSE

commit 40843f0e86ff2e33bc1609044bd6157c54f19726
parent 5125342f0bcf350cc7ce00653bcae5447c459d67
Author: Alexandre BIQUE <bique.alexandre@gmail.com>
Date:   Thu, 10 Jun 2021 14:30:39 +0200

Improve the documentation

Diffstat:
Minclude/clap/ext/gui.h | 3+++
Minclude/clap/ext/params.h | 21++++++++++++++-------
Minclude/clap/ext/render.h | 4++--
Minclude/clap/ext/state.h | 14++++++++------
Minclude/clap/ext/thread-check.h | 4++--
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;