[linux-audio-dev] LADSPA extension - Formal proposal.

[Fons Adriaensen]

Hello list,

After much debate, I propose to extend the current LADPSA 1.1 interface
specification in the way documented below. Two new LADSPA_HINT bits are
introduced. Both can be ignored by existing hosts without any ill
consequences.

The purpose of the first new bit is to allow simple hosts that do not
need the extended information in an RDF file to display meaningfull
labels on a switch widget, as they can already do for e.g. sliders.

The second new bit allows a plugin to request that the host indicates
unconnected ports by providing a NULL pointer.

To those who have followed the debate, I changed the original name 
LADSPA_HINT_ENUMERATED to LADSPA_HINT_SWITCHED. This more correctly
represents the idea, and also allows Tim to use LADSPA_HINT_ENUMERATED
for his proposal which is complementary to this one. 

The text below represents those sections of ladspa.h that would be added
or modified by this proposal.

-- 
Fons


------------8<-------------------------------------------------------


#define LADSPA_VERSION "1.2"
#define LADSPA_VERSION_MAJOR 1
#define LADSPA_VERSION_MINOR 2

.....

/* This hint must be used only together with LADSPA_HINT_INTEGER. 
   It indicates that the port corresponds to a multiway switch selecting
   between options that have no natural numerical value. A port using this
   option would typically correspond to a switch statement in the plugin
   code, and can be represented in a GUI by a menu, a set of radio buttons,
   or any '1 out of N' selection widget.
   For each option a label string is provided in the PortNames array (see
   below). These strings come after all port names. They must be listed
   in order of the ports using this hint bit, and for each port in order
   of the numerical value that represents the switch option. The number of
   options and strings is equal to MAX - MIN + 1, where MIN and MAX are
   the values of the LowerBound and UpperBound fields in the PortRangeHint
   struct for the port. These values must be integers. */
#define LADSPA_HINT_SWITCHED        0x400

/* This hint indicates that a host may provide a NULL pointer for this
   port, to indicate that it is not connected. The host must still define
   the port pointer, even if it is NULL. The plugin code must check ports
   using this bit after each call to connect_port() (see below) that may
   have changed the port's pointer. */
#define LADSPA_HINT_NULLPOINTER     0x800

......

#define LADSPA_IS_HINT_SWITCHED(x)        ((x) & LADSPA_HINT_SWITCHED)
#define LADSPA_IS_HINT_NULLPOINTER(x)     ((x) & LADSPA_HINT_NULLPOINTER)

......

  /* This member indicates an array of null-terminated strings
     describing ports (e.g. "Frequency (Hz)"). Valid indices vary
     from 0 to PortCount-1.
     If there are any ports using LADSPA_HINT_SWITCHED, then their
     label strings follow after all port names (i.e. the port names 
     remain in their normal place). In this case the range of valid
     indices is increased by the number of labels defined. The labels
     are not included in PortCount. */
  const char * const * PortNames;

------------8<-------------------------------------------------------