Main Page | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members

ladspa.h

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

Generated on Sun Jan 8 13:38:56 2006 for Cinelerra-svn by  doxygen 1.4.4