Blame src/ladspa.h

Packit 995986
/* ladspa.h
Packit 995986
Packit 995986
   Linux Audio Developer's Simple Plugin API Version 1.1[LGPL].
Packit 995986
   Copyright (C) 2000-2002 Richard W.E. Furse, Paul Barton-Davis,
Packit 995986
   Stefan Westerfeld.
Packit 995986
   
Packit 995986
   This library is free software; you can redistribute it and/or
Packit 995986
   modify it under the terms of the GNU Lesser General Public License
Packit 995986
   as published by the Free Software Foundation; either version 2.1 of
Packit 995986
   the License, or (at your option) any later version.
Packit 995986
   
Packit 995986
   This library is distributed in the hope that it will be useful, but
Packit 995986
   WITHOUT ANY WARRANTY; without even the implied warranty of
Packit 995986
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Packit 995986
   Lesser General Public License for more details.
Packit 995986
   
Packit 995986
   You should have received a copy of the GNU Lesser General Public
Packit 995986
   License along with this library; if not, write to the Free Software
Packit 995986
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
Packit 995986
   USA. */
Packit 995986
Packit 995986
#ifndef LADSPA_INCLUDED
Packit 995986
#define LADSPA_INCLUDED
Packit 995986
Packit 995986
#define LADSPA_VERSION "1.1"
Packit 995986
#define LADSPA_VERSION_MAJOR 1
Packit 995986
#define LADSPA_VERSION_MINOR 1
Packit 995986
Packit 995986
#ifdef __cplusplus
Packit 995986
extern "C" {
Packit 995986
#endif
Packit 995986
Packit 995986
/*****************************************************************************/
Packit 995986
Packit 995986
/* Overview: 
Packit 995986
Packit 995986
   There is a large number of synthesis packages in use or development
Packit 995986
   on the Linux platform at this time. This API (`The Linux Audio
Packit 995986
   Developer's Simple Plugin API') attempts to give programmers the
Packit 995986
   ability to write simple `plugin' audio processors in C/C++ and link
Packit 995986
   them dynamically (`plug') into a range of these packages (`hosts').
Packit 995986
   It should be possible for any host and any plugin to communicate
Packit 995986
   completely through this interface.
Packit 995986
Packit 995986
   This API is deliberately short and simple. To achieve compatibility
Packit 995986
   with a range of promising Linux sound synthesis packages it
Packit 995986
   attempts to find the `greatest common divisor' in their logical
Packit 995986
   behaviour. Having said this, certain limiting decisions are
Packit 995986
   implicit, notably the use of a fixed type (LADSPA_Data) for all
Packit 995986
   data transfer and absence of a parameterised `initialisation'
Packit 995986
   phase. See below for the LADSPA_Data typedef.
Packit 995986
Packit 995986
   Plugins are expected to distinguish between control and audio
Packit 995986
   data. Plugins have `ports' that are inputs or outputs for audio or
Packit 995986
   control data and each plugin is `run' for a `block' corresponding
Packit 995986
   to a short time interval measured in samples. Audio data is
Packit 995986
   communicated using arrays of LADSPA_Data, allowing a block of audio
Packit 995986
   to be processed by the plugin in a single pass. Control data is
Packit 995986
   communicated using single LADSPA_Data values. Control data has a
Packit 995986
   single value at the start of a call to the `run()' or `run_adding()'
Packit 995986
   function, and may be considered to remain this value for its
Packit 995986
   duration. The plugin may assume that all its input and output ports
Packit 995986
   have been connected to the relevant data location (see the
Packit 995986
   `connect_port()' function below) before it is asked to run.
Packit 995986
Packit 995986
   Plugins will reside in shared object files suitable for dynamic
Packit 995986
   linking by dlopen() and family. The file will provide a number of
Packit 995986
   `plugin types' that can be used to instantiate actual plugins
Packit 995986
   (sometimes known as `plugin instances') that can be connected
Packit 995986
   together to perform tasks.
Packit 995986
Packit 995986
   This API contains very limited error-handling. */
Packit 995986
Packit 995986
/*****************************************************************************/
Packit 995986
Packit 995986
/* Fundamental data type passed in and out of plugin. This data type
Packit 995986
   is used to communicate audio samples and control values. It is
Packit 995986
   assumed that the plugin will work sensibly given any numeric input
Packit 995986
   value although it may have a preferred range (see hints below). 
Packit 995986
Packit 995986
   For audio it is generally assumed that 1.0f is the `0dB' reference
Packit 995986
   amplitude and is a `normal' signal level. */
Packit 995986
Packit 995986
typedef float LADSPA_Data;
Packit 995986
Packit 995986
/*****************************************************************************/
Packit 995986
Packit 995986
/* Special Plugin Properties: 
Packit 995986
 
Packit 995986
   Optional features of the plugin type are encapsulated in the
Packit 995986
   LADSPA_Properties type. This is assembled by ORing individual
Packit 995986
   properties together. */
Packit 995986
Packit 995986
typedef int LADSPA_Properties;
Packit 995986
Packit 995986
/* Property LADSPA_PROPERTY_REALTIME indicates that the plugin has a
Packit 995986
   real-time dependency (e.g. listens to a MIDI device) and so its
Packit 995986
   output must not be cached or subject to significant latency. */
Packit 995986
#define LADSPA_PROPERTY_REALTIME        0x1
Packit 995986
Packit 995986
/* Property LADSPA_PROPERTY_INPLACE_BROKEN indicates that the plugin
Packit 995986
   may cease to work correctly if the host elects to use the same data
Packit 995986
   location for both input and output (see connect_port()). This
Packit 995986
   should be avoided as enabling this flag makes it impossible for
Packit 995986
   hosts to use the plugin to process audio `in-place.' */
Packit 995986
#define LADSPA_PROPERTY_INPLACE_BROKEN  0x2
Packit 995986
Packit 995986
/* Property LADSPA_PROPERTY_HARD_RT_CAPABLE indicates that the plugin
Packit 995986
   is capable of running not only in a conventional host but also in a
Packit 995986
   `hard real-time' environment. To qualify for this the plugin must
Packit 995986
   satisfy all of the following:
Packit 995986
Packit 995986
   (1) The plugin must not use malloc(), free() or other heap memory
Packit 995986
   management within its run() or run_adding() functions. All new
Packit 995986
   memory used in run() must be managed via the stack. These
Packit 995986
   restrictions only apply to the run() function.
Packit 995986
Packit 995986
   (2) The plugin will not attempt to make use of any library
Packit 995986
   functions with the exceptions of functions in the ANSI standard C
Packit 995986
   and C maths libraries, which the host is expected to provide.
Packit 995986
Packit 995986
   (3) The plugin will not access files, devices, pipes, sockets, IPC
Packit 995986
   or any other mechanism that might result in process or thread
Packit 995986
   blocking.
Packit 995986
      
Packit 995986
   (4) The plugin will take an amount of time to execute a run() or
Packit 995986
   run_adding() call approximately of form (A+B*SampleCount) where A
Packit 995986
   and B depend on the machine and host in use. This amount of time
Packit 995986
   may not depend on input signals or plugin state. The host is left
Packit 995986
   the responsibility to perform timings to estimate upper bounds for
Packit 995986
   A and B. */
Packit 995986
#define LADSPA_PROPERTY_HARD_RT_CAPABLE 0x4
Packit 995986
Packit 995986
#define LADSPA_IS_REALTIME(x)        ((x) & LADSPA_PROPERTY_REALTIME)
Packit 995986
#define LADSPA_IS_INPLACE_BROKEN(x)  ((x) & LADSPA_PROPERTY_INPLACE_BROKEN)
Packit 995986
#define LADSPA_IS_HARD_RT_CAPABLE(x) ((x) & LADSPA_PROPERTY_HARD_RT_CAPABLE)
Packit 995986
Packit 995986
/*****************************************************************************/
Packit 995986
Packit 995986
/* Plugin Ports: 
Packit 995986
Packit 995986
   Plugins have `ports' that are inputs or outputs for audio or
Packit 995986
   data. Ports can communicate arrays of LADSPA_Data (for audio
Packit 995986
   inputs/outputs) or single LADSPA_Data values (for control
Packit 995986
   input/outputs). This information is encapsulated in the
Packit 995986
   LADSPA_PortDescriptor type which is assembled by ORing individual
Packit 995986
   properties together.
Packit 995986
Packit 995986
   Note that a port must be an input or an output port but not both
Packit 995986
   and that a port must be a control or audio port but not both. */
Packit 995986
Packit 995986
typedef int LADSPA_PortDescriptor;
Packit 995986
Packit 995986
/* Property LADSPA_PORT_INPUT indicates that the port is an input. */
Packit 995986
#define LADSPA_PORT_INPUT   0x1
Packit 995986
Packit 995986
/* Property LADSPA_PORT_OUTPUT indicates that the port is an output. */
Packit 995986
#define LADSPA_PORT_OUTPUT  0x2
Packit 995986
Packit 995986
/* Property LADSPA_PORT_CONTROL indicates that the port is a control
Packit 995986
   port. */
Packit 995986
#define LADSPA_PORT_CONTROL 0x4
Packit 995986
Packit 995986
/* Property LADSPA_PORT_AUDIO indicates that the port is a audio
Packit 995986
   port. */
Packit 995986
#define LADSPA_PORT_AUDIO   0x8
Packit 995986
Packit 995986
#define LADSPA_IS_PORT_INPUT(x)   ((x) & LADSPA_PORT_INPUT)
Packit 995986
#define LADSPA_IS_PORT_OUTPUT(x)  ((x) & LADSPA_PORT_OUTPUT)
Packit 995986
#define LADSPA_IS_PORT_CONTROL(x) ((x) & LADSPA_PORT_CONTROL)
Packit 995986
#define LADSPA_IS_PORT_AUDIO(x)   ((x) & LADSPA_PORT_AUDIO)
Packit 995986
Packit 995986
/*****************************************************************************/
Packit 995986
Packit 995986
/* Plugin Port Range Hints: 
Packit 995986
Packit 995986
   The host may wish to provide a representation of data entering or
Packit 995986
   leaving a plugin (e.g. to generate a GUI automatically). To make
Packit 995986
   this more meaningful, the plugin should provide `hints' to the host
Packit 995986
   describing the usual values taken by the data.
Packit 995986
   
Packit 995986
   Note that these are only hints. The host may ignore them and the
Packit 995986
   plugin must not assume that data supplied to it is meaningful. If
Packit 995986
   the plugin receives invalid input data it is expected to continue
Packit 995986
   to run without failure and, where possible, produce a sensible
Packit 995986
   output (e.g. a high-pass filter given a negative cutoff frequency
Packit 995986
   might switch to an all-pass mode).
Packit 995986
    
Packit 995986
   Hints are meaningful for all input and output ports but hints for
Packit 995986
   input control ports are expected to be particularly useful.
Packit 995986
   
Packit 995986
   More hint information is encapsulated in the
Packit 995986
   LADSPA_PortRangeHintDescriptor type which is assembled by ORing
Packit 995986
   individual hint types together. Hints may require further
Packit 995986
   LowerBound and UpperBound information.
Packit 995986
Packit 995986
   All the hint information for a particular port is aggregated in the
Packit 995986
   LADSPA_PortRangeHint structure. */
Packit 995986
Packit 995986
typedef int LADSPA_PortRangeHintDescriptor;
Packit 995986
Packit 995986
/* Hint LADSPA_HINT_BOUNDED_BELOW indicates that the LowerBound field
Packit 995986
   of the LADSPA_PortRangeHint should be considered meaningful. The
Packit 995986
   value in this field should be considered the (inclusive) lower
Packit 995986
   bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also
Packit 995986
   specified then the value of LowerBound should be multiplied by the
Packit 995986
   sample rate. */
Packit 995986
#define LADSPA_HINT_BOUNDED_BELOW   0x1
Packit 995986
Packit 995986
/* Hint LADSPA_HINT_BOUNDED_ABOVE indicates that the UpperBound field
Packit 995986
   of the LADSPA_PortRangeHint should be considered meaningful. The
Packit 995986
   value in this field should be considered the (inclusive) upper
Packit 995986
   bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also
Packit 995986
   specified then the value of UpperBound should be multiplied by the
Packit 995986
   sample rate. */
Packit 995986
#define LADSPA_HINT_BOUNDED_ABOVE   0x2
Packit 995986
Packit 995986
/* Hint LADSPA_HINT_TOGGLED indicates that the data item should be
Packit 995986
   considered a Boolean toggle. Data less than or equal to zero should
Packit 995986
   be considered `off' or `false,' and data above zero should be
Packit 995986
   considered `on' or `true.' LADSPA_HINT_TOGGLED may not be used in
Packit 995986
   conjunction with any other hint except LADSPA_HINT_DEFAULT_0 or
Packit 995986
   LADSPA_HINT_DEFAULT_1. */
Packit 995986
#define LADSPA_HINT_TOGGLED         0x4
Packit 995986
Packit 995986
/* Hint LADSPA_HINT_SAMPLE_RATE indicates that any bounds specified
Packit 995986
   should be interpreted as multiples of the sample rate. For
Packit 995986
   instance, a frequency range from 0Hz to the Nyquist frequency (half
Packit 995986
   the sample rate) could be requested by this hint in conjunction
Packit 995986
   with LowerBound = 0 and UpperBound = 0.5. Hosts that support bounds
Packit 995986
   at all must support this hint to retain meaning. */
Packit 995986
#define LADSPA_HINT_SAMPLE_RATE     0x8
Packit 995986
Packit 995986
/* Hint LADSPA_HINT_LOGARITHMIC indicates that it is likely that the
Packit 995986
   user will find it more intuitive to view values using a logarithmic
Packit 995986
   scale. This is particularly useful for frequencies and gains. */
Packit 995986
#define LADSPA_HINT_LOGARITHMIC     0x10
Packit 995986
Packit 995986
/* Hint LADSPA_HINT_INTEGER indicates that a user interface would
Packit 995986
   probably wish to provide a stepped control taking only integer
Packit 995986
   values. Any bounds set should be slightly wider than the actual
Packit 995986
   integer range required to avoid floating point rounding errors. For
Packit 995986
   instance, the integer set {0,1,2,3} might be described as [-0.1,
Packit 995986
   3.1]. */
Packit 995986
#define LADSPA_HINT_INTEGER         0x20
Packit 995986
Packit 995986
/* The various LADSPA_HINT_HAS_DEFAULT_* hints indicate a `normal'
Packit 995986
   value for the port that is sensible as a default. For instance,
Packit 995986
   this value is suitable for use as an initial value in a user
Packit 995986
   interface or as a value the host might assign to a control port
Packit 995986
   when the user has not provided one. Defaults are encoded using a
Packit 995986
   mask so only one default may be specified for a port. Some of the
Packit 995986
   hints make use of lower and upper bounds, in which case the
Packit 995986
   relevant bound or bounds must be available and
Packit 995986
   LADSPA_HINT_SAMPLE_RATE must be applied as usual. The resulting
Packit 995986
   default must be rounded if LADSPA_HINT_INTEGER is present. Default
Packit 995986
   values were introduced in LADSPA v1.1. */
Packit 995986
#define LADSPA_HINT_DEFAULT_MASK    0x3C0
Packit 995986
Packit 995986
/* This default values indicates that no default is provided. */
Packit 995986
#define LADSPA_HINT_DEFAULT_NONE    0x0
Packit 995986
Packit 995986
/* This default hint indicates that the suggested lower bound for the
Packit 995986
   port should be used. */
Packit 995986
#define LADSPA_HINT_DEFAULT_MINIMUM 0x40
Packit 995986
Packit 995986
/* This default hint indicates that a low value between the suggested
Packit 995986
   lower and upper bounds should be chosen. For ports with
Packit 995986
   LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.75 +
Packit 995986
   log(upper) * 0.25). Otherwise, this should be (lower * 0.75 + upper
Packit 995986
   * 0.25). */
Packit 995986
#define LADSPA_HINT_DEFAULT_LOW     0x80
Packit 995986
Packit 995986
/* This default hint indicates that a middle value between the
Packit 995986
   suggested lower and upper bounds should be chosen. For ports with
Packit 995986
   LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.5 +
Packit 995986
   log(upper) * 0.5). Otherwise, this should be (lower * 0.5 + upper *
Packit 995986
   0.5). */
Packit 995986
#define LADSPA_HINT_DEFAULT_MIDDLE  0xC0
Packit 995986
Packit 995986
/* This default hint indicates that a high value between the suggested
Packit 995986
   lower and upper bounds should be chosen. For ports with
Packit 995986
   LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.25 +
Packit 995986
   log(upper) * 0.75). Otherwise, this should be (lower * 0.25 + upper
Packit 995986
   * 0.75). */
Packit 995986
#define LADSPA_HINT_DEFAULT_HIGH    0x100
Packit 995986
Packit 995986
/* This default hint indicates that the suggested upper bound for the
Packit 995986
   port should be used. */
Packit 995986
#define LADSPA_HINT_DEFAULT_MAXIMUM 0x140
Packit 995986
Packit 995986
/* This default hint indicates that the number 0 should be used. Note
Packit 995986
   that this default may be used in conjunction with
Packit 995986
   LADSPA_HINT_TOGGLED. */
Packit 995986
#define LADSPA_HINT_DEFAULT_0       0x200
Packit 995986
Packit 995986
/* This default hint indicates that the number 1 should be used. Note
Packit 995986
   that this default may be used in conjunction with
Packit 995986
   LADSPA_HINT_TOGGLED. */
Packit 995986
#define LADSPA_HINT_DEFAULT_1       0x240
Packit 995986
Packit 995986
/* This default hint indicates that the number 100 should be used. */
Packit 995986
#define LADSPA_HINT_DEFAULT_100     0x280
Packit 995986
Packit 995986
/* This default hint indicates that the Hz frequency of `concert A'
Packit 995986
   should be used. This will be 440 unless the host uses an unusual
Packit 995986
   tuning convention, in which case it may be within a few Hz. */
Packit 995986
#define LADSPA_HINT_DEFAULT_440     0x2C0
Packit 995986
Packit 995986
#define LADSPA_IS_HINT_BOUNDED_BELOW(x)   ((x) & LADSPA_HINT_BOUNDED_BELOW)
Packit 995986
#define LADSPA_IS_HINT_BOUNDED_ABOVE(x)   ((x) & LADSPA_HINT_BOUNDED_ABOVE)
Packit 995986
#define LADSPA_IS_HINT_TOGGLED(x)         ((x) & LADSPA_HINT_TOGGLED)
Packit 995986
#define LADSPA_IS_HINT_SAMPLE_RATE(x)     ((x) & LADSPA_HINT_SAMPLE_RATE)
Packit 995986
#define LADSPA_IS_HINT_LOGARITHMIC(x)     ((x) & LADSPA_HINT_LOGARITHMIC)
Packit 995986
#define LADSPA_IS_HINT_INTEGER(x)         ((x) & LADSPA_HINT_INTEGER)
Packit 995986
Packit 995986
#define LADSPA_IS_HINT_HAS_DEFAULT(x)     ((x) & LADSPA_HINT_DEFAULT_MASK)
Packit 995986
#define LADSPA_IS_HINT_DEFAULT_MINIMUM(x) (((x) & LADSPA_HINT_DEFAULT_MASK)   \
Packit 995986
                                           == LADSPA_HINT_DEFAULT_MINIMUM)
