← Back to branch summary

~ubuntu-branches/ubuntu/maverick/alsa-lib/maverick-proposed

« back to all changes in this revision

Viewing changes to src/seq/seq_midi_event.c

  • Committer: Bazaar Package Importer
  • Author(s): Jordi Mallach
  • Date: 2009-09-14 21:56:13 UTC
  • mto: (2.2.4 squeeze) (1.1.12 upstream)
  • mto: This revision was merged to the branch mainline in revision 59.
  • Revision ID: james.westby@ubuntu.com-20090914215613-8n8y0d3ruo41l9dg
Import upstream version 1.0.21a

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/seq/seq_midi_event.c
129
129
#endif /* DOC_HIDDEN */
130
130
 
131
131
/**
132
 
 * \brief Initialize MIDI event parser
133
 
 * \param bufsize buffer size for MIDI message
134
 
 * \param rdev allocated MIDI event parser
135
 
 * \return 0 on success otherwise a negative error code
136
 
 *
137
 
 * Allocates and initializes MIDI event parser.
 
132
 * \brief Creates a MIDI event parser.
 
133
 * \param[in] bufsize Size of the buffer used for encoding; this should be
 
134
 *                    large enough to hold the largest MIDI message to be
 
135
 *                    encoded.
 
136
 * \param[out] rdev The new MIDI event parser.
 
137
 * \return Zero on success, otherwise a negative error code.
 
138
 *
 
139
 * This function creates and initializes a MIDI parser object that can be used
 
140
 * to convert a MIDI byte stream to sequencer events (encoding) and/or to
 
141
 * convert sequencer events to a MIDI byte stream (decoding).
 
142
 *
 
143
 * \par Errors:
 
144
 * <dl>
 
145
 * <dt>-ENOMEM<dd>Out of memory.
 
146
 *
 
147
 * \par Conforming to:
 
148
 * LSB 3.2
138
149
 */
139
150
int snd_midi_event_new(size_t bufsize, snd_midi_event_t **rdev)
140
151
{
159
170
}
160
171
 
161
172
/**
162
 
 * \brief Free MIDI event parser
163
 
 * \param dev MIDI event parser
164
 
 * \return 0 on success otherwise a negative error code
165
 
 *
166
 
 * Frees MIDI event parser.
 
173
 * \brief Frees a MIDI event parser.
 
174
 * \param dev MIDI event parser.
 
175
 *
 
176
 * Frees a MIDI event parser.
 
177
 *
 
178
 * \par Conforming to:
 
179
 * LSB 3.2
167
180
 */
168
181
void snd_midi_event_free(snd_midi_event_t *dev)
169
182
{
174
187
}
175
188
 
176
189
/**
177
 
 * \brief Enable/disable MIDI command merging
178
 
 * \param dev MIDI event parser
179
 
 * \param on 0 - enable MIDI command merging, 1 - always pass the command
180
 
 *
181
 
 * Enable/disable MIDI command merging
 
190
 * \brief Enables/disables MIDI command merging.
 
191
 * \param dev MIDI event parser.
 
192
 * \param on 0 to enable MIDI command merging,
 
193
 *           1 to always write the command byte.
 
194
 *
 
195
 * This function enables or disables MIDI command merging (running status).
 
196
 *
 
197
 * When MIDI command merging is not disabled, #snd_midi_event_decode is allowed
 
198
 * to omit any status byte that is identical to the previous status byte.
182
199
 */
183
200
void snd_midi_event_no_status(snd_midi_event_t *dev, int on)
184
201
{
196
213
}
197
214
 
198
215
/**
199
 
 * \brief Reset MIDI encode parser
200
 
 * \param dev MIDI event parser
201
 
 * \return 0 on success otherwise a negative error code
202
 
 *
203
 
 * Resets MIDI encode parser
 
216
 * \brief Resets MIDI encode parser.
 
217
 * \param dev MIDI event parser.
 
218
 *
 
219
 * This function resets the MIDI encoder of the parser \a dev.
 
220
 * Any partially encoded MIDI message is dropped,
 
221
 * and running status state is cleared.
 
222
 *
 
223
 * \par Conforming to:
 
224
 * LSB 3.2
204
225
 */
205
226
void snd_midi_event_reset_encode(snd_midi_event_t *dev)
206
227
{
208
229
}
209
230
 
