00001 /* 00002 SDL - Simple DirectMedia Layer 00003 Copyright (C) 1997-2009 Sam Lantinga 00004 00005 This library is free software; you can redistribute it and/or 00006 modify it under the terms of the GNU Lesser General Public 00007 License as published by the Free Software Foundation; either 00008 version 2.1 of the License, or (at your option) any later version. 00009 00010 This library is distributed in the hope that it will be useful, 00011 but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00013 Lesser General Public License for more details. 00014 00015 You should have received a copy of the GNU Lesser General Public 00016 License along with this library; if not, write to the Free Software 00017 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 00018 00019 Sam Lantinga 00020 slouken@libsdl.org 00021 */ 00022 00029 #ifndef _SDL_audio_h 00030 #define _SDL_audio_h 00031 00032 #include "SDL_stdinc.h" 00033 #include "SDL_error.h" 00034 #include "SDL_endian.h" 00035 #include "SDL_mutex.h" 00036 #include "SDL_thread.h" 00037 #include "SDL_rwops.h" 00038 00039 #include "begin_code.h" 00040 /* Set up for C function definitions, even when using C++ */ 00041 #ifdef __cplusplus 00042 /* *INDENT-OFF* */ 00043 extern "C" { 00044 /* *INDENT-ON* */ 00045 #endif 00046 00047 typedef Uint16 SDL_AudioFormat; 00048 00049 /* The calculated values in this structure are calculated by SDL_OpenAudio() */ 00050 typedef struct SDL_AudioSpec 00051 { 00052 int freq; /* DSP frequency -- samples per second */ 00053 SDL_AudioFormat format; /* Audio data format */ 00054 Uint8 channels; /* Number of channels: 1 mono, 2 stereo */ 00055 Uint8 silence; /* Audio buffer silence value (calculated) */ 00056 Uint16 samples; /* Audio buffer size in samples (power of 2) */ 00057 Uint16 padding; /* Necessary for some compile environments */ 00058 Uint32 size; /* Audio buffer size in bytes (calculated) */ 00059 /* This function is called when the audio device needs more data. 00060 'stream' is a pointer to the audio data buffer 00061 'len' is the length of that buffer in bytes. 00062 Once the callback returns, the buffer will no longer be valid. 00063 Stereo samples are stored in a LRLRLR ordering. 00064 */ 00065 void (SDLCALL * callback) (void *userdata, Uint8 * stream, int len); 00066 void *userdata; 00067 } SDL_AudioSpec; 00068 00069 00070 /* 00071 These are what the 16 bits in SDL_AudioFormat currently mean... 00072 (Unspecified bits are always zero.) 00073 00074 ++-----------------------sample is signed if set 00075 || 00076 || ++-----------sample is bigendian if set 00077 || || 00078 || || ++---sample is float if set 00079 || || || 00080 || || || +---sample bit size---+ 00081 || || || | | 00082 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 00083 00084 There are macros in SDL 1.3 and later to query these bits. 00085 */ 00086 00087 #define SDL_AUDIO_MASK_BITSIZE (0xFF) 00088 #define SDL_AUDIO_MASK_DATATYPE (1<<8) 00089 #define SDL_AUDIO_MASK_ENDIAN (1<<12) 00090 #define SDL_AUDIO_MASK_SIGNED (1<<15) 00091 #define SDL_AUDIO_BITSIZE(x) (x & SDL_AUDIO_MASK_BITSIZE) 00092 #define SDL_AUDIO_ISFLOAT(x) (x & SDL_AUDIO_MASK_DATATYPE) 00093 #define SDL_AUDIO_ISBIGENDIAN(x) (x & SDL_AUDIO_MASK_ENDIAN) 00094 #define SDL_AUDIO_ISSIGNED(x) (x & SDL_AUDIO_MASK_SIGNED) 00095 #define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x)) 00096 #define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x)) 00097 #define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x)) 00098 00099 /* Audio format flags (defaults to LSB byte order) */ 00100 #define AUDIO_U8 0x0008 /* Unsigned 8-bit samples */ 00101 #define AUDIO_S8 0x8008 /* Signed 8-bit samples */ 00102 #define AUDIO_U16LSB 0x0010 /* Unsigned 16-bit samples */ 00103 #define AUDIO_S16LSB 0x8010 /* Signed 16-bit samples */ 00104 #define AUDIO_U16MSB 0x1010 /* As above, but big-endian byte order */ 00105 #define AUDIO_S16MSB 0x9010 /* As above, but big-endian byte order */ 00106 #define AUDIO_U16 AUDIO_U16LSB 00107 #define AUDIO_S16 AUDIO_S16LSB 00108 00109 /* int32 support new to SDL 1.3 */ 00110 #define AUDIO_S32LSB 0x8020 /* 32-bit integer samples */ 00111 #define AUDIO_S32MSB 0x9020 /* As above, but big-endian byte order */ 00112 #define AUDIO_S32 AUDIO_S32LSB 00113 00114 /* float32 support new to SDL 1.3 */ 00115 #define AUDIO_F32LSB 0x8120 /* 32-bit floating point samples */ 00116 #define AUDIO_F32MSB 0x9120 /* As above, but big-endian byte order */ 00117 #define AUDIO_F32 AUDIO_F32LSB 00118 00119 /* Native audio byte ordering */ 00120 #if SDL_BYTEORDER == SDL_LIL_ENDIAN 00121 #define AUDIO_U16SYS AUDIO_U16LSB 00122 #define AUDIO_S16SYS AUDIO_S16LSB 00123 #define AUDIO_S32SYS AUDIO_S32LSB 00124 #define AUDIO_F32SYS AUDIO_F32LSB 00125 #else 00126 #define AUDIO_U16SYS AUDIO_U16MSB 00127 #define AUDIO_S16SYS AUDIO_S16MSB 00128 #define AUDIO_S32SYS AUDIO_S32MSB 00129 #define AUDIO_F32SYS AUDIO_F32MSB 00130 #endif 00131 00132 /* Which audio format changes are allowed when opening a device */ 00133 #define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE 0x00000001 00134 #define SDL_AUDIO_ALLOW_FORMAT_CHANGE 0x00000002 00135 #define SDL_AUDIO_ALLOW_CHANNELS_CHANGE 0x00000004 00136 #define SDL_AUDIO_ALLOW_ANY_CHANGE (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE) 00137 00138 /* A structure to hold a set of audio conversion filters and buffers */ 00139 struct SDL_AudioCVT; 00140 typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt, 00141 SDL_AudioFormat format); 00142 00143 typedef struct SDL_AudioCVT 00144 { 00145 int needed; /* Set to 1 if conversion possible */ 00146 SDL_AudioFormat src_format; /* Source audio format */ 00147 SDL_AudioFormat dst_format; /* Target audio format */ 00148 double rate_incr; /* Rate conversion increment */ 00149 Uint8 *buf; /* Buffer to hold entire audio data */ 00150 int len; /* Length of original audio buffer */ 00151 int len_cvt; /* Length of converted audio buffer */ 00152 int len_mult; /* buffer must be len*len_mult big */ 00153 double len_ratio; /* Given len, final size is len*len_ratio */ 00154 SDL_AudioFilter filters[10]; /* Filter list */ 00155 int filter_index; /* Current audio conversion function */ 00156 } SDL_AudioCVT; 00157 00158 00159 /* Function prototypes */ 00160 00161 /* These functions return the list of built in audio drivers, in the 00162 * order that they are normally initialized by default. 00163 */ 00164 extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); 00165 extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index); 00166 00167 /* These functions are used internally, and should not be used unless you 00168 * have a specific need to specify the audio driver you want to use. 00169 * You should normally use SDL_Init() or SDL_InitSubSystem(). 00170 */ 00171 extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name); 00172 extern DECLSPEC void SDLCALL SDL_AudioQuit(void); 00173 00174 /* This function returns the name of the current audio driver, or NULL 00175 * if no driver has been initialized. 00176 */ 00177 extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void); 00178 00179 /* 00180 * This function opens the audio device with the desired parameters, and 00181 * returns 0 if successful, placing the actual hardware parameters in the 00182 * structure pointed to by 'obtained'. If 'obtained' is NULL, the audio 00183 * data passed to the callback function will be guaranteed to be in the 00184 * requested format, and will be automatically converted to the hardware 00185 * audio format if necessary. This function returns -1 if it failed 00186 * to open the audio device, or couldn't set up the audio thread. 00187 * 00188 * When filling in the desired audio spec structure, 00189 * 'desired->freq' should be the desired audio frequency in samples-per-second. 00190 * 'desired->format' should be the desired audio format. 00191 * 'desired->samples' is the desired size of the audio buffer, in samples. 00192 * This number should be a power of two, and may be adjusted by the audio 00193 * driver to a value more suitable for the hardware. Good values seem to 00194 * range between 512 and 8096 inclusive, depending on the application and 00195 * CPU speed. Smaller values yield faster response time, but can lead 00196 * to underflow if the application is doing heavy processing and cannot 00197 * fill the audio buffer in time. A stereo sample consists of both right 00198 * and left channels in LR ordering. 00199 * Note that the number of samples is directly related to time by the 00200 * following formula: ms = (samples*1000)/freq 00201 * 'desired->size' is the size in bytes of the audio buffer, and is 00202 * calculated by SDL_OpenAudio(). 00203 * 'desired->silence' is the value used to set the buffer to silence, 00204 * and is calculated by SDL_OpenAudio(). 00205 * 'desired->callback' should be set to a function that will be called 00206 * when the audio device is ready for more data. It is passed a pointer 00207 * to the audio buffer, and the length in bytes of the audio buffer. 00208 * This function usually runs in a separate thread, and so you should 00209 * protect data structures that it accesses by calling SDL_LockAudio() 00210 * and SDL_UnlockAudio() in your code. 00211 * 'desired->userdata' is passed as the first parameter to your callback 00212 * function. 00213 * 00214 * The audio device starts out playing silence when it's opened, and should 00215 * be enabled for playing by calling SDL_PauseAudio(0) when you are ready 00216 * for your audio callback function to be called. Since the audio driver 00217 * may modify the requested size of the audio buffer, you should allocate 00218 * any local mixing buffers after you open the audio device. 00219 */ 00220 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired, 00221 SDL_AudioSpec * obtained); 00222 00223 /* 00224 * SDL Audio Device IDs. 00225 * A successful call to SDL_OpenAudio() is always device id 1, and legacy 00226 * SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls 00227 * always returns devices >= 2 on success. The legacy calls are good both 00228 * for backwards compatibility and when you don't care about multiple, 00229 * specific, or capture devices. 00230 */ 00231 typedef Uint32 SDL_AudioDeviceID; 00232 00233 /* 00234 * Get the number of available devices exposed by the current driver. 00235 * Only valid after a successfully initializing the audio subsystem. 00236 * Returns -1 if an explicit list of devices can't be determined; this is 00237 * not an error. For example, if SDL is set up to talk to a remote audio 00238 * server, it can't list every one available on the Internet, but it will 00239 * still allow a specific host to be specified to SDL_OpenAudioDevice(). 00240 * In many common cases, when this function returns a value <= 0, it can still 00241 * successfully open the default device (NULL for first argument of 00242 * SDL_OpenAudioDevice()). 00243 */ 00244 extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture); 00245 00246 /* 00247 * Get the human-readable name of a specific audio device. 00248 * Must be a value between 0 and (number of audio devices-1). 00249 * Only valid after a successfully initializing the audio subsystem. 00250 * The values returned by this function reflect the latest call to 00251 * SDL_GetNumAudioDevices(); recall that function to redetect available 00252 * hardware. 00253 * 00254 * The string returned by this function is UTF-8 encoded, read-only, and 00255 * managed internally. You are not to free it. If you need to keep the 00256 * string for any length of time, you should make your own copy of it, as it 00257 * will be invalid next time any of several other SDL functions is called. 00258 */ 00259 extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index, 00260 int iscapture); 00261 00262 00263 /* 00264 * Open a specific audio device. Passing in a device name of NULL requests 00265 * the most reasonable default (and is equivalent to calling SDL_OpenAudio()). 00266 * The device name is a UTF-8 string reported by SDL_GetAudioDevice(), but 00267 * some drivers allow arbitrary and driver-specific strings, such as a 00268 * hostname/IP address for a remote audio server, or a filename in the 00269 * diskaudio driver. 00270 * Returns 0 on error, a valid device ID that is >= 2 on success. 00271 * SDL_OpenAudio(), unlike this function, always acts on device ID 1. 00272 */ 00273 extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char 00274 *device, 00275 int iscapture, 00276 const 00277 SDL_AudioSpec * 00278 desired, 00279 SDL_AudioSpec * 00280 obtained, 00281 int 00282 allowed_changes); 00283 00284 00285 00286 /* 00287 * Get the current audio state: 00288 */ 00289 typedef enum 00290 { 00291 SDL_AUDIO_STOPPED = 0, 00292 SDL_AUDIO_PLAYING, 00293 SDL_AUDIO_PAUSED 00294 } SDL_audiostatus; 00295 extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void); 00296 00297 extern DECLSPEC SDL_audiostatus SDLCALL 00298 SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev); 00299 00300 /* 00301 * This function pauses and unpauses the audio callback processing. 00302 * It should be called with a parameter of 0 after opening the audio 00303 * device to start playing sound. This is so you can safely initialize 00304 * data for your callback function after opening the audio device. 00305 * Silence will be written to the audio device during the pause. 00306 */ 00307 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on); 00308 extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev, 00309 int pause_on); 00310 00311 /* 00312 * This function loads a WAVE from the data source, automatically freeing 00313 * that source if 'freesrc' is non-zero. For example, to load a WAVE file, 00314 * you could do: 00315 * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); 00316 * 00317 * If this function succeeds, it returns the given SDL_AudioSpec, 00318 * filled with the audio data format of the wave data, and sets 00319 * 'audio_buf' to a malloc()'d buffer containing the audio data, 00320 * and sets 'audio_len' to the length of that audio buffer, in bytes. 00321 * You need to free the audio buffer with SDL_FreeWAV() when you are 00322 * done with it. 00323 * 00324 * This function returns NULL and sets the SDL error message if the 00325 * wave file cannot be opened, uses an unknown data format, or is 00326 * corrupt. Currently raw and MS-ADPCM WAVE files are supported. 00327 */ 00328 extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, 00329 int freesrc, 00330 SDL_AudioSpec * spec, 00331 Uint8 ** audio_buf, 00332 Uint32 * audio_len); 00333 00334 /* Compatibility convenience function -- loads a WAV from a file */ 00335 #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \ 00336 SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len) 00337 00338 /* 00339 * This function frees data previously allocated with SDL_LoadWAV_RW() 00340 */ 00341 extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf); 00342 00343 /* 00344 * This function takes a source format and rate and a destination format 00345 * and rate, and initializes the 'cvt' structure with information needed 00346 * by SDL_ConvertAudio() to convert a buffer of audio data from one format 00347 * to the other. 00348 * Returns -1 if the format conversion is not supported, 0 if there's 00349 * no conversion needed, or 1 if the audio filter is set up. 00350 */ 00351 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt, 00352 SDL_AudioFormat src_format, 00353 Uint8 src_channels, 00354 int src_rate, 00355 SDL_AudioFormat dst_format, 00356 Uint8 dst_channels, 00357 int dst_rate); 00358 00359 /* Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(), 00360 * created an audio buffer cvt->buf, and filled it with cvt->len bytes of 00361 * audio data in the source format, this function will convert it in-place 00362 * to the desired format. 00363 * The data conversion may expand the size of the audio data, so the buffer 00364 * cvt->buf should be allocated after the cvt structure is initialized by 00365 * SDL_BuildAudioCVT(), and should be cvt->len*cvt->len_mult bytes long. 00366 */ 00367 extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt); 00368 00369 /* 00370 * This takes two audio buffers of the playing audio format and mixes 00371 * them, performing addition, volume adjustment, and overflow clipping. 00372 * The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME 00373 * for full audio volume. Note this does not change hardware volume. 00374 * This is provided for convenience -- you can mix your own audio data. 00375 */ 00376 #define SDL_MIX_MAXVOLUME 128 00377 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src, 00378 Uint32 len, int volume); 00379 00380 /* 00381 * This works like SDL_MixAudio, but you specify the audio format instead of 00382 * using the format of audio device 1. Thus it can be used when no audio 00383 * device is open at all. 00384 */ 00385 extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, 00386 const Uint8 * src, 00387 SDL_AudioFormat format, 00388 Uint32 len, int volume); 00389 00390 /* 00391 * The lock manipulated by these functions protects the callback function. 00392 * During a LockAudio/UnlockAudio pair, you can be guaranteed that the 00393 * callback function is not running. Do not call these from the callback 00394 * function or you will cause deadlock. 00395 */ 00396 extern DECLSPEC void SDLCALL SDL_LockAudio(void); 00397 extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev); 00398 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void); 00399 extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev); 00400 00401 /* 00402 * This function shuts down audio processing and closes the audio device. 00403 */ 00404 extern DECLSPEC void SDLCALL SDL_CloseAudio(void); 00405 extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev); 00406 00407 /* 00408 * Returns 1 if audio device is still functioning, zero if not, -1 on error. 00409 */ 00410 extern DECLSPEC int SDLCALL SDL_AudioDeviceConnected(SDL_AudioDeviceID dev); 00411 00412 00413 /* Ends C function definitions when using C++ */ 00414 #ifdef __cplusplus 00415 /* *INDENT-OFF* */ 00416 } 00417 /* *INDENT-ON* */ 00418 #endif 00419 #include "close_code.h" 00420 00421 #endif /* _SDL_audio_h */ 00422 00423 /* vi: set ts=4 sw=4 expandtab: */
1.5.8