forked from free-audio/clap
-
Notifications
You must be signed in to change notification settings - Fork 0
/
entry.h
136 lines (128 loc) · 6.32 KB
/
entry.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
#pragma once
#include "version.h"
#include "private/macros.h"
#ifdef __cplusplus
extern "C" {
#endif
// This interface is the entry point of the dynamic library.
//
// CLAP plugins standard search path:
//
// Linux
// - ~/.clap
// - /usr/lib/clap
//
// Windows
// - %COMMONPROGRAMFILES%\CLAP
// - %LOCALAPPDATA%\Programs\Common\CLAP
//
// MacOS
// - /Library/Audio/Plug-Ins/CLAP
// - ~/Library/Audio/Plug-Ins/CLAP
//
// 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`.
//
// init and deinit in most cases are called once, in a matched pair, when the dso is loaded / unloaded.
// In some rare situations it may be called multiple times in a process, so the functions must be defensive,
// mutex locking and counting calls if undertaking non trivial non idempotent actions.
//
// Rationale:
//
// The intent of the init() and deinit() functions is to provide a "normal" initialization patterh
// which occurs when the shared object is loaded or unloaded. As such, hosts will call each once and
// in matched pairs. In CLAP specifications prior to 1.2.0, this single-call was documented as a
// requirement.
//
// We realized, though, that this is not a requirement hosts can meet. If hosts load a plugin
// which itself wraps another CLAP for instance, while also loading that same clap in its memory
// space, both the host and the wrapper will call init() and deinit() and have no means to communicate
// the state.
//
// With CLAP 1.2.0 and beyond we are changing the spec to indicate that a host should make an
// absolute best effort to call init() and deinit() once, and always in matched pairs (for every
// init() which returns true, one deinit() should be called).
//
// This takes the de-facto burden on plugin writers to deal with multiple calls into a hard requirement.
//
// Most init() / deinit() pairs we have seen are the relatively trivial {return true;} and {}. But
// if your init() function does non-trivial one time work, the plugin author must maintain a counter
// and must manage a mutex lock. The most obvious implementation will maintain a static counter and a
// global mutex, increment the counter on each init, decrement it on each deinit, and only undertake
// the init or deinit action when the counter is zero.
typedef struct clap_plugin_entry {
clap_version_t clap_version; // initialized to CLAP_VERSION
// Initializes the DSO.
//
// This function must be called first, before any-other CLAP-related function or symbol from this
// DSO.
//
// It also must only be called once, until a later call to deinit() is made, after which init()
// can be called once more to re-initialize the DSO.
// This enables hosts to e.g. quickly load and unload a DSO for scanning its plugins, and then
// load it again later to actually use the plugins if needed.
//
// As stated above, even though hosts are forbidden to do so directly, multiple calls before any
// deinit() call may still happen. Implementations *should* take this into account, and *must*
// do so as of CLAP 1.2.0.
//
// 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 interfaces in this call.
// It is forbidden to perform any user interaction in this call.
//
// If the initialization depends upon expensive computation, maybe try to do them ahead of time
// and cache the result.
//
// Returns true on success. If init() returns false, then the DSO must be considered
// uninitialized, and the host must not call deinit() nor any other CLAP-related symbols from the
// DSO.
// This function also returns true in the case where the DSO is already initialized, and no
// actual initialization work is done in this call, as explain above.
//
// plugin_path is the path to the DSO (Linux, Windows), or the bundle (macOS).
//
// This function may be called on any thread, including a different one from the one a later call
// to deinit() (or a later init()) can be made.
// However, it is forbidden to call this function simultaneously from multiple threads.
// It is also forbidden to call it simultaneously with *any* other CLAP-related symbols from the
// DSO, including (but not limited to) deinit().
bool(CLAP_ABI *init)(const char *plugin_path);
// De-initializes the DSO, freeing any resources allocated or initialized by init().
//
// After this function is called, no more calls into the DSO must be made, except calling init()
// again to re-initialize the DSO.
// This means that after deinit() is called, the DSO can be considered to be in the same state
// as if init() was never called at all yet, enabling it to be re-initialized as needed.
//
// As stated above, even though hosts are forbidden to do so directly, multiple calls before any
// new init() call may still happen. Implementations *should* take this into account, and *must*
// do so as of CLAP 1.2.0.
//
// Just like init(), this function may be called on any thread, including a different one from
// the one init() was called from, or from the one a later init() call can be made.
// However, it is forbidden to call this function simultaneously from multiple threads.
// It is also forbidden to call it simultaneously with *any* other CLAP-related symbols from the
// DSO, including (but not limited to) deinit().
void(CLAP_ABI *deinit)(void);
// Get the pointer to a factory. See factory/plugin-factory.h for an example.
//
// Returns null if the factory is not provided.
// The returned pointer must *not* be freed by the caller.
//
// Unlike init() and deinit(), this function can be called simultaneously by multiple threads.
//
// [thread-safe]
const void *(CLAP_ABI *get_factory)(const char *factory_id);
} clap_plugin_entry_t;
/* Entry point */
CLAP_EXPORT extern const clap_plugin_entry_t clap_entry;
#ifdef __cplusplus
}
#endif