SDL 3.0
SDL_audio.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 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/**
23 * # CategoryAudio
24 *
25 * Audio functionality for the SDL library.
26 *
27 * All audio in SDL3 revolves around SDL_AudioStream. Whether you want to play
28 * or record audio, convert it, stream it, buffer it, or mix it, you're going
29 * to be passing it through an audio stream.
30 *
31 * Audio streams are quite flexible; they can accept any amount of data at a
32 * time, in any supported format, and output it as needed in any other format,
33 * even if the data format changes on either side halfway through.
34 *
35 * An app opens an audio device and binds any number of audio streams to it,
36 * feeding more data to it as available. When the devices needs more data, it
37 * will pull it from all bound streams and mix them together for playback.
38 *
39 * Audio streams can also use an app-provided callback to supply data
40 * on-demand, which maps pretty closely to the SDL2 audio model.
41 *
42 * SDL also provides a simple .WAV loader in SDL_LoadWAV (and SDL_LoadWAV_IO
43 * if you aren't reading from a file) as a basic means to load sound data into
44 * your program.
45 *
46 * ## Channel layouts
47 *
48 * Audio data passing through SDL is uncompressed PCM data, interleaved. One
49 * can provide their own decompression through an MP3, etc, decoder, but SDL
50 * does not provide this directly. Each interleaved channel of data is meant
51 * to be in a specific order.
52 *
53 * Abbreviations:
54 *
55 * - FRONT = single mono speaker
56 * - FL = front left speaker
57 * - FR = front right speaker
58 * - FC = front center speaker
59 * - BL = back left speaker
60 * - BR = back right speaker
61 * - SR = surround right speaker
62 * - SL = surround left speaker
63 * - BC = back center speaker
64 * - LFE = low-frequency speaker
65 *
66 * These are listed in the order they are laid out in memory, so "FL, FR"
67 * means "the front left speaker is laid out in memory first, then the front
68 * right, then it repeats for the next audio frame".
69 *
70 * - 1 channel (mono) layout: FRONT
71 * - 2 channels (stereo) layout: FL, FR
72 * - 3 channels (2.1) layout: FL, FR, LFE
73 * - 4 channels (quad) layout: FL, FR, BL, BR
74 * - 5 channels (4.1) layout: FL, FR, LFE, BL, BR
75 * - 6 channels (5.1) layout: FL, FR, FC, LFE, BL, BR (last two can also be
76 * BL, BR)
77 * - 7 channels (6.1) layout: FL, FR, FC, LFE, BC, SL, SR
78 * - 8 channels (7.1) layout: FL, FR, FC, LFE, BL, BR, SL, SR
79 *
80 * This is the same order as DirectSound expects, but applied to all
81 * platforms; SDL will swizzle the channels as necessary if a platform expects
82 * something different.
83 *
84 * SDL_AudioStream can also be provided channel maps to change this ordering
85 * to whatever is necessary, in other audio processing scenarios.
86 */
87
88#ifndef SDL_audio_h_
89#define SDL_audio_h_
90
91#include <SDL3/SDL_stdinc.h>
92#include <SDL3/SDL_endian.h>
93#include <SDL3/SDL_error.h>
94#include <SDL3/SDL_mutex.h>
95#include <SDL3/SDL_properties.h>
96#include <SDL3/SDL_iostream.h>
97
98#include <SDL3/SDL_begin_code.h>
99/* Set up for C function definitions, even when using C++ */
100#ifdef __cplusplus
101extern "C" {
102#endif
103
104/* masks for different parts of SDL_AudioFormat. */
105#define SDL_AUDIO_MASK_BITSIZE (0xFFu)
106#define SDL_AUDIO_MASK_FLOAT (1u<<8)
107#define SDL_AUDIO_MASK_BIG_ENDIAN (1u<<12)
108#define SDL_AUDIO_MASK_SIGNED (1u<<15)
109
110#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, float, size) \
111 (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(float) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE))
112
113/**
114 * Audio format.
115 *
116 * \since This enum is available since SDL 3.0.0.
117 *
118 * \sa SDL_AUDIO_BITSIZE
119 * \sa SDL_AUDIO_BYTESIZE
120 * \sa SDL_AUDIO_ISINT
121 * \sa SDL_AUDIO_ISFLOAT
122 * \sa SDL_AUDIO_ISBIGENDIAN
123 * \sa SDL_AUDIO_ISLITTLEENDIAN
124 * \sa SDL_AUDIO_ISSIGNED
125 * \sa SDL_AUDIO_ISUNSIGNED
126 */
127typedef enum SDL_AudioFormat
128{
129 SDL_AUDIO_UNKNOWN = 0x0000u, /**< Unspecified audio format */
130 SDL_AUDIO_U8 = 0x0008u, /**< Unsigned 8-bit samples */
131 /* SDL_DEFINE_AUDIO_FORMAT(0, 0, 0, 8), */
132 SDL_AUDIO_S8 = 0x8008u, /**< Signed 8-bit samples */
133 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 8), */
134 SDL_AUDIO_S16LE = 0x8010u, /**< Signed 16-bit samples */
135 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 16), */
136 SDL_AUDIO_S16BE = 0x9010u, /**< As above, but big-endian byte order */
137 /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 0, 16), */
138 SDL_AUDIO_S32LE = 0x8020u, /**< 32-bit integer samples */
139 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32), */
140 SDL_AUDIO_S32BE = 0x9020u, /**< As above, but big-endian byte order */
141 /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 0, 32), */
142 SDL_AUDIO_F32LE = 0x8120u, /**< 32-bit floating point samples */
143 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 1, 32), */
144 SDL_AUDIO_F32BE = 0x9120u, /**< As above, but big-endian byte order */
145 /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 1, 32), */
146
147 /* These represent the current system's byteorder. */
148 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
152 #else
156 #endif
158
159
160/**
161 * Retrieve the size, in bits, from an SDL_AudioFormat.
162 *
163 * For example, `SDL_AUDIO_BITSIZE(SDL_AUDIO_S16)` returns 16.
164 *
165 * \param x an SDL_AudioFormat value.
166 * \returns data size in bits.
167 *
168 * \threadsafety It is safe to call this macro from any thread.
169 *
170 * \since This macro is available since SDL 3.0.0.
171 */
172#define SDL_AUDIO_BITSIZE(x) ((x) & SDL_AUDIO_MASK_BITSIZE)
173
174/**
175 * Retrieve the size, in bytes, from an SDL_AudioFormat.
176 *
177 * For example, `SDL_AUDIO_BYTESIZE(SDL_AUDIO_S16)` returns 2.
178 *
179 * \param x an SDL_AudioFormat value.
180 * \returns data size in bytes.
181 *
182 * \threadsafety It is safe to call this macro from any thread.
183 *
184 * \since This macro is available since SDL 3.0.0.
185 */
186#define SDL_AUDIO_BYTESIZE(x) (SDL_AUDIO_BITSIZE(x) / 8)
187
188/**
189 * Determine if an SDL_AudioFormat represents floating point data.
190 *
191 * For example, `SDL_AUDIO_ISFLOAT(SDL_AUDIO_S16)` returns 0.
192 *
193 * \param x an SDL_AudioFormat value.
194 * \returns non-zero if format is floating point, zero otherwise.
195 *
196 * \threadsafety It is safe to call this macro from any thread.
197 *
198 * \since This macro is available since SDL 3.0.0.
199 */
200#define SDL_AUDIO_ISFLOAT(x) ((x) & SDL_AUDIO_MASK_FLOAT)
201
202/**
203 * Determine if an SDL_AudioFormat represents bigendian data.
204 *
205 * For example, `SDL_AUDIO_ISBIGENDIAN(SDL_AUDIO_S16LE)` returns 0.
206 *
207 * \param x an SDL_AudioFormat value.
208 * \returns non-zero if format is bigendian, zero otherwise.
209 *
210 * \threadsafety It is safe to call this macro from any thread.
211 *
212 * \since This macro is available since SDL 3.0.0.
213 */
214#define SDL_AUDIO_ISBIGENDIAN(x) ((x) & SDL_AUDIO_MASK_BIG_ENDIAN)
215
216/**
217 * Determine if an SDL_AudioFormat represents littleendian data.
218 *
219 * For example, `SDL_AUDIO_ISLITTLEENDIAN(SDL_AUDIO_S16BE)` returns 0.
220 *
221 * \param x an SDL_AudioFormat value.
222 * \returns non-zero if format is littleendian, zero otherwise.
223 *
224 * \threadsafety It is safe to call this macro from any thread.
225 *
226 * \since This macro is available since SDL 3.0.0.
227 */
228#define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x))
229
230/**
231 * Determine if an SDL_AudioFormat represents signed data.
232 *
233 * For example, `SDL_AUDIO_ISSIGNED(SDL_AUDIO_U8)` returns 0.
234 *
235 * \param x an SDL_AudioFormat value.
236 * \returns non-zero if format is signed, zero otherwise.
237 *
238 * \threadsafety It is safe to call this macro from any thread.
239 *
240 * \since This macro is available since SDL 3.0.0.
241 */
242#define SDL_AUDIO_ISSIGNED(x) ((x) & SDL_AUDIO_MASK_SIGNED)
243
244/**
245 * Determine if an SDL_AudioFormat represents integer data.
246 *
247 * For example, `SDL_AUDIO_ISINT(SDL_AUDIO_F32)` returns 0.
248 *
249 * \param x an SDL_AudioFormat value.
250 * \returns non-zero if format is integer, zero otherwise.
251 *
252 * \threadsafety It is safe to call this macro from any thread.
253 *
254 * \since This macro is available since SDL 3.0.0.
255 */
256#define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x))
257
258/**
259 * Determine if an SDL_AudioFormat represents unsigned data.
260 *
261 * For example, `SDL_AUDIO_ISUNSIGNED(SDL_AUDIO_S16)` returns 0.
262 *
263 * \param x an SDL_AudioFormat value.
264 * \returns non-zero if format is unsigned, zero otherwise.
265 *
266 * \threadsafety It is safe to call this macro from any thread.
267 *
268 * \since This macro is available since SDL 3.0.0.
269 */
270#define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x))
271
272
273/**
274 * SDL Audio Device instance IDs.
275 *
276 * Zero is used to signify an invalid/null device.
277 *
278 * \since This datatype is available since SDL 3.0.0.
279 */
281
282/**
283 * A value used to request a default playback audio device.
284 *
285 * Several functions that require an SDL_AudioDeviceID will accept this value
286 * to signify the app just wants the system to choose a default device instead
287 * of the app providing a specific one.
288 *
289 * \since This macro is available since SDL 3.0.0.
290 */
291#define SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK ((SDL_AudioDeviceID) 0xFFFFFFFFu)
292
293/**
294 * A value used to request a default recording audio device.
295 *
296 * Several functions that require an SDL_AudioDeviceID will accept this value
297 * to signify the app just wants the system to choose a default device instead
298 * of the app providing a specific one.
299 *
300 * \since This macro is available since SDL 3.0.0.
301 */
302#define SDL_AUDIO_DEVICE_DEFAULT_RECORDING ((SDL_AudioDeviceID) 0xFFFFFFFEu)
303
304/**
305 * Format specifier for audio data.
306 *
307 * \since This struct is available since SDL 3.0.0.
308 *
309 * \sa SDL_AudioFormat
310 */
311typedef struct SDL_AudioSpec
312{
313 SDL_AudioFormat format; /**< Audio data format */
314 int channels; /**< Number of channels: 1 mono, 2 stereo, etc */
315 int freq; /**< sample rate: sample frames per second */
317
318/**
319 * Calculate the size of each audio frame (in bytes) from an SDL_AudioSpec.
320 *
321 * This reports on the size of an audio sample frame: stereo Sint16 data (2
322 * channels of 2 bytes each) would be 4 bytes per frame, for example.
323 *
324 * \param x an SDL_AudioSpec to query.
325 * \returns the number of bytes used per sample frame.
326 *
327 * \threadsafety It is safe to call this macro from any thread.
328 *
329 * \since This macro is available since SDL 3.0.0.
330 */
331#define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels)
332
333/**
334 * The opaque handle that represents an audio stream.
335 *
336 * SDL_AudioStream is an audio conversion interface.
337 *
338 * - It can handle resampling data in chunks without generating artifacts,
339 * when it doesn't have the complete buffer available.
340 * - It can handle incoming data in any variable size.
341 * - It can handle input/output format changes on the fly.
342 * - It can remap audio channels between inputs and outputs.
343 * - You push data as you have it, and pull it when you need it
344 * - It can also function as a basic audio data queue even if you just have
345 * sound that needs to pass from one place to another.
346 * - You can hook callbacks up to them when more data is added or requested,
347 * to manage data on-the-fly.
348 *
349 * Audio streams are the core of the SDL3 audio interface. You create one or
350 * more of them, bind them to an opened audio device, and feed data to them
351 * (or for recording, consume data from them).
352 *
353 * \since This struct is available since SDL 3.0.0.
354 *
355 * \sa SDL_CreateAudioStream
356 */
358
359
360/* Function prototypes */
361
362/**
363 * \name Driver discovery functions
364 *
365 * These functions return the list of built in audio drivers, in the
366 * order that they are normally initialized by default.
367 */
368/* @{ */
369
370/**
371 * Use this function to get the number of built-in audio drivers.
372 *
373 * This function returns a hardcoded number. This never returns a negative
374 * value; if there are no drivers compiled into this build of SDL, this
375 * function returns zero. The presence of a driver in this list does not mean
376 * it will function, it just means SDL is capable of interacting with that
377 * interface. For example, a build of SDL might have esound support, but if
378 * there's no esound server available, SDL's esound driver would fail if used.
379 *
380 * By default, SDL tries all drivers, in its preferred order, until one is
381 * found to be usable.
382 *
383 * \returns the number of built-in audio drivers.
384 *
385 * \threadsafety It is safe to call this function from any thread.
386 *
387 * \since This function is available since SDL 3.0.0.
388 *
389 * \sa SDL_GetAudioDriver
390 */
391extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
392
393/**
394 * Use this function to get the name of a built in audio driver.
395 *
396 * The list of audio drivers is given in the order that they are normally
397 * initialized by default; the drivers that seem more reasonable to choose
398 * first (as far as the SDL developers believe) are earlier in the list.
399 *
400 * The names of drivers are all simple, low-ASCII identifiers, like "alsa",
401 * "coreaudio" or "wasapi". These never have Unicode characters, and are not
402 * meant to be proper names.
403 *
404 * \param index the index of the audio driver; the value ranges from 0 to
405 * SDL_GetNumAudioDrivers() - 1.
406 * \returns the name of the audio driver at the requested index, or NULL if an
407 * invalid index was specified.
408 *
409 * \threadsafety It is safe to call this function from any thread.
410 *
411 * \since This function is available since SDL 3.0.0.
412 *
413 * \sa SDL_GetNumAudioDrivers
414 */
415extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index);
416/* @} */
417
418/**
419 * Get the name of the current audio driver.
420 *
421 * The names of drivers are all simple, low-ASCII identifiers, like "alsa",
422 * "coreaudio" or "wasapi". These never have Unicode characters, and are not
423 * meant to be proper names.
424 *
425 * \returns the name of the current audio driver or NULL if no driver has been
426 * initialized.
427 *
428 * \threadsafety It is safe to call this function from any thread.
429 *
430 * \since This function is available since SDL 3.0.0.
431 */
432extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void);
433
434/**
435 * Get a list of currently-connected audio playback devices.
436 *
437 * This returns of list of available devices that play sound, perhaps to
438 * speakers or headphones ("playback" devices). If you want devices that
439 * record audio, like a microphone ("recording" devices), use
440 * SDL_GetAudioRecordingDevices() instead.
441 *
442 * This only returns a list of physical devices; it will not have any device
443 * IDs returned by SDL_OpenAudioDevice().
444 *
445 * If this function returns NULL, to signify an error, `*count` will be set to
446 * zero.
447 *
448 * \param count a pointer filled in with the number of devices returned, may
449 * be NULL.
450 * \returns a 0 terminated array of device instance IDs or NULL on error; call
451 * SDL_GetError() for more information. This should be freed with
452 * SDL_free() when it is no longer needed.
453 *
454 * \threadsafety It is safe to call this function from any thread.
455 *
456 * \since This function is available since SDL 3.0.0.
457 *
458 * \sa SDL_OpenAudioDevice
459 * \sa SDL_GetAudioRecordingDevices
460 */
461extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int *count);
462
463/**
464 * Get a list of currently-connected audio recording devices.
465 *
466 * This returns of list of available devices that record audio, like a
467 * microphone ("recording" devices). If you want devices that play sound,
468 * perhaps to speakers or headphones ("playback" devices), use
469 * SDL_GetAudioPlaybackDevices() instead.
470 *
471 * This only returns a list of physical devices; it will not have any device
472 * IDs returned by SDL_OpenAudioDevice().
473 *
474 * If this function returns NULL, to signify an error, `*count` will be set to
475 * zero.
476 *
477 * \param count a pointer filled in with the number of devices returned, may
478 * be NULL.
479 * \returns a 0 terminated array of device instance IDs, or NULL on failure;
480 * call SDL_GetError() for more information. This should be freed
481 * with SDL_free() when it is no longer needed.
482 *
483 * \threadsafety It is safe to call this function from any thread.
484 *
485 * \since This function is available since SDL 3.0.0.
486 *
487 * \sa SDL_OpenAudioDevice
488 * \sa SDL_GetAudioPlaybackDevices
489 */
490extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int *count);
491
492/**
493 * Get the human-readable name of a specific audio device.
494 *
495 * \param devid the instance ID of the device to query.
496 * \returns the name of the audio device, or NULL on failure; call
497 * SDL_GetError() for more information.
498 *
499 * \threadsafety It is safe to call this function from any thread.
500 *
501 * \since This function is available since SDL 3.0.0.
502 *
503 * \sa SDL_GetAudioPlaybackDevices
504 * \sa SDL_GetAudioRecordingDevices
505 * \sa SDL_GetDefaultAudioInfo
506 */
507extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid);
508
509/**
510 * Get the current audio format of a specific audio device.
511 *
512 * For an opened device, this will report the format the device is currently
513 * using. If the device isn't yet opened, this will report the device's
514 * preferred format (or a reasonable default if this can't be determined).
515 *
516 * You may also specify SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or
517 * SDL_AUDIO_DEVICE_DEFAULT_RECORDING here, which is useful for getting a
518 * reasonable recommendation before opening the system-recommended default
519 * device.
520 *
521 * You can also use this to request the current device buffer size. This is
522 * specified in sample frames and represents the amount of data SDL will feed
523 * to the physical hardware in each chunk. This can be converted to
524 * milliseconds of audio with the following equation:
525 *
526 * `ms = (int) ((((Sint64) frames) * 1000) / spec.freq);`
527 *
528 * Buffer size is only important if you need low-level control over the audio
529 * playback timing. Most apps do not need this.
530 *
531 * \param devid the instance ID of the device to query.
532 * \param spec on return, will be filled with device details.
533 * \param sample_frames pointer to store device buffer size, in sample frames.
534 * Can be NULL.
535 * \returns true on success or false on failure; call SDL_GetError() for more
536 * information.
537 *
538 * \threadsafety It is safe to call this function from any thread.
539 *
540 * \since This function is available since SDL 3.0.0.
541 */
542extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames);
543
544/**
545 * Get the current channel map of an audio device.
546 *
547 * Channel maps are optional; most things do not need them, instead passing
548 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
549 *
550 * Audio devices usually have no remapping applied. This is represented by
551 * returning NULL, and does not signify an error.
552 *
553 * \param devid the instance ID of the device to query.
554 * \param count On output, set to number of channels in the map. Can be NULL.
555 * \returns an array of the current channel mapping, with as many elements as
556 * the current output spec's channels, or NULL if default. This
557 * should be freed with SDL_free() when it is no longer needed.
558 *
559 * \threadsafety It is safe to call this function from any thread.
560 *
561 * \since This function is available since SDL 3.0.0.
562 *
563 * \sa SDL_SetAudioStreamInputChannelMap
564 */
565extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID devid, int *count);
566
567/**
568 * Open a specific audio device.
569 *
570 * You can open both playback and recording devices through this function.
571 * Playback devices will take data from bound audio streams, mix it, and send
572 * it to the hardware. Recording devices will feed any bound audio streams
573 * with a copy of any incoming data.
574 *
575 * An opened audio device starts out with no audio streams bound. To start
576 * audio playing, bind a stream and supply audio data to it. Unlike SDL2,
577 * there is no audio callback; you only bind audio streams and make sure they
578 * have data flowing into them (however, you can simulate SDL2's semantics
579 * fairly closely by using SDL_OpenAudioDeviceStream instead of this
580 * function).
581 *
582 * If you don't care about opening a specific device, pass a `devid` of either
583 * `SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK` or
584 * `SDL_AUDIO_DEVICE_DEFAULT_RECORDING`. In this case, SDL will try to pick
585 * the most reasonable default, and may also switch between physical devices
586 * seamlessly later, if the most reasonable default changes during the
587 * lifetime of this opened device (user changed the default in the OS's system
588 * preferences, the default got unplugged so the system jumped to a new
589 * default, the user plugged in headphones on a mobile device, etc). Unless
590 * you have a good reason to choose a specific device, this is probably what
591 * you want.
592 *
593 * You may request a specific format for the audio device, but there is no
594 * promise the device will honor that request for several reasons. As such,
595 * it's only meant to be a hint as to what data your app will provide. Audio
596 * streams will accept data in whatever format you specify and manage
597 * conversion for you as appropriate. SDL_GetAudioDeviceFormat can tell you
598 * the preferred format for the device before opening and the actual format
599 * the device is using after opening.
600 *
601 * It's legal to open the same device ID more than once; each successful open
602 * will generate a new logical SDL_AudioDeviceID that is managed separately
603 * from others on the same physical device. This allows libraries to open a
604 * device separately from the main app and bind its own streams without
605 * conflicting.
606 *
607 * It is also legal to open a device ID returned by a previous call to this
608 * function; doing so just creates another logical device on the same physical
609 * device. This may be useful for making logical groupings of audio streams.
610 *
611 * This function returns the opened device ID on success. This is a new,
612 * unique SDL_AudioDeviceID that represents a logical device.
613 *
614 * Some backends might offer arbitrary devices (for example, a networked audio
615 * protocol that can connect to an arbitrary server). For these, as a change
616 * from SDL2, you should open a default device ID and use an SDL hint to
617 * specify the target if you care, or otherwise let the backend figure out a
618 * reasonable default. Most backends don't offer anything like this, and often
619 * this would be an end user setting an environment variable for their custom
620 * need, and not something an application should specifically manage.
621 *
622 * When done with an audio device, possibly at the end of the app's life, one
623 * should call SDL_CloseAudioDevice() on the returned device id.
624 *
625 * \param devid the device instance id to open, or
626 * SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or
627 * SDL_AUDIO_DEVICE_DEFAULT_RECORDING for the most reasonable
628 * default device.
629 * \param spec the requested device configuration. Can be NULL to use
630 * reasonable defaults.
631 * \returns the device ID on success or 0 on failure; call SDL_GetError() for
632 * more information.
633 *
634 * \threadsafety It is safe to call this function from any thread.
635 *
636 * \since This function is available since SDL 3.0.0.
637 *
638 * \sa SDL_CloseAudioDevice
639 * \sa SDL_GetAudioDeviceFormat
640 */
641extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec);
642
643/**
644 * Use this function to pause audio playback on a specified device.
645 *
646 * This function pauses audio processing for a given device. Any bound audio
647 * streams will not progress, and no audio will be generated. Pausing one
648 * device does not prevent other unpaused devices from running.
649 *
650 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
651 * has to bind a stream before any audio will flow. Pausing a paused device is
652 * a legal no-op.
653 *
654 * Pausing a device can be useful to halt all audio without unbinding all the
655 * audio streams. This might be useful while a game is paused, or a level is
656 * loading, etc.
657 *
658 * Physical devices can not be paused or unpaused, only logical devices
659 * created through SDL_OpenAudioDevice() can be.
660 *
661 * \param dev a device opened by SDL_OpenAudioDevice().
662 * \returns true on success or false on failure; call SDL_GetError() for more
663 * information.
664 *
665 * \threadsafety It is safe to call this function from any thread.
666 *
667 * \since This function is available since SDL 3.0.0.
668 *
669 * \sa SDL_ResumeAudioDevice
670 * \sa SDL_AudioDevicePaused
671 */
672extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev);
673
674/**
675 * Use this function to unpause audio playback on a specified device.
676 *
677 * This function unpauses audio processing for a given device that has
678 * previously been paused with SDL_PauseAudioDevice(). Once unpaused, any
679 * bound audio streams will begin to progress again, and audio can be
680 * generated.
681 *
682 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
683 * has to bind a stream before any audio will flow. Unpausing an unpaused
684 * device is a legal no-op.
685 *
686 * Physical devices can not be paused or unpaused, only logical devices
687 * created through SDL_OpenAudioDevice() can be.
688 *
689 * \param dev a device opened by SDL_OpenAudioDevice().
690 * \returns true on success or false on failure; call SDL_GetError() for more
691 * information.
692 *
693 * \threadsafety It is safe to call this function from any thread.
694 *
695 * \since This function is available since SDL 3.0.0.
696 *
697 * \sa SDL_AudioDevicePaused
698 * \sa SDL_PauseAudioDevice
699 */
700extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev);
701
702/**
703 * Use this function to query if an audio device is paused.
704 *
705 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
706 * has to bind a stream before any audio will flow.
707 *
708 * Physical devices can not be paused or unpaused, only logical devices
709 * created through SDL_OpenAudioDevice() can be. Physical and invalid device
710 * IDs will report themselves as unpaused here.
711 *
712 * \param dev a device opened by SDL_OpenAudioDevice().
713 * \returns true if device is valid and paused, false otherwise.
714 *
715 * \threadsafety It is safe to call this function from any thread.
716 *
717 * \since This function is available since SDL 3.0.0.
718 *
719 * \sa SDL_PauseAudioDevice
720 * \sa SDL_ResumeAudioDevice
721 */
722extern SDL_DECLSPEC bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev);
723
724/**
725 * Get the gain of an audio device.
726 *
727 * The gain of a device is its volume; a larger gain means a louder output,
728 * with a gain of zero being silence.
729 *
730 * Audio devices default to a gain of 1.0f (no change in output).
731 *
732 * Physical devices may not have their gain changed, only logical devices, and
733 * this function will always return -1.0f when used on physical devices.
734 *
735 * \param devid the audio device to query.
736 * \returns the gain of the device or -1.0f on failure; call SDL_GetError()
737 * for more information.
738 *
739 * \threadsafety It is safe to call this function from any thread.
740 *
741 * \since This function is available since SDL 3.0.0.
742 *
743 * \sa SDL_SetAudioDeviceGain
744 */
745extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid);
746
747/**
748 * Change the gain of an audio device.
749 *
750 * The gain of a device is its volume; a larger gain means a louder output,
751 * with a gain of zero being silence.
752 *
753 * Audio devices default to a gain of 1.0f (no change in output).
754 *
755 * Physical devices may not have their gain changed, only logical devices, and
756 * this function will always return false when used on physical devices. While
757 * it might seem attractive to adjust several logical devices at once in this
758 * way, it would allow an app or library to interfere with another portion of
759 * the program's otherwise-isolated devices.
760 *
761 * This is applied, along with any per-audiostream gain, during playback to
762 * the hardware, and can be continuously changed to create various effects. On
763 * recording devices, this will adjust the gain before passing the data into
764 * an audiostream; that recording audiostream can then adjust its gain further
765 * when outputting the data elsewhere, if it likes, but that second gain is
766 * not applied until the data leaves the audiostream again.
767 *
768 * \param devid the audio device on which to change gain.
769 * \param gain the gain. 1.0f is no change, 0.0f is silence.
770 * \returns true on success or false on failure; call SDL_GetError() for more
771 * information.
772 *
773 * \threadsafety It is safe to call this function from any thread, as it holds
774 * a stream-specific mutex while running.
775 *
776 * \since This function is available since SDL 3.0.0.
777 *
778 * \sa SDL_GetAudioDeviceGain
779 */
780extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain);
781
782/**
783 * Close a previously-opened audio device.
784 *
785 * The application should close open audio devices once they are no longer
786 * needed.
787 *
788 * This function may block briefly while pending audio data is played by the
789 * hardware, so that applications don't drop the last buffer of data they
790 * supplied if terminating immediately afterwards.
791 *
792 * \param devid an audio device id previously returned by
793 * SDL_OpenAudioDevice().
794 *
795 * \threadsafety It is safe to call this function from any thread.
796 *
797 * \since This function is available since SDL 3.0.0.
798 *
799 * \sa SDL_OpenAudioDevice
800 */
801extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
802
803/**
804 * Bind a list of audio streams to an audio device.
805 *
806 * Audio data will flow through any bound streams. For a playback device, data
807 * for all bound streams will be mixed together and fed to the device. For a
808 * recording device, a copy of recorded data will be provided to each bound
809 * stream.
810 *
811 * Audio streams can only be bound to an open device. This operation is
812 * atomic--all streams bound in the same call will start processing at the
813 * same time, so they can stay in sync. Also: either all streams will be bound
814 * or none of them will be.
815 *
816 * It is an error to bind an already-bound stream; it must be explicitly
817 * unbound first.
818 *
819 * Binding a stream to a device will set its output format for playback
820 * devices, and its input format for recording devices, so they match the
821 * device's settings. The caller is welcome to change the other end of the
822 * stream's format at any time.
823 *
824 * \param devid an audio device to bind a stream to.
825 * \param streams an array of audio streams to bind.
826 * \param num_streams number streams listed in the `streams` array.
827 * \returns true on success or false on failure; call SDL_GetError() for more
828 * information.
829 *
830 * \threadsafety It is safe to call this function from any thread.
831 *
832 * \since This function is available since SDL 3.0.0.
833 *
834 * \sa SDL_BindAudioStreams
835 * \sa SDL_UnbindAudioStream
836 * \sa SDL_GetAudioStreamDevice
837 */
838extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams);
839
840/**
841 * Bind a single audio stream to an audio device.
842 *
843 * This is a convenience function, equivalent to calling
844 * `SDL_BindAudioStreams(devid, &stream, 1)`.
845 *
846 * \param devid an audio device to bind a stream to.
847 * \param stream an audio stream to bind to a device.
848 * \returns true on success or false on failure; call SDL_GetError() for more
849 * information.
850 *
851 * \threadsafety It is safe to call this function from any thread.
852 *
853 * \since This function is available since SDL 3.0.0.
854 *
855 * \sa SDL_BindAudioStreams
856 * \sa SDL_UnbindAudioStream
857 * \sa SDL_GetAudioStreamDevice
858 */
859extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream);
860
861/**
862 * Unbind a list of audio streams from their audio devices.
863 *
864 * The streams being unbound do not all have to be on the same device. All
865 * streams on the same device will be unbound atomically (data will stop
866 * flowing through all unbound streams on the same device at the same time).
867 *
868 * Unbinding a stream that isn't bound to a device is a legal no-op.
869 *
870 * \param streams an array of audio streams to unbind.
871 * \param num_streams number streams listed in the `streams` array.
872 *
873 * \threadsafety It is safe to call this function from any thread.
874 *
875 * \since This function is available since SDL 3.0.0.
876 *
877 * \sa SDL_BindAudioStreams
878 */
879extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams);
880
881/**
882 * Unbind a single audio stream from its audio device.
883 *
884 * This is a convenience function, equivalent to calling
885 * `SDL_UnbindAudioStreams(&stream, 1)`.
886 *
887 * \param stream an audio stream to unbind from a device.
888 *
889 * \threadsafety It is safe to call this function from any thread.
890 *
891 * \since This function is available since SDL 3.0.0.
892 *
893 * \sa SDL_BindAudioStream
894 */
895extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream);
896
897/**
898 * Query an audio stream for its currently-bound device.
899 *
900 * This reports the audio device that an audio stream is currently bound to.
901 *
902 * If not bound, or invalid, this returns zero, which is not a valid device
903 * ID.
904 *
905 * \param stream the audio stream to query.
906 * \returns the bound audio device, or 0 if not bound or invalid.
907 *
908 * \threadsafety It is safe to call this function from any thread.
909 *
910 * \since This function is available since SDL 3.0.0.
911 *
912 * \sa SDL_BindAudioStream
913 * \sa SDL_BindAudioStreams
914 */
915extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_AudioStream *stream);
916
917/**
918 * Create a new audio stream.
919 *
920 * \param src_spec the format details of the input audio.
921 * \param dst_spec the format details of the output audio.
922 * \returns a new audio stream on success or NULL on failure; call
923 * SDL_GetError() for more information.
924 *
925 * \threadsafety It is safe to call this function from any thread.
926 *
927 * \since This function is available since SDL 3.0.0.
928 *
929 * \sa SDL_PutAudioStreamData
930 * \sa SDL_GetAudioStreamData
931 * \sa SDL_GetAudioStreamAvailable
932 * \sa SDL_FlushAudioStream
933 * \sa SDL_ClearAudioStream
934 * \sa SDL_SetAudioStreamFormat
935 * \sa SDL_DestroyAudioStream
936 */
937extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec);
938
939/**
940 * Get the properties associated with an audio stream.
941 *
942 * \param stream the SDL_AudioStream to query.
943 * \returns a valid property ID on success or 0 on failure; call
944 * SDL_GetError() for more information.
945 *
946 * \since This function is available since SDL 3.0.0.
947 */
949
950/**
951 * Query the current format of an audio stream.
952 *
953 * \param stream the SDL_AudioStream to query.
954 * \param src_spec where to store the input audio format; ignored if NULL.
955 * \param dst_spec where to store the output audio format; ignored if NULL.
956 * \returns true on success or false on failure; call SDL_GetError() for more
957 * information.
958 *
959 * \threadsafety It is safe to call this function from any thread, as it holds
960 * a stream-specific mutex while running.
961 *
962 * \since This function is available since SDL 3.0.0.
963 *
964 * \sa SDL_SetAudioStreamFormat
965 */
966extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec);
967
968/**
969 * Change the input and output formats of an audio stream.
970 *
971 * Future calls to and SDL_GetAudioStreamAvailable and SDL_GetAudioStreamData
972 * will reflect the new format, and future calls to SDL_PutAudioStreamData
973 * must provide data in the new input formats.
974 *
975 * Data that was previously queued in the stream will still be operated on in
976 * the format that was current when it was added, which is to say you can put
977 * the end of a sound file in one format to a stream, change formats for the
978 * next sound file, and start putting that new data while the previous sound
979 * file is still queued, and everything will still play back correctly.
980 *
981 * \param stream the stream the format is being changed.
982 * \param src_spec the new format of the audio input; if NULL, it is not
983 * changed.
984 * \param dst_spec the new format of the audio output; if NULL, it is not
985 * changed.
986 * \returns true on success or false on failure; call SDL_GetError() for more
987 * information.
988 *
989 * \threadsafety It is safe to call this function from any thread, as it holds
990 * a stream-specific mutex while running.
991 *
992 * \since This function is available since SDL 3.0.0.
993 *
994 * \sa SDL_GetAudioStreamFormat
995 * \sa SDL_SetAudioStreamFrequencyRatio
996 */
997extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec);
998
999/**
1000 * Get the frequency ratio of an audio stream.
1001 *
1002 * \param stream the SDL_AudioStream to query.
1003 * \returns the frequency ratio of the stream or 0.0 on failure; call
1004 * SDL_GetError() for more information.
1005 *
1006 * \threadsafety It is safe to call this function from any thread, as it holds
1007 * a stream-specific mutex while running.
1008 *
1009 * \since This function is available since SDL 3.0.0.
1010 *
1011 * \sa SDL_SetAudioStreamFrequencyRatio
1012 */
1013extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStream *stream);
1014
1015/**
1016 * Change the frequency ratio of an audio stream.
1017 *
1018 * The frequency ratio is used to adjust the rate at which input data is
1019 * consumed. Changing this effectively modifies the speed and pitch of the
1020 * audio. A value greater than 1.0 will play the audio faster, and at a higher
1021 * pitch. A value less than 1.0 will play the audio slower, and at a lower
1022 * pitch.
1023 *
1024 * This is applied during SDL_GetAudioStreamData, and can be continuously
1025 * changed to create various effects.
1026 *
1027 * \param stream the stream the frequency ratio is being changed.
1028 * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01
1029 * and 100.
1030 * \returns true on success or false on failure; call SDL_GetError() for more
1031 * information.
1032 *
1033 * \threadsafety It is safe to call this function from any thread, as it holds
1034 * a stream-specific mutex while running.
1035 *
1036 * \since This function is available since SDL 3.0.0.
1037 *
1038 * \sa SDL_GetAudioStreamFrequencyRatio
1039 * \sa SDL_SetAudioStreamFormat
1040 */
1041extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio);
1042
1043/**
1044 * Get the gain of an audio stream.
1045 *
1046 * The gain of a stream is its volume; a larger gain means a louder output,
1047 * with a gain of zero being silence.
1048 *
1049 * Audio streams default to a gain of 1.0f (no change in output).
1050 *
1051 * \param stream the SDL_AudioStream to query.
1052 * \returns the gain of the stream or -1.0f on failure; call SDL_GetError()
1053 * for more information.
1054 *
1055 * \threadsafety It is safe to call this function from any thread, as it holds
1056 * a stream-specific mutex while running.
1057 *
1058 * \since This function is available since SDL 3.0.0.
1059 *
1060 * \sa SDL_SetAudioStreamGain
1061 */
1062extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream);
1063
1064/**
1065 * Change the gain of an audio stream.
1066 *
1067 * The gain of a stream is its volume; a larger gain means a louder output,
1068 * with a gain of zero being silence.
1069 *
1070 * Audio streams default to a gain of 1.0f (no change in output).
1071 *
1072 * This is applied during SDL_GetAudioStreamData, and can be continuously
1073 * changed to create various effects.
1074 *
1075 * \param stream the stream on which the gain is being changed.
1076 * \param gain the gain. 1.0f is no change, 0.0f is silence.
1077 * \returns true on success or false on failure; call SDL_GetError() for more
1078 * information.
1079 *
1080 * \threadsafety It is safe to call this function from any thread, as it holds
1081 * a stream-specific mutex while running.
1082 *
1083 * \since This function is available since SDL 3.0.0.
1084 *
1085 * \sa SDL_GetAudioStreamGain
1086 */
1087extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain);
1088
1089/**
1090 * Get the current input channel map of an audio stream.
1091 *
1092 * Channel maps are optional; most things do not need them, instead passing
1093 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
1094 *
1095 * Audio streams default to no remapping applied. This is represented by
1096 * returning NULL, and does not signify an error.
1097 *
1098 * \param stream the SDL_AudioStream to query.
1099 * \param count On output, set to number of channels in the map. Can be NULL.
1100 * \returns an array of the current channel mapping, with as many elements as
1101 * the current output spec's channels, or NULL if default. This
1102 * should be freed with SDL_free() when it is no longer needed.
1103 *
1104 * \threadsafety It is safe to call this function from any thread, as it holds
1105 * a stream-specific mutex while running.
1106 *
1107 * \since This function is available since SDL 3.0.0.
1108 *
1109 * \sa SDL_SetAudioStreamInputChannelMap
1110 */
1111extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStream *stream, int *count);
1112
1113/**
1114 * Get the current output channel map of an audio stream.
1115 *
1116 * Channel maps are optional; most things do not need them, instead passing
1117 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
1118 *
1119 * Audio streams default to no remapping applied. This is represented by
1120 * returning NULL, and does not signify an error.
1121 *
1122 * \param stream the SDL_AudioStream to query.
1123 * \param count On output, set to number of channels in the map. Can be NULL.
1124 * \returns an array of the current channel mapping, with as many elements as
1125 * the current output spec's channels, or NULL if default. This
1126 * should be freed with SDL_free() when it is no longer needed.
1127 *
1128 * \threadsafety It is safe to call this function from any thread, as it holds
1129 * a stream-specific mutex while running.
1130 *
1131 * \since This function is available since SDL 3.0.0.
1132 *
1133 * \sa SDL_SetAudioStreamInputChannelMap
1134 */
1135extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioStream *stream, int *count);
1136
1137/**
1138 * Set the current input channel map of an audio stream.
1139 *
1140 * Channel maps are optional; most things do not need them, instead passing
1141 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
1142 *
1143 * The input channel map reorders data that is added to a stream via
1144 * SDL_PutAudioStreamData. Future calls to SDL_PutAudioStreamData must provide
1145 * data in the new channel order.
1146 *
1147 * Each item in the array represents an input channel, and its value is the
1148 * channel that it should be remapped to. To reverse a stereo signal's left
1149 * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap
1150 * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the
1151 * right channel to both channels of a stereo signal. You cannot change the
1152 * number of channels through a channel map, just reorder them.
1153 *
1154 * Data that was previously queued in the stream will still be operated on in
1155 * the order that was current when it was added, which is to say you can put
1156 * the end of a sound file in one order to a stream, change orders for the
1157 * next sound file, and start putting that new data while the previous sound
1158 * file is still queued, and everything will still play back correctly.
1159 *
1160 * Audio streams default to no remapping applied. Passing a NULL channel map
1161 * is legal, and turns off remapping.
1162 *
1163 * SDL will copy the channel map; the caller does not have to save this array
1164 * after this call.
1165 *
1166 * If `count` is not equal to the current number of channels in the audio
1167 * stream's format, this will fail. This is a safety measure to make sure a a
1168 * race condition hasn't changed the format while you this call is setting the
1169 * channel map.
1170 *
1171 * \param stream the SDL_AudioStream to change.
1172 * \param chmap the new channel map, NULL to reset to default.
1173 * \param count The number of channels in the map.
1174 * \returns true on success or false on failure; call SDL_GetError() for more
1175 * information.
1176 *
1177 * \threadsafety It is safe to call this function from any thread, as it holds
1178 * a stream-specific mutex while running. Don't change the
1179 * stream's format to have a different number of channels from a
1180 * a different thread at the same time, though!
1181 *
1182 * \since This function is available since SDL 3.0.0.
1183 *
1184 * \sa SDL_SetAudioStreamInputChannelMap
1185 */
1186extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count);
1187
1188/**
1189 * Set the current output channel map of an audio stream.
1190 *
1191 * Channel maps are optional; most things do not need them, instead passing
1192 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
1193 *
1194 * The output channel map reorders data that leaving a stream via
1195 * SDL_GetAudioStreamData.
1196 *
1197 * Each item in the array represents an output channel, and its value is the
1198 * channel that it should be remapped to. To reverse a stereo signal's left
1199 * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap
1200 * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the
1201 * right channel to both channels of a stereo signal. You cannot change the
1202 * number of channels through a channel map, just reorder them.
1203 *
1204 * The output channel map can be changed at any time, as output remapping is
1205 * applied during SDL_GetAudioStreamData.
1206 *
1207 * Audio streams default to no remapping applied. Passing a NULL channel map
1208 * is legal, and turns off remapping.
1209 *
1210 * SDL will copy the channel map; the caller does not have to save this array
1211 * after this call.
1212 *
1213 * If `count` is not equal to the current number of channels in the audio
1214 * stream's format, this will fail. This is a safety measure to make sure a a
1215 * race condition hasn't changed the format while you this call is setting the
1216 * channel map.
1217 *
1218 * \param stream the SDL_AudioStream to change.
1219 * \param chmap the new channel map, NULL to reset to default.
1220 * \param count The number of channels in the map.
1221 * \returns true on success or false on failure; call SDL_GetError() for more
1222 * information.
1223 *
1224 * \threadsafety It is safe to call this function from any thread, as it holds
1225 * a stream-specific mutex while running. Don't change the
1226 * stream's format to have a different number of channels from a
1227 * a different thread at the same time, though!
1228 *
1229 * \since This function is available since SDL 3.0.0.
1230 *
1231 * \sa SDL_SetAudioStreamInputChannelMap
1232 */
1233extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count);
1234
1235/**
1236 * Add data to the stream.
1237 *
1238 * This data must match the format/channels/samplerate specified in the latest
1239 * call to SDL_SetAudioStreamFormat, or the format specified when creating the
1240 * stream if it hasn't been changed.
1241 *
1242 * Note that this call simply copies the unconverted data for later. This is
1243 * different than SDL2, where data was converted during the Put call and the
1244 * Get call would just dequeue the previously-converted data.
1245 *
1246 * \param stream the stream the audio data is being added to.
1247 * \param buf a pointer to the audio data to add.
1248 * \param len the number of bytes to write to the stream.
1249 * \returns true on success or false on failure; call SDL_GetError() for more
1250 * information.
1251 *
1252 * \threadsafety It is safe to call this function from any thread, but if the
1253 * stream has a callback set, the caller might need to manage
1254 * extra locking.
1255 *
1256 * \since This function is available since SDL 3.0.0.
1257 *
1258 * \sa SDL_ClearAudioStream
1259 * \sa SDL_FlushAudioStream
1260 * \sa SDL_GetAudioStreamData
1261 * \sa SDL_GetAudioStreamQueued
1262 */
1263extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len);
1264
1265/**
1266 * Get converted/resampled data from the stream.
1267 *
1268 * The input/output data format/channels/samplerate is specified when creating
1269 * the stream, and can be changed after creation by calling
1270 * SDL_SetAudioStreamFormat.
1271 *
1272 * Note that any conversion and resampling necessary is done during this call,
1273 * and SDL_PutAudioStreamData simply queues unconverted data for later. This
1274 * is different than SDL2, where that work was done while inputting new data
1275 * to the stream and requesting the output just copied the converted data.
1276 *
1277 * \param stream the stream the audio is being requested from.
1278 * \param buf a buffer to fill with audio data.
1279 * \param len the maximum number of bytes to fill.
1280 * \returns the number of bytes read from the stream or -1 on failure; call
1281 * SDL_GetError() for more information.
1282 *
1283 * \threadsafety It is safe to call this function from any thread, but if the
1284 * stream has a callback set, the caller might need to manage
1285 * extra locking.
1286 *
1287 * \since This function is available since SDL 3.0.0.
1288 *
1289 * \sa SDL_ClearAudioStream
1290 * \sa SDL_GetAudioStreamAvailable
1291 * \sa SDL_PutAudioStreamData
1292 */
1293extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, void *buf, int len);
1294
1295/**
1296 * Get the number of converted/resampled bytes available.
1297 *
1298 * The stream may be buffering data behind the scenes until it has enough to
1299 * resample correctly, so this number might be lower than what you expect, or
1300 * even be zero. Add more data or flush the stream if you need the data now.
1301 *
1302 * If the stream has so much data that it would overflow an int, the return
1303 * value is clamped to a maximum value, but no queued data is lost; if there
1304 * are gigabytes of data queued, the app might need to read some of it with
1305 * SDL_GetAudioStreamData before this function's return value is no longer
1306 * clamped.
1307 *
1308 * \param stream the audio stream to query.
1309 * \returns the number of converted/resampled bytes available or -1 on
1310 * failure; call SDL_GetError() for more information.
1311 *
1312 * \threadsafety It is safe to call this function from any thread.
1313 *
1314 * \since This function is available since SDL 3.0.0.
1315 *
1316 * \sa SDL_GetAudioStreamData
1317 * \sa SDL_PutAudioStreamData
1318 */
1319extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *stream);
1320
1321
1322/**
1323 * Get the number of bytes currently queued.
1324 *
1325 * This is the number of bytes put into a stream as input, not the number that
1326 * can be retrieved as output. Because of several details, it's not possible
1327 * to calculate one number directly from the other. If you need to know how
1328 * much usable data can be retrieved right now, you should use
1329 * SDL_GetAudioStreamAvailable() and not this function.
1330 *
1331 * Note that audio streams can change their input format at any time, even if
1332 * there is still data queued in a different format, so the returned byte
1333 * count will not necessarily match the number of _sample frames_ available.
1334 * Users of this API should be aware of format changes they make when feeding
1335 * a stream and plan accordingly.
1336 *
1337 * Queued data is not converted until it is consumed by
1338 * SDL_GetAudioStreamData, so this value should be representative of the exact
1339 * data that was put into the stream.
1340 *
1341 * If the stream has so much data that it would overflow an int, the return
1342 * value is clamped to a maximum value, but no queued data is lost; if there
1343 * are gigabytes of data queued, the app might need to read some of it with
1344 * SDL_GetAudioStreamData before this function's return value is no longer
1345 * clamped.
1346 *
1347 * \param stream the audio stream to query.
1348 * \returns the number of bytes queued or -1 on failure; call SDL_GetError()
1349 * for more information.
1350 *
1351 * \threadsafety It is safe to call this function from any thread.
1352 *
1353 * \since This function is available since SDL 3.0.0.
1354 *
1355 * \sa SDL_PutAudioStreamData
1356 * \sa SDL_ClearAudioStream
1357 */
1358extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream);
1359
1360
1361/**
1362 * Tell the stream that you're done sending data, and anything being buffered
1363 * should be converted/resampled and made available immediately.
1364 *
1365 * It is legal to add more data to a stream after flushing, but there may be
1366 * audio gaps in the output. Generally this is intended to signal the end of
1367 * input, so the complete output becomes available.
1368 *
1369 * \param stream the audio stream to flush.
1370 * \returns true on success or false on failure; call SDL_GetError() for more
1371 * information.
1372 *
1373 * \threadsafety It is safe to call this function from any thread.
1374 *
1375 * \since This function is available since SDL 3.0.0.
1376 *
1377 * \sa SDL_PutAudioStreamData
1378 */
1379extern SDL_DECLSPEC bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
1380
1381/**
1382 * Clear any pending data in the stream.
1383 *
1384 * This drops any queued data, so there will be nothing to read from the
1385 * stream until more is added.
1386 *
1387 * \param stream the audio stream to clear.
1388 * \returns true on success or false on failure; call SDL_GetError() for more
1389 * information.
1390 *
1391 * \threadsafety It is safe to call this function from any thread.
1392 *
1393 * \since This function is available since SDL 3.0.0.
1394 *
1395 * \sa SDL_GetAudioStreamAvailable
1396 * \sa SDL_GetAudioStreamData
1397 * \sa SDL_GetAudioStreamQueued
1398 * \sa SDL_PutAudioStreamData
1399 */
1400extern SDL_DECLSPEC bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
1401
1402/**
1403 * Use this function to pause audio playback on the audio device associated
1404 * with an audio stream.
1405 *
1406 * This function pauses audio processing for a given device. Any bound audio
1407 * streams will not progress, and no audio will be generated. Pausing one
1408 * device does not prevent other unpaused devices from running.
1409 *
1410 * Pausing a device can be useful to halt all audio without unbinding all the
1411 * audio streams. This might be useful while a game is paused, or a level is
1412 * loading, etc.
1413 *
1414 * \param stream the audio stream associated with the audio device to pause.
1415 * \returns true on success or false on failure; call SDL_GetError() for more
1416 * information.
1417 *
1418 * \threadsafety It is safe to call this function from any thread.
1419 *
1420 * \since This function is available since SDL 3.0.0.
1421 *
1422 * \sa SDL_ResumeAudioStreamDevice
1423 */
1424extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream);
1425
1426/**
1427 * Use this function to unpause audio playback on the audio device associated
1428 * with an audio stream.
1429 *
1430 * This function unpauses audio processing for a given device that has
1431 * previously been paused. Once unpaused, any bound audio streams will begin
1432 * to progress again, and audio can be generated.
1433 *
1434 * \param stream the audio stream associated with the audio device to resume.
1435 * \returns true on success or false on failure; call SDL_GetError() for more
1436 * information.
1437 *
1438 * \threadsafety It is safe to call this function from any thread.
1439 *
1440 * \since This function is available since SDL 3.0.0.
1441 *
1442 * \sa SDL_PauseAudioStreamDevice
1443 */
1444extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream);
1445
1446/**
1447 * Lock an audio stream for serialized access.
1448 *
1449 * Each SDL_AudioStream has an internal mutex it uses to protect its data
1450 * structures from threading conflicts. This function allows an app to lock
1451 * that mutex, which could be useful if registering callbacks on this stream.
1452 *
1453 * One does not need to lock a stream to use in it most cases, as the stream
1454 * manages this lock internally. However, this lock is held during callbacks,
1455 * which may run from arbitrary threads at any time, so if an app needs to
1456 * protect shared data during those callbacks, locking the stream guarantees
1457 * that the callback is not running while the lock is held.
1458 *
1459 * As this is just a wrapper over SDL_LockMutex for an internal lock; it has
1460 * all the same attributes (recursive locks are allowed, etc).
1461 *
1462 * \param stream the audio stream to lock.
1463 * \returns true on success or false on failure; call SDL_GetError() for more
1464 * information.
1465 *
1466 * \threadsafety It is safe to call this function from any thread.
1467 *
1468 * \since This function is available since SDL 3.0.0.
1469 *
1470 * \sa SDL_UnlockAudioStream
1471 */
1472extern SDL_DECLSPEC bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream);
1473
1474
1475/**
1476 * Unlock an audio stream for serialized access.
1477 *
1478 * This unlocks an audio stream after a call to SDL_LockAudioStream.
1479 *
1480 * \param stream the audio stream to unlock.
1481 * \returns true on success or false on failure; call SDL_GetError() for more
1482 * information.
1483 *
1484 * \threadsafety You should only call this from the same thread that
1485 * previously called SDL_LockAudioStream.
1486 *
1487 * \since This function is available since SDL 3.0.0.
1488 *
1489 * \sa SDL_LockAudioStream
1490 */
1491extern SDL_DECLSPEC bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream);
1492
1493/**
1494 * A callback that fires when data passes through an SDL_AudioStream.
1495 *
1496 * Apps can (optionally) register a callback with an audio stream that is
1497 * called when data is added with SDL_PutAudioStreamData, or requested with
1498 * SDL_GetAudioStreamData.
1499 *
1500 * Two values are offered here: one is the amount of additional data needed to
1501 * satisfy the immediate request (which might be zero if the stream already
1502 * has enough data queued) and the other is the total amount being requested.
1503 * In a Get call triggering a Put callback, these values can be different. In
1504 * a Put call triggering a Get callback, these values are always the same.
1505 *
1506 * Byte counts might be slightly overestimated due to buffering or resampling,
1507 * and may change from call to call.
1508 *
1509 * This callback is not required to do anything. Generally this is useful for
1510 * adding/reading data on demand, and the app will often put/get data as
1511 * appropriate, but the system goes on with the data currently available to it
1512 * if this callback does nothing.
1513 *
1514 * \param stream the SDL audio stream associated with this callback.
1515 * \param additional_amount the amount of data, in bytes, that is needed right
1516 * now.
1517 * \param total_amount the total amount of data requested, in bytes, that is
1518 * requested or available.
1519 * \param userdata an opaque pointer provided by the app for their personal
1520 * use.
1521 *
1522 * \threadsafety This callbacks may run from any thread, so if you need to
1523 * protect shared data, you should use SDL_LockAudioStream to
1524 * serialize access; this lock will be held before your callback
1525 * is called, so your callback does not need to manage the lock
1526 * explicitly.
1527 *
1528 * \since This datatype is available since SDL 3.0.0.
1529 *
1530 * \sa SDL_SetAudioStreamGetCallback
1531 * \sa SDL_SetAudioStreamPutCallback
1532 */
1533typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount);
1534
1535/**
1536 * Set a callback that runs when data is requested from an audio stream.
1537 *
1538 * This callback is called _before_ data is obtained from the stream, giving
1539 * the callback the chance to add more on-demand.
1540 *
1541 * The callback can (optionally) call SDL_PutAudioStreamData() to add more
1542 * audio to the stream during this call; if needed, the request that triggered
1543 * this callback will obtain the new data immediately.
1544 *
1545 * The callback's `approx_request` argument is roughly how many bytes of
1546 * _unconverted_ data (in the stream's input format) is needed by the caller,
1547 * although this may overestimate a little for safety. This takes into account
1548 * how much is already in the stream and only asks for any extra necessary to
1549 * resolve the request, which means the callback may be asked for zero bytes,
1550 * and a different amount on each call.
1551 *
1552 * The callback is not required to supply exact amounts; it is allowed to
1553 * supply too much or too little or none at all. The caller will get what's
1554 * available, up to the amount they requested, regardless of this callback's
1555 * outcome.
1556 *
1557 * Clearing or flushing an audio stream does not call this callback.
1558 *
1559 * This function obtains the stream's lock, which means any existing callback
1560 * (get or put) in progress will finish running before setting the new
1561 * callback.
1562 *
1563 * Setting a NULL function turns off the callback.
1564 *
1565 * \param stream the audio stream to set the new callback on.
1566 * \param callback the new callback function to call when data is requested
1567 * from the stream.
1568 * \param userdata an opaque pointer provided to the callback for its own
1569 * personal use.
1570 * \returns true on success or false on failure; call SDL_GetError() for more
1571 * information. This only fails if `stream` is NULL.
1572 *
1573 * \threadsafety It is safe to call this function from any thread.
1574 *
1575 * \since This function is available since SDL 3.0.0.
1576 *
1577 * \sa SDL_SetAudioStreamPutCallback
1578 */
1579extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata);
1580
1581/**
1582 * Set a callback that runs when data is added to an audio stream.
1583 *
1584 * This callback is called _after_ the data is added to the stream, giving the
1585 * callback the chance to obtain it immediately.
1586 *
1587 * The callback can (optionally) call SDL_GetAudioStreamData() to obtain audio
1588 * from the stream during this call.
1589 *
1590 * The callback's `approx_request` argument is how many bytes of _converted_
1591 * data (in the stream's output format) was provided by the caller, although
1592 * this may underestimate a little for safety. This value might be less than
1593 * what is currently available in the stream, if data was already there, and
1594 * might be less than the caller provided if the stream needs to keep a buffer
1595 * to aid in resampling. Which means the callback may be provided with zero
1596 * bytes, and a different amount on each call.
1597 *
1598 * The callback may call SDL_GetAudioStreamAvailable to see the total amount
1599 * currently available to read from the stream, instead of the total provided
1600 * by the current call.
1601 *
1602 * The callback is not required to obtain all data. It is allowed to read less
1603 * or none at all. Anything not read now simply remains in the stream for
1604 * later access.
1605 *
1606 * Clearing or flushing an audio stream does not call this callback.
1607 *
1608 * This function obtains the stream's lock, which means any existing callback
1609 * (get or put) in progress will finish running before setting the new
1610 * callback.
1611 *
1612 * Setting a NULL function turns off the callback.
1613 *
1614 * \param stream the audio stream to set the new callback on.
1615 * \param callback the new callback function to call when data is added to the
1616 * stream.
1617 * \param userdata an opaque pointer provided to the callback for its own
1618 * personal use.
1619 * \returns true on success or false on failure; call SDL_GetError() for more
1620 * information. This only fails if `stream` is NULL.
1621 *
1622 * \threadsafety It is safe to call this function from any thread.
1623 *
1624 * \since This function is available since SDL 3.0.0.
1625 *
1626 * \sa SDL_SetAudioStreamGetCallback
1627 */
1628extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata);
1629
1630
1631/**
1632 * Free an audio stream.
1633 *
1634 * This will release all allocated data, including any audio that is still
1635 * queued. You do not need to manually clear the stream first.
1636 *
1637 * If this stream was bound to an audio device, it is unbound during this
1638 * call. If this stream was created with SDL_OpenAudioDeviceStream, the audio
1639 * device that was opened alongside this stream's creation will be closed,
1640 * too.
1641 *
1642 * \param stream the audio stream to destroy.
1643 *
1644 * \threadsafety It is safe to call this function from any thread.
1645 *
1646 * \since This function is available since SDL 3.0.0.
1647 *
1648 * \sa SDL_CreateAudioStream
1649 */
1650extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream);
1651
1652
1653/**
1654 * Convenience function for straightforward audio init for the common case.
1655 *
1656 * If all your app intends to do is provide a single source of PCM audio, this
1657 * function allows you to do all your audio setup in a single call.
1658 *
1659 * This is also intended to be a clean means to migrate apps from SDL2.
1660 *
1661 * This function will open an audio device, create a stream and bind it.
1662 * Unlike other methods of setup, the audio device will be closed when this
1663 * stream is destroyed, so the app can treat the returned SDL_AudioStream as
1664 * the only object needed to manage audio playback.
1665 *
1666 * Also unlike other functions, the audio device begins paused. This is to map
1667 * more closely to SDL2-style behavior, since there is no extra step here to
1668 * bind a stream to begin audio flowing. The audio device should be resumed
1669 * with `SDL_ResumeAudioStreamDevice(stream);`
1670 *
1671 * This function works with both playback and recording devices.
1672 *
1673 * The `spec` parameter represents the app's side of the audio stream. That
1674 * is, for recording audio, this will be the output format, and for playing
1675 * audio, this will be the input format. If spec is NULL, the system will
1676 * choose the format, and the app can use SDL_GetAudioStreamFormat() to obtain
1677 * this information later.
1678 *
1679 * If you don't care about opening a specific audio device, you can (and
1680 * probably _should_), use SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK for playback and
1681 * SDL_AUDIO_DEVICE_DEFAULT_RECORDING for recording.
1682 *
1683 * One can optionally provide a callback function; if NULL, the app is
1684 * expected to queue audio data for playback (or unqueue audio data if
1685 * capturing). Otherwise, the callback will begin to fire once the device is
1686 * unpaused.
1687 *
1688 * Destroying the returned stream with SDL_DestroyAudioStream will also close
1689 * the audio device associated with this stream.
1690 *
1691 * \param devid an audio device to open, or SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK
1692 * or SDL_AUDIO_DEVICE_DEFAULT_RECORDING.
1693 * \param spec the audio stream's data format. Can be NULL.
1694 * \param callback a callback where the app will provide new data for
1695 * playback, or receive new data for recording. Can be NULL,
1696 * in which case the app will need to call
1697 * SDL_PutAudioStreamData or SDL_GetAudioStreamData as
1698 * necessary.
1699 * \param userdata app-controlled pointer passed to callback. Can be NULL.
1700 * Ignored if callback is NULL.
1701 * \returns an audio stream on success, ready to use, or NULL on failure; call
1702 * SDL_GetError() for more information. When done with this stream,
1703 * call SDL_DestroyAudioStream to free resources and close the
1704 * device.
1705 *
1706 * \threadsafety It is safe to call this function from any thread.
1707 *
1708 * \since This function is available since SDL 3.0.0.
1709 *
1710 * \sa SDL_GetAudioStreamDevice
1711 * \sa SDL_ResumeAudioStreamDevice
1712 */
1713extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata);
1714
1715/**
1716 * A callback that fires when data is about to be fed to an audio device.
1717 *
1718 * This is useful for accessing the final mix, perhaps for writing a
1719 * visualizer or applying a final effect to the audio data before playback.
1720 *
1721 * This callback should run as quickly as possible and not block for any
1722 * significant time, as this callback delays submission of data to the audio
1723 * device, which can cause audio playback problems.
1724 *
1725 * The postmix callback _must_ be able to handle any audio data format
1726 * specified in `spec`, which can change between callbacks if the audio device
1727 * changed. However, this only covers frequency and channel count; data is
1728 * always provided here in SDL_AUDIO_F32 format.
1729 *
1730 * The postmix callback runs _after_ logical device gain and audiostream gain
1731 * have been applied, which is to say you can make the output data louder at
1732 * this point than the gain settings would suggest.
1733 *
1734 * \param userdata a pointer provided by the app through
1735 * SDL_SetAudioPostmixCallback, for its own use.
1736 * \param spec the current format of audio that is to be submitted to the
1737 * audio device.
1738 * \param buffer the buffer of audio samples to be submitted. The callback can
1739 * inspect and/or modify this data.
1740 * \param buflen the size of `buffer` in bytes.
1741 *
1742 * \threadsafety This will run from a background thread owned by SDL. The
1743 * application is responsible for locking resources the callback
1744 * touches that need to be protected.
1745 *
1746 * \since This datatype is available since SDL 3.0.0.
1747 *
1748 * \sa SDL_SetAudioPostmixCallback
1749 */
1750typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_AudioSpec *spec, float *buffer, int buflen);
1751
1752/**
1753 * Set a callback that fires when data is about to be fed to an audio device.
1754 *
1755 * This is useful for accessing the final mix, perhaps for writing a
1756 * visualizer or applying a final effect to the audio data before playback.
1757 *
1758 * The buffer is the final mix of all bound audio streams on an opened device;
1759 * this callback will fire regularly for any device that is both opened and
1760 * unpaused. If there is no new data to mix, either because no streams are
1761 * bound to the device or all the streams are empty, this callback will still
1762 * fire with the entire buffer set to silence.
1763 *
1764 * This callback is allowed to make changes to the data; the contents of the
1765 * buffer after this call is what is ultimately passed along to the hardware.
1766 *
1767 * The callback is always provided the data in float format (values from -1.0f
1768 * to 1.0f), but the number of channels or sample rate may be different than
1769 * the format the app requested when opening the device; SDL might have had to
1770 * manage a conversion behind the scenes, or the playback might have jumped to
1771 * new physical hardware when a system default changed, etc. These details may
1772 * change between calls. Accordingly, the size of the buffer might change
1773 * between calls as well.
1774 *
1775 * This callback can run at any time, and from any thread; if you need to
1776 * serialize access to your app's data, you should provide and use a mutex or
1777 * other synchronization device.
1778 *
1779 * All of this to say: there are specific needs this callback can fulfill, but
1780 * it is not the simplest interface. Apps should generally provide audio in
1781 * their preferred format through an SDL_AudioStream and let SDL handle the
1782 * difference.
1783 *
1784 * This function is extremely time-sensitive; the callback should do the least
1785 * amount of work possible and return as quickly as it can. The longer the
1786 * callback runs, the higher the risk of audio dropouts or other problems.
1787 *
1788 * This function will block until the audio device is in between iterations,
1789 * so any existing callback that might be running will finish before this
1790 * function sets the new callback and returns.
1791 *
1792 * Setting a NULL callback function disables any previously-set callback.
1793 *
1794 * \param devid the ID of an opened audio device.
1795 * \param callback a callback function to be called. Can be NULL.
1796 * \param userdata app-controlled pointer passed to callback. Can be NULL.
1797 * \returns true on success or false on failure; call SDL_GetError() for more
1798 * information.
1799 *
1800 * \threadsafety It is safe to call this function from any thread.
1801 *
1802 * \since This function is available since SDL 3.0.0.
1803 */
1804extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata);
1805
1806
1807/**
1808 * Load the audio data of a WAVE file into memory.
1809 *
1810 * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
1811 * be valid pointers. The entire data portion of the file is then loaded into
1812 * memory and decoded if necessary.
1813 *
1814 * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
1815 * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
1816 * A-law and mu-law (8 bits). Other formats are currently unsupported and
1817 * cause an error.
1818 *
1819 * If this function succeeds, the return value is zero and the pointer to the
1820 * audio data allocated by the function is written to `audio_buf` and its
1821 * length in bytes to `audio_len`. The SDL_AudioSpec members `freq`,
1822 * `channels`, and `format` are set to the values of the audio data in the
1823 * buffer.
1824 *
1825 * It's necessary to use SDL_free() to free the audio data returned in
1826 * `audio_buf` when it is no longer used.
1827 *
1828 * Because of the underspecification of the .WAV format, there are many
1829 * problematic files in the wild that cause issues with strict decoders. To
1830 * provide compatibility with these files, this decoder is lenient in regards
1831 * to the truncation of the file, the fact chunk, and the size of the RIFF
1832 * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
1833 * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
1834 * tune the behavior of the loading process.
1835 *
1836 * Any file that is invalid (due to truncation, corruption, or wrong values in
1837 * the headers), too big, or unsupported causes an error. Additionally, any
1838 * critical I/O error from the data source will terminate the loading process
1839 * with an error. The function returns NULL on error and in all cases (with
1840 * the exception of `src` being NULL), an appropriate error message will be
1841 * set.
1842 *
1843 * It is required that the data source supports seeking.
1844 *
1845 * Example:
1846 *
1847 * ```c
1848 * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
1849 * ```
1850 *
1851 * Note that the SDL_LoadWAV function does this same thing for you, but in a
1852 * less messy way:
1853 *
1854 * ```c
1855 * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
1856 * ```
1857 *
1858 * \param src the data source for the WAVE data.
1859 * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even
1860 * in the case of an error.
1861 * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE
1862 * data's format details on successful return.
1863 * \param audio_buf a pointer filled with the audio data, allocated by the
1864 * function.
1865 * \param audio_len a pointer filled with the length of the audio data buffer
1866 * in bytes.
1867 * \returns true on success. `audio_buf` will be filled with a pointer to an
1868 * allocated buffer containing the audio data, and `audio_len` is
1869 * filled with the length of that audio buffer in bytes.
1870 *
1871 * This function returns false if the .WAV file cannot be opened,
1872 * uses an unknown data format, or is corrupt; call SDL_GetError()
1873 * for more information.
1874 *
1875 * When the application is done with the data returned in
1876 * `audio_buf`, it should call SDL_free() to dispose of it.
1877 *
1878 * \threadsafety It is safe to call this function from any thread.
1879 *
1880 * \since This function is available since SDL 3.0.0.
1881 *
1882 * \sa SDL_free
1883 * \sa SDL_LoadWAV
1884 */
1885extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len);
1886
1887/**
1888 * Loads a WAV from a file path.
1889 *
1890 * This is a convenience function that is effectively the same as:
1891 *
1892 * ```c
1893 * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), true, spec, audio_buf, audio_len);
1894 * ```
1895 *
1896 * \param path the file path of the WAV file to open.
1897 * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE
1898 * data's format details on successful return.
1899 * \param audio_buf a pointer filled with the audio data, allocated by the
1900 * function.
1901 * \param audio_len a pointer filled with the length of the audio data buffer
1902 * in bytes.
1903 * \returns true on success. `audio_buf` will be filled with a pointer to an
1904 * allocated buffer containing the audio data, and `audio_len` is
1905 * filled with the length of that audio buffer in bytes.
1906 *
1907 * This function returns false if the .WAV file cannot be opened,
1908 * uses an unknown data format, or is corrupt; call SDL_GetError()
1909 * for more information.
1910 *
1911 * When the application is done with the data returned in
1912 * `audio_buf`, it should call SDL_free() to dispose of it.
1913 *
1914 * \threadsafety It is safe to call this function from any thread.
1915 *
1916 * \since This function is available since SDL 3.0.0.
1917 *
1918 * \sa SDL_free
1919 * \sa SDL_LoadWAV_IO
1920 */
1921extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len);
1922
1923/**
1924 * Mix audio data in a specified format.
1925 *
1926 * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
1927 * it into `dst`, performing addition, volume adjustment, and overflow
1928 * clipping. The buffer pointed to by `dst` must also be `len` bytes of
1929 * `format` data.
1930 *
1931 * This is provided for convenience -- you can mix your own audio data.
1932 *
1933 * Do not use this function for mixing together more than two streams of
1934 * sample data. The output from repeated application of this function may be
1935 * distorted by clipping, because there is no accumulator with greater range
1936 * than the input (not to mention this being an inefficient way of doing it).
1937 *
1938 * It is a common misconception that this function is required to write audio
1939 * data to an output stream in an audio callback. While you can do that,
1940 * SDL_MixAudio() is really only needed when you're mixing a single audio
1941 * stream with a volume adjustment.
1942 *
1943 * \param dst the destination for the mixed audio.
1944 * \param src the source audio buffer to be mixed.
1945 * \param format the SDL_AudioFormat structure representing the desired audio
1946 * format.
1947 * \param len the length of the audio buffer in bytes.
1948 * \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full
1949 * audio volume.
1950 * \returns true on success or false on failure; call SDL_GetError() for more
1951 * information.
1952 *
1953 * \threadsafety It is safe to call this function from any thread.
1954 *
1955 * \since This function is available since SDL 3.0.0.
1956 */
1957extern SDL_DECLSPEC bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume);
1958
1959/**
1960 * Convert some audio data of one format to another format.
1961 *
1962 * Please note that this function is for convenience, but should not be used
1963 * to resample audio in blocks, as it will introduce audio artifacts on the
1964 * boundaries. You should only use this function if you are converting audio
1965 * data in its entirety in one call. If you want to convert audio in smaller
1966 * chunks, use an SDL_AudioStream, which is designed for this situation.
1967 *
1968 * Internally, this function creates and destroys an SDL_AudioStream on each
1969 * use, so it's also less efficient than using one directly, if you need to
1970 * convert multiple times.
1971 *
1972 * \param src_spec the format details of the input audio.
1973 * \param src_data the audio data to be converted.
1974 * \param src_len the len of src_data.
1975 * \param dst_spec the format details of the output audio.
1976 * \param dst_data will be filled with a pointer to converted audio data,
1977 * which should be freed with SDL_free(). On error, it will be
1978 * NULL.
1979 * \param dst_len will be filled with the len of dst_data.
1980 * \returns true on success or false on failure; call SDL_GetError() for more
1981 * information.
1982 *
1983 * \threadsafety It is safe to call this function from any thread.
1984 *
1985 * \since This function is available since SDL 3.0.0.
1986 */
1987extern SDL_DECLSPEC bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len);
1988
1989/**
1990 * Get the human readable name of an audio format.
1991 *
1992 * \param format the audio format to query.
1993 * \returns the human readable name of the specified audio format or
1994 * "SDL_AUDIO_UNKNOWN" if the format isn't recognized.
1995 *
1996 * \threadsafety It is safe to call this function from any thread.
1997 *
1998 * \since This function is available since SDL 3.0.0.
1999 */
2000extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat format);
2001
2002/**
2003 * Get the appropriate memset value for silencing an audio format.
2004 *
2005 * The value returned by this function can be used as the second argument to
2006 * memset (or SDL_memset) to set an audio buffer in a specific format to
2007 * silence.
2008 *
2009 * \param format the audio data format to query.
2010 * \returns a byte value that can be passed to memset.
2011 *
2012 * \threadsafety It is safe to call this function from any thread.
2013 *
2014 * \since This function is available since SDL 3.0.0.
2015 */
2016extern SDL_DECLSPEC int SDLCALL SDL_GetSilenceValueForFormat(SDL_AudioFormat format);
2017
2018
2019/* Ends C function definitions when using C++ */
2020#ifdef __cplusplus
2021}
2022#endif
2023#include <SDL3/SDL_close_code.h>
2024
2025#endif /* SDL_audio_h_ */
bool SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume)
const char * SDL_GetAudioDeviceName(SDL_AudioDeviceID devid)
bool SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec)
SDL_AudioDeviceID * SDL_GetAudioRecordingDevices(int *count)
bool SDL_UnlockAudioStream(SDL_AudioStream *stream)
int * SDL_GetAudioStreamInputChannelMap(SDL_AudioStream *stream, int *count)
const char * SDL_GetAudioDriver(int index)
SDL_AudioStream * SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec)
void SDL_UnbindAudioStream(SDL_AudioStream *stream)
float SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid)
bool SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain)
struct SDL_AudioStream SDL_AudioStream
Definition SDL_audio.h:357
bool SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata)
SDL_AudioDeviceID * SDL_GetAudioPlaybackDevices(int *count)
bool SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata)
void(* SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount)
Definition SDL_audio.h:1533
bool SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count)
bool SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio)
bool SDL_AudioDevicePaused(SDL_AudioDeviceID dev)
int SDL_GetNumAudioDrivers(void)
bool SDL_LockAudioStream(SDL_AudioStream *stream)
float SDL_GetAudioStreamGain(SDL_AudioStream *stream)
Uint32 SDL_AudioDeviceID
Definition SDL_audio.h:280
int SDL_GetAudioStreamQueued(SDL_AudioStream *stream)
bool SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain)
int SDL_GetSilenceValueForFormat(SDL_AudioFormat format)
const char * SDL_GetCurrentAudioDriver(void)
SDL_PropertiesID SDL_GetAudioStreamProperties(SDL_AudioStream *stream)
SDL_AudioStream * SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata)
bool SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream)
void(* SDL_AudioPostmixCallback)(void *userdata, const SDL_AudioSpec *spec, float *buffer, int buflen)
Definition SDL_audio.h:1750
bool SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames)
bool SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count)
bool SDL_PauseAudioStreamDevice(SDL_AudioStream *stream)
float SDL_GetAudioStreamFrequencyRatio(SDL_AudioStream *stream)
int SDL_GetAudioStreamAvailable(SDL_AudioStream *stream)
SDL_AudioFormat
Definition SDL_audio.h:128
@ SDL_AUDIO_S32LE
Definition SDL_audio.h:138
@ SDL_AUDIO_F32
Definition SDL_audio.h:151
@ SDL_AUDIO_S16LE
Definition SDL_audio.h:134
@ SDL_AUDIO_S16
Definition SDL_audio.h:149
@ SDL_AUDIO_U8
Definition SDL_audio.h:130
@ SDL_AUDIO_S8
Definition SDL_audio.h:132
@ SDL_AUDIO_S32
Definition SDL_audio.h:150
@ SDL_AUDIO_F32LE
Definition SDL_audio.h:142
@ SDL_AUDIO_S32BE
Definition SDL_audio.h:140
@ SDL_AUDIO_UNKNOWN
Definition SDL_audio.h:129
@ SDL_AUDIO_S16BE
Definition SDL_audio.h:136
@ SDL_AUDIO_F32BE
Definition SDL_audio.h:144
bool SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
bool SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len)
bool SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams)
void SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams)
int * SDL_GetAudioStreamOutputChannelMap(SDL_AudioStream *stream, int *count)
bool SDL_ResumeAudioDevice(SDL_AudioDeviceID dev)
bool SDL_ClearAudioStream(SDL_AudioStream *stream)
void SDL_DestroyAudioStream(SDL_AudioStream *stream)
bool SDL_PauseAudioDevice(SDL_AudioDeviceID dev)
void SDL_CloseAudioDevice(SDL_AudioDeviceID devid)
int SDL_GetAudioStreamData(SDL_AudioStream *stream, void *buf, int len)
const char * SDL_GetAudioFormatName(SDL_AudioFormat format)
bool SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec)
SDL_AudioDeviceID SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec)
bool SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream)
bool SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata)
bool SDL_FlushAudioStream(SDL_AudioStream *stream)
int * SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID devid, int *count)
bool SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len)
SDL_AudioDeviceID SDL_GetAudioStreamDevice(SDL_AudioStream *stream)
bool SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
struct SDL_IOStream SDL_IOStream
Uint32 SDL_PropertiesID
uint8_t Uint8
Definition SDL_stdinc.h:320
uint32_t Uint32
Definition SDL_stdinc.h:356
SDL_AudioFormat format
Definition SDL_audio.h:313