1diff -r dssi-CVS-20051012=0.9.1/dssi/dssi.h _dssi-transport-mine-new/dssi/dssi.h 25,6c5,6 3< DSSI version 0.9 4< Copyright (c) 2004 Chris Cannam, Steve Harris and Sean Bolton 5--- 6> DSSI version 0.10 7> Copyright (c) 2004,2005 Chris Cannam, Steve Harris and Sean Bolton 830c30 9< #define DSSI_VERSION "0.9" 10--- 11> #define DSSI_VERSION "0.10" 1232c32 13< #define DSSI_VERSION_MINOR 9 14--- 15> #define DSSI_VERSION_MINOR 10 1676a77,152 17> #define DSSI_TRANSPORT_VALID_STATE 0x01 18> #define DSSI_TRANSPORT_VALID_BPM 0x02 19> #define DSSI_TRANSPORT_VALID_BBT 0x10 20> #define DSSI_TRANSPORT_VALID_TIME 0x20 21> 22> #define DSSI_TRANSPORT_STATE_STOPPED 0 23> #define DSSI_TRANSPORT_STATE_RUNNING 1 24> #define DSSI_TRANSPORT_STATE_FREEWHEELING 2 25> #define DSSI_TRANSPORT_STATE_OTHER 3 /* waiting for sync, ? */ 26> 27> typedef struct _DSSI_Transport_Info { 28> 29> /** The value of this field indicates which of the following 30> * transport information fields contain valid values. It is 31> * the logical OR of the DSSI_TRANSPORT_VALID_* bits defined 32> * above, and may be zero. */ 33> int Valid; 34> 35> 36> /** This field is valid when (Valid & DSSI_TRANSPORT_VALID_STATE) 37> * is true: 38> * 39> * ---- The current transport state, one of the DSSI_TRANSPORT_STATE_* 40> * values defined above. */ 41> int State; 42> 43> 44> /** This field is valid when (Valid & DSSI_TRANSPORT_VALID_BPM) 45> * is true: 46> * 47> * ---- The current tempo, in beats per minute. */ 48> double Beats_Per_Minute; 49> 50> 51> /** These six fields are valid when (Valid & DSSI_TRANSPORT_VALID_BBT) 52> * is true: 53> * 54> * ---- The bar number at the beginning of the current process cycle. */ 55> unsigned long Bar; 56> 57> * ---- The beat within that Bar. */ 58> unsigned long Beat; 59> 60> /** ---- The tick within that Beat. */ 61> unsigned long Tick; 62> 63> /** ---- The (possibly fractional) tick count since transport 'start' 64> * and the beginning of the current Bar. */ 65> double Bar_Start_Tick; 66> 67> /** ---- The number of beats per bar. */ 68> float Beats_Per_Bar; 69> 70> /** ---- The number of ticks for each beat. */ 71> double Ticks_Per_Beat; 72> 73> /* [Sean says: I left out the 'beat_type' (time signature "denominator") 74> * field of the jack_position_t structure, because I think it's useless 75> * except to a notation program. Does anybody else feel like we need it?] 76> 77> 78> /** These two fields are valid when (Valid & DSSI_TRANSPORT_VALID_TIME) 79> * is true: 80> * 81> * ---- The transport time at the beginning of the current process 82> * cycle, in seconds. */ 83> double Current_Time; 84> 85> /** ---- The transport time at the beginning of the next process 86> cycle, unless repositioning occurs. */ 87> double Next_Time; 88> 89> } DSSI_Transport_Info; 90> 91> typedef struct _DSSI_Host_Descriptor DSSI_Host_Descriptor; /* below */ 92> 9383,84c159,161 94< * If we're lucky, this will never be needed. For now all plugins 95< * must set it to 1. 96--- 97> * All plugins must set this to 1 or 2. The version 1 API contains 98> * all DSSI_Descriptor fields through run_multiple_synths_adding(), 99> * while the version 2 API adds the receive_host_descriptor(). 100376a454,472 101> 102> /** 103> * receive_host_descriptor() 104> * 105> * This member is a function pointer by which a host may provide 106> * a plugin with a pointer to its DSSI_Host_Descriptor. Hosts 107> * which provide host descriptor support must call this function 108> * once per plugin shared object file, before any calls to 109> * instantiate(). 110> * 111> * NOTE: This field was added in version 2 of the DSSI API. Hosts 112> * supporting version 2 must not access this field in a plugin 113> * whose DSSI_API_Version is 1, and plugins supporting version 2 114> * should behave reasonably under hosts (of any version) which do 115> * not implement this function. A version 2 plugin that does not 116> * provide this function must set this member to NULL. 117> */ 118> void (*receive_host_descriptor)(DSSI_Host_Descriptor *Descriptor); 119> 120377a474,598 121> 122> struct _DSSI_Host_Descriptor { 123> 124> /** 125> * DSSI_API_Version 126> * 127> * This member indicates the DSSI API level used by this host. 128> * All hosts must set this to 2. Hopefully, we'll get this right 129> * the first time, and this will never be needed. 130> */ 131> int DSSI_API_Version; 132> 133> /** 134> * request_tranport_information() 135> * 136> * This member is a function pointer by which a plugin instance may 137> * request that a host begin providing transport information (if 138> * Request is non-zero), or notify the host that it no longer needs 139> * transport information (if Request is zero). Upon receiving a 140> * non-zero request, the host should return a pointer to a 141> * DSSI_Transport_Info structure if it is able to provide transport 142> * information, or NULL otherwise. 143> * 144> * Once a plugin instance has received a non-null transport 145> * information pointer, it may read from the structure at any time 146> * within the execution of an audio class function (see doc/RFC.txt). 147> * It should not consider the structure contents to be meaningful 148> * while within a instantiation or control class function. Also, 149> * since the validity of fields within the structure may change 150> * between each new invocation of an audio class function, a plugin 151> * instance must check the Valid field of the structure accordingly 152> * before using the structure's other contents. 153> * 154> * A host which does not support this function must set this member 155> * to NULL. 156> */ 157> DSSI_Transport_Info * 158> (*request_transport_information)(LADSPA_Handle Instance, 159> int Request); 160> 161> /** 162> * request_midi_send() 163> * 164> * This member is a function pointer that allows a plugin to 165> * request the ability to send MIDI events to the host. 166> * 167> * While the interpretation of plugin-generated MIDI events is 168> * host implementation specific, a mechanism exists by which a 169> * plugin may declare to the host the number of destination 170> * 'ports' and MIDI channels it can expect will be used in the 171> * plugin-generated events. Plugins which generate unchannelized 172> * MIDI should supply zero for both Ports and Channels, otherwise 173> * they should supply the maximum numbers for Ports and Channels 174> * they expect to use. 175> * 176> * A plugin instance must call this function during instantiate(). 177> * [Sean says: this restriction seems reasonable to me, since 178> * the host may need to create output ports, etc., and instantiate() 179> * seems like a good place to do such things. I'm sure I haven't 180> * fully thought through all the details, though....] 181> * 182> * The host should return a non-zero value if it is able to 183> * provide MIDI send for the plugin instance, otherwise it should 184> * return zero, and the plugin instance may not subsequently call 185> * midi_send(). 186> * 187> * A host which does not support the MIDI send function must set 188> * both this member and (*midi_send)() below to NULL. 189> */ 190> int (*request_midi_send)(LADSPA_Handle Instance, 191> unsigned char Ports, 192> unsigned char Channels); 193> 194> /** 195> * midi_send() 196> * 197> * This member is a function pointer by which a plugin actually 198> * sends MIDI events to the host (provided it has received a non- 199> * zero return from request_midi_send()). As in the run_synth() 200> * functions, the Event pointer points to a block of EventCount 201> * ALSA sequencer events. The dest.port and data.*.channel fields 202> * of each event are used to specify destination port and channel, 203> * respectively, when the plugin is supplying channelized events. 204> * 205> * A plugin may only call this function from within the execution 206> * of the audio class run_*() or select_program() functions. When 207> * called from a run_*() functions, the events are timestamped 208> * relative to the start of the block, (mis)using the ALSA "tick 209> * time" field as a frame count. The plugin is responsible for 210> * ensuring that events with differing timestamps are already 211> * ordered by time, and that timestamps across multiple calls to 212> * midi_send() from within the same run_*() invocation are 213> * monotonic. When midi_send() is called from within 214> * select_program(), the timestamps are ignored, and the events 215> * are considered to originate at the same frame time as the 216> * select_program() call, if such a timing can be considered 217> * meaningful. 218> * 219> * The memory pointed to by Event belongs to the plugin, and it is 220> * the host's responsibility to copy the events as needed before 221> * returning from the midi_send() call. 222> * 223> * A host which does not support the MIDI send function must set 224> * both this member and (*request_midi_send)() above to NULL. 225> */ 226> void (*midi_send)(LADSPA_Handle Instance, 227> snd_seq_event_t *Event, 228> unsigned long EventCount); 229> 230> /** 231> * . . . additional fields could follow here, possibly supporting: 232> * 233> * - a facility by which a plugin instance may request from a 234> * host a non-realtime thread in which to do off-line 235> * rendering, I/O, etc., thus (hopefully) avoiding the 236> * crashes that seem to occur when plugins create their own 237> * threads. I got this idea after noticing that ZynAddSubFX 238> * achieves its gorgeous textures while remaining very 239> * responsive by doing a lot of non-real-time rendering. 240> * Several other uses for it have been mentioned on the DSSI 241> * list; I forget what. 242> * 243> * - per-voice audio output 244> */ 245> }; 246