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 */ 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 */ 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 */ 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 */ 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