210
231
/**
211
 
 * \brief Reset MIDI decode parser
212
 
 * \param dev MIDI event parser
213
 
 * \return 0 on success otherwise a negative error code
214
 
 *
215
 
 * Resets MIDI decode parser
 
232
 * \brief Resets MIDI decode parser.
 
233
 * \param dev MIDI event parser.
 
234
 *
 
235
 * This function resets the MIDI decoder of the parser \a dev.
 
236
 * The next decoded message does not use running status from before the call to
 
237
 * \a snd_midi_event_reset_decode.
 
238
 *
 
239
 * \par Conforming to:
 
240
 * LSB 3.2
216
241
 */
217
242
void snd_midi_event_reset_decode(snd_midi_event_t *dev)
218
243
{
220
245
}
221
246
 
222
247
/**
223
 
 * \brief Initializes MIDI parsers
224
 
 * \param dev MIDI event parser
225
 
 * \return 0 on success otherwise a negative error code
226
 
 *
227
 
 * Initializes MIDI parsers (both encode and decode)
 
248
 * \brief Resets MIDI encode/decode parsers.
 
249
 * \param dev MIDI event parser.
 
250
 *
 
251
 * This function resets both encoder and decoder of the MIDI event parser.
 
252
 * \sa snd_midi_event_reset_encode, snd_midi_event_reset_decode
 
253
 *
 
254
 * \par Conforming to:
 
255
 * LSB 3.2
228
256
 */
229
257
void snd_midi_event_init(snd_midi_event_t *dev)
230
258
{
233
261
}
234
262
 
235
263
/**
236
 
 * \brief Resize MIDI message (event) buffer
237
 
 * \param dev MIDI event parser
238
 
 * \param bufsize new requested buffer size
239
 
 * \return 0 on success otherwise a negative error code
240
 
 *
241
 
 * Resizes MIDI message (event) buffer.
 
264
 * \brief Resizes the MIDI message encoding buffer.
 
265
 * \param dev MIDI event parser.
 
266
 * \param bufsize The new buffer size.
 
267
 * \return Zero on success, otherwise a negative error code.
 
268
 *
 
269
 * This function resizes the buffer that is used to hold partially encoded MIDI
 
270
 * messages.
 
271
 *
 
272
 * If there is a partially encoded message in the buffer, it is dropped.
 
273
 *
 
274
 * \par Errors:
 
275
 * <dl>
 
276
 * <dt>-ENOMEM<dd>Out of memory.
 
277
 *
 
278
 * \sa snd_midi_event_encode, snd_midi_event_reset_encode
242
279
 */
243
280
int snd_midi_event_resize_buffer(snd_midi_event_t *dev, size_t bufsize)
244
281
{
258
295
}
259
296
 
