--- ladspa.h.orig Fri Mar 5 15:21:14 2004 +++ ladspa.h Mon Mar 8 00:00:37 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, 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 @@ -127,9 +131,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 +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 version 2.0. For a grace period, host authors should try to + make use of the PortInfo member of the 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 +370,105 @@ /*****************************************************************************/ +/* 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 a non-zero port value causes + the plugin to initiate a one-shot process. Consequently, a host is + expected to reset the port value to zero after every run() or + run_adding() call. Please note that the port value range needs not + necessarily include zero. The use of this hint precludes the use of + LADSPA_HINT_MOMENTARY. + + Plugin writers should note 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 use of this hint precludes the use of + LADSPA_HINT_TRIGGER. */ +#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 dimension-less + 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; + +/*****************************************************************************/ + /* Plugin Handles: This plugin handle indicates a particular instance of the plugin @@ -406,7 +526,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 +601,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 @@ -552,6 +676,30 @@ corresponding call to deactivate() must be made before cleanup() 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 the delay, in 1 / (sample rate) time units, + the plugin imposes upon processed signals. */ + const LADSPA_Data Latency; + + /* 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;