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