260
297
/**
261
 
 * \brief Read bytes and encode to sequencer event if finished
262
 
 * \param dev MIDI event parser
263
 
 * \param buf MIDI byte stream
264
 
 * \param count count of bytes of MIDI byte stream to encode
265
 
 * \param ev Result - sequencer event
266
 
 * \return count of encoded bytes otherwise a negative error code
267
 
 *
268
 
 * Read bytes and encode to sequencer event if finished.
269
 
 * If complete sequencer event is available, ev->type is not
270
 
 * equal to #SND_SEQ_EVENT_NONE.
 
298
 * \brief Encodes bytes to sequencer event.
 
299
 * \param[in] dev MIDI event parser.
 
300
 * \param[in] buf Buffer containing bytes of a raw MIDI stream.
 
301
 * \param[in] count Number of bytes in \a buf.
 
302
 * \param[out] ev Sequencer event.
 
303
 * \return The number of bytes consumed, or a negative error code.
 
304
 *
 
305
 * This function tries to use up to \a count bytes from the beginning of the
 
306
 * buffer to encode a sequencer event.  If a complete MIDI message has been
 
307
 * encoded, the sequencer event is written to \a ev; otherwise, \a ev->type is
 
308
 * set to #SND_SEQ_EVENT_NONE, and further bytes are required to complete
 
309
 * a message.
 
310
 *
 
311
 * The buffer in \a dev is used to hold any bytes of a not-yet-complete MIDI
 
312
 * message.  If a System Exclusive message is larger than the buffer, the
 
313
 * message is split into multiple parts, and a sequencer event is returned at
 
314
 * the end of each part.
 
315
 *
 
316
 * Any bytes that are not part of a valid MIDI message are silently ignored,
 
317
 * i.e., they are consumed without signaling an error.
 
318
 *
 
319
 * When this function returns a system exclusive sequencer event (\a ev->type
 
320
 * is #SND_SEQ_EVENT_SYSEX), the data pointer (\a ev->data.ext.ptr) points into
 
321
 * the MIDI event parser's buffer.  Therefore, the sequencer event can only be
 
322
 * used as long as that buffer remains valid, i.e., until the next call to
 
323
 * #snd_midi_event_encode, #snd_midi_event_encode_byte,
 
324
 * #snd_midi_event_resize_buffer, #snd_midi_event_init,
 
325
 * #snd_midi_event_reset_encode, or #snd_midi_event_free for that MIDI event
 
326
 * parser.
 
327
 *
 
328
 * This function can generate any sequencer event that corresponds to a MIDI
 
329
 * message, i.e.:
 
330
 * - #SND_SEQ_EVENT_NOTEOFF
 
331
 * - #SND_SEQ_EVENT_NOTEON
 
332
 * - #SND_SEQ_EVENT_KEYPRESS
 
333
 * - #SND_SEQ_EVENT_CONTROLLER
 
334
 * - #SND_SEQ_EVENT_PGMCHANGE
 
335
 * - #SND_SEQ_EVENT_CHANPRESS
 
336
 * - #SND_SEQ_EVENT_PITCHBEND
 
337
 * - #SND_SEQ_EVENT_SYSEX
 
338
 * - #SND_SEQ_EVENT_QFRAME
 
339
 * - #SND_SEQ_EVENT_SONGPOS
 
340
 * - #SND_SEQ_EVENT_SONGSEL
 
341
 * - #SND_SEQ_EVENT_TUNE_REQUEST
 
342
 * - #SND_SEQ_EVENT_CLOCK
 
343
 * - #SND_SEQ_EVENT_START
 
344
 * - #SND_SEQ_EVENT_CONTINUE
 
345
 * - #SND_SEQ_EVENT_STOP
 
346
 * - #SND_SEQ_EVENT_SENSING
 
347
 * - #SND_SEQ_EVENT_RESET
 
348
 * .
 
349
 * Some implementations may also be able to generate the following events
 
350
 * for a sequence of controller change messages:
 
351
 * - #SND_SEQ_EVENT_CONTROL14
 
352
 * - #SND_SEQ_EVENT_NONREGPARAM
 
353
 * - #SND_SEQ_EVENT_REGPARAM
 
354
 *
 
355
 * \par Conforming to:
 
356
 * LSB 3.2
 
357
 *
 
358
 * \sa snd_midi_event_new, snd_midi_event_reset_encode, snd_midi_event_encode_byte
271
359
 */
272
360
long snd_midi_event_encode(snd_midi_event_t *dev, const unsigned char *buf, long count, snd_seq_event_t *ev)
273
361
{
289
377
}
290
378
 
291
379
/**
292
 
 * \brief Read one byte and encode to sequencer event if finished
293
 
 * \param dev MIDI event parser
294
 
 * \param c a byte of MIDI stream
295
 
 * \param ev Result - sequencer event
296
 
 * \return 1 - sequencer event is completed, 0 - next byte is required for completion, otherwise a negative error code
297
 
 *
298
 
 * Read byte and encode to sequencer event if finished.
 
380
 * \brief Encodes byte to sequencer event.
 
381
 * \param[in] dev MIDI event parser.
 
382
 * \param[in] c A byte of a raw MIDI stream.
 
383
 * \param[out] ev Sequencer event.
 
384
 * \return 1 if a sequenver event has been completed, 0 if more bytes are
 
385
 *         required to complete an event, or a negative error code.
 
386
 *
 
387
 * This function tries to use the byte \a c to encode a sequencer event.  If
 
388
 * a complete MIDI message has been encoded, the sequencer event is written to
 
389
 * \a ev; otherwise, further bytes are required to complete a message.
 
390
 *
 
391
 * See also the description of #snd_midi_event_encode.
 
392
 *
 
393
 * \par Conforming to:
 
394
 * LSB 3.2
 
395
 *
 
396
 * \sa snd_midi_event_new, snd_midi_event_reset_encode, snd_midi_event_encode
299
397
 */
300
398
int snd_midi_event_encode_byte(snd_midi_event_t *dev, int c, snd_seq_event_t *ev)
301
399
{
405
503
}
406
504
 
