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: > };