src/modules/ladspa.h

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