1 /**
2 * \file include/seqmid.h
3 * \brief Application interface library for the ALSA driver
4 * \author Jaroslav Kysela <perex@perex.cz>
5 * \author Abramo Bagnara <abramo@alsa-project.org>
6 * \author Takashi Iwai <tiwai@suse.de>
7 * \date 1998-2001
8 *
9 * Application interface library for the ALSA driver
10 */
11 /*
12 * This library is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Lesser General Public License as
14 * published by the Free Software Foundation; either version 2.1 of
15 * the License, or (at your option) any later version.
16 *
17 * This program is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Lesser General Public License for more details.
21 *
22 * You should have received a copy of the GNU Lesser General Public
23 * License along with this library; if not, write to the Free Software
24 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
25 *
26 */
27
28 #ifndef __ALSA_SEQMID_H
29 #define __ALSA_SEQMID_H
30
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34
35 /**
36 * \defgroup SeqMiddle Sequencer Middle Level Interface
37 * Sequencer Middle Level Interface
38 * \ingroup Sequencer
39 * \{
40 */
41
42 /**
43 * \brief initialize event record
44 * \param ev event record pointer
45 *
46 * This macro clears the given event record pointer to the default status.
47 */
snd_seq_ev_clear(snd_seq_event_t * ev)48 static inline void snd_seq_ev_clear(snd_seq_event_t *ev)
49 {
50 memset(ev, 0, sizeof(*ev));
51 }
52
53 /**
54 * \brief initialize event record for UMP
55 * \param ev event record pointer
56 *
57 * This macro clears the given UMP event record pointer to the default status.
58 */
snd_seq_ump_ev_clear(snd_seq_ump_event_t * ev)59 static inline void snd_seq_ump_ev_clear(snd_seq_ump_event_t *ev)
60 {
61 memset(ev, 0, sizeof(*ev));
62 }
63
64 /**
65 * \brief set the tag for given event
66 * \param ev event record
67 * \param t event tag
68 *
69 * This macro sets the tag to the given event record.
70 */
71 #define snd_seq_ev_set_tag(ev,t) \
72 ((ev)->tag = (t))
73
74 /**
75 * \brief set the explicit destination
76 * \param ev event record
77 * \param c destination client id
78 * \param p destination port id
79 *
80 * This macro sets the client and port id numbers to the given event record.
81 *
82 * \sa snd_seq_ev_set_subs()
83 */
84 #define snd_seq_ev_set_dest(ev,c,p) \
85 ((ev)->dest.client = (c), (ev)->dest.port = (p))
86
87 /**
88 * \brief set broadcasting to subscribers
89 * \param ev event record
90 *
91 * This macro sets the destination as the subscribers.
92 *
93 * \sa snd_seq_ev_set_dest()
94 */
95 #define snd_seq_ev_set_subs(ev) \
96 ((ev)->dest.client = SND_SEQ_ADDRESS_SUBSCRIBERS,\
97 (ev)->dest.port = SND_SEQ_ADDRESS_UNKNOWN)
98
99 /**
100 * \brief set broadcasting to all clients/ports
101 * \param ev event record
102 *
103 * This macro sets the destination as the broadcasting.
104 *
105 * \sa snd_seq_ev_set_dest()
106 */
107 #define snd_seq_ev_set_broadcast(ev) \
108 ((ev)->dest.client = SND_SEQ_ADDRESS_BROADCAST,\
109 (ev)->dest.port = SND_SEQ_ADDRESS_BROADCAST)
110
111 /**
112 * \brief set the source port
113 * \param ev event record
114 * \param p source port id
115 *
116 * This macro sets the source port id number.
117 */
118 #define snd_seq_ev_set_source(ev,p) \
119 ((ev)->source.port = (p))
120
121 /**
122 * \brief set direct passing mode (without queued)
123 * \param ev event instance
124 *
125 * This macro sets the event to the direct passing mode
126 * to be delivered immediately without queueing.
127 *
128 * \sa snd_seq_ev_schedule_tick(), snd_seq_ev_schedule_real()
129 */
130 #define snd_seq_ev_set_direct(ev) \
131 ((ev)->queue = SND_SEQ_QUEUE_DIRECT)
132
133 /**
134 * \brief set tick-scheduling mode on queue
135 * \param ev event instance
136 * \param q queue id to schedule
137 * \param relative relative time-stamp if non-zero
138 * \param ttick tick time-stamp to be delivered
139 *
140 * This macro sets the scheduling of the event in the
141 * MIDI tick mode.
142 *
143 * \sa snd_seq_ev_schedule_real(), snd_seq_ev_set_direct()
144 */
145 #define snd_seq_ev_schedule_tick(ev, q, relative, ttick) \
146 ((ev)->flags &= ~(SND_SEQ_TIME_STAMP_MASK | SND_SEQ_TIME_MODE_MASK),\
147 (ev)->flags |= SND_SEQ_TIME_STAMP_TICK,\
148 (ev)->flags |= (relative) ? SND_SEQ_TIME_MODE_REL : SND_SEQ_TIME_MODE_ABS,\
149 (ev)->time.tick = (ttick),\
150 (ev)->queue = (q))
151
152 /**
153 * \brief set real-time-scheduling mode on queue
154 * \param ev event instance
155 * \param q queue id to schedule
156 * \param relative relative time-stamp if non-zero
157 * \param rtime time-stamp to be delivered
158 *
159 * This macro sets the scheduling of the event in the
160 * realtime mode.
161 *
162 * \sa snd_seq_ev_schedule_tick(), snd_seq_ev_set_direct()
163 */
164 #define snd_seq_ev_schedule_real(ev, q, relative, rtime) \
165 ((ev)->flags &= ~(SND_SEQ_TIME_STAMP_MASK | SND_SEQ_TIME_MODE_MASK),\
166 (ev)->flags |= SND_SEQ_TIME_STAMP_REAL,\
167 (ev)->flags |= (relative) ? SND_SEQ_TIME_MODE_REL : SND_SEQ_TIME_MODE_ABS,\
168 (ev)->time.time = *(rtime),\
169 (ev)->queue = (q))
170
171 /**
172 * \brief set event priority
173 * \param ev event instance
174 * \param high_prior 1 for high priority mode
175 */
176 #define snd_seq_ev_set_priority(ev, high_prior) \
177 ((ev)->flags &= ~SND_SEQ_PRIORITY_MASK,\
178 (ev)->flags |= (high_prior) ? SND_SEQ_PRIORITY_HIGH : SND_SEQ_PRIORITY_NORMAL)
179
180 /**
181 * \brief set fixed data
182 * \param ev event instance
183 *
184 * Sets the event length mode as fixed size.
185 *
186 * \sa snd_seq_ev_set_variable(), snd_seq_ev_set_varusr()
187 */
188 #define snd_seq_ev_set_fixed(ev) \
189 ((ev)->flags &= ~SND_SEQ_EVENT_LENGTH_MASK,\
190 (ev)->flags |= SND_SEQ_EVENT_LENGTH_FIXED)
191
192 /**
193 * \brief set variable data
194 * \param ev event instance
195 * \param datalen length of the external data
196 * \param dataptr pointer of the external data
197 *
198 * Sets the event length mode as variable length and stores the data.
199 *
200 * \sa snd_seq_ev_set_fixed(), snd_seq_ev_set_varusr()
201 */
202 #define snd_seq_ev_set_variable(ev, datalen, dataptr) \
203 ((ev)->flags &= ~SND_SEQ_EVENT_LENGTH_MASK,\
204 (ev)->flags |= SND_SEQ_EVENT_LENGTH_VARIABLE,\
205 (ev)->data.ext.len = (datalen),\
206 (ev)->data.ext.ptr = (dataptr))
207
208 /**
209 * \brief set varusr data
210 * \param ev event instance
211 * \param datalen length of the external data
212 * \param dataptr pointer of the external data
213 *
214 * Sets the event length mode as variable user-space data and stores the data.
215 *
216 * \sa snd_seq_ev_set_fixed(), snd_seq_ev_set_variable()
217 */
218 #define snd_seq_ev_set_varusr(ev, datalen, dataptr) \
219 ((ev)->flags &= ~SND_SEQ_EVENT_LENGTH_MASK,\
220 (ev)->flags |= SND_SEQ_EVENT_LENGTH_VARUSR,\
221 (ev)->data.ext.len = (datalen),\
222 (ev)->data.ext.ptr = (dataptr))
223
224 /**
225 * \brief set queue controls
226 * \param ev event record
227 * \param typ event type
228 * \param q queue id
229 * \param val control value
230 */
231 #define snd_seq_ev_set_queue_control(ev, typ, q, val) \
232 ((ev)->type = (typ),\
233 snd_seq_ev_set_dest(ev, SND_SEQ_CLIENT_SYSTEM, SND_SEQ_PORT_SYSTEM_TIMER),\
234 (ev)->data.queue.queue = (q),\
235 (ev)->data.queue.param.value = (val))
236
237 /**
238 * \brief set the start queue event
239 * \param ev event record
240 * \param q queue id to start
241 *
242 * \sa snd_seq_ev_set_queue_stop(), snd_seq_ev_set_queue_continue()
243 */
244 #define snd_seq_ev_set_queue_start(ev, q) \
245 snd_seq_ev_set_queue_control(ev, SND_SEQ_EVENT_START, q, 0)
246
247 /**
248 * \brief set the stop queue event
249 * \param ev event record
250 * \param q queue id to stop
251 *
252 * \sa snd_seq_ev_set_queue_start(), snd_seq_ev_set_queue_continue()
253 */
254 #define snd_seq_ev_set_queue_stop(ev, q) \
255 snd_seq_ev_set_queue_control(ev, SND_SEQ_EVENT_STOP, q, 0)
256
257 /**
258 * \brief set the stop queue event
259 * \param ev event record
260 * \param q queue id to continue
261 *
262 * \sa snd_seq_ev_set_queue_start(), snd_seq_ev_set_queue_stop()
263 */
264 #define snd_seq_ev_set_queue_continue(ev, q) \
265 snd_seq_ev_set_queue_control(ev, SND_SEQ_EVENT_CONTINUE, q, 0)
266
267 /**
268 * \brief set the stop queue event
269 * \param ev event record
270 * \param q queue id to change tempo
271 * \param val the new tempo value
272 */
273 #define snd_seq_ev_set_queue_tempo(ev, q, val) \
274 snd_seq_ev_set_queue_control(ev, SND_SEQ_EVENT_TEMPO, q, val)
275
276 /**
277 * \brief set the real-time position of a queue
278 * \param ev event record
279 * \param q queue id to change tempo
280 * \param rtime the new real-time pointer
281 */
282 #define snd_seq_ev_set_queue_pos_real(ev, q, rtime) \
283 ((ev)->type = SND_SEQ_EVENT_SETPOS_TIME,\
284 snd_seq_ev_set_dest(ev, SND_SEQ_CLIENT_SYSTEM, SND_SEQ_PORT_SYSTEM_TIMER),\
285 (ev)->data.queue.queue = (q),\
286 (ev)->data.queue.param.time.time = *(rtime))
287
288 /**
289 * \brief set the tick-time position of a queue
290 * \param ev event record
291 * \param q queue id to change tempo
292 * \param ttime the new tick-time
293 */
294 #define snd_seq_ev_set_queue_pos_tick(ev, q, ttime) \
295 ((ev)->type = SND_SEQ_EVENT_SETPOS_TICK,\
296 snd_seq_ev_set_dest(ev, SND_SEQ_CLIENT_SYSTEM, SND_SEQ_PORT_SYSTEM_TIMER),\
297 (ev)->data.queue.queue = (q),\
298 (ev)->data.queue.param.time.tick = (ttime))
299
300 /**
301 * \brief set the event UMP flag
302 * \param ev event record
303 */
snd_seq_ev_set_ump(snd_seq_ump_event_t * ev)304 static inline void snd_seq_ev_set_ump(snd_seq_ump_event_t *ev)
305 {
306 ev->flags |= SND_SEQ_EVENT_UMP;
307 ev->type = 0; /* unused for UMP */
308 }
309
310 /**
311 * \brief set the event UMP flag and fill UMP raw bytes
312 * \param ev event record
313 * \param data UMP packet data
314 * \param bytes UMP packet size in bytes
315 */
snd_seq_ev_set_ump_data(snd_seq_ump_event_t * ev,void * data,size_t bytes)316 static inline int snd_seq_ev_set_ump_data(snd_seq_ump_event_t *ev, void *data, size_t bytes)
317 {
318 if (bytes > 16)
319 return -EINVAL;
320 snd_seq_ev_set_ump(ev);
321 memcpy(ev->ump, data, bytes);
322 return 0;
323 }
324
325 /* set and send a queue control event */
326 int snd_seq_control_queue(snd_seq_t *seq, int q, int type, int value, snd_seq_event_t *ev);
327
328 /**
329 * \brief start the specified queue
330 * \param seq sequencer handle
331 * \param q queue id to start
332 * \param ev optional event record (see #snd_seq_control_queue)
333 */
334 #define snd_seq_start_queue(seq, q, ev) \
335 snd_seq_control_queue(seq, q, SND_SEQ_EVENT_START, 0, ev)
336
337 /**
338 * \brief stop the specified queue
339 * \param seq sequencer handle
340 * \param q queue id to stop
341 * \param ev optional event record (see #snd_seq_control_queue)
342 */
343 #define snd_seq_stop_queue(seq, q, ev) \
344 snd_seq_control_queue(seq, q, SND_SEQ_EVENT_STOP, 0, ev)
345
346 /**
347 * \brief continue the specified queue
348 * \param seq sequencer handle
349 * \param q queue id to continue
350 * \param ev optional event record (see #snd_seq_control_queue)
351 */
352 #define snd_seq_continue_queue(seq, q, ev) \
353 snd_seq_control_queue(seq, q, SND_SEQ_EVENT_CONTINUE, 0, ev)
354
355 /**
356 * \brief change the tempo of the specified queue
357 * \param seq sequencer handle
358 * \param q queue id
359 * \param tempo the new tempo value
360 * \param ev optional event record (see #snd_seq_control_queue)
361 */
362 #define snd_seq_change_queue_tempo(seq, q, tempo, ev) \
363 snd_seq_control_queue(seq, q, SND_SEQ_EVENT_TEMPO, tempo, ev)
364
365 /* create a port - simple version - return the port number */
366 int snd_seq_create_simple_port(snd_seq_t *seq, const char *name,
367 unsigned int caps, unsigned int type);
368 /* delete the port */
369 int snd_seq_delete_simple_port(snd_seq_t *seq, int port);
370
371 /* simple subscription between this port and another port
372 (w/o exclusive & time conversion)
373 */
374 int snd_seq_connect_from(snd_seq_t *seq, int my_port, int src_client, int src_port);
375 int snd_seq_connect_to(snd_seq_t *seq, int my_port, int dest_client, int dest_port);
376 int snd_seq_disconnect_from(snd_seq_t *seq, int my_port, int src_client, int src_port);
377 int snd_seq_disconnect_to(snd_seq_t *seq, int my_port, int dest_client, int dest_port);
378
379 /*
380 * set client information
381 */
382 int snd_seq_set_client_name(snd_seq_t *seq, const char *name);
383 int snd_seq_set_client_event_filter(snd_seq_t *seq, int event_type);
384 int snd_seq_set_client_midi_version(snd_seq_t *seq, int midi_version);
385 int snd_seq_set_client_ump_conversion(snd_seq_t *seq, int enable);
386 int snd_seq_set_client_pool_output(snd_seq_t *seq, size_t size);
387 int snd_seq_set_client_pool_output_room(snd_seq_t *seq, size_t size);
388 int snd_seq_set_client_pool_input(snd_seq_t *seq, size_t size);
389 /* sync output queue */
390 int snd_seq_sync_output_queue(snd_seq_t *seq);
391
392 /*
393 * parse the given string and get the sequencer address
394 */
395 int snd_seq_parse_address(snd_seq_t *seq, snd_seq_addr_t *addr, const char *str);
396
397 /*
398 * reset client input/output pool
399 */
400 int snd_seq_reset_pool_output(snd_seq_t *seq);
401 int snd_seq_reset_pool_input(snd_seq_t *seq);
402
403 /**
404 * \brief set note event
405 * \param ev event record
406 * \param ch channel number
407 * \param key note key
408 * \param vel velocity
409 * \param dur duration (in tick or msec)
410 */
411 #define snd_seq_ev_set_note(ev, ch, key, vel, dur) \
412 ((ev)->type = SND_SEQ_EVENT_NOTE,\
413 snd_seq_ev_set_fixed(ev),\
414 (ev)->data.note.channel = (ch),\
415 (ev)->data.note.note = (key),\
416 (ev)->data.note.velocity = (vel),\
417 (ev)->data.note.duration = (dur))
418
419 /**
420 * \brief set note-on event
421 * \param ev event record
422 * \param ch channel number
423 * \param key note key
424 * \param vel velocity
425 */
426 #define snd_seq_ev_set_noteon(ev, ch, key, vel) \
427 ((ev)->type = SND_SEQ_EVENT_NOTEON,\
428 snd_seq_ev_set_fixed(ev),\
429 (ev)->data.note.channel = (ch),\
430 (ev)->data.note.note = (key),\
431 (ev)->data.note.velocity = (vel))
432
433 /**
434 * \brief set note-off event
435 * \param ev event record
436 * \param ch channel number
437 * \param key note key
438 * \param vel velocity
439 */
440 #define snd_seq_ev_set_noteoff(ev, ch, key, vel) \
441 ((ev)->type = SND_SEQ_EVENT_NOTEOFF,\
442 snd_seq_ev_set_fixed(ev),\
443 (ev)->data.note.channel = (ch),\
444 (ev)->data.note.note = (key),\
445 (ev)->data.note.velocity = (vel))
446
447 /**
448 * \brief set key-pressure event
449 * \param ev event record
450 * \param ch channel number
451 * \param key note key
452 * \param vel velocity
453 */
454 #define snd_seq_ev_set_keypress(ev,ch,key,vel) \
455 ((ev)->type = SND_SEQ_EVENT_KEYPRESS,\
456 snd_seq_ev_set_fixed(ev),\
457 (ev)->data.note.channel = (ch),\
458 (ev)->data.note.note = (key),\
459 (ev)->data.note.velocity = (vel))
460
461 /**
462 * \brief set MIDI controller event
463 * \param ev event record
464 * \param ch channel number
465 * \param cc controller number
466 * \param val control value
467 */
468 #define snd_seq_ev_set_controller(ev,ch,cc,val) \
469 ((ev)->type = SND_SEQ_EVENT_CONTROLLER,\
470 snd_seq_ev_set_fixed(ev),\
471 (ev)->data.control.channel = (ch),\
472 (ev)->data.control.param = (cc),\
473 (ev)->data.control.value = (val))
474
475 /**
476 * \brief set program change event
477 * \param ev event record
478 * \param ch channel number
479 * \param val program number
480 */
481 #define snd_seq_ev_set_pgmchange(ev,ch,val) \
482 ((ev)->type = SND_SEQ_EVENT_PGMCHANGE,\
483 snd_seq_ev_set_fixed(ev),\
484 (ev)->data.control.channel = (ch),\
485 (ev)->data.control.value = (val))
486
487 /**
488 * \brief set pitch-bend event
489 * \param ev event record
490 * \param ch channel number
491 * \param val pitch bend; zero centered from -8192 to 8191
492 */
493 #define snd_seq_ev_set_pitchbend(ev,ch,val) \
494 ((ev)->type = SND_SEQ_EVENT_PITCHBEND,\
495 snd_seq_ev_set_fixed(ev),\
496 (ev)->data.control.channel = (ch),\
497 (ev)->data.control.value = (val))
498
499 /**
500 * \brief set channel pressure event
501 * \param ev event record
502 * \param ch channel number
503 * \param val channel pressure value
504 */
505 #define snd_seq_ev_set_chanpress(ev,ch,val) \
506 ((ev)->type = SND_SEQ_EVENT_CHANPRESS,\
507 snd_seq_ev_set_fixed(ev),\
508 (ev)->data.control.channel = (ch),\
509 (ev)->data.control.value = (val))
510
511 /**
512 * \brief set sysex event
513 * \param ev event record
514 * \param datalen length of sysex data
515 * \param dataptr sysex data pointer
516 *
517 * the sysex data must contain the start byte 0xf0 and the end byte 0xf7.
518 */
519 #define snd_seq_ev_set_sysex(ev,datalen,dataptr) \
520 ((ev)->type = SND_SEQ_EVENT_SYSEX,\
521 snd_seq_ev_set_variable(ev, datalen, dataptr))
522
523 /** \} */
524
525 #ifdef __cplusplus
526 }
527 #endif
528
529 #endif /* __ALSA_SEQMID_H */
530
531