cinelerra-5.1/cinelerra/ladspa.h

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