dssi.h

Go to the documentation of this file.

/* -*- c-basic-offset: 4 -*- */
 
/* dssi.h
 
   DSSI version 1.0
   Copyright (c) 2004, 2009 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., 51 Franklin Street, Fifth Floor, Boston,
   MA  02110-1301  USA
*/
 
#ifndef DSSI_INCLUDED
#define DSSI_INCLUDED
 
#include "../ladspa/ladspa.h"
#include "seq_event-compat.h"
 
#define DSSI_VERSION "1.0"
#define DSSI_VERSION_MAJOR 1
#define DSSI_VERSION_MINOR 0
 
#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.
*/
 
typedef struct _DSSI_Program_Descriptor {

    unsigned long Bank;

    unsigned long Program;

    const char * Name;
 
} DSSI_Program_Descriptor;
 
 
typedef struct _DSSI_Descriptor {

    int DSSI_API_Version;

    const LADSPA_Descriptor *LADSPA_Plugin;

    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"
    #define DSSI_CUSTOMDATA_EXTENSION_KEY \
        DSSI_RESERVED_CONFIGURE_PREFIX "SUPPORTS_CUSTOMDATA"

    const DSSI_Program_Descriptor *(*get_program)(LADSPA_Handle Instance,
                                                  unsigned long Index);
    
    void (*select_program)(LADSPA_Handle Instance,
                           unsigned long Bank,
                           unsigned long Program);

    int (*get_midi_controller_for_port)(LADSPA_Handle Instance,
                                        unsigned long Port);

    void (*run_synth)(LADSPA_Handle    Instance,
                      unsigned long    SampleCount,
                      snd_seq_event_t *Events,
                      unsigned long    EventCount);

    void (*run_synth_adding)(LADSPA_Handle    Instance,
                             unsigned long    SampleCount,
                             snd_seq_event_t *Events,
                             unsigned long    EventCount);

    void (*run_multiple_synths)(unsigned long     InstanceCount,
                                LADSPA_Handle    *Instances,
                                unsigned long     SampleCount,
                                snd_seq_event_t **Events,
                                unsigned long    *EventCounts);

    void (*run_multiple_synths_adding)(unsigned long     InstanceCount,
                                       LADSPA_Handle    *Instances,
                                       unsigned long     SampleCount,
                                       snd_seq_event_t **Events,
                                       unsigned long    *EventCounts);

    int (*set_custom_data)(LADSPA_Handle Instance,
                           void         *Data,
                           unsigned long DataLength);

    int (*get_custom_data)(LADSPA_Handle  Instance,
                           void         **Data,
                           unsigned long *DataLength);
 
} DSSI_Descriptor;

 
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 */