Mercurial > SDL_sound_CoreAudio
annotate SDL_sound.h @ 264:abe472572e38
Updated.
author | Ryan C. Gordon <icculus@icculus.org> |
---|---|
date | Fri, 22 Feb 2002 08:58:38 +0000 |
parents | c54eae85f5f1 |
children | c345a40a8a99 |
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 /** | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
21 * @overview |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
22 * |
0 | 23 * The basic gist of SDL_sound is that you use an SDL_RWops to get sound data |
24 * into this library, and SDL_sound will take that data, in one of several | |
25 * popular formats, and decode it into raw waveform data in the format of | |
26 * your choice. This gives you a nice abstraction for getting sound into your | |
27 * game or application; just feed it to SDL_sound, and it will handle | |
28 * 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
|
29 * callback (or whatever). Since it gets data from an SDL_RWops, you can get |
0 | 30 * the initial sound data from any number of sources: file, memory buffer, |
31 * network connection, etc. | |
32 * | |
33 * As the name implies, this library depends on SDL: Simple Directmedia Layer, | |
34 * which is a powerful, free, and cross-platform multimedia library. It can | |
35 * be found at http://www.libsdl.org/ | |
36 * | |
37 * 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
|
38 * - .WAV (Microsoft WAVfile RIFF data, internal.) |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
39 * - .VOC (Creative Labs' Voice format, internal.) |
11 | 40 * - .MP3 (MPEG-1 Layer 3 support, via the SMPEG library.) |
252
c54eae85f5f1
Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents:
223
diff
changeset
|
41 * - .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
|
42 * - .MOD (MOD files, via MikMod and ModPlug.) |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
43 * - .OGG (Ogg files, via Ogg Vorbis libraries.) |
252
c54eae85f5f1
Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents:
223
diff
changeset
|
44 * - .SHN (Shorten files, internal.) |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
45 * - .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
|
46 * - .AU (Sun's Audio format, internal.) |
c54eae85f5f1
Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents:
223
diff
changeset
|
47 * - .AIFF (Audio Interchange format, internal.) |
c54eae85f5f1
Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents:
223
diff
changeset
|
48 * - .FLAC (Lossless audio compression, via libFLAC.) |
0 | 49 * |
50 * (...and more to come...) | |
51 * | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
52 * Please see the file COPYING in the source's root directory. |
0 | 53 * |
54 * This file written by Ryan C. Gordon. (icculus@clutteredmind.org) | |
55 */ | |
56 | |
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
57 #ifndef _INCLUDE_SDL_SOUND_H_ |
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
58 #define _INCLUDE_SDL_SOUND_H_ |
0 | 59 |
60 #include "SDL.h" | |
19
734e5d75acec
Now includes SDL_endian.h ...
Ryan C. Gordon <icculus@icculus.org>
parents:
15
diff
changeset
|
61 #include "SDL_endian.h" |
0 | 62 |
63 #ifdef __cplusplus | |
64 extern "C" { | |
65 #endif | |
66 | |
130
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
67 #ifdef SDL_SOUND_DLL_EXPORTS |
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
68 # undef DECLSPEC |
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
69 # define DECLSPEC __declspec(dllexport) |
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
70 #endif |
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
71 |
ac49f81e42d6
Win32 fix, upped version to 0.1.3.
Ryan C. Gordon <icculus@icculus.org>
parents:
44
diff
changeset
|
72 |
29 | 73 #define SOUND_VER_MAJOR 0 |
74 #define SOUND_VER_MINOR 1 | |
252
c54eae85f5f1
Upped version to 0.1.5.
Ryan C. Gordon <icculus@icculus.org>
parents:
223
diff
changeset
|
75 #define SOUND_VER_PATCH 5 |
29 | 76 |
77 | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
78 /** |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
79 * These are flags that are used in a Sound_Sample to show various states. |
0 | 80 * |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
81 * To use: "if (sample->flags & SOUND_SAMPLEFLAG_ERROR) { dosomething(); }" |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
82 * |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
83 * @param SOUND_SAMPLEFLAG_NONE null flag. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
84 * @param SOUND_SAMPLEFLAG_NEEDSEEK SDL_RWops must be able to seek. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
85 * @param SOUND_SAMPLEFLAG_EOF end of input stream. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
86 * @param SOUND_SAMPLEFLAG_ERROR unrecoverable error. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
87 * @param SOUND_SAMPLEFLAG_EAGAIN function would block, or temp error. |
0 | 88 */ |
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
89 typedef enum __SOUND_SAMPLEFLAGS__ |
0 | 90 { |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
91 SOUND_SAMPLEFLAG_NONE = 0, |
0 | 92 |
93 /* these are set at sample creation time... */ | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
94 SOUND_SAMPLEFLAG_NEEDSEEK = 1, |
0 | 95 |
96 /* these are set during decoding... */ | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
97 SOUND_SAMPLEFLAG_EOF = 1 << 29, |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
98 SOUND_SAMPLEFLAG_ERROR = 1 << 30, |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
99 SOUND_SAMPLEFLAG_EAGAIN = 1 << 31 |
0 | 100 } Sound_SampleFlags; |
101 | |
102 | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
103 /** |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
104 * 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
|
105 * (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
|
106 * 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
|
107 * sound code right now. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
108 * |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
109 * @param format Equivalent of SDL_AudioSpec.format. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
110 * @param channels Number of sound channels. 1 == mono, 2 == stereo. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
111 * @param rate Sample rate; frequency of sample points per second (44100, |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
112 * 22050, 8000, etc.) |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
113 */ |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
114 typedef struct __SOUND_AUDIOINFO__ |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
115 { |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
116 Uint16 format; |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
117 Uint8 channels; |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
118 Uint32 rate; |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
119 } Sound_AudioInfo; |
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 |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
122 /** |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
123 * 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
|
124 * 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
|
125 * |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
126 * @param extensions File extensions, list ends with NULL. Read it like this: |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
127 * const char **ext; |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
128 * for (ext = info->extensions; *ext != NULL; ext++) |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
129 * printf(" File extension \"%s\"\n", *ext); |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
130 * @param description Human readable description of decoder. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
131 * @param author "Name Of Author <email@emailhost.dom>" |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
132 * @param url URL specific to this decoder. |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
133 */ |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
134 typedef struct __SOUND_DECODERINFO__ |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
135 { |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
136 const char **extensions; |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
137 const char *description; |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
138 const char *author; |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
139 const char *url; |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
140 } Sound_DecoderInfo; |
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 |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
143 |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
144 /** |
0 | 145 * The Sound_Sample structure is the heart of SDL_sound. This holds |
146 * information about a source of sound data as it is being decoded. | |
147 * EVERY FIELD IN THIS IS READ-ONLY. Please use the API functions to | |
148 * change them. | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
149 * |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
150 * @param opaque Internal use only. Don't touch. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
151 * @param decoder Decoder used for this sample. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
152 * @param desired Desired audio format for conversion. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
153 * @param actual Actual audio format of sample. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
154 * @param buffer Decoded sound data lands in here. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
155 * @param buffer_size Current size of (buffer), in bytes (Uint8). |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
156 * @param flags Flags relating to this sample. |
0 | 157 */ |
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
158 typedef struct __SOUND_SAMPLE__ |
0 | 159 { |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
160 void *opaque; |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
161 const Sound_DecoderInfo *decoder; |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
162 Sound_AudioInfo desired; |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
163 Sound_AudioInfo actual; |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
164 void *buffer; |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
165 Uint32 buffer_size; |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
166 Sound_SampleFlags flags; |
0 | 167 } Sound_Sample; |
168 | |
169 | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
170 /** |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
171 * Just what it says: a major.minor.patch style version number... |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
172 * |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
173 * @param major The major version number. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
174 * @param minor The minor version number. |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
175 * @param patch The patchlevel version number. |
0 | 176 */ |
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
177 typedef struct __SOUND_VERSION__ |
0 | 178 { |
179 int major; | |
180 int minor; | |
181 int patch; | |
182 } Sound_Version; | |
183 | |
184 | |
185 | |
186 /* functions and macros... */ | |
187 | |
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
188 #define SOUND_VERSION(x) { \ |
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
189 (x)->major = SOUND_VER_MAJOR; \ |
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
190 (x)->minor = SOUND_VER_MINOR; \ |
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
191 (x)->patch = SOUND_VER_PATCH; \ |
0 | 192 } |
193 | |
194 /** | |
195 * Get the version of SDL_sound that is linked against your program. If you | |
196 * are using a shared library (DLL) version of SDL_sound, then it is possible | |
197 * that it will be different than the version you compiled against. | |
198 * | |
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
199 * This is a real function; the macro SOUND_VERSION tells you what version |
0 | 200 * of SDL_sound you compiled against: |
201 * | |
202 * Sound_Version compiled; | |
203 * Sound_Version linked; | |
204 * | |
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
205 * SOUND_VERSION(&compiled); |
0 | 206 * Sound_GetLinkedVersion(&linked); |
207 * printf("We compiled against SDL_sound version %d.%d.%d ...\n", | |
208 * compiled.major, compiled.minor, compiled.patch); | |
209 * printf("But we linked against SDL_sound version %d.%d.%d.\n", | |
210 * linked.major, linked.minor, linked.patch); | |
211 * | |
212 * 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
|
213 * |
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
214 * @param ver Sound_Version structure to fill with shared library's version. |
0 | 215 */ |
216 extern DECLSPEC void Sound_GetLinkedVersion(Sound_Version *ver); | |
217 | |
218 | |
219 /** | |
220 * Initialize SDL_sound. This must be called before any other SDL_sound | |
221 * function (except perhaps Sound_GetLinkedVersion()). You should call | |
222 * SDL_Init() before calling this. Sound_Init() will attempt to call | |
223 * SDL_Init(SDL_INIT_AUDIO), just in case. This is a safe behaviour, but it | |
224 * may not configure SDL to your liking by itself. | |
225 * | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
226 * @returns nonzero on success, zero on error. Specifics of the |
186
70561bf8d5fd
Updated and clarified some documentation.
Ryan C. Gordon <icculus@icculus.org>
parents:
184
diff
changeset
|
227 * error can be gleaned from Sound_GetError(). |
0 | 228 */ |
229 extern DECLSPEC int Sound_Init(void); | |
230 | |
231 | |
232 /** | |
233 * Shutdown SDL_sound. This closes any SDL_RWops that were being used as | |
234 * sound sources, and frees any resources in use by SDL_sound. | |
235 * | |
236 * All Sound_Sample pointers you had prior to this call are INVALIDATED. | |
237 * | |
238 * 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
|
239 * restart the subsystem. All default API states are restored at this |
0 | 240 * point. |
241 * | |
242 * You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit() | |
243 * for you! | |
244 * | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
245 * @returns nonzero on success, zero on error. Specifics of the error |
186
70561bf8d5fd
Updated and clarified some documentation.
Ryan C. Gordon <icculus@icculus.org>
parents:
184
diff
changeset
|
246 * can be gleaned from Sound_GetError(). If failure, state of |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
247 * SDL_sound is undefined, and probably badly screwed up. |
0 | 248 */ |
249 extern DECLSPEC int Sound_Quit(void); | |
250 | |
251 | |
252 /** | |
253 * Get a list of sound formats supported by this implementation of SDL_sound. | |
254 * This is for informational purposes only. Note that the extension listed is | |
11 | 255 * merely convention: if we list "MP3", you can open an MPEG-1 Layer 3 audio |
0 | 256 * file with an extension of "XYZ", if you like. The file extensions are |
257 * informational, and only required as a hint to choosing the correct | |
258 * decoder, since the sound data may not be coming from a file at all, thanks | |
259 * to the abstraction that an SDL_RWops provides. | |
260 * | |
261 * The returned value is an array of pointers to Sound_DecoderInfo structures, | |
262 * with a NULL entry to signify the end of the list: | |
263 * | |
264 * Sound_DecoderInfo **i; | |
265 * | |
266 * for (i = Sound_AvailableDecoders(); *i != NULL; i++) | |
267 * { | |
268 * printf("Supported sound format: [%s], which is [%s].\n", | |
269 * i->extension, i->description); | |
270 * // ...and other fields... | |
271 * } | |
272 * | |
273 * The return values are pointers to static internal memory, and should | |
274 * be considered READ ONLY, and never freed. | |
275 * | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
276 * @returns READ ONLY Null-terminated array of READ ONLY structures. |
0 | 277 */ |
278 extern DECLSPEC const Sound_DecoderInfo **Sound_AvailableDecoders(void); | |
279 | |
280 | |
281 /** | |
282 * Get the last SDL_sound error message as a null-terminated string. | |
283 * This will be NULL if there's been no error since the last call to this | |
284 * function. The pointer returned by this call points to an internal buffer. | |
285 * Each thread has a unique error state associated with it, but each time | |
286 * a new error message is set, it will overwrite the previous one associated | |
287 * with that thread. It is safe to call this function at anytime, even | |
288 * before Sound_Init(). | |
289 * | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
290 * @returns READ ONLY string of last error message. |
0 | 291 */ |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
292 extern DECLSPEC const char *Sound_GetError(void); |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
293 |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
294 |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
295 /** |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
296 * 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
|
297 * return NULL. |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
298 */ |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
299 extern DECLSPEC void Sound_ClearError(void); |
0 | 300 |
301 | |
302 /** | |
303 * Start decoding a new sound sample. The data is read via an SDL_RWops | |
304 * structure (see SDL_rwops.h in the SDL include directory), so it may be | |
305 * coming from memory, disk, network stream, etc. The (ext) parameter is | |
306 * merely a hint to determining the correct decoder; if you specify, for | |
307 * 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
|
308 * 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
|
309 * 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
|
310 * 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
|
311 * 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
|
312 * need to be capable of rewinding to the start of the stream. |
0 | 313 * 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
|
314 * readable error message can be fetched from Sound_GetError(). |
0 | 315 * Optionally, a desired audio format can be specified. If the incoming data |
316 * is in a different format, SDL_sound will convert it to the desired format | |
317 * on the fly. Note that this can be an expensive operation, so it may be | |
318 * wise to convert data before you need to play it back, if possible, or | |
319 * make sure your data is initially in the format that you need it in. | |
320 * If you don't want to convert the data, you can specify NULL for a desired | |
321 * format. The incoming format of the data, preconversion, can be found | |
322 * in the Sound_Sample structure. | |
323 * 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
|
324 * 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
|
325 * 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
|
326 * by the other decoders. |
0 | 327 * Finally, specify an initial buffer size; this is the number of bytes that |
328 * will be allocated to store each read from the sound buffer. The more you | |
329 * can safely allocate, the more decoding can be done in one block, but the | |
330 * more resources you have to use up, and the longer each decoding call will | |
331 * take. Note that different data formats require more or less space to | |
332 * 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
|
333 * 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
|
334 * 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
|
335 * 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
|
336 * 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
|
337 * 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
|
338 * MUCH larger buffer). |
0 | 339 * When you are done with this Sound_Sample pointer, you can dispose of it |
340 * via Sound_FreeSample(). | |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
341 * 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
|
342 * 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
|
343 * 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
|
344 * SDL_RWops for you. |
0 | 345 * |
346 * @param rw SDL_RWops with sound data. | |
347 * @param ext File extension normally associated with a data format. | |
348 * Can usually be NULL. | |
349 * @param desired Format to convert sound data into. Can usually be NULL, | |
350 * if you don't need conversion. | |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
351 * @returns Sound_Sample pointer, which is used as a handle to several other |
0 | 352 * SDL_sound APIs. NULL on error. If error, use |
186
70561bf8d5fd
Updated and clarified some documentation.
Ryan C. Gordon <icculus@icculus.org>
parents:
184
diff
changeset
|
353 * Sound_GetError() to see what went wrong. |
0 | 354 */ |
355 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
|
356 Sound_AudioInfo *desired, |
0 | 357 Uint32 bufferSize); |
358 | |
359 /** | |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
360 * 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
|
361 * 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
|
362 * 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
|
363 * "/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
|
364 * 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
|
365 * (filename). |
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 * @param filename file containing sound data. |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
368 * @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
|
369 * if you don't need conversion. |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
370 * @param bufferSize size, in bytes, of initial read buffer. |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
371 * @returns Sound_Sample pointer, which is used as a handle to several other |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
372 * SDL_sound APIs. NULL on error. If error, use |
186
70561bf8d5fd
Updated and clarified some documentation.
Ryan C. Gordon <icculus@icculus.org>
parents:
184
diff
changeset
|
373 * Sound_GetError() to see what went wrong. |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
374 */ |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
375 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
|
376 Sound_AudioInfo *desired, |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
377 Uint32 bufferSize); |
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 * Dispose of a Sound_Sample pointer that was returned from Sound_NewSample(). |
381 * This will also close/dispose of the SDL_RWops that was used at creation | |
382 * time, so there's no need to keep a reference to that around. | |
383 * The Sound_Sample pointer is invalid after this call, and will almost | |
384 * certainly result in a crash if you attempt to keep using it. | |
385 * | |
386 * @param sample The Sound_Sample to delete. | |
387 */ | |
388 extern DECLSPEC void Sound_FreeSample(Sound_Sample *sample); | |
389 | |
390 | |
391 /** | |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
392 * 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
|
393 * 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
|
394 * 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
|
395 * 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
|
396 * 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
|
397 * 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
|
398 * it yourself. |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
399 * |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
400 * 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
|
401 * 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
|
402 * 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
|
403 * 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
|
404 * 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
|
405 * MUCH larger buffer). |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
406 * |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
407 * @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
|
408 * @param new_size The desired size, in bytes, of the new buffer. |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
409 * @returns non-zero if buffer size changed, zero on failure. |
3
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
410 */ |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
411 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
|
412 |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
413 |
fd6cd0e04e6f
First stab at implementation complete.
Ryan C. Gordon <icculus@icculus.org>
parents:
1
diff
changeset
|
414 /** |
0 | 415 * Decode more of the sound data in a Sound_Sample. It will decode at most |
416 * sample->buffer_size bytes into sample->buffer in the desired format, and | |
417 * return the number of decoded bytes. | |
418 * If sample->buffer_size bytes could not be decoded, then please refer to | |
419 * sample->flags to determine if this was an End-of-stream or error condition. | |
420 * | |
421 * @param sample Do more decoding to this Sound_Sample. | |
186
70561bf8d5fd
Updated and clarified some documentation.
Ryan C. Gordon <icculus@icculus.org>
parents:
184
diff
changeset
|
422 * @returns number of bytes decoded into sample->buffer. If it is less than |
0 | 423 * sample->buffer_size, then you should check sample->flags to see |
424 * what the current state of the sample is (EOF, error, read again). | |
425 */ | |
426 extern DECLSPEC Uint32 Sound_Decode(Sound_Sample *sample); | |
427 | |
428 | |
429 /** | |
430 * Decode the remainder of the sound data in a Sound_Sample. This will | |
431 * dynamically allocate memory for the ENTIRE remaining sample. | |
432 * sample->buffer_size and sample->buffer will be updated to reflect the | |
433 * new buffer. Please refer to sample->flags to determine if the decoding | |
434 * finished due to an End-of-stream or error condition. | |
435 * | |
436 * Be aware that sound data can take a large amount of memory, and that | |
437 * this function may block for quite awhile while processing. Also note | |
438 * that a streaming source (for example, from a SDL_RWops that is getting | |
439 * fed from an Internet radio feed that doesn't end) may fill all available | |
440 * memory before giving up...be sure to use this on finite sound sources | |
441 * only! | |
442 * | |
170
e91fb8d5bd62
Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents:
149
diff
changeset
|
443 * 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
|
444 * 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
|
445 * 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
|
446 * 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
|
447 * 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
|
448 * 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
|
449 * 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
|
450 * the sample isn't specific and small. |
e91fb8d5bd62
Updated Sound_DecodeAll()'s comments.
Ryan C. Gordon <icculus@icculus.org>
parents:
149
diff
changeset
|
451 * |
0 | 452 * @param sample Do all decoding for this Sound_Sample. |
184
47cc2de2ae36
Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents:
170
diff
changeset
|
453 * @returns 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
|
454 * 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
|
455 * (EOF, error, read again). |
0 | 456 */ |
457 extern DECLSPEC Uint32 Sound_DecodeAll(Sound_Sample *sample); | |
458 | |
223
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
459 |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
460 /** |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
461 * Restart a sample at the start of its waveform data, as if newly |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
462 * created with Sound_NewSample(). If successful, the next call to |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
463 * Sound_Decode[All]() will give audio data from the earliest point |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
464 * in the stream. |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
465 * |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
466 * Beware that this function will fail if the SDL_RWops that feeds the |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
467 * decoder can not be rewound via it's seek method, but this can |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
468 * theoretically be avoided by wrapping it in some sort of buffering |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
469 * SDL_RWops. |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
470 * |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
471 * This function should ONLY fail if the RWops is not seekable, or |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
472 * SDL_sound is not initialized. Both can be controlled by the application, |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
473 * and thus, it is up to the developer's paranoia to dictate whether this |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
474 * function's return value need be checked at all. |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
475 * |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
476 * If this function fails, the state of the sample is undefined, but it |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
477 * is still safe to call Sound_FreeSample() to dispose of it. |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
478 * |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
479 * On success, ERROR, EOF, and EAGAIN are cleared from sample->flags. The |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
480 * ERROR flag is set on error. |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
481 * |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
482 * @param sample The Sound_Sample to rewind. |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
483 * @return nonzero on success, zero on error. Specifics of the |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
484 * error can be gleaned from Sound_GetError(). |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
485 */ |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
486 extern DECLSPEC int Sound_Rewind(Sound_Sample *sample); |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
487 |
249186e31431
Sound_Rewind() support code.
Ryan C. Gordon <icculus@icculus.org>
parents:
194
diff
changeset
|
488 |
0 | 489 #ifdef __cplusplus |
490 } | |
491 #endif | |
492 | |
1
508aac690b19
Whoops...changed some overlooked "voice" to "sound".
Ryan C. Gordon <icculus@icculus.org>
parents:
0
diff
changeset
|
493 #endif /* !defined _INCLUDE_SDL_SOUND_H_ */ |
0 | 494 |
495 /* end of SDL_sound.h ... */ | |
496 |