My Project
SDL_audio.h
Go to the documentation of this file.
1 /*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2020 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_SAMPLES_CHANGE 0x00000008
144 #define SDL_AUDIO_ALLOW_ANY_CHANGE (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE|SDL_AUDIO_ALLOW_SAMPLES_CHANGE)
145 /* @} */
146 
147 /* @} *//* Audio flags */
148 
163 typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
164  int len);
165 
178 typedef struct SDL_AudioSpec
179 {
180  int freq;
182  Uint8 channels;
183  Uint8 silence;
184  Uint16 samples;
185  Uint16 padding;
186  Uint32 size;
188  void *userdata;
190 
191 
192 struct SDL_AudioCVT;
193 typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
194  SDL_AudioFormat format);
195 
203 #define SDL_AUDIOCVT_MAX_FILTERS 9
204 
215 #ifdef __GNUC__
216 /* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't
217  pad it out to 88 bytes to guarantee ABI compatibility between compilers.
218  vvv
219  The next time we rev the ABI, make sure to size the ints and add padding.
220 */
221 #define SDL_AUDIOCVT_PACKED __attribute__((packed))
222 #else
223 #define SDL_AUDIOCVT_PACKED
224 #endif
225 /* */
226 typedef struct SDL_AudioCVT
227 {
228  int needed;
231  double rate_incr;
232  Uint8 *buf;
233  int len;
234  int len_cvt;
235  int len_mult;
236  double len_ratio;
237  SDL_AudioFilter filters[SDL_AUDIOCVT_MAX_FILTERS + 1];
239 } SDL_AUDIOCVT_PACKED SDL_AudioCVT;
240 
241 
242 /* Function prototypes */
243 
250 /* @{ */
251 extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
252 extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
253 /* @} */
254 
262 /* @{ */
263 extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
264 extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
265 /* @} */
266 
271 extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
272 
318 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
319  SDL_AudioSpec * obtained);
320 
330 typedef Uint32 SDL_AudioDeviceID;
331 
344 extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
345 
359 extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
360  int iscapture);
361 
362 
376 extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
377  *device,
378  int iscapture,
379  const
380  SDL_AudioSpec *
381  desired,
382  SDL_AudioSpec *
383  obtained,
384  int
385  allowed_changes);
386 
387 
388 
394 /* @{ */
395 typedef enum
396 {
397  SDL_AUDIO_STOPPED = 0,
398  SDL_AUDIO_PLAYING,
399  SDL_AUDIO_PAUSED
400 } SDL_AudioStatus;
401 extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
402 
403 extern DECLSPEC SDL_AudioStatus SDLCALL
404 SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
405 /* @} *//* Audio State */
406 
416 /* @{ */
417 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
418 extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
419  int pause_on);
420 /* @} *//* Pause audio functions */
421 
474 extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
475  int freesrc,
476  SDL_AudioSpec * spec,
477  Uint8 ** audio_buf,
478  Uint32 * audio_len);
479 
484 #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
485  SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
486 
490 extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
491 
501 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
502  SDL_AudioFormat src_format,
503  Uint8 src_channels,
504  int src_rate,
505  SDL_AudioFormat dst_format,
506  Uint8 dst_channels,
507  int dst_rate);
508 
521 extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
522 
523 /* SDL_AudioStream is a new audio conversion interface.
524  The benefits vs SDL_AudioCVT:
525  - it can handle resampling data in chunks without generating
526  artifacts, when it doesn't have the complete buffer available.
527  - it can handle incoming data in any variable size.
528  - You push data as you have it, and pull it when you need it
529  */
530 /* this is opaque to the outside world. */
531 struct _SDL_AudioStream;
532 typedef struct _SDL_AudioStream SDL_AudioStream;
533 
552 extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format,
553  const Uint8 src_channels,
554  const int src_rate,
555  const SDL_AudioFormat dst_format,
556  const Uint8 dst_channels,
557  const int dst_rate);
558 
574 extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len);
575 
591 extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len);
592 
606 extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
607 
623 extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
624 
635 extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
636 
647 extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
648 
649 #define SDL_MIX_MAXVOLUME 128
650 
657 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
658  Uint32 len, int volume);
659 
665 extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
666  const Uint8 * src,
667  SDL_AudioFormat format,
668  Uint32 len, int volume);
669 
709 extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
710 
755 extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
756 
791 extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
792 
827 extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
828 
829 
838 /* @{ */
839 extern DECLSPEC void SDLCALL SDL_LockAudio(void);
840 extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
841 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
842 extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
843 /* @} *//* Audio lock functions */
844 
848 extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
849 extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
850 
851 /* Ends C function definitions when using C++ */
852 #ifdef __cplusplus
853 }
854 #endif
855 #include "close_code.h"
856 
857 #endif /* SDL_audio_h_ */
858 
859 /* vi: set ts=4 sw=4 expandtab: */
SDL_AudioSpec::userdata
void * userdata
Definition: SDL_audio.h:188
SDL_AudioCVT::len_mult
int len_mult
Definition: SDL_audio.h:235
SDL_AudioCVT::filters
SDL_AudioFilter filters[SDL_AUDIOCVT_MAX_FILTERS+1]
Definition: SDL_audio.h:237
SDL_CloseAudio
DECLSPEC void SDLCALL SDL_CloseAudio(void)
SDL_AudioCVT::buf
Uint8 * buf
Definition: SDL_audio.h:232
SDL_AudioCVT::dst_format
SDL_AudioFormat dst_format
Definition: SDL_audio.h:230
SDL_AudioStreamFlush
DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream)
SDL_DequeueAudio
DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len)
SDL_GetNumAudioDevices
DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture)
SDL_GetAudioDeviceName
DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index, int iscapture)
SDL_AudioStreamClear
DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream)
SDL_AudioCVT::len_cvt
int len_cvt
Definition: SDL_audio.h:234
SDL_AudioStreamPut
DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len)
SDL_OpenAudio
DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec *desired, SDL_AudioSpec *obtained)
SDL_AudioCVT::src_format
SDL_AudioFormat src_format
Definition: SDL_audio.h:229
SDL_AudioSpec
Definition: SDL_audio.h:179
SDL_AudioCallback
void(SDLCALL * SDL_AudioCallback)(void *userdata, Uint8 *stream, int len)
Definition: SDL_audio.h:163
SDL_OpenAudioDevice
DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char *device, int iscapture, const SDL_AudioSpec *desired, SDL_AudioSpec *obtained, int allowed_changes)
SDL_AudioSpec::size
Uint32 size
Definition: SDL_audio.h:186
SDL_LoadWAV_RW
DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
Load the audio data of a WAVE file into memory.
SDL_stdinc.h
SDL_RWops
Definition: SDL_rwops.h:53
SDL_AudioSpec
struct SDL_AudioSpec SDL_AudioSpec
close_code.h
begin_code.h
SDL_AudioSpec::freq
int freq
Definition: SDL_audio.h:180
SDL_thread.h
SDL_AudioSpec::padding
Uint16 padding
Definition: SDL_audio.h:185
SDL_AudioCVT::needed
int needed
Definition: SDL_audio.h:228
SDL_MixAudio
DECLSPEC void SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, Uint32 len, int volume)
SDL_MixAudioFormat
DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, int volume)
SDL_endian.h
SDL_FreeAudioStream
DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream)
SDL_AudioCVT
A structure to hold a set of audio conversion filters and buffers.
Definition: SDL_audio.h:227
SDL_AudioDeviceID
Uint32 SDL_AudioDeviceID
Definition: SDL_audio.h:330
SDL_AudioSpec::channels
Uint8 channels
Definition: SDL_audio.h:182
SDL_GetCurrentAudioDriver
DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void)
SDL_ConvertAudio
DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT *cvt)
SDL_BuildAudioCVT
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)
SDL_rwops.h
SDL_AudioCVT::filter_index
int filter_index
Definition: SDL_audio.h:238
SDL_QueueAudio
DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len)
SDL_AudioStreamGet
DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len)
SDL_AudioSpec::format
SDL_AudioFormat format
Definition: SDL_audio.h:181
SDL_AudioCVT::rate_incr
double rate_incr
Definition: SDL_audio.h:231
SDL_GetQueuedAudioSize
DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev)
SDL_ClearQueuedAudio
DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev)
SDL_AudioStreamAvailable
DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream)
SDL_AudioCVT::len
int len
Definition: SDL_audio.h:233
SDL_AudioCVT::len_ratio
double len_ratio
Definition: SDL_audio.h:236
SDL_NewAudioStream
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)
SDL_mutex.h
SDL_AudioSpec::silence
Uint8 silence
Definition: SDL_audio.h:183
SDL_AudioSpec::samples
Uint16 samples
Definition: SDL_audio.h:184
SDL_error.h
SDL_FreeWAV
DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 *audio_buf)
SDL_AudioSpec::callback
SDL_AudioCallback callback
Definition: SDL_audio.h:187
SDL_AUDIOCVT_MAX_FILTERS
#define SDL_AUDIOCVT_MAX_FILTERS
Upper limit of filters in SDL_AudioCVT.
Definition: SDL_audio.h:203
SDL_AudioFormat
Uint16 SDL_AudioFormat
Audio format flags.
Definition: SDL_audio.h:64