Packit 995986
#define LADSPA_IS_HINT_DEFAULT_LOW(x)     (((x) & LADSPA_HINT_DEFAULT_MASK)   \
Packit 995986
                                           == LADSPA_HINT_DEFAULT_LOW)
Packit 995986
#define LADSPA_IS_HINT_DEFAULT_MIDDLE(x)  (((x) & LADSPA_HINT_DEFAULT_MASK)   \
Packit 995986
                                           == LADSPA_HINT_DEFAULT_MIDDLE)
Packit 995986
#define LADSPA_IS_HINT_DEFAULT_HIGH(x)    (((x) & LADSPA_HINT_DEFAULT_MASK)   \
Packit 995986
                                           == LADSPA_HINT_DEFAULT_HIGH)
Packit 995986
#define LADSPA_IS_HINT_DEFAULT_MAXIMUM(x) (((x) & LADSPA_HINT_DEFAULT_MASK)   \
Packit 995986
                                           == LADSPA_HINT_DEFAULT_MAXIMUM)
Packit 995986
#define LADSPA_IS_HINT_DEFAULT_0(x)       (((x) & LADSPA_HINT_DEFAULT_MASK)   \
Packit 995986
                                           == LADSPA_HINT_DEFAULT_0)
Packit 995986
#define LADSPA_IS_HINT_DEFAULT_1(x)       (((x) & LADSPA_HINT_DEFAULT_MASK)   \
Packit 995986
                                           == LADSPA_HINT_DEFAULT_1)
