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