Chris@0: diff -r dssi-CVS-20051012=0.9.1/dssi/dssi.h _dssi-transport-mine-new/dssi/dssi.h
Chris@0: 5,6c5,6
Chris@0: <    DSSI version 0.9
Chris@0: <    Copyright (c) 2004 Chris Cannam, Steve Harris and Sean Bolton
Chris@0: ---
Chris@0: >    DSSI version 0.10
Chris@0: >    Copyright (c) 2004,2005 Chris Cannam, Steve Harris and Sean Bolton
Chris@0: 30c30
Chris@0: < #define DSSI_VERSION "0.9"
Chris@0: ---
Chris@0: > #define DSSI_VERSION "0.10"
Chris@0: 32c32
Chris@0: < #define DSSI_VERSION_MINOR 9
Chris@0: ---
Chris@0: > #define DSSI_VERSION_MINOR 10
Chris@0: 76a77,152
Chris@0: > #define DSSI_TRANSPORT_VALID_STATE  0x01
Chris@0: > #define DSSI_TRANSPORT_VALID_BPM    0x02
Chris@0: > #define DSSI_TRANSPORT_VALID_BBT    0x10
Chris@0: > #define DSSI_TRANSPORT_VALID_TIME   0x20
Chris@0: > 
Chris@0: > #define DSSI_TRANSPORT_STATE_STOPPED       0
Chris@0: > #define DSSI_TRANSPORT_STATE_RUNNING       1
Chris@0: > #define DSSI_TRANSPORT_STATE_FREEWHEELING  2
Chris@0: > #define DSSI_TRANSPORT_STATE_OTHER         3  /* waiting for sync, ? */
Chris@0: > 
Chris@0: > typedef struct _DSSI_Transport_Info {
Chris@0: > 
Chris@0: >     /** The value of this field indicates which of the following
Chris@0: >      *  transport information fields contain valid values. It is
Chris@0: >      *  the logical OR of the DSSI_TRANSPORT_VALID_* bits defined
Chris@0: >      *  above, and may be zero. */
Chris@0: >     int  Valid;
Chris@0: > 
Chris@0: > 
Chris@0: >     /** This field is valid when (Valid & DSSI_TRANSPORT_VALID_STATE)
Chris@0: >      *  is true:
Chris@0: >      *
Chris@0: >      *  ---- The current transport state, one of the DSSI_TRANSPORT_STATE_*
Chris@0: >      *       values defined above. */
Chris@0: >     int  State;
Chris@0: > 
Chris@0: > 
Chris@0: >     /** This field is valid when (Valid & DSSI_TRANSPORT_VALID_BPM)
Chris@0: >      *  is true:
Chris@0: >      *
Chris@0: >      *  ---- The current tempo, in beats per minute.  */
Chris@0: >     double Beats_Per_Minute;
Chris@0: > 
Chris@0: > 
Chris@0: >     /** These six fields are valid when (Valid & DSSI_TRANSPORT_VALID_BBT)
Chris@0: >      *  is true:
Chris@0: >      *
Chris@0: >      *  ---- The bar number at the beginning of the current process cycle. */
Chris@0: >     unsigned long Bar;
Chris@0: > 
Chris@0: >      *  ---- The beat within that Bar. */
Chris@0: >     unsigned long Beat;
Chris@0: >     
Chris@0: >     /** ---- The tick within that Beat. */
Chris@0: >     unsigned long Tick;
Chris@0: > 
Chris@0: >     /** ---- The (possibly fractional) tick count since transport 'start'
Chris@0: >      *       and the beginning of the current Bar. */
Chris@0: >     double Bar_Start_Tick;
Chris@0: > 
Chris@0: >     /** ---- The number of beats per bar. */
Chris@0: >     float  Beats_Per_Bar;
Chris@0: > 
Chris@0: >     /** ---- The number of ticks for each beat. */
Chris@0: >     double Ticks_Per_Beat;
Chris@0: > 
Chris@0: >     /* [Sean says: I left out the 'beat_type' (time signature "denominator")
Chris@0: >      * field of the jack_position_t structure, because I think it's useless
Chris@0: >      * except to a notation program. Does anybody else feel like we need it?]
Chris@0: >     
Chris@0: > 
Chris@0: >     /** These two fields are valid when (Valid & DSSI_TRANSPORT_VALID_TIME)
Chris@0: >      *  is true:
Chris@0: >      *
Chris@0: >      *  ---- The transport time at the beginning of the current process
Chris@0: >      *       cycle, in seconds. */
Chris@0: >     double  Current_Time;
Chris@0: > 
Chris@0: >     /** ---- The transport time at the beginning of the next process
Chris@0: >              cycle, unless repositioning occurs. */
Chris@0: >     double  Next_Time;
Chris@0: > 
Chris@0: > } DSSI_Transport_Info;
Chris@0: > 
Chris@0: > typedef struct _DSSI_Host_Descriptor DSSI_Host_Descriptor; /* below */
Chris@0: > 
Chris@0: 83,84c159,161
Chris@0: <      * If we're lucky, this will never be needed.  For now all plugins
Chris@0: <      * must set it to 1.
Chris@0: ---
Chris@0: >      * All plugins must set this to 1 or 2.  The version 1 API contains
Chris@0: >      * all DSSI_Descriptor fields through run_multiple_synths_adding(),
Chris@0: >      * while the version 2 API adds the receive_host_descriptor().
Chris@0: 376a454,472
Chris@0: > 
Chris@0: >     /**
Chris@0: >      * receive_host_descriptor()
Chris@0: >      *
Chris@0: >      * This member is a function pointer by which a host may provide
Chris@0: >      * a plugin with a pointer to its DSSI_Host_Descriptor. Hosts
Chris@0: >      * which provide host descriptor support must call this function
Chris@0: >      * once per plugin shared object file, before any calls to
Chris@0: >      * instantiate().
Chris@0: >      *
Chris@0: >      * NOTE: This field was added in version 2 of the DSSI API. Hosts
Chris@0: >      * supporting version 2 must not access this field in a plugin
Chris@0: >      * whose DSSI_API_Version is 1, and plugins supporting version 2
Chris@0: >      * should behave reasonably under hosts (of any version) which do
Chris@0: >      * not implement this function. A version 2 plugin that does not
Chris@0: >      * provide this function must set this member to NULL.
Chris@0: >      */
Chris@0: >     void (*receive_host_descriptor)(DSSI_Host_Descriptor *Descriptor);
Chris@0: > 
Chris@0: 377a474,598
Chris@0: > 
Chris@0: > struct _DSSI_Host_Descriptor {
Chris@0: > 
Chris@0: >     /**
Chris@0: >      * DSSI_API_Version
Chris@0: >      *
Chris@0: >      * This member indicates the DSSI API level used by this host.
Chris@0: >      * All hosts must set this to 2.  Hopefully, we'll get this right
Chris@0: >      * the first time, and this will never be needed.
Chris@0: >      */
Chris@0: >     int DSSI_API_Version;
Chris@0: > 
Chris@0: >     /**
Chris@0: >      * request_tranport_information()
Chris@0: >      *
Chris@0: >      * This member is a function pointer by which a plugin instance may
Chris@0: >      * request that a host begin providing transport information (if
Chris@0: >      * Request is non-zero), or notify the host that it no longer needs
Chris@0: >      * transport information (if Request is zero).  Upon receiving a
Chris@0: >      * non-zero request, the host should return a pointer to a
Chris@0: >      * DSSI_Transport_Info structure if it is able to provide transport
Chris@0: >      * information, or NULL otherwise.
Chris@0: >      *
Chris@0: >      * Once a plugin instance has received a non-null transport
Chris@0: >      * information pointer, it may read from the structure at any time
Chris@0: >      * within the execution of an audio class function (see doc/RFC.txt).
Chris@0: >      * It should not consider the structure contents to be meaningful
Chris@0: >      * while within a instantiation or control class function.  Also,
Chris@0: >      * since the validity of fields within the structure may change
Chris@0: >      * between each new invocation of an audio class function, a plugin
Chris@0: >      * instance must check the Valid field of the structure accordingly
Chris@0: >      * before using the structure's other contents.
Chris@0: >      *
Chris@0: >      * A host which does not support this function must set this member
Chris@0: >      * to NULL.
Chris@0: >      */
Chris@0: >     DSSI_Transport_Info *
Chris@0: >         (*request_transport_information)(LADSPA_Handle Instance,
Chris@0: >                                          int           Request);
Chris@0: > 
Chris@0: >     /**
Chris@0: >      * request_midi_send()
Chris@0: >      *
Chris@0: >      * This member is a function pointer that allows a plugin to
Chris@0: >      * request the ability to send MIDI events to the host.
Chris@0: >      *
Chris@0: >      * While the interpretation of plugin-generated MIDI events is
Chris@0: >      * host implementation specific, a mechanism exists by which a
Chris@0: >      * plugin may declare to the host the number of destination
Chris@0: >      * 'ports' and MIDI channels it can expect will be used in the
Chris@0: >      * plugin-generated events.  Plugins which generate unchannelized
Chris@0: >      * MIDI should supply zero for both Ports and Channels, otherwise
Chris@0: >      * they should supply the maximum numbers for Ports and Channels
Chris@0: >      * they expect to use.
Chris@0: >      *
Chris@0: >      * A plugin instance must call this function during instantiate().
Chris@0: >      * [Sean says: this restriction seems reasonable to me, since
Chris@0: >      * the host may need to create output ports, etc., and instantiate()
Chris@0: >      * seems like a good place to do such things.  I'm sure I haven't
Chris@0: >      * fully thought through all the details, though....]
Chris@0: >      *
Chris@0: >      * The host should return a non-zero value if it is able to
Chris@0: >      * provide MIDI send for the plugin instance, otherwise it should
Chris@0: >      * return zero, and the plugin instance may not subsequently call
Chris@0: >      * midi_send().
Chris@0: >      *
Chris@0: >      * A host which does not support the MIDI send function must set
Chris@0: >      * both this member and (*midi_send)() below to NULL.
Chris@0: >      */
Chris@0: >     int (*request_midi_send)(LADSPA_Handle Instance,
Chris@0: >                              unsigned char Ports,
Chris@0: >                              unsigned char Channels);
Chris@0: > 
Chris@0: >     /**
Chris@0: >      * midi_send()
Chris@0: >      *
Chris@0: >      * This member is a function pointer by which a plugin actually
Chris@0: >      * sends MIDI events to the host (provided it has received a non-
Chris@0: >      * zero return from request_midi_send()). As in the run_synth()
Chris@0: >      * functions, the Event pointer points to a block of EventCount
Chris@0: >      * ALSA sequencer events.  The dest.port and data.*.channel fields
Chris@0: >      * of each event are used to specify destination port and channel,
Chris@0: >      * respectively, when the plugin is supplying channelized events.
Chris@0: >      *
Chris@0: >      * A plugin may only call this function from within the execution
Chris@0: >      * of the audio class run_*() or select_program() functions. When
Chris@0: >      * called from a run_*() functions, the events are timestamped
Chris@0: >      * relative to the start of the block, (mis)using the ALSA "tick
Chris@0: >      * time" field as a frame count. The plugin is responsible for
Chris@0: >      * ensuring that events with differing timestamps are already
Chris@0: >      * ordered by time, and that timestamps across multiple calls to
Chris@0: >      * midi_send() from within the same run_*() invocation are
Chris@0: >      * monotonic.  When midi_send() is called from within
Chris@0: >      * select_program(), the timestamps are ignored, and the events
Chris@0: >      * are considered to originate at the same frame time as the
Chris@0: >      * select_program() call, if such a timing can be considered
Chris@0: >      * meaningful.
Chris@0: >      *
Chris@0: >      * The memory pointed to by Event belongs to the plugin, and it is
Chris@0: >      * the host's responsibility to copy the events as needed before
Chris@0: >      * returning from the midi_send() call.
Chris@0: >      *
Chris@0: >      * A host which does not support the MIDI send function must set
Chris@0: >      * both this member and (*request_midi_send)() above to NULL.
Chris@0: >      */
Chris@0: >     void (*midi_send)(LADSPA_Handle    Instance,
Chris@0: >                       snd_seq_event_t *Event,
Chris@0: >                       unsigned long    EventCount);
Chris@0: > 
Chris@0: >    /**
Chris@0: >     * . . . additional fields could follow here, possibly supporting:
Chris@0: >     *
Chris@0: >     *   - a facility by which a plugin instance may request from a
Chris@0: >     *       host a non-realtime thread in which to do off-line
Chris@0: >     *       rendering, I/O, etc., thus (hopefully) avoiding the
Chris@0: >     *       crashes that seem to occur when plugins create their own
Chris@0: >     *       threads.  I got this idea after noticing that ZynAddSubFX
Chris@0: >     *       achieves its gorgeous textures while remaining very
Chris@0: >     *       responsive by doing a lot of non-real-time rendering.
Chris@0: >     *       Several other uses for it have been mentioned on the DSSI
Chris@0: >     *       list; I forget what.
Chris@0: >     *
Chris@0: >     *   - per-voice audio output
Chris@0: >     */
Chris@0: > };