annotate plugin/api/dssi.h @ 490:c3fb8258e34d

* Make it possible to import an entire session from an RDF document.
  However, at the moment the timings of events appear to be constrained
  by how far the audio decoder has got through its audio file at the
  time the event is queried -- need to investigate.

/* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- */

/* dssi.h

   DSSI version 0.10
   Copyright (c) 2004,2005 Chris Cannam, Steve Harris and Sean Bolton
   
   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
   the License, or (at your option) any later version.
   
   This library is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   Lesser General Public License for more details.
   
   You should have received a copy of the GNU Lesser General Public
   License along with this library; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
   USA.
*/

#ifndef DSSI_INCLUDED
#define DSSI_INCLUDED

#include "ladspa.h"
#include "alsa/seq_event.h"

#define DSSI_VERSION "0.10"
#define DSSI_VERSION_MAJOR 0
#define DSSI_VERSION_MINOR 10

#ifdef __cplusplus
extern "C" {
#endif

/* 
   There is a need for an API that supports hosted MIDI soft synths
   with GUIs in Linux audio applications.  In time the GMPI initiative
   should comprehensively address this need, but the requirement for
   Linux applications to be able to support simple hosted synths is
   here now, and GMPI is not.  This proposal (the "DSSI Soft Synth
   Interface" or DSSI, pronounced "dizzy") aims to provide a simple
   solution in a way that we hope will prove complete and compelling
   enough to support now, yet not so compelling as to supplant GMPI or
   any other comprehensive future proposal.

   For simplicity and familiarity, this API is based as far as
   possible on existing work -- the LADSPA plugin API for control
   values and audio processing, and the ALSA sequencer event types for
   MIDI event communication.  The GUI part of the proposal is quite
   new, but may also be applicable retroactively to LADSPA plugins
   that do not otherwise support this synth interface.
*/

/*
   A program wishing to use the DSSI v2 API should set the following
   symbol to 2 before including this header.
*/
#if (!defined DSSI_API_LEVEL)
#define DSSI_API_LEVEL 1
#endif

typedef struct _DSSI_Program_Descriptor {

    /** Bank number for this program.  Note that DSSI does not support
        MIDI-style separation of bank LSB and MSB values.  There is no
        restriction on the set of available banks: the numbers do not
        need to be contiguous, there does not need to be a bank 0, etc. */
    unsigned long Bank;

    /** Program number (unique within its bank) for this program.
	There is no restriction on the set of available programs: the
	numbers do not need to be contiguous, there does not need to
	be a program 0, etc. */
    unsigned long Program;

    /** Name of the program. */
    const char * Name;

} DSSI_Program_Descriptor;


#define DSSI_TRANSPORT_VALID_STATE  0x01
#define DSSI_TRANSPORT_VALID_BPM    0x02
#define DSSI_TRANSPORT_VALID_BBT    0x10
#define DSSI_TRANSPORT_VALID_TIME   0x20

#define DSSI_TRANSPORT_STATE_STOPPED       0
#define DSSI_TRANSPORT_STATE_RUNNING       1
#define DSSI_TRANSPORT_STATE_FREEWHEELING  2
#define DSSI_TRANSPORT_STATE_OTHER         3  /* waiting for sync, ? */

typedef struct _DSSI_Transport_Info {

    /** The value of this field indicates which of the following
     *  transport information fields contain valid values. It is
     *  the logical OR of the DSSI_TRANSPORT_VALID_* bits defined
     *  above, and may be zero. */
    int  Valid;


    /** This field is valid when (Valid & DSSI_TRANSPORT_VALID_STATE)
     *  is true:
     *
     *  ---- The current transport state, one of the DSSI_TRANSPORT_STATE_*
     *       values defined above. */
    int  State;


    /** This field is valid when (Valid & DSSI_TRANSPORT_VALID_BPM)
     *  is true:
     *
     *  ---- The current tempo, in beats per minute.  */
    double Beats_Per_Minute;


    /** These six fields are valid when (Valid & DSSI_TRANSPORT_VALID_BBT)
     *  is true:
     *
     *  ---- The bar number at the beginning of the current process cycle. */
    unsigned long Bar;

    /** ---- The beat within that Bar. */
    unsigned long Beat;
    
    /** ---- The tick within that Beat. */
    unsigned long Tick;

    /** ---- The (possibly fractional) tick count since transport 'start'
     *       and the beginning of the current Bar. */
    double Bar_Start_Tick;

    /** ---- The number of beats per bar. */
    float  Beats_Per_Bar;

    /** ---- The number of ticks for each beat. */
    double Ticks_Per_Beat;

    /* [Sean says: I left out the 'beat_type' (time signature "denominator")
     * field of the jack_position_t structure, because I think it's useless
     * except to a notation program. Does anybody else feel like we need it?]
     */

    /** These two fields are valid when (Valid & DSSI_TRANSPORT_VALID_TIME)
     *  is true:
     *
     *  ---- The transport time at the beginning of the current process
     *       cycle, in seconds. */
    double  Current_Time;

    /** ---- The transport time at the beginning of the next process
             cycle, unless repositioning occurs. */
    double  Next_Time;

} DSSI_Transport_Info;

typedef struct _DSSI_Host_Descriptor DSSI_Host_Descriptor; /* below */

typedef struct _DSSI_Descriptor {

    /**
     * DSSI_API_Version
     *
     * This member indicates the DSSI API level used by this plugin.
     * All plugins must set this to 1 or 2.  The version 1 API contains
     * all DSSI_Descriptor fields through run_multiple_synths_adding(),
     * while the version 2 API adds the receive_host_descriptor().
     */
    int DSSI_API_Version;

    /**
     * LADSPA_Plugin
     *
     * A DSSI synth plugin consists of a LADSPA plugin plus an
     * additional framework for controlling program settings and
     * transmitting MIDI events.  A plugin must fully implement the
     * LADSPA descriptor fields as well as the required LADSPA
     * functions including instantiate() and (de)activate().  It
     * should also implement run(), with the same behaviour as if
     * run_synth() (below) were called with no synth events.
     *
     * In order to instantiate a synth the host calls the LADSPA
     * instantiate function, passing in this LADSPA_Descriptor
     * pointer.  The returned LADSPA_Handle is used as the argument
     * for the DSSI functions below as well as for the LADSPA ones.
     */
    const LADSPA_Descriptor *LADSPA_Plugin;

    /**
     * configure()
     *
     * This member is a function pointer that sends a piece of
     * configuration data to the plugin.  The key argument specifies
     * some aspect of the synth's configuration that is to be changed,
     * and the value argument specifies a new value for it.  A plugin
     * that does not require this facility at all may set this member
     * to NULL.
     *
     * This call is intended to set some session-scoped aspect of a
     * plugin's behaviour, for example to tell the plugin to load
     * sample data from a particular file.  The plugin should act
     * immediately on the request.  The call should return NULL on
     * success, or an error string that may be shown to the user.  The
     * host will free the returned value after use if it is non-NULL.
     *
     * Calls to configure() are not automated as timed events.
     * Instead, a host should remember the last value associated with
     * each key passed to configure() during a given session for a
     * given plugin instance, and should call configure() with the
     * correct value for each key the next time it instantiates the
     * "same" plugin instance, for example on reloading a project in
     * which the plugin was used before.  Plugins should note that a
     * host may typically instantiate a plugin multiple times with the
     * same configuration values, and should share data between
     * instances where practical.
     *
     * Calling configure() completely invalidates the program and bank
     * information last obtained from the plugin.
     *
     * Reserved and special key prefixes
     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     * The DSSI: prefix
     * ----------------
     * Configure keys starting with DSSI: are reserved for particular
     * purposes documented in the DSSI specification.  At the moment,
     * there is one such key: DSSI:PROJECT_DIRECTORY.  A host may call
     * configure() passing this key and a directory path value.  This
     * indicates to the plugin and its UI that a directory at that
     * path exists and may be used for project-local data.  Plugins
     * may wish to use the project directory as a fallback location
     * when looking for other file data, or as a base for relative
     * paths in other configuration values.
     *
     * The GLOBAL: prefix
     * ------------------
     * Configure keys starting with GLOBAL: may be used by the plugin
     * and its UI for any purpose, but are treated specially by the
     * host.  When one of these keys is used in a configure OSC call
     * from the plugin UI, the host makes the corresponding configure
     * call (preserving the GLOBAL: prefix) not only to the target
     * plugin but also to all other plugins in the same instance
     * group, as well as their UIs.  Note that if any instance
     * returns non-NULL from configure to indicate error, the host
     * may stop there (and the set of plugins on which configure has
     * been called will thus depend on the host implementation).
     * See also the configure OSC call documentation in RFC.txt.
     */
    char *(*configure)(LADSPA_Handle Instance,
		       const char *Key,
		       const char *Value);

    #define DSSI_RESERVED_CONFIGURE_PREFIX "DSSI:"
    #define DSSI_GLOBAL_CONFIGURE_PREFIX "GLOBAL:"
    #define DSSI_PROJECT_DIRECTORY_KEY \
	DSSI_RESERVED_CONFIGURE_PREFIX "PROJECT_DIRECTORY"

    /**
     * get_program()
     *
     * This member is a function pointer that provides a description
     * of a program (named preset sound) available on this synth.  A
     * plugin that does not support programs at all should set this
     * member to NULL.
     *
     * The Index argument is an index into the plugin's list of
     * programs, not a program number as represented by the Program
     * field of the DSSI_Program_Descriptor.  (This distinction is
     * needed to support synths that use non-contiguous program or
     * bank numbers.)
     *
     * This function returns a DSSI_Program_Descriptor pointer that is
     * guaranteed to be valid only until the next call to get_program,
     * deactivate, or configure, on the same plugin instance.  This
     * function must return NULL if passed an Index argument out of
     * range, so that the host can use it to query the number of
     * programs as well as their properties.
     */
    const DSSI_Program_Descriptor *(*get_program)(LADSPA_Handle Instance,
						  unsigned long Index);
    
    /**
     * select_program()
     *
     * This member is a function pointer that selects a new program
     * for this synth.  The program change should take effect
     * immediately at the start of the next run_synth() call.  (This
     * means that a host providing the capability of changing programs
     * between any two notes on a track must vary the block size so as
     * to place the program change at the right place.  A host that
     * wanted to avoid this would probably just instantiate a plugin
     * for each program.)
     * 
     * A plugin that does not support programs at all should set this
     * member NULL.  Plugins should ignore a select_program() call
     * with an invalid bank or program.
     *
     * A plugin is not required to select any particular default
     * program on activate(): it's the host's duty to set a program
     * explicitly.  The current program is invalidated by any call to
     * configure().
     *
     * A plugin is permitted to re-write the values of its input
     * control ports when select_program is called.  The host should
     * re-read the input control port values and update its own
     * records appropriately.  (This is the only circumstance in
     * which a DSSI plugin is allowed to modify its own input ports.)
     */
    void (*select_program)(LADSPA_Handle Instance,
			   unsigned long Bank,
			   unsigned long Program);

    /**
     * get_midi_controller_for_port()
     *
     * This member is a function pointer that returns the MIDI
     * controller number or NRPN that should be mapped to the given
     * input control port.  If the given port should not have any MIDI
     * controller mapped to it, the function should return DSSI_NONE.
     * The behaviour of this function is undefined if the given port
     * number does not correspond to an input control port.  A plugin
     * that does not want MIDI controllers mapped to ports at all may
     * set this member NULL.
     *
     * Correct values can be got using the macros DSSI_CC(num) and
     * DSSI_NRPN(num) as appropriate, and values can be combined using
     * bitwise OR: e.g. DSSI_CC(23) | DSSI_NRPN(1069) means the port
     * should respond to CC #23 and NRPN #1069.
     *
     * The host is responsible for doing proper scaling from MIDI
     * controller and NRPN value ranges to port ranges according to
     * the plugin's LADSPA port hints.  Hosts should not deliver
     * through run_synth any MIDI controller events that have already
     * been mapped to control port values.
     *
     * A plugin should not attempt to request mappings from
     * controllers 0 or 32 (MIDI Bank Select MSB and LSB).
     */
    int (*get_midi_controller_for_port)(LADSPA_Handle Instance,
					unsigned long Port);

    /**
     * run_synth()
     *
     * This member is a function pointer that runs a synth for a
     * block.  This is identical in function to the LADSPA run()
     * function, except that it also supplies events to the synth.
     *
     * A plugin may provide this function, run_multiple_synths() (see
     * below), both, or neither (if it is not in fact a synth).  A
     * plugin that does not provide this function must set this member
     * to NULL.  Authors of synth plugins are encouraged to provide
     * this function if at all possible.
     *
     * The Events pointer points to a block of EventCount ALSA
     * sequencer events, which is used to communicate MIDI and related
     * events to the synth.  Each event is timestamped relative to the
     * start of the block, (mis)using the ALSA "tick time" field as a
     * frame count. The host is responsible for ensuring that events
     * with differing timestamps are already ordered by time.
     *
     * See also the notes on activation, port connection etc in
     * ladpsa.h, in the context of the LADSPA run() function.
     *
     * Note Events
     * ~~~~~~~~~~~
     * There are two minor requirements aimed at making the plugin
     * writer's life as simple as possible:
     * 
     * 1. A host must never send events of type SND_SEQ_EVENT_NOTE.
     * Notes should always be sent as separate SND_SEQ_EVENT_NOTE_ON
     * and NOTE_OFF events.  A plugin should discard any one-point
     * NOTE events it sees.
     * 
     * 2. A host must not attempt to switch notes off by sending
     * zero-velocity NOTE_ON events.  It should always send true
     * NOTE_OFFs.  It is the host's responsibility to remap events in
     * cases where an external MIDI source has sent it zero-velocity
     * NOTE_ONs.
     *
     * Bank and Program Events
     * ~~~~~~~~~~~~~~~~~~~~~~~
     * Hosts must map MIDI Bank Select MSB and LSB (0 and 32)
     * controllers and MIDI Program Change events onto the banks and
     * programs specified by the plugin, using the DSSI select_program
     * call.  No host should ever deliver a program change or bank
     * select controller to a plugin via run_synth.
     */
    void (*run_synth)(LADSPA_Handle    Instance,
		      unsigned long    SampleCount,
		      snd_seq_event_t *Events,
		      unsigned long    EventCount);

    /**
     * run_synth_adding()
     *
     * This member is a function pointer that runs an instance of a
     * synth for a block, adding its outputs to the values already
     * present at the output ports.  This is provided for symmetry
     * with LADSPA run_adding(), and is equally optional.  A plugin
     * that does not provide it must set this member to NULL.
     */
    void (*run_synth_adding)(LADSPA_Handle    Instance,
			     unsigned long    SampleCount,
			     snd_seq_event_t *Events,
			     unsigned long    EventCount);

    /**
     * run_multiple_synths()
     *
     * This member is a function pointer that runs multiple synth
     * instances for a block.  This is very similar to run_synth(),
     * except that Instances, Events, and EventCounts each point to
     * arrays that hold the LADSPA handles, event buffers, and
     * event counts for each of InstanceCount instances.  That is,
     * Instances points to an array of InstanceCount pointers to
     * DSSI plugin instantiations, Events points to an array of
     * pointers to each instantiation's respective event list, and
     * EventCounts points to an array containing each instantiation's
     * respective event count.
     *
     * A host using this function must guarantee that ALL active
     * instances of the plugin are represented in each call to the
     * function -- that is, a host may not call run_multiple_synths()
     * for some instances of a given plugin and then call run_synth()
     * as well for others.  'All .. instances of the plugin' means
     * every instance sharing the same LADSPA label and shared object
     * (*.so) file (rather than every instance sharing the same *.so).
     * 'Active' means any instance for which activate() has been called
     * but deactivate() has not.
     *
     * A plugin may provide this function, run_synths() (see above),
     * both, or neither (if it not in fact a synth).  A plugin that
     * does not provide this function must set this member to NULL.
     * Plugin authors implementing run_multiple_synths are strongly
     * encouraged to implement run_synth as well if at all possible,
     * to aid simplistic hosts, even where it would be less efficient
     * to use it.
     */
    void (*run_multiple_synths)(unsigned long     InstanceCount,
                                LADSPA_Handle    *Instances,
                                unsigned long     SampleCount,
                                snd_seq_event_t **Events,
                                unsigned long    *EventCounts);

    /**
     * run_multiple_synths_adding()
     *
     * This member is a function pointer that runs multiple synth
     * instances for a block, adding each synth's outputs to the
     * values already present at the output ports.  This is provided
     * for symmetry with both the DSSI run_multiple_synths() and LADSPA
     * run_adding() functions, and is equally optional.  A plugin
     * that does not provide it must set this member to NULL.
     */
    void (*run_multiple_synths_adding)(unsigned long     InstanceCount,
                                       LADSPA_Handle    *Instances,
                                       unsigned long     SampleCount,
                                       snd_seq_event_t **Events,
                                       unsigned long    *EventCounts);

#if (DSSI_API_LEVEL > 1)

    /**
     * receive_host_descriptor()
     *
     * This member is a function pointer by which a host may provide
     * a plugin with a pointer to its DSSI_Host_Descriptor. Hosts
     * which provide host descriptor support must call this function
     * once per plugin shared object file, before any calls to
     * instantiate().
     *
     * NOTE: This field was added in version 2 of the DSSI API. Hosts
     * supporting version 2 must not access this field in a plugin
     * whose DSSI_API_Version is 1, and plugins supporting version 2
     * should behave reasonably under hosts (of any version) which do
     * not implement this function. A version 2 plugin that does not
     * provide this function must set this member to NULL.
     */
    void (*receive_host_descriptor)(const DSSI_Host_Descriptor *Descriptor);

#endif

} DSSI_Descriptor;

struct _DSSI_Host_Descriptor {

    /**
     * DSSI_API_Version
     *
     * This member indicates the DSSI API level used by this host.
     * All hosts must set this to 2.  Hopefully, we'll get this right
     * the first time, and this will never be needed.
     */
    int DSSI_API_Version;

    /**
     * request_transport_information()
     *
     * This member is a function pointer by which a plugin instance may
     * request that a host begin providing transport information (if
     * Request is non-zero), or notify the host that it no longer needs
     * transport information (if Request is zero).  Upon receiving a
     * non-zero request, the host should return a pointer to a
     * DSSI_Transport_Info structure if it is able to provide transport
     * information, or NULL otherwise.
     *
     * Once a plugin instance has received a non-null transport
     * information pointer, it may read from the structure at any time
     * within the execution of an audio class function (see doc/RFC.txt).
     * It should not consider the structure contents to be meaningful
     * while within a instantiation or control class function.  Also,
     * since the validity of fields within the structure may change
     * between each new invocation of an audio class function, a plugin
     * instance must check the Valid field of the structure accordingly
     * before using the structure's other contents.
     *
     * A host which does not support this function must set this member
     * to NULL.
     */
    DSSI_Transport_Info *
        (*request_transport_information)(LADSPA_Handle Instance,
                                         int           Request);

    /**
     * request_midi_send()
     *
     * This member is a function pointer that allows a plugin to
     * request the ability to send MIDI events to the host.
     *
     * While the interpretation of plugin-generated MIDI events is
     * host implementation specific, a mechanism exists by which a
     * plugin may declare to the host the number of destination
     * 'ports' and MIDI channels it can expect will be used in the
     * plugin-generated events.  Plugins which generate unchannelized
     * MIDI should supply zero for both Ports and Channels, otherwise
     * they should supply the maximum numbers for Ports and Channels
     * they expect to use.
     *
     * A plugin instance must call this function during instantiate().
     * [Sean says: this restriction seems reasonable to me, since
     * the host may need to create output ports, etc., and instantiate()
     * seems like a good place to do such things.  I'm sure I haven't
     * fully thought through all the details, though....]
     *
     * The host should return a non-zero value if it is able to
     * provide MIDI send for the plugin instance, otherwise it should
     * return zero, and the plugin instance may not subsequently call
     * midi_send().
     *
     * A host which does not support the MIDI send function must set
     * both this member and (*midi_send)() below to NULL.
     */
    int (*request_midi_send)(LADSPA_Handle Instance,
                             unsigned char Ports,
                             unsigned char Channels);

    /**
     * midi_send()
     *
     * This member is a function pointer by which a plugin actually
     * sends MIDI events to the host (provided it has received a non-
     * zero return from request_midi_send()). As in the run_synth()
     * functions, the Event pointer points to a block of EventCount
     * ALSA sequencer events.  The dest.port and data.*.channel fields
     * of each event are used to specify destination port and channel,
     * respectively, when the plugin is supplying channelized events.
     *
     * A plugin may only call this function from within the execution
     * of the audio class run_*() or select_program() functions. When
     * called from a run_*() functions, the events are timestamped
     * relative to the start of the block, (mis)using the ALSA "tick
     * time" field as a frame count. The plugin is responsible for
     * ensuring that events with differing timestamps are already
     * ordered by time, and that timestamps across multiple calls to
     * midi_send() from within the same run_*() invocation are
     * monotonic.  When midi_send() is called from within
     * select_program(), the timestamps are ignored, and the events
     * are considered to originate at the same frame time as the
     * select_program() call, if such a timing can be considered
     * meaningful.
     *
     * The memory pointed to by Event belongs to the plugin, and it is
     * the host's responsibility to copy the events as needed before
     * returning from the midi_send() call.
     *
     * A host which does not support the MIDI send function must set
     * both this member and (*request_midi_send)() above to NULL.
     */
    void (*midi_send)(LADSPA_Handle    Instance,
                      snd_seq_event_t *Event,
                      unsigned long    EventCount);

   /**
    * . . . additional fields could follow here, possibly supporting:
    *
    *   - a facility by which a plugin instance may request from a
    *       host a non-realtime thread in which to do off-line
    *       rendering, I/O, etc., thus (hopefully) avoiding the
    *       crashes that seem to occur when plugins create their own
    *       threads.  I got this idea after noticing that ZynAddSubFX
    *       achieves its gorgeous textures while remaining very
    *       responsive by doing a lot of non-real-time rendering.
    *       Several other uses for it have been mentioned on the DSSI
    *       list; I forget what.
    *
    *   - per-voice audio output
    */

    int (*request_non_rt_thread)(LADSPA_Handle Instance,
				 void (*RunFunction)(LADSPA_Handle Instance));
};

/**
 * DSSI supports a plugin discovery method similar to that of LADSPA:
 *
 * - DSSI hosts may wish to locate DSSI plugin shared object files by
 *    searching the paths contained in the DSSI_PATH and LADSPA_PATH
 *    environment variables, if they are present.  Both are expected
 *    to be colon-separated lists of directories to be searched (in
 *    order), and DSSI_PATH should be searched first if both variables
 *    are set.
 *
 * - Each shared object file containing DSSI plugins must include a
 *   function dssi_descriptor(), with the following function prototype
 *   and C-style linkage.  Hosts may enumerate the plugin types
 *   available in the shared object file by repeatedly calling
 *   this function with successive Index values (beginning from 0),
 *   until a return value of NULL indicates no more plugin types are
 *   available.  Each non-NULL return is the DSSI_Descriptor
 *   of a distinct plugin type.
 */

const DSSI_Descriptor *dssi_descriptor(unsigned long Index);
  
typedef const DSSI_Descriptor *(*DSSI_Descriptor_Function)(unsigned long Index);

/*
 * Macros to specify particular MIDI controllers in return values from
 * get_midi_controller_for_port()
 */

#define DSSI_CC_BITS			0x20000000
#define DSSI_NRPN_BITS			0x40000000

#define DSSI_NONE			-1
#define DSSI_CONTROLLER_IS_SET(n)	(DSSI_NONE != (n))

#define DSSI_CC(n)			(DSSI_CC_BITS | (n))
#define DSSI_IS_CC(n)			(DSSI_CC_BITS & (n))
#define DSSI_CC_NUMBER(n)		((n) & 0x7f)

#define DSSI_NRPN(n)			(DSSI_NRPN_BITS | ((n) << 7))
#define DSSI_IS_NRPN(n)			(DSSI_NRPN_BITS & (n))
#define DSSI_NRPN_NUMBER(n)		(((n) >> 7) & 0x3fff)

#ifdef __cplusplus
}
#endif

#endif /* DSSI_INCLUDED */