My Project
SDL_audio.h
Go to the documentation of this file.
1 /*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2018 Sam Lantinga <slouken@libsdl.org>
4 
5  This software is provided 'as-is', without any express or implied
6  warranty. In no event will the authors be held liable for any damages
7  arising from the use of this software.
8 
9  Permission is granted to anyone to use this software for any purpose,
10  including commercial applications, and to alter it and redistribute it
11  freely, subject to the following restrictions:
12 
13  1. The origin of this software must not be misrepresented; you must not
14  claim that you wrote the original software. If you use this software
15  in a product, an acknowledgment in the product documentation would be
16  appreciated but is not required.
17  2. Altered source versions must be plainly marked as such, and must not be
18  misrepresented as being the original software.
19  3. This notice may not be removed or altered from any source distribution.
20 */
21 
28 #ifndef SDL_audio_h_
29 #define SDL_audio_h_
30 
31 #include "SDL_stdinc.h"
32 #include "SDL_error.h"
33 #include "SDL_endian.h"
34 #include "SDL_mutex.h"
35 #include "SDL_thread.h"
36 #include "SDL_rwops.h"
37 
38 #include "begin_code.h"
39 /* Set up for C function definitions, even when using C++ */
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
64 typedef Uint16 SDL_AudioFormat;
65 
69 /* @{ */
70 
71 #define SDL_AUDIO_MASK_BITSIZE (0xFF)
72 #define SDL_AUDIO_MASK_DATATYPE (1<<8)
73 #define SDL_AUDIO_MASK_ENDIAN (1<<12)
74 #define SDL_AUDIO_MASK_SIGNED (1<<15)
75 #define SDL_AUDIO_BITSIZE(x) (x & SDL_AUDIO_MASK_BITSIZE)
76 #define SDL_AUDIO_ISFLOAT(x) (x & SDL_AUDIO_MASK_DATATYPE)
77 #define SDL_AUDIO_ISBIGENDIAN(x) (x & SDL_AUDIO_MASK_ENDIAN)
78 #define SDL_AUDIO_ISSIGNED(x) (x & SDL_AUDIO_MASK_SIGNED)
79 #define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x))
80 #define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x))
81 #define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x))
82 
88 /* @{ */
89 #define AUDIO_U8 0x0008
90 #define AUDIO_S8 0x8008
91 #define AUDIO_U16LSB 0x0010
92 #define AUDIO_S16LSB 0x8010
93 #define AUDIO_U16MSB 0x1010
94 #define AUDIO_S16MSB 0x9010
95 #define AUDIO_U16 AUDIO_U16LSB
96 #define AUDIO_S16 AUDIO_S16LSB
97 /* @} */
98 
102 /* @{ */
103 #define AUDIO_S32LSB 0x8020
104 #define AUDIO_S32MSB 0x9020
105 #define AUDIO_S32 AUDIO_S32LSB
106 /* @} */
107 
111 /* @{ */
112 #define AUDIO_F32LSB 0x8120
113 #define AUDIO_F32MSB 0x9120
114 #define AUDIO_F32 AUDIO_F32LSB
115 /* @} */
116 
120 /* @{ */
121 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
122 #define AUDIO_U16SYS AUDIO_U16LSB
123 #define AUDIO_S16SYS AUDIO_S16LSB
124 #define AUDIO_S32SYS AUDIO_S32LSB
125 #define AUDIO_F32SYS AUDIO_F32LSB
126 #else
127 #define AUDIO_U16SYS AUDIO_U16MSB
128 #define AUDIO_S16SYS AUDIO_S16MSB
129 #define AUDIO_S32SYS AUDIO_S32MSB
130 #define AUDIO_F32SYS AUDIO_F32MSB
131 #endif
132 /* @} */
133 
139 /* @{ */
140 #define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE 0x00000001
141 #define SDL_AUDIO_ALLOW_FORMAT_CHANGE 0x00000002
142 #define SDL_AUDIO_ALLOW_CHANNELS_CHANGE 0x00000004
143 #define SDL_AUDIO_ALLOW_ANY_CHANGE (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE)
144 /* @} */
145 
146 /* @} *//* Audio flags */
147 
162 typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
163  int len);
164 
177 typedef struct SDL_AudioSpec
178 {
179  int freq;
180  SDL_AudioFormat format;
181  Uint8 channels;
182  Uint8 silence;
183  Uint16 samples;
184  Uint16 padding;
185  Uint32 size;
187  void *userdata;
188 } SDL_AudioSpec;
189 
190 
191 struct SDL_AudioCVT;
192 typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
193  SDL_AudioFormat format);
194 
202 #define SDL_AUDIOCVT_MAX_FILTERS 9
203 
214 #ifdef __GNUC__
215 /* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't
216  pad it out to 88 bytes to guarantee ABI compatibility between compilers.
217  vvv
218  The next time we rev the ABI, make sure to size the ints and add padding.
219 */
220 #define SDL_AUDIOCVT_PACKED __attribute__((packed))
221 #else
222 #define SDL_AUDIOCVT_PACKED
223 #endif
224 /* */
225 typedef struct SDL_AudioCVT
226 {
227  int needed;
228  SDL_AudioFormat src_format;
229  SDL_AudioFormat dst_format;
230  double rate_incr;
231  Uint8 *buf;
232  int len;
233  int len_cvt;
234  int len_mult;
235  double len_ratio;
236  SDL_AudioFilter filters[SDL_AUDIOCVT_MAX_FILTERS + 1];
238 } SDL_AUDIOCVT_PACKED SDL_AudioCVT;
239 
240 
241 /* Function prototypes */
242 
249 /* @{ */
250 extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
251 extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
252 /* @} */
253 
261 /* @{ */
262 extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
263 extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
264 /* @} */
265 
270 extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
271 
317 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
318  SDL_AudioSpec * obtained);
319 
329 typedef Uint32 SDL_AudioDeviceID;
330 
343 extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
344 
358 extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
359  int iscapture);
360 
361 
375 extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
376  *device,
377  int iscapture,
378  const
379  SDL_AudioSpec *
380  desired,
381  SDL_AudioSpec *
382  obtained,
383  int
384  allowed_changes);
385 
386 
387 
393 /* @{ */
394 typedef enum
395 {
396  SDL_AUDIO_STOPPED = 0,
397  SDL_AUDIO_PLAYING,
398  SDL_AUDIO_PAUSED
399 } SDL_AudioStatus;
400 extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
401 
402 extern DECLSPEC SDL_AudioStatus SDLCALL
403 SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
404 /* @} *//* Audio State */
405 
415 /* @{ */
416 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
417 extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
418  int pause_on);
419 /* @} *//* Pause audio functions */
420 
440 extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
441  int freesrc,
442  SDL_AudioSpec * spec,
443  Uint8 ** audio_buf,
444  Uint32 * audio_len);
445 
450 #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
451  SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
452 
456 extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
457 
467 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
468  SDL_AudioFormat src_format,
469  Uint8 src_channels,
470  int src_rate,
471  SDL_AudioFormat dst_format,
472  Uint8 dst_channels,
473  int dst_rate);
474 
487 extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
488 
489 /* SDL_AudioStream is a new audio conversion interface.
490  The benefits vs SDL_AudioCVT:
491  - it can handle resampling data in chunks without generating
492  artifacts, when it doesn't have the complete buffer available.
493  - it can handle incoming data in any variable size.
494  - You push data as you have it, and pull it when you need it
495  */
496 /* this is opaque to the outside world. */
497 struct _SDL_AudioStream;
498 typedef struct _SDL_AudioStream SDL_AudioStream;
499 
518 extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format,
519  const Uint8 src_channels,
520  const int src_rate,
521  const SDL_AudioFormat dst_format,
522  const Uint8 dst_channels,
523  const int dst_rate);
524 
540 extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len);
541 
557 extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len);
558 
572 extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
573 
589 extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
590 
601 extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
602 
613 extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
614 
615 #define SDL_MIX_MAXVOLUME 128
616 
623 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
624  Uint32 len, int volume);
625 
631 extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
632  const Uint8 * src,
633  SDL_AudioFormat format,
634  Uint32 len, int volume);
635 
675 extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
676 
721 extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
722 
757 extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
758 
793 extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
794 
795 
804 /* @{ */
805 extern DECLSPEC void SDLCALL SDL_LockAudio(void);
806 extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
807 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
808 extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
809 /* @} *//* Audio lock functions */
810 
814 extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
815 extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
816 
817 /* Ends C function definitions when using C++ */
818 #ifdef __cplusplus
819 }
820 #endif
821 #include "close_code.h"
822 
823 #endif /* SDL_audio_h_ */
824 
825 /* vi: set ts=4 sw=4 expandtab: */
int len_cvt
Definition: SDL_audio.h:233
DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
Definition: SDL_audio.h:177
DECLSPEC void SDLCALL SDL_CloseAudio(void)
DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream)
DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec *desired, SDL_AudioSpec *obtained)
DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 *audio_buf)
Uint16 padding
Definition: SDL_audio.h:184
int needed
Definition: SDL_audio.h:227
DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index, int iscapture)
DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len)
Uint8 channels
Definition: SDL_audio.h:181
void(SDLCALL * SDL_AudioCallback)(void *userdata, Uint8 *stream, int len)
Definition: SDL_audio.h:162
void * userdata
Definition: SDL_audio.h:187
double rate_incr
Definition: SDL_audio.h:230
DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, int volume)
DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream)
DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture)
Uint8 * buf
Definition: SDL_audio.h:231
DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream)
SDL_AudioFormat src_format
Definition: SDL_audio.h:228
struct SDL_AudioSpec SDL_AudioSpec
int len_mult
Definition: SDL_audio.h:234
DECLSPEC void SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, Uint32 len, int volume)
double len_ratio
Definition: SDL_audio.h:235
Uint32 size
Definition: SDL_audio.h:185
SDL_AudioFormat format
Definition: SDL_audio.h:180
A structure to hold a set of audio conversion filters and buffers.
Definition: SDL_audio.h:225
DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT *cvt)
DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream)
int len
Definition: SDL_audio.h:232
DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT *cvt, SDL_AudioFormat src_format, Uint8 src_channels, int src_rate, SDL_AudioFormat dst_format, Uint8 dst_channels, int dst_rate)
Uint32 SDL_AudioDeviceID
Definition: SDL_audio.h:329
DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void)
DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev)
DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev)
SDL_AudioFormat dst_format
Definition: SDL_audio.h:229
DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len)
Uint16 SDL_AudioFormat
Audio format flags.
Definition: SDL_audio.h:64
Uint8 silence
Definition: SDL_audio.h:182
int filter_index
Definition: SDL_audio.h:237
DECLSPEC SDL_AudioStream *SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format, const Uint8 src_channels, const int src_rate, const SDL_AudioFormat dst_format, const Uint8 dst_channels, const int dst_rate)
Uint16 samples
Definition: SDL_audio.h:183
DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len)
DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len)
int freq
Definition: SDL_audio.h:179
DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char *device, int iscapture, const SDL_AudioSpec *desired, SDL_AudioSpec *obtained, int allowed_changes)
#define SDL_AUDIOCVT_MAX_FILTERS
Upper limit of filters in SDL_AudioCVT.
Definition: SDL_audio.h:202
Definition: SDL_rwops.h:52
SDL_AudioCallback callback
Definition: SDL_audio.h:186