include/ladspa.h

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