Major change to sequencer API.

The sequencer API is totally recoded with the style of "encapsulation"
in other api.
The structure becomes opaque and accessed only via functions.

Other changes:
- There is no longer group in client and port info.
- snd_seq_query_subs_t is renamed to snd_seq_query_subscribe_t.
- snd_seq_delete_port takes only the port id argument instead of
  port_info structure.
- snd_seq_input/output_buffer_size are renamed
  as snd_seq_get_input/output_buffer_size.
  Similarly snd_seq_resize_input/output_buffer are renamed as
  snd_seq_set_input/output_buffer_size.
- snd_seq_get_named_queue is renamed to snd_seq_query_named_queue.
- Sync codes are removed temporarily from API.
- Subscription conditions are accessed via the corresponding functions.
  convert_time is named now as time_update.
- snd_seq_get/set_queue_owner are removed.
  Use snd_seq_get/set_queue_info instead.
- Instrument put/get/remove structure is unified as snd_instr_header_t.
This commit is contained in:
Jaroslav Kysela 2001-07-04 13:54:13 +00:00
parent d23ff765ad
commit 88e5e45151
20 changed files with 4410 additions and 1691 deletions

View file

@ -4,6 +4,10 @@
* *
****************************************************************************/
#ifdef __cplusplus
extern "C" {
#endif
/**
* \defgroup SeqMiddle Sequencer Middle Level Interface
* Sequencer Middle Level Interface
@ -11,72 +15,237 @@
* \{
*/
#ifdef __cplusplus
extern "C" {
#endif
/* initialize event record */
void snd_seq_ev_clear(snd_seq_event_t *ev);
/* set destination - following three macros are exclusive */
/* explicit destination */
void snd_seq_ev_set_dest(snd_seq_event_t *ev, int client, int port);
/* to subscribers */
void snd_seq_ev_set_subs(snd_seq_event_t *ev);
/* broadcast to all clients/ports */
void snd_seq_ev_set_broadcast(snd_seq_event_t *ev);
/* set source port */
void snd_seq_ev_set_source(snd_seq_event_t *ev, int port);
/* set scheduling - following three macros are exclusive */
/* direct event passing without enqueued */
void snd_seq_ev_set_direct(snd_seq_event_t *ev);
/* scheduled on tick-queue */
void snd_seq_ev_schedule_tick(snd_seq_event_t *ev, int q, int relative,
snd_seq_tick_time_t tick);
/* scheduled on real-time-queue */
void snd_seq_ev_schedule_real(snd_seq_event_t *ev, int q, int relative,
snd_seq_real_time_t *_time);
/* set event priority (optional) */
void snd_seq_ev_set_priority(snd_seq_event_t *ev, int high_prior);
/* set event data type - following three macros are exclusive */
/* fixed size event */
void snd_seq_ev_set_fixed(snd_seq_event_t *ev);
/* variable size event */
void snd_seq_ev_set_variable(snd_seq_event_t *ev, int len, void *ptr);
/* variable size event - user memory space */
void snd_seq_ev_set_varusr(snd_seq_event_t *ev, int len, void *ptr);
/* set queue control event data */
/* destination is overwritten to Timer port (0:0) */
int snd_seq_ev_set_queue_start(snd_seq_event_t *ev, int q);
int snd_seq_ev_set_queue_stop(snd_seq_event_t *ev, int q);
int snd_seq_ev_set_queue_continue(snd_seq_event_t *ev, int q);
int snd_seq_ev_set_queue_tempo(snd_seq_event_t *ev, int q, int tempo);
int snd_seq_ev_set_queue_control(snd_seq_event_t *ev, int type, int q, int value);
int snd_seq_ev_set_queue_pos_real(snd_seq_event_t *ev, int q, snd_seq_real_time_t *rtime);
int snd_seq_ev_set_queue_pos_tick(snd_seq_event_t *ev, int q, snd_seq_tick_time_t tick);
/*
* use/unuse a queue
/**
* \brief initialize event record
* \param ev event record pointer
*/
int snd_seq_use_queue(snd_seq_t *seq, int q, int use);
#define snd_seq_ev_clear(ev) \
memset(ev, 0, sizeof(snd_seq_event_t))
/* set and send a queue control event:
* to send at scheduled time, set the schedule in ev.
* if ev is NULL, event is sent immediately (to output queue).
* Note: to send actually to driver, you need to call snd_seq_flush_event()
* apropriately.
/**
* \brief set the explicit destination
* \param ev event record
* \param c destination client id
* \param p destination port id
*/
#define snd_seq_ev_set_dest(ev,c,p) \
((ev)->dest.client = (c), (ev)->dest.port = (p))
/**
* \brief set broadcasting to subscribers
* \param ev event record
*/
#define snd_seq_ev_set_subs(ev) \
((ev)->dest.client = SND_SEQ_ADDRESS_SUBSCRIBERS,\
(ev)->dest.port = SND_SEQ_ADDRESS_UNKNOWN)
/**
* \brief set broadcasting to all clients/ports
* \param ev event record
*/
#define snd_seq_ev_set_broadcast(ev) \
((ev)->dest.client = SND_SEQ_ADDRESS_BROADCAST,\
(ev)->dest.port = SND_SEQ_ADDRESS_BROADCAST)
/**
* \brief set the source port
* \param ev event record
* \param p source port id
*/
#define snd_seq_ev_set_source(ev,p) \
((ev)->source.port = (p))
/**
* \brief set direct passing mode (without queued)
* \param ev event instance
*/
#define snd_seq_ev_set_direct(ev) \
((ev)->queue = SNDRV_SEQ_QUEUE_DIRECT)
/**
* \brief set tick-scheduling mode on queue
* \param ev event instance
* \param q queue id to schedule
* \param relative relative time-stamp if non-zero
* \param ttick tick time-stap to be delivered
*/
#define snd_seq_ev_schedule_tick(ev, q, relative, ttick) \
((ev)->flags &= ~(SNDRV_SEQ_TIME_STAMP_MASK | SNDRV_SEQ_TIME_MODE_MASK),\
(ev)->flags |= SNDRV_SEQ_TIME_STAMP_TICK,\
(ev)->flags |= (relative) ? SNDRV_SEQ_TIME_MODE_REL : SNDRV_SEQ_TIME_MODE_ABS,\
(ev)->time.tick = (ttick),\
(ev)->queue = (q))
/**
* \brief set real-time-scheduling mode on queue
* \param ev event instance
* \param q queue id to schedule
* \param relative relative time-stamp if non-zero
* \param rtime time-stamp to be delivered
*/
#define snd_seq_ev_schedule_real(ev, q, relative, rtime) \
((ev)->flags &= ~( SNDRV_SEQ_TIME_STAMP_MASK | SNDRV_SEQ_TIME_MODE_MASK),\
(ev)->flags |= SNDRV_SEQ_TIME_STAMP_REAL,\
(ev)->flags |= (relative) ? SNDRV_SEQ_TIME_MODE_REL : SNDRV_SEQ_TIME_MODE_ABS,\
(ev)->time.time = *(rtime),\
(ev)->queue = (q))
/**
* \brief set event priority
* \param ev event instance
* \param high_prior 1 for high priority mode
*/
#define snd_seq_ev_set_priority(ev, high_prior) \
((ev)->flags &= ~SNDRV_SEQ_PRIORITY_MASK,\
(ev)->flags |= (high_prior) ? SNDRV_SEQ_PRIORITY_HIGH : SNDRV_SEQ_PRIORITY_NORMAL)
/**
* \brief set fixed data
* \param ev event instance
*
* Sets the event length mode as fixed size.
*/
#define snd_seq_ev_set_fixed(ev) \
((ev)->flags &= ~SNDRV_SEQ_EVENT_LENGTH_MASK,\
(ev)->flags |= SNDRV_SEQ_EVENT_LENGTH_FIXED)
/**
* \brief set variable data
* \param ev event instance
* \param datalen length of the external data
* \param dataptr pointer of the external data
*
* Sets the event length mode as variable length and stores the data.
*/
#define snd_seq_ev_set_variable(ev, datalen, dataptr) \
((ev)->flags &= ~SNDRV_SEQ_EVENT_LENGTH_MASK,\
(ev)->flags |= SNDRV_SEQ_EVENT_LENGTH_VARIABLE,\
(ev)->data.ext.len = (datalen),\
(ev)->data.ext.ptr = (dataptr))
/**
* \brief set varusr data
* \param ev event instance
* \param len length of the external data
* \param ptr pointer of the external data
*
* Sets the event length mode as variable user-space data and stores the data.
*/
#define snd_seq_ev_set_varusr(ev, datalen, dataptr) \
((ev)->flags &= ~SNDRV_SEQ_EVENT_LENGTH_MASK,\
(ev)->flags |= SNDRV_SEQ_EVENT_LENGTH_VARUSR,\
(ev)->data.ext.len = (datalen),\
(ev)->data.ext.ptr = (dataptr))
/**
* \brief set queue controls
* \param ev event record
* \param typ event type
* \param q queue id
* \param val control value
*/
#define snd_seq_ev_set_queue_control(ev, typ, q, val) \
((ev)->type = (typ),\
snd_seq_ev_set_dest(ev, SND_SEQ_CLIENT_SYSTEM, SND_SEQ_PORT_SYSTEM_TIMER),\
(ev)->data.queue.queue = (q),\
(ev)->data.queue.param.value = (val))
/**
* \brief set the start queue event
* \param ev event record
* \param q queud id to start
*/
#define snd_seq_ev_set_queue_start(ev, q) \
snd_seq_ev_set_queue_control(ev, SND_SEQ_EVENT_START, q, 0)
/**
* \brief set the stop queue event
* \param ev event record
* \param q queud id to stop
*/
#define snd_seq_ev_set_queue_stop(ev, q) \
snd_seq_ev_set_queue_control(ev, SND_SEQ_EVENT_STOP, q, 0)
/**
* \brief set the stop queue event
* \param ev event record
* \param q queud id to continue
*/
#define snd_seq_ev_set_queue_continue(ev, q) \
snd_seq_ev_set_queue_control(ev, SND_SEQ_EVENT_CONTINUE, q, 0)
/**
* \brief set the stop queue event
* \param ev event record
* \param q queud id to change tempo
* \param val the new tempo value
*/
#define snd_seq_ev_set_queue_tempo(ev, q, val) \
snd_seq_ev_set_queue_control(ev, SND_SEQ_EVENT_TEMPO, q, val)
/**
* \brief set the real-time position of a queue
* \param ev event record
* \param q queud id to change tempo
* \param rtime the new real-time pointer
*/
#define snd_seq_ev_set_queue_pos_real(ev, q, rtime) \
((ev)->type = SND_SEQ_EVENT_SETPOS_TIME,\
snd_seq_ev_set_dest(ev, SND_SEQ_CLIENT_SYSTEM, SND_SEQ_PORT_SYSTEM_TIMER),\
(ev)->data.queue.queue = (q),\
(ev)->data.queue.param.time.time = *(rtime))
/**
* \brief set the tick-time position of a queue
* \param ev event record
* \param q queud id to change tempo
* \param ttime the new tick-time
*/
#define snd_seq_ev_set_queue_pos_tick(ev, q, ttime) \
((ev)->type = SND_SEQ_EVENT_SETPOS_TICK,\
snd_seq_ev_set_dest(ev, SND_SEQ_CLIENT_SYSTEM, SND_SEQ_PORT_SYSTEM_TIMER),\
(ev)->data.queue.queue = (q),\
(ev)->data.queue.param.time.tick = (ttime))
/* set and send a queue control event */
int snd_seq_control_queue(snd_seq_t *seq, int q, int type, int value, snd_seq_event_t *ev);
int snd_seq_start_queue(snd_seq_t *seq, int q, snd_seq_event_t *ev);
int snd_seq_stop_queue(snd_seq_t *seq, int q, snd_seq_event_t *ev);
int snd_seq_continue_queue(snd_seq_t *seq, int q, snd_seq_event_t *ev);
int snd_seq_change_queue_tempo(snd_seq_t *seq, int q, int tempo, snd_seq_event_t *ev);
int snd_seq_setpos_queue(snd_seq_t *seq, int q, snd_seq_timestamp_t *rtime, snd_seq_event_t *ev);
/**
* \brief start the specified queue
* \param seq sequencer handle
* \param q queue id to start
* \param ev optional event record (see #snd_seq_control_queue)
*/
#define snd_seq_start_queue(seq, q, ev) \
snd_seq_control_queue(seq, q, SND_SEQ_EVENT_START, 0, ev)
/**
* \brief stop the specified queue
* \param seq sequencer handle
* \param q queue id to stop
* \param ev optional event record (see #snd_seq_control_queue)
*/
#define snd_seq_stop_queue(seq, q, ev) \
snd_seq_control_queue(seq, q, SND_SEQ_EVENT_STOP, 0, ev)
/**
* \brief continue the specified queue
* \param seq sequencer handle
* \param q queue id to continue
* \param ev optional event record (see #snd_seq_control_queue)
*/
#define snd_seq_continue_queue(seq, q, ev) \
snd_seq_control_queue(seq, q, SND_SEQ_EVENT_CONTINUE, 0, ev)
/**
* \brief change the tempo of the specified queue
* \param seq sequencer handle
* \param q queue id
* \param tempo the new tempo value
* \param ev optional event record (see #snd_seq_control_queue)
*/
#define snd_seq_change_queue_tempo(seq, q, tempo, ev) \
snd_seq_control_queue(seq, q, SND_SEQ_EVENT_TEMPO, tempo, ev)
/* create a port - simple version - return the port number */
int snd_seq_create_simple_port(snd_seq_t *seq, const char *name,
@ -96,12 +265,15 @@ int snd_seq_disconnect_to(snd_seq_t *seq, int my_port, int dest_client, int dest
* set client information
*/
int snd_seq_set_client_name(snd_seq_t *seq, const char *name);
int snd_seq_set_client_group(snd_seq_t *seq, const char *name);
int snd_seq_set_client_filter(snd_seq_t *seq, unsigned int filter);
int snd_seq_set_client_event_filter(snd_seq_t *seq, int event_type);
int snd_seq_set_client_pool_output(snd_seq_t *seq, int size);
int snd_seq_set_client_pool_output_room(snd_seq_t *seq, int size);
int snd_seq_set_client_pool_input(snd_seq_t *seq, int size);
int snd_seq_set_client_pool_output(snd_seq_t *seq, size_t size);
int snd_seq_set_client_pool_output_room(snd_seq_t *seq, size_t size);
int snd_seq_set_client_pool_input(snd_seq_t *seq, size_t size);
/*
* parse the given string and get the sequencer address
*/
int snd_seq_parse_address(snd_seq_t *seq, snd_seq_addr_t *addr, const char *str);
/*
* reset client input/output pool
@ -109,115 +281,129 @@ int snd_seq_set_client_pool_input(snd_seq_t *seq, int size);
int snd_seq_reset_pool_output(snd_seq_t *seq);
int snd_seq_reset_pool_input(snd_seq_t *seq);
/*
* equivalent macros
/**
* \brief set note event
* \param ev event record
* \param ch channel number
* \param key note key
* \param vel velocity
* \param dur duration (in tick or msec)
*/
#define snd_seq_ev_clear(ev) memset(ev, 0, sizeof(snd_seq_event_t))
#define snd_seq_ev_set_dest(ev,c,p) \
((ev)->dest.client = (c), (ev)->dest.port = (p))
#define snd_seq_ev_set_subs(ev) \
((ev)->dest.client = SND_SEQ_ADDRESS_SUBSCRIBERS,\
(ev)->dest.port = SND_SEQ_ADDRESS_UNKNOWN)
#define snd_seq_ev_set_broadcast(ev) \
((ev)->dest.client = SND_SEQ_ADDRESS_BROADCAST,\
(ev)->dest.port = SND_SEQ_ADDRESS_BROADCAST)
#define snd_seq_ev_set_source(ev,p) ((ev)->source.port = (p))
/*
* queue controls
*/
#define snd_seq_ev_set_queue_control(ev,t,q,val) \
((ev)->type = (t),\
snd_seq_ev_set_dest(ev, SND_SEQ_CLIENT_SYSTEM, SND_SEQ_PORT_SYSTEM_TIMER),\
(ev)->data.queue.queue = (q),\
(ev)->data.queue.param.value = (val))
#define snd_seq_ev_set_queue_start(ev,q) \
snd_seq_ev_set_queue_control(ev,SND_SEQ_EVENT_START,q,0)
#define snd_seq_ev_set_queue_stop(ev,q) \
snd_seq_ev_set_queue_control(ev,SND_SEQ_EVENT_STOP,q,0)
#define snd_seq_ev_set_queue_continue(ev,q) \
snd_seq_ev_set_queue_control(ev,SND_SEQ_EVENT_CONTINUE,q,0)
#define snd_seq_ev_set_queue_tempo(ev,q,val) \
snd_seq_ev_set_queue_control(ev,SND_SEQ_EVENT_TEMPO,q,val)
#define snd_seq_ev_set_queue_pos_real(ev,q,rtime) \
((ev)->type = SND_SEQ_EVENT_SETPOS_TIME,\
snd_seq_ev_set_dest(ev, SND_SEQ_CLIENT_SYSTEM, SND_SEQ_PORT_SYSTEM_TIMER),\
(ev)->data.queue.queue = (q),\
(ev)->data.queue.param.time.time = *(rtime))
#define snd_seq_ev_set_queue_pos_tick(ev,q,ttime) \
((ev)->type = SND_SEQ_EVENT_SETPOS_TICK,\
snd_seq_ev_set_dest(ev, SND_SEQ_CLIENT_SYSTEM, SND_SEQ_PORT_SYSTEM_TIMER),\
(ev)->data.queue.queue = (q),\
(ev)->data.queue.param.time.tick = (ttime))
#define snd_seq_start_queue(seq,q,ev) \
snd_seq_control_queue(seq, q, SND_SEQ_EVENT_START, 0, ev)
#define snd_seq_stop_queue(seq,q,ev) \
snd_seq_control_queue(seq, q, SND_SEQ_EVENT_STOP, 0, ev)
#define snd_seq_continue_queue(seq,q,ev) \
snd_seq_control_queue(seq, q, SND_SEQ_EVENT_CONTINUE, 0, ev)
#define snd_seq_change_queue_tempo(seq,q,tempo,ev) \
snd_seq_control_queue(seq, q, SND_SEQ_EVENT_TEMPO, tempo, ev)
/*
* macros to set standard event data
*/
#define snd_seq_ev_set_note(ev,ch,key,vel,dur) \
#define snd_seq_ev_set_note(ev, ch, key, vel, dur) \
((ev)->type = SND_SEQ_EVENT_NOTE,\
snd_seq_ev_set_fixed(ev),\
(ev)->data.note.channel = (ch),\
(ev)->data.note.note = (key),\
(ev)->data.note.velocity = (vel),\
(ev)->data.note.dulation = (dur))
#define snd_seq_ev_set_noteon(ev,ch,key,vel) \
(ev)->data.note.duration = (dur))
/**
* \brief set note-on event
* \param ev event record
* \param ch channel number
* \param key note key
* \param vel velocity
*/
#define snd_seq_ev_set_noteon(ev, ch, key, vel) \
((ev)->type = SND_SEQ_EVENT_NOTEON,\
snd_seq_ev_set_fixed(ev),\
(ev)->data.note.channel = (ch),\
(ev)->data.note.note = (key),\
(ev)->data.note.velocity = (vel))
#define snd_seq_ev_set_noteoff(ev,ch,key,vel) \
/**
* \brief set note-off event
* \param ev event record
* \param ch channel number
* \param key note key
* \param vel velocity
*/
#define snd_seq_ev_set_noteoff(ev, ch, key, vel) \
((ev)->type = SND_SEQ_EVENT_NOTEOFF,\
snd_seq_ev_set_fixed(ev),\
(ev)->data.note.channel = (ch),\
(ev)->data.note.note = (key),\
(ev)->data.note.velocity = (vel))
/**
* \brief set key-pressure event
* \param ev event record
* \param ch channel number
* \param key note key
* \param vel velocity
*/
#define snd_seq_ev_set_keypress(ev,ch,key,vel) \
((ev)->type = SND_SEQ_EVENT_KEYPRESS,\
snd_seq_ev_set_fixed(ev),\
(ev)->data.note.channel = (ch),\
(ev)->data.note.note = (key),\
(ev)->data.note.velocity = (vel))
/**
* \brief set MIDI controller event
* \param ev event record
* \param ch channel number
* \param cc controller number
* \param val control value
*/
#define snd_seq_ev_set_controller(ev,ch,cc,val) \
((ev)->type = SND_SEQ_EVENT_CONTROLLER,\
snd_seq_ev_set_fixed(ev),\
(ev)->data.control.channel = (ch),\
(ev)->data.control.param = (cc),\
(ev)->data.control.value = (val))
/**
* \brief set program change event
* \param ev event record
* \param ch channel number
* \param val program number
*/
#define snd_seq_ev_set_pgmchange(ev,ch,val) \
((ev)->type = SND_SEQ_EVENT_PGMCHANGE,\
snd_seq_ev_set_fixed(ev),\
(ev)->data.control.channel = (ch),\
(ev)->data.control.value = (val))
/**
* \brief set pitchbend event
* \param ev event record
* \param ch channel number
* \param val pitch bend; zero centered from -8192 to 8191
*/
#define snd_seq_ev_set_pitchbend(ev,ch,val) \
((ev)->type = SND_SEQ_EVENT_PITCHBEND,\
snd_seq_ev_set_fixed(ev),\
(ev)->data.control.channel = (ch),\
(ev)->data.control.value = (val))
/**
* \brief set channel pressure event
* \param ev event record
* \param ch channel number
* \param val channel pressure value
*/
#define snd_seq_ev_set_chanpress(ev,ch,val) \
((ev)->type = SND_SEQ_EVENT_CHANPRESS,\
snd_seq_ev_set_fixed(ev),\
(ev)->data.control.channel = (ch),\
(ev)->data.control.value = (val))
/**
* \brief set sysex event
* \param ev event record
* \param datalen length of sysex data
* \param dataptr sysex data pointer
*
* the sysex data must contain the start byte 0xf0 and the end byte 0xf7.
*/
#define snd_seq_ev_set_sysex(ev,datalen,dataptr) \
((ev)->type = SND_SEQ_EVENT_SYSEX,\
snd_seq_ev_set_variable(ev, datalen, dataptr))
/* etc. etc... */
/** \} */
#ifdef __cplusplus
}
#endif
/** \} */