Mercurial > SDL_sound_CoreAudio

comparison SDL_sound.h @ 305:c345a40a8a99

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
VERY preliminary work on Sound_Seek() API.
author Ryan C. Gordon <icculus@icculus.org>
date Sun, 21 Apr 2002 17:48:11 +0000
parents c54eae85f5f1
children 2740fad98dfe
comparison
equal deleted inserted replaced
304:0cf2b2e4a259 305:c345a40a8a99
35 * be found at http://www.libsdl.org/ 35 * be found at http://www.libsdl.org/
36 * 36 *
37 * Support is in place or planned for the following sound formats: 37 * Support is in place or planned for the following sound formats:
38 * - .WAV (Microsoft WAVfile RIFF data, internal.) 38 * - .WAV (Microsoft WAVfile RIFF data, internal.)
39 * - .VOC (Creative Labs' Voice format, internal.) 39 * - .VOC (Creative Labs' Voice format, internal.)
40 * - .MP3 (MPEG-1 Layer 3 support, via the SMPEG library.) 40 * - .MP3 (MPEG-1 Layer 3 support, via the SMPEG and mpglib libraries.)
41 * - .MID (MIDI music converted to Waveform data, internal.) 41 * - .MID (MIDI music converted to Waveform data, internal.)
42 * - .MOD (MOD files, via MikMod and ModPlug.) 42 * - .MOD (MOD files, via MikMod and ModPlug.)
43 * - .OGG (Ogg files, via Ogg Vorbis libraries.) 43 * - .OGG (Ogg files, via Ogg Vorbis libraries.)
44 * - .SHN (Shorten files, internal.) 44 * - .SHN (Shorten files, internal.)
45 * - .RAW (Raw sound data in any format, internal.) 45 * - .RAW (Raw sound data in any format, internal.)
79 * These are flags that are used in a Sound_Sample to show various states. 79 * These are flags that are used in a Sound_Sample to show various states.
80 * 80 *
81 * To use: "if (sample->flags & SOUND_SAMPLEFLAG_ERROR) { dosomething(); }" 81 * To use: "if (sample->flags & SOUND_SAMPLEFLAG_ERROR) { dosomething(); }"
82 * 82 *
83 * @param SOUND_SAMPLEFLAG_NONE null flag. 83 * @param SOUND_SAMPLEFLAG_NONE null flag.
84 * @param SOUND_SAMPLEFLAG_NEEDSEEK SDL_RWops must be able to seek. 84 * @param SOUND_SAMPLEFLAG_CANSEEK sample can seek to arbitrary points.
85 * @param SOUND_SAMPLEFLAG_EOF end of input stream. 85 * @param SOUND_SAMPLEFLAG_EOF end of input stream.
86 * @param SOUND_SAMPLEFLAG_ERROR unrecoverable error. 86 * @param SOUND_SAMPLEFLAG_ERROR unrecoverable error.
87 * @param SOUND_SAMPLEFLAG_EAGAIN function would block, or temp error. 87 * @param SOUND_SAMPLEFLAG_EAGAIN function would block, or temp error.
88 */ 88 */
89 typedef enum __SOUND_SAMPLEFLAGS__ 89 typedef enum __SOUND_SAMPLEFLAGS__
90 { 90 {
91 SOUND_SAMPLEFLAG_NONE = 0, 91 SOUND_SAMPLEFLAG_NONE = 0,
92 92
93 /* these are set at sample creation time... */ 93 /* these are set at sample creation time... */
94 SOUND_SAMPLEFLAG_NEEDSEEK = 1, 94 SOUND_SAMPLEFLAG_CANSEEK = 1,
95 95
96 /* these are set during decoding... */ 96 /* these are set during decoding... */
97 SOUND_SAMPLEFLAG_EOF = 1 << 29, 97 SOUND_SAMPLEFLAG_EOF = 1 << 29,
98 SOUND_SAMPLEFLAG_ERROR = 1 << 30, 98 SOUND_SAMPLEFLAG_ERROR = 1 << 30,
99 SOUND_SAMPLEFLAG_EAGAIN = 1 << 31 99 SOUND_SAMPLEFLAG_EAGAIN = 1 << 31
484 * error can be gleaned from Sound_GetError(). 484 * error can be gleaned from Sound_GetError().
485 */ 485 */
486 extern DECLSPEC int Sound_Rewind(Sound_Sample *sample); 486 extern DECLSPEC int Sound_Rewind(Sound_Sample *sample);
487 487
488 488
489 /**
490 * Reposition a sample's stream. If successful, the next call to
491 * Sound_Decode[All]() will give audio data from the offset you
492 * specified.
493 *
494 * The offset is specified in milliseconds from the start of the
495 * sample.
496 *
497 * Beware that this function can fail for several reasons. If the
498 * SDL_RWops that feeds the decoder can not seek, this call will almost
499 * certainly fail, but this can theoretically be avoided by wrapping it
500 * in some sort of buffering SDL_RWops. Some decoders can never seek,
501 * others can only seek with certain files. The decoders will set a flag
502 * in the sample at creation time to help you determine this.
503 *
504 * You should check sample->flags & SOUND_SAMPLEFLAG_CANSEEK
505 * before attempting. Sound_Seek() reports failure immediately if this
506 * flag isn't set. This function can still fail for other reasons if the
507 * flag is set.
508 *
509 * This function can be emulated in the application with Sound_Rewind()
510 * and predecoding a specific amount of the sample, but this can be
511 * extremely inefficient. Sound_Seek() accelerates the seek on a
512 * with decoder-specific code.
513 *
514 * If this function fails, the sample should continue to function as if
515 * this call was never made. If there was an unrecoverable error,
516 * sample->flags & SOUND_SAMPLEFLAG_ERROR will be set, which you regular
517 * decoding loop can pick up.
518 *
519 * On success, ERROR, EOF, and EAGAIN are cleared from sample->flags.
520 *
521 * @param sample The Sound_Sample to seek.
522 * @param ms The new position, in milliseconds from start of sample.
523 * @return nonzero on success, zero on error. Specifics of the
524 * error can be gleaned from Sound_GetError().
525 */
526 extern DECLSPEC int Sound_Seek(Sound_Sample *sample, Uint32 ms);
527
528
489 #ifdef __cplusplus 529 #ifdef __cplusplus
490 } 530 }
491 #endif 531 #endif
492 532
493 #endif /* !defined _INCLUDE_SDL_SOUND_H_ */ 533 #endif /* !defined _INCLUDE_SDL_SOUND_H_ */