BEAST/BSE - Better Audio System and Sound Engine  0.8.2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
ladspa.hh
Go to the documentation of this file.
00001  // Licensed GNU LGPL v2.1 or later: http://www.gnu.org/licenses/lgpl.html
00002 
00003 #ifndef LADSPA_INCLUDED
00004 #define LADSPA_INCLUDED
00005 
00006 #define LADSPA_VERSION "1.1"
00007 #define LADSPA_VERSION_MAJOR 1
00008 #define LADSPA_VERSION_MINOR 1
00009 
00010 #ifdef __cplusplus
00011 extern "C" {
00012 #endif
00013 
00014 /*****************************************************************************/
00015 
00016 /* Overview: 
00017 
00018    There is a large number of synthesis packages in use or development
00019    on the Linux platform at this time. This API (`The Linux Audio
00020    Developer's Simple Plugin API') attempts to give programmers the
00021    ability to write simple `plugin' audio processors in C/C++ and link
00022    them dynamically (`plug') into a range of these packages (`hosts').
00023    It should be possible for any host and any plugin to communicate
00024    completely through this interface.
00025 
00026    This API is deliberately short and simple. To achieve compatibility
00027    with a range of promising Linux sound synthesis packages it
00028    attempts to find the `greatest common divisor' in their logical
00029    behaviour. Having said this, certain limiting decisions are
00030    implicit, notably the use of a fixed type (LADSPA_Data) for all
00031    data transfer and absence of a parameterised `initialisation'
00032    phase. See below for the LADSPA_Data typedef.
00033 
00034    Plugins are expected to distinguish between control and audio
00035    data. Plugins have `ports' that are inputs or outputs for audio or
00036    control data and each plugin is `run' for a `block' corresponding
00037    to a short time interval measured in samples. Audio data is
00038    communicated using arrays of LADSPA_Data, allowing a block of audio
00039    to be processed by the plugin in a single pass. Control data is
00040    communicated using single LADSPA_Data values. Control data has a
00041    single value at the start of a call to the `run()' or `run_adding()'
00042    function, and may be considered to remain this value for its
00043    duration. The plugin may assume that all its input and output ports
00044    have been connected to the relevant data location (see the
00045    `connect_port()' function below) before it is asked to run.
00046 
00047    Plugins will reside in shared object files suitable for dynamic
00048    linking by dlopen() and family. The file will provide a number of
00049    `plugin types' that can be used to instantiate actual plugins
00050    (sometimes known as `plugin instances') that can be connected
00051    together to perform tasks.
00052 
00053    This API contains very limited error-handling. */
00054 
00055 /*****************************************************************************/
00056 
00057 /* Fundamental data type passed in and out of plugin. This data type
00058    is used to communicate audio samples and control values. It is
00059    assumed that the plugin will work sensibly given any numeric input
00060    value although it may have a preferred range (see hints below). 
00061 
00062    For audio it is generally assumed that 1.0f is the `0dB' reference
00063    amplitude and is a `normal' signal level. */
00064 
00065 typedef float LADSPA_Data;
00066 
00067 /*****************************************************************************/
00068 
00069 /* Special Plugin Properties: 
00070 
00071    Optional features of the plugin type are encapsulated in the
00072    LADSPA_Properties type. This is assembled by ORing individual
00073    properties together. */
00074 
00075 typedef int LADSPA_Properties;
00076 
00077 /* Property LADSPA_PROPERTY_REALTIME indicates that the plugin has a
00078    real-time dependency (e.g. listens to a MIDI device) and so its
00079    output must not be cached or subject to significant latency. */
00080 #define LADSPA_PROPERTY_REALTIME        0x1
00081 
00082 /* Property LADSPA_PROPERTY_INPLACE_BROKEN indicates that the plugin
00083    may cease to work correctly if the host elects to use the same data
00084    location for both input and output (see connect_port()). This
00085    should be avoided as enabling this flag makes it impossible for
00086    hosts to use the plugin to process audio `in-place.' */
00087 #define LADSPA_PROPERTY_INPLACE_BROKEN  0x2
00088 
00089 /* Property LADSPA_PROPERTY_HARD_RT_CAPABLE indicates that the plugin
00090    is capable of running not only in a conventional host but also in a
00091    `hard real-time' environment. To qualify for this the plugin must
00092    satisfy all of the following:
00093 
00094    (1) The plugin must not use malloc(), free() or other heap memory
00095    management within its run() or run_adding() functions. All new
00096    memory used in run() must be managed via the stack. These
00097    restrictions only apply to the run() function.
00098 
00099    (2) The plugin will not attempt to make use of any library
00100    functions with the exceptions of functions in the ANSI standard C
00101    and C maths libraries, which the host is expected to provide.
00102 
00103    (3) The plugin will not access files, devices, pipes, sockets, IPC
00104    or any other mechanism that might result in process or thread
00105    blocking.
00106 
00107    (4) The plugin will take an amount of time to execute a run() or
00108    run_adding() call approximately of form (A+B*SampleCount) where A
00109    and B depend on the machine and host in use. This amount of time
00110    may not depend on input signals or plugin state. The host is left
00111    the responsibility to perform timings to estimate upper bounds for
00112    A and B. */
00113 #define LADSPA_PROPERTY_HARD_RT_CAPABLE 0x4
00114 
00115 #define LADSPA_IS_REALTIME(x)        ((x) & LADSPA_PROPERTY_REALTIME)
00116 #define LADSPA_IS_INPLACE_BROKEN(x)  ((x) & LADSPA_PROPERTY_INPLACE_BROKEN)
00117 #define LADSPA_IS_HARD_RT_CAPABLE(x) ((x) & LADSPA_PROPERTY_HARD_RT_CAPABLE)
00118 
00119 /*****************************************************************************/
00120 
00121 /* Plugin Ports: 
00122 
00123    Plugins have `ports' that are inputs or outputs for audio or
00124    data. Ports can communicate arrays of LADSPA_Data (for audio
00125    inputs/outputs) or single LADSPA_Data values (for control
00126    input/outputs). This information is encapsulated in the
00127    LADSPA_PortDescriptor type which is assembled by ORing individual
00128    properties together.
00129 
00130    Note that a port must be an input or an output port but not both
00131    and that a port must be a control or audio port but not both. */
00132 
00133 typedef int LADSPA_PortDescriptor;
00134 
00135 /* Property LADSPA_PORT_INPUT indicates that the port is an input. */
00136 #define LADSPA_PORT_INPUT   0x1
00137 
00138 /* Property LADSPA_PORT_OUTPUT indicates that the port is an output. */
00139 #define LADSPA_PORT_OUTPUT  0x2
00140 
00141 /* Property LADSPA_PORT_CONTROL indicates that the port is a control
00142    port. */
00143 #define LADSPA_PORT_CONTROL 0x4
00144 
00145 /* Property LADSPA_PORT_AUDIO indicates that the port is a audio
00146    port. */
00147 #define LADSPA_PORT_AUDIO   0x8
00148 
00149 #define LADSPA_IS_PORT_INPUT(x)   ((x) & LADSPA_PORT_INPUT)
00150 #define LADSPA_IS_PORT_OUTPUT(x)  ((x) & LADSPA_PORT_OUTPUT)
00151 #define LADSPA_IS_PORT_CONTROL(x) ((x) & LADSPA_PORT_CONTROL)
00152 #define LADSPA_IS_PORT_AUDIO(x)   ((x) & LADSPA_PORT_AUDIO)
00153 
00154 /*****************************************************************************/
00155 
00156 /* Plugin Port Range Hints: 
00157 
00158    The host may wish to provide a representation of data entering or
00159    leaving a plugin (e.g. to generate a GUI automatically). To make
00160    this more meaningful, the plugin should provide `hints' to the host
00161    describing the usual values taken by the data.
00162 
00163    Note that these are only hints. The host may ignore them and the
00164    plugin must not assume that data supplied to it is meaningful. If
00165    the plugin receives invalid input data it is expected to continue
00166    to run without failure and, where possible, produce a sensible
00167    output (e.g. a high-pass filter given a negative cutoff frequency
00168    might switch to an all-pass mode).
00169 
00170    Hints are meaningful for all input and output ports but hints for
00171    input control ports are expected to be particularly useful.
00172 
00173    More hint information is encapsulated in the
00174    LADSPA_PortRangeHintDescriptor type which is assembled by ORing
00175    individual hint types together. Hints may require further
00176    LowerBound and UpperBound information.
00177 
00178    All the hint information for a particular port is aggregated in the
00179    LADSPA_PortRangeHint structure. */
00180 
00181 typedef int LADSPA_PortRangeHintDescriptor;
00182 
00183 /* Hint LADSPA_HINT_BOUNDED_BELOW indicates that the LowerBound field
00184    of the LADSPA_PortRangeHint should be considered meaningful. The
00185    value in this field should be considered the (inclusive) lower
00186    bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also
00187    specified then the value of LowerBound should be multiplied by the
00188    sample rate. */
00189 #define LADSPA_HINT_BOUNDED_BELOW   0x1
00190 
00191 /* Hint LADSPA_HINT_BOUNDED_ABOVE indicates that the UpperBound field
00192    of the LADSPA_PortRangeHint should be considered meaningful. The
00193    value in this field should be considered the (inclusive) upper
00194    bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also
00195    specified then the value of UpperBound should be multiplied by the
00196    sample rate. */
00197 #define LADSPA_HINT_BOUNDED_ABOVE   0x2
00198 
00199 /* Hint LADSPA_HINT_TOGGLED indicates that the data item should be
00200    considered a Boolean toggle. Data less than or equal to zero should
00201    be considered `off' or `false,' and data above zero should be
00202    considered `on' or `true.' LADSPA_HINT_TOGGLED may not be used in
00203    conjunction with any other hint except LADSPA_HINT_DEFAULT_0 or
00204    LADSPA_HINT_DEFAULT_1. */
00205 #define LADSPA_HINT_TOGGLED         0x4
00206 
00207 /* Hint LADSPA_HINT_SAMPLE_RATE indicates that any bounds specified
00208    should be interpreted as multiples of the sample rate. For
00209    instance, a frequency range from 0Hz to the Nyquist frequency (half
00210    the sample rate) could be requested by this hint in conjunction
00211    with LowerBound = 0 and UpperBound = 0.5. Hosts that support bounds
00212    at all must support this hint to retain meaning. */
00213 #define LADSPA_HINT_SAMPLE_RATE     0x8
00214 
00215 /* Hint LADSPA_HINT_LOGARITHMIC indicates that it is likely that the
00216    user will find it more intuitive to view values using a logarithmic
00217    scale. This is particularly useful for frequencies and gains. */
00218 #define LADSPA_HINT_LOGARITHMIC     0x10
00219 
00220 /* Hint LADSPA_HINT_INTEGER indicates that a user interface would
00221    probably wish to provide a stepped control taking only integer
00222    values. Any bounds set should be slightly wider than the actual
00223    integer range required to avoid floating point rounding errors. For
00224    instance, the integer set {0,1,2,3} might be described as [-0.1,
00225    3.1]. */
00226 #define LADSPA_HINT_INTEGER         0x20
00227 
00228 /* The various LADSPA_HINT_HAS_DEFAULT_* hints indicate a `normal'
00229    value for the port that is sensible as a default. For instance,
00230    this value is suitable for use as an initial value in a user
00231    interface or as a value the host might assign to a control port
00232    when the user has not provided one. Defaults are encoded using a
00233    mask so only one default may be specified for a port. Some of the
00234    hints make use of lower and upper bounds, in which case the
00235    relevant bound or bounds must be available and
00236    LADSPA_HINT_SAMPLE_RATE must be applied as usual. The resulting
00237    default must be rounded if LADSPA_HINT_INTEGER is present. Default
00238    values were introduced in LADSPA v1.1. */
00239 #define LADSPA_HINT_DEFAULT_MASK    0x3C0
00240 
00241 /* This default values indicates that no default is provided. */
00242 #define LADSPA_HINT_DEFAULT_NONE    0x0
00243 
00244 /* This default hint indicates that the suggested lower bound for the
00245    port should be used. */
00246 #define LADSPA_HINT_DEFAULT_MINIMUM 0x40
00247 
00248 /* This default hint indicates that a low value between the suggested
00249    lower and upper bounds should be chosen. For ports with
00250    LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.75 +
00251    log(upper) * 0.25). Otherwise, this should be (lower * 0.75 + upper
00252    * 0.25). */
00253 #define LADSPA_HINT_DEFAULT_LOW     0x80
00254 
00255 /* This default hint indicates that a middle value between the
00256    suggested lower and upper bounds should be chosen. For ports with
00257    LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.5 +
00258    log(upper) * 0.5). Otherwise, this should be (lower * 0.5 + upper *
00259    0.5). */
00260 #define LADSPA_HINT_DEFAULT_MIDDLE  0xC0
00261 
00262 /* This default hint indicates that a high value between the suggested
00263    lower and upper bounds should be chosen. For ports with
00264    LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.25 +
00265    log(upper) * 0.75). Otherwise, this should be (lower * 0.25 + upper
00266    * 0.75). */
00267 #define LADSPA_HINT_DEFAULT_HIGH    0x100
00268 
00269 /* This default hint indicates that the suggested upper bound for the
00270    port should be used. */
00271 #define LADSPA_HINT_DEFAULT_MAXIMUM 0x140
00272 
00273 /* This default hint indicates that the number 0 should be used. Note
00274    that this default may be used in conjunction with
00275    LADSPA_HINT_TOGGLED. */
00276 #define LADSPA_HINT_DEFAULT_0       0x200
00277 
00278 /* This default hint indicates that the number 1 should be used. Note
00279    that this default may be used in conjunction with
00280    LADSPA_HINT_TOGGLED. */
00281 #define LADSPA_HINT_DEFAULT_1       0x240
00282 
00283 /* This default hint indicates that the number 100 should be used. */
00284 #define LADSPA_HINT_DEFAULT_100     0x280
00285 
00286 /* This default hint indicates that the Hz frequency of `concert A'
00287    should be used. This will be 440 unless the host uses an unusual
00288    tuning convention, in which case it may be within a few Hz. */
00289 #define LADSPA_HINT_DEFAULT_440     0x2C0
00290 
00291 #define LADSPA_IS_HINT_BOUNDED_BELOW(x)   ((x) & LADSPA_HINT_BOUNDED_BELOW)
00292 #define LADSPA_IS_HINT_BOUNDED_ABOVE(x)   ((x) & LADSPA_HINT_BOUNDED_ABOVE)
00293 #define LADSPA_IS_HINT_TOGGLED(x)         ((x) & LADSPA_HINT_TOGGLED)
00294 #define LADSPA_IS_HINT_SAMPLE_RATE(x)     ((x) & LADSPA_HINT_SAMPLE_RATE)
00295 #define LADSPA_IS_HINT_LOGARITHMIC(x)     ((x) & LADSPA_HINT_LOGARITHMIC)
00296 #define LADSPA_IS_HINT_INTEGER(x)         ((x) & LADSPA_HINT_INTEGER)
00297 
00298 #define LADSPA_IS_HINT_HAS_DEFAULT(x)     ((x) & LADSPA_HINT_DEFAULT_MASK)
00299 #define LADSPA_IS_HINT_DEFAULT_MINIMUM(x) (((x) & LADSPA_HINT_DEFAULT_MASK)   \
00300                                            == LADSPA_HINT_DEFAULT_MINIMUM)
00301 #define LADSPA_IS_HINT_DEFAULT_LOW(x)     (((x) & LADSPA_HINT_DEFAULT_MASK)   \
00302                                            == LADSPA_HINT_DEFAULT_LOW)
00303 #define LADSPA_IS_HINT_DEFAULT_MIDDLE(x)  (((x) & LADSPA_HINT_DEFAULT_MASK)   \
00304                                            == LADSPA_HINT_DEFAULT_MIDDLE)
00305 #define LADSPA_IS_HINT_DEFAULT_HIGH(x)    (((x) & LADSPA_HINT_DEFAULT_MASK)   \
00306                                            == LADSPA_HINT_DEFAULT_HIGH)
00307 #define LADSPA_IS_HINT_DEFAULT_MAXIMUM(x) (((x) & LADSPA_HINT_DEFAULT_MASK)   \
00308                                            == LADSPA_HINT_DEFAULT_MAXIMUM)
00309 #define LADSPA_IS_HINT_DEFAULT_0(x)       (((x) & LADSPA_HINT_DEFAULT_MASK)   \
00310                                            == LADSPA_HINT_DEFAULT_0)
00311 #define LADSPA_IS_HINT_DEFAULT_1(x)       (((x) & LADSPA_HINT_DEFAULT_MASK)   \
00312                                            == LADSPA_HINT_DEFAULT_1)
00313 #define LADSPA_IS_HINT_DEFAULT_100(x)     (((x) & LADSPA_HINT_DEFAULT_MASK)   \
00314                                            == LADSPA_HINT_DEFAULT_100)
00315 #define LADSPA_IS_HINT_DEFAULT_440(x)     (((x) & LADSPA_HINT_DEFAULT_MASK)   \
00316                                             == LADSPA_HINT_DEFAULT_440)
00317 
00318 typedef struct _LADSPA_PortRangeHint {
00319 
00320   /* Hints about the port. */
00321   LADSPA_PortRangeHintDescriptor HintDescriptor;
00322 
00323   /* Meaningful when hint LADSPA_HINT_BOUNDED_BELOW is active. When
00324      LADSPA_HINT_SAMPLE_RATE is also active then this value should be
00325      multiplied by the relevant sample rate. */
00326   LADSPA_Data LowerBound;
00327 
00328   /* Meaningful when hint LADSPA_HINT_BOUNDED_ABOVE is active. When
00329      LADSPA_HINT_SAMPLE_RATE is also active then this value should be
00330      multiplied by the relevant sample rate. */
00331   LADSPA_Data UpperBound;
00332 
00333 } LADSPA_PortRangeHint;
00334 
00335 /*****************************************************************************/
00336 
00337 /* Plugin Handles: 
00338 
00339    This plugin handle indicates a particular instance of the plugin
00340    concerned. It is valid to compare this to NULL (0 for C++) but
00341    otherwise the host should not attempt to interpret it. The plugin
00342    may use it to reference internal instance data. */
00343 
00344 typedef void * LADSPA_Handle;
00345 
00346 /*****************************************************************************/
00347 
00348 /* Descriptor for a Type of Plugin: 
00349 
00350    This structure is used to describe a plugin type. It provides a
00351    number of functions to examine the type, instantiate it, link it to
00352    buffers and workspaces and to run it. */
00353 
00354 typedef struct _LADSPA_Descriptor { 
00355 
00356   /* This numeric identifier indicates the plugin type
00357      uniquely. Plugin programmers may reserve ranges of IDs from a
00358      central body to avoid clashes. Hosts may assume that IDs are
00359      below 0x1000000. */
00360   unsigned long UniqueID;
00361 
00362   /* This identifier can be used as a unique, case-sensitive
00363      identifier for the plugin type within the plugin file. Plugin
00364      types should be identified by file and label rather than by index
00365      or plugin name, which may be changed in new plugin
00366      versions. Labels must not contain white-space characters. */
00367   const char * Label;
00368 
00369   /* This indicates a number of properties of the plugin. */
00370   LADSPA_Properties Properties;
00371 
00372   /* This member points to the null-terminated name of the plugin
00373      (e.g. "Sine Oscillator"). */
00374   const char * Name;
00375 
00376   /* This member points to the null-terminated string indicating the
00377      maker of the plugin. This can be an empty string but not NULL. */
00378   const char * Maker;
00379 
00380   /* This member points to the null-terminated string indicating any
00381      copyright applying to the plugin. If no Copyright applies the
00382      string "None" should be used. */
00383   const char * Copyright;
00384 
00385   /* This indicates the number of ports (input AND output) present on
00386      the plugin. */
00387   unsigned long PortCount;
00388 
00389   /* This member indicates an array of port descriptors. Valid indices
00390      vary from 0 to PortCount-1. */
00391   const LADSPA_PortDescriptor * PortDescriptors;
00392 
00393   /* This member indicates an array of null-terminated strings
00394      describing ports (e.g. "Frequency (Hz)"). Valid indices vary from
00395      0 to PortCount-1. */
00396   const char * const * PortNames;
00397 
00398   /* This member indicates an array of range hints for each port (see
00399      above). Valid indices vary from 0 to PortCount-1. */
00400   const LADSPA_PortRangeHint * PortRangeHints;
00401 
00402   /* This may be used by the plugin developer to pass any custom
00403      implementation data into an instantiate call. It must not be used
00404      or interpreted by the host. It is expected that most plugin
00405      writers will not use this facility as LADSPA_Handle should be
00406      used to hold instance data. */
00407   void * ImplementationData;
00408 
00409   /* This member is a function pointer that instantiates a plugin. A
00410      handle is returned indicating the new plugin instance. The
00411      instantiation function accepts a sample rate as a parameter. The
00412      plugin descriptor from which this instantiate function was found
00413      must also be passed. This function must return NULL if
00414      instantiation fails. 
00415 
00416      Note that instance initialisation should generally occur in
00417      activate() rather than here. */
00418   LADSPA_Handle (*instantiate)(const struct _LADSPA_Descriptor * Descriptor,
00419                                unsigned long                     SampleRate);
00420 
00421   /* This member is a function pointer that connects a port on an
00422      instantiated plugin to a memory location at which a block of data
00423      for the port will be read/written. The data location is expected
00424      to be an array of LADSPA_Data for audio ports or a single
00425      LADSPA_Data value for control ports. Memory issues will be
00426      managed by the host. The plugin must read/write the data at these
00427      locations every time run() or run_adding() is called and the data
00428      present at the time of this connection call should not be
00429      considered meaningful.
00430 
00431      connect_port() may be called more than once for a plugin instance
00432      to allow the host to change the buffers that the plugin is
00433      reading or writing. These calls may be made before or after
00434      activate() or deactivate() calls.
00435 
00436      connect_port() must be called at least once for each port before
00437      run() or run_adding() is called. When working with blocks of
00438      LADSPA_Data the plugin should pay careful attention to the block
00439      size passed to the run function as the block allocated may only
00440      just be large enough to contain the block of samples.
00441 
00442      Plugin writers should be aware that the host may elect to use the
00443      same buffer for more than one port and even use the same buffer
00444      for both input and output (see LADSPA_PROPERTY_INPLACE_BROKEN).
00445      However, overlapped buffers or use of a single buffer for both
00446      audio and control data may result in unexpected behaviour. */
00447    void (*connect_port)(LADSPA_Handle Instance,
00448                         unsigned long Port,
00449                         LADSPA_Data * DataLocation);
00450 
00451   /* This member is a function pointer that initialises a plugin
00452      instance and activates it for use. This is separated from
00453      instantiate() to aid real-time support and so that hosts can
00454      reinitialise a plugin instance by calling deactivate() and then
00455      activate(). In this case the plugin instance must reset all state
00456      information dependent on the history of the plugin instance
00457      except for any data locations provided by connect_port() and any
00458      gain set by set_run_adding_gain(). If there is nothing for
00459      activate() to do then the plugin writer may provide a NULL rather
00460      than an empty function.
00461 
00462      When present, hosts must call this function once before run() (or
00463      run_adding()) is called for the first time. This call should be
00464      made as close to the run() call as possible and indicates to
00465      real-time plugins that they are now live. Plugins should not rely
00466      on a prompt call to run() after activate(). activate() may not be
00467      called again unless deactivate() is called first. Note that
00468      connect_port() may be called before or after a call to
00469      activate(). */
00470   void (*activate)(LADSPA_Handle Instance);
00471 
00472   /* This method is a function pointer that runs an instance of a
00473      plugin for a block. Two parameters are required: the first is a
00474      handle to the particular instance to be run and the second
00475      indicates the block size (in samples) for which the plugin
00476      instance may run.
00477 
00478      Note that if an activate() function exists then it must be called
00479      before run() or run_adding(). If deactivate() is called for a
00480      plugin instance then the plugin instance may not be reused until
00481      activate() has been called again.
00482 
00483      If the plugin has the property LADSPA_PROPERTY_HARD_RT_CAPABLE
00484      then there are various things that the plugin should not do
00485      within the run() or run_adding() functions (see above). */
00486   void (*run)(LADSPA_Handle Instance,
00487               unsigned long SampleCount);
00488 
00489   /* This method is a function pointer that runs an instance of a
00490      plugin for a block. This has identical behaviour to run() except
00491      in the way data is output from the plugin. When run() is used,
00492      values are written directly to the memory areas associated with
00493      the output ports. However when run_adding() is called, values
00494      must be added to the values already present in the memory
00495      areas. Furthermore, output values written must be scaled by the
00496      current gain set by set_run_adding_gain() (see below) before
00497      addition.
00498 
00499      run_adding() is optional. When it is not provided by a plugin,
00500      this function pointer must be set to NULL. When it is provided,
00501      the function set_run_adding_gain() must be provided also. */
00502   void (*run_adding)(LADSPA_Handle Instance,
00503                      unsigned long SampleCount);
00504 
00505   /* This method is a function pointer that sets the output gain for
00506      use when run_adding() is called (see above). If this function is
00507      never called the gain is assumed to default to 1. Gain
00508      information should be retained when activate() or deactivate()
00509      are called.
00510 
00511      This function should be provided by the plugin if and only if the
00512      run_adding() function is provided. When it is absent this
00513      function pointer must be set to NULL. */
00514   void (*set_run_adding_gain)(LADSPA_Handle Instance,
00515                               LADSPA_Data   Gain);
00516 
00517   /* This is the counterpart to activate() (see above). If there is
00518      nothing for deactivate() to do then the plugin writer may provide
00519      a NULL rather than an empty function.
00520 
00521      Hosts must deactivate all activated units after they have been
00522      run() (or run_adding()) for the last time. This call should be
00523      made as close to the last run() call as possible and indicates to
00524      real-time plugins that they are no longer live. Plugins should
00525      not rely on prompt deactivation. Note that connect_port() may be
00526      called before or after a call to deactivate().
00527 
00528      Deactivation is not similar to pausing as the plugin instance
00529      will be reinitialised when activate() is called to reuse it. */
00530   void (*deactivate)(LADSPA_Handle Instance);
00531 
00532   /* Once an instance of a plugin has been finished with it can be
00533      deleted using the following function. The instance handle passed
00534      ceases to be valid after this call.
00535 
00536      If activate() was called for a plugin instance then a
00537      corresponding call to deactivate() must be made before cleanup()
00538      is called. */
00539   void (*cleanup)(LADSPA_Handle Instance);
00540 
00541 } LADSPA_Descriptor;
00542 
00543 /**********************************************************************/
00544 
00545 /* Accessing a Plugin: */
00546 
00547 /* The exact mechanism by which plugins are loaded is host-dependent,
00548    however all most hosts will need to know is the name of shared
00549    object file containing the plugin types. To allow multiple hosts to
00550    share plugin types, hosts may wish to check for environment
00551    variable LADSPA_PATH. If present, this should contain a
00552    colon-separated path indicating directories that should be searched
00553    (in order) when loading plugin types.
00554 
00555    A plugin programmer must include a function called
00556    "ladspa_descriptor" with the following function prototype within
00557    the shared object file. This function will have C-style linkage (if
00558    you are using C++ this is taken care of by the `extern "C"' clause
00559    at the top of the file).
00560 
00561    A host will find the plugin shared object file by one means or
00562    another, find the ladspa_descriptor() function, call it, and
00563    proceed from there.
00564 
00565    Plugin types are accessed by index (not ID) using values from 0
00566    upwards. Out of range indexes must result in this function
00567    returning NULL, so the plugin count can be determined by checking
00568    for the least index that results in NULL being returned. */
00569 
00570 const LADSPA_Descriptor * ladspa_descriptor(unsigned long Index);
00571 
00572 /* Datatype corresponding to the ladspa_descriptor() function. */
00573 typedef const LADSPA_Descriptor * 
00574 (*LADSPA_Descriptor_Function)(unsigned long Index);
00575 
00576 /**********************************************************************/
00577 
00578 #ifdef __cplusplus
00579 }
00580 #endif
00581 
00582 #endif /* LADSPA_INCLUDED */
00583 
00584 /* EOF */
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines