My Project
Loading...
Searching...
No Matches
SDL_audio.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2023 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
22/* !!! FIXME: several functions in here need Doxygen comments. */
23
30#ifndef SDL_audio_h_
31#define SDL_audio_h_
32
33#include "SDL_stdinc.h"
34#include "SDL_error.h"
35#include "SDL_endian.h"
36#include "SDL_mutex.h"
37#include "SDL_thread.h"
38#include "SDL_rwops.h"
39
40#include "begin_code.h"
41/* Set up for C function definitions, even when using C++ */
42#ifdef __cplusplus
43extern "C" {
44#endif
45
66typedef Uint16 SDL_AudioFormat;
67
71/* @{ */
72
73#define SDL_AUDIO_MASK_BITSIZE (0xFF)
74#define SDL_AUDIO_MASK_DATATYPE (1<<8)
75#define SDL_AUDIO_MASK_ENDIAN (1<<12)
76#define SDL_AUDIO_MASK_SIGNED (1<<15)
77#define SDL_AUDIO_BITSIZE(x) (x & SDL_AUDIO_MASK_BITSIZE)
78#define SDL_AUDIO_ISFLOAT(x) (x & SDL_AUDIO_MASK_DATATYPE)
79#define SDL_AUDIO_ISBIGENDIAN(x) (x & SDL_AUDIO_MASK_ENDIAN)
80#define SDL_AUDIO_ISSIGNED(x) (x & SDL_AUDIO_MASK_SIGNED)
81#define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x))
82#define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x))
83#define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x))
84
90/* @{ */
91#define AUDIO_U8 0x0008
92#define AUDIO_S8 0x8008
93#define AUDIO_U16LSB 0x0010
94#define AUDIO_S16LSB 0x8010
95#define AUDIO_U16MSB 0x1010
96#define AUDIO_S16MSB 0x9010
97#define AUDIO_U16 AUDIO_U16LSB
98#define AUDIO_S16 AUDIO_S16LSB
99/* @} */
100
104/* @{ */
105#define AUDIO_S32LSB 0x8020
106#define AUDIO_S32MSB 0x9020
107#define AUDIO_S32 AUDIO_S32LSB
108/* @} */
109
113/* @{ */
114#define AUDIO_F32LSB 0x8120
115#define AUDIO_F32MSB 0x9120
116#define AUDIO_F32 AUDIO_F32LSB
117/* @} */
118
122/* @{ */
123#if SDL_BYTEORDER == SDL_LIL_ENDIAN
124#define AUDIO_U16SYS AUDIO_U16LSB
125#define AUDIO_S16SYS AUDIO_S16LSB
126#define AUDIO_S32SYS AUDIO_S32LSB
127#define AUDIO_F32SYS AUDIO_F32LSB
128#else
129#define AUDIO_U16SYS AUDIO_U16MSB
130#define AUDIO_S16SYS AUDIO_S16MSB
131#define AUDIO_S32SYS AUDIO_S32MSB
132#define AUDIO_F32SYS AUDIO_F32MSB
133#endif
134/* @} */
135
141/* @{ */
142#define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE 0x00000001
143#define SDL_AUDIO_ALLOW_FORMAT_CHANGE 0x00000002
144#define SDL_AUDIO_ALLOW_CHANNELS_CHANGE 0x00000004
145#define SDL_AUDIO_ALLOW_SAMPLES_CHANGE 0x00000008
146#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)
147/* @} */
148
149/* @} *//* Audio flags */
150
165typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
166 int len);
167
180typedef struct SDL_AudioSpec
181{
182 int freq;
184 Uint8 channels;
185 Uint8 silence;
186 Uint16 samples;
187 Uint16 padding;
188 Uint32 size;
190 void *userdata;
192
193
194struct SDL_AudioCVT;
195typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
196 SDL_AudioFormat format);
197
205#define SDL_AUDIOCVT_MAX_FILTERS 9
206
217#if defined(__GNUC__) && !defined(__CHERI_PURE_CAPABILITY__)
218/* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't
219 pad it out to 88 bytes to guarantee ABI compatibility between compilers.
220 This is not a concern on CHERI architectures, where pointers must be stored
221 at aligned locations otherwise they will become invalid, and thus structs
222 containing pointers cannot be packed without giving a warning or error.
223 vvv
224 The next time we rev the ABI, make sure to size the ints and add padding.
225*/
226#define SDL_AUDIOCVT_PACKED __attribute__((packed))
227#else
228#define SDL_AUDIOCVT_PACKED
229#endif
230/* */
231typedef struct SDL_AudioCVT
232{
233 int needed;
236 double rate_incr;
237 Uint8 *buf;
238 int len;
241 double len_ratio;
242 SDL_AudioFilter filters[SDL_AUDIOCVT_MAX_FILTERS + 1];
244} SDL_AUDIOCVT_PACKED SDL_AudioCVT;
245
246
247/* Function prototypes */
248
255/* @{ */
256
276extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
277
298extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
299/* @} */
300
308/* @{ */
309
325extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
326
339extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
340/* @} */
341
358extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
359
407extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
408 SDL_AudioSpec * obtained);
409
419typedef Uint32 SDL_AudioDeviceID;
420
465extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
466
492extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
493 int iscapture);
494
518extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
519 int iscapture,
520 SDL_AudioSpec *spec);
521
522
553extern DECLSPEC int SDLCALL SDL_GetDefaultAudioInfo(char **name,
554 SDL_AudioSpec *spec,
555 int iscapture);
556
557
670 const char *device,
671 int iscapture,
672 const SDL_AudioSpec *desired,
673 SDL_AudioSpec *obtained,
674 int allowed_changes);
675
676
677
683/* @{ */
684typedef enum
685{
686 SDL_AUDIO_STOPPED = 0,
687 SDL_AUDIO_PLAYING,
688 SDL_AUDIO_PAUSED
689} SDL_AudioStatus;
690
709extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
710
722extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
723/* @} *//* Audio State */
724
734/* @{ */
735
755extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
756
785extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
786 int pause_on);
787/* @} *//* Pause audio functions */
788
870extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
871 int freesrc,
872 SDL_AudioSpec * spec,
873 Uint8 ** audio_buf,
874 Uint32 * audio_len);
875
880#define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
881 SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
882
898extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
899
932extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
933 SDL_AudioFormat src_format,
934 Uint8 src_channels,
935 int src_rate,
936 SDL_AudioFormat dst_format,
937 Uint8 dst_channels,
938 int dst_rate);
939
978extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
979
980/* SDL_AudioStream is a new audio conversion interface.
981 The benefits vs SDL_AudioCVT:
982 - it can handle resampling data in chunks without generating
983 artifacts, when it doesn't have the complete buffer available.
984 - it can handle incoming data in any variable size.
985 - You push data as you have it, and pull it when you need it
986 */
987/* this is opaque to the outside world. */
988struct _SDL_AudioStream;
989typedef struct _SDL_AudioStream SDL_AudioStream;
990
1011extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format,
1012 const Uint8 src_channels,
1013 const int src_rate,
1014 const SDL_AudioFormat dst_format,
1015 const Uint8 dst_channels,
1016 const int dst_rate);
1017
1035extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len);
1036
1054extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len);
1055
1072extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
1073
1091extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
1092
1105extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
1106
1119extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
1120
1121#define SDL_MIX_MAXVOLUME 128
1122
1145extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
1146 Uint32 len, int volume);
1147
1178extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
1179 const Uint8 * src,
1180 SDL_AudioFormat format,
1181 Uint32 len, int volume);
1182
1229extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
1230
1277extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
1278
1311extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
1312
1345extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
1346
1347
1356/* @{ */
1357
1376extern DECLSPEC void SDLCALL SDL_LockAudio(void);
1377
1415extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
1416
1434extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
1435
1448extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
1449/* @} *//* Audio lock functions */
1450
1466extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
1467
1490extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
1491
1492/* Ends C function definitions when using C++ */
1493#ifdef __cplusplus
1494}
1495#endif
1496#include "close_code.h"
1497
1498#endif /* SDL_audio_h_ */
1499
1500/* vi: set ts=4 sw=4 expandtab: */
DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev)
DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev)
DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len)
DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void)
DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, int volume)
DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec *desired, SDL_AudioSpec *obtained)
DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev)
void(SDLCALL * SDL_AudioCallback)(void *userdata, Uint8 *stream, int len)
Definition: SDL_audio.h:165
#define SDL_AUDIOCVT_MAX_FILTERS
Upper limit of filters in SDL_AudioCVT.
Definition: SDL_audio.h:205
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)
DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream)
DECLSPEC int SDLCALL SDL_GetDefaultAudioInfo(char **name, SDL_AudioSpec *spec, int iscapture)
DECLSPEC void SDLCALL SDL_AudioQuit(void)
Uint16 SDL_AudioFormat
Audio format flags.
Definition: SDL_audio.h:66
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)
DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void)
DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index)
DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 *audio_buf)
Uint32 SDL_AudioDeviceID
Definition: SDL_audio.h:419
DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len)
DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len)
DECLSPEC void SDLCALL SDL_UnlockAudio(void)
DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream)
DECLSPEC void SDLCALL SDL_LockAudio(void)
DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT *cvt)
DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev)
DECLSPEC void SDLCALL SDL_CloseAudio(void)
DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on)
DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index, int iscapture, SDL_AudioSpec *spec)
DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index, int iscapture)
DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream)
DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev, int pause_on)
DECLSPEC void SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, Uint32 len, int volume)
DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev)
DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev)
DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream)
DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture)
DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len)
DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name)
DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void)
DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char *device, int iscapture, const SDL_AudioSpec *desired, SDL_AudioSpec *obtained, int allowed_changes)
A structure to hold a set of audio conversion filters and buffers.
Definition: SDL_audio.h:232
double len_ratio
Definition: SDL_audio.h:241
int len_mult
Definition: SDL_audio.h:240
int filter_index
Definition: SDL_audio.h:243
SDL_AudioFormat src_format
Definition: SDL_audio.h:234
int len_cvt
Definition: SDL_audio.h:239
double rate_incr
Definition: SDL_audio.h:236
Uint8 * buf
Definition: SDL_audio.h:237
int needed
Definition: SDL_audio.h:233
SDL_AudioFormat dst_format
Definition: SDL_audio.h:235
SDL_AudioFilter filters[SDL_AUDIOCVT_MAX_FILTERS+1]
Definition: SDL_audio.h:242
int len
Definition: SDL_audio.h:238
Definition: SDL_audio.h:181
Uint32 size
Definition: SDL_audio.h:188
Uint8 channels
Definition: SDL_audio.h:184
Uint16 padding
Definition: SDL_audio.h:187
Uint8 silence
Definition: SDL_audio.h:185
SDL_AudioCallback callback
Definition: SDL_audio.h:189
SDL_AudioFormat format
Definition: SDL_audio.h:183
int freq
Definition: SDL_audio.h:182
void * userdata
Definition: SDL_audio.h:190
Uint16 samples
Definition: SDL_audio.h:186
Definition: SDL_rwops.h:53