clap

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

commit 05113e71987212948685c766317e212df56c0752
parent add8847cffcf973a803f3d297e231d9dbd2750df
Author: joshnatis <31445542+joshnatis@users.noreply.github.com>
Date:   Fri, 24 Jun 2022 16:32:20 -0400

Merge branch 'next' into main
Diffstat:
MCMakeLists.txt | 5++++-
MChangeLog.md | 9+++++++++
MREADME.md | 4+++-
Minclude/clap/entry.h | 9+++++++--
Minclude/clap/ext/draft/quick-controls.h | 2+-
Minclude/clap/ext/gui.h | 2+-
Minclude/clap/ext/params.h | 15++++++++-------
Minclude/clap/ext/thread-pool.h | 2+-
Minclude/clap/plugin.h | 2+-
Msrc/plugin-template.c | 5++++-
10 files changed, 39 insertions(+), 16 deletions(-)

diff --git 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 @@ -1,3 +1,12 @@ +# 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 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. + # Changes in 1.0.2 * CMake: add `CLAP_BUILD_TESTS` which enables the tests. diff --git a/README.md b/README.md @@ -115,6 +115,8 @@ and use to get a basic plugin experience: ## Hosts - [Bitwig](https://bitwig.com), you need at least _Bitwig Studio 4.3 Beta 5_ +- [MultitrackStudio](https://www.multitrackstudio.com/), you need at least _MultitrackStudio 10.4.1_ +- [Qtractor](https://www.qtractor.org) ## Examples @@ -127,7 +129,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 diff --git a/include/clap/entry.h b/include/clap/entry.h @@ -23,8 +23,13 @@ extern "C" { // - /Library/Audio/Plug-Ins/CLAP // - ~/Library/Audio/Plug-Ins/CLAP // -// Additionally, extra paths may be specified in CLAP_PATH environment variable. -// CLAP_PATH is formatted 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). +// +// 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 { diff --git a/include/clap/ext/draft/quick-controls.h b/include/clap/ext/draft/quick-controls.h @@ -3,7 +3,7 @@ #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 offer, and it is more or less a standard. diff --git a/include/clap/ext/gui.h b/include/clap/ext/gui.h @@ -86,7 +86,7 @@ typedef struct clap_gui_resize_hints { 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; diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h @@ -279,16 +279,17 @@ 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 parameter value changes to report to the host but the plugin - // is not processing. + + // Request a parameter flush. // - // eg. the plugin has a USB socket to some hardware controllers and receives a parameter change - // while it is not processing. + // If the plugin is processing, this will result in no action. The process call + // will run normally. If plugin isn't processing, the host will make a subsequent + // call to clap_plugin_params->flush(). As a result, this function is always + // safe to call from a non-audio thread (typically the UI thread on a gesture) + // whether processing is active or not. // // This must not be called on the [audio-thread]. - // - // [thread-safe] + // [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 @@ -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.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/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,