/* ladspa.h   Linux Audio Developer's Simple Plugin API Version 1.1[LGPL].   Copyright (C) 2000-2002 Richard W.E. Furse, Paul Barton-Davis,   Stefan Westerfeld.      This library is free software; you can redistribute it and/or   modify it under the terms of the GNU Lesser General Public License   as published by the Free Software Foundation; either version 2.1 of   the License, or (at your option) any later version.      This library is distributed in the hope that it will be useful, but   WITHOUT ANY WARRANTY; without even the implied warranty of   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU   Lesser General Public License for more details.      You should have received a copy of the GNU Lesser General Public   License along with this library; if not, write to the Free Software   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307   USA. */#ifndef LADSPA_INCLUDED#define LADSPA_INCLUDED#define LADSPA_VERSION "1.1"#define LADSPA_VERSION_MAJOR 1#define LADSPA_VERSION_MINOR 1#ifdef __cplusplusextern "C" {#endif/*****************************************************************************//* Overview:    There is a large number of synthesis packages in use or development   on the Linux platform at this time. This API (`The Linux Audio   Developer's Simple Plugin API') attempts to give programmers the   ability to write simple `plugin' audio processors in C/C++ and link   them dynamically (`plug') into a range of these packages (`hosts').   It should be possible for any host and any plugin to communicate   completely through this interface.   This API is deliberately short and simple. To achieve compatibility   with a range of promising Linux sound synthesis packages it   attempts to find the `greatest common divisor' in their logical   behaviour. Having said this, certain limiting decisions are   implicit, notably the use of a fixed type (LADSPA_Data) for all   data transfer and absence of a parameterised `initialisation'   phase. See below for the LADSPA_Data typedef.   Plugins are expected to distinguish between control and audio   data. Plugins have `ports' that are inputs or outputs for audio or   control data and each plugin is `run' for a `block' corresponding   to a short time interval measured in samples. Audio data is   communicated using arrays of LADSPA_Data, allowing a block of audio   to be processed by the plugin in a single pass. Control data is   communicated using single LADSPA_Data values. Control data has a   single value at the start of a call to the `run()' or `run_adding()'   function, and may be considered to remain this value for its   duration. The plugin may assume that all its input and output ports   have been connected to the relevant data location (see the   `connect_port()' function below) before it is asked to run.   Plugins will reside in shared object files suitable for dynamic   linking by dlopen() and family. The file will provide a number of   `plugin types' that can be used to instantiate actual plugins   (sometimes known as `plugin instances') that can be connected   together to perform tasks.   This API contains very limited error-handling. *//*****************************************************************************//* Fundamental data type passed in and out of plugin. This data type   is used to communicate audio samples and control values. It is   assumed that the plugin will work sensibly given any numeric input   value although it may have a preferred range (see hints below).    For audio it is generally assumed that 1.0f is the `0dB' reference   amplitude and is a `normal' signal level. */typedef float LADSPA_Data;/*****************************************************************************//* Special Plugin Properties:     Optional features of the plugin type are encapsulated in the   LADSPA_Properties type. This is assembled by ORing individual   properties together. */typedef int LADSPA_Properties;/* Property LADSPA_PROPERTY_REALTIME indicates that the plugin has a   real-time dependency (e.g. listens to a MIDI device) and so its   output must not be cached or subject to significant latency. */#define LADSPA_PROPERTY_REALTIME        0x1/* Property LADSPA_PROPERTY_INPLACE_BROKEN indicates that the plugin   may cease to work correctly if the host elects to use the same data   location for both input and output (see connect_port()). This   should be avoided as enabling this flag makes it impossible for   hosts to use the plugin to process audio `in-place.' */#define LADSPA_PROPERTY_INPLACE_BROKEN  0x2/* Property LADSPA_PROPERTY_HARD_RT_CAPABLE indicates that the plugin   is capable of running not only in a conventional host but also in a   `hard real-time' environment. To qualify for this the plugin must   satisfy all of the following:   (1) The plugin must not use malloc(), free() or other heap memory   management within its run() or run_adding() functions. All new   memory used in run() must be managed via the stack. These   restrictions only apply to the run() function.   (2) The plugin will not attempt to make use of any library   functions with the exceptions of functions in the ANSI standard C   and C maths libraries, which the host is expected to provide.   (3) The plugin will not access files, devices, pipes, sockets, IPC   or any other mechanism that might result in process or thread   blocking.         (4) The plugin will take an amount of time to execute a run() or   run_adding() call approximately of form (A+B*SampleCount) where A   and B depend on the machine and host in use. This amount of time   may not depend on input signals or plugin state. The host is left   the responsibility to perform timings to estimate upper bounds for   A and B. */#define LADSPA_PROPERTY_HARD_RT_CAPABLE 0x4#define LADSPA_IS_REALTIME(x)        ((x) & LADSPA_PROPERTY_REALTIME)#define LADSPA_IS_INPLACE_BROKEN(x)  ((x) & LADSPA_PROPERTY_INPLACE_BROKEN)#define LADSPA_IS_HARD_RT_CAPABLE(x) ((x) & LADSPA_PROPERTY_HARD_RT_CAPABLE)/*****************************************************************************//* Plugin Ports:    Plugins have `ports' that are inputs or outputs for audio or   data. Ports can communicate arrays of LADSPA_Data (for audio   inputs/outputs) or single LADSPA_Data values (for control   input/outputs). This information is encapsulated in the   LADSPA_PortDescriptor type which is assembled by ORing individual   properties together.   Note that a port must be an input or an output port but not both   and that a port must be a control or audio port but not both. */typedef int LADSPA_PortDescriptor;/* Property LADSPA_PORT_INPUT indicates that the port is an input. */#define LADSPA_PORT_INPUT   0x1/* Property LADSPA_PORT_OUTPUT indicates that the port is an output. */#define LADSPA_PORT_OUTPUT  0x2/* Property LADSPA_PORT_CONTROL indicates that the port is a control   port. */#define LADSPA_PORT_CONTROL 0x4/* Property LADSPA_PORT_AUDIO indicates that the port is a audio   port. */#define LADSPA_PORT_AUDIO   0x8#define LADSPA_IS_PORT_INPUT(x)   ((x) & LADSPA_PORT_INPUT)#define LADSPA_IS_PORT_OUTPUT(x)  ((x) & LADSPA_PORT_OUTPUT)#define LADSPA_IS_PORT_CONTROL(x) ((x) & LADSPA_PORT_CONTROL)#define LADSPA_IS_PORT_AUDIO(x)   ((x) & LADSPA_PORT_AUDIO)/*****************************************************************************//* Plugin Port Range Hints:    The host may wish to provide a representation of data entering or   leaving a plugin (e.g. to generate a GUI automatically). To make   this more meaningful, the plugin should provide `hints' to the host   describing the usual values taken by the data.      Note that these are only hints. The host may ignore them and the   plugin must not assume that data supplied to it is meaningful. If   the plugin receives invalid input data it is expected to continue   to run without failure and, where possible, produce a sensible   output (e.g. a high-pass filter given a negative cutoff frequency   might switch to an all-pass mode).       Hints are meaningful for all input and output ports but hints for   input control ports are expected to be particularly useful.      More hint information is encapsulated in the   LADSPA_PortRangeHintDescriptor type which is assembled by ORing   individual hint types together. Hints may require further   LowerBound and UpperBound information.   All the hint information for a particular port is aggregated in the   LADSPA_PortRangeHint structure. */typedef int LADSPA_PortRangeHintDescriptor;/* Hint LADSPA_HINT_BOUNDED_BELOW indicates that the LowerBound field   of the LADSPA_PortRangeHint should be considered meaningful. The   value in this field should be considered the (inclusive) lower   bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also   specified then the value of LowerBound should be multiplied by the   sample rate. */#define LADSPA_HINT_BOUNDED_BELOW   0x1/* Hint LADSPA_HINT_BOUNDED_ABOVE indicates that the UpperBound field   of the LADSPA_PortRangeHint should be considered meaningful. The   value in this field should be considered the (inclusive) upper   bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also   specified then the value of UpperBound should be multiplied by the   sample rate. */#define LADSPA_HINT_BOUNDED_ABOVE   0x2/* Hint LADSPA_HINT_TOGGLED indicates that the data item should be   considered a Boolean toggle. Data less than or equal to zero should   be considered `off' or `false,' and data above zero should be   considered `on' or `true.' LADSPA_HINT_TOGGLED may not be used in   conjunction with any other hint except LADSPA_HINT_DEFAULT_0 or   LADSPA_HINT_DEFAULT_1. */#define LADSPA_HINT_TOGGLED         0x4/* Hint LADSPA_HINT_SAMPLE_RATE indicates that any bounds specified   should be interpreted as multiples of the sample rate. For   instance, a frequency range from 0Hz to the Nyquist frequency (half   the sample rate) could be requested by this hint in conjunction   with LowerBound = 0 and UpperBound = 0.5. Hosts that support bounds   at all must support this hint to retain meaning. */#define LADSPA_HINT_SAMPLE_RATE     0x8/* Hint LADSPA_HINT_LOGARITHMIC indicates that it is likely that the   user will find it more intuitive to view values using a logarithmic   scale. This is particularly useful for frequencies and gains. */#define LADSPA_HINT_LOGARITHMIC     0x10/* Hint LADSPA_HINT_INTEGER indicates that a user interface would   probably wish to provide a stepped control taking only integer   values. Any bounds set should be slightly wider than the actual   integer range required to avoid floating point rounding errors. For   instance, the integer set {0,1,2,3} might be described as [-0.1,   3.1]. */#define LADSPA_HINT_INTEGER         0x20/* The various LADSPA_HINT_HAS_DEFAULT_* hints indicate a `normal'   value for the port that is sensible as a default. For instance,   this value is suitable for use as an initial value in a user   interface or as a value the host might assign to a control port   when the user has not provided one. Defaults are encoded using a   mask so only one default may be specified for a port. Some of the   hints make use of lower and upper bounds, in which case the   relevant bound or bounds must be available and   LADSPA_HINT_SAMPLE_RATE must be applied as usual. The resulting   default must be rounded if LADSPA_HINT_INTEGER is present. Default   values were introduced in LADSPA v1.1. */#define LADSPA_HINT_DEFAULT_MASK    0x3C0/* This default values indicates that no default is provided. */#define LADSPA_HINT_DEFAULT_NONE    0x0/* This default hint indicates that the suggested lower bound for the   port should be used. */#define LADSPA_HINT_DEFAULT_MINIMUM 0x40/* This default hint indicates that a low value between the suggested   lower and upper bounds should be chosen. For ports with   LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.75 +   log(upper) * 0.25). Otherwise, this should be (lower * 0.75 + upper   * 0.25). */#define LADSPA_HINT_DEFAULT_LOW     0x80/* This default hint indicates that a middle value between the   suggested lower and upper bounds should be chosen. For ports with   LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.5 +   log(upper) * 0.5). Otherwise, this should be (lower * 0.5 + upper *   0.5). */#define LADSPA_HINT_DEFAULT_MIDDLE  0xC0/* This default hint indicates that a high value between the suggested   lower and upper bounds should be chosen. For ports with   LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.25 +   log(upper) * 0.75). Otherwise, this should be (lower * 0.25 + upper   * 0.75). */#define LADSPA_HINT_DEFAULT_HIGH    0x100/* This default hint indicates that the suggested upper bound for the   port should be used. */#define LADSPA_HINT_DEFAULT_MAXIMUM 0x140/* This default hint indicates that the number 0 should be used. Note   that this default may be used in conjunction with   LADSPA_HINT_TOGGLED. */#define LADSPA_HINT_DEFAULT_0       0x200/* This default hint indicates that the number 1 should be used. Note   that this default may be used in conjunction with   LADSPA_HINT_TOGGLED. */#define LADSPA_HINT_DEFAULT_1       0x240/* This default hint indicates that the number 100 should be used. */