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