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