DPF

DISTRHO Plugin Framework
Log | Files | Refs | Submodules | README | LICENSE

ladspa.h (27820B)


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