Audacity  2.2.0
ladspa.h
Go to the documentation of this file.
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 
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 
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 
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. */
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. */
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 
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 */
int LADSPA_PortRangeHintDescriptor
Definition: ladspa.h:200
void * LADSPA_Handle
Definition: ladspa.h:363
void * ImplementationData
Definition: ladspa.h:426
LADSPA_Properties Properties
Definition: ladspa.h:389
const LADSPA_PortRangeHint * PortRangeHints
Definition: ladspa.h:419
int LADSPA_PortDescriptor
Definition: ladspa.h:152
const char * Name
Definition: ladspa.h:393
void(* run_adding)(LADSPA_Handle Instance, unsigned long SampleCount)
Definition: ladspa.h:521
void(* connect_port)(LADSPA_Handle Instance, unsigned long Port, LADSPA_Data *DataLocation)
Definition: ladspa.h:466
struct _LADSPA_PortRangeHint LADSPA_PortRangeHint
unsigned long UniqueID
Definition: ladspa.h:379
const char * Label
Definition: ladspa.h:386
LADSPA_PortRangeHintDescriptor HintDescriptor
Definition: ladspa.h:340
void(* activate)(LADSPA_Handle Instance)
Definition: ladspa.h:489
int LADSPA_Properties
Definition: ladspa.h:94
float LADSPA_Data
Definition: ladspa.h:84
const char *const * PortNames
Definition: ladspa.h:415
void(* cleanup)(LADSPA_Handle Instance)
Definition: ladspa.h:558
_LADSPA_PortRangeHint is a structure that gives parameter validation information for a LADSPA (Linux ...
Definition: ladspa.h:337
unsigned long PortCount
Definition: ladspa.h:406
void(* run)(LADSPA_Handle Instance, unsigned long SampleCount)
Definition: ladspa.h:505
struct _LADSPA_Descriptor LADSPA_Descriptor
_LADSPA_Descriptor is a structure that provides the API to a LADSPA (Linux Audio Plugin Architecture)...
Definition: ladspa.h:373
const char * Maker
Definition: ladspa.h:397
const char * Copyright
Definition: ladspa.h:402
LADSPA_Data LowerBound
Definition: ladspa.h:345
void(* deactivate)(LADSPA_Handle Instance)
Definition: ladspa.h:549
const LADSPA_Descriptor * ladspa_descriptor(unsigned long Index)
LADSPA_Handle(* instantiate)(const struct _LADSPA_Descriptor *Descriptor, unsigned long SampleRate)
Definition: ladspa.h:437
LADSPA_Data UpperBound
Definition: ladspa.h:350
void(* set_run_adding_gain)(LADSPA_Handle Instance, LADSPA_Data Gain)
Definition: ladspa.h:533
const LADSPA_PortDescriptor * PortDescriptors
Definition: ladspa.h:410