|
0
|
1 /*
|
|
|
2 * SDL_sound -- An abstract sound format decoding API.
|
|
|
3 * Copyright (C) 2001 Ryan C. Gordon.
|
|
|
4 *
|
|
|
5 * This library is free software; you can redistribute it and/or
|
|
|
6 * modify it under the terms of the GNU Lesser General Public
|
|
|
7 * License as published by the Free Software Foundation; either
|
|
|
8 * version 2.1 of the License, or (at your option) any later version.
|
|
|
9 *
|
|
|
10 * This library is distributed in the hope that it will be useful,
|
|
|
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
|
13 * Lesser General Public License for more details.
|
|
|
14 *
|
|
|
15 * You should have received a copy of the GNU Lesser General Public
|
|
|
16 * License along with this library; if not, write to the Free Software
|
|
|
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
|
18 */
|
|
|
19
|
|
|
20 /**
|
|
|
21 * The basic gist of SDL_sound is that you use an SDL_RWops to get sound data
|
|
|
22 * into this library, and SDL_sound will take that data, in one of several
|
|
|
23 * popular formats, and decode it into raw waveform data in the format of
|
|
|
24 * your choice. This gives you a nice abstraction for getting sound into your
|
|
|
25 * game or application; just feed it to SDL_sound, and it will handle
|
|
|
26 * decoding and converting, so you can just pass it to your SDL audio
|
|
|
27 * callback (or whatever). Since it gets data from a SDL_RWops, you can get
|
|
|
28 * the initial sound data from any number of sources: file, memory buffer,
|
|
|
29 * network connection, etc.
|
|
|
30 *
|
|
|
31 * As the name implies, this library depends on SDL: Simple Directmedia Layer,
|
|
|
32 * which is a powerful, free, and cross-platform multimedia library. It can
|
|
|
33 * be found at http://www.libsdl.org/
|
|
|
34 *
|
|
|
35 * Support is in place or planned for the following sound formats:
|
|
|
36 * - .WAV (Microsoft WAVfile RIFF data, internal.)
|
|
|
37 * - .VOC (Creative Labs' Voice format, internal.)
|
|
|
38 * - .MP3 (MPEG-1 layer 3 support, via the SMPEG library.)
|
|
|
39 * - .MID (MIDI music converted to Waveform data, via Timidity.)
|
|
|
40 * - .MOD (MOD files, via MikMod.)
|
|
|
41 * - .OGG (Ogg files, via Ogg Vorbis libraries.)
|
|
|
42 * - .RAWDATA (Raw sound data in any format, internal.)
|
|
|
43 * - .CDA (CD audio read into a sound buffer, internal.)
|
|
|
44 *
|
|
|
45 * (...and more to come...)
|
|
|
46 *
|
|
|
47 * Please see the file LICENSE in the source's root directory.
|
|
|
48 *
|
|
|
49 * This file written by Ryan C. Gordon. (icculus@clutteredmind.org)
|
|
|
50 */
|
|
|
51
|
|
|
52 #ifndef _INCLUDE_SDL_VOICE_H_
|
|
|
53 #define _INCLUDE_SDL_VOICE_H_
|
|
|
54
|
|
|
55 #include "SDL.h"
|
|
|
56
|
|
|
57 #ifdef __cplusplus
|
|
|
58 extern "C" {
|
|
|
59 #endif
|
|
|
60
|
|
|
61 /*
|
|
|
62 * These are flags that are used in a Sound_Sample (below) to show various
|
|
|
63 * states.
|
|
|
64 *
|
|
|
65 * To use: "if (sample->flags & VOICE_SAMPLEFLAGS_ERROR) { dosomething(); }"
|
|
|
66 */
|
|
|
67 typedef enum __VOICE_SAMPLEFLAGS__
|
|
|
68 {
|
|
|
69 VOICE_SAMPLEFLAG_NONE = 0, /* Null flag. */
|
|
|
70
|
|
|
71 /* these are set at sample creation time... */
|
|
|
72 VOICE_SAMPLEFLAG_NEEDSEEK = 1, /* SDL_RWops must be able to seek. */
|
|
|
73 VOICE_SAMPLEFLAG_STREAMING = 1 << 1, /* source is streaming (no EOF). */
|
|
|
74
|
|
|
75 /* these are set during decoding... */
|
|
|
76 VOICE_SAMPLEFLAG_EOF = 1 << 29, /* end of input stream. */
|
|
|
77 VOICE_SAMPLEFLAG_ERROR = 1 << 30, /* unrecoverable error. */
|
|
|
78 VOICE_SAMPLEFLAG_AGAIN = 1 << 31 /* couldn't read without blocking. */
|
|
|
79 } Sound_SampleFlags;
|
|
|
80
|
|
|
81
|
|
|
82 /*
|
|
|
83 * The Sound_Sample structure is the heart of SDL_sound. This holds
|
|
|
84 * information about a source of sound data as it is being decoded.
|
|
|
85 * EVERY FIELD IN THIS IS READ-ONLY. Please use the API functions to
|
|
|
86 * change them.
|
|
|
87 */
|
|
|
88 typedef struct __VOICE_SAMPLE__
|
|
|
89 {
|
|
|
90 void *opaque; /* Internal use only. */
|
|
|
91 Sound_DecoderInfo *decoder; /* Decoder used for this sample. */
|
|
|
92 SDL_AudioSpec desired; /* Desired audio format for conversion. */
|
|
|
93 SDL_AudioSpec actual; /* Actual audio format of sample. */
|
|
|
94 void *buffer; /* Decoded sound data lands in here. */
|
|
|
95 Uint32 buffer_size; /* Current size of (buffer), in bytes. */
|
|
|
96 Sound_SampleFlags flags; /* Flags relating to this sample. */
|
|
|
97 } Sound_Sample;
|
|
|
98
|
|
|
99
|
|
|
100 /*
|
|
|
101 * Each decoder sets up one of these structs, which can be retrieved via
|
|
|
102 * the Sound_AvailableDecoders() function.
|
|
|
103 */
|
|
|
104 typedef struct __PHYSFS_ARCHIVEINFO__
|
|
|
105 {
|
|
|
106 const char *extension; /* Case sensitive standard file extension. */
|
|
|
107 const char *description; /* Human readable description of decoder. */
|
|
|
108 const char *author; /* "Name Of Author (email@emailhost.dom)" */
|
|
|
109 const char *url; /* URL specific to this decoder. */
|
|
|
110 } PHYSFS_ArchiveInfo;
|
|
|
111
|
|
|
112
|
|
|
113 /*
|
|
|
114 * Just what it says: a x.y.z style version number...
|
|
|
115 */
|
|
|
116 typedef struct __VOICE_VERSION__
|
|
|
117 {
|
|
|
118 int major;
|
|
|
119 int minor;
|
|
|
120 int patch;
|
|
|
121 } Sound_Version;
|
|
|
122
|
|
|
123
|
|
|
124
|
|
|
125 /* functions and macros... */
|
|
|
126
|
|
|
127 #define VOICE_VER_MAJOR 0
|
|
|
128 #define VOICE_VER_MINOR 0
|
|
|
129 #define VOICE_VER_PATCH 1
|
|
|
130
|
|
|
131 #define VOICE_VERSION(x) { \
|
|
|
132 (x)->major = VOICE_VER_MAJOR; \
|
|
|
133 (x)->minor = VOICE_VER_MINOR; \
|
|
|
134 (x)->patch = VOICE_VER_PATCH; \
|
|
|
135 }
|
|
|
136
|
|
|
137 /**
|
|
|
138 * Get the version of SDL_sound that is linked against your program. If you
|
|
|
139 * are using a shared library (DLL) version of SDL_sound, then it is possible
|
|
|
140 * that it will be different than the version you compiled against.
|
|
|
141 *
|
|
|
142 * This is a real function; the macro VOICE_VERSION tells you what version
|
|
|
143 * of SDL_sound you compiled against:
|
|
|
144 *
|
|
|
145 * Sound_Version compiled;
|
|
|
146 * Sound_Version linked;
|
|
|
147 *
|
|
|
148 * VOICE_VERSION(&compiled);
|
|
|
149 * Sound_GetLinkedVersion(&linked);
|
|
|
150 * printf("We compiled against SDL_sound version %d.%d.%d ...\n",
|
|
|
151 * compiled.major, compiled.minor, compiled.patch);
|
|
|
152 * printf("But we linked against SDL_sound version %d.%d.%d.\n",
|
|
|
153 * linked.major, linked.minor, linked.patch);
|
|
|
154 *
|
|
|
155 * This function may be called safely at any time, even before Sound_Init().
|
|
|
156 */
|
|
|
157 extern DECLSPEC void Sound_GetLinkedVersion(Sound_Version *ver);
|
|
|
158
|
|
|
159
|
|
|
160 /**
|
|
|
161 * Initialize SDL_sound. This must be called before any other SDL_sound
|
|
|
162 * function (except perhaps Sound_GetLinkedVersion()). You should call
|
|
|
163 * SDL_Init() before calling this. Sound_Init() will attempt to call
|
|
|
164 * SDL_Init(SDL_INIT_AUDIO), just in case. This is a safe behaviour, but it
|
|
|
165 * may not configure SDL to your liking by itself.
|
|
|
166 *
|
|
|
167 * @return nonzero on success, zero on error. Specifics of the error can be
|
|
|
168 * gleaned from Sound_GetLastError().
|
|
|
169 */
|
|
|
170 extern DECLSPEC int Sound_Init(void);
|
|
|
171
|
|
|
172
|
|
|
173 /**
|
|
|
174 * Shutdown SDL_sound. This closes any SDL_RWops that were being used as
|
|
|
175 * sound sources, and frees any resources in use by SDL_sound.
|
|
|
176 *
|
|
|
177 * All Sound_Sample pointers you had prior to this call are INVALIDATED.
|
|
|
178 *
|
|
|
179 * Once successfully deinitialized, Sound_Init() can be called again to
|
|
|
180 * restart the subsystem. All defaults API states are restored at this
|
|
|
181 * point.
|
|
|
182 *
|
|
|
183 * You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit()
|
|
|
184 * for you!
|
|
|
185 *
|
|
|
186 * @return nonzero on success, zero on error. Specifics of the error can be
|
|
|
187 * gleaned from Sound_GetLastError(). If failure, state of SDL_sound
|
|
|
188 * is undefined, and probably badly screwed up.
|
|
|
189 */
|
|
|
190 extern DECLSPEC int Sound_Quit(void);
|
|
|
191
|
|
|
192
|
|
|
193 /**
|
|
|
194 * Get a list of sound formats supported by this implementation of SDL_sound.
|
|
|
195 * This is for informational purposes only. Note that the extension listed is
|
|
|
196 * merely convention: if we list "MP3", you can open an MPEG Audio layer 3
|
|
|
197 * file with an extension of "XYZ", if you like. The file extensions are
|
|
|
198 * informational, and only required as a hint to choosing the correct
|
|
|
199 * decoder, since the sound data may not be coming from a file at all, thanks
|
|
|
200 * to the abstraction that an SDL_RWops provides.
|
|
|
201 *
|
|
|
202 * The returned value is an array of pointers to Sound_DecoderInfo structures,
|
|
|
203 * with a NULL entry to signify the end of the list:
|
|
|
204 *
|
|
|
205 * Sound_DecoderInfo **i;
|
|
|
206 *
|
|
|
207 * for (i = Sound_AvailableDecoders(); *i != NULL; i++)
|
|
|
208 * {
|
|
|
209 * printf("Supported sound format: [%s], which is [%s].\n",
|
|
|
210 * i->extension, i->description);
|
|
|
211 * // ...and other fields...
|
|
|
212 * }
|
|
|
213 *
|
|
|
214 * The return values are pointers to static internal memory, and should
|
|
|
215 * be considered READ ONLY, and never freed.
|
|
|
216 *
|
|
|
217 * @return READ ONLY Null-terminated array of READ ONLY structures.
|
|
|
218 */
|
|
|
219 extern DECLSPEC const Sound_DecoderInfo **Sound_AvailableDecoders(void);
|
|
|
220
|
|
|
221
|
|
|
222 /**
|
|
|
223 * Get the last SDL_sound error message as a null-terminated string.
|
|
|
224 * This will be NULL if there's been no error since the last call to this
|
|
|
225 * function. The pointer returned by this call points to an internal buffer.
|
|
|
226 * Each thread has a unique error state associated with it, but each time
|
|
|
227 * a new error message is set, it will overwrite the previous one associated
|
|
|
228 * with that thread. It is safe to call this function at anytime, even
|
|
|
229 * before Sound_Init().
|
|
|
230 *
|
|
|
231 * @return READ ONLY string of last error message.
|
|
|
232 */
|
|
|
233 extern DECLSPEC const char *Sound_GetLastError(void);
|
|
|
234
|
|
|
235
|
|
|
236 /**
|
|
|
237 * Start decoding a new sound sample. The data is read via an SDL_RWops
|
|
|
238 * structure (see SDL_rwops.h in the SDL include directory), so it may be
|
|
|
239 * coming from memory, disk, network stream, etc. The (ext) parameter is
|
|
|
240 * merely a hint to determining the correct decoder; if you specify, for
|
|
|
241 * example, "mp3" for an extension, and one of the decoders lists that
|
|
|
242 * (case sensitive) as a handled extension, then that decoder is given
|
|
|
243 * first shot at trying to claim the data for decoding. If none of the
|
|
|
244 * extensions match (or the extension is NULL), then every decoder examines
|
|
|
245 * the data to determine if it can handle it, until one accepts it.
|
|
|
246 * If no decoders can handle the data, a NULL value is returned, and a human
|
|
|
247 * readable error message can be fetched from Sound_GetLastError().
|
|
|
248 * Optionally, a desired audio format can be specified. If the incoming data
|
|
|
249 * is in a different format, SDL_sound will convert it to the desired format
|
|
|
250 * on the fly. Note that this can be an expensive operation, so it may be
|
|
|
251 * wise to convert data before you need to play it back, if possible, or
|
|
|
252 * make sure your data is initially in the format that you need it in.
|
|
|
253 * If you don't want to convert the data, you can specify NULL for a desired
|
|
|
254 * format. The incoming format of the data, preconversion, can be found
|
|
|
255 * in the Sound_Sample structure.
|
|
|
256 * Note that the raw sound data "decoder" needs you to specify both the
|
|
|
257 * extension "RAWDATA" and a "desired" format, or it will refuse to handle
|
|
|
258 * the data.
|
|
|
259 * Finally, specify an initial buffer size; this is the number of bytes that
|
|
|
260 * will be allocated to store each read from the sound buffer. The more you
|
|
|
261 * can safely allocate, the more decoding can be done in one block, but the
|
|
|
262 * more resources you have to use up, and the longer each decoding call will
|
|
|
263 * take. Note that different data formats require more or less space to
|
|
|
264 * store. This buffer can be resized via Sound_SetBufferSize() ...
|
|
|
265 *
|
|
|
266 * When you are done with this Sound_Sample pointer, you can dispose of it
|
|
|
267 * via Sound_FreeSample().
|
|
|
268 *
|
|
|
269 * @param rw SDL_RWops with sound data.
|
|
|
270 * @param ext File extension normally associated with a data format.
|
|
|
271 * Can usually be NULL.
|
|
|
272 * @param desired Format to convert sound data into. Can usually be NULL,
|
|
|
273 * if you don't need conversion.
|
|
|
274 * @return Sound_Sample pointer, which is used as a handle to several other
|
|
|
275 * SDL_sound APIs. NULL on error. If error, use
|
|
|
276 * Sound_GetLastError() to see what went wrong.
|
|
|
277 */
|
|
|
278 extern DECLSPEC Sound_Sample *Sound_NewSample(SDL_RWops *rw, const char *ext,
|
|
|
279 SDL_AudioInfo *desired,
|
|
|
280 Uint32 bufferSize);
|
|
|
281
|
|
|
282 /**
|
|
|
283 * Dispose of a Sound_Sample pointer that was returned from Sound_NewSample().
|
|
|
284 * This will also close/dispose of the SDL_RWops that was used at creation
|
|
|
285 * time, so there's no need to keep a reference to that around.
|
|
|
286 * The Sound_Sample pointer is invalid after this call, and will almost
|
|
|
287 * certainly result in a crash if you attempt to keep using it.
|
|
|
288 *
|
|
|
289 * @param sample The Sound_Sample to delete.
|
|
|
290 */
|
|
|
291 extern DECLSPEC void Sound_FreeSample(Sound_Sample *sample);
|
|
|
292
|
|
|
293
|
|
|
294 /**
|
|
|
295 * Decode more of the sound data in a Sound_Sample. It will decode at most
|
|
|
296 * sample->buffer_size bytes into sample->buffer in the desired format, and
|
|
|
297 * return the number of decoded bytes.
|
|
|
298 * If sample->buffer_size bytes could not be decoded, then please refer to
|
|
|
299 * sample->flags to determine if this was an End-of-stream or error condition.
|
|
|
300 *
|
|
|
301 * @param sample Do more decoding to this Sound_Sample.
|
|
|
302 * @return number of bytes decoded into sample->buffer. If it is less than
|
|
|
303 * sample->buffer_size, then you should check sample->flags to see
|
|
|
304 * what the current state of the sample is (EOF, error, read again).
|
|
|
305 */
|
|
|
306 extern DECLSPEC Uint32 Sound_Decode(Sound_Sample *sample);
|
|
|
307
|
|
|
308
|
|
|
309 /**
|
|
|
310 * Decode the remainder of the sound data in a Sound_Sample. This will
|
|
|
311 * dynamically allocate memory for the ENTIRE remaining sample.
|
|
|
312 * sample->buffer_size and sample->buffer will be updated to reflect the
|
|
|
313 * new buffer. Please refer to sample->flags to determine if the decoding
|
|
|
314 * finished due to an End-of-stream or error condition.
|
|
|
315 *
|
|
|
316 * Be aware that sound data can take a large amount of memory, and that
|
|
|
317 * this function may block for quite awhile while processing. Also note
|
|
|
318 * that a streaming source (for example, from a SDL_RWops that is getting
|
|
|
319 * fed from an Internet radio feed that doesn't end) may fill all available
|
|
|
320 * memory before giving up...be sure to use this on finite sound sources
|
|
|
321 * only!
|
|
|
322 *
|
|
|
323 * @param sample Do all decoding for this Sound_Sample.
|
|
|
324 * @return number of bytes decoded into sample->buffer. If it is less than
|
|
|
325 * sample->buffer_size, then you should check sample->flags to see
|
|
|
326 * what the current state of the sample is (EOF, error, read again).
|
|
|
327 */
|
|
|
328 extern DECLSPEC Uint32 Sound_DecodeAll(Sound_Sample *sample);
|
|
|
329
|
|
|
330 #ifdef __cplusplus
|
|
|
331 }
|
|
|
332 #endif
|
|
|
333
|
|
|
334 #endif /* !defined _INCLUDE_SDL_VOICE_H_ */
|
|
|
335
|
|
|
336 /* end of SDL_sound.h ... */
|
|
|
337
|
