[linux-audio-dev] +well-known-ports -Latency (ladspa.h.diff)
Tim Goetze
tim at quitte.de
Wed Mar 10 14:37:14 UTC 2004
attached you'll find my latest patch against ladspa.h that, in
addition to the previous patches, discusses the well-known-port
concept and in particular the "_latency" port. it removes the
Latency member from the descriptor structure, introduces
LADSPA_VERSION and tries to clarify things in other places.
as before, the patch causes no side-effects in hosts and plugins
implementing ladspa 1.1 during either compilation or use. in
effect, upgrading is painless.
to keep this post small, the accompanying sample host and plugin
source code has been moved to http://quitte.de/ladspa .
tim
-------------- next part --------------
--- 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 */
More information about the Linux-audio-dev
mailing list