Merge branch 'next' into main

ChangeLog.md

@@ -1,3 +1,20 @@
+# Changes in 1.2.3
+
+## New draft extensions
+
+* [scratch-memory](include/clap/ext/draft/scratch-memory.h): host provided scratch memory within the process call
+* [location](include/clap/ext/draft/location.h): better info about the plugin location within the project
+
+## Documention
+
+* [events.h](include/clap/events.h): clarify sysex lifetime
+* [host.h](include/clap/host.h): clarify `request_callback()`
+* [ambisonic.h](include/clap/ext/ambisonic.h): remove bad comment
+
+## Fixes
+
+* [plugin-template.c](src/plugin-template.c): fix bad assertion
+
 # Changes in 1.2.2
 
 * [thread-check.h](include/clap/ext/thread-check.h): expand the thread-doc to clarify and expand realtime

include/clap/all.h

@@ -9,6 +9,8 @@
 #include "ext/draft/resource-directory.h"
 #include "ext/draft/transport-control.h"
 #include "ext/draft/triggers.h"
+#include "ext/draft/location.h"
 #include "ext/draft/tuning.h"
 #include "ext/draft/undo.h"
 #include "ext/draft/web.h"
+#include "ext/draft/scratch-memory.h"

include/clap/color.h

@@ -13,6 +13,8 @@ typedef struct clap_color {
    uint8_t blue;
 } clap_color_t;
 
+static const CLAP_CONSTEXPR clap_color_t CLAP_COLOR_TRANSPARENT = { 0, 0, 0, 0 };
+
 #ifdef __cplusplus
 }
 #endif

include/clap/events.h

@@ -297,11 +297,27 @@ typedef struct clap_event_midi {
    uint8_t  data[3];
 } clap_event_midi_t;
 
+// clap_event_midi_sysex contains a pointer to a sysex contents buffer.
+// The lifetime of this buffer is (from host->plugin) only the process
+// call in which the event is delivered or (from plugin->host) only the
+// duration of a try_push call.
+//
+// Since `clap_output_events.try_push` requires hosts to make a copy of
+// an event, host implementers receiving sysex messages from plugins need
+// to take care to both copy the event (so header, size, etc...) but
+// also memcpy the contents of the sysex pointer to host-owned memory, and
+// not just copy the data pointer.
+//
+// Similarly plugins retaining the sysex outside the lifetime of a single
+// process call must copy the sysex buffer to plugin-owned memory.
+//
+// As a consequence, the data structure pointed to by the sysex buffer
+// must be contiguous and copyable with `memcpy` of `size` bytes.
 typedef struct clap_event_midi_sysex {
    clap_event_header_t header;
 
    uint16_t       port_index;
-   const uint8_t *buffer; // midi buffer
+   const uint8_t *buffer; // midi buffer. See lifetime comment above.
    uint32_t       size;
 } clap_event_midi_sysex_t;
 

include/clap/ext/ambisonic.h

@@ -43,9 +43,6 @@ typedef struct clap_plugin_ambisonic {
                                        const clap_ambisonic_config_t *config);
 
    // Returns true on success
-   //
-   // config_id: the configuration id, see clap_plugin_audio_ports_config.
-   // If config_id is CLAP_INVALID_ID, then this function queries the current port info.
    // [main-thread]
    bool(CLAP_ABI *get_config)(const clap_plugin_t     *plugin,
                               bool                     is_input,

include/clap/ext/draft/location.h

@@ -0,0 +1,51 @@
+#pragma once
+
+#include "../../plugin.h"
+#include "../../color.h"
+
+// This extension allows a host to tell the plugin more about its position 
+// within a project or session. 
+
+static CLAP_CONSTEXPR const char CLAP_EXT_LOCATION[] = "clap.location/1";
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+enum {
+   CLAP_PLUGIN_LOCATION_PROJECT,
+   CLAP_PLUGIN_LOCATION_TRACK,
+   CLAP_PLUGIN_LOCATION_TRACK_GROUP,
+   CLAP_PLUGIN_LOCATION_DEVICE,
+   CLAP_PLUGIN_LOCATION_DEVICE_PARALLEL_GROUP,
+   CLAP_PLUGIN_LOCATION_DEVICE_SERIAL_GROUP,
+};
+
+typedef struct clap_plugin_location_element {
+   // Internal ID of the element. This is not intended for display to the user, 
+   // but rather to give the host a potential quick way for lookups.
+   const char *id;
+   // User friendly name of the element.
+   const char *name;
+   // Kind of the element, must be one of the CLAP_PLUGIN_LOCATION_* values.
+   int kind;
+   // Index within the parent element. 
+   uint32_t index_in_group;
+   // Color for this element, should be CLAP_COLOR_TRANSPARENT if no color is 
+   // used for this element. 
+   clap_color_t color;
+} clap_plugin_location_element_t;
+
+
+typedef struct clap_plugin_location {
+   // Called by the host when the location of the plugin instance changes.
+   //
+   // The last item in this array always refers to the device itself, and as 
+   // such is expected to be of kind CLAP_PLUGIN_LOCATION_DEVICE. 
+   // [main-thread]
+   void (*set_location)(clap_plugin_t *plugin, clap_plugin_location_element_t *path, int num_elements);
+} clap_plugin_location_t;
+
+#ifdef __cplusplus
+}
+#endif

include/clap/ext/draft/scratch-memory.h

@@ -0,0 +1,91 @@
+#pragma once
+
+#include "../../plugin.h"
+
+// This extension lets the plugin request "scratch" memory
+// from the host. Scratch memory can be accessed during the
+// `process()` callback, but its content not persistent
+// between callbacks.
+//
+// The motivation for this extension is to allow the plugin host
+// to "share" a single scratch buffer across multiple plugin
+// instances.
+//
+// For example, imagine the host needs to process three plugins
+// in sequence, and each plugin requires 10K of scratch memory.
+// If each plugin pre-allocates its own scratch memory, then 30K
+// of memory is being allocated in total. However, if each plugin
+// requests 10K of scratch memory from the host, then the host can
+// allocate a single 10K scratch buffer, and make it available to all
+// three plugins.
+//
+// This optimization may allow for reduced memory usage and improved
+// CPU cache usage.
+
+static CLAP_CONSTEXPR const char CLAP_EXT_SCRATCH_MEMORY[] = "clap.scratch-memory/1";
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct clap_host_scratch_memory {
+   // Asks the host for certain amount of scratch memory.
+   // If the host is unable to provide the memory, it should
+   // return "false".
+   //
+   // The plugin may call this method multiple times (for
+   // example, gradually decreasing the amount of scratch
+   // being asked for until the host returns true), however,
+   // the plugin should avoid calling this method un-neccesarily
+   // since the host implementation may be relatively expensive.
+   // If the plugin calls `reserve()` multiple times, then the
+   // final call determines the actual amount of scratch memory
+   // that will be available to the plugin. If the final call
+   // returns false then no scratch memory will be provided,
+   // regardless of any previous calls to `reserve()`.
+   //
+   // When the plugin is de-activated, the scratch memory
+   // is invalidated, and the host may free the memory if
+   // appropriate. The plugin will need to reserve scratch
+   // memory again the next time it is activated.
+   //
+   // In the context of plugins and hosts that implement
+   // the "thread-pool" extension, scratch memory is assumed
+   // to be "thread-local". The plugin should request the maximum
+   // amount of scratch memory that it will need on a single
+   // thread. Accordingly, the host must ensure that each
+   // thread can independently provide the requested amount
+   // of scratch memory.
+   //
+   // [main-thread & being-activated]
+   bool(CLAP_ABI *reserve)(const clap_host_t *host, uint32_t scratch_size_bytes);
+
+   // Asks the host for the previously reserved scratch memory.
+   // If the host returned "true" when scratch memory was requested,
+   // then this method must return a pointer to a memory block at least
+   // as large as the reserved size. If the host returned "false"
+   // when scratch memory was requested, then this method must not
+   // be called, and will return NULL.
+   //
+   // This method may only be called by the plugin from the audio thread,
+   // (i.e. during the process() or thread_pool.exec() callback), and
+   // the provided memory is only valid until the plugin returns from
+   // that callback. The plugin must not hold any references to data
+   // that lives in the scratch memory after returning from the callback,
+   // as that data will likely be over-written by another plugin using
+   // the same scratch memory.
+   //
+   // The provided memory is not initialized, and may have been used
+   // by other plugin instances, so the plugin must correctly initialize
+   // the memory when using it.
+   //
+   // The provided memory is owned by the host, so the plugin should not
+   // attempt to free the memory.
+   //
+   // [audio-thread]
+   void*(CLAP_ABI *access)(const clap_host_t *host);
+} clap_host_scratch_memory_t;
+
+#ifdef __cplusplus
+}
+#endif

include/clap/host.h

@@ -35,6 +35,12 @@ typedef struct clap_host {
    void(CLAP_ABI *request_process)(const struct clap_host *host);
 
    // Request the host to schedule a call to plugin->on_main_thread(plugin) on the main thread.
+   // This callback should be called as soon as practicable, usually in the host application's next
+   // available main thread time slice. Typically callbacks occur withink 33ms / 30hz.
+   // Despite this guidance, plugins should not make assumptions about the exactness of timing for
+   // a main thread callback, but hosts should endeavour to be prompt. For example, in high load situations
+   // the environment may starve the gui/main thread in favor of audio processing, leading to substantially
+   // longer latencies for the callback than the indicative times given here.
    // [thread-safe]
    void(CLAP_ABI *request_callback)(const struct clap_host *host);
 } clap_host_t;

include/clap/plugin.h

@@ -61,6 +61,7 @@ typedef struct clap_plugin {
    // In this call the plugin may allocate memory and prepare everything needed for the process
    // call. The process's sample rate will be constant and process's frame count will included in
    // the [min, max] range, which is bounded by [1, INT32_MAX].
+   // In this call the plugin may call host-provided methods marked [being-activated].
    // Once activated the latency and port configuration must remain constant, until deactivation.
    // Returns true on success.
    // [main-thread & !active]

include/clap/version.h

@@ -22,7 +22,7 @@ typedef struct clap_version {
 
 #define CLAP_VERSION_MAJOR 1
 #define CLAP_VERSION_MINOR 2
-#define CLAP_VERSION_REVISION 2
+#define CLAP_VERSION_REVISION 3
 
 #define CLAP_VERSION_INIT                                                                          \
    { (uint32_t)CLAP_VERSION_MAJOR, (uint32_t)CLAP_VERSION_MINOR, (uint32_t)CLAP_VERSION_REVISION }

src/plugin-template.c

@@ -419,7 +419,7 @@ static void entry_deinit_guard(void) {
 #endif
 
    const int cnt = --g_entry_init_counter;
-   assert(cnt > 0);
+   assert(cnt >= 0);
 
    bool succeed = true;
    if (cnt == 0)