--- ladspa.h.orig Fri Mar 5 15:21:14 2004 +++ ladspa.h Wed Apr 14 13:47:21 2004 @@ -4,6 +4,10 @@ LGPL]. Copyright (C) 2000-2002 Richard W.E. Furse, Paul Barton-Davis, Stefan Westerfeld. + Ladspa Audio DSP API Version 1.2 (provisional, LGPL) + Copyright (C) 2004 Steve Harris, Matthias Nagorni, Fons Adriaensen, + Tom Szilagyi, Taybin Rutkin, Paul Davis, Tim Goetze. + 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 @@ -19,8 +23,10 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. */ -#ifndef LADSPA_INCLUDED -#define LADSPA_INCLUDED +#ifndef LADSPA_VERSION +#define LADSPA_VERSION "1.2" +#define LADSPA_VERSION_MAJOR 1 +#define LADSPA_VERSION_MINOR 2 #ifdef __cplusplus extern "C" { @@ -127,9 +133,16 @@ A and B. */ #define LADSPA_PROPERTY_HARD_RT_CAPABLE 0x4 +/* Property LADSPA_PROPERTY_HAVE_VERSION indicates that the plugin is + aware of API versioning, and that it is implementing v1.2 or above. + The v1.2 API extends the plugin descriptor structure with a dedicated + API version field and extended plugin port info. */ +#define LADSPA_PROPERTY_HAVE_VERSION 0x8 + #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) +#define LADSPA_HAS_VERSION(x) ((x) & LADSPA_PROPERTY_HAVE_VERSION) /*****************************************************************************/ @@ -250,7 +263,15 @@ 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. */ + values were introduced in LADSPA v1.1. + + Please note that the use of LADSPA_HINT_DEFAULT_* is deprecated + since v1.2. For a grace period, hosts should try to evaluate + the PortInfo member of the v1.2 plugin descriptor prior to falling + back to the v1.1 hint mechanism. Plugins implementing v1.2 should + both specify their precise idea of the default value through + the new PortInfo method as well as give older host programs a rough + idea through the v1.1 default hints. */ #define LADSPA_HINT_DEFAULT_MASK 0x3C0 /* This default values indicates that no default is provided. */ @@ -349,6 +370,120 @@ /*****************************************************************************/ +/* v1.2 Hints: + + The following hints were introduced with v1.2 of the API. */ + +/* Hint LADSPA_HINT_NULL_OK indicates that the plugin supports a NULL value + passed as data location to the connect_port() method. Host authors must + not assume a port hinted NULL_OK is connected to the NULL data location + by default, i.e. an explicit connect_port (NULL) is still required. */ +#define LADSPA_HINT_NULL_OK 0x400 + +/* Hint LADSPA_HINT_TRIGGER indicates that the signal passed through the + port is intended to trigger one-shot processes such as sample playback, + start of an envelope, restart of a wavecycle etc. If the port is an + input, a non-zero value will cause the plugin to start such a process. + Please note that the port value range needs not necessarily include + zero, the value which indicates 'no trigger'. The default value for the + port, specified elsewhere, indicates a sensible 'trigger' level and + should not be zero. The use of this hint precludes the use of + LADSPA_HINT_MOMENTARY. */ +#define LADSPA_HINT_TRIGGER 0x800 + +/* Hint LADSPA_HINT_MOMENTARY indicates that the signal passed through the + port corresponds to gate CV signals in the analog world. A simple + example for such a signal source is a pushbutton: the port value is set + to a non-zero value while the button is pressed, and returns to zero when + the button is released. Please note that the port value range needs not + necessarily include zero, the value which indicates a 'low' signal. The + default value for the port, specified elsewhere, indicates a sensible + 'high' level and should not be zero. The use of this hint precludes the + use of LADSPA_HINT_TRIGGER. */ +#define LADSPA_HINT_MOMENTARY 0x1000 + +/* Hint LADSPA_HINT_GROUP indicates that the port starts a 'group' of + ports which are related in meaning. The group comprises all following + ports until the next port hinted 'GROUP'. For example, a parametric + equalizer plugin can compose groups of center frequency, width and gain + for each of the bands provided. */ +#define LADSPA_HINT_GROUP 0x2000 + +#define LADSPA_IS_HINT_NULL_OK(x) ((x) & LADSPA_HINT_NULL_OK) +#define LADSPA_IS_HINT_TRIGGER(x) ((x) & LADSPA_HINT_TRIGGER) +#define LADSPA_IS_HINT_MOMENTARY(x) ((x) & LADSPA_HINT_MOMENTARY) +#define LADSPA_IS_HINT_GROUP(x) ((x) & LADSPA_HINT_GROUP) + +/*****************************************************************************/ + +/* Port Value Enumerations: + + Since v1.2, plugins can associate control port values of particular + interest with labels by providing arrays of the following structure tied + to specific ports. For example, a port used to choose a waveform may + benefit from indicating: 0 -> "sin", 1 -> "tri", 2 -> "saw" etc. + Plugin authors should note that a host may choose to override or ignore + this information. */ + +typedef struct _LADSPA_PortValueEnum { + + /* The label to associate with the value following. A NULL value + indicates the end of the enumeration array. */ + const char * Label; + + /* The value to be associated with the label. */ + const LADSPA_Data Value; + +} LADSPA_PortValueEnum; + + +/* Extended Port Info Structure: + + Plugins following v1.2 or above provide more detail about their ports + through the following structure. */ + +typedef struct _LADSPA_PortInfo { + + /* The default value for the port, to be used by the host if it does not + choose to retrieve a saved state from a preset or other persistent + storage. */ + const LADSPA_Data Default; + + /* The unit of port values. Plugin authors should follow the international + conventions, in particular the SI, when choosing unit names. Some + examples: "Hz" for frequency, "dB" for decibels, "ms" for milliseconds. + A plugin may choose to set this member to NULL to indicate a + dimensionless parameter. */ + const char * Unit; + + /* Additional information about particularly noteworthy values can be + communicated to the host through this array of LADSPA_PortValueEnum + structures. A plugin may choose to set this member to NULL if no such + information needs to be communicated. */ + const LADSPA_PortValueEnum * ValueEnum; + +} LADSPA_PortInfo; + +/*****************************************************************************/ + +/* Well-Known Ports: + + To communicate common properties, plugins can define ports using the + well-known port name convention. */ + +/* The "_latency" port always indicates a control output port. The value + the plugin writes to this port is the delay, in 1 / SampleRate time + units, the plugin imposes on the signals it processes. + + Plugin authors should assume that hosts that care about plugin latency + will read the latency value as often as they deem necessary. However, + host authors should assume that the port value is only valid after a + legal call to run() or run_adding() (i.e. the plugin is active when + run() or run_adding() is called). */ +#define LADSPA_LATENCY_PORT_NAME "_latency" + +/*****************************************************************************/ + /* Plugin Handles: This plugin handle indicates a particular instance of the plugin @@ -406,7 +541,7 @@ const LADSPA_PortDescriptor * PortDescriptors; /* This member indicates an array of null-terminated strings - describing ports (e.g. "Frequency (Hz)"). Valid indices vary from + describing ports (e.g. "Frequency"). Valid indices vary from 0 to PortCount-1. */ const char * const * PortNames; @@ -481,7 +616,11 @@ 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(). */ + activate(). + + Host authors should note that plugins implementing control value + smoothing benefit from a valid set of control values at the time + that activate() is called. */ void (*activate)(LADSPA_Handle Instance); /* This method is a function pointer that runs an instance of a @@ -553,6 +692,25 @@ is called. */ void (*cleanup)(LADSPA_Handle Instance); + /*******************************************************************/ + + /* The following members of the plugin descriptor structure are only + evaluated if the plugin sets LADSPA_PROPERTY_HAVE_VERSION as + discussed above, indicating it is aware of the v1.2 extensions. */ + + /* This structure documents the API version the plugin implements. + Implicitly, a major.minor combination evaluating to 1.1 or less + indicates to a host that evaluation of the following members is + pointless. */ + const struct { + short major, minor; + } Version; + + /* This member indicates an array of LADSPA_PortInfo structures used + to document sensible default parameter values, parameter units + and to label port values of particular interest. */ + const LADSPA_PortInfo * PortInfo; + } LADSPA_Descriptor; /**********************************************************************/ @@ -594,6 +752,6 @@ } #endif -#endif /* LADSPA_INCLUDED */ +#endif /* LADSPA_VERSION */ /* EOF */