407
505
/**
408
 
 * \brief Decode sequencer event to MIDI byte stream
409
 
 * \param dev MIDI event parser
410
 
 * \param buf Result - MIDI byte stream
411
 
 * \param count Available bytes in MIDI byte stream
412
 
 * \param ev Event to decode
413
 
 * \return count of decoded bytes otherwise a negative error code
414
 
 *
415
 
 * Decode sequencer event to MIDI byte stream.
 
506
 * \brief Decodes sequencer event to MIDI byte stream.
 
507
 * \param[in] dev MIDI event parser.
 
508
 * \param[out] buf Buffer for the resulting MIDI byte stream.
 
509
 * \param[in] count Number of bytes in \a buf.
 
510
 * \param[in] ev The sequencer event to decode.
 
511
 * \return The number of bytes written to \a buf, or a negative error code.
 
512
 *
 
513
 * This function tries to decode the sequencer event into one or more MIDI
 
514
 * messages, and writes the raw MIDI byte(s) into \a buf.
 
515
 *
 
516
 * The generated MIDI messages may use running status, unless disabled with
 
517
 * #snd_midi_event_no_status.
 
518
 *
 
519
 * The required buffer size for a sequencer event it as most 12 bytes, except
 
520
 * for System Exclusive events (\a ev->type == #SND_SEQ_EVENT_SYSEX) which can
 
521
 * have any length (as specified by \a ev->data.ext.len).
 
522
 *
 
523
 * The following sequencer events correspond to MIDI messages:
 
524
 * - #SND_SEQ_EVENT_NOTEOFF
 
525
 * - #SND_SEQ_EVENT_NOTEON
 
526
 * - #SND_SEQ_EVENT_KEYPRESS
 
527
 * - #SND_SEQ_EVENT_CONTROLLER
 
528
 * - #SND_SEQ_EVENT_PGMCHANGE
 
529
 * - #SND_SEQ_EVENT_CHANPRESS
 
530
 * - #SND_SEQ_EVENT_PITCHBEND
 
531
 * - #SND_SEQ_EVENT_SYSEX
 
532
 * - #SND_SEQ_EVENT_QFRAME
 
533
 * - #SND_SEQ_EVENT_SONGPOS
 
534
 * - #SND_SEQ_EVENT_SONGSEL
 
535
 * - #SND_SEQ_EVENT_TUNE_REQUEST
 
536
 * - #SND_SEQ_EVENT_CLOCK
 
537
 * - #SND_SEQ_EVENT_START
 
538
 * - #SND_SEQ_EVENT_CONTINUE
 
539
 * - #SND_SEQ_EVENT_STOP
 
540
 * - #SND_SEQ_EVENT_SENSING
 
541
 * - #SND_SEQ_EVENT_RESET
 
542
 * - #SND_SEQ_EVENT_CONTROL14
 
543
 * - #SND_SEQ_EVENT_NONREGPARAM
 
544
 * - #SND_SEQ_EVENT_REGPARAM
 
545
 *
 
546
 * \par Errors:
 
547
 * <dl>
 
548
 * <dt>-EINVAL<dd>\a ev is not a valid sequencer event.
 
549
 * <dt>-ENOENT<dd>The sequencer event does not correspond to one or more MIDI messages.
 
550
 * <dt>-ENOMEM<dd>The MIDI message(s) would not fit into \a count bytes.
 
551
 *
 
552
 * \par Conforming to:
 
553
 * LSB 3.2
 
554
 *
 
555
 * \sa snd_midi_event_reset_decode, snd_midi_event_no_status
416
556
 */
417
557
long snd_midi_event_decode(snd_midi_event_t *dev, unsigned char *buf, long count, const snd_seq_event_t *ev)
418
558
{
442
582
 
443
583
 
444
584
        if (cmd == MIDI_CMD_COMMON_SYSEX) {
 
585
                snd_midi_event_reset_decode(dev);
445
586
                qlen = ev->data.ext.len;
446
587
                if (count < qlen)
447
588
                        return -ENOMEM;
566
707
        if (dev->nostat && count < 12)
567
708
                return -ENOMEM;
568
709
        cmd = MIDI_CMD_CONTROL|(ev->data.control.channel & 0x0f);
569
 
        bytes[0] = ev->data.control.param & 0x007f;
570
 
        bytes[1] = (ev->data.control.param & 0x3f80) >> 7;
571
 
        bytes[2] = ev->data.control.value & 0x007f;
572
 
        bytes[3] = (ev->data.control.value & 0x3f80) >> 7;
 
710
        bytes[0] = (ev->data.control.param & 0x3f80) >> 7;
 
711
        bytes[1] = ev->data.control.param & 0x007f;
 
712
        bytes[2] = (ev->data.control.value & 0x3f80) >> 7;
 
713
        bytes[3] = ev->data.control.value & 0x007f;
573
714
        if (cmd != dev->lastcmd && !dev->nostat) {
574
715
                if (count < 9)
575
716
                        return -ENOMEM;