Packit 995986
#define LADSPA_IS_HINT_DEFAULT_100(x)     (((x) & LADSPA_HINT_DEFAULT_MASK)   \
Packit 995986
                                           == LADSPA_HINT_DEFAULT_100)
Packit 995986
#define LADSPA_IS_HINT_DEFAULT_440(x)     (((x) & LADSPA_HINT_DEFAULT_MASK)   \
Packit 995986
                                            == LADSPA_HINT_DEFAULT_440)
Packit 995986
Packit 995986
typedef struct _LADSPA_PortRangeHint {
Packit 995986
Packit 995986
  /* Hints about the port. */
Packit 995986
  LADSPA_PortRangeHintDescriptor HintDescriptor;
Packit 995986
Packit 995986
  /* Meaningful when hint LADSPA_HINT_BOUNDED_BELOW is active. When
Packit 995986
     LADSPA_HINT_SAMPLE_RATE is also active then this value should be
Packit 995986
     multiplied by the relevant sample rate. */
Packit 995986
  LADSPA_Data LowerBound;
Packit 995986
Packit 995986
  /* Meaningful when hint LADSPA_HINT_BOUNDED_ABOVE is active. When
Packit 995986
     LADSPA_HINT_SAMPLE_RATE is also active then this value should be
Packit 995986
     multiplied by the relevant sample rate. */
Packit 995986
  LADSPA_Data UpperBound;
Packit 995986
Packit 995986
} LADSPA_PortRangeHint;
Packit 995986
Packit 995986
/*****************************************************************************/
Packit 995986
Packit 995986
/* Plugin Handles: 
Packit 995986
Packit 995986
   This plugin handle indicates a particular instance of the plugin
Packit 995986
   concerned. It is valid to compare this to NULL (0 for C++) but
Packit 995986
   otherwise the host should not attempt to interpret it. The plugin
Packit 995986
   may use it to reference internal instance data. */
Packit 995986
Packit 995986
typedef void * LADSPA_Handle;
Packit 995986
Packit 995986
/*****************************************************************************/
Packit 995986
Packit 995986
/* Descriptor for a Type of Plugin: 
Packit 995986
Packit 995986
   This structure is used to describe a plugin type. It provides a
Packit 995986
   number of functions to examine the type, instantiate it, link it to
Packit 995986
   buffers and workspaces and to run it. */
Packit 995986
Packit 995986
typedef struct _LADSPA_Descriptor { 
Packit 995986
Packit 995986
  /* This numeric identifier indicates the plugin type
Packit 995986
     uniquely. Plugin programmers may reserve ranges of IDs from a
Packit 995986
     central body to avoid clashes. Hosts may assume that IDs are
Packit 995986
     below 0x1000000. */
Packit 995986
  unsigned long UniqueID;
Packit 995986
Packit 995986
  /* This identifier can be used as a unique, case-sensitive
Packit 995986
     identifier for the plugin type within the plugin file. Plugin
Packit 995986
     types should be identified by file and label rather than by index
Packit 995986
     or plugin name, which may be changed in new plugin
Packit 995986
     versions. Labels must not contain white-space characters. */
Packit 995986
  const char * Label;
Packit 995986
Packit 995986
  /* This indicates a number of properties of the plugin. */
Packit 995986
  LADSPA_Properties Properties;
Packit 995986
Packit 995986
  /* This member points to the null-terminated name of the plugin
Packit 995986
     (e.g. "Sine Oscillator"). */
Packit 995986
  const char * Name;
Packit 995986
Packit 995986
  /* This member points to the null-terminated string indicating the
Packit 995986
     maker of the plugin. This can be an empty string but not NULL. */
Packit 995986
  const char * Maker;
Packit 995986
Packit 995986
  /* This member points to the null-terminated string indicating any
Packit 995986
     copyright applying to the plugin. If no Copyright applies the
Packit 995986
     string "None" should be used. */
Packit 995986
  const char * Copyright;
Packit 995986
Packit 995986
  /* This indicates the number of ports (input AND output) present on
Packit 995986
     the plugin. */
Packit 995986
  unsigned long PortCount;
Packit 995986
Packit 995986
  /* This member indicates an array of port descriptors. Valid indices
Packit 995986
     vary from 0 to PortCount-1. */
Packit 995986
  const LADSPA_PortDescriptor * PortDescriptors;
Packit 995986
Packit 995986
  /* This member indicates an array of null-terminated strings
Packit 995986
     describing ports (e.g. "Frequency (Hz)"). Valid indices vary from
Packit 995986
     0 to PortCount-1. */
Packit 995986
  const char * const * PortNames;
Packit 995986
Packit 995986
  /* This member indicates an array of range hints for each port (see
Packit 995986
     above). Valid indices vary from 0 to PortCount-1. */
Packit 995986
  const LADSPA_PortRangeHint * PortRangeHints;
Packit 995986
Packit 995986
  /* This may be used by the plugin developer to pass any custom
Packit 995986
     implementation data into an instantiate call. It must not be used
Packit 995986
     or interpreted by the host. It is expected that most plugin
Packit 995986
     writers will not use this facility as LADSPA_Handle should be
Packit 995986
     used to hold instance data. */
Packit 995986
  void * ImplementationData;
Packit 995986
Packit 995986
  /* This member is a function pointer that instantiates a plugin. A
Packit 995986
     handle is returned indicating the new plugin instance. The
Packit 995986
     instantiation function accepts a sample rate as a parameter. The
Packit 995986
     plugin descriptor from which this instantiate function was found
Packit 995986
     must also be passed. This function must return NULL if
Packit 995986
     instantiation fails. 
Packit 995986
Packit 995986
     Note that instance initialisation should generally occur in
Packit 995986
     activate() rather than here. */
Packit 995986
  LADSPA_Handle (*instantiate)(const struct _LADSPA_Descriptor * Descriptor,
Packit 995986
                               unsigned long                     SampleRate);
Packit 995986
Packit 995986
  /* This member is a function pointer that connects a port on an
Packit 995986
     instantiated plugin to a memory location at which a block of data
Packit 995986
     for the port will be read/written. The data location is expected
Packit 995986
     to be an array of LADSPA_Data for audio ports or a single
Packit 995986
     LADSPA_Data value for control ports. Memory issues will be
Packit 995986
     managed by the host. The plugin must read/write the data at these
Packit 995986
     locations every time run() or run_adding() is called and the data
Packit 995986
     present at the time of this connection call should not be
Packit 995986
     considered meaningful.
Packit 995986
Packit 995986
     connect_port() may be called more than once for a plugin instance
Packit 995986
     to allow the host to change the buffers that the plugin is
Packit 995986
     reading or writing. These calls may be made before or after
Packit 995986
     activate() or deactivate() calls.
Packit 995986
Packit 995986
     connect_port() must be called at least once for each port before
Packit 995986
     run() or run_adding() is called. When working with blocks of
Packit 995986
     LADSPA_Data the plugin should pay careful attention to the block
Packit 995986
     size passed to the run function as the block allocated may only
Packit 995986
     just be large enough to contain the block of samples.
Packit 995986
Packit 995986
     Plugin writers should be aware that the host may elect to use the
Packit 995986
     same buffer for more than one port and even use the same buffer
Packit 995986
     for both input and output (see LADSPA_PROPERTY_INPLACE_BROKEN).
Packit 995986
     However, overlapped buffers or use of a single buffer for both
Packit 995986
     audio and control data may result in unexpected behaviour. */
Packit 995986
   void (*connect_port)(LADSPA_Handle Instance,
Packit 995986
                        unsigned long Port,
Packit 995986
                        LADSPA_Data * DataLocation);
Packit 995986
Packit 995986
  /* This member is a function pointer that initialises a plugin
Packit 995986
     instance and activates it for use. This is separated from
Packit 995986
     instantiate() to aid real-time support and so that hosts can
Packit 995986
     reinitialise a plugin instance by calling deactivate() and then
Packit 995986
     activate(). In this case the plugin instance must reset all state
Packit 995986
     information dependent on the history of the plugin instance
Packit 995986
     except for any data locations provided by connect_port() and any
Packit 995986
     gain set by set_run_adding_gain(). If there is nothing for
Packit 995986
     activate() to do then the plugin writer may provide a NULL rather
Packit 995986
     than an empty function.
Packit 995986
Packit 995986
     When present, hosts must call this function once before run() (or
Packit 995986
     run_adding()) is called for the first time. This call should be
Packit 995986
     made as close to the run() call as possible and indicates to
Packit 995986
     real-time plugins that they are now live. Plugins should not rely
Packit 995986
     on a prompt call to run() after activate(). activate() may not be
Packit 995986
     called again unless deactivate() is called first. Note that
Packit 995986
     connect_port() may be called before or after a call to
Packit 995986
     activate(). */
Packit 995986
  void (*activate)(LADSPA_Handle Instance);
Packit 995986
Packit 995986
  /* This method is a function pointer that runs an instance of a
Packit 995986
     plugin for a block. Two parameters are required: the first is a
Packit 995986
     handle to the particular instance to be run and the second
Packit 995986
     indicates the block size (in samples) for which the plugin
Packit 995986
     instance may run.
Packit 995986
Packit 995986
     Note that if an activate() function exists then it must be called
Packit 995986
     before run() or run_adding(). If deactivate() is called for a
Packit 995986
     plugin instance then the plugin instance may not be reused until
Packit 995986
     activate() has been called again.
Packit 995986
Packit 995986
     If the plugin has the property LADSPA_PROPERTY_HARD_RT_CAPABLE
Packit 995986
     then there are various things that the plugin should not do
Packit 995986
     within the run() or run_adding() functions (see above). */
Packit 995986
  void (*run)(LADSPA_Handle Instance,
Packit 995986
              unsigned long SampleCount);
Packit 995986
Packit 995986
  /* This method is a function pointer that runs an instance of a
Packit 995986
     plugin for a block. This has identical behaviour to run() except
Packit 995986
     in the way data is output from the plugin. When run() is used,
Packit 995986
     values are written directly to the memory areas associated with
Packit 995986
     the output ports. However when run_adding() is called, values
Packit 995986
     must be added to the values already present in the memory
Packit 995986
     areas. Furthermore, output values written must be scaled by the
Packit 995986
     current gain set by set_run_adding_gain() (see below) before
Packit 995986
     addition.
Packit 995986
Packit 995986
     run_adding() is optional. When it is not provided by a plugin,
Packit 995986
     this function pointer must be set to NULL. When it is provided,
Packit 995986
     the function set_run_adding_gain() must be provided also. */
Packit 995986
  void (*run_adding)(LADSPA_Handle Instance,
Packit 995986
                     unsigned long SampleCount);
Packit 995986
Packit 995986
  /* This method is a function pointer that sets the output gain for
Packit 995986
     use when run_adding() is called (see above). If this function is
Packit 995986
     never called the gain is assumed to default to 1. Gain
Packit 995986
     information should be retained when activate() or deactivate()
Packit 995986
     are called.
Packit 995986
Packit 995986
     This function should be provided by the plugin if and only if the
Packit 995986
     run_adding() function is provided. When it is absent this
Packit 995986
     function pointer must be set to NULL. */
Packit 995986
  void (*set_run_adding_gain)(LADSPA_Handle Instance,
Packit 995986
                              LADSPA_Data   Gain);
Packit 995986
Packit 995986
  /* This is the counterpart to activate() (see above). If there is
Packit 995986
     nothing for deactivate() to do then the plugin writer may provide
Packit 995986
     a NULL rather than an empty function.
Packit 995986
Packit 995986
     Hosts must deactivate all activated units after they have been
Packit 995986
     run() (or run_adding()) for the last time. This call should be
Packit 995986
     made as close to the last run() call as possible and indicates to
Packit 995986
     real-time plugins that they are no longer live. Plugins should
Packit 995986
     not rely on prompt deactivation. Note that connect_port() may be
Packit 995986
     called before or after a call to deactivate().
Packit 995986
Packit 995986
     Deactivation is not similar to pausing as the plugin instance
Packit 995986
     will be reinitialised when activate() is called to reuse it. */
Packit 995986
  void (*deactivate)(LADSPA_Handle Instance);
Packit 995986
Packit 995986
  /* Once an instance of a plugin has been finished with it can be
Packit 995986
     deleted using the following function. The instance handle passed
Packit 995986
     ceases to be valid after this call.
Packit 995986
  
Packit 995986
     If activate() was called for a plugin instance then a
Packit 995986
     corresponding call to deactivate() must be made before cleanup()
Packit 995986
     is called. */
Packit 995986
  void (*cleanup)(LADSPA_Handle Instance);
Packit 995986
Packit 995986
} LADSPA_Descriptor;
Packit 995986
Packit 995986
/**********************************************************************/
Packit 995986
Packit 995986
/* Accessing a Plugin: */
Packit 995986
Packit 995986
/* The exact mechanism by which plugins are loaded is host-dependent,
Packit 995986
   however all most hosts will need to know is the name of shared
Packit 995986
   object file containing the plugin types. To allow multiple hosts to
Packit 995986
   share plugin types, hosts may wish to check for environment
Packit 995986
   variable LADSPA_PATH. If present, this should contain a
Packit 995986
   colon-separated path indicating directories that should be searched
Packit 995986
   (in order) when loading plugin types.
Packit 995986
Packit 995986
   A plugin programmer must include a function called
Packit 995986
   "ladspa_descriptor" with the following function prototype within
Packit 995986
   the shared object file. This function will have C-style linkage (if
Packit 995986
   you are using C++ this is taken care of by the `extern "C"' clause
Packit 995986
   at the top of the file).
Packit 995986
Packit 995986
   A host will find the plugin shared object file by one means or
Packit 995986
   another, find the ladspa_descriptor() function, call it, and
Packit 995986
   proceed from there.
Packit 995986
Packit 995986
   Plugin types are accessed by index (not ID) using values from 0
Packit 995986
   upwards. Out of range indexes must result in this function
Packit 995986
   returning NULL, so the plugin count can be determined by checking
Packit 995986
   for the least index that results in NULL being returned. */
Packit 995986
Packit 995986
const LADSPA_Descriptor * ladspa_descriptor(unsigned long Index);
Packit 995986
Packit 995986
/* Datatype corresponding to the ladspa_descriptor() function. */
Packit 995986
typedef const LADSPA_Descriptor * 
Packit 995986
(*LADSPA_Descriptor_Function)(unsigned long Index);
Packit 995986
Packit 995986
/**********************************************************************/
Packit 995986
Packit 995986
#ifdef __cplusplus
Packit 995986
}
Packit 995986
#endif
Packit 995986
Packit 995986
#endif /* LADSPA_INCLUDED */
Packit 995986
Packit 995986
/* EOF */