/* ladspa-2.h
 *
 * Linux Audio Developer's Simple Plugin API Version 2.0[provisional,
 * LGPL].  Copyright (C) 2000-2002 Richard W.E. Furse, Paul
 * Barton-Davis, Stefan Westerfeld, Steve Harris.
 * 
 * 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 LADSPA2_INCLUDED
#define LADSPA2_INCLUDED

#ifdef __cplusplus
extern "C" {
#endif


/* ************************************************************************* */

/* Overview: 
 *
 * There are 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.
 *
 * 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 floats, allowing a block of audio
 * to be processed by the plugin in a single pass. Control data is
 * communicated using single float values. Control data has a
 * single value at the start of a call to the 'run()' 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.
 */

/* ************************************************************************* */

    
/** Plugin Handle.
 *
 * This plugin handle indicates a particular instance of the plugin
 * concerned. It is valid to compare this to NULL (0 for C++) but
 * otherwise the host should not attempt to interpret it. The plugin
 * may use it to reference internal instance data. */
typedef void * LADSPA_Handle;


/* ************************************************************************* */


/** Descriptor for a Type of Plugin.
 * 
 * This structure is used to describe a plugin type. It provides a
 * number of functions to examine the type, instantiate it, link it to
 * buffers and workspaces and to run it. */
typedef struct _LADSPA_Descriptor { 

  /** A globally unique, case-sensitive identifier for this plugin type.
   * All plugins with the same URI MUST be compatible in terms of
   * 'port signature' (eg. in most cases a version number should be included) */
  const char * URI;

  /** Function pointer that instantiates a plugin.
   *
   * A handle is returned indicating the new plugin instance. The
   * instantiation function accepts a sample rate as a parameter. The
   * plugin descriptor from which this instantiate function was found
   * must also be passed. This function must return NULL if
   * instantiation fails. 
   *
   * The BundlePath parameter is a string of the path to the plugin's
   * .ladspa2 bundle directory, it MUST not include the trailing /.
   *
   * HostFeatures is a NULL terminated array of the URIs of the LADSPA
   * features that the host supports. Plugins may refuse to instantiate
   * if required features are not found here.
   *
   * Note that instance initialisation should generally occur in
   * activate() rather than here. */
  LADSPA_Handle (*instantiate)(const struct _LADSPA_Descriptor * Descriptor,
                               unsigned long                     SampleRate,
                               const char *                      BundlePath,
                               const char **                     HostFeatures);

  /** Function pointer that connects a port on a plugin instance to a memory
   * location where the block of data for the port will be read/written.
   *
   * The data location is expected
   * to be an array of void * (typically float *) for audio ports or a
   * single void * value for control ports. Memory issues will be
   * managed by the host. The plugin must read/write the data at these
   * locations every time run() is called and the data present at the time of
   * this connection call should not be considered meaningful.
   *
   * connect_port() may be called more than once for a plugin instance
   * to allow the host to change the buffers that the plugin is
   * reading or writing. These calls may be made before or after
   * activate() or deactivate() calls.
   *
   * connect_port() must be called at least once for each port before
   * run() is called. When working with blocks of void * the plugin should pay
   * careful attention to the block size passed to the run function as the
   * block allocated may only just be large enough to contain the block of
   * samples.
   *
   * Plugin writers should be aware that the host may elect to use the
   * same buffer for more than one port and even use the same buffer
   * for both input and output (see LADSPA_PROPERTY_INPLACE_BROKEN).
   * However, overlapped buffers or use of a single buffer for both
   * audio and control data may result in unexpected behaviour. */
  void (*connect_port)(LADSPA_Handle Instance,
                       unsigned long Port,
                       void *        DataLocation);

  /** Function pointer that initialises a plugin instance
   * and activates it for use.
   *
   * This is separated from instantiate() to aid real-time support and so that
   * hosts can reinitialise a plugin instance by calling deactivate() and then
   * activate(). In this case the plugin instance must reset all state
   * information dependent on the history of the plugin instance
   * except for any data locations provided by connect_port(). If there is
   * nothing for activate() to do then the plugin writer may provide a NULL
   * rather than an empty function.
   *
   * When present, hosts must call this function once before run() is called
   * for the first time. This call should be made as close to the run() call as
   * possible and indicates to real-time plugins that they are now live.
   * Plugins should not rely on a prompt call to run() after activate().
   * activate() may not be called again unless deactivate() is called first.
   * Note that connect_port() may be called before or after a call to
   * activate(). */
  void (*activate)(LADSPA_Handle Instance);

  /** Function pointer that runs a plugin instance for a block.
   *
   * Two parameters are required: the first is a handle to the particular
   * instance to be run and the second indicates the block size (in samples)
   * for which the plugin * instance may run.
   *
   * Note that if an activate() function exists then it must be called before
   * run(). If deactivate() is called for a plugin instance then the plugin
   * instance may not be reused until activate() has been called again.
   *
   * If the plugin has the property LADSPA_PROPERTY_HARD_RT_CAPABLE then there
   * are various things that the plugin should not do within the run()
   * function (see above). */
  void (*run)(LADSPA_Handle Instance,
              unsigned long SampleCount);

  /** This is the counterpart to activate() (see above). If there is
   * nothing for deactivate() to do then the plugin writer may provide
   * a NULL rather than an empty function.
   *
   * Hosts must deactivate all activated units after they have been
   * run() for the last time. This call should be made as close to the last
   * run() call as possible and indicates to real-time plugins that they are no
   * longer live. Plugins should not rely on prompt deactivation. Note that
   * connect_port() may be called before or after a call to deactivate().
   *
   * Deactivation is not similar to pausing as the plugin instance
   * will be reinitialised when activate() is called to reuse it. */
  void (*deactivate)(LADSPA_Handle Instance);

  /** Once an instance of a plugin has been finished with it can be
   * deleted using this function. The instance handle passed
   * ceases to be valid after this call.
   * 
   * If activate() was called for a plugin instance then a
   * corresponding call to deactivate() must be made before cleanup()
   * is called. */
  void (*cleanup)(LADSPA_Handle Instance);

} LADSPA_Descriptor;


/* ****************************************************************** */


/** Accessing a Plugin:
 *
 * The exact mechanism by which plugins are loaded is host-dependent,
 * however all most hosts will need to know is the name of shared
 * object file containing the plugin types. To allow multiple hosts to
 * share plugin types, hosts may wish to check for environment
 * variable LADSPA_PATH. If present, this should contain a
 * colon-separated path indicating directories that should be searched
 * (in order) when loading plugin types.
 *
 * A plugin programmer must include a function called
 * "ladspa_descriptor" with the following function prototype within
 * the shared object file. This function will have C-style linkage (if
 * you are using C++ this is taken care of by the 'extern "C"' clause
 * at the top of the file).
 *
 * A host will find the plugin shared object file by one means or
 * another, find the ladspa_descriptor() function, call it, and
 * proceed from there.
 *
 * Plugin types are accessed by index (not ID) using values from 0
 * upwards. Out of range indexes must result in this function
 * returning NULL, so the plugin count can be determined by checking
 * for the least index that results in NULL being returned. */
const LADSPA_Descriptor * ladspa_descriptor(unsigned long Index);


/** Datatype corresponding to the ladspa_descriptor() function. */
typedef const LADSPA_Descriptor * 
(*LADSPA_Descriptor_Function)(unsigned long Index);


/* ******************************************************************** */


#ifdef __cplusplus
}
#endif

#endif /* LADSPA2_INCLUDED */