[linux-audio-dev] +momentary, consolidated (ladspa.h.diff)

Tim Goetze tim at quitte.de
Sun Mar 7 19:39:36 EST 2004


attached you'll please find three files:

* a patch moving ladspa.h 1.1 to 2.0
* a program showing how a host evaluates 2.0 extensions
* a thoroughly documented example plugin making use of the extensions

changes to the patch with respect to the last version include
consolidation of the extended port info into a dedicated structure.

also included is a warning note concerning the deprecation of the
1.1 default value hints and some minor clarifications.

the patch defines HINT_MOMENTARY as asked by Taybin and Steve. it
also credits Taybin now (Steve already being credited).

-

the example plugin is written with the intention to show, in all its
sometimes gory detail, how ladspa works 'from the plugin side'. the
plugin is fully operational in hosts implementing either version of
the standard. (it doesn't even sound so bad at all :)

there are a number of more elegant ways to accomplish what the plugin
source does, but these have all been ignored for the sake of showing
exactly how things are coming together in ladspa.

-

if you expect the extension to make a plugin author's life harder by a
significant amount, i would like to ask you to go over the source code
of the example plugin and see for yourself.

all the places where the plugin refers to the 2.0 incarnation have
been marked as such. i'm confident you'll agree that words like
'invasive', 'incomprehensible', 'bloated' or 'complicating' are not
doing the extension justice.

i would also like you to consider that it is up to you, either plugin
or host author, to altogether ignore the extension and still come up
with something perfectly useful. you can always extend your work to
make use of the extension at a later date. all this takes is added
code, with no changes to what you already have.

-

my apologies offered for the obnoxious use of the '2.0' version tag
for this proposal. for sheer lack of fantasy, typing laziness and a
number of other bad habits, i couldn't come up with something better.

amicalement,

tim

ps: it is hoped that the example plugin source will be helpful to
aspiring plugin authors, no matter the fate of the extension proposal.
-------------- next part --------------
--- 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;
 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: host.c
Type: text/x-csrc
Size: 1792 bytes
Desc: host.c (host-side source)
Url : http://music.columbia.edu/pipermail/linux-audio-dev/attachments/20040308/7e429843/host-0001.bin
-------------- next part --------------
A non-text attachment was scrubbed...
Name: drive.c
Type: text/x-csrc
Size: 9533 bytes
Desc: drive.c (plugin-side source)
Url : http://music.columbia.edu/pipermail/linux-audio-dev/attachments/20040308/7e429843/drive-0001.bin


More information about the linux-audio-dev mailing list