1 |
/* ladspa.h |
2 |
|
3 |
Linux Audio Developer's Simple Plugin API Version 1.1[LGPL]. |
4 |
Copyright (C) 2000-2002 Richard W.E. Furse, Paul Barton-Davis, |
5 |
Stefan Westerfeld. |
6 |
|
7 |
This library is free software; you can redistribute it and/or |
8 |
modify it under the terms of the GNU Lesser General Public License |
9 |
as published by the Free Software Foundation; either version 2.1 of |
10 |
the License, or (at your option) any later version. |
11 |
|
12 |
This library is distributed in the hope that it will be useful, but |
13 |
WITHOUT ANY WARRANTY; without even the implied warranty of |
14 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 |
Lesser General Public License for more details. |
16 |
|
17 |
You should have received a copy of the GNU Lesser General Public |
18 |
License along with this library; if not, write to the Free Software |
19 |
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 |
20 |
USA. */ |
21 |
|
22 |
#ifndef LADSPA_INCLUDED |
23 |
#define LADSPA_INCLUDED |
24 |
|
25 |
#define LADSPA_VERSION "1.1" |
26 |
#define LADSPA_VERSION_MAJOR 1 |
27 |
#define LADSPA_VERSION_MINOR 1 |
28 |
|
29 |
#ifdef __cplusplus |
30 |
extern "C" { |
31 |
#endif |
32 |
|
33 |
/*****************************************************************************/ |
34 |
|
35 |
/* Overview: |
36 |
|
37 |
There is a large number of synthesis packages in use or development |
38 |
on the Linux platform at this time. This API (`The Linux Audio |
39 |
Developer's Simple Plugin API') attempts to give programmers the |
40 |
ability to write simple `plugin' audio processors in C/C++ and link |
41 |
them dynamically (`plug') into a range of these packages (`hosts'). |
42 |
It should be possible for any host and any plugin to communicate |
43 |
completely through this interface. |
44 |
|
45 |
This API is deliberately short and simple. To achieve compatibility |
46 |
with a range of promising Linux sound synthesis packages it |
47 |
attempts to find the `greatest common divisor' in their logical |
48 |
behaviour. Having said this, certain limiting decisions are |
49 |
implicit, notably the use of a fixed type (LADSPA_Data) for all |
50 |
data transfer and absence of a parameterised `initialisation' |
51 |
phase. See below for the LADSPA_Data typedef. |
52 |
|
53 |
Plugins are expected to distinguish between control and audio |
54 |
data. Plugins have `ports' that are inputs or outputs for audio or |
55 |
control data and each plugin is `run' for a `block' corresponding |
56 |
to a short time interval measured in samples. Audio data is |
57 |
communicated using arrays of LADSPA_Data, allowing a block of audio |
58 |
to be processed by the plugin in a single pass. Control data is |
59 |
communicated using single LADSPA_Data values. Control data has a |
60 |
single value at the start of a call to the `run()' or `run_adding()' |
61 |
function, and may be considered to remain this value for its |
62 |
duration. The plugin may assume that all its input and output ports |
63 |
have been connected to the relevant data location (see the |
64 |
`connect_port()' function below) before it is asked to run. |
65 |
|
66 |
Plugins will reside in shared object files suitable for dynamic |
67 |
linking by dlopen() and family. The file will provide a number of |
68 |
`plugin types' that can be used to instantiate actual plugins |
69 |
(sometimes known as `plugin instances') that can be connected |
70 |
together to perform tasks. |
71 |
|
72 |
This API contains very limited error-handling. */ |
73 |
|
74 |
/*****************************************************************************/ |
75 |
|
76 |
/* Fundamental data type passed in and out of plugin. This data type |
77 |
is used to communicate audio samples and control values. It is |
78 |
assumed that the plugin will work sensibly given any numeric input |
79 |
value although it may have a preferred range (see hints below). |
80 |
|
81 |
For audio it is generally assumed that 1.0f is the `0dB' reference |
82 |
amplitude and is a `normal' signal level. */ |
83 |
|
84 |
typedef float LADSPA_Data; |
85 |
|
86 |
/*****************************************************************************/ |
87 |
|
88 |
/* Special Plugin Properties: |
89 |
|
90 |
Optional features of the plugin type are encapsulated in the |
91 |
LADSPA_Properties type. This is assembled by ORing individual |
92 |
properties together. */ |
93 |
|
94 |
typedef int LADSPA_Properties; |
95 |
|
96 |
/* Property LADSPA_PROPERTY_REALTIME indicates that the plugin has a |
97 |
real-time dependency (e.g. listens to a MIDI device) and so its |
98 |
output must not be cached or subject to significant latency. */ |
99 |
#define LADSPA_PROPERTY_REALTIME 0x1 |
100 |
|
101 |
/* Property LADSPA_PROPERTY_INPLACE_BROKEN indicates that the plugin |
102 |
may cease to work correctly if the host elects to use the same data |
103 |
location for both input and output (see connect_port()). This |
104 |
should be avoided as enabling this flag makes it impossible for |
105 |
hosts to use the plugin to process audio `in-place.' */ |
106 |
#define LADSPA_PROPERTY_INPLACE_BROKEN 0x2 |
107 |
|
108 |
/* Property LADSPA_PROPERTY_HARD_RT_CAPABLE indicates that the plugin |
109 |
is capable of running not only in a conventional host but also in a |
110 |
`hard real-time' environment. To qualify for this the plugin must |
111 |
satisfy all of the following: |
112 |
|
113 |
(1) The plugin must not use malloc(), free() or other heap memory |
114 |
management within its run() or run_adding() functions. All new |
115 |
memory used in run() must be managed via the stack. These |
116 |
restrictions only apply to the run() function. |
117 |
|
118 |
(2) The plugin will not attempt to make use of any library |
119 |
functions with the exceptions of functions in the ANSI standard C |
120 |
and C maths libraries, which the host is expected to provide. |
121 |
|
122 |
(3) The plugin will not access files, devices, pipes, sockets, IPC |
123 |
or any other mechanism that might result in process or thread |
124 |
blocking. |
125 |
|
126 |
(4) The plugin will take an amount of time to execute a run() or |
127 |
run_adding() call approximately of form (A+B*SampleCount) where A |
128 |
and B depend on the machine and host in use. This amount of time |
129 |
may not depend on input signals or plugin state. The host is left |
130 |
the responsibility to perform timings to estimate upper bounds for |
131 |
A and B. */ |
132 |
#define LADSPA_PROPERTY_HARD_RT_CAPABLE 0x4 |
133 |
|
134 |
#define LADSPA_IS_REALTIME(x) ((x) & LADSPA_PROPERTY_REALTIME) |
135 |
#define LADSPA_IS_INPLACE_BROKEN(x) ((x) & LADSPA_PROPERTY_INPLACE_BROKEN) |
136 |
#define LADSPA_IS_HARD_RT_CAPABLE(x) ((x) & LADSPA_PROPERTY_HARD_RT_CAPABLE) |
137 |
|
138 |
/*****************************************************************************/ |
139 |
|
140 |
/* Plugin Ports: |
141 |
|
142 |
Plugins have `ports' that are inputs or outputs for audio or |
143 |
data. Ports can communicate arrays of LADSPA_Data (for audio |
144 |
inputs/outputs) or single LADSPA_Data values (for control |
145 |
input/outputs). This information is encapsulated in the |
146 |
LADSPA_PortDescriptor type which is assembled by ORing individual |
147 |
properties together. |
148 |
|
149 |
Note that a port must be an input or an output port but not both |
150 |
and that a port must be a control or audio port but not both. */ |
151 |
|
152 |
typedef int LADSPA_PortDescriptor; |
153 |
|
154 |
/* Property LADSPA_PORT_INPUT indicates that the port is an input. */ |
155 |
#define LADSPA_PORT_INPUT 0x1 |
156 |
|
157 |
/* Property LADSPA_PORT_OUTPUT indicates that the port is an output. */ |
158 |
#define LADSPA_PORT_OUTPUT 0x2 |
159 |
|
160 |
/* Property LADSPA_PORT_CONTROL indicates that the port is a control |
161 |
port. */ |
162 |
#define LADSPA_PORT_CONTROL 0x4 |
163 |
|
164 |
/* Property LADSPA_PORT_AUDIO indicates that the port is a audio |
165 |
port. */ |
166 |
#define LADSPA_PORT_AUDIO 0x8 |
167 |
|
168 |
#define LADSPA_IS_PORT_INPUT(x) ((x) & LADSPA_PORT_INPUT) |
169 |
#define LADSPA_IS_PORT_OUTPUT(x) ((x) & LADSPA_PORT_OUTPUT) |
170 |
#define LADSPA_IS_PORT_CONTROL(x) ((x) & LADSPA_PORT_CONTROL) |
171 |
#define LADSPA_IS_PORT_AUDIO(x) ((x) & LADSPA_PORT_AUDIO) |
172 |
|
173 |
/*****************************************************************************/ |
174 |
|
175 |
/* Plugin Port Range Hints: |
176 |
|
177 |
The host may wish to provide a representation of data entering or |
178 |
leaving a plugin (e.g. to generate a GUI automatically). To make |
179 |
this more meaningful, the plugin should provide `hints' to the host |
180 |
describing the usual values taken by the data. |
181 |
|
182 |
Note that these are only hints. The host may ignore them and the |
183 |
plugin must not assume that data supplied to it is meaningful. If |
184 |
the plugin receives invalid input data it is expected to continue |
185 |
to run without failure and, where possible, produce a sensible |
186 |
output (e.g. a high-pass filter given a negative cutoff frequency |
187 |
might switch to an all-pass mode). |
188 |
|
189 |
Hints are meaningful for all input and output ports but hints for |
190 |
input control ports are expected to be particularly useful. |
191 |
|
192 |
More hint information is encapsulated in the |
193 |
LADSPA_PortRangeHintDescriptor type which is assembled by ORing |
194 |
individual hint types together. Hints may require further |
195 |
LowerBound and UpperBound information. |
196 |
|
197 |
All the hint information for a particular port is aggregated in the |
198 |
LADSPA_PortRangeHint structure. */ |
199 |
|
200 |
typedef int LADSPA_PortRangeHintDescriptor; |
201 |
|
202 |
/* Hint LADSPA_HINT_BOUNDED_BELOW indicates that the LowerBound field |
203 |
of the LADSPA_PortRangeHint should be considered meaningful. The |
204 |
value in this field should be considered the (inclusive) lower |
205 |
bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also |
206 |
specified then the value of LowerBound should be multiplied by the |
207 |
sample rate. */ |
208 |
#define LADSPA_HINT_BOUNDED_BELOW 0x1 |
209 |
|
210 |
/* Hint LADSPA_HINT_BOUNDED_ABOVE indicates that the UpperBound field |
211 |
of the LADSPA_PortRangeHint should be considered meaningful. The |
212 |
value in this field should be considered the (inclusive) upper |
213 |
bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also |
214 |
specified then the value of UpperBound should be multiplied by the |
215 |
sample rate. */ |
216 |
#define LADSPA_HINT_BOUNDED_ABOVE 0x2 |
217 |
|
218 |
/* Hint LADSPA_HINT_TOGGLED indicates that the data item should be |
219 |
considered a Boolean toggle. Data less than or equal to zero should |
220 |
be considered `off' or `false,' and data above zero should be |
221 |
considered `on' or `true.' LADSPA_HINT_TOGGLED may not be used in |
222 |
conjunction with any other hint except LADSPA_HINT_DEFAULT_0 or |
223 |
LADSPA_HINT_DEFAULT_1. */ |
224 |
#define LADSPA_HINT_TOGGLED 0x4 |
225 |
|
226 |
/* Hint LADSPA_HINT_SAMPLE_RATE indicates that any bounds specified |
227 |
should be interpreted as multiples of the sample rate. For |
228 |
instance, a frequency range from 0Hz to the Nyquist frequency (half |
229 |
the sample rate) could be requested by this hint in conjunction |
230 |
with LowerBound = 0 and UpperBound = 0.5. Hosts that support bounds |
231 |
at all must support this hint to retain meaning. */ |
232 |
#define LADSPA_HINT_SAMPLE_RATE 0x8 |
233 |
|
234 |
/* Hint LADSPA_HINT_LOGARITHMIC indicates that it is likely that the |
235 |
user will find it more intuitive to view values using a logarithmic |
236 |
scale. This is particularly useful for frequencies and gains. */ |
237 |
#define LADSPA_HINT_LOGARITHMIC 0x10 |
238 |
|
239 |
/* Hint LADSPA_HINT_INTEGER indicates that a user interface would |
240 |
probably wish to provide a stepped control taking only integer |
241 |
values. Any bounds set should be slightly wider than the actual |
242 |
integer range required to avoid floating point rounding errors. For |
243 |
instance, the integer set {0,1,2,3} might be described as [-0.1, |
244 |
3.1]. */ |
245 |
#define LADSPA_HINT_INTEGER 0x20 |
246 |
|
247 |
/* The various LADSPA_HINT_HAS_DEFAULT_* hints indicate a `normal' |
248 |
value for the port that is sensible as a default. For instance, |
249 |
this value is suitable for use as an initial value in a user |
250 |
interface or as a value the host might assign to a control port |
251 |
when the user has not provided one. Defaults are encoded using a |
252 |
mask so only one default may be specified for a port. Some of the |
253 |
hints make use of lower and upper bounds, in which case the |
254 |
relevant bound or bounds must be available and |
255 |
LADSPA_HINT_SAMPLE_RATE must be applied as usual. The resulting |
256 |
default must be rounded if LADSPA_HINT_INTEGER is present. Default |
257 |
values were introduced in LADSPA v1.1. */ |
258 |
#define LADSPA_HINT_DEFAULT_MASK 0x3C0 |
259 |
|
260 |
/* This default values indicates that no default is provided. */ |
261 |
#define LADSPA_HINT_DEFAULT_NONE 0x0 |
262 |
|
263 |
/* This default hint indicates that the suggested lower bound for the |
264 |
port should be used. */ |
265 |
#define LADSPA_HINT_DEFAULT_MINIMUM 0x40 |
266 |
|
267 |
/* This default hint indicates that a low value between the suggested |
268 |
lower and upper bounds should be chosen. For ports with |
269 |
LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.75 + |
270 |
log(upper) * 0.25). Otherwise, this should be (lower * 0.75 + upper |
271 |
* 0.25). */ |
272 |
#define LADSPA_HINT_DEFAULT_LOW 0x80 |
273 |
|
274 |
/* This default hint indicates that a middle value between the |
275 |
suggested lower and upper bounds should be chosen. For ports with |
276 |
LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.5 + |
277 |
log(upper) * 0.5). Otherwise, this should be (lower * 0.5 + upper * |
278 |
0.5). */ |
279 |
#define LADSPA_HINT_DEFAULT_MIDDLE 0xC0 |
280 |
|
281 |
/* This default hint indicates that a high value between the suggested |
282 |
lower and upper bounds should be chosen. For ports with |
283 |
LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.25 + |
284 |
log(upper) * 0.75). Otherwise, this should be (lower * 0.25 + upper |
285 |
* 0.75). */ |
286 |
#define LADSPA_HINT_DEFAULT_HIGH 0x100 |
287 |
|
288 |
/* This default hint indicates that the suggested upper bound for the |
289 |
port should be used. */ |
290 |
#define LADSPA_HINT_DEFAULT_MAXIMUM 0x140 |
291 |
|
292 |
/* This default hint indicates that the number 0 should be used. Note |
293 |
that this default may be used in conjunction with |
294 |
LADSPA_HINT_TOGGLED. */ |
295 |
#define LADSPA_HINT_DEFAULT_0 0x200 |
296 |
|
297 |
/* This default hint indicates that the number 1 should be used. Note |
298 |
that this default may be used in conjunction with |
299 |
LADSPA_HINT_TOGGLED. */ |
300 |
#define LADSPA_HINT_DEFAULT_1 0x240 |
301 |
|
302 |
/* This default hint indicates that the number 100 should be used. */ |
303 |
#define LADSPA_HINT_DEFAULT_100 0x280 |
304 |
|
305 |
/* This default hint indicates that the Hz frequency of `concert A' |
306 |
should be used. This will be 440 unless the host uses an unusual |
307 |
tuning convention, in which case it may be within a few Hz. */ |
308 |
#define LADSPA_HINT_DEFAULT_440 0x2C0 |
309 |
|
310 |
#define LADSPA_IS_HINT_BOUNDED_BELOW(x) ((x) & LADSPA_HINT_BOUNDED_BELOW) |
311 |
#define LADSPA_IS_HINT_BOUNDED_ABOVE(x) ((x) & LADSPA_HINT_BOUNDED_ABOVE) |
312 |
#define LADSPA_IS_HINT_TOGGLED(x) ((x) & LADSPA_HINT_TOGGLED) |
313 |
#define LADSPA_IS_HINT_SAMPLE_RATE(x) ((x) & LADSPA_HINT_SAMPLE_RATE) |
314 |
#define LADSPA_IS_HINT_LOGARITHMIC(x) ((x) & LADSPA_HINT_LOGARITHMIC) |
315 |
#define LADSPA_IS_HINT_INTEGER(x) ((x) & LADSPA_HINT_INTEGER) |
316 |
|
317 |
#define LADSPA_IS_HINT_HAS_DEFAULT(x) ((x) & LADSPA_HINT_DEFAULT_MASK) |
318 |
#define LADSPA_IS_HINT_DEFAULT_MINIMUM(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ |
319 |
== LADSPA_HINT_DEFAULT_MINIMUM) |
320 |
#define LADSPA_IS_HINT_DEFAULT_LOW(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ |
321 |
== LADSPA_HINT_DEFAULT_LOW) |
322 |
#define LADSPA_IS_HINT_DEFAULT_MIDDLE(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ |
323 |
== LADSPA_HINT_DEFAULT_MIDDLE) |
324 |
#define LADSPA_IS_HINT_DEFAULT_HIGH(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ |
325 |
== LADSPA_HINT_DEFAULT_HIGH) |
326 |
#define LADSPA_IS_HINT_DEFAULT_MAXIMUM(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ |
327 |
== LADSPA_HINT_DEFAULT_MAXIMUM) |
328 |
#define LADSPA_IS_HINT_DEFAULT_0(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ |
329 |
== LADSPA_HINT_DEFAULT_0) |
330 |
#define LADSPA_IS_HINT_DEFAULT_1(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ |
331 |
== LADSPA_HINT_DEFAULT_1) |
332 |
#define LADSPA_IS_HINT_DEFAULT_100(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ |
333 |
== LADSPA_HINT_DEFAULT_100) |
334 |
#define LADSPA_IS_HINT_DEFAULT_440(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ |
335 |
== LADSPA_HINT_DEFAULT_440) |
336 |
|
337 |
typedef struct _LADSPA_PortRangeHint { |
338 |
|
339 |
/* Hints about the port. */ |
340 |
LADSPA_PortRangeHintDescriptor HintDescriptor; |
341 |
|
342 |
/* Meaningful when hint LADSPA_HINT_BOUNDED_BELOW is active. When |
343 |
LADSPA_HINT_SAMPLE_RATE is also active then this value should be |
344 |
multiplied by the relevant sample rate. */ |
345 |
LADSPA_Data LowerBound; |
346 |
|
347 |
/* Meaningful when hint LADSPA_HINT_BOUNDED_ABOVE is active. When |
348 |
LADSPA_HINT_SAMPLE_RATE is also active then this value should be |
349 |
multiplied by the relevant sample rate. */ |
350 |
LADSPA_Data UpperBound; |
351 |
|
352 |
} LADSPA_PortRangeHint; |
353 |
|
354 |
/*****************************************************************************/ |
355 |
|
356 |
/* Plugin Handles: |
357 |
|
358 |
This plugin handle indicates a particular instance of the plugin |
359 |
concerned. It is valid to compare this to NULL (0 for C++) but |
360 |
otherwise the host should not attempt to interpret it. The plugin |
361 |
may use it to reference internal instance data. */ |
362 |
|
363 |
typedef void * LADSPA_Handle; |
364 |
|
365 |
/*****************************************************************************/ |
366 |
|
367 |
/* Descriptor for a Type of Plugin: |
368 |
|
369 |
This structure is used to describe a plugin type. It provides a |
370 |
number of functions to examine the type, instantiate it, link it to |
371 |
buffers and workspaces and to run it. */ |
372 |
|
373 |
typedef struct _LADSPA_Descriptor { |
374 |
|
375 |
/* This numeric identifier indicates the plugin type |
376 |
uniquely. Plugin programmers may reserve ranges of IDs from a |
377 |
central body to avoid clashes. Hosts may assume that IDs are |
378 |
below 0x1000000. */ |
379 |
unsigned long UniqueID; |
380 |
|
381 |
/* This identifier can be used as a unique, case-sensitive |
382 |
identifier for the plugin type within the plugin file. Plugin |
383 |
types should be identified by file and label rather than by index |
384 |
or plugin name, which may be changed in new plugin |
385 |
versions. Labels must not contain white-space characters. */ |
386 |
const char * Label; |
387 |
|
388 |
/* This indicates a number of properties of the plugin. */ |
389 |
LADSPA_Properties Properties; |
390 |
|
391 |
/* This member points to the null-terminated name of the plugin |
392 |
(e.g. "Sine Oscillator"). */ |
393 |
const char * Name; |
394 |
|
395 |
/* This member points to the null-terminated string indicating the |
396 |
maker of the plugin. This can be an empty string but not NULL. */ |
397 |
const char * Maker; |
398 |
|
399 |
/* This member points to the null-terminated string indicating any |
400 |
copyright applying to the plugin. If no Copyright applies the |
401 |
string "None" should be used. */ |
402 |
const char * Copyright; |
403 |
|
404 |
/* This indicates the number of ports (input AND output) present on |
405 |
the plugin. */ |
406 |
unsigned long PortCount; |
407 |
|
408 |
/* This member indicates an array of port descriptors. Valid indices |
409 |
vary from 0 to PortCount-1. */ |
410 |
const LADSPA_PortDescriptor * PortDescriptors; |
411 |
|
412 |
/* This member indicates an array of null-terminated strings |
413 |
describing ports (e.g. "Frequency (Hz)"). Valid indices vary from |
414 |
0 to PortCount-1. */ |
415 |
const char * const * PortNames; |
416 |
|
417 |
/* This member indicates an array of range hints for each port (see |
418 |
above). Valid indices vary from 0 to PortCount-1. */ |
419 |
const LADSPA_PortRangeHint * PortRangeHints; |
420 |
|
421 |
/* This may be used by the plugin developer to pass any custom |
422 |
implementation data into an instantiate call. It must not be used |
423 |
or interpreted by the host. It is expected that most plugin |
424 |
writers will not use this facility as LADSPA_Handle should be |
425 |
used to hold instance data. */ |
426 |
void * ImplementationData; |
427 |
|
428 |
/* This member is a function pointer that instantiates a plugin. A |
429 |
handle is returned indicating the new plugin instance. The |
430 |
instantiation function accepts a sample rate as a parameter. The |
431 |
plugin descriptor from which this instantiate function was found |
432 |
must also be passed. This function must return NULL if |
433 |
instantiation fails. |
434 |
|
435 |
Note that instance initialisation should generally occur in |
436 |
activate() rather than here. */ |
437 |
LADSPA_Handle (*instantiate)(const struct _LADSPA_Descriptor * Descriptor, |
438 |
unsigned long SampleRate); |
439 |
|
440 |
/* This member is a function pointer that connects a port on an |
441 |
instantiated plugin to a memory location at which a block of data |
442 |
for the port will be read/written. The data location is expected |
443 |
to be an array of LADSPA_Data for audio ports or a single |
444 |
LADSPA_Data value for control ports. Memory issues will be |
445 |
managed by the host. The plugin must read/write the data at these |
446 |
locations every time run() or run_adding() is called and the data |
447 |
present at the time of this connection call should not be |
448 |
considered meaningful. |
449 |
|
450 |
connect_port() may be called more than once for a plugin instance |
451 |
to allow the host to change the buffers that the plugin is |
452 |
reading or writing. These calls may be made before or after |
453 |
activate() or deactivate() calls. |
454 |
|
455 |
connect_port() must be called at least once for each port before |
456 |
run() or run_adding() is called. When working with blocks of |
457 |
LADSPA_Data the plugin should pay careful attention to the block |
458 |
size passed to the run function as the block allocated may only |
459 |
just be large enough to contain the block of samples. |
460 |
|
461 |
Plugin writers should be aware that the host may elect to use the |
462 |
same buffer for more than one port and even use the same buffer |
463 |
for both input and output (see LADSPA_PROPERTY_INPLACE_BROKEN). |
464 |
However, overlapped buffers or use of a single buffer for both |
465 |
audio and control data may result in unexpected behaviour. */ |
466 |
void (*connect_port)(LADSPA_Handle Instance, |
467 |
unsigned long Port, |
468 |
LADSPA_Data * DataLocation); |
469 |
|
470 |
/* This member is a function pointer that initialises a plugin |
471 |
instance and activates it for use. This is separated from |
472 |
instantiate() to aid real-time support and so that hosts can |
473 |
reinitialise a plugin instance by calling deactivate() and then |
474 |
activate(). In this case the plugin instance must reset all state |
475 |
information dependent on the history of the plugin instance |
476 |
except for any data locations provided by connect_port() and any |
477 |
gain set by set_run_adding_gain(). If there is nothing for |
478 |
activate() to do then the plugin writer may provide a NULL rather |
479 |
than an empty function. |
480 |
|
481 |
When present, hosts must call this function once before run() (or |
482 |
run_adding()) is called for the first time. This call should be |
483 |
made as close to the run() call as possible and indicates to |
484 |
real-time plugins that they are now live. Plugins should not rely |
485 |
on a prompt call to run() after activate(). activate() may not be |
486 |
called again unless deactivate() is called first. Note that |
487 |
connect_port() may be called before or after a call to |
488 |
activate(). */ |
489 |
void (*activate)(LADSPA_Handle Instance); |
490 |
|
491 |
/* This method is a function pointer that runs an instance of a |
492 |
plugin for a block. Two parameters are required: the first is a |
493 |
handle to the particular instance to be run and the second |
494 |
indicates the block size (in samples) for which the plugin |
495 |
instance may run. |
496 |
|
497 |
Note that if an activate() function exists then it must be called |
498 |
before run() or run_adding(). If deactivate() is called for a |
499 |
plugin instance then the plugin instance may not be reused until |
500 |
activate() has been called again. |
501 |
|
502 |
If the plugin has the property LADSPA_PROPERTY_HARD_RT_CAPABLE |
503 |
then there are various things that the plugin should not do |
504 |
within the run() or run_adding() functions (see above). */ |
505 |
void (*run)(LADSPA_Handle Instance, |
506 |
unsigned long SampleCount); |
507 |
|
508 |
/* This method is a function pointer that runs an instance of a |
509 |
plugin for a block. This has identical behaviour to run() except |
510 |
in the way data is output from the plugin. When run() is used, |
511 |
values are written directly to the memory areas associated with |
512 |
the output ports. However when run_adding() is called, values |
513 |
must be added to the values already present in the memory |
514 |
areas. Furthermore, output values written must be scaled by the |
515 |
current gain set by set_run_adding_gain() (see below) before |
516 |
addition. |
517 |
|
518 |
run_adding() is optional. When it is not provided by a plugin, |
519 |
this function pointer must be set to NULL. When it is provided, |
520 |
the function set_run_adding_gain() must be provided also. */ |
521 |
void (*run_adding)(LADSPA_Handle Instance, |
522 |
unsigned long SampleCount); |
523 |
|
524 |
/* This method is a function pointer that sets the output gain for |
525 |
use when run_adding() is called (see above). If this function is |
526 |
never called the gain is assumed to default to 1. Gain |
527 |
information should be retained when activate() or deactivate() |
528 |
are called. |
529 |
|
530 |
This function should be provided by the plugin if and only if the |
531 |
run_adding() function is provided. When it is absent this |
532 |
function pointer must be set to NULL. */ |
533 |
void (*set_run_adding_gain)(LADSPA_Handle Instance, |
534 |
LADSPA_Data Gain); |
535 |
|
536 |
/* This is the counterpart to activate() (see above). If there is |
537 |
nothing for deactivate() to do then the plugin writer may provide |
538 |
a NULL rather than an empty function. |
539 |
|
540 |
Hosts must deactivate all activated units after they have been |
541 |
run() (or run_adding()) for the last time. This call should be |
542 |
made as close to the last run() call as possible and indicates to |
543 |
real-time plugins that they are no longer live. Plugins should |
544 |
not rely on prompt deactivation. Note that connect_port() may be |
545 |
called before or after a call to deactivate(). |
546 |
|
547 |
Deactivation is not similar to pausing as the plugin instance |
548 |
will be reinitialised when activate() is called to reuse it. */ |
549 |
void (*deactivate)(LADSPA_Handle Instance); |
550 |
|
551 |
/* Once an instance of a plugin has been finished with it can be |
552 |
deleted using the following function. The instance handle passed |
553 |
ceases to be valid after this call. |
554 |
|
555 |
If activate() was called for a plugin instance then a |
556 |
corresponding call to deactivate() must be made before cleanup() |
557 |
is called. */ |
558 |
void (*cleanup)(LADSPA_Handle Instance); |
559 |
|
560 |
} LADSPA_Descriptor; |
561 |
|
562 |
/**********************************************************************/ |
563 |
|
564 |
/* Accessing a Plugin: */ |
565 |
|
566 |
/* The exact mechanism by which plugins are loaded is host-dependent, |
567 |
however all most hosts will need to know is the name of shared |
568 |
object file containing the plugin types. To allow multiple hosts to |
569 |
share plugin types, hosts may wish to check for environment |
570 |
variable LADSPA_PATH. If present, this should contain a |
571 |
colon-separated path indicating directories that should be searched |
572 |
(in order) when loading plugin types. |
573 |
|
574 |
A plugin programmer must include a function called |
575 |
"ladspa_descriptor" with the following function prototype within |
576 |
the shared object file. This function will have C-style linkage (if |
577 |
you are using C++ this is taken care of by the `extern "C"' clause |
578 |
at the top of the file). |
579 |
|
580 |
A host will find the plugin shared object file by one means or |
581 |
another, find the ladspa_descriptor() function, call it, and |
582 |
proceed from there. |
583 |
|
584 |
Plugin types are accessed by index (not ID) using values from 0 |
585 |
upwards. Out of range indexes must result in this function |
586 |
returning NULL, so the plugin count can be determined by checking |
587 |
for the least index that results in NULL being returned. */ |
588 |
|
589 |
const LADSPA_Descriptor * ladspa_descriptor(unsigned long Index); |
590 |
|
591 |
/* Datatype corresponding to the ladspa_descriptor() function. */ |
592 |
typedef const LADSPA_Descriptor * |
593 |
(*LADSPA_Descriptor_Function)(unsigned long Index); |
594 |
|
595 |
/**********************************************************************/ |
596 |
|
597 |
#ifdef __cplusplus |
598 |
} |
599 |
#endif |
600 |
|
601 |
#endif /* LADSPA_INCLUDED */ |
602 |
|
603 |
/* EOF */ |