-
Notifications
You must be signed in to change notification settings - Fork 103
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
1 parent
bcbf761
commit dbf7513
Showing
2 changed files
with
92 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters