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