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