--- ladspa.h.orig Fri Mar 5 15:21:14 2004 +++ ladspa.h Wed Mar 10 15:10:13 2004 @@ -4,6 +4,10 @@ LGPL]. Copyright (C) 2000-2002 Richard W.E. Furse, Paul Barton-Davis, Stefan Westerfeld. + Ladspa Audio DSP API Version 2.0 (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 "2.0" +#define LADSPA_VERSION_MAJOR 2 +#define LADSPA_VERSION_MINOR 0 #ifdef __cplusplus extern "C" { @@ -127,9 +133,18 @@ 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 a version 2 or above + plugin. Plugins that follow the version 2 API make use of the + fields of the Descriptor structure following the 'version' field. + + VERSION: 2 or above. */ +#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 +265,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 version 2.0. For a grace period, hosts should try to evaluate + the PortInfo member of the version 2 plugin descriptor prior to + falling back to the version 1.1 hint mechanism. Plugins written for + version 2.0 should specify both their precise idea of the default + value through the new LADSPA_PortInfo structure, as well as give + older host programs a rough idea through the default hints. */ #define LADSPA_HINT_DEFAULT_MASK 0x3C0 /* This default values indicates that no default is provided. */ @@ -349,6 +372,126 @@ /*****************************************************************************/ +/* Version 2 Hints: + + Plugins implementing version 2 or above can set these port hints in + addition to the hints defined above. */ + +/* Hint LADSPA_HINT_NULL_OK indicates that the plugin supports a NULL value + passed as data location to the connect_port() method. */ +#define LADSPA_HINT_NULL_OK 0x400 + +/* Hint LADSPA_HINT_TRIGGER indicates that the port signifies the triggering + of 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. If the port is an output, + the plugin itself is the source of the trigger signal. Please note that the + port value range needs not necessarily include zero, the value which + indicates 'no trigger'. The use of this hint precludes the use of + LADSPA_HINT_MOMENTARY. + + Plugin writers should be aware that ignoring this hint is valid for a + pre-version 2 host. */ +#define LADSPA_HINT_TRIGGER 0x800 + +/* Hint LADSPA_HINT_MOMENTARY indicates that port is intended to be + connected to a trigger signal emitting both rising and falling edge + signals, corresponding 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 when 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 + use of this hint precludes the use of LADSPA_HINT_TRIGGER. + + Plugin writers should be aware that ignoring this hint is valid for a + pre-version 2 host. */ +#define LADSPA_HINT_MOMENTARY 0x1000 + +/* Hint LADSPA_HINT_RANDOMIZABLE indicates that the host can opt to + choose any value from the indicated value range for the port at any + time and expect sensible results from the plugin. This hint is meant + to be used primarily in conjunction with LADSPA_HINT_TRIGGER or + LADSPA_HINT_MOMENTARY. */ +#define LADSPA_HINT_RANDOMIZABLE 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_RANDOMIZABLE(x) ((x) & LADSPA_HINT_RANDOMIZABLE) + +/*****************************************************************************/ + +/* Port Value Enumerations: + + Plugins implementing version 2 or above can associate port values with + labels by providing arrays of the following structure tied to specific + ports. Plugin authors should note that a host may choose to override + or ignore this information. + + VERSION: 2 or above. */ + +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 implementing version 2 or above use the following structure + to communicate additional information about their ports to the host + program. + + VERSION: 2 or above. */ + +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. For + example: "Hz" for a frequency, "dB" for decibels, "s" for seconds etc. + A plugin may choose to set this 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. For example, an oscillator plugin may want to label + specific waveforms: "sin" -> 0, "tri" -> 1, "saw" -> 2, "square" -> 3. + 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. */ + +/* This port name always indicates a control output port (LADSPA_PORT_OUTPUT | + LADSPA_PORT_CONTROL). 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 take note that hosts will most likely + evaluate this information only once during the lifecycle of a plugin + instance. Host authors must assume that the port value will only be valid + after the first call to run() or run_adding(). */ +#define LADSPA_LATENCY_PORT_NAME "_latency" + +/*****************************************************************************/ + /* Plugin Handles: This plugin handle indicates a particular instance of the plugin @@ -406,7 +549,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 +624,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 +700,26 @@ 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. + + VERSION: 2 or above. */ + + /* This structure documents the API version the plugin implements. + Implicitly, a 'major' value of less than 2 indicates to a host that + evaluation of version 2 extensions 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 +761,6 @@ } #endif -#endif /* LADSPA_INCLUDED */ +#endif /* LADSPA_VERSION */ /* EOF */