SDL_sound_CoreAudio: SDL_sound.h annotate

annotate SDL_sound.h @ 562:7e08477b0fc1

MP3 decoder upgrade work. Ripped out SMPEG and mpglib support, replaced it with "mpg123.c" and libmpg123. libmpg123 is a much better version of mpglib, so it should solve all the problems about MP3's not seeking, or most modern MP3's not playing at all, etc. Since you no longer have to make a tradeoff with SMPEG for features, and SMPEG is basically rotting, I removed it from the project. There is still work to be done with libmpg123...there are MMX, 3DNow, SSE, Altivec, etc decoders which we don't have enabled at the moment, and the build system could use some work to make this compile more cleanly, etc. Still: huge win.

author	Ryan C. Gordon <icculus@icculus.org>
date	Fri, 30 Jan 2009 02:44:47 -0500
parents	2e8907ff98e9
children

rev	line source
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	1 /** \file SDL_sound.h */
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	2
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	3 /*
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	4 * SDL_sound -- An abstract sound format decoding API.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	5 * Copyright (C) 2001 Ryan C. Gordon.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	6 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	7 * This library is free software; you can redistribute it and/or
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	8 * modify it under the terms of the GNU Lesser General Public
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	9 * License as published by the Free Software Foundation; either
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	10 * version 2.1 of the License, or (at your option) any later version.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	11 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	12 * This library is distributed in the hope that it will be useful,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	15 * Lesser General Public License for more details.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	16 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	17 * You should have received a copy of the GNU Lesser General Public
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	18 * License along with this library; if not, write to the Free Software
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	19 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	20 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	21
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	22 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	23 * \mainpage SDL_sound
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	24 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	25 * The latest version of SDL_sound can be found at:
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	26 * http://icculus.org/SDL_sound/
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	27 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	28 * The basic gist of SDL_sound is that you use an SDL_RWops to get sound data
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	29 * into this library, and SDL_sound will take that data, in one of several
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	30 * popular formats, and decode it into raw waveform data in the format of
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	31 * your choice. This gives you a nice abstraction for getting sound into your
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	32 * game or application; just feed it to SDL_sound, and it will handle
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	33 * decoding and converting, so you can just pass it to your SDL audio
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	34 * callback (or whatever). Since it gets data from an SDL_RWops, you can get
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	35 * the initial sound data from any number of sources: file, memory buffer,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	36 * network connection, etc.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	37 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	38 * As the name implies, this library depends on SDL: Simple Directmedia Layer,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	39 * which is a powerful, free, and cross-platform multimedia library. It can
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	40 * be found at http://www.libsdl.org/
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	41 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	42 * Support is in place or planned for the following sound formats:
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	43 * - .WAV (Microsoft WAVfile RIFF data, internal.)
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	44 * - .VOC (Creative Labs' Voice format, internal.)
562 7e08477b0fc1 MP3 decoder upgrade work. Ryan C. Gordon <icculus@icculus.org> parents: 552 diff changeset	45 * - .MP3 (MPEG-1 Layer 3 support, via libmpg123.)
252 c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	46 * - .MID (MIDI music converted to Waveform data, internal.)
c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	47 * - .MOD (MOD files, via MikMod and ModPlug.)
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	48 * - .OGG (Ogg files, via Ogg Vorbis libraries.)
453 b9856ba6fb4e Updated comments on supported files to include Speex. Ryan C. Gordon <icculus@icculus.org> parents: 427 diff changeset	49 * - .SPX (Speex files, via libspeex.)
252 c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	50 * - .SHN (Shorten files, internal.)
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	51 * - .RAW (Raw sound data in any format, internal.)
252 c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	52 * - .AU (Sun's Audio format, internal.)
c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	53 * - .AIFF (Audio Interchange format, internal.)
c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	54 * - .FLAC (Lossless audio compression, via libFLAC.)
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	55 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	56 * (...and more to come...)
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	57 *
552 2e8907ff98e9 Replaced references to COPYING with references to LICENSE.txt ... Ryan C. Gordon <icculus@icculus.org> parents: 526 diff changeset	58 * Please see the file LICENSE.txt in the source's root directory.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	59 *
526 2df1f5c62d38 Updated my email address. Ryan C. Gordon <icculus@icculus.org> parents: 524 diff changeset	60 * \author Ryan C. Gordon (icculus@icculus.org)
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	61 * \author many others, please see CREDITS in the source's root directory.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	62 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	63
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	64 #ifndef _INCLUDE_SDL_SOUND_H_
508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	65 #define _INCLUDE_SDL_SOUND_H_
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	66
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	67 #include "SDL.h"
19 734e5d75acec Now includes SDL_endian.h ... Ryan C. Gordon <icculus@icculus.org> parents: 15 diff changeset	68 #include "SDL_endian.h"
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	69
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	70 #ifdef __cplusplus
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	71 extern "C" {
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	72 #endif
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	73
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	74 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
386 8c8ecd1008c9 Changed DECLSPEC definition. Ryan C. Gordon <icculus@icculus.org> parents: 357 diff changeset	75
8c8ecd1008c9 Changed DECLSPEC definition. Ryan C. Gordon <icculus@icculus.org> parents: 357 diff changeset	76 #ifndef SDLCALL /* may not be defined with older SDL releases. */
8c8ecd1008c9 Changed DECLSPEC definition. Ryan C. Gordon <icculus@icculus.org> parents: 357 diff changeset	77 #define SDLCALL
8c8ecd1008c9 Changed DECLSPEC definition. Ryan C. Gordon <icculus@icculus.org> parents: 357 diff changeset	78 #endif
8c8ecd1008c9 Changed DECLSPEC definition. Ryan C. Gordon <icculus@icculus.org> parents: 357 diff changeset	79
130 ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	80 #ifdef SDL_SOUND_DLL_EXPORTS
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	81 # define SNDDECLSPEC __declspec(dllexport)
524 a0bb7a9c05b1 Added -fvisibility=hidden support. Ryan C. Gordon <icculus@icculus.org> parents: 485 diff changeset	82 #elif (__GNUC__ >= 3)
a0bb7a9c05b1 Added -fvisibility=hidden support. Ryan C. Gordon <icculus@icculus.org> parents: 485 diff changeset	83 # define SNDDECLSPEC __attribute__((visibility("default")))
386 8c8ecd1008c9 Changed DECLSPEC definition. Ryan C. Gordon <icculus@icculus.org> parents: 357 diff changeset	84 #else
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	85 # define SNDDECLSPEC
130 ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	86 #endif
ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	87
427 ba94ffe34a47 Upped version to 1.0.0. Ryan C. Gordon <icculus@icculus.org> parents: 417 diff changeset	88 #define SOUND_VER_MAJOR 1
ba94ffe34a47 Upped version to 1.0.0. Ryan C. Gordon <icculus@icculus.org> parents: 417 diff changeset	89 #define SOUND_VER_MINOR 0
463 6e50a61059b8 Upped version to 1.0.1. Ryan C. Gordon <icculus@icculus.org> parents: 453 diff changeset	90 #define SOUND_VER_PATCH 1
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	91 #endif
29 0e27c909c952 Upped version to 0.1.1 Ryan C. Gordon <icculus@icculus.org> parents: 19 diff changeset	92
0e27c909c952 Upped version to 0.1.1 Ryan C. Gordon <icculus@icculus.org> parents: 19 diff changeset	93
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	94 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	95 * \enum Sound_SampleFlags
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	96 * \brief Flags that are used in a Sound_Sample to show various states.
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	97 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	98 * To use:
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	99 * \code
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	100 * if (sample->flags & SOUND_SAMPLEFLAG_ERROR) { dosomething(); }
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	101 * \endcode
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	102 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	103 * \sa Sound_SampleNew
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	104 * \sa Sound_SampleNewFromFile
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	105 * \sa Sound_SampleDecode
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	106 * \sa Sound_SampleDecodeAll
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	107 * \sa Sound_SampleSeek
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	108 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	109 typedef enum
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	110 {
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	111 SOUND_SAMPLEFLAG_NONE = 0, /*< No special attributes. /
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	112
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	113 /* these are set at sample creation time... */
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	114 SOUND_SAMPLEFLAG_CANSEEK = 1, /*< Sample can seek to arbitrary points. /
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	115
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	116 /* these are set during decoding... */
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	117 SOUND_SAMPLEFLAG_EOF = 1 << 29, /*< End of input stream. /
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	118 SOUND_SAMPLEFLAG_ERROR = 1 << 30, /*< Unrecoverable error. /
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	119 SOUND_SAMPLEFLAG_EAGAIN = 1 << 31 /*< Function would block, or temp error. /
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	120 } Sound_SampleFlags;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	121
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	122
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	123 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	124 * \struct Sound_AudioInfo
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	125 * \brief Information about an existing sample's format.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	126 *
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	127 * These are the basics of a decoded sample's data structure: data format
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	128 * (see AUDIO_U8 and friends in SDL_audio.h), number of channels, and sample
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	129 * rate. If you need more explanation than that, you should stop developing
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	130 * sound code right now.
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	131 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	132 * \sa Sound_SampleNew
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	133 * \sa Sound_SampleNewFromFile
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	134 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	135 typedef struct
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	136 {
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	137 Uint16 format; /*< Equivalent of SDL_AudioSpec.format. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	138 Uint8 channels; /*< Number of sound channels. 1 == mono, 2 == stereo. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	139 Uint32 rate; /*< Sample rate; frequency of sample points per second. /
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	140 } Sound_AudioInfo;
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	141
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	142
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	143 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	144 * \struct Sound_DecoderInfo
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	145 * \brief Information about available soudn decoders.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	146 *
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	147 * Each decoder sets up one of these structs, which can be retrieved via
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	148 * the Sound_AvailableDecoders() function. EVERY FIELD IN THIS IS READ-ONLY.
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	149 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	150 * The extensions field is a NULL-terminated list of ASCIZ strings. You
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	151 * should read it like this:
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	152 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	153 * \code
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	154 * const char **ext;
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	155 * for (ext = info->extensions; *ext != NULL; ext++) {
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	156 * printf(" File extension \"%s\"\n", *ext);
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	157 * }
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	158 * \endcode
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	159 *
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	160 * \sa Sound_AvailableDecoders
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	161 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	162 typedef struct
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	163 {
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	164 const char extensions; /< File extensions, list ends with NULL. */
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	165 const char description; /< Human readable description of decoder. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	166 const char author; /< "Name Of Author \<email@emailhost.dom\>" /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	167 const char url; /< URL specific to this decoder. /
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	168 } Sound_DecoderInfo;
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	169
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	170
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	171
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	172 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	173 * \struct Sound_Sample
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	174 * \brief Represents sound data in the process of being decoded.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	175 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	176 * The Sound_Sample structure is the heart of SDL_sound. This holds
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	177 * information about a source of sound data as it is being decoded.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	178 * EVERY FIELD IN THIS IS READ-ONLY. Please use the API functions to
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	179 * change them.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	180 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	181 typedef struct
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	182 {
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	183 void opaque; /< Internal use only. Don't touch. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	184 const Sound_DecoderInfo decoder; /< Decoder used for this sample. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	185 Sound_AudioInfo desired; /*< Desired audio format for conversion. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	186 Sound_AudioInfo actual; /*< Actual audio format of sample. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	187 void buffer; /< Decoded sound data lands in here. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	188 Uint32 buffer_size; /*< Current size of (buffer), in bytes (Uint8). /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	189 Sound_SampleFlags flags; /*< Flags relating to this sample. /
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	190 } Sound_Sample;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	191
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	192
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	193 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	194 * \struct Sound_Version
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	195 * \brief Information the version of SDL_sound in use.
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	196 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	197 * Represents the library's version as three levels: major revision
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	198 * (increments with massive changes, additions, and enhancements),
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	199 * minor revision (increments with backwards-compatible changes to the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	200 * major revision), and patchlevel (increments with fixes to the minor
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	201 * revision).
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	202 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	203 * \sa SOUND_VERSION
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	204 * \sa Sound_GetLinkedVersion
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	205 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	206 typedef struct
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	207 {
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	208 int major; /*< major revision /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	209 int minor; /*< minor revision /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	210 int patch; /*< patchlevel /
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	211 } Sound_Version;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	212
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	213
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	214 /* functions and macros... */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	215
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	216 /**
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	217 * \def SOUND_VERSION(x)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	218 * \brief Macro to determine SDL_sound version program was compiled against.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	219 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	220 * This macro fills in a Sound_Version structure with the version of the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	221 * library you compiled against. This is determined by what header the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	222 * compiler uses. Note that if you dynamically linked the library, you might
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	223 * have a slightly newer or older version at runtime. That version can be
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	224 * determined with Sound_GetLinkedVersion(), which, unlike SOUND_VERSION,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	225 * is not a macro.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	226 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	227 * \param x A pointer to a Sound_Version struct to initialize.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	228 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	229 * \sa Sound_Version
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	230 * \sa Sound_GetLinkedVersion
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	231 */
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	232 #define SOUND_VERSION(x) \
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	233 { \
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	234 (x)->major = SOUND_VER_MAJOR; \
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	235 (x)->minor = SOUND_VER_MINOR; \
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	236 (x)->patch = SOUND_VER_PATCH; \
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	237 }
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	238
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	239
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	240 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	241 * \fn void Sound_GetLinkedVersion(Sound_Version *ver)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	242 * \brief Get the version of SDL_sound that is linked against your program.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	243 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	244 * If you are using a shared library (DLL) version of SDL_sound, then it is
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	245 * possible that it will be different than the version you compiled against.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	246 *
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	247 * This is a real function; the macro SOUND_VERSION tells you what version
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	248 * of SDL_sound you compiled against:
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	249 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	250 * \code
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	251 * Sound_Version compiled;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	252 * Sound_Version linked;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	253 *
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	254 * SOUND_VERSION(&compiled);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	255 * Sound_GetLinkedVersion(&linked);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	256 * printf("We compiled against SDL_sound version %d.%d.%d ...\n",
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	257 * compiled.major, compiled.minor, compiled.patch);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	258 * printf("But we linked against SDL_sound version %d.%d.%d.\n",
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	259 * linked.major, linked.minor, linked.patch);
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	260 * \endcode
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	261 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	262 * This function may be called safely at any time, even before Sound_Init().
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	263 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	264 * \param ver Sound_Version structure to fill with shared library's version.
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	265 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	266 * \sa Sound_Version
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	267 * \sa SOUND_VERSION
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	268 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	269 SNDDECLSPEC void SDLCALL Sound_GetLinkedVersion(Sound_Version *ver);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	270
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	271
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	272 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	273 * \fn Sound_Init(void)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	274 * \brief Initialize SDL_sound.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	275 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	276 * This must be called before any other SDL_sound function (except perhaps
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	277 * Sound_GetLinkedVersion()). You should call SDL_Init() before calling this.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	278 * Sound_Init() will attempt to call SDL_Init(SDL_INIT_AUDIO), just in case.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	279 * This is a safe behaviour, but it may not configure SDL to your liking by
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	280 * itself.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	281 *
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	282 * \return nonzero on success, zero on error. Specifics of the
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	283 * error can be gleaned from Sound_GetError().
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	284 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	285 * \sa Sound_Quit
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	286 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	287 SNDDECLSPEC int SDLCALL Sound_Init(void);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	288
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	289
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	290 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	291 * \fn Sound_Quit(void)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	292 * \brief Shutdown SDL_sound.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	293 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	294 * This closes any SDL_RWops that were being used as sound sources, and frees
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	295 * any resources in use by SDL_sound.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	296 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	297 * All Sound_Sample pointers you had prior to this call are INVALIDATED.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	298 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	299 * Once successfully deinitialized, Sound_Init() can be called again to
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	300 * restart the subsystem. All default API states are restored at this
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	301 * point.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	302 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	303 * You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit()
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	304 * for you!
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	305 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	306 * \return nonzero on success, zero on error. Specifics of the error
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	307 * can be gleaned from Sound_GetError(). If failure, state of
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	308 * SDL_sound is undefined, and probably badly screwed up.
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	309 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	310 * \sa Sound_Init
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	311 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	312 SNDDECLSPEC int SDLCALL Sound_Quit(void);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	313
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	314
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	315 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	316 * \fn const Sound_DecoderInfo **Sound_AvailableDecoders(void)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	317 * \brief Get a list of sound formats supported by this version of SDL_sound.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	318 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	319 * This is for informational purposes only. Note that the extension listed is
11 5ff1dce70aec Typos. Ryan C. Gordon <icculus@icculus.org> parents: 3 diff changeset	320 * merely convention: if we list "MP3", you can open an MPEG-1 Layer 3 audio
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	321 * file with an extension of "XYZ", if you like. The file extensions are
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	322 * informational, and only required as a hint to choosing the correct
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	323 * decoder, since the sound data may not be coming from a file at all, thanks
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	324 * to the abstraction that an SDL_RWops provides.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	325 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	326 * The returned value is an array of pointers to Sound_DecoderInfo structures,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	327 * with a NULL entry to signify the end of the list:
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	328 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	329 * \code
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	330 * Sound_DecoderInfo **i;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	331 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	332 * for (i = Sound_AvailableDecoders(); *i != NULL; i++)
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	333 * {
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	334 * printf("Supported sound format: [%s], which is [%s].\n",
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	335 * i->extension, i->description);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	336 * // ...and other fields...
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	337 * }
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	338 * \endcode
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	339 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	340 * The return values are pointers to static internal memory, and should
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	341 * be considered READ ONLY, and never freed.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	342 *
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	343 * \return READ ONLY Null-terminated array of READ ONLY structures.
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	344 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	345 * \sa Sound_DecoderInfo
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	346 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	347 SNDDECLSPEC const Sound_DecoderInfo ** SDLCALL Sound_AvailableDecoders(void);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	348
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	349
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	350 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	351 * \fn const char *Sound_GetError(void)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	352 * \brief Get the last SDL_sound error message as a null-terminated string.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	353 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	354 * This will be NULL if there's been no error since the last call to this
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	355 * function. The pointer returned by this call points to an internal buffer,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	356 * and should not be deallocated. Each thread has a unique error state
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	357 * associated with it, but each time a new error message is set, it will
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	358 * overwrite the previous one associated with that thread. It is safe to call
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	359 * this function at anytime, even before Sound_Init().
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	360 *
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	361 * \return READ ONLY string of last error message.
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	362 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	363 * \sa Sound_ClearError
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	364 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	365 SNDDECLSPEC const char * SDLCALL Sound_GetError(void);
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	366
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	367
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	368 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	369 * \fn void Sound_ClearError(void)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	370 * \brief Clear the current error message.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	371 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	372 * The next call to Sound_GetError() after Sound_ClearError() will return NULL.
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	373 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	374 * \sa Sound_GetError
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	375 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	376 SNDDECLSPEC void SDLCALL Sound_ClearError(void);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	377
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	378
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	379 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	380 * \fn Sound_Sample Sound_NewSample(SDL_RWops rw, const char ext, Sound_AudioInfo desired, Uint32 bufferSize)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	381 * \brief Start decoding a new sound sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	382 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	383 * The data is read via an SDL_RWops structure (see SDL_rwops.h in the SDL
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	384 * include directory), so it may be coming from memory, disk, network stream,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	385 * etc. The (ext) parameter is merely a hint to determining the correct
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	386 * decoder; if you specify, for example, "mp3" for an extension, and one of
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	387 * the decoders lists that as a handled extension, then that decoder is given
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	388 * first shot at trying to claim the data for decoding. If none of the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	389 * extensions match (or the extension is NULL), then every decoder examines
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	390 * the data to determine if it can handle it, until one accepts it. In such a
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	391 * case your SDL_RWops will need to be capable of rewinding to the start of
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	392 * the stream.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	393 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	394 * If no decoders can handle the data, a NULL value is returned, and a human
186 70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	395 * readable error message can be fetched from Sound_GetError().
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	396 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	397 * Optionally, a desired audio format can be specified. If the incoming data
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	398 * is in a different format, SDL_sound will convert it to the desired format
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	399 * on the fly. Note that this can be an expensive operation, so it may be
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	400 * wise to convert data before you need to play it back, if possible, or
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	401 * make sure your data is initially in the format that you need it in.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	402 * If you don't want to convert the data, you can specify NULL for a desired
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	403 * format. The incoming format of the data, preconversion, can be found
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	404 * in the Sound_Sample structure.
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	405 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	406 * Note that the raw sound data "decoder" needs you to specify both the
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	407 * extension "RAW" and a "desired" format, or it will refuse to handle
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	408 * the data. This is to prevent it from catching all formats unsupported
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	409 * by the other decoders.
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	410 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	411 * Finally, specify an initial buffer size; this is the number of bytes that
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	412 * will be allocated to store each read from the sound buffer. The more you
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	413 * can safely allocate, the more decoding can be done in one block, but the
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	414 * more resources you have to use up, and the longer each decoding call will
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	415 * take. Note that different data formats require more or less space to
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	416 * store. This buffer can be resized via Sound_SetBufferSize() ...
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	417 *
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	418 * The buffer size specified must be a multiple of the size of a single
186 70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	419 * sample point. So, if you want 16-bit, stereo samples, then your sample
70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	420 * point size is (2 channels * 16 bits), or 32 bits per sample, which is four
70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	421 * bytes. In such a case, you could specify 128 or 132 bytes for a buffer,
70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	422 * but not 129, 130, or 131 (although in reality, you'll want to specify a
70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	423 * MUCH larger buffer).
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	424 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	425 * When you are done with this Sound_Sample pointer, you can dispose of it
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	426 * via Sound_FreeSample().
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	427 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	428 * You do not have to keep a reference to (rw) around. If this function
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	429 * suceeds, it stores (rw) internally (and disposes of it during the call
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	430 * to Sound_FreeSample()). If this function fails, it will dispose of the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	431 * SDL_RWops for you.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	432 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	433 * \param rw SDL_RWops with sound data.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	434 * \param ext File extension normally associated with a data format.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	435 * Can usually be NULL.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	436 * \param desired Format to convert sound data into. Can usually be NULL,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	437 * if you don't need conversion.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	438 * \param bufferSize Size, in bytes, to allocate for the decoding buffer.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	439 * \return Sound_Sample pointer, which is used as a handle to several other
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	440 * SDL_sound APIs. NULL on error. If error, use
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	441 * Sound_GetError() to see what went wrong.
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	442 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	443 * \sa Sound_NewSampleFromFile
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	444 * \sa Sound_SetBufferSize
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	445 * \sa Sound_Decode
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	446 * \sa Sound_DecodeAll
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	447 * \sa Sound_Seek
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	448 * \sa Sound_Rewind
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	449 * \sa Sound_FreeSample
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	450 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	451 SNDDECLSPEC Sound_Sample * SDLCALL Sound_NewSample(SDL_RWops *rw,
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	452 const char *ext,
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	453 Sound_AudioInfo *desired,
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	454 Uint32 bufferSize);
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	455
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	456 /**
485 137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	457 * \fn Sound_Sample Sound_NewSampleFromMem(const Uint8 data, Sound_AudioInfo *desired, Uint32 bufferSize)
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	458 * \brief Start decoding a new sound sample from a file on disk.
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	459 *
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	460 * This is identical to Sound_NewSample(), but it creates an SDL_RWops for you
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	461 * from the (size) bytes of memory referenced by (data).
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	462 *
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	463 * This can pool RWops structures, so it may fragment the heap less over time
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	464 * than using SDL_RWFromMem().
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	465 *
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	466 * \param filename file containing sound data.
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	467 * \param desired Format to convert sound data into. Can usually be NULL,
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	468 * if you don't need conversion.
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	469 * \param bufferSize size, in bytes, of initial read buffer.
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	470 * \return Sound_Sample pointer, which is used as a handle to several other
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	471 * SDL_sound APIs. NULL on error. If error, use
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	472 * Sound_GetError() to see what went wrong.
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	473 *
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	474 * \sa Sound_NewSample
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	475 * \sa Sound_SetBufferSize
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	476 * \sa Sound_Decode
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	477 * \sa Sound_DecodeAll
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	478 * \sa Sound_Seek
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	479 * \sa Sound_Rewind
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	480 * \sa Sound_FreeSample
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	481 */
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	482 SNDDECLSPEC Sound_Sample * SDLCALL Sound_NewSampleFromMem(const Uint8 *data,
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	483 Uint32 size,
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	484 const char *ext,
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	485 Sound_AudioInfo *desired,
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	486 Uint32 bufferSize);
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	487
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	488
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	489 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	490 * \fn Sound_Sample Sound_NewSampleFromFile(const char filename, Sound_AudioInfo *desired, Uint32 bufferSize)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	491 * \brief Start decoding a new sound sample from a file on disk.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	492 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	493 * This is identical to Sound_NewSample(), but it creates an SDL_RWops for you
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	494 * from the file located in (filename). Note that (filename) is specified in
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	495 * platform-dependent notation. ("C:\\music\\mysong.mp3" on windows, and
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	496 * "/home/icculus/music/mysong.mp3" or whatever on Unix, etc.)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	497 * Sound_NewSample()'s "ext" parameter is gleaned from the contents of
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	498 * (filename).
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	499 *
485 137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	500 * This can pool RWops structures, so it may fragment the heap less over time
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	501 * than using SDL_RWFromFile().
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling. Ryan C. Gordon <icculus@icculus.org> parents: 477 diff changeset	502 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	503 * \param filename file containing sound data.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	504 * \param desired Format to convert sound data into. Can usually be NULL,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	505 * if you don't need conversion.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	506 * \param bufferSize size, in bytes, of initial read buffer.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	507 * \return Sound_Sample pointer, which is used as a handle to several other
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	508 * SDL_sound APIs. NULL on error. If error, use
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	509 * Sound_GetError() to see what went wrong.
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	510 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	511 * \sa Sound_NewSample
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	512 * \sa Sound_SetBufferSize
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	513 * \sa Sound_Decode
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	514 * \sa Sound_DecodeAll
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	515 * \sa Sound_Seek
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	516 * \sa Sound_Rewind
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	517 * \sa Sound_FreeSample
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	518 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	519 SNDDECLSPEC Sound_Sample * SDLCALL Sound_NewSampleFromFile(const char *fname,
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	520 Sound_AudioInfo *desired,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	521 Uint32 bufferSize);
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	522
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	523 /**
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	524 * \fn void Sound_FreeSample(Sound_Sample *sample)
389 fced17b9890c Fixed a typo in the comments (and as such, also in the Doxygen output). Ryan C. Gordon <icculus@icculus.org> parents: 386 diff changeset	525 * \brief Dispose of a Sound_Sample.
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	526 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	527 * This will also close/dispose of the SDL_RWops that was used at creation
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	528 * time, so there's no need to keep a reference to that around.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	529 * The Sound_Sample pointer is invalid after this call, and will almost
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	530 * certainly result in a crash if you attempt to keep using it.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	531 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	532 * \param sample The Sound_Sample to delete.
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	533 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	534 * \sa Sound_NewSample
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	535 * \sa Sound_NewSampleFromFile
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	536 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	537 SNDDECLSPEC void SDLCALL Sound_FreeSample(Sound_Sample *sample);
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	538
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	539
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	540 /**
477 3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	541 * \fn Sint32 Sound_GetDuration(Sound_Sample *sample)
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	542 * \brief Retrieve total play time of sample, in milliseconds.
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	543 *
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	544 * Report total time length of sample, in milliseconds. This is a fast
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	545 * call. Duration is calculated during Sound_NewSample*, so this is just
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	546 * an accessor into otherwise opaque data.
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	547 *
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	548 * Please note that not all formats can determine a total time, some can't
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	549 * be exact without fully decoding the data, and thus will estimate the
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	550 * duration. Many decoders will require the ability to seek in the data
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	551 * stream to calculate this, so even if we can tell you how long an .ogg
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	552 * file will be, the same data set may fail if it's, say, streamed over an
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	553 * HTTP connection. Plan accordingly.
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	554 *
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	555 * Most people won't need this function to just decode and playback, but it
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	556 * can be useful for informational purposes in, say, a music player's UI.
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	557 *
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	558 * \param sample Sound_Sample from which to retrieve duration information.
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	559 * \return Sample length in milliseconds, or -1 if duration can't be
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	560 * determined for any reason.
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	561 */
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	562 SNDDECLSPEC Sint32 SDLCALL Sound_GetDuration(Sound_Sample *sample);
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	563
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	564
3e705c9180e5 Fixed binary compatibility, added Sound_GetDuration(). Ryan C. Gordon <icculus@icculus.org> parents: 474 diff changeset	565 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	566 * \fn int Sound_SetBufferSize(Sound_Sample *sample, Uint32 new_size)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	567 * \brief Change the current buffer size for a sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	568 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	569 * If the buffer size could be changed, then the sample->buffer and
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	570 * sample->buffer_size fields will reflect that. If they could not be
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	571 * changed, then your original sample state is preserved. If the buffer is
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	572 * shrinking, the data at the end of buffer is truncated. If the buffer is
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	573 * growing, the contents of the new space at the end is undefined until you
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	574 * decode more into it or initialize it yourself.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	575 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	576 * The buffer size specified must be a multiple of the size of a single
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	577 * sample point. So, if you want 16-bit, stereo samples, then your sample
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	578 * point size is (2 channels * 16 bits), or 32 bits per sample, which is four
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	579 * bytes. In such a case, you could specify 128 or 132 bytes for a buffer,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	580 * but not 129, 130, or 131 (although in reality, you'll want to specify a
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	581 * MUCH larger buffer).
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	582 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	583 * \param sample The Sound_Sample whose buffer to modify.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	584 * \param new_size The desired size, in bytes, of the new buffer.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	585 * \return non-zero if buffer size changed, zero on failure.
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	586 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	587 * \sa Sound_Decode
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	588 * \sa Sound_DecodeAll
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	589 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	590 SNDDECLSPEC int SDLCALL Sound_SetBufferSize(Sound_Sample *sample,
55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	591 Uint32 new_size);
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	592
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	593
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	594 /**
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	595 * \fn Uint32 Sound_Decode(Sound_Sample *sample)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	596 * \brief Decode more of the sound data in a Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	597 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	598 * It will decode at most sample->buffer_size bytes into sample->buffer in the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	599 * desired format, and return the number of decoded bytes.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	600 * If sample->buffer_size bytes could not be decoded, then please refer to
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	601 * sample->flags to determine if this was an end-of-stream or error condition.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	602 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	603 * \param sample Do more decoding to this Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	604 * \return number of bytes decoded into sample->buffer. If it is less than
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	605 * sample->buffer_size, then you should check sample->flags to see
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	606 * what the current state of the sample is (EOF, error, read again).
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	607 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	608 * \sa Sound_DecodeAll
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	609 * \sa Sound_SetBufferSize
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	610 * \sa Sound_Seek
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	611 * \sa Sound_Rewind
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	612 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	613 SNDDECLSPEC Uint32 SDLCALL Sound_Decode(Sound_Sample *sample);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	614
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	615
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	616 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	617 * \fn Uint32 Sound_DecodeAll(Sound_Sample *sample)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	618 * \brief Decode the remainder of the sound data in a Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	619 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	620 * This will dynamically allocate memory for the ENTIRE remaining sample.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	621 * sample->buffer_size and sample->buffer will be updated to reflect the
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	622 * new buffer. Please refer to sample->flags to determine if the decoding
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	623 * finished due to an End-of-stream or error condition.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	624 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	625 * Be aware that sound data can take a large amount of memory, and that
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	626 * this function may block for quite awhile while processing. Also note
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	627 * that a streaming source (for example, from a SDL_RWops that is getting
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	628 * fed from an Internet radio feed that doesn't end) may fill all available
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	629 * memory before giving up...be sure to use this on finite sound sources
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	630 * only!
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	631 *
170 e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	632 * When decoding the sample in its entirety, the work is done one buffer at a
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	633 * time. That is, sound is decoded in sample->buffer_size blocks, and
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	634 * appended to a continually-growing buffer until the decoding completes.
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	635 * That means that this function will need enough RAM to hold approximately
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	636 * sample->buffer_size bytes plus the complete decoded sample at most. The
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	637 * larger your buffer size, the less overhead this function needs, but beware
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	638 * the possibility of paging to disk. Best to make this user-configurable if
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	639 * the sample isn't specific and small.
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	640 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	641 * \param sample Do all decoding for this Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	642 * \return number of bytes decoded into sample->buffer. You should check
170 e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	643 * sample->flags to see what the current state of the sample is
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	644 * (EOF, error, read again).
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	645 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	646 * \sa Sound_Decode
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	647 * \sa Sound_SetBufferSize
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	648 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	649 SNDDECLSPEC Uint32 SDLCALL Sound_DecodeAll(Sound_Sample *sample);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	650
223 249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	651
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	652 /**
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	653 * \fn int Sound_Rewind(Sound_Sample *sample)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	654 * \brief Rewind a sample to the start.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	655 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	656 * Restart a sample at the start of its waveform data, as if newly
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	657 * created with Sound_NewSample(). If successful, the next call to
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	658 * Sound_Decode[All]() will give audio data from the earliest point
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	659 * in the stream.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	660 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	661 * Beware that this function will fail if the SDL_RWops that feeds the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	662 * decoder can not be rewound via it's seek method, but this can
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	663 * theoretically be avoided by wrapping it in some sort of buffering
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	664 * SDL_RWops.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	665 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	666 * This function should ONLY fail if the RWops is not seekable, or
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	667 * SDL_sound is not initialized. Both can be controlled by the application,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	668 * and thus, it is up to the developer's paranoia to dictate whether this
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	669 * function's return value need be checked at all.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	670 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	671 * If this function fails, the state of the sample is undefined, but it
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	672 * is still safe to call Sound_FreeSample() to dispose of it.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	673 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	674 * On success, ERROR, EOF, and EAGAIN are cleared from sample->flags. The
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	675 * ERROR flag is set on error.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	676 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	677 * \param sample The Sound_Sample to rewind.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	678 * \return nonzero on success, zero on error. Specifics of the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	679 * error can be gleaned from Sound_GetError().
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	680 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	681 * \sa Sound_Seek
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	682 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	683 SNDDECLSPEC int SDLCALL Sound_Rewind(Sound_Sample *sample);
223 249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	684
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	685
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	686 /**
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	687 * \fn int Sound_Seek(Sound_Sample *sample, Uint32 ms)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	688 * \brief Seek to a different point in a sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	689 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	690 * Reposition a sample's stream. If successful, the next call to
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	691 * Sound_Decode[All]() will give audio data from the offset you
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	692 * specified.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	693 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	694 * The offset is specified in milliseconds from the start of the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	695 * sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	696 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	697 * Beware that this function can fail for several reasons. If the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	698 * SDL_RWops that feeds the decoder can not seek, this call will almost
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	699 * certainly fail, but this can theoretically be avoided by wrapping it
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	700 * in some sort of buffering SDL_RWops. Some decoders can never seek,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	701 * others can only seek with certain files. The decoders will set a flag
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	702 * in the sample at creation time to help you determine this.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	703 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	704 * You should check sample->flags & SOUND_SAMPLEFLAG_CANSEEK
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	705 * before attempting. Sound_Seek() reports failure immediately if this
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	706 * flag isn't set. This function can still fail for other reasons if the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	707 * flag is set.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	708 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	709 * This function can be emulated in the application with Sound_Rewind()
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	710 * and predecoding a specific amount of the sample, but this can be
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	711 * extremely inefficient. Sound_Seek() accelerates the seek on a
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	712 * with decoder-specific code.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	713 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	714 * If this function fails, the sample should continue to function as if
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	715 * this call was never made. If there was an unrecoverable error,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	716 * sample->flags & SOUND_SAMPLEFLAG_ERROR will be set, which you regular
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	717 * decoding loop can pick up.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	718 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	719 * On success, ERROR, EOF, and EAGAIN are cleared from sample->flags.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	720 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	721 * \param sample The Sound_Sample to seek.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	722 * \param ms The new position, in milliseconds from start of sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	723 * \return nonzero on success, zero on error. Specifics of the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	724 * error can be gleaned from Sound_GetError().
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	725 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	726 * \sa Sound_Rewind
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	727 */
417 55c6695b6038 Fixed SDLCALL nonsense. Should work with Win32/WinCE now, I think. Ryan C. Gordon <icculus@icculus.org> parents: 389 diff changeset	728 SNDDECLSPEC int SDLCALL Sound_Seek(Sound_Sample *sample, Uint32 ms);
305 c345a40a8a99 VERY preliminary work on Sound_Seek() API. Ryan C. Gordon <icculus@icculus.org> parents: 252 diff changeset	729
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	730 #ifdef __cplusplus
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	731 }
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	732 #endif
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	733
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	734 #endif /* !defined _INCLUDE_SDL_SOUND_H_ */
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	735
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	736 /* end of SDL_sound.h ... */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	737

Mercurial > SDL_sound_CoreAudio

annotate SDL_sound.h @ 562:7e08477b0fc1