SDL standard library
SDL_audio.h@0:dda4f4550403, 2016-09-07 (annotated)
- Committer:
- miruga27
- Date:
- Wed Sep 07 18:46:53 2016 +0000
- Revision:
- 0:dda4f4550403
7/09/2016;
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
miruga27 | 0:dda4f4550403 | 1 | /* |
miruga27 | 0:dda4f4550403 | 2 | Simple DirectMedia Layer |
miruga27 | 0:dda4f4550403 | 3 | Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org> |
miruga27 | 0:dda4f4550403 | 4 | |
miruga27 | 0:dda4f4550403 | 5 | This software is provided 'as-is', without any express or implied |
miruga27 | 0:dda4f4550403 | 6 | warranty. In no event will the authors be held liable for any damages |
miruga27 | 0:dda4f4550403 | 7 | arising from the use of this software. |
miruga27 | 0:dda4f4550403 | 8 | |
miruga27 | 0:dda4f4550403 | 9 | Permission is granted to anyone to use this software for any purpose, |
miruga27 | 0:dda4f4550403 | 10 | including commercial applications, and to alter it and redistribute it |
miruga27 | 0:dda4f4550403 | 11 | freely, subject to the following restrictions: |
miruga27 | 0:dda4f4550403 | 12 | |
miruga27 | 0:dda4f4550403 | 13 | 1. The origin of this software must not be misrepresented; you must not |
miruga27 | 0:dda4f4550403 | 14 | claim that you wrote the original software. If you use this software |
miruga27 | 0:dda4f4550403 | 15 | in a product, an acknowledgment in the product documentation would be |
miruga27 | 0:dda4f4550403 | 16 | appreciated but is not required. |
miruga27 | 0:dda4f4550403 | 17 | 2. Altered source versions must be plainly marked as such, and must not be |
miruga27 | 0:dda4f4550403 | 18 | misrepresented as being the original software. |
miruga27 | 0:dda4f4550403 | 19 | 3. This notice may not be removed or altered from any source distribution. |
miruga27 | 0:dda4f4550403 | 20 | */ |
miruga27 | 0:dda4f4550403 | 21 | |
miruga27 | 0:dda4f4550403 | 22 | /** |
miruga27 | 0:dda4f4550403 | 23 | * \file SDL_audio.h |
miruga27 | 0:dda4f4550403 | 24 | * |
miruga27 | 0:dda4f4550403 | 25 | * Access to the raw audio mixing buffer for the SDL library. |
miruga27 | 0:dda4f4550403 | 26 | */ |
miruga27 | 0:dda4f4550403 | 27 | |
miruga27 | 0:dda4f4550403 | 28 | #ifndef _SDL_audio_h |
miruga27 | 0:dda4f4550403 | 29 | #define _SDL_audio_h |
miruga27 | 0:dda4f4550403 | 30 | |
miruga27 | 0:dda4f4550403 | 31 | #include "SDL_stdinc.h" |
miruga27 | 0:dda4f4550403 | 32 | #include "SDL_error.h" |
miruga27 | 0:dda4f4550403 | 33 | #include "SDL_endian.h" |
miruga27 | 0:dda4f4550403 | 34 | #include "SDL_mutex.h" |
miruga27 | 0:dda4f4550403 | 35 | #include "SDL_thread.h" |
miruga27 | 0:dda4f4550403 | 36 | #include "SDL_rwops.h" |
miruga27 | 0:dda4f4550403 | 37 | |
miruga27 | 0:dda4f4550403 | 38 | #include "begin_code.h" |
miruga27 | 0:dda4f4550403 | 39 | /* Set up for C function definitions, even when using C++ */ |
miruga27 | 0:dda4f4550403 | 40 | #ifdef __cplusplus |
miruga27 | 0:dda4f4550403 | 41 | extern "C" { |
miruga27 | 0:dda4f4550403 | 42 | #endif |
miruga27 | 0:dda4f4550403 | 43 | |
miruga27 | 0:dda4f4550403 | 44 | /** |
miruga27 | 0:dda4f4550403 | 45 | * \brief Audio format flags. |
miruga27 | 0:dda4f4550403 | 46 | * |
miruga27 | 0:dda4f4550403 | 47 | * These are what the 16 bits in SDL_AudioFormat currently mean... |
miruga27 | 0:dda4f4550403 | 48 | * (Unspecified bits are always zero). |
miruga27 | 0:dda4f4550403 | 49 | * |
miruga27 | 0:dda4f4550403 | 50 | * \verbatim |
miruga27 | 0:dda4f4550403 | 51 | ++-----------------------sample is signed if set |
miruga27 | 0:dda4f4550403 | 52 | || |
miruga27 | 0:dda4f4550403 | 53 | || ++-----------sample is bigendian if set |
miruga27 | 0:dda4f4550403 | 54 | || || |
miruga27 | 0:dda4f4550403 | 55 | || || ++---sample is float if set |
miruga27 | 0:dda4f4550403 | 56 | || || || |
miruga27 | 0:dda4f4550403 | 57 | || || || +---sample bit size---+ |
miruga27 | 0:dda4f4550403 | 58 | || || || | | |
miruga27 | 0:dda4f4550403 | 59 | 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 |
miruga27 | 0:dda4f4550403 | 60 | \endverbatim |
miruga27 | 0:dda4f4550403 | 61 | * |
miruga27 | 0:dda4f4550403 | 62 | * There are macros in SDL 2.0 and later to query these bits. |
miruga27 | 0:dda4f4550403 | 63 | */ |
miruga27 | 0:dda4f4550403 | 64 | typedef Uint16 SDL_AudioFormat; |
miruga27 | 0:dda4f4550403 | 65 | |
miruga27 | 0:dda4f4550403 | 66 | /** |
miruga27 | 0:dda4f4550403 | 67 | * \name Audio flags |
miruga27 | 0:dda4f4550403 | 68 | */ |
miruga27 | 0:dda4f4550403 | 69 | /* @{ */ |
miruga27 | 0:dda4f4550403 | 70 | |
miruga27 | 0:dda4f4550403 | 71 | #define SDL_AUDIO_MASK_BITSIZE (0xFF) |
miruga27 | 0:dda4f4550403 | 72 | #define SDL_AUDIO_MASK_DATATYPE (1<<8) |
miruga27 | 0:dda4f4550403 | 73 | #define SDL_AUDIO_MASK_ENDIAN (1<<12) |
miruga27 | 0:dda4f4550403 | 74 | #define SDL_AUDIO_MASK_SIGNED (1<<15) |
miruga27 | 0:dda4f4550403 | 75 | #define SDL_AUDIO_BITSIZE(x) (x & SDL_AUDIO_MASK_BITSIZE) |
miruga27 | 0:dda4f4550403 | 76 | #define SDL_AUDIO_ISFLOAT(x) (x & SDL_AUDIO_MASK_DATATYPE) |
miruga27 | 0:dda4f4550403 | 77 | #define SDL_AUDIO_ISBIGENDIAN(x) (x & SDL_AUDIO_MASK_ENDIAN) |
miruga27 | 0:dda4f4550403 | 78 | #define SDL_AUDIO_ISSIGNED(x) (x & SDL_AUDIO_MASK_SIGNED) |
miruga27 | 0:dda4f4550403 | 79 | #define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x)) |
miruga27 | 0:dda4f4550403 | 80 | #define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x)) |
miruga27 | 0:dda4f4550403 | 81 | #define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x)) |
miruga27 | 0:dda4f4550403 | 82 | |
miruga27 | 0:dda4f4550403 | 83 | /** |
miruga27 | 0:dda4f4550403 | 84 | * \name Audio format flags |
miruga27 | 0:dda4f4550403 | 85 | * |
miruga27 | 0:dda4f4550403 | 86 | * Defaults to LSB byte order. |
miruga27 | 0:dda4f4550403 | 87 | */ |
miruga27 | 0:dda4f4550403 | 88 | /* @{ */ |
miruga27 | 0:dda4f4550403 | 89 | #define AUDIO_U8 0x0008 /**< Unsigned 8-bit samples */ |
miruga27 | 0:dda4f4550403 | 90 | #define AUDIO_S8 0x8008 /**< Signed 8-bit samples */ |
miruga27 | 0:dda4f4550403 | 91 | #define AUDIO_U16LSB 0x0010 /**< Unsigned 16-bit samples */ |
miruga27 | 0:dda4f4550403 | 92 | #define AUDIO_S16LSB 0x8010 /**< Signed 16-bit samples */ |
miruga27 | 0:dda4f4550403 | 93 | #define AUDIO_U16MSB 0x1010 /**< As above, but big-endian byte order */ |
miruga27 | 0:dda4f4550403 | 94 | #define AUDIO_S16MSB 0x9010 /**< As above, but big-endian byte order */ |
miruga27 | 0:dda4f4550403 | 95 | #define AUDIO_U16 AUDIO_U16LSB |
miruga27 | 0:dda4f4550403 | 96 | #define AUDIO_S16 AUDIO_S16LSB |
miruga27 | 0:dda4f4550403 | 97 | /* @} */ |
miruga27 | 0:dda4f4550403 | 98 | |
miruga27 | 0:dda4f4550403 | 99 | /** |
miruga27 | 0:dda4f4550403 | 100 | * \name int32 support |
miruga27 | 0:dda4f4550403 | 101 | */ |
miruga27 | 0:dda4f4550403 | 102 | /* @{ */ |
miruga27 | 0:dda4f4550403 | 103 | #define AUDIO_S32LSB 0x8020 /**< 32-bit integer samples */ |
miruga27 | 0:dda4f4550403 | 104 | #define AUDIO_S32MSB 0x9020 /**< As above, but big-endian byte order */ |
miruga27 | 0:dda4f4550403 | 105 | #define AUDIO_S32 AUDIO_S32LSB |
miruga27 | 0:dda4f4550403 | 106 | /* @} */ |
miruga27 | 0:dda4f4550403 | 107 | |
miruga27 | 0:dda4f4550403 | 108 | /** |
miruga27 | 0:dda4f4550403 | 109 | * \name float32 support |
miruga27 | 0:dda4f4550403 | 110 | */ |
miruga27 | 0:dda4f4550403 | 111 | /* @{ */ |
miruga27 | 0:dda4f4550403 | 112 | #define AUDIO_F32LSB 0x8120 /**< 32-bit floating point samples */ |
miruga27 | 0:dda4f4550403 | 113 | #define AUDIO_F32MSB 0x9120 /**< As above, but big-endian byte order */ |
miruga27 | 0:dda4f4550403 | 114 | #define AUDIO_F32 AUDIO_F32LSB |
miruga27 | 0:dda4f4550403 | 115 | /* @} */ |
miruga27 | 0:dda4f4550403 | 116 | |
miruga27 | 0:dda4f4550403 | 117 | /** |
miruga27 | 0:dda4f4550403 | 118 | * \name Native audio byte ordering |
miruga27 | 0:dda4f4550403 | 119 | */ |
miruga27 | 0:dda4f4550403 | 120 | /* @{ */ |
miruga27 | 0:dda4f4550403 | 121 | #if SDL_BYTEORDER == SDL_LIL_ENDIAN |
miruga27 | 0:dda4f4550403 | 122 | #define AUDIO_U16SYS AUDIO_U16LSB |
miruga27 | 0:dda4f4550403 | 123 | #define AUDIO_S16SYS AUDIO_S16LSB |
miruga27 | 0:dda4f4550403 | 124 | #define AUDIO_S32SYS AUDIO_S32LSB |
miruga27 | 0:dda4f4550403 | 125 | #define AUDIO_F32SYS AUDIO_F32LSB |
miruga27 | 0:dda4f4550403 | 126 | #else |
miruga27 | 0:dda4f4550403 | 127 | #define AUDIO_U16SYS AUDIO_U16MSB |
miruga27 | 0:dda4f4550403 | 128 | #define AUDIO_S16SYS AUDIO_S16MSB |
miruga27 | 0:dda4f4550403 | 129 | #define AUDIO_S32SYS AUDIO_S32MSB |
miruga27 | 0:dda4f4550403 | 130 | #define AUDIO_F32SYS AUDIO_F32MSB |
miruga27 | 0:dda4f4550403 | 131 | #endif |
miruga27 | 0:dda4f4550403 | 132 | /* @} */ |
miruga27 | 0:dda4f4550403 | 133 | |
miruga27 | 0:dda4f4550403 | 134 | /** |
miruga27 | 0:dda4f4550403 | 135 | * \name Allow change flags |
miruga27 | 0:dda4f4550403 | 136 | * |
miruga27 | 0:dda4f4550403 | 137 | * Which audio format changes are allowed when opening a device. |
miruga27 | 0:dda4f4550403 | 138 | */ |
miruga27 | 0:dda4f4550403 | 139 | /* @{ */ |
miruga27 | 0:dda4f4550403 | 140 | #define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE 0x00000001 |
miruga27 | 0:dda4f4550403 | 141 | #define SDL_AUDIO_ALLOW_FORMAT_CHANGE 0x00000002 |
miruga27 | 0:dda4f4550403 | 142 | #define SDL_AUDIO_ALLOW_CHANNELS_CHANGE 0x00000004 |
miruga27 | 0:dda4f4550403 | 143 | #define SDL_AUDIO_ALLOW_ANY_CHANGE (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE) |
miruga27 | 0:dda4f4550403 | 144 | /* @} */ |
miruga27 | 0:dda4f4550403 | 145 | |
miruga27 | 0:dda4f4550403 | 146 | /* @} *//* Audio flags */ |
miruga27 | 0:dda4f4550403 | 147 | |
miruga27 | 0:dda4f4550403 | 148 | /** |
miruga27 | 0:dda4f4550403 | 149 | * This function is called when the audio device needs more data. |
miruga27 | 0:dda4f4550403 | 150 | * |
miruga27 | 0:dda4f4550403 | 151 | * \param userdata An application-specific parameter saved in |
miruga27 | 0:dda4f4550403 | 152 | * the SDL_AudioSpec structure |
miruga27 | 0:dda4f4550403 | 153 | * \param stream A pointer to the audio data buffer. |
miruga27 | 0:dda4f4550403 | 154 | * \param len The length of that buffer in bytes. |
miruga27 | 0:dda4f4550403 | 155 | * |
miruga27 | 0:dda4f4550403 | 156 | * Once the callback returns, the buffer will no longer be valid. |
miruga27 | 0:dda4f4550403 | 157 | * Stereo samples are stored in a LRLRLR ordering. |
miruga27 | 0:dda4f4550403 | 158 | */ |
miruga27 | 0:dda4f4550403 | 159 | typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream, |
miruga27 | 0:dda4f4550403 | 160 | int len); |
miruga27 | 0:dda4f4550403 | 161 | |
miruga27 | 0:dda4f4550403 | 162 | /** |
miruga27 | 0:dda4f4550403 | 163 | * The calculated values in this structure are calculated by SDL_OpenAudio(). |
miruga27 | 0:dda4f4550403 | 164 | */ |
miruga27 | 0:dda4f4550403 | 165 | typedef struct SDL_AudioSpec |
miruga27 | 0:dda4f4550403 | 166 | { |
miruga27 | 0:dda4f4550403 | 167 | int freq; /**< DSP frequency -- samples per second */ |
miruga27 | 0:dda4f4550403 | 168 | SDL_AudioFormat format; /**< Audio data format */ |
miruga27 | 0:dda4f4550403 | 169 | Uint8 channels; /**< Number of channels: 1 mono, 2 stereo */ |
miruga27 | 0:dda4f4550403 | 170 | Uint8 silence; /**< Audio buffer silence value (calculated) */ |
miruga27 | 0:dda4f4550403 | 171 | Uint16 samples; /**< Audio buffer size in samples (power of 2) */ |
miruga27 | 0:dda4f4550403 | 172 | Uint16 padding; /**< Necessary for some compile environments */ |
miruga27 | 0:dda4f4550403 | 173 | Uint32 size; /**< Audio buffer size in bytes (calculated) */ |
miruga27 | 0:dda4f4550403 | 174 | SDL_AudioCallback callback; |
miruga27 | 0:dda4f4550403 | 175 | void *userdata; |
miruga27 | 0:dda4f4550403 | 176 | } SDL_AudioSpec; |
miruga27 | 0:dda4f4550403 | 177 | |
miruga27 | 0:dda4f4550403 | 178 | |
miruga27 | 0:dda4f4550403 | 179 | struct SDL_AudioCVT; |
miruga27 | 0:dda4f4550403 | 180 | typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt, |
miruga27 | 0:dda4f4550403 | 181 | SDL_AudioFormat format); |
miruga27 | 0:dda4f4550403 | 182 | |
miruga27 | 0:dda4f4550403 | 183 | /** |
miruga27 | 0:dda4f4550403 | 184 | * A structure to hold a set of audio conversion filters and buffers. |
miruga27 | 0:dda4f4550403 | 185 | */ |
miruga27 | 0:dda4f4550403 | 186 | #ifdef __GNUC__ |
miruga27 | 0:dda4f4550403 | 187 | /* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't |
miruga27 | 0:dda4f4550403 | 188 | pad it out to 88 bytes to guarantee ABI compatibility between compilers. |
miruga27 | 0:dda4f4550403 | 189 | vvv |
miruga27 | 0:dda4f4550403 | 190 | The next time we rev the ABI, make sure to size the ints and add padding. |
miruga27 | 0:dda4f4550403 | 191 | */ |
miruga27 | 0:dda4f4550403 | 192 | #define SDL_AUDIOCVT_PACKED __attribute__((packed)) |
miruga27 | 0:dda4f4550403 | 193 | #else |
miruga27 | 0:dda4f4550403 | 194 | #define SDL_AUDIOCVT_PACKED |
miruga27 | 0:dda4f4550403 | 195 | #endif |
miruga27 | 0:dda4f4550403 | 196 | /* */ |
miruga27 | 0:dda4f4550403 | 197 | typedef struct SDL_AudioCVT |
miruga27 | 0:dda4f4550403 | 198 | { |
miruga27 | 0:dda4f4550403 | 199 | int needed; /**< Set to 1 if conversion possible */ |
miruga27 | 0:dda4f4550403 | 200 | SDL_AudioFormat src_format; /**< Source audio format */ |
miruga27 | 0:dda4f4550403 | 201 | SDL_AudioFormat dst_format; /**< Target audio format */ |
miruga27 | 0:dda4f4550403 | 202 | double rate_incr; /**< Rate conversion increment */ |
miruga27 | 0:dda4f4550403 | 203 | Uint8 *buf; /**< Buffer to hold entire audio data */ |
miruga27 | 0:dda4f4550403 | 204 | int len; /**< Length of original audio buffer */ |
miruga27 | 0:dda4f4550403 | 205 | int len_cvt; /**< Length of converted audio buffer */ |
miruga27 | 0:dda4f4550403 | 206 | int len_mult; /**< buffer must be len*len_mult big */ |
miruga27 | 0:dda4f4550403 | 207 | double len_ratio; /**< Given len, final size is len*len_ratio */ |
miruga27 | 0:dda4f4550403 | 208 | SDL_AudioFilter filters[10]; /**< Filter list */ |
miruga27 | 0:dda4f4550403 | 209 | int filter_index; /**< Current audio conversion function */ |
miruga27 | 0:dda4f4550403 | 210 | } SDL_AUDIOCVT_PACKED SDL_AudioCVT; |
miruga27 | 0:dda4f4550403 | 211 | |
miruga27 | 0:dda4f4550403 | 212 | |
miruga27 | 0:dda4f4550403 | 213 | /* Function prototypes */ |
miruga27 | 0:dda4f4550403 | 214 | |
miruga27 | 0:dda4f4550403 | 215 | /** |
miruga27 | 0:dda4f4550403 | 216 | * \name Driver discovery functions |
miruga27 | 0:dda4f4550403 | 217 | * |
miruga27 | 0:dda4f4550403 | 218 | * These functions return the list of built in audio drivers, in the |
miruga27 | 0:dda4f4550403 | 219 | * order that they are normally initialized by default. |
miruga27 | 0:dda4f4550403 | 220 | */ |
miruga27 | 0:dda4f4550403 | 221 | /* @{ */ |
miruga27 | 0:dda4f4550403 | 222 | extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); |
miruga27 | 0:dda4f4550403 | 223 | extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index); |
miruga27 | 0:dda4f4550403 | 224 | /* @} */ |
miruga27 | 0:dda4f4550403 | 225 | |
miruga27 | 0:dda4f4550403 | 226 | /** |
miruga27 | 0:dda4f4550403 | 227 | * \name Initialization and cleanup |
miruga27 | 0:dda4f4550403 | 228 | * |
miruga27 | 0:dda4f4550403 | 229 | * \internal These functions are used internally, and should not be used unless |
miruga27 | 0:dda4f4550403 | 230 | * you have a specific need to specify the audio driver you want to |
miruga27 | 0:dda4f4550403 | 231 | * use. You should normally use SDL_Init() or SDL_InitSubSystem(). |
miruga27 | 0:dda4f4550403 | 232 | */ |
miruga27 | 0:dda4f4550403 | 233 | /* @{ */ |
miruga27 | 0:dda4f4550403 | 234 | extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name); |
miruga27 | 0:dda4f4550403 | 235 | extern DECLSPEC void SDLCALL SDL_AudioQuit(void); |
miruga27 | 0:dda4f4550403 | 236 | /* @} */ |
miruga27 | 0:dda4f4550403 | 237 | |
miruga27 | 0:dda4f4550403 | 238 | /** |
miruga27 | 0:dda4f4550403 | 239 | * This function returns the name of the current audio driver, or NULL |
miruga27 | 0:dda4f4550403 | 240 | * if no driver has been initialized. |
miruga27 | 0:dda4f4550403 | 241 | */ |
miruga27 | 0:dda4f4550403 | 242 | extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void); |
miruga27 | 0:dda4f4550403 | 243 | |
miruga27 | 0:dda4f4550403 | 244 | /** |
miruga27 | 0:dda4f4550403 | 245 | * This function opens the audio device with the desired parameters, and |
miruga27 | 0:dda4f4550403 | 246 | * returns 0 if successful, placing the actual hardware parameters in the |
miruga27 | 0:dda4f4550403 | 247 | * structure pointed to by \c obtained. If \c obtained is NULL, the audio |
miruga27 | 0:dda4f4550403 | 248 | * data passed to the callback function will be guaranteed to be in the |
miruga27 | 0:dda4f4550403 | 249 | * requested format, and will be automatically converted to the hardware |
miruga27 | 0:dda4f4550403 | 250 | * audio format if necessary. This function returns -1 if it failed |
miruga27 | 0:dda4f4550403 | 251 | * to open the audio device, or couldn't set up the audio thread. |
miruga27 | 0:dda4f4550403 | 252 | * |
miruga27 | 0:dda4f4550403 | 253 | * When filling in the desired audio spec structure, |
miruga27 | 0:dda4f4550403 | 254 | * - \c desired->freq should be the desired audio frequency in samples-per- |
miruga27 | 0:dda4f4550403 | 255 | * second. |
miruga27 | 0:dda4f4550403 | 256 | * - \c desired->format should be the desired audio format. |
miruga27 | 0:dda4f4550403 | 257 | * - \c desired->samples is the desired size of the audio buffer, in |
miruga27 | 0:dda4f4550403 | 258 | * samples. This number should be a power of two, and may be adjusted by |
miruga27 | 0:dda4f4550403 | 259 | * the audio driver to a value more suitable for the hardware. Good values |
miruga27 | 0:dda4f4550403 | 260 | * seem to range between 512 and 8096 inclusive, depending on the |
miruga27 | 0:dda4f4550403 | 261 | * application and CPU speed. Smaller values yield faster response time, |
miruga27 | 0:dda4f4550403 | 262 | * but can lead to underflow if the application is doing heavy processing |
miruga27 | 0:dda4f4550403 | 263 | * and cannot fill the audio buffer in time. A stereo sample consists of |
miruga27 | 0:dda4f4550403 | 264 | * both right and left channels in LR ordering. |
miruga27 | 0:dda4f4550403 | 265 | * Note that the number of samples is directly related to time by the |
miruga27 | 0:dda4f4550403 | 266 | * following formula: \code ms = (samples*1000)/freq \endcode |
miruga27 | 0:dda4f4550403 | 267 | * - \c desired->size is the size in bytes of the audio buffer, and is |
miruga27 | 0:dda4f4550403 | 268 | * calculated by SDL_OpenAudio(). |
miruga27 | 0:dda4f4550403 | 269 | * - \c desired->silence is the value used to set the buffer to silence, |
miruga27 | 0:dda4f4550403 | 270 | * and is calculated by SDL_OpenAudio(). |
miruga27 | 0:dda4f4550403 | 271 | * - \c desired->callback should be set to a function that will be called |
miruga27 | 0:dda4f4550403 | 272 | * when the audio device is ready for more data. It is passed a pointer |
miruga27 | 0:dda4f4550403 | 273 | * to the audio buffer, and the length in bytes of the audio buffer. |
miruga27 | 0:dda4f4550403 | 274 | * This function usually runs in a separate thread, and so you should |
miruga27 | 0:dda4f4550403 | 275 | * protect data structures that it accesses by calling SDL_LockAudio() |
miruga27 | 0:dda4f4550403 | 276 | * and SDL_UnlockAudio() in your code. |
miruga27 | 0:dda4f4550403 | 277 | * - \c desired->userdata is passed as the first parameter to your callback |
miruga27 | 0:dda4f4550403 | 278 | * function. |
miruga27 | 0:dda4f4550403 | 279 | * |
miruga27 | 0:dda4f4550403 | 280 | * The audio device starts out playing silence when it's opened, and should |
miruga27 | 0:dda4f4550403 | 281 | * be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready |
miruga27 | 0:dda4f4550403 | 282 | * for your audio callback function to be called. Since the audio driver |
miruga27 | 0:dda4f4550403 | 283 | * may modify the requested size of the audio buffer, you should allocate |
miruga27 | 0:dda4f4550403 | 284 | * any local mixing buffers after you open the audio device. |
miruga27 | 0:dda4f4550403 | 285 | */ |
miruga27 | 0:dda4f4550403 | 286 | extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired, |
miruga27 | 0:dda4f4550403 | 287 | SDL_AudioSpec * obtained); |
miruga27 | 0:dda4f4550403 | 288 | |
miruga27 | 0:dda4f4550403 | 289 | /** |
miruga27 | 0:dda4f4550403 | 290 | * SDL Audio Device IDs. |
miruga27 | 0:dda4f4550403 | 291 | * |
miruga27 | 0:dda4f4550403 | 292 | * A successful call to SDL_OpenAudio() is always device id 1, and legacy |
miruga27 | 0:dda4f4550403 | 293 | * SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls |
miruga27 | 0:dda4f4550403 | 294 | * always returns devices >= 2 on success. The legacy calls are good both |
miruga27 | 0:dda4f4550403 | 295 | * for backwards compatibility and when you don't care about multiple, |
miruga27 | 0:dda4f4550403 | 296 | * specific, or capture devices. |
miruga27 | 0:dda4f4550403 | 297 | */ |
miruga27 | 0:dda4f4550403 | 298 | typedef Uint32 SDL_AudioDeviceID; |
miruga27 | 0:dda4f4550403 | 299 | |
miruga27 | 0:dda4f4550403 | 300 | /** |
miruga27 | 0:dda4f4550403 | 301 | * Get the number of available devices exposed by the current driver. |
miruga27 | 0:dda4f4550403 | 302 | * Only valid after a successfully initializing the audio subsystem. |
miruga27 | 0:dda4f4550403 | 303 | * Returns -1 if an explicit list of devices can't be determined; this is |
miruga27 | 0:dda4f4550403 | 304 | * not an error. For example, if SDL is set up to talk to a remote audio |
miruga27 | 0:dda4f4550403 | 305 | * server, it can't list every one available on the Internet, but it will |
miruga27 | 0:dda4f4550403 | 306 | * still allow a specific host to be specified to SDL_OpenAudioDevice(). |
miruga27 | 0:dda4f4550403 | 307 | * |
miruga27 | 0:dda4f4550403 | 308 | * In many common cases, when this function returns a value <= 0, it can still |
miruga27 | 0:dda4f4550403 | 309 | * successfully open the default device (NULL for first argument of |
miruga27 | 0:dda4f4550403 | 310 | * SDL_OpenAudioDevice()). |
miruga27 | 0:dda4f4550403 | 311 | */ |
miruga27 | 0:dda4f4550403 | 312 | extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture); |
miruga27 | 0:dda4f4550403 | 313 | |
miruga27 | 0:dda4f4550403 | 314 | /** |
miruga27 | 0:dda4f4550403 | 315 | * Get the human-readable name of a specific audio device. |
miruga27 | 0:dda4f4550403 | 316 | * Must be a value between 0 and (number of audio devices-1). |
miruga27 | 0:dda4f4550403 | 317 | * Only valid after a successfully initializing the audio subsystem. |
miruga27 | 0:dda4f4550403 | 318 | * The values returned by this function reflect the latest call to |
miruga27 | 0:dda4f4550403 | 319 | * SDL_GetNumAudioDevices(); recall that function to redetect available |
miruga27 | 0:dda4f4550403 | 320 | * hardware. |
miruga27 | 0:dda4f4550403 | 321 | * |
miruga27 | 0:dda4f4550403 | 322 | * The string returned by this function is UTF-8 encoded, read-only, and |
miruga27 | 0:dda4f4550403 | 323 | * managed internally. You are not to free it. If you need to keep the |
miruga27 | 0:dda4f4550403 | 324 | * string for any length of time, you should make your own copy of it, as it |
miruga27 | 0:dda4f4550403 | 325 | * will be invalid next time any of several other SDL functions is called. |
miruga27 | 0:dda4f4550403 | 326 | */ |
miruga27 | 0:dda4f4550403 | 327 | extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index, |
miruga27 | 0:dda4f4550403 | 328 | int iscapture); |
miruga27 | 0:dda4f4550403 | 329 | |
miruga27 | 0:dda4f4550403 | 330 | |
miruga27 | 0:dda4f4550403 | 331 | /** |
miruga27 | 0:dda4f4550403 | 332 | * Open a specific audio device. Passing in a device name of NULL requests |
miruga27 | 0:dda4f4550403 | 333 | * the most reasonable default (and is equivalent to calling SDL_OpenAudio()). |
miruga27 | 0:dda4f4550403 | 334 | * |
miruga27 | 0:dda4f4550403 | 335 | * The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but |
miruga27 | 0:dda4f4550403 | 336 | * some drivers allow arbitrary and driver-specific strings, such as a |
miruga27 | 0:dda4f4550403 | 337 | * hostname/IP address for a remote audio server, or a filename in the |
miruga27 | 0:dda4f4550403 | 338 | * diskaudio driver. |
miruga27 | 0:dda4f4550403 | 339 | * |
miruga27 | 0:dda4f4550403 | 340 | * \return 0 on error, a valid device ID that is >= 2 on success. |
miruga27 | 0:dda4f4550403 | 341 | * |
miruga27 | 0:dda4f4550403 | 342 | * SDL_OpenAudio(), unlike this function, always acts on device ID 1. |
miruga27 | 0:dda4f4550403 | 343 | */ |
miruga27 | 0:dda4f4550403 | 344 | extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char |
miruga27 | 0:dda4f4550403 | 345 | *device, |
miruga27 | 0:dda4f4550403 | 346 | int iscapture, |
miruga27 | 0:dda4f4550403 | 347 | const |
miruga27 | 0:dda4f4550403 | 348 | SDL_AudioSpec * |
miruga27 | 0:dda4f4550403 | 349 | desired, |
miruga27 | 0:dda4f4550403 | 350 | SDL_AudioSpec * |
miruga27 | 0:dda4f4550403 | 351 | obtained, |
miruga27 | 0:dda4f4550403 | 352 | int |
miruga27 | 0:dda4f4550403 | 353 | allowed_changes); |
miruga27 | 0:dda4f4550403 | 354 | |
miruga27 | 0:dda4f4550403 | 355 | |
miruga27 | 0:dda4f4550403 | 356 | |
miruga27 | 0:dda4f4550403 | 357 | /** |
miruga27 | 0:dda4f4550403 | 358 | * \name Audio state |
miruga27 | 0:dda4f4550403 | 359 | * |
miruga27 | 0:dda4f4550403 | 360 | * Get the current audio state. |
miruga27 | 0:dda4f4550403 | 361 | */ |
miruga27 | 0:dda4f4550403 | 362 | /* @{ */ |
miruga27 | 0:dda4f4550403 | 363 | typedef enum |
miruga27 | 0:dda4f4550403 | 364 | { |
miruga27 | 0:dda4f4550403 | 365 | SDL_AUDIO_STOPPED = 0, |
miruga27 | 0:dda4f4550403 | 366 | SDL_AUDIO_PLAYING, |
miruga27 | 0:dda4f4550403 | 367 | SDL_AUDIO_PAUSED |
miruga27 | 0:dda4f4550403 | 368 | } SDL_AudioStatus; |
miruga27 | 0:dda4f4550403 | 369 | extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void); |
miruga27 | 0:dda4f4550403 | 370 | |
miruga27 | 0:dda4f4550403 | 371 | extern DECLSPEC SDL_AudioStatus SDLCALL |
miruga27 | 0:dda4f4550403 | 372 | SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev); |
miruga27 | 0:dda4f4550403 | 373 | /* @} *//* Audio State */ |
miruga27 | 0:dda4f4550403 | 374 | |
miruga27 | 0:dda4f4550403 | 375 | /** |
miruga27 | 0:dda4f4550403 | 376 | * \name Pause audio functions |
miruga27 | 0:dda4f4550403 | 377 | * |
miruga27 | 0:dda4f4550403 | 378 | * These functions pause and unpause the audio callback processing. |
miruga27 | 0:dda4f4550403 | 379 | * They should be called with a parameter of 0 after opening the audio |
miruga27 | 0:dda4f4550403 | 380 | * device to start playing sound. This is so you can safely initialize |
miruga27 | 0:dda4f4550403 | 381 | * data for your callback function after opening the audio device. |
miruga27 | 0:dda4f4550403 | 382 | * Silence will be written to the audio device during the pause. |
miruga27 | 0:dda4f4550403 | 383 | */ |
miruga27 | 0:dda4f4550403 | 384 | /* @{ */ |
miruga27 | 0:dda4f4550403 | 385 | extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on); |
miruga27 | 0:dda4f4550403 | 386 | extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev, |
miruga27 | 0:dda4f4550403 | 387 | int pause_on); |
miruga27 | 0:dda4f4550403 | 388 | /* @} *//* Pause audio functions */ |
miruga27 | 0:dda4f4550403 | 389 | |
miruga27 | 0:dda4f4550403 | 390 | /** |
miruga27 | 0:dda4f4550403 | 391 | * This function loads a WAVE from the data source, automatically freeing |
miruga27 | 0:dda4f4550403 | 392 | * that source if \c freesrc is non-zero. For example, to load a WAVE file, |
miruga27 | 0:dda4f4550403 | 393 | * you could do: |
miruga27 | 0:dda4f4550403 | 394 | * \code |
miruga27 | 0:dda4f4550403 | 395 | * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); |
miruga27 | 0:dda4f4550403 | 396 | * \endcode |
miruga27 | 0:dda4f4550403 | 397 | * |
miruga27 | 0:dda4f4550403 | 398 | * If this function succeeds, it returns the given SDL_AudioSpec, |
miruga27 | 0:dda4f4550403 | 399 | * filled with the audio data format of the wave data, and sets |
miruga27 | 0:dda4f4550403 | 400 | * \c *audio_buf to a malloc()'d buffer containing the audio data, |
miruga27 | 0:dda4f4550403 | 401 | * and sets \c *audio_len to the length of that audio buffer, in bytes. |
miruga27 | 0:dda4f4550403 | 402 | * You need to free the audio buffer with SDL_FreeWAV() when you are |
miruga27 | 0:dda4f4550403 | 403 | * done with it. |
miruga27 | 0:dda4f4550403 | 404 | * |
miruga27 | 0:dda4f4550403 | 405 | * This function returns NULL and sets the SDL error message if the |
miruga27 | 0:dda4f4550403 | 406 | * wave file cannot be opened, uses an unknown data format, or is |
miruga27 | 0:dda4f4550403 | 407 | * corrupt. Currently raw and MS-ADPCM WAVE files are supported. |
miruga27 | 0:dda4f4550403 | 408 | */ |
miruga27 | 0:dda4f4550403 | 409 | extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, |
miruga27 | 0:dda4f4550403 | 410 | int freesrc, |
miruga27 | 0:dda4f4550403 | 411 | SDL_AudioSpec * spec, |
miruga27 | 0:dda4f4550403 | 412 | Uint8 ** audio_buf, |
miruga27 | 0:dda4f4550403 | 413 | Uint32 * audio_len); |
miruga27 | 0:dda4f4550403 | 414 | |
miruga27 | 0:dda4f4550403 | 415 | /** |
miruga27 | 0:dda4f4550403 | 416 | * Loads a WAV from a file. |
miruga27 | 0:dda4f4550403 | 417 | * Compatibility convenience function. |
miruga27 | 0:dda4f4550403 | 418 | */ |
miruga27 | 0:dda4f4550403 | 419 | #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \ |
miruga27 | 0:dda4f4550403 | 420 | SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len) |
miruga27 | 0:dda4f4550403 | 421 | |
miruga27 | 0:dda4f4550403 | 422 | /** |
miruga27 | 0:dda4f4550403 | 423 | * This function frees data previously allocated with SDL_LoadWAV_RW() |
miruga27 | 0:dda4f4550403 | 424 | */ |
miruga27 | 0:dda4f4550403 | 425 | extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf); |
miruga27 | 0:dda4f4550403 | 426 | |
miruga27 | 0:dda4f4550403 | 427 | /** |
miruga27 | 0:dda4f4550403 | 428 | * This function takes a source format and rate and a destination format |
miruga27 | 0:dda4f4550403 | 429 | * and rate, and initializes the \c cvt structure with information needed |
miruga27 | 0:dda4f4550403 | 430 | * by SDL_ConvertAudio() to convert a buffer of audio data from one format |
miruga27 | 0:dda4f4550403 | 431 | * to the other. |
miruga27 | 0:dda4f4550403 | 432 | * |
miruga27 | 0:dda4f4550403 | 433 | * \return -1 if the format conversion is not supported, 0 if there's |
miruga27 | 0:dda4f4550403 | 434 | * no conversion needed, or 1 if the audio filter is set up. |
miruga27 | 0:dda4f4550403 | 435 | */ |
miruga27 | 0:dda4f4550403 | 436 | extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt, |
miruga27 | 0:dda4f4550403 | 437 | SDL_AudioFormat src_format, |
miruga27 | 0:dda4f4550403 | 438 | Uint8 src_channels, |
miruga27 | 0:dda4f4550403 | 439 | int src_rate, |
miruga27 | 0:dda4f4550403 | 440 | SDL_AudioFormat dst_format, |
miruga27 | 0:dda4f4550403 | 441 | Uint8 dst_channels, |
miruga27 | 0:dda4f4550403 | 442 | int dst_rate); |
miruga27 | 0:dda4f4550403 | 443 | |
miruga27 | 0:dda4f4550403 | 444 | /** |
miruga27 | 0:dda4f4550403 | 445 | * Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(), |
miruga27 | 0:dda4f4550403 | 446 | * created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of |
miruga27 | 0:dda4f4550403 | 447 | * audio data in the source format, this function will convert it in-place |
miruga27 | 0:dda4f4550403 | 448 | * to the desired format. |
miruga27 | 0:dda4f4550403 | 449 | * |
miruga27 | 0:dda4f4550403 | 450 | * The data conversion may expand the size of the audio data, so the buffer |
miruga27 | 0:dda4f4550403 | 451 | * \c cvt->buf should be allocated after the \c cvt structure is initialized by |
miruga27 | 0:dda4f4550403 | 452 | * SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long. |
miruga27 | 0:dda4f4550403 | 453 | */ |
miruga27 | 0:dda4f4550403 | 454 | extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt); |
miruga27 | 0:dda4f4550403 | 455 | |
miruga27 | 0:dda4f4550403 | 456 | #define SDL_MIX_MAXVOLUME 128 |
miruga27 | 0:dda4f4550403 | 457 | /** |
miruga27 | 0:dda4f4550403 | 458 | * This takes two audio buffers of the playing audio format and mixes |
miruga27 | 0:dda4f4550403 | 459 | * them, performing addition, volume adjustment, and overflow clipping. |
miruga27 | 0:dda4f4550403 | 460 | * The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME |
miruga27 | 0:dda4f4550403 | 461 | * for full audio volume. Note this does not change hardware volume. |
miruga27 | 0:dda4f4550403 | 462 | * This is provided for convenience -- you can mix your own audio data. |
miruga27 | 0:dda4f4550403 | 463 | */ |
miruga27 | 0:dda4f4550403 | 464 | extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src, |
miruga27 | 0:dda4f4550403 | 465 | Uint32 len, int volume); |
miruga27 | 0:dda4f4550403 | 466 | |
miruga27 | 0:dda4f4550403 | 467 | /** |
miruga27 | 0:dda4f4550403 | 468 | * This works like SDL_MixAudio(), but you specify the audio format instead of |
miruga27 | 0:dda4f4550403 | 469 | * using the format of audio device 1. Thus it can be used when no audio |
miruga27 | 0:dda4f4550403 | 470 | * device is open at all. |
miruga27 | 0:dda4f4550403 | 471 | */ |
miruga27 | 0:dda4f4550403 | 472 | extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, |
miruga27 | 0:dda4f4550403 | 473 | const Uint8 * src, |
miruga27 | 0:dda4f4550403 | 474 | SDL_AudioFormat format, |
miruga27 | 0:dda4f4550403 | 475 | Uint32 len, int volume); |
miruga27 | 0:dda4f4550403 | 476 | |
miruga27 | 0:dda4f4550403 | 477 | /** |
miruga27 | 0:dda4f4550403 | 478 | * \name Audio lock functions |
miruga27 | 0:dda4f4550403 | 479 | * |
miruga27 | 0:dda4f4550403 | 480 | * The lock manipulated by these functions protects the callback function. |
miruga27 | 0:dda4f4550403 | 481 | * During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that |
miruga27 | 0:dda4f4550403 | 482 | * the callback function is not running. Do not call these from the callback |
miruga27 | 0:dda4f4550403 | 483 | * function or you will cause deadlock. |
miruga27 | 0:dda4f4550403 | 484 | */ |
miruga27 | 0:dda4f4550403 | 485 | /* @{ */ |
miruga27 | 0:dda4f4550403 | 486 | extern DECLSPEC void SDLCALL SDL_LockAudio(void); |
miruga27 | 0:dda4f4550403 | 487 | extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev); |
miruga27 | 0:dda4f4550403 | 488 | extern DECLSPEC void SDLCALL SDL_UnlockAudio(void); |
miruga27 | 0:dda4f4550403 | 489 | extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev); |
miruga27 | 0:dda4f4550403 | 490 | /* @} *//* Audio lock functions */ |
miruga27 | 0:dda4f4550403 | 491 | |
miruga27 | 0:dda4f4550403 | 492 | /** |
miruga27 | 0:dda4f4550403 | 493 | * This function shuts down audio processing and closes the audio device. |
miruga27 | 0:dda4f4550403 | 494 | */ |
miruga27 | 0:dda4f4550403 | 495 | extern DECLSPEC void SDLCALL SDL_CloseAudio(void); |
miruga27 | 0:dda4f4550403 | 496 | extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev); |
miruga27 | 0:dda4f4550403 | 497 | |
miruga27 | 0:dda4f4550403 | 498 | /* Ends C function definitions when using C++ */ |
miruga27 | 0:dda4f4550403 | 499 | #ifdef __cplusplus |
miruga27 | 0:dda4f4550403 | 500 | } |
miruga27 | 0:dda4f4550403 | 501 | #endif |
miruga27 | 0:dda4f4550403 | 502 | #include "close_code.h" |
miruga27 | 0:dda4f4550403 | 503 | |
miruga27 | 0:dda4f4550403 | 504 | #endif /* _SDL_audio_h */ |
miruga27 | 0:dda4f4550403 | 505 | |
miruga27 | 0:dda4f4550403 | 506 | /* vi: set ts=4 sw=4 expandtab: */ |