BEAST/BSE - Better Audio System and Sound Engine
0.8.2
|
00001 // Licensed GNU LGPL v2.1 or later: http://www.gnu.org/licenses/lgpl.html 00002 00003 #ifndef LADSPA_INCLUDED 00004 #define LADSPA_INCLUDED 00005 00006 #define LADSPA_VERSION "1.1" 00007 #define LADSPA_VERSION_MAJOR 1 00008 #define LADSPA_VERSION_MINOR 1 00009 00010 #ifdef __cplusplus 00011 extern "C" { 00012 #endif 00013 00014 /*****************************************************************************/ 00015 00016 /* Overview: 00017 00018 There is a large number of synthesis packages in use or development 00019 on the Linux platform at this time. This API (`The Linux Audio 00020 Developer's Simple Plugin API') attempts to give programmers the 00021 ability to write simple `plugin' audio processors in C/C++ and link 00022 them dynamically (`plug') into a range of these packages (`hosts'). 00023 It should be possible for any host and any plugin to communicate 00024 completely through this interface. 00025 00026 This API is deliberately short and simple. To achieve compatibility 00027 with a range of promising Linux sound synthesis packages it 00028 attempts to find the `greatest common divisor' in their logical 00029 behaviour. Having said this, certain limiting decisions are 00030 implicit, notably the use of a fixed type (LADSPA_Data) for all 00031 data transfer and absence of a parameterised `initialisation' 00032 phase. See below for the LADSPA_Data typedef. 00033 00034 Plugins are expected to distinguish between control and audio 00035 data. Plugins have `ports' that are inputs or outputs for audio or 00036 control data and each plugin is `run' for a `block' corresponding 00037 to a short time interval measured in samples. Audio data is 00038 communicated using arrays of LADSPA_Data, allowing a block of audio 00039 to be processed by the plugin in a single pass. Control data is 00040 communicated using single LADSPA_Data values. Control data has a 00041 single value at the start of a call to the `run()' or `run_adding()' 00042 function, and may be considered to remain this value for its 00043 duration. The plugin may assume that all its input and output ports 00044 have been connected to the relevant data location (see the 00045 `connect_port()' function below) before it is asked to run. 00046 00047 Plugins will reside in shared object files suitable for dynamic 00048 linking by dlopen() and family. The file will provide a number of 00049 `plugin types' that can be used to instantiate actual plugins 00050 (sometimes known as `plugin instances') that can be connected 00051 together to perform tasks. 00052 00053 This API contains very limited error-handling. */ 00054 00055 /*****************************************************************************/ 00056 00057 /* Fundamental data type passed in and out of plugin. This data type 00058 is used to communicate audio samples and control values. It is 00059 assumed that the plugin will work sensibly given any numeric input 00060 value although it may have a preferred range (see hints below). 00061 00062 For audio it is generally assumed that 1.0f is the `0dB' reference 00063 amplitude and is a `normal' signal level. */ 00064 00065 typedef float LADSPA_Data; 00066 00067 /*****************************************************************************/ 00068 00069 /* Special Plugin Properties: 00070 00071 Optional features of the plugin type are encapsulated in the 00072 LADSPA_Properties type. This is assembled by ORing individual 00073 properties together. */ 00074 00075 typedef int LADSPA_Properties; 00076 00077 /* Property LADSPA_PROPERTY_REALTIME indicates that the plugin has a 00078 real-time dependency (e.g. listens to a MIDI device) and so its 00079 output must not be cached or subject to significant latency. */ 00080 #define LADSPA_PROPERTY_REALTIME 0x1 00081 00082 /* Property LADSPA_PROPERTY_INPLACE_BROKEN indicates that the plugin 00083 may cease to work correctly if the host elects to use the same data 00084 location for both input and output (see connect_port()). This 00085 should be avoided as enabling this flag makes it impossible for 00086 hosts to use the plugin to process audio `in-place.' */ 00087 #define LADSPA_PROPERTY_INPLACE_BROKEN 0x2 00088 00089 /* Property LADSPA_PROPERTY_HARD_RT_CAPABLE indicates that the plugin 00090 is capable of running not only in a conventional host but also in a 00091 `hard real-time' environment. To qualify for this the plugin must 00092 satisfy all of the following: 00093 00094 (1) The plugin must not use malloc(), free() or other heap memory 00095 management within its run() or run_adding() functions. All new 00096 memory used in run() must be managed via the stack. These 00097 restrictions only apply to the run() function. 00098 00099 (2) The plugin will not attempt to make use of any library 00100 functions with the exceptions of functions in the ANSI standard C 00101 and C maths libraries, which the host is expected to provide. 00102 00103 (3) The plugin will not access files, devices, pipes, sockets, IPC 00104 or any other mechanism that might result in process or thread 00105 blocking. 00106 00107 (4) The plugin will take an amount of time to execute a run() or 00108 run_adding() call approximately of form (A+B*SampleCount) where A 00109 and B depend on the machine and host in use. This amount of time 00110 may not depend on input signals or plugin state. The host is left 00111 the responsibility to perform timings to estimate upper bounds for 00112 A and B. */ 00113 #define LADSPA_PROPERTY_HARD_RT_CAPABLE 0x4 00114 00115 #define LADSPA_IS_REALTIME(x) ((x) & LADSPA_PROPERTY_REALTIME) 00116 #define LADSPA_IS_INPLACE_BROKEN(x) ((x) & LADSPA_PROPERTY_INPLACE_BROKEN) 00117 #define LADSPA_IS_HARD_RT_CAPABLE(x) ((x) & LADSPA_PROPERTY_HARD_RT_CAPABLE) 00118 00119 /*****************************************************************************/ 00120 00121 /* Plugin Ports: 00122 00123 Plugins have `ports' that are inputs or outputs for audio or 00124 data. Ports can communicate arrays of LADSPA_Data (for audio 00125 inputs/outputs) or single LADSPA_Data values (for control 00126 input/outputs). This information is encapsulated in the 00127 LADSPA_PortDescriptor type which is assembled by ORing individual 00128 properties together. 00129 00130 Note that a port must be an input or an output port but not both 00131 and that a port must be a control or audio port but not both. */ 00132 00133 typedef int LADSPA_PortDescriptor; 00134 00135 /* Property LADSPA_PORT_INPUT indicates that the port is an input. */ 00136 #define LADSPA_PORT_INPUT 0x1 00137 00138 /* Property LADSPA_PORT_OUTPUT indicates that the port is an output. */ 00139 #define LADSPA_PORT_OUTPUT 0x2 00140 00141 /* Property LADSPA_PORT_CONTROL indicates that the port is a control 00142 port. */ 00143 #define LADSPA_PORT_CONTROL 0x4 00144 00145 /* Property LADSPA_PORT_AUDIO indicates that the port is a audio 00146 port. */ 00147 #define LADSPA_PORT_AUDIO 0x8 00148 00149 #define LADSPA_IS_PORT_INPUT(x) ((x) & LADSPA_PORT_INPUT) 00150 #define LADSPA_IS_PORT_OUTPUT(x) ((x) & LADSPA_PORT_OUTPUT) 00151 #define LADSPA_IS_PORT_CONTROL(x) ((x) & LADSPA_PORT_CONTROL) 00152 #define LADSPA_IS_PORT_AUDIO(x) ((x) & LADSPA_PORT_AUDIO) 00153 00154 /*****************************************************************************/ 00155 00156 /* Plugin Port Range Hints: 00157 00158 The host may wish to provide a representation of data entering or 00159 leaving a plugin (e.g. to generate a GUI automatically). To make 00160 this more meaningful, the plugin should provide `hints' to the host 00161 describing the usual values taken by the data. 00162 00163 Note that these are only hints. The host may ignore them and the 00164 plugin must not assume that data supplied to it is meaningful. If 00165 the plugin receives invalid input data it is expected to continue 00166 to run without failure and, where possible, produce a sensible 00167 output (e.g. a high-pass filter given a negative cutoff frequency 00168 might switch to an all-pass mode). 00169 00170 Hints are meaningful for all input and output ports but hints for 00171 input control ports are expected to be particularly useful. 00172 00173 More hint information is encapsulated in the 00174 LADSPA_PortRangeHintDescriptor type which is assembled by ORing 00175 individual hint types together. Hints may require further 00176 LowerBound and UpperBound information. 00177 00178 All the hint information for a particular port is aggregated in the 00179 LADSPA_PortRangeHint structure. */ 00180 00181 typedef int LADSPA_PortRangeHintDescriptor; 00182 00183 /* Hint LADSPA_HINT_BOUNDED_BELOW indicates that the LowerBound field 00184 of the LADSPA_PortRangeHint should be considered meaningful. The 00185 value in this field should be considered the (inclusive) lower 00186 bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also 00187 specified then the value of LowerBound should be multiplied by the 00188 sample rate. */ 00189 #define LADSPA_HINT_BOUNDED_BELOW 0x1 00190 00191 /* Hint LADSPA_HINT_BOUNDED_ABOVE indicates that the UpperBound field 00192 of the LADSPA_PortRangeHint should be considered meaningful. The 00193 value in this field should be considered the (inclusive) upper 00194 bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also 00195 specified then the value of UpperBound should be multiplied by the 00196 sample rate. */ 00197 #define LADSPA_HINT_BOUNDED_ABOVE 0x2 00198 00199 /* Hint LADSPA_HINT_TOGGLED indicates that the data item should be 00200 considered a Boolean toggle. Data less than or equal to zero should 00201 be considered `off' or `false,' and data above zero should be 00202 considered `on' or `true.' LADSPA_HINT_TOGGLED may not be used in 00203 conjunction with any other hint except LADSPA_HINT_DEFAULT_0 or 00204 LADSPA_HINT_DEFAULT_1. */ 00205 #define LADSPA_HINT_TOGGLED 0x4 00206 00207 /* Hint LADSPA_HINT_SAMPLE_RATE indicates that any bounds specified 00208 should be interpreted as multiples of the sample rate. For 00209 instance, a frequency range from 0Hz to the Nyquist frequency (half 00210 the sample rate) could be requested by this hint in conjunction 00211 with LowerBound = 0 and UpperBound = 0.5. Hosts that support bounds 00212 at all must support this hint to retain meaning. */ 00213 #define LADSPA_HINT_SAMPLE_RATE 0x8 00214 00215 /* Hint LADSPA_HINT_LOGARITHMIC indicates that it is likely that the 00216 user will find it more intuitive to view values using a logarithmic 00217 scale. This is particularly useful for frequencies and gains. */ 00218 #define LADSPA_HINT_LOGARITHMIC 0x10 00219 00220 /* Hint LADSPA_HINT_INTEGER indicates that a user interface would 00221 probably wish to provide a stepped control taking only integer 00222 values. Any bounds set should be slightly wider than the actual 00223 integer range required to avoid floating point rounding errors. For 00224 instance, the integer set {0,1,2,3} might be described as [-0.1, 00225 3.1]. */ 00226 #define LADSPA_HINT_INTEGER 0x20 00227 00228 /* The various LADSPA_HINT_HAS_DEFAULT_* hints indicate a `normal' 00229 value for the port that is sensible as a default. For instance, 00230 this value is suitable for use as an initial value in a user 00231 interface or as a value the host might assign to a control port 00232 when the user has not provided one. Defaults are encoded using a 00233 mask so only one default may be specified for a port. Some of the 00234 hints make use of lower and upper bounds, in which case the 00235 relevant bound or bounds must be available and 00236 LADSPA_HINT_SAMPLE_RATE must be applied as usual. The resulting 00237 default must be rounded if LADSPA_HINT_INTEGER is present. Default 00238 values were introduced in LADSPA v1.1. */ 00239 #define LADSPA_HINT_DEFAULT_MASK 0x3C0 00240 00241 /* This default values indicates that no default is provided. */ 00242 #define LADSPA_HINT_DEFAULT_NONE 0x0 00243 00244 /* This default hint indicates that the suggested lower bound for the 00245 port should be used. */ 00246 #define LADSPA_HINT_DEFAULT_MINIMUM 0x40 00247 00248 /* This default hint indicates that a low value between the suggested 00249 lower and upper bounds should be chosen. For ports with 00250 LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.75 + 00251 log(upper) * 0.25). Otherwise, this should be (lower * 0.75 + upper 00252 * 0.25). */ 00253 #define LADSPA_HINT_DEFAULT_LOW 0x80 00254 00255 /* This default hint indicates that a middle value between the 00256 suggested lower and upper bounds should be chosen. For ports with 00257 LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.5 + 00258 log(upper) * 0.5). Otherwise, this should be (lower * 0.5 + upper * 00259 0.5). */ 00260 #define LADSPA_HINT_DEFAULT_MIDDLE 0xC0 00261 00262 /* This default hint indicates that a high value between the suggested 00263 lower and upper bounds should be chosen. For ports with 00264 LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.25 + 00265 log(upper) * 0.75). Otherwise, this should be (lower * 0.25 + upper 00266 * 0.75). */ 00267 #define LADSPA_HINT_DEFAULT_HIGH 0x100 00268 00269 /* This default hint indicates that the suggested upper bound for the 00270 port should be used. */ 00271 #define LADSPA_HINT_DEFAULT_MAXIMUM 0x140 00272 00273 /* This default hint indicates that the number 0 should be used. Note 00274 that this default may be used in conjunction with 00275 LADSPA_HINT_TOGGLED. */ 00276 #define LADSPA_HINT_DEFAULT_0 0x200 00277 00278 /* This default hint indicates that the number 1 should be used. Note 00279 that this default may be used in conjunction with 00280 LADSPA_HINT_TOGGLED. */ 00281 #define LADSPA_HINT_DEFAULT_1 0x240 00282 00283 /* This default hint indicates that the number 100 should be used. */ 00284 #define LADSPA_HINT_DEFAULT_100 0x280 00285 00286 /* This default hint indicates that the Hz frequency of `concert A' 00287 should be used. This will be 440 unless the host uses an unusual 00288 tuning convention, in which case it may be within a few Hz. */ 00289 #define LADSPA_HINT_DEFAULT_440 0x2C0 00290 00291 #define LADSPA_IS_HINT_BOUNDED_BELOW(x) ((x) & LADSPA_HINT_BOUNDED_BELOW) 00292 #define LADSPA_IS_HINT_BOUNDED_ABOVE(x) ((x) & LADSPA_HINT_BOUNDED_ABOVE) 00293 #define LADSPA_IS_HINT_TOGGLED(x) ((x) & LADSPA_HINT_TOGGLED) 00294 #define LADSPA_IS_HINT_SAMPLE_RATE(x) ((x) & LADSPA_HINT_SAMPLE_RATE) 00295 #define LADSPA_IS_HINT_LOGARITHMIC(x) ((x) & LADSPA_HINT_LOGARITHMIC) 00296 #define LADSPA_IS_HINT_INTEGER(x) ((x) & LADSPA_HINT_INTEGER) 00297 00298 #define LADSPA_IS_HINT_HAS_DEFAULT(x) ((x) & LADSPA_HINT_DEFAULT_MASK) 00299 #define LADSPA_IS_HINT_DEFAULT_MINIMUM(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ 00300 == LADSPA_HINT_DEFAULT_MINIMUM) 00301 #define LADSPA_IS_HINT_DEFAULT_LOW(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ 00302 == LADSPA_HINT_DEFAULT_LOW) 00303 #define LADSPA_IS_HINT_DEFAULT_MIDDLE(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ 00304 == LADSPA_HINT_DEFAULT_MIDDLE) 00305 #define LADSPA_IS_HINT_DEFAULT_HIGH(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ 00306 == LADSPA_HINT_DEFAULT_HIGH) 00307 #define LADSPA_IS_HINT_DEFAULT_MAXIMUM(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ 00308 == LADSPA_HINT_DEFAULT_MAXIMUM) 00309 #define LADSPA_IS_HINT_DEFAULT_0(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ 00310 == LADSPA_HINT_DEFAULT_0) 00311 #define LADSPA_IS_HINT_DEFAULT_1(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ 00312 == LADSPA_HINT_DEFAULT_1) 00313 #define LADSPA_IS_HINT_DEFAULT_100(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ 00314 == LADSPA_HINT_DEFAULT_100) 00315 #define LADSPA_IS_HINT_DEFAULT_440(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \ 00316 == LADSPA_HINT_DEFAULT_440) 00317 00318 typedef struct _LADSPA_PortRangeHint { 00319 00320 /* Hints about the port. */ 00321 LADSPA_PortRangeHintDescriptor HintDescriptor; 00322 00323 /* Meaningful when hint LADSPA_HINT_BOUNDED_BELOW is active. When 00324 LADSPA_HINT_SAMPLE_RATE is also active then this value should be 00325 multiplied by the relevant sample rate. */ 00326 LADSPA_Data LowerBound; 00327 00328 /* Meaningful when hint LADSPA_HINT_BOUNDED_ABOVE is active. When 00329 LADSPA_HINT_SAMPLE_RATE is also active then this value should be 00330 multiplied by the relevant sample rate. */ 00331 LADSPA_Data UpperBound; 00332 00333 } LADSPA_PortRangeHint; 00334 00335 /*****************************************************************************/ 00336 00337 /* Plugin Handles: 00338 00339 This plugin handle indicates a particular instance of the plugin 00340 concerned. It is valid to compare this to NULL (0 for C++) but 00341 otherwise the host should not attempt to interpret it. The plugin 00342 may use it to reference internal instance data. */ 00343 00344 typedef void * LADSPA_Handle; 00345 00346 /*****************************************************************************/ 00347 00348 /* Descriptor for a Type of Plugin: 00349 00350 This structure is used to describe a plugin type. It provides a 00351 number of functions to examine the type, instantiate it, link it to 00352 buffers and workspaces and to run it. */ 00353 00354 typedef struct _LADSPA_Descriptor { 00355 00356 /* This numeric identifier indicates the plugin type 00357 uniquely. Plugin programmers may reserve ranges of IDs from a 00358 central body to avoid clashes. Hosts may assume that IDs are 00359 below 0x1000000. */ 00360 unsigned long UniqueID; 00361 00362 /* This identifier can be used as a unique, case-sensitive 00363 identifier for the plugin type within the plugin file. Plugin 00364 types should be identified by file and label rather than by index 00365 or plugin name, which may be changed in new plugin 00366 versions. Labels must not contain white-space characters. */ 00367 const char * Label; 00368 00369 /* This indicates a number of properties of the plugin. */ 00370 LADSPA_Properties Properties; 00371 00372 /* This member points to the null-terminated name of the plugin 00373 (e.g. "Sine Oscillator"). */ 00374 const char * Name; 00375 00376 /* This member points to the null-terminated string indicating the 00377 maker of the plugin. This can be an empty string but not NULL. */ 00378 const char * Maker; 00379 00380 /* This member points to the null-terminated string indicating any 00381 copyright applying to the plugin. If no Copyright applies the 00382 string "None" should be used. */ 00383 const char * Copyright; 00384 00385 /* This indicates the number of ports (input AND output) present on 00386 the plugin. */ 00387 unsigned long PortCount; 00388 00389 /* This member indicates an array of port descriptors. Valid indices 00390 vary from 0 to PortCount-1. */ 00391 const LADSPA_PortDescriptor * PortDescriptors; 00392 00393 /* This member indicates an array of null-terminated strings 00394 describing ports (e.g. "Frequency (Hz)"). Valid indices vary from 00395 0 to PortCount-1. */ 00396 const char * const * PortNames; 00397 00398 /* This member indicates an array of range hints for each port (see 00399 above). Valid indices vary from 0 to PortCount-1. */ 00400 const LADSPA_PortRangeHint * PortRangeHints; 00401 00402 /* This may be used by the plugin developer to pass any custom 00403 implementation data into an instantiate call. It must not be used 00404 or interpreted by the host. It is expected that most plugin 00405 writers will not use this facility as LADSPA_Handle should be 00406 used to hold instance data. */ 00407 void * ImplementationData; 00408 00409 /* This member is a function pointer that instantiates a plugin. A 00410 handle is returned indicating the new plugin instance. The 00411 instantiation function accepts a sample rate as a parameter. The 00412 plugin descriptor from which this instantiate function was found 00413 must also be passed. This function must return NULL if 00414 instantiation fails. 00415 00416 Note that instance initialisation should generally occur in 00417 activate() rather than here. */ 00418 LADSPA_Handle (*instantiate)(const struct _LADSPA_Descriptor * Descriptor, 00419 unsigned long SampleRate); 00420 00421 /* This member is a function pointer that connects a port on an 00422 instantiated plugin to a memory location at which a block of data 00423 for the port will be read/written. The data location is expected 00424 to be an array of LADSPA_Data for audio ports or a single 00425 LADSPA_Data value for control ports. Memory issues will be 00426 managed by the host. The plugin must read/write the data at these 00427 locations every time run() or run_adding() is called and the data 00428 present at the time of this connection call should not be 00429 considered meaningful. 00430 00431 connect_port() may be called more than once for a plugin instance 00432 to allow the host to change the buffers that the plugin is 00433 reading or writing. These calls may be made before or after 00434 activate() or deactivate() calls. 00435 00436 connect_port() must be called at least once for each port before 00437 run() or run_adding() is called. When working with blocks of 00438 LADSPA_Data the plugin should pay careful attention to the block 00439 size passed to the run function as the block allocated may only 00440 just be large enough to contain the block of samples. 00441 00442 Plugin writers should be aware that the host may elect to use the 00443 same buffer for more than one port and even use the same buffer 00444 for both input and output (see LADSPA_PROPERTY_INPLACE_BROKEN). 00445 However, overlapped buffers or use of a single buffer for both 00446 audio and control data may result in unexpected behaviour. */ 00447 void (*connect_port)(LADSPA_Handle Instance, 00448 unsigned long Port, 00449 LADSPA_Data * DataLocation); 00450 00451 /* This member is a function pointer that initialises a plugin 00452 instance and activates it for use. This is separated from 00453 instantiate() to aid real-time support and so that hosts can 00454 reinitialise a plugin instance by calling deactivate() and then 00455 activate(). In this case the plugin instance must reset all state 00456 information dependent on the history of the plugin instance 00457 except for any data locations provided by connect_port() and any 00458 gain set by set_run_adding_gain(). If there is nothing for 00459 activate() to do then the plugin writer may provide a NULL rather 00460 than an empty function. 00461 00462 When present, hosts must call this function once before run() (or 00463 run_adding()) is called for the first time. This call should be 00464 made as close to the run() call as possible and indicates to 00465 real-time plugins that they are now live. Plugins should not rely 00466 on a prompt call to run() after activate(). activate() may not be 00467 called again unless deactivate() is called first. Note that 00468 connect_port() may be called before or after a call to 00469 activate(). */ 00470 void (*activate)(LADSPA_Handle Instance); 00471 00472 /* This method is a function pointer that runs an instance of a 00473 plugin for a block. Two parameters are required: the first is a 00474 handle to the particular instance to be run and the second 00475 indicates the block size (in samples) for which the plugin 00476 instance may run. 00477 00478 Note that if an activate() function exists then it must be called 00479 before run() or run_adding(). If deactivate() is called for a 00480 plugin instance then the plugin instance may not be reused until 00481 activate() has been called again. 00482 00483 If the plugin has the property LADSPA_PROPERTY_HARD_RT_CAPABLE 00484 then there are various things that the plugin should not do 00485 within the run() or run_adding() functions (see above). */ 00486 void (*run)(LADSPA_Handle Instance, 00487 unsigned long SampleCount); 00488 00489 /* This method is a function pointer that runs an instance of a 00490 plugin for a block. This has identical behaviour to run() except 00491 in the way data is output from the plugin. When run() is used, 00492 values are written directly to the memory areas associated with 00493 the output ports. However when run_adding() is called, values 00494 must be added to the values already present in the memory 00495 areas. Furthermore, output values written must be scaled by the 00496 current gain set by set_run_adding_gain() (see below) before 00497 addition. 00498 00499 run_adding() is optional. When it is not provided by a plugin, 00500 this function pointer must be set to NULL. When it is provided, 00501 the function set_run_adding_gain() must be provided also. */ 00502 void (*run_adding)(LADSPA_Handle Instance, 00503 unsigned long SampleCount); 00504 00505 /* This method is a function pointer that sets the output gain for 00506 use when run_adding() is called (see above). If this function is 00507 never called the gain is assumed to default to 1. Gain 00508 information should be retained when activate() or deactivate() 00509 are called. 00510 00511 This function should be provided by the plugin if and only if the 00512 run_adding() function is provided. When it is absent this 00513 function pointer must be set to NULL. */ 00514 void (*set_run_adding_gain)(LADSPA_Handle Instance, 00515 LADSPA_Data Gain); 00516 00517 /* This is the counterpart to activate() (see above). If there is 00518 nothing for deactivate() to do then the plugin writer may provide 00519 a NULL rather than an empty function. 00520 00521 Hosts must deactivate all activated units after they have been 00522 run() (or run_adding()) for the last time. This call should be 00523 made as close to the last run() call as possible and indicates to 00524 real-time plugins that they are no longer live. Plugins should 00525 not rely on prompt deactivation. Note that connect_port() may be 00526 called before or after a call to deactivate(). 00527 00528 Deactivation is not similar to pausing as the plugin instance 00529 will be reinitialised when activate() is called to reuse it. */ 00530 void (*deactivate)(LADSPA_Handle Instance); 00531 00532 /* Once an instance of a plugin has been finished with it can be 00533 deleted using the following function. The instance handle passed 00534 ceases to be valid after this call. 00535 00536 If activate() was called for a plugin instance then a 00537 corresponding call to deactivate() must be made before cleanup() 00538 is called. */ 00539 void (*cleanup)(LADSPA_Handle Instance); 00540 00541 } LADSPA_Descriptor; 00542 00543 /**********************************************************************/ 00544 00545 /* Accessing a Plugin: */ 00546 00547 /* The exact mechanism by which plugins are loaded is host-dependent, 00548 however all most hosts will need to know is the name of shared 00549 object file containing the plugin types. To allow multiple hosts to 00550 share plugin types, hosts may wish to check for environment 00551 variable LADSPA_PATH. If present, this should contain a 00552 colon-separated path indicating directories that should be searched 00553 (in order) when loading plugin types. 00554 00555 A plugin programmer must include a function called 00556 "ladspa_descriptor" with the following function prototype within 00557 the shared object file. This function will have C-style linkage (if 00558 you are using C++ this is taken care of by the `extern "C"' clause 00559 at the top of the file). 00560 00561 A host will find the plugin shared object file by one means or 00562 another, find the ladspa_descriptor() function, call it, and 00563 proceed from there. 00564 00565 Plugin types are accessed by index (not ID) using values from 0 00566 upwards. Out of range indexes must result in this function 00567 returning NULL, so the plugin count can be determined by checking 00568 for the least index that results in NULL being returned. */ 00569 00570 const LADSPA_Descriptor * ladspa_descriptor(unsigned long Index); 00571 00572 /* Datatype corresponding to the ladspa_descriptor() function. */ 00573 typedef const LADSPA_Descriptor * 00574 (*LADSPA_Descriptor_Function)(unsigned long Index); 00575 00576 /**********************************************************************/ 00577 00578 #ifdef __cplusplus 00579 } 00580 #endif 00581 00582 #endif /* LADSPA_INCLUDED */ 00583 00584 /* EOF */