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