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