← Back to branch summary

~ubuntu-branches/ubuntu/hardy/lmms/hardy

« back to all changes in this revision

Viewing changes to include/ladspa-1.1.h

  • Committer: Bazaar Package Importer
  • Author(s): Tobias Doerffel
  • Date: 2007-09-17 15:00:24 UTC
  • mfrom: (1.1.4 upstream)
  • Revision ID: james.westby@ubuntu.com-20070917150024-mo0zk4ks81jawqii
Tags: 0.3.0-1ubuntu1
https://launchpad.net/bugs/139759
https://launchpad.net/bugs/90806
https://launchpad.net/bugs/102639
https://launchpad.net/bugs/113447
https://launchpad.net/bugs/121172
https://launchpad.net/bugs/124890
* Resynchronized with Debian (LP: #139759, LP: #90806, LP: #102639,
  LP: #113447, LP: #121172, LP: #124890)
* reverted changes from 0.2.1-1.1ubuntu1 as upstream merged/included them

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/ladspa-1.1.h
 
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 */