70 * |
70 * |
71 * @note The calculated values in this structure are calculated by SDL_OpenAudio() |
71 * @note The calculated values in this structure are calculated by SDL_OpenAudio() |
72 * |
72 * |
73 */ |
73 */ |
74 typedef struct SDL_AudioSpec { |
74 typedef struct SDL_AudioSpec { |
75 int freq; /**< DSP frequency -- samples per second */ |
75 int freq; /**< DSP frequency -- samples per second */ |
76 Uint16 format; /**< Audio data format */ |
76 Uint16 format; /**< Audio data format */ |
77 Uint8 channels; /**< Number of channels: 1 mono, 2 stereo */ |
77 Uint8 channels; /**< Number of channels: 1 mono, 2 stereo */ |
78 Uint8 silence; /**< Audio buffer silence value (calculated) */ |
78 Uint8 silence; /**< Audio buffer silence value (calculated) */ |
79 Uint16 samples; /**< Audio buffer size in samples (power of 2) */ |
79 Uint16 samples; /**< Audio buffer size in samples (power of 2) */ |
80 Uint16 padding; /**< Necessary for some compile environments */ |
80 Uint16 padding; /**< Necessary for some compile environments */ |
81 Uint32 size; /**< Audio buffer size in bytes (calculated) */ |
81 Uint32 size; /**< Audio buffer size in bytes (calculated) */ |
82 /** |
82 /** |
83 * This function is called when the audio device needs more data. |
83 * This function is called when the audio device needs more data. |
84 * |
84 * |
85 * @param[out] stream A pointer to the audio data buffer |
85 * @param[out] stream A pointer to the audio data buffer |
86 * @param[in] len The length of the audio buffer in bytes. |
86 * @param[in] len The length of the audio buffer in bytes. |
87 * |
87 * |
88 * Once the callback returns, the buffer will no longer be valid. |
88 * Once the callback returns, the buffer will no longer be valid. |
89 * Stereo samples are stored in a LRLRLR ordering. |
89 * Stereo samples are stored in a LRLRLR ordering. |
90 */ |
90 */ |
91 void (SDLCALL *callback)(void *userdata, Uint8 *stream, int len); |
91 void (SDLCALL *callback)(void *userdata, Uint8 *stream, int len); |
92 void *userdata; |
92 void *userdata; |
93 } SDL_AudioSpec; |
93 } SDL_AudioSpec; |
94 |
94 |
95 /** |
95 /** |
96 * @name Audio format flags |
96 * @name Audio format flags |
97 * defaults to LSB byte order |
97 * defaults to LSB byte order |
98 */ |
98 */ |
99 /*@{*/ |
99 /*@{*/ |
100 #define AUDIO_U8 0x0008 /**< Unsigned 8-bit samples */ |
100 #define AUDIO_U8 0x0008 /**< Unsigned 8-bit samples */ |
101 #define AUDIO_S8 0x8008 /**< Signed 8-bit samples */ |
101 #define AUDIO_S8 0x8008 /**< Signed 8-bit samples */ |
102 #define AUDIO_U16LSB 0x0010 /**< Unsigned 16-bit samples */ |
102 #define AUDIO_U16LSB 0x0010 /**< Unsigned 16-bit samples */ |
103 #define AUDIO_S16LSB 0x8010 /**< Signed 16-bit samples */ |
103 #define AUDIO_S16LSB 0x8010 /**< Signed 16-bit samples */ |
104 #define AUDIO_U16MSB 0x1010 /**< As above, but big-endian byte order */ |
104 #define AUDIO_U16MSB 0x1010 /**< As above, but big-endian byte order */ |
105 #define AUDIO_S16MSB 0x9010 /**< As above, but big-endian byte order */ |
105 #define AUDIO_S16MSB 0x9010 /**< As above, but big-endian byte order */ |
106 #define AUDIO_U16 AUDIO_U16LSB |
106 #define AUDIO_U16 AUDIO_U16LSB |
107 #define AUDIO_S16 AUDIO_S16LSB |
107 #define AUDIO_S16 AUDIO_S16LSB |
108 |
108 |
109 /** |
109 /** |
110 * @name Native audio byte ordering |
110 * @name Native audio byte ordering |
111 */ |
111 */ |
112 /*@{*/ |
112 /*@{*/ |
113 #if SDL_BYTEORDER == SDL_LIL_ENDIAN |
113 #if SDL_BYTEORDER == SDL_LIL_ENDIAN |
114 #define AUDIO_U16SYS AUDIO_U16LSB |
114 #define AUDIO_U16SYS AUDIO_U16LSB |
115 #define AUDIO_S16SYS AUDIO_S16LSB |
115 #define AUDIO_S16SYS AUDIO_S16LSB |
116 #else |
116 #else |
117 #define AUDIO_U16SYS AUDIO_U16MSB |
117 #define AUDIO_U16SYS AUDIO_U16MSB |
118 #define AUDIO_S16SYS AUDIO_S16MSB |
118 #define AUDIO_S16SYS AUDIO_S16MSB |
119 #endif |
119 #endif |
120 /*@}*/ |
120 /*@}*/ |
121 |
121 |
122 /*@}*/ |
122 /*@}*/ |
123 |
123 |
124 |
124 |
125 /** A structure to hold a set of audio conversion filters and buffers */ |
125 /** A structure to hold a set of audio conversion filters and buffers */ |
126 typedef struct SDL_AudioCVT { |
126 typedef struct SDL_AudioCVT { |
127 int needed; /**< Set to 1 if conversion possible */ |
127 int needed; /**< Set to 1 if conversion possible */ |
128 Uint16 src_format; /**< Source audio format */ |
128 Uint16 src_format; /**< Source audio format */ |
129 Uint16 dst_format; /**< Target audio format */ |
129 Uint16 dst_format; /**< Target audio format */ |
130 double rate_incr; /**< Rate conversion increment */ |
130 double rate_incr; /**< Rate conversion increment */ |
131 Uint8 *buf; /**< Buffer to hold entire audio data */ |
131 Uint8 *buf; /**< Buffer to hold entire audio data */ |
132 int len; /**< Length of original audio buffer */ |
132 int len; /**< Length of original audio buffer */ |
133 int len_cvt; /**< Length of converted audio buffer */ |
133 int len_cvt; /**< Length of converted audio buffer */ |
134 int len_mult; /**< buffer must be len*len_mult big */ |
134 int len_mult; /**< buffer must be len*len_mult big */ |
135 double len_ratio; /**< Given len, final size is len*len_ratio */ |
135 double len_ratio; /**< Given len, final size is len*len_ratio */ |
136 void (SDLCALL *filters[10])(struct SDL_AudioCVT *cvt, Uint16 format); |
136 void (SDLCALL *filters[10])(struct SDL_AudioCVT *cvt, Uint16 format); |
137 int filter_index; /**< Current audio conversion function */ |
137 int filter_index; /**< Current audio conversion function */ |
138 } SDL_AudioCVT; |
138 } SDL_AudioCVT; |
139 |
139 |
140 |
140 |
141 /* Function prototypes */ |
141 /* Function prototypes */ |
142 |
142 |
162 * This function opens the audio device with the desired parameters, and |
162 * This function opens the audio device with the desired parameters, and |
163 * returns 0 if successful, placing the actual hardware parameters in the |
163 * returns 0 if successful, placing the actual hardware parameters in the |
164 * structure pointed to by 'obtained'. If 'obtained' is NULL, the audio |
164 * structure pointed to by 'obtained'. If 'obtained' is NULL, the audio |
165 * data passed to the callback function will be guaranteed to be in the |
165 * data passed to the callback function will be guaranteed to be in the |
166 * requested format, and will be automatically converted to the hardware |
166 * requested format, and will be automatically converted to the hardware |
167 * audio format if necessary. This function returns -1 if it failed |
167 * audio format if necessary. This function returns -1 if it failed |
168 * to open the audio device, or couldn't set up the audio thread. |
168 * to open the audio device, or couldn't set up the audio thread. |
169 * |
169 * |
170 * The audio device starts out playing silence when it's opened, and should |
170 * The audio device starts out playing silence when it's opened, and should |
171 * be enabled for playing by calling SDL_PauseAudio(0) when you are ready |
171 * be enabled for playing by calling SDL_PauseAudio(0) when you are ready |
172 * for your audio callback function to be called. Since the audio driver |
172 * for your audio callback function to be called. Since the audio driver |
197 |
197 |
198 /** |
198 /** |
199 * This function loads a WAVE from the data source, automatically freeing |
199 * This function loads a WAVE from the data source, automatically freeing |
200 * that source if 'freesrc' is non-zero. For example, to load a WAVE file, |
200 * that source if 'freesrc' is non-zero. For example, to load a WAVE file, |
201 * you could do: |
201 * you could do: |
202 * @code SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); @endcode |
202 * @code SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); @endcode |
203 * |
203 * |
204 * If this function succeeds, it returns the given SDL_AudioSpec, |
204 * If this function succeeds, it returns the given SDL_AudioSpec, |
205 * filled with the audio data format of the wave data, and sets |
205 * filled with the audio data format of the wave data, and sets |
206 * 'audio_buf' to a malloc()'d buffer containing the audio data, |
206 * 'audio_buf' to a malloc()'d buffer containing the audio data, |
207 * and sets 'audio_len' to the length of that audio buffer, in bytes. |
207 * and sets 'audio_len' to the length of that audio buffer, in bytes. |
208 * You need to free the audio buffer with SDL_FreeWAV() when you are |
208 * You need to free the audio buffer with SDL_FreeWAV() when you are |
209 * done with it. |
209 * done with it. |
210 * |
210 * |
211 * This function returns NULL and sets the SDL error message if the |
211 * This function returns NULL and sets the SDL error message if the |
212 * wave file cannot be opened, uses an unknown data format, or is |
212 * wave file cannot be opened, uses an unknown data format, or is |
213 * corrupt. Currently raw and MS-ADPCM WAVE files are supported. |
213 * corrupt. Currently raw and MS-ADPCM WAVE files are supported. |
214 */ |
214 */ |
215 extern DECLSPEC SDL_AudioSpec * SDLCALL SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); |
215 extern DECLSPEC SDL_AudioSpec * SDLCALL SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); |
216 |
216 |
217 /** Compatibility convenience function -- loads a WAV from a file */ |
217 /** Compatibility convenience function -- loads a WAV from a file */ |
218 #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \ |
218 #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \ |
219 SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len) |
219 SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len) |
220 |
220 |
221 /** |
221 /** |
222 * This function frees data previously allocated with SDL_LoadWAV_RW() |
222 * This function frees data previously allocated with SDL_LoadWAV_RW() |
223 */ |
223 */ |
224 extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 *audio_buf); |
224 extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 *audio_buf); |
230 * to the other. |
230 * to the other. |
231 * |
231 * |
232 * @return This function returns 0, or -1 if there was an error. |
232 * @return This function returns 0, or -1 if there was an error. |
233 */ |
233 */ |
234 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT *cvt, |
234 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT *cvt, |
235 Uint16 src_format, Uint8 src_channels, int src_rate, |
235 Uint16 src_format, Uint8 src_channels, int src_rate, |
236 Uint16 dst_format, Uint8 dst_channels, int dst_rate); |
236 Uint16 dst_format, Uint8 dst_channels, int dst_rate); |
237 |
237 |
238 /** |
238 /** |
239 * Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(), |
239 * Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(), |
240 * created an audio buffer cvt->buf, and filled it with cvt->len bytes of |
240 * created an audio buffer cvt->buf, and filled it with cvt->len bytes of |
241 * audio data in the source format, this function will convert it in-place |
241 * audio data in the source format, this function will convert it in-place |