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