+trigger, Re: [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.

attached is the same patch extended to define a TRIGGER hint.

amicalement,

tim
-------------- next part --------------
--- ladspa.h.orig	Fri Mar  5 15:21:14 2004
+++ ladspa.h	Fri Mar  5 16:36:26 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,50 @@
 
 /*****************************************************************************/
 
+/* 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
+
+/* 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 ignoring this hint is valid for
+   a pre-version 2 host. */
+#define LADSPA_HINT_TRIGGER         0x800
+
+#define LADSPA_IS_HINT_NULL_OK(x)       ((x) & LADSPA_HINT_NULL_OK)
+#define LADSPA_IS_HINT_TRIGGER(x)       ((x) & LADSPA_HINT_TRIGGER)
+
+/*****************************************************************************/
+
+/* 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 +609,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;