90 lines
3.5 KiB
C
90 lines
3.5 KiB
C
|
#pragma once
|
||
|
|
|
||
|
|
#include "../../plugin.h"
|
||
|
|
|
||
|
|
// This extension lets the plugin request "scratch" memory from the host.
|
||
|
|
//
|
||
|
|
// The scratch memory is thread-local, and can be accessed during
|
||
|
|
// `clap_plugin->process()` and `clap_plugin_thread_pool->exec()`;
|
||
|
|
// its content is 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 N plugins
|
||
|
|
// in sequence, and each plugin requires 10K of scratch memory.
|
||
|
|
// If each plugin pre-allocates its own scratch memory, then N * 10K
|
||
|
|
// 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
|
||
|
|
// 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 to reserve scratch memory.
|
||
|
|
//
|
||
|
|
// 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
|
||
|
|
// last call invalidates all previous calls.
|
||
|
|
//
|
||
|
|
// De-activating the plugin releases the scratch memory.
|
||
|
|
//
|
||
|
|
// `max_concurrency_hint` is an optional hint which indicates
|
||
|
|
// the maximum number of threads concurrently accessing the scratch memory.
|
||
|
|
// Set to 0 if unspecified.
|
||
|
|
//
|
||
|
|
// Returns true on success.
|
||
|
|
//
|
||
|
|
// [main-thread & being-activated]
|
||
|
|
bool(CLAP_ABI *reserve)(const clap_host_t *host,
|
||
|
|
uint32_t scratch_size_bytes,
|
||
|
|
uint32_t max_concurrency_hint);
|
||
|
|
|
||
|
|
// Returns a pointer to the "thread-local" scratch memory.
|
||
|
|
//
|
||
|
|
// If the scratch memory wasn't successfully reserved, returns NULL.
|
||
|
|
//
|
||
|
|
// If the plugin crosses `max_concurrency_hint`, then the return value
|
||
|
|
// is either NULL or a valid scratch memory pointer.
|
||
|
|
//
|
||
|
|
// 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 must not
|
||
|
|
// free the memory.
|
||
|
|
//
|
||
|
|
// If the plugin wants to share the same scratch memory pointer with
|
||
|
|
// many threads, it must access the the scratch at the beginning of the
|
||
|
|
// `process()` callback, cache the returned pointer before calling
|
||
|
|
// `clap_host_thread_pool->request_exec()` and clear the cached pointer
|
||
|
|
// before returning from `process()`.
|
||
|
|
//
|
||
|
|
// [audio-thread]
|
||
|
|
void *(CLAP_ABI *access)(const clap_host_t *host);
|
||
|
|
} clap_host_scratch_memory_t;
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|