annotate plugin/api/new_dssi_transport_patch @ 588:d04b8674b710

* Try to identify the properly conformant audio file structure written out
  by Sonic Annotator (but we still don't actually import it yet)

diff -r dssi-CVS-20051012=0.9.1/dssi/dssi.h _dssi-transport-mine-new/dssi/dssi.h
5,6c5,6
<    DSSI version 0.9
<    Copyright (c) 2004 Chris Cannam, Steve Harris and Sean Bolton
---
>    DSSI version 0.10
>    Copyright (c) 2004,2005 Chris Cannam, Steve Harris and Sean Bolton
30c30
< #define DSSI_VERSION "0.9"
---
> #define DSSI_VERSION "0.10"
32c32
< #define DSSI_VERSION_MINOR 9
---
> #define DSSI_VERSION_MINOR 10
76a77,152
> #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 */
> 
83,84c159,161
<      * If we're lucky, this will never be needed.  For now all plugins
<      * must set it to 1.
---
>      * 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().
376a454,472
> 
>     /**
>      * 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)(DSSI_Host_Descriptor *Descriptor);
> 
377a474,598
> 
> 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_tranport_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
>     */
> };