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