[linux-audio-dev] ladspa.h.diff

[Tim Goetze]

the attached patch proves that LADSPA can be extended without breaking
binary compatibility. i've compiled plugins against a patched ladspa.h
and run them in hosts compiled against ladspa.h version 1.1 without
experiencing any problems.

also attached is a short test program that demonstrates how the
extensions provided by the patch can be put to use.

to demonstrate various possibilities and their relative ease of use,
the patch implements the following extensions:

hints:
* connect_port (NULL) is ok hint

member extensions to the descriptor:
* Version (major, minor)
* Latency
* char ** PortUnits
* LADSPA_Data * DefaultValues
* LADSPA_PortValueEnum ** PortValueEnum

the PortValueEnum is a structure having a char * Label and LADSPA_Data
Value member associating a value with a label. this arrangement is
deemed to suit integer enumerations as well as arbitrary association
of values with a label.

while the patch follows the general style of the original ladspa
header, more sophistication would probably need to go into it for a
production version, especially into the comments describing the
extended version mechanism and members.

vriendelijk,

tim
-------------- next part --------------
--- ladspa.h.orig	Fri Mar  5 15:21:14 2004
+++ ladspa.h	Fri Mar  5 15:24:11 2004
@@ -4,6 +4,10 @@
    LGPL].  Copyright (C) 2000-2002 Richard W.E. Furse, Paul
    Barton-Davis, Stefan Westerfeld.
    
+   Version 2.0 (provisional, LGPL)
+   Copyright (C) 2004 Steve Harris, Matthias Nagorni, Fons Adriaensen, 
+   Tom Szilyagi, 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 can 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)
 
 /*****************************************************************************/
 
@@ -349,6 +362,42 @@
 
 /*****************************************************************************/
 
+/* Version 2 Hints:
+ 
+   Plugins implementing version 2 or above can set these port hints in 
+   addition to the hints defined above.
+
+   VERSION: 2 or 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
+
+#define LADSPA_IS_HINT_NULL_OK(x)       ((x) & LADSPA_HINT_NULL_OK)
+
+/*****************************************************************************/
+
+/* 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.
+
+   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;
+
+/*****************************************************************************/
+
 /* Plugin Handles: 
 
    This plugin handle indicates a particular instance of the plugin
@@ -552,6 +601,40 @@
      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' member 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 default port parameter values.
+     Valid indices vary from 0 to PortCount-1. */
+  const LADSPA_Data * DefaultValues;
+
+  /* This member indicates an array of null-terminated strings
+     describing value units (e.g. "Hz", "dB"). Valid indices vary from
+     0 to PortCount-1. */
+  const char ** PortUnits;
+
+  /* This member indicates an array of arrays of value to label 
+     association structures. A plugin can choose to set this member
+     to NULL, or set individual members to NULL. Valid indices vary 
+     from 0 to PortCount-1. */
+  const LADSPA_PortValueEnum ** PortValueEnum;
 
 } LADSPA_Descriptor;
 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: test.c
Type: text/x-csrc
Size: 1289 bytes
Desc: 
URL: <http://lists.linuxaudio.org/pipermail/linux-audio-dev/attachments/20040305/5192629d/attachment.c>