Mercurial > SDL_sound_CoreAudio
annotate SDL_sound.h @ 159:844364c50790
Updated.
| author | Ryan C. Gordon <icculus@icculus.org> |
|---|---|
| date | Fri, 09 Nov 2001 23:16:21 +0000 |
| parents | 1df5c106504e |
| children | e91fb8d5bd62 |
| rev | line source |
|---|---|
| 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 | |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
27 * callback (or whatever). Since it gets data from an SDL_RWops, you can get |
| 0 | 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: | |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
36 * - .WAV (Microsoft WAVfile RIFF data, internal.) |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
37 * - .VOC (Creative Labs' Voice format, internal.) |
| 11 | 38 * - .MP3 (MPEG-1 Layer 3 support, via the SMPEG library.) |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
39 * - .MID (MIDI music converted to Waveform data, via Timidity.) |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
40 * - .MOD (MOD files, via MikMod.) |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
41 * - .OGG (Ogg files, via Ogg Vorbis libraries.) |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
42 * - .RAW (Raw sound data in any format, internal.) |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
43 * - .CDA (CD audio read into a sound buffer, internal.) |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
44 * - .AU |
|
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
45 * - .AIFF |
| 0 | 46 * |
| 47 * (...and more to come...) | |
| 48 * | |
| 49 * Please see the file LICENSE in the source's root directory. | |
| 50 * | |
| 51 * This file written by Ryan C. Gordon. (icculus@clutteredmind.org) | |
| 52 */ | |
| 53 | |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
54 #ifndef _INCLUDE_SDL_SOUND_H_ |
|
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
55 #define _INCLUDE_SDL_SOUND_H_ |
| 0 | 56 |
| 57 #include "SDL.h" | |
|
19
734e5d75acec
Now includes SDL_endian.h ...
Ryan C. Gordon <icculus@icculus.org>
parents:
15
diff
changeset
|
58 #include "SDL_endian.h" |
| 0 | 59 |
| 60 #ifdef __cplusplus | |
| 61 extern "C" { | |
| 62 #endif | |
| 63 | |
|
130
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
64 #ifdef SDL_SOUND_DLL_EXPORTS |
|
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
65 # undef DECLSPEC |
|
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
66 # define DECLSPEC __declspec(dllexport) |
|
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
67 #endif |
|
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
68 |
|
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
69 |
| 29 | 70 #define SOUND_VER_MAJOR 0 |
| 71 #define SOUND_VER_MINOR 1 | |
|
130
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
72 #define SOUND_VER_PATCH 3 |
| 29 | 73 |
| 74 | |
| 0 | 75 /* |
| 76 * These are flags that are used in a Sound_Sample (below) to show various | |
| 77 * states. | |
| 78 * | |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
79 * To use: "if (sample->flags & SOUND_SAMPLEFLAG_ERROR) { dosomething(); }" |
| 0 | 80 */ |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
81 typedef enum __SOUND_SAMPLEFLAGS__ |
| 0 | 82 { |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
83 SOUND_SAMPLEFLAG_NONE = 0, /* Null flag. */ |
| 0 | 84 |
| 85 /* these are set at sample creation time... */ | |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
86 SOUND_SAMPLEFLAG_NEEDSEEK = 1, /* SDL_RWops must be able to seek. */ |
| 0 | 87 |
| 88 /* these are set during decoding... */ | |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
89 SOUND_SAMPLEFLAG_EOF = 1 << 29, /* end of input stream. */ |
|
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
90 SOUND_SAMPLEFLAG_ERROR = 1 << 30, /* unrecoverable error. */ |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
91 SOUND_SAMPLEFLAG_EAGAIN = 1 << 31 /* would block, or temp error. */ |
| 0 | 92 } Sound_SampleFlags; |
| 93 | |
| 94 | |
| 95 /* | |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
96 * Basics of a decoded sample's data structure: data format (see AUDIO_U8 and |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
97 * friends in SDL_audio.h), number of channels, and sample rate. If you need |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
98 * more explanation than that, you should stop developing sound code right |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
99 * now. |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
100 */ |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
101 typedef struct __SOUND_AUDIOINFO__ |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
102 { |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
103 Uint16 format; |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
104 Uint8 channels; |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
105 Uint32 rate; |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
106 } Sound_AudioInfo; |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
107 |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
108 |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
109 /* |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
110 * 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
|
111 * the Sound_AvailableDecoders() function. EVERY FIELD IN THIS IS READ-ONLY. |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
112 */ |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
113 typedef struct __SOUND_DECODERINFO__ |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
114 { |
|
149
1df5c106504e
Decoders can now list multiple file extensions.
Ryan C. Gordon <icculus@icculus.org>
parents:
130
diff
changeset
|
115 const char **extensions; /* File extensions, list ends with NULL. */ |
|
1df5c106504e
Decoders can now list multiple file extensions.
Ryan C. Gordon <icculus@icculus.org>
parents:
130
diff
changeset
|
116 const char *description; /* Human readable description of decoder. */ |
|
1df5c106504e
Decoders can now list multiple file extensions.
Ryan C. Gordon <icculus@icculus.org>
parents:
130
diff
changeset
|
117 const char *author; /* "Name Of Author <email@emailhost.dom>" */ |
|
1df5c106504e
Decoders can now list multiple file extensions.
Ryan C. Gordon <icculus@icculus.org>
parents:
130
diff
changeset
|
118 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
|
119 } Sound_DecoderInfo; |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
120 |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
121 |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
122 |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
123 /* |
| 0 | 124 * The Sound_Sample structure is the heart of SDL_sound. This holds |
| 125 * information about a source of sound data as it is being decoded. | |
| 126 * EVERY FIELD IN THIS IS READ-ONLY. Please use the API functions to | |
| 127 * change them. | |
| 128 */ | |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
129 typedef struct __SOUND_SAMPLE__ |
| 0 | 130 { |
| 131 void *opaque; /* Internal use only. */ | |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
132 const Sound_DecoderInfo *decoder; /* Decoder used for this sample. */ |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
133 Sound_AudioInfo desired; /* Desired audio format for conversion. */ |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
134 Sound_AudioInfo actual; /* Actual audio format of sample. */ |
| 0 | 135 void *buffer; /* Decoded sound data lands in here. */ |
| 136 Uint32 buffer_size; /* Current size of (buffer), in bytes. */ | |
| 137 Sound_SampleFlags flags; /* Flags relating to this sample. */ | |
| 138 } Sound_Sample; | |
| 139 | |
| 140 | |
| 141 /* | |
| 142 * Just what it says: a x.y.z style version number... | |
| 143 */ | |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
144 typedef struct __SOUND_VERSION__ |
| 0 | 145 { |
| 146 int major; | |
| 147 int minor; | |
| 148 int patch; | |
| 149 } Sound_Version; | |
| 150 | |
| 151 | |
| 152 | |
| 153 /* functions and macros... */ | |
| 154 | |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
155 #define SOUND_VERSION(x) { \ |
|
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
156 (x)->major = SOUND_VER_MAJOR; \ |
|
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
157 (x)->minor = SOUND_VER_MINOR; \ |
|
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
158 (x)->patch = SOUND_VER_PATCH; \ |
| 0 | 159 } |
| 160 | |
| 161 /** | |
| 162 * Get the version of SDL_sound that is linked against your program. If you | |
| 163 * are using a shared library (DLL) version of SDL_sound, then it is possible | |
| 164 * that it will be different than the version you compiled against. | |
| 165 * | |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
166 * This is a real function; the macro SOUND_VERSION tells you what version |
| 0 | 167 * of SDL_sound you compiled against: |
| 168 * | |
| 169 * Sound_Version compiled; | |
| 170 * Sound_Version linked; | |
| 171 * | |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
172 * SOUND_VERSION(&compiled); |
| 0 | 173 * Sound_GetLinkedVersion(&linked); |
| 174 * printf("We compiled against SDL_sound version %d.%d.%d ...\n", | |
| 175 * compiled.major, compiled.minor, compiled.patch); | |
| 176 * printf("But we linked against SDL_sound version %d.%d.%d.\n", | |
| 177 * linked.major, linked.minor, linked.patch); | |
| 178 * | |
| 179 * This function may be called safely at any time, even before Sound_Init(). | |
| 180 */ | |
| 181 extern DECLSPEC void Sound_GetLinkedVersion(Sound_Version *ver); | |
| 182 | |
| 183 | |
| 184 /** | |
| 185 * Initialize SDL_sound. This must be called before any other SDL_sound | |
| 186 * function (except perhaps Sound_GetLinkedVersion()). You should call | |
| 187 * SDL_Init() before calling this. Sound_Init() will attempt to call | |
| 188 * SDL_Init(SDL_INIT_AUDIO), just in case. This is a safe behaviour, but it | |
| 189 * may not configure SDL to your liking by itself. | |
| 190 * | |
| 191 * @return nonzero on success, zero on error. Specifics of the error can be | |
| 192 * gleaned from Sound_GetLastError(). | |
| 193 */ | |
| 194 extern DECLSPEC int Sound_Init(void); | |
| 195 | |
| 196 | |
| 197 /** | |
| 198 * Shutdown SDL_sound. This closes any SDL_RWops that were being used as | |
| 199 * sound sources, and frees any resources in use by SDL_sound. | |
| 200 * | |
| 201 * All Sound_Sample pointers you had prior to this call are INVALIDATED. | |
| 202 * | |
| 203 * 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
|
204 * restart the subsystem. All default API states are restored at this |
| 0 | 205 * point. |
| 206 * | |
| 207 * You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit() | |
| 208 * for you! | |
| 209 * | |
| 210 * @return nonzero on success, zero on error. Specifics of the error can be | |
| 211 * gleaned from Sound_GetLastError(). If failure, state of SDL_sound | |
| 212 * is undefined, and probably badly screwed up. | |
| 213 */ | |
| 214 extern DECLSPEC int Sound_Quit(void); | |
| 215 | |
| 216 | |
| 217 /** | |
| 218 * Get a list of sound formats supported by this implementation of SDL_sound. | |
| 219 * This is for informational purposes only. Note that the extension listed is | |
| 11 | 220 * merely convention: if we list "MP3", you can open an MPEG-1 Layer 3 audio |
| 0 | 221 * file with an extension of "XYZ", if you like. The file extensions are |
| 222 * informational, and only required as a hint to choosing the correct | |
| 223 * decoder, since the sound data may not be coming from a file at all, thanks | |
| 224 * to the abstraction that an SDL_RWops provides. | |
| 225 * | |
| 226 * The returned value is an array of pointers to Sound_DecoderInfo structures, | |
| 227 * with a NULL entry to signify the end of the list: | |
| 228 * | |
| 229 * Sound_DecoderInfo **i; | |
| 230 * | |
| 231 * for (i = Sound_AvailableDecoders(); *i != NULL; i++) | |
| 232 * { | |
| 233 * printf("Supported sound format: [%s], which is [%s].\n", | |
| 234 * i->extension, i->description); | |
| 235 * // ...and other fields... | |
| 236 * } | |
| 237 * | |
| 238 * The return values are pointers to static internal memory, and should | |
| 239 * be considered READ ONLY, and never freed. | |
| 240 * | |
| 241 * @return READ ONLY Null-terminated array of READ ONLY structures. | |
| 242 */ | |
| 243 extern DECLSPEC const Sound_DecoderInfo **Sound_AvailableDecoders(void); | |
| 244 | |
| 245 | |
| 246 /** | |
| 247 * Get the last SDL_sound error message as a null-terminated string. | |
| 248 * This will be NULL if there's been no error since the last call to this | |
| 249 * function. The pointer returned by this call points to an internal buffer. | |
| 250 * Each thread has a unique error state associated with it, but each time | |
| 251 * a new error message is set, it will overwrite the previous one associated | |
| 252 * with that thread. It is safe to call this function at anytime, even | |
| 253 * before Sound_Init(). | |
| 254 * | |
| 255 * @return READ ONLY string of last error message. | |
| 256 */ | |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
257 extern DECLSPEC const char *Sound_GetError(void); |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
258 |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
259 |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
260 /** |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
261 * Clear the current error message, so the next call to Sound_GetError() will |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
262 * return NULL. |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
263 */ |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
264 extern DECLSPEC void Sound_ClearError(void); |
| 0 | 265 |
| 266 | |
| 267 /** | |
| 268 * Start decoding a new sound sample. The data is read via an SDL_RWops | |
| 269 * structure (see SDL_rwops.h in the SDL include directory), so it may be | |
| 270 * coming from memory, disk, network stream, etc. The (ext) parameter is | |
| 271 * merely a hint to determining the correct decoder; if you specify, for | |
| 272 * example, "mp3" for an extension, and one of the decoders lists that | |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
273 * as a handled extension, then that decoder is given first shot at trying |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
274 * to claim the data for decoding. If none of the extensions match (or the |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
275 * extension is NULL), then every decoder examines the data to determine if |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
276 * it can handle it, until one accepts it. In such a case your SDL_RWops will |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
277 * need to be capable of rewinding to the start of the stream. |
| 0 | 278 * If no decoders can handle the data, a NULL value is returned, and a human |
| 279 * readable error message can be fetched from Sound_GetLastError(). | |
| 280 * Optionally, a desired audio format can be specified. If the incoming data | |
| 281 * is in a different format, SDL_sound will convert it to the desired format | |
| 282 * on the fly. Note that this can be an expensive operation, so it may be | |
| 283 * wise to convert data before you need to play it back, if possible, or | |
| 284 * make sure your data is initially in the format that you need it in. | |
| 285 * If you don't want to convert the data, you can specify NULL for a desired | |
| 286 * format. The incoming format of the data, preconversion, can be found | |
| 287 * in the Sound_Sample structure. | |
| 288 * 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
|
289 * 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
|
290 * 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
|
291 * by the other decoders. |
| 0 | 292 * Finally, specify an initial buffer size; this is the number of bytes that |
| 293 * will be allocated to store each read from the sound buffer. The more you | |
| 294 * can safely allocate, the more decoding can be done in one block, but the | |
| 295 * more resources you have to use up, and the longer each decoding call will | |
| 296 * take. Note that different data formats require more or less space to | |
| 297 * 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
|
298 * The buffer size specified must be a multiple of the size of a single |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
299 * sample (not to be confused with a single Sound_Sample). So, if you want |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
300 * 16-bit, stereo samples, then your sample size is (2 channels * 16 bits), |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
301 * or 32 bits per sample, which is four bytes. In such a case, you could |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
302 * specify 128 or 132 bytes for a buffer, but not 129, 130, or 131, although |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
303 * in reality, you'll want to specify a MUCH larger buffer. |
| 0 | 304 * When you are done with this Sound_Sample pointer, you can dispose of it |
| 305 * via Sound_FreeSample(). | |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
306 * You do not have to keep a reference to (rw) around. If this function |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
307 * suceeds, it stores (rw) internally (and disposes of it during the call |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
308 * to Sound_FreeSample()). If this function fails, it will dispose of the |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
309 * SDL_RWops for you. |
| 0 | 310 * |
| 311 * @param rw SDL_RWops with sound data. | |
| 312 * @param ext File extension normally associated with a data format. | |
| 313 * Can usually be NULL. | |
| 314 * @param desired Format to convert sound data into. Can usually be NULL, | |
| 315 * if you don't need conversion. | |
| 316 * @return Sound_Sample pointer, which is used as a handle to several other | |
| 317 * SDL_sound APIs. NULL on error. If error, use | |
| 318 * Sound_GetLastError() to see what went wrong. | |
| 319 */ | |
| 320 extern DECLSPEC Sound_Sample *Sound_NewSample(SDL_RWops *rw, const char *ext, | |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
321 Sound_AudioInfo *desired, |
| 0 | 322 Uint32 bufferSize); |
| 323 | |
| 324 /** | |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
325 * This is identical to Sound_NewSample(), but it creates an SDL_RWops for you |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
326 * from the file located in (filename). Note that (filename) is specified in |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
327 * platform-dependent notation. ("C:\\music\\mysong.mp3" on windows, and |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
328 * "/home/icculus/music/mysong.mp3" or whatever on Unix, etc.) |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
329 * Sound_NewSample()'s "ext" parameter is gleaned from the contents of |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
330 * (filename). |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
331 * |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
332 * @param filename file containing sound data. |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
333 * @param desired Format to convert sound data into. Can usually be NULL, |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
334 * if you don't need conversion. |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
335 * @param bufferSize size, in bytes, of initial read buffer. |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
336 * @return Sound_Sample pointer, which is used as a handle to several other |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
337 * SDL_sound APIs. NULL on error. If error, use |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
338 * Sound_GetLastError() to see what went wrong. |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
339 */ |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
340 extern DECLSPEC Sound_Sample *Sound_NewSampleFromFile(const char *filename, |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
341 Sound_AudioInfo *desired, |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
342 Uint32 bufferSize); |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
343 |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
344 /** |
| 0 | 345 * Dispose of a Sound_Sample pointer that was returned from Sound_NewSample(). |
| 346 * This will also close/dispose of the SDL_RWops that was used at creation | |
| 347 * time, so there's no need to keep a reference to that around. | |
| 348 * The Sound_Sample pointer is invalid after this call, and will almost | |
| 349 * certainly result in a crash if you attempt to keep using it. | |
| 350 * | |
| 351 * @param sample The Sound_Sample to delete. | |
| 352 */ | |
| 353 extern DECLSPEC void Sound_FreeSample(Sound_Sample *sample); | |
| 354 | |
| 355 | |
| 356 /** | |
|
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
357 * Change the current buffer size for a sample. If the buffer size could |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
358 * be changed, then the sample->buffer and sample->buffer_size fields will |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
359 * reflect that. If they could not be changed, then your original sample |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
360 * state is preserved. If the buffer is shrinking, the data at the end of |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
361 * buffer is truncated. If the buffer is growing, the contents of the new |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
362 * space at the end is undefined until you decode more into it or initialize |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
363 * it yourself. |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
364 * |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
365 * The buffer size specified must be a multiple of the size of a single |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
366 * sample (not to be confused with a single Sound_Sample). So, if you want |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
367 * 16-bit, stereo samples, then your sample size is (2 channels * 16 bits), |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
368 * or 32 bits per sample, which is four bytes. In such a case, you could |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
369 * specify 128 or 132 bytes for a buffer, but not 129, 130, or 131, although |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
370 * in reality, you'll want to specify a MUCH larger buffer. |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
371 * |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
372 * @param sample The Sound_Sample whose buffer to modify. |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
373 * @param new_size The desired size, in bytes, of the new buffer. |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
374 * @return non-zero if buffer size changed, zero on failure. |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
375 */ |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
376 extern DECLSPEC int Sound_SetBufferSize(Sound_Sample *sample, Uint32 new_size); |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
377 |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
378 |
|
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
379 /** |
| 0 | 380 * Decode more of the sound data in a Sound_Sample. It will decode at most |
| 381 * sample->buffer_size bytes into sample->buffer in the desired format, and | |
| 382 * return the number of decoded bytes. | |
| 383 * If sample->buffer_size bytes could not be decoded, then please refer to | |
| 384 * sample->flags to determine if this was an End-of-stream or error condition. | |
| 385 * | |
| 386 * @param sample Do more decoding to this Sound_Sample. | |
| 387 * @return number of bytes decoded into sample->buffer. If it is less than | |
| 388 * sample->buffer_size, then you should check sample->flags to see | |
| 389 * what the current state of the sample is (EOF, error, read again). | |
| 390 */ | |
| 391 extern DECLSPEC Uint32 Sound_Decode(Sound_Sample *sample); | |
| 392 | |
| 393 | |
| 394 /** | |
| 395 * Decode the remainder of the sound data in a Sound_Sample. This will | |
| 396 * dynamically allocate memory for the ENTIRE remaining sample. | |
| 397 * sample->buffer_size and sample->buffer will be updated to reflect the | |
| 398 * new buffer. Please refer to sample->flags to determine if the decoding | |
| 399 * finished due to an End-of-stream or error condition. | |
| 400 * | |
| 401 * Be aware that sound data can take a large amount of memory, and that | |
| 402 * this function may block for quite awhile while processing. Also note | |
| 403 * that a streaming source (for example, from a SDL_RWops that is getting | |
| 404 * fed from an Internet radio feed that doesn't end) may fill all available | |
| 405 * memory before giving up...be sure to use this on finite sound sources | |
| 406 * only! | |
| 407 * | |
| 408 * @param sample Do all decoding for this Sound_Sample. | |
| 409 * @return number of bytes decoded into sample->buffer. If it is less than | |
| 410 * sample->buffer_size, then you should check sample->flags to see | |
| 411 * what the current state of the sample is (EOF, error, read again). | |
| 412 */ | |
| 413 extern DECLSPEC Uint32 Sound_DecodeAll(Sound_Sample *sample); | |
| 414 | |
| 415 #ifdef __cplusplus | |
| 416 } | |
| 417 #endif | |
| 418 | |
|
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
419 #endif /* !defined _INCLUDE_SDL_SOUND_H_ */ |
| 0 | 420 |
| 421 /* end of SDL_sound.h ... */ | |
| 422 |