Merge pull request #106 from free-audio/next

1.0.3

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})

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.

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 <clap/ext/xxx.h>`
+- a header `#include <clap/ext/xxx.h>`
 - 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,12 +118,13 @@ 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
 
 - [clap-sys](https://github.com/glowcoil/clap-sys), rust binding
 - [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)

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().

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,

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";

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;

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);

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;
 

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";
 

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);

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);
 

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,

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;

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] */