diff --git a/CMakeLists.txt b/CMakeLists.txt index c3402e1c..9bb4b865 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -12,9 +12,12 @@ target_include_directories(clap-core INTERFACE include) install(DIRECTORY include DESTINATION "." OPTIONAL EXCLUDE_FROM_ALL) +# clap-tests should always be available, to avoid build failing here and there +# because the target doesn't exists +add_custom_target(clap-tests) + if (${CLAP_BUILD_TESTS}) message(STATUS "Including CLAP tests, compile tests, and versions") - add_custom_target(clap-tests) macro(clap_compile_cpp SUFFIX EXT STDC STDCPP) add_executable(clap-compile-${SUFFIX} EXCLUDE_FROM_ALL src/main.${EXT}) diff --git a/ChangeLog.md b/ChangeLog.md index c183fdc2..b6e2cd6a 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,3 +1,13 @@ +# Changes in 1.0.3 + +* [plugin.h](include/clap/plugin.h): fix an inconsistency in `clap_plugin->destroy()` documentation: + it is now **required** to deactivate the plugin before destroying it. +* [params.h](include/clap/ext/params.h): improve documentation for `clap_host_params->request_flush()`. +* [entry.h](include/clap/entry.h): improve documentation regarding `init()`, `deinit()` and CLAP search path. +* [gui.h](inclued/clap/gui.h): fix typo `clap_gui_resize_hints.preserve_aspect_ratio` +* [plugin-template](src/plugin-template.c): missing impl of plugin destroy. +* various documentation improvements + # Changes in 1.0.2 * CMake: add `CLAP_BUILD_TESTS` which enables the tests. diff --git a/README.md b/README.md index ab06760a..39591719 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,6 @@ - [Support extensions](#support-extensions) - [Extra extensions](#extra-extensions) - [Resources](#resources) - - [Plugins](#plugins) - - [Hosts](#hosts) - [Examples](#examples) - [Community related projects](#community-related-projects) - [Programming Language Bindings](#programming-language-bindings) @@ -53,21 +51,21 @@ if (params) } ``` -The extensions are defined in [ext](include/clap/ext) folder. +The extensions are defined in the [ext](include/clap/ext) folder. Some extensions are still in the progress of being designed and they are in the [draft](include/clap/ext/draft) folder. An extension comes with: -- an header `#include ` +- a header `#include ` - an extension identifier: `#define CLAP_EXT_XXX "clap/XXX"` - host interfaces are named like: `struct clap_host_xxx` - plugin interfaces are named like: `struct clap_plugin_xxx` -- each methods must have a clear thread specification +- each method must have a clear thread specification -You can create your own extensions and share them, make sure that the extension identifier +You can create your own extensions and share them. Make sure that the extension identifier: - includes versioning in case the ABI breaks -- a unique identifier +- is a unique identifier **All strings are valid UTF-8**. @@ -106,15 +104,8 @@ and use to get a basic plugin experience: # Resources -## Plugins - -- [u-he](https://u-he.com/fwd/clap/), synthesizers and effects -- [Surge](https://surge-synthesizer.github.io/), open source synthesizer and effect - - CLAP is enabled in [nightly builds](https://github.com/surge-synthesizer/releases-xt/releases/tag/Nightly) - -## Hosts - -- [Bitwig](https://bitwig.com), you need at least _Bitwig Studio 4.3 Beta 5_ +- [clap-validator](https://github.com/robbert-vdh/clap-validator), a validator and automatic test suite for CLAP plugins. +- [clapdb](https://clapdb.tech), a list of plugins and DAWs which supports CLAP ## Examples @@ -127,7 +118,7 @@ and use to get a basic plugin experience: - [clap-juce-extension](https://github.com/free-audio/clap-juce-extension), juce add-on - [MIP2](https://github.com/skei/MIP2), host and plugins - [Avendish](https://github.com/celtera/avendish), a reflection-based API for media plug-ins in C++ which supports Clap -- [nih-plug](https://github.com/robbert-vdh/nih-plug), an API-agnostic, Rust-based plugin framework aiming to reduce boilerplate without getting in your way +- [NIH-plug](https://github.com/robbert-vdh/nih-plug), an API-agnostic, Rust-based plugin framework aiming to reduce boilerplate without getting in your way ## Programming Language Bindings @@ -135,4 +126,5 @@ and use to get a basic plugin experience: - [CLAP-for-Delphi](https://github.com/Bremmers/CLAP-for-Delphi), Delphi binding ## Artwork + - [CLAP Logo Pack.zip](https://github.com/free-audio/clap/files/8805281/CLAP.Logo.Pack.zip) diff --git a/include/clap/entry.h b/include/clap/entry.h index c58676b6..8f3cc1da 100644 --- a/include/clap/entry.h +++ b/include/clap/entry.h @@ -23,23 +23,31 @@ extern "C" { // - /Library/Audio/Plug-Ins/CLAP // - ~/Library/Audio/Plug-Ins/CLAP // -// Additionally, extra path may be specified in CLAP_PATH environment variable. -// CLAP_PATH is formated in the same way as the OS' binary search path (PATH on UNIX, Path on Windows). +// In addition to the OS-specific default locations above, a CLAP host must query the environment +// for a CLAP_PATH variable, which is a list of directories formatted in the same manner as the host +// OS binary search path (PATH on Unix, separated by `:` and Path on Windows, separated by ';', as +// of this writing). // -// Every methods must be thread-safe. +// Each directory should be recursively searched for files and/or bundles as appropriate in your OS +// ending with the extension `.clap`. +// +// Every method must be thread-safe. typedef struct clap_plugin_entry { clap_version_t clap_version; // initialized to CLAP_VERSION // This function must be called first, and can only be called once. // - // It should be as fast as possible, in order to perform very quick scan of the plugin + // It should be as fast as possible, in order to perform a very quick scan of the plugin // descriptors. // // It is forbidden to display graphical user interface in this call. - // It is forbidden to perform user inter-action in this call. + // It is forbidden to perform user interaction in this call. // // If the initialization depends upon expensive computation, maybe try to do them ahead of time // and cache the result. + // + // If init() returns false, then the host must not call deinit() nor any other clap + // related symbols from the DSO. bool (*init)(const char *plugin_path); // No more calls into the DSO must be made after calling deinit(). diff --git a/include/clap/events.h b/include/clap/events.h index 6322211a..db2314f1 100644 --- a/include/clap/events.h +++ b/include/clap/events.h @@ -22,7 +22,7 @@ typedef struct clap_event_header { static const CLAP_CONSTEXPR uint16_t CLAP_CORE_EVENT_SPACE_ID = 0; enum clap_event_flags { - // Indicate a live user event, for example a user turning a phisical knob + // Indicate a live user event, for example a user turning a physical knob // or playing a physical key. CLAP_EVENT_IS_LIVE = 1 << 0, @@ -46,11 +46,11 @@ enum clap_event_flags { // The plugins are encouraged to be able to handle note events encoded as raw midi or midi2, // or implement clap_plugin_event_filter and reject raw midi and midi2 events. enum { - // NOTE_ON and NOTE_OFF represents a key pressed and key released event. + // NOTE_ON and NOTE_OFF represent a key pressed and key released event, respectively. // A NOTE_ON with a velocity of 0 is valid and should not be interpreted as a NOTE_OFF. // // NOTE_CHOKE is meant to choke the voice(s), like in a drum machine when a closed hihat - // chokes an open hihat. This event can be sent by the host to the plugin. Here two use case: + // chokes an open hihat. This event can be sent by the host to the plugin. Here are two use cases: // - a plugin is inside a drum pad in Bitwig Studio's drum machine, and this pad is choked by // another one // - the user double clicks the DAW's stop button in the transport which then stops the sound on @@ -77,11 +77,11 @@ enum { // Host->Plugin NoteOff(port:0, channel:0, key:64, t1) // # on t2, both notes did terminate // Host->Plugin NoteOn(port:0, channel:0, key:64, t3) - // # Here the plugin finished to process all the frames and will tell the host + // # Here the plugin finished processing all the frames and will tell the host // # to terminate the voice on key 16 but not 64, because a note has been started at t3 // Plugin->Host NoteEnd(port:0, channel:0, key:16, time:ignored) // - // Those four events use clap_event_note. + // These four events use clap_event_note. CLAP_EVENT_NOTE_ON, CLAP_EVENT_NOTE_OFF, CLAP_EVENT_NOTE_CHOKE, @@ -102,9 +102,9 @@ enum { CLAP_EVENT_PARAM_VALUE, CLAP_EVENT_PARAM_MOD, - // Indicates that the user started or finished to adjust a knob. - // This is not mandatory to wrap parameter changes with gesture events, but this improves a lot - // the user experience when recording automation or overriding automation playback. + // Indicates that the user started or finished adjusting a knob. + // This is not mandatory to wrap parameter changes with gesture events, but this improves + // the user experience a lot when recording automation or overriding automation playback. // Uses clap_event_param_gesture. CLAP_EVENT_PARAM_GESTURE_BEGIN, CLAP_EVENT_PARAM_GESTURE_END, diff --git a/include/clap/ext/audio-ports-config.h b/include/clap/ext/audio-ports-config.h index 4cb0119c..1ab94d83 100644 --- a/include/clap/ext/audio-ports-config.h +++ b/include/clap/ext/audio-ports-config.h @@ -5,7 +5,7 @@ /// @page Audio Ports Config /// -/// This extension provides a way for the plugin to describe possible ports configurations, for +/// This extension provides a way for the plugin to describe possible port configurations, for /// example mono, stereo, surround, ... and a way for the host to select a configuration. /// /// After the plugin initialization, the host may scan the list of configurations and eventually @@ -18,7 +18,7 @@ /// /// The idea behind the configurations, is to let the user choose one via a menu. /// -/// Plugin with very complex configuration possibilities should let the user configure the ports +/// Plugins with very complex configuration possibilities should let the user configure the ports /// from the plugin GUI, and call @ref clap_host_audio_ports.rescan(CLAP_AUDIO_PORTS_RESCAN_ALL). static CLAP_CONSTEXPR const char CLAP_EXT_AUDIO_PORTS_CONFIG[] = "clap.audio-ports-config"; diff --git a/include/clap/ext/audio-ports.h b/include/clap/ext/audio-ports.h index 78ebe8a0..5d0af462 100644 --- a/include/clap/ext/audio-ports.h +++ b/include/clap/ext/audio-ports.h @@ -27,20 +27,22 @@ enum { // Main port must be at index 0. CLAP_AUDIO_PORT_IS_MAIN = 1 << 0, - // The port can be used with 64 bits audio + // This port can be used with 64 bits audio CLAP_AUDIO_PORT_SUPPORTS_64BITS = 1 << 1, // 64 bits audio is preferred with this port CLAP_AUDIO_PORT_PREFERS_64BITS = 1 << 2, - // This port must be used with the same sample size as all the other ports which have this flags. - // In other words if all ports have this flags then the plugin may either be used entirely with + // This port must be used with the same sample size as all the other ports which have this flag. + // In other words if all ports have this flag then the plugin may either be used entirely with // 64 bits audio or 32 bits audio, but it can't be mixed. CLAP_AUDIO_PORT_REQUIRES_COMMON_SAMPLE_SIZE = 1 << 3, }; typedef struct clap_audio_port_info { - clap_id id; // stable identifier + // id identifies a port and must be stable. + // id may overlap between input and output ports. + clap_id id; char name[CLAP_NAME_SIZE]; // displayable name uint32_t flags; diff --git a/include/clap/ext/draft/ambisonic.h b/include/clap/ext/draft/ambisonic.h index 0cc27297..b545232c 100644 --- a/include/clap/ext/draft/ambisonic.h +++ b/include/clap/ext/draft/ambisonic.h @@ -44,7 +44,7 @@ typedef struct clap_plugin_ambisonic { } clap_plugin_ambisonic_t; typedef struct clap_host_ambisonic { - // Informs the host that the info have changed. + // Informs the host that the info has changed. // The info can only change when the plugin is de-activated. // [main-thread] void (*changed)(const clap_host_t *host); diff --git a/include/clap/ext/draft/file-reference.h b/include/clap/ext/draft/file-reference.h index 5d7f083e..f34aef87 100644 --- a/include/clap/ext/draft/file-reference.h +++ b/include/clap/ext/draft/file-reference.h @@ -20,13 +20,13 @@ extern "C" { /// - filename /// - hash /// - file size -/// - be aware that some external file references are marked as dirty and needs to be saved. +/// - be aware that some external file references are marked as dirty and need to be saved. /// /// Regarding the hashing algorithm, as of 2022 BLAKE3 seems to be the best choice in regards to /// performances and robustness while also providing a very small pure C library with permissive /// licensing. For more info see https://github.com/BLAKE3-team/BLAKE3 /// -/// This extension only expose one hashing algorithm on purpose. +/// This extension only exposes one hashing algorithm on purpose. // This describes a file currently used by the plugin typedef struct clap_file_reference { @@ -35,7 +35,7 @@ typedef struct clap_file_reference { size_t path_capacity; // [in] the number of bytes reserved in path size_t path_size; // [out] the actual length of the path, can be bigger than path_capacity - char *path; // [in,out] path to the file on the disk, must be null terminated, and maybe + char *path; // [in,out] path to the file on the disk, must be null terminated, and may be // truncated if the capacity is less than the size } clap_file_reference_t; diff --git a/include/clap/ext/draft/quick-controls.h b/include/clap/ext/draft/quick-controls.h index a555c96a..3b34cbc2 100644 --- a/include/clap/ext/draft/quick-controls.h +++ b/include/clap/ext/draft/quick-controls.h @@ -3,9 +3,9 @@ #include "../../plugin.h" #include "../../string-sizes.h" -// This extensions provides a set a pages, where each page contains up to 8 controls. +// This extensions provides a set of pages, where each page contains up to 8 controls. // Those controls are param_id, and they are meant to be mapped onto a physical controller. -// We chose 8 because this what most controllers offers, and it is more or less a standard. +// We chose 8 because this what most controllers offer, and it is more or less a standard. static CLAP_CONSTEXPR const char CLAP_EXT_QUICK_CONTROLS[] = "clap.quick-controls.draft/0"; diff --git a/include/clap/ext/draft/surround.h b/include/clap/ext/draft/surround.h index bd07c605..0663f406 100644 --- a/include/clap/ext/draft/surround.h +++ b/include/clap/ext/draft/surround.h @@ -4,7 +4,7 @@ // This extension can be used to specify the channel mapping used by the plugin. // -// To have a consistent surround features across all the plugin instances, +// To have consistent surround features across all the plugin instances, // here is the proposed workflow: // 1. the plugin queries the host preferred channel mapping and // adjusts its configuration to match it. @@ -14,7 +14,7 @@ // 1. deactivate the plugin // 2. host calls clap_plugin_surround->changed() // 3. plugin calls clap_host_surround->get_preferred_channel_map() -// 4. plugin eventualy calls clap_host_surround->changed() +// 4. plugin eventually calls clap_host_surround->changed() // 5. host calls clap_plugin_surround->get_channel_map() if changed // 6. host activates the plugin and can start processing audio // @@ -69,7 +69,7 @@ typedef struct clap_plugin_surround { } clap_plugin_surround_t; typedef struct clap_host_surround { - // Informs the host that the channel map have changed. + // Informs the host that the channel map has changed. // The channel map can only change when the plugin is de-activated. // [main-thread] void (*changed)(const clap_host_t *host); diff --git a/include/clap/ext/draft/transport-control.h b/include/clap/ext/draft/transport-control.h index 70b4df1b..e947337e 100644 --- a/include/clap/ext/draft/transport-control.h +++ b/include/clap/ext/draft/transport-control.h @@ -2,8 +2,8 @@ #include "../../plugin.h" -// This extension let the plugin submit transport requests to the host. -// The host has no obligation to execute those request, so the interface maybe +// This extension lets the plugin submit transport requests to the host. +// The host has no obligation to execute these requests, so the interface may be // partially working. static CLAP_CONSTEXPR const char CLAP_EXT_TRANSPORT_CONTROL[] = "clap.transport-control.draft/0"; @@ -29,7 +29,7 @@ typedef struct clap_host_transport_control { // [main-thread] void (*request_pause)(const clap_host_t *host); - // Equivalent to what "space bar" does with most DAW + // Equivalent to what "space bar" does with most DAWs // [main-thread] void (*request_toggle_play)(const clap_host_t *host); diff --git a/include/clap/ext/draft/tuning.h b/include/clap/ext/draft/tuning.h index 442b15b6..8bb5327a 100644 --- a/include/clap/ext/draft/tuning.h +++ b/include/clap/ext/draft/tuning.h @@ -35,7 +35,7 @@ typedef struct clap_plugin_tuning { // This extension provides a dynamic tuning table to the plugin. typedef struct clap_host_tuning { - // Gets the relative tuning in semitone against equal temperament with A4=440Hz. + // Gets the relative tuning in semitones against equal temperament with A4=440Hz. // The plugin may query the tuning at a rate that makes sense for *low* frequency modulations. // // If the tuning_id is not found or equals to CLAP_INVALID_ID, diff --git a/include/clap/ext/draft/voice-info.h b/include/clap/ext/draft/voice-info.h index 2d776543..8e9341b0 100644 --- a/include/clap/ext/draft/voice-info.h +++ b/include/clap/ext/draft/voice-info.h @@ -2,7 +2,7 @@ #include "../../plugin.h" -// This extensions indicates the number of voices the synthesizer. +// This extension indicates the number of voices the synthesizer has. // It is useful for the host when performing polyphonic modulations, // because the host needs its own voice management and should try to follow // what the plugin is doing: @@ -46,7 +46,7 @@ typedef struct clap_plugin_voice_info { } clap_plugin_voice_info_t; typedef struct clap_host_voice_info { - // informs the host that the voice info have changed + // informs the host that the voice info has changed // [main-thread] void (*changed)(const clap_host_t *host); } clap_host_voice_info_t; diff --git a/include/clap/ext/gui.h b/include/clap/ext/gui.h index 944dd7ef..dec26421 100644 --- a/include/clap/ext/gui.h +++ b/include/clap/ext/gui.h @@ -80,19 +80,19 @@ typedef struct clap_window { }; } clap_window_t; -// Information to improve window resizement when initiated by the host or window manager. +// Information to improve window resizing when initiated by the host or window manager. typedef struct clap_gui_resize_hints { bool can_resize_horizontally; bool can_resize_vertically; // only if can resize horizontally and vertically - bool preseve_aspect_ratio; + bool preserve_aspect_ratio; uint32_t aspect_ratio_width; uint32_t aspect_ratio_height; } clap_gui_resize_hints_t; // Size (width, height) is in pixels; the corresponding windowing system extension is -// responsible to define if it is physical pixels or logical pixels. +// responsible for defining if it is physical pixels or logical pixels. typedef struct clap_plugin_gui { // Returns true if the requested gui api is supported // [main-thread] @@ -173,8 +173,8 @@ typedef struct clap_plugin_gui { // [main-thread] bool (*show)(const clap_plugin_t *plugin); - // Hide the window, this method do not free the resources, it just hides - // the window content. Yet it maybe a good idea to stop painting timers. + // Hide the window, this method does not free the resources, it just hides + // the window content. Yet it may be a good idea to stop painting timers. // [main-thread] bool (*hide)(const clap_plugin_t *plugin); } clap_plugin_gui_t; @@ -189,7 +189,7 @@ typedef struct clap_host_gui { * The host doesn't have to call set_size(). * * Note: if not called from the main thread, then a return value simply means that the host - * acknowledge the request and will process it asynchronously. If the request then can't be + * acknowledged the request and will process it asynchronously. If the request then can't be * satisfied then the host will call set_size() to revert the operation. * * [thread-safe] */ diff --git a/include/clap/ext/log.h b/include/clap/ext/log.h index fa14e6e0..bc3c2138 100644 --- a/include/clap/ext/log.h +++ b/include/clap/ext/log.h @@ -15,7 +15,7 @@ enum { CLAP_LOG_ERROR = 3, CLAP_LOG_FATAL = 4, - // Those severities should be used to report misbehaviour. + // These severities should be used to report misbehaviour. // The plugin one can be used by a layer between the plugin and the host. CLAP_LOG_HOST_MISBEHAVING = 5, CLAP_LOG_PLUGIN_MISBEHAVING = 6, diff --git a/include/clap/ext/note-name.h b/include/clap/ext/note-name.h index dbee5bff..288ace7b 100644 --- a/include/clap/ext/note-name.h +++ b/include/clap/ext/note-name.h @@ -27,7 +27,7 @@ typedef struct clap_plugin_note_name { } clap_plugin_note_name; typedef struct clap_host_note_name { - // Informs the host that the note names has changed. + // Informs the host that the note names have changed. // [main-thread] void (*changed)(const clap_host_t *host); } clap_host_note_name_t; diff --git a/include/clap/ext/note-ports.h b/include/clap/ext/note-ports.h index eeb9d0b0..10bb2d87 100644 --- a/include/clap/ext/note-ports.h +++ b/include/clap/ext/note-ports.h @@ -30,7 +30,9 @@ enum clap_note_dialect { }; typedef struct clap_note_port_info { - clap_id id; // stable identifier + // id identifies a port and must be stable. + // id may overlap between input and output ports. + clap_id id; uint32_t supported_dialects; // bitfield, see clap_note_dialect uint32_t preferred_dialect; // one value of clap_note_dialect char name[CLAP_NAME_SIZE]; // displayable name, i18n? diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h index bbb4df1f..27396a3d 100644 --- a/include/clap/ext/params.h +++ b/include/clap/ext/params.h @@ -8,24 +8,24 @@ /// /// Main idea: /// -/// The host sees the plugin as an atomic entity; and acts as a controler on top of its parameters. -/// The plugin is responsible to keep in sync its audio processor and its GUI. +/// The host sees the plugin as an atomic entity; and acts as a controller on top of its parameters. +/// The plugin is responsible for keeping its audio processor and its GUI in sync. /// -/// The host can read at any time parameters value on the [main-thread] using +/// The host can at any time read parameters' value on the [main-thread] using /// @ref clap_plugin_params.value(). /// -/// There is two options to communicate parameter value change, and they are not concurrent. +/// There are two options to communicate parameter value changes, and they are not concurrent. /// - send automation points during clap_plugin.process() -/// - send automation points during clap_plugin_params.flush(), this one is used when the plugin is -/// not processing +/// - send automation points during clap_plugin_params.flush(), for parameter changes +/// without processing audio /// /// When the plugin changes a parameter value, it must inform the host. /// It will send @ref CLAP_EVENT_PARAM_VALUE event during process() or flush(). /// If the user is adjusting the value, don't forget to mark the begining and end -/// of the gesture by send CLAP_EVENT_PARAM_GESTURE_BEGIN and CLAP_EVENT_PARAM_GESTURE_END events. +/// of the gesture by sending CLAP_EVENT_PARAM_GESTURE_BEGIN and CLAP_EVENT_PARAM_GESTURE_END events. /// -/// @note MIDI CCs are a tricky because you may not know when the parameter adjustment ends. -/// Also if the hosts records incoming MIDI CC and parameter change automation at the same time, +/// @note MIDI CCs are tricky because you may not know when the parameter adjustment ends. +/// Also if the host records incoming MIDI CC and parameter change automation at the same time, /// there will be a conflict at playback: MIDI CC vs Automation. /// 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. @@ -41,25 +41,25 @@ /// - 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 +/// - if the plugin is activated and the preset will introduce breaking changes /// (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. +/// The plugin is resonsible for updating both its audio processor and its gui. /// /// II. Turning a knob on the DAW interface /// - the host will send an automation event to the plugin via a process() or flush() /// /// III. Turning a knob on the Plugin interface -/// - if the plugin is not processing, call clap_host_params->request_flush() or -/// clap_host->request_process(). -/// - send an automation event and don't forget to set begin_adjust, end_adjust and should_record -/// flags -/// - the plugin is responsible to send the parameter value to its audio processor +/// - the plugin is responsible for sending the parameter value to its audio processor +/// - call clap_host_params->request_flush() or clap_host->request_process(). +/// - when the host calls either clap_plugin->process() or clap_plugin_params->flush(), +/// send an automation event and don't forget to set begin_adjust, +/// end_adjust and should_record flags /// /// IV. Turning a knob via automation /// - host sends an automation point during clap_plugin->process() or clap_plugin_params->flush(). -/// - the plugin is responsible to update its GUI +/// - the plugin is responsible for updating its GUI /// /// V. Turning a knob via plugin's internal MIDI mapping /// - the plugin sends a CLAP_EVENT_PARAM_SET output event, set should_record to false @@ -111,31 +111,31 @@ enum { // host->request_restart(), and perform the change once the plugin is re-activated. CLAP_PARAM_IS_AUTOMATABLE = 1 << 5, - // Does this param supports per note automations? + // Does this parameter support per note automations? CLAP_PARAM_IS_AUTOMATABLE_PER_NOTE_ID = 1 << 6, - // Does this param supports per note automations? + // Does this parameter support per key automations? CLAP_PARAM_IS_AUTOMATABLE_PER_KEY = 1 << 7, - // Does this param supports per channel automations? + // Does this parameter support per channel automations? CLAP_PARAM_IS_AUTOMATABLE_PER_CHANNEL = 1 << 8, - // Does this param supports per port automations? + // Does this parameter support per port automations? CLAP_PARAM_IS_AUTOMATABLE_PER_PORT = 1 << 9, - // Does the parameter support the modulation signal? + // Does this parameter support the modulation signal? CLAP_PARAM_IS_MODULATABLE = 1 << 10, - // Does this param supports per note automations? + // Does this parameter support per note automations? CLAP_PARAM_IS_MODULATABLE_PER_NOTE_ID = 1 << 11, - // Does this param supports per note automations? + // Does this parameter support per key automations? CLAP_PARAM_IS_MODULATABLE_PER_KEY = 1 << 12, - // Does this param supports per channel automations? + // Does this parameter support per channel automations? CLAP_PARAM_IS_MODULATABLE_PER_CHANNEL = 1 << 13, - // Does this param supports per channel automations? + // Does this parameter support per port automations? CLAP_PARAM_IS_MODULATABLE_PER_PORT = 1 << 14, // Any change to this parameter will affect the plugin output and requires to be done via @@ -210,10 +210,8 @@ typedef struct clap_plugin_params { // Flushes a set of parameter changes. // This method must not be called concurrently to clap_plugin->process(). - // This method must not be used if the plugin is processing. // - // [active && !processing : audio-thread] - // [!active : main-thread] + // [active ? audio-thread : main-thread] void (*flush)(const clap_plugin_t *plugin, const clap_input_events_t *in, const clap_output_events_t *out); @@ -279,16 +277,15 @@ typedef struct clap_host_params { // [main-thread] void (*clear)(const clap_host_t *host, clap_id param_id, clap_param_clear_flags flags); - // Request the host to call clap_plugin_params->fush(). - // This is useful if the plugin has parameters value changes to report to the host but the plugin - // is not processing. - // - // eg. the plugin has a USB socket to some hardware controllers and receives a parameter change - // while it is not processing. + + // Request a parameter flush. // - // This must not be called on the [audio-thread]. + // The host will then schedule a call to either: + // - clap_plugin.process() + // - clap_plugin_params->flush() // - // [thread-safe] + // This function is always safe to use and must not be called on the [audio-thread]. + // [thread-safe,!audio-thread] void (*request_flush)(const clap_host_t *host); } clap_host_params_t; diff --git a/include/clap/ext/thread-pool.h b/include/clap/ext/thread-pool.h index 2b4d6354..7261a5f8 100644 --- a/include/clap/ext/thread-pool.h +++ b/include/clap/ext/thread-pool.h @@ -4,10 +4,10 @@ /// @page /// -/// This extension let the plugin use the host's thread pool. +/// This extension lets the plugin use the host's thread pool. /// /// The plugin must provide @ref clap_plugin_thread_pool, and the host may provide @ref -/// clap_host_thread_pool. If it doesn't, the plugin should process its data by its own mean. In the +/// clap_host_thread_pool. If it doesn't, the plugin should process its data by its own means. In the /// worst case, a single threaded for-loop. /// /// Simple example with N voices to process @@ -27,7 +27,7 @@ /// /// if (!didComputeVoices) /// for (uint32_t i = 0; i < N; ++i) -/// myplug_thread_pool_exec(plugin, N); +/// myplug_thread_pool_exec(plugin, i); /// ... /// } /// @endcode diff --git a/include/clap/plugin-factory.h b/include/clap/plugin-factory.h index 866c17e2..07e8560c 100644 --- a/include/clap/plugin-factory.h +++ b/include/clap/plugin-factory.h @@ -8,7 +8,7 @@ static const CLAP_CONSTEXPR char CLAP_PLUGIN_FACTORY_ID[] = "clap.plugin-factory extern "C" { #endif -// Every methods must be thread-safe. +// Every method must be thread-safe. // It is very important to be able to scan the plugin as quickly as possible. // // If the content of the factory may change due to external events, like the user installed diff --git a/include/clap/plugin-features.h b/include/clap/plugin-features.h index cb6f78e4..624ab39b 100644 --- a/include/clap/plugin-features.h +++ b/include/clap/plugin-features.h @@ -2,13 +2,13 @@ #include "private/macros.h" -// This files provides a set of standard plugin features meant to be use +// This file provides a set of standard plugin features meant to be used // within clap_plugin_descriptor.features. // // For practical reasons we'll avoid spaces and use `-` instead to facilitate // scripts that generate the feature array. // -// Non standard feature should be formated as follow: "$namespace:$feature" +// Non-standard features should be formated as follow: "$namespace:$feature" ///////////////////// // Plugin category // diff --git a/include/clap/plugin.h b/include/clap/plugin.h index 4f602a83..dedeac89 100644 --- a/include/clap/plugin.h +++ b/include/clap/plugin.h @@ -41,7 +41,7 @@ typedef struct clap_plugin { bool (*init)(const struct clap_plugin *plugin); // Free the plugin and its resources. - // It is not required to deactivate the plugin prior to this call. + // It is required to deactivate the plugin prior to this call. // [main-thread & !active] void (*destroy)(const struct clap_plugin *plugin); diff --git a/include/clap/process.h b/include/clap/process.h index f346bfa3..d5bf572a 100644 --- a/include/clap/process.h +++ b/include/clap/process.h @@ -11,18 +11,18 @@ enum { // Processing failed. The output buffer must be discarded. CLAP_PROCESS_ERROR = 0, - // Processing succeed, keep processing. + // Processing succeeded, keep processing. CLAP_PROCESS_CONTINUE = 1, - // Processing succeed, keep processing if the output is not quiet. + // Processing succeeded, keep processing if the output is not quiet. CLAP_PROCESS_CONTINUE_IF_NOT_QUIET = 2, // Rely upon the plugin's tail to determine if the plugin should continue to process. // see clap_plugin_tail CLAP_PROCESS_TAIL = 3, - // Processing succeed, but no more processing is required, - // until next event or variation in audio input. + // Processing succeeded, but no more processing is required, + // until the next event or variation in audio input. CLAP_PROCESS_SLEEP = 4, }; typedef int32_t clap_process_status; @@ -37,7 +37,7 @@ typedef struct clap_process { // and must be increased by at least `frames_count` for the next call to process. int64_t steady_time; - // Number of frame to process + // Number of frames to process uint32_t frames_count; // time info at sample 0 diff --git a/include/clap/version.h b/include/clap/version.h index da2a2a6c..ab66ea3a 100644 --- a/include/clap/version.h +++ b/include/clap/version.h @@ -22,7 +22,7 @@ typedef struct clap_version { #define CLAP_VERSION_MAJOR ((uint32_t)1) #define CLAP_VERSION_MINOR ((uint32_t)0) -#define CLAP_VERSION_REVISION ((uint32_t)2) +#define CLAP_VERSION_REVISION ((uint32_t)3) #define CLAP_VERSION_INIT {CLAP_VERSION_MAJOR, CLAP_VERSION_MINOR, CLAP_VERSION_REVISION} static const CLAP_CONSTEXPR clap_version_t CLAP_VERSION = CLAP_VERSION_INIT; diff --git a/src/plugin-template.c b/src/plugin-template.c index ee300539..eeb4f224 100644 --- a/src/plugin-template.c +++ b/src/plugin-template.c @@ -114,7 +114,10 @@ static bool my_plug_init(const struct clap_plugin *plugin) { return true; } -static void my_plug_destroy(const struct clap_plugin *plugin) {} +static void my_plug_destroy(const struct clap_plugin *plugin) { + my_plug_t *plug = plugin->plugin_data; + free(plug); +} static bool my_plug_activate(const struct clap_plugin *plugin, double sample_rate, @@ -142,7 +145,7 @@ static void my_plug_process_event(my_plug_t *plug, const clap_event_header_t *hd case CLAP_EVENT_NOTE_OFF: { const clap_event_note_t *ev = (const clap_event_note_t *)hdr; - // TODO: handle note on + // TODO: handle note off break; }