Mercurial > sdl-ios-xcode

comparison include/SDL_audio.h @ 1964:071b6598d48f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
1.3 API proposals for audio subsystem. Nothing in here is guaranteed to stay as-is! And none of it is implemented yet! Use at own risk!
author Ryan C. Gordon <icculus@icculus.org>
date Thu, 03 Aug 2006 19:34:05 +0000
parents c121d94672cb
children 01e29c3e9a29
comparison
equal deleted inserted replaced
1963:2590b68531ef 1964:071b6598d48f
42 /* *INDENT-OFF* */ 42 /* *INDENT-OFF* */
43 extern "C" { 43 extern "C" {
44 /* *INDENT-ON* */ 44 /* *INDENT-ON* */
45 #endif 45 #endif
46 46
47 typedef Uint16 SDL_AudioFormat;
48
47 /* The calculated values in this structure are calculated by SDL_OpenAudio() */ 49 /* The calculated values in this structure are calculated by SDL_OpenAudio() */
48 typedef struct SDL_AudioSpec 50 typedef struct SDL_AudioSpec
49 { 51 {
50 int freq; /* DSP frequency -- samples per second */ 52 int freq; /* DSP frequency -- samples per second */
51 Uint16 format; /* Audio data format */ 53 SDL_AudioFormat format; /* Audio data format */
52 Uint8 channels; /* Number of channels: 1 mono, 2 stereo */ 54 Uint8 channels; /* Number of channels: 1 mono, 2 stereo */
53 Uint8 silence; /* Audio buffer silence value (calculated) */ 55 Uint8 silence; /* Audio buffer silence value (calculated) */
54 Uint16 samples; /* Audio buffer size in samples (power of 2) */ 56 Uint16 samples; /* Audio buffer size in samples (power of 2) */
55 Uint16 padding; /* Necessary for some compile environments */ 57 Uint16 padding; /* Necessary for some compile environments */
56 Uint32 size; /* Audio buffer size in bytes (calculated) */ 58 Uint32 size; /* Audio buffer size in bytes (calculated) */
62 */ 64 */
63 void (SDLCALL * callback) (void *userdata, Uint8 * stream, int len); 65 void (SDLCALL * callback) (void *userdata, Uint8 * stream, int len);
64 void *userdata; 66 void *userdata;
65 } SDL_AudioSpec; 67 } SDL_AudioSpec;
66 68
69
70 /*
71 These are what the 16 bits in SDL_AudioFormat currently mean...
72 (Unspecified bits are always zero.)
73
74 ++-----------------------sample is signed if set
75 ||
76 || ++-----------sample is bigendian if set
77 || ||
78 || || ++---sample is float if set
79 || || ||
80 || || || +---sample bit size---+
81 || || || | |
82 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
83
84 There are macros in SDL 1.3 and later to query these bits.
85 */
86
87 #define SDL_AUDIO_MASK_BITSIZE (0xFF)
88 #define SDL_AUDIO_MASK_DATATYPE (1<<8)
89 #define SDL_AUDIO_MASK_ENDIAN (1<<12)
90 #define SDL_AUDIO_MASK_SIGNED (1<<15)
91 #define SDL_AUDIO_BITSIZE(x) (x & SDL_AUDIO_MASK_BITSIZE)
92 #define SDL_AUDIO_ISFLOAT(x) (x & SDL_AUDIO_MASK_DATATYPE)
93 #define SDL_AUDIO_ISBIGENDIAN(x) (x & SDL_AUDIO_MASK_ENDIAN)
94 #define SDL_AUDIO_ISSIGNED(x) (x & SDL_AUDIO_MASK_SIGNED)
95 #define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x))
96 #define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x))
97 #define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x))
98
67 /* Audio format flags (defaults to LSB byte order) */ 99 /* Audio format flags (defaults to LSB byte order) */
68 #define AUDIO_U8 0x0008 /* Unsigned 8-bit samples */ 100 #define AUDIO_U8 0x0008 /* Unsigned 8-bit samples */
69 #define AUDIO_S8 0x8008 /* Signed 8-bit samples */ 101 #define AUDIO_S8 0x8008 /* Signed 8-bit samples */
70 #define AUDIO_U16LSB 0x0010 /* Unsigned 16-bit samples */ 102 #define AUDIO_U16LSB 0x0010 /* Unsigned 16-bit samples */
71 #define AUDIO_S16LSB 0x8010 /* Signed 16-bit samples */ 103 #define AUDIO_S16LSB 0x8010 /* Signed 16-bit samples */
72 #define AUDIO_U16MSB 0x1010 /* As above, but big-endian byte order */ 104 #define AUDIO_U16MSB 0x1010 /* As above, but big-endian byte order */
73 #define AUDIO_S16MSB 0x9010 /* As above, but big-endian byte order */ 105 #define AUDIO_S16MSB 0x9010 /* As above, but big-endian byte order */
74 #define AUDIO_U16 AUDIO_U16LSB 106 #define AUDIO_U16 AUDIO_U16LSB
75 #define AUDIO_S16 AUDIO_S16LSB 107 #define AUDIO_S16 AUDIO_S16LSB
76 108
109 /* int32 support new to SDL 1.3 */
110 #define AUDIO_S32LSB 0x8020 /* 32-bit integer samples */
111 #define AUDIO_S32MSB 0x9020 /* As above, but big-endian byte order */
112 #define AUDIO_S32 AUDIO_S32LSB
113 #define AUDIO_U32LSB 0x0020 /* Unsigned 32-bit integer samples */
114 #define AUDIO_U32MSB 0x1020 /* As above, but big-endian byte order */
115 #define AUDIO_U32 AUDIO_U32LSB
116
117 /* float32 support new to SDL 1.3 */
118 #define AUDIO_F32LSB 0x8120 /* 32-bit floating point samples */
119 #define AUDIO_F32MSB 0x9120 /* As above, but big-endian byte order */
120 #define AUDIO_F32 AUDIO_F32LSB
121
77 /* Native audio byte ordering */ 122 /* Native audio byte ordering */
78 #if SDL_BYTEORDER == SDL_LIL_ENDIAN 123 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
79 #define AUDIO_U16SYS AUDIO_U16LSB 124 #define AUDIO_U16SYS AUDIO_U16LSB
80 #define AUDIO_S16SYS AUDIO_S16LSB 125 #define AUDIO_S16SYS AUDIO_S16LSB
126 #define AUDIO_S32SYS AUDIO_S32LSB
127 #define AUDIO_U32SYS AUDIO_U32LSB
128 #define AUDIO_F32SYS AUDIO_F32LSB
81 #else 129 #else
82 #define AUDIO_U16SYS AUDIO_U16MSB 130 #define AUDIO_U16SYS AUDIO_U16MSB
83 #define AUDIO_S16SYS AUDIO_S16MSB 131 #define AUDIO_S16SYS AUDIO_S16MSB
132 #define AUDIO_S32SYS AUDIO_S32MSB
133 #define AUDIO_U32SYS AUDIO_U32MSB
134 #define AUDIO_F32SYS AUDIO_F32MSB
84 #endif 135 #endif
85 136
86 137
87 /* A structure to hold a set of audio conversion filters and buffers */ 138 /* A structure to hold a set of audio conversion filters and buffers */
88 typedef struct SDL_AudioCVT 139 typedef struct SDL_AudioCVT
164 */ 215 */
165 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired, 216 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
166 SDL_AudioSpec * obtained); 217 SDL_AudioSpec * obtained);
167 218
168 /* 219 /*
220 * SDL Audio Device IDs.
221 * A successful call to SDL_OpenAudio() is always device id 1, and legacy
222 * SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
223 * always returns devices >= 2 on success. The legacy calls are good both
224 * for backwards compatibility and when you don't care about multiple,
225 * specific, or capture devices.
226 */
227 typedef Uint32 SDL_AudioDeviceID;
228
229 /*
230 * Get the number of available devices exposed by the current driver.
231 * Only valid after a successfully initializing the audio subsystem.
232 */
233 extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
234
235 /*
236 * Get the human-readable name of a specific audio device.
237 * Must be a value between 0 and (number of audio devices-1).
238 * Only valid after a successfully initializing the audio subsystem.
239 */
240 extern DECLSPEC const char *SDLCALL SDL_GetAudioDevice(int index, int iscapture);
241
242
243 /*
244 * Open a specific audio device. Passing in a device name of NULL is
245 * equivalent to SDL_OpenAudio(). Returns 0 on error, a valid device ID
246 * on success.
247 */
248 extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(
249 const char * device,
250 int iscapture,
251 const SDL_AudioSpec * desired,
252 SDL_AudioSpec * obtained);
253
254
255
256 /*
169 * Get the current audio state: 257 * Get the current audio state:
170 */ 258 */
171 typedef enum 259 typedef enum
172 { 260 {
173 SDL_AUDIO_STOPPED = 0, 261 SDL_AUDIO_STOPPED = 0,
174 SDL_AUDIO_PLAYING, 262 SDL_AUDIO_PLAYING,
175 SDL_AUDIO_PAUSED 263 SDL_AUDIO_PAUSED
176 } SDL_audiostatus; 264 } SDL_audiostatus;
177 extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void); 265 extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
178 266
267 extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioDeviceStatus(
268 SDL_AudioDeviceID dev);
269
179 /* 270 /*
180 * This function pauses and unpauses the audio callback processing. 271 * This function pauses and unpauses the audio callback processing.
181 * It should be called with a parameter of 0 after opening the audio 272 * It should be called with a parameter of 0 after opening the audio
182 * device to start playing sound. This is so you can safely initialize 273 * device to start playing sound. This is so you can safely initialize
183 * data for your callback function after opening the audio device. 274 * data for your callback function after opening the audio device.
184 * Silence will be written to the audio device during the pause. 275 * Silence will be written to the audio device during the pause.
185 */ 276 */
186 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on); 277 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
278 extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
279 int pause_on);
187 280
188 /* 281 /*
189 * This function loads a WAVE from the data source, automatically freeing 282 * This function loads a WAVE from the data source, automatically freeing
190 * that source if 'freesrc' is non-zero. For example, to load a WAVE file, 283 * that source if 'freesrc' is non-zero. For example, to load a WAVE file,
191 * you could do: 284 * you could do:
220 /* 313 /*
221 * This function takes a source format and rate and a destination format 314 * This function takes a source format and rate and a destination format
222 * and rate, and initializes the 'cvt' structure with information needed 315 * and rate, and initializes the 'cvt' structure with information needed
223 * by SDL_ConvertAudio() to convert a buffer of audio data from one format 316 * by SDL_ConvertAudio() to convert a buffer of audio data from one format
224 * to the other. 317 * to the other.
225 * This function returns 0, or -1 if there was an error. 318 * Returns -1 if the format conversion is not supported, 0 if there's
319 * no conversion needed, or 1 if the audio filter is set up.
226 */ 320 */
227 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt, 321 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
228 Uint16 src_format, 322 Uint16 src_format,
229 Uint8 src_channels, 323 Uint8 src_channels,
230 int src_rate, 324 int src_rate,
252 #define SDL_MIX_MAXVOLUME 128 346 #define SDL_MIX_MAXVOLUME 128
253 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src, 347 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
254 Uint32 len, int volume); 348 Uint32 len, int volume);
255 349
256 /* 350 /*
351 * This works like SDL_MixAudio, but you specify the audio format instead of
352 * using the format of audio device 1. Thus it can be used when no audio
353 * device is open at all.
354 */
355 extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, const Uint8 * src,
356 SDL_AudioFormat format,
357 Uint32 len, int volume);
358
359 /*
257 * The lock manipulated by these functions protects the callback function. 360 * The lock manipulated by these functions protects the callback function.
258 * During a LockAudio/UnlockAudio pair, you can be guaranteed that the 361 * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
259 * callback function is not running. Do not call these from the callback 362 * callback function is not running. Do not call these from the callback
260 * function or you will cause deadlock. 363 * function or you will cause deadlock.
261 */ 364 */
262 extern DECLSPEC void SDLCALL SDL_LockAudio(void); 365 extern DECLSPEC void SDLCALL SDL_LockAudio(void);
366 extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
263 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void); 367 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
368 extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
264 369
265 /* 370 /*
266 * This function shuts down audio processing and closes the audio device. 371 * This function shuts down audio processing and closes the audio device.
267 */ 372 */
268 extern DECLSPEC void SDLCALL SDL_CloseAudio(void); 373 extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
374 extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
375
376 /*
377 * Returns 1 if audio device is still functioning, zero if not, -1 on error.
378 */
379 extern DECLSPEC int SDLCALL SDL_AudioDeviceConnected(SDL_AudioDeviceID dev);
269 380
270 381
271 /* Ends C function definitions when using C++ */ 382 /* Ends C function definitions when using C++ */
272 #ifdef __cplusplus 383 #ifdef __cplusplus
273 /* *INDENT-OFF* */ 384 /* *INDENT-OFF* */