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