SDL 3.0
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/**
23 * \file SDL_audio.h
24 *
25 * \brief Audio functionality for the SDL library.
26 */
27
28#ifndef SDL_audio_h_
29#define SDL_audio_h_
30
31#include <SDL3/SDL_stdinc.h>
32#include <SDL3/SDL_error.h>
33#include <SDL3/SDL_endian.h>
34#include <SDL3/SDL_mutex.h>
35#include <SDL3/SDL_thread.h>
36#include <SDL3/SDL_rwops.h>
37
38#include <SDL3/SDL_begin_code.h>
39/* Set up for C function definitions, even when using C++ */
40#ifdef __cplusplus
41extern "C" {
42#endif
43
44/*
45 * For multi-channel audio, the default SDL channel mapping is:
46 * 2: FL FR (stereo)
47 * 3: FL FR LFE (2.1 surround)
48 * 4: FL FR BL BR (quad)
49 * 5: FL FR LFE BL BR (4.1 surround)
50 * 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR)
51 * 7: FL FR FC LFE BC SL SR (6.1 surround)
52 * 8: FL FR FC LFE BL BR SL SR (7.1 surround)
53 */
54
55/**
56 * \brief Audio format flags.
57 *
58 * These are what the 16 bits in SDL_AudioFormat currently mean...
59 * (Unspecified bits are always zero).
60 *
61 * \verbatim
62 ++-----------------------sample is signed if set
63 ||
64 || ++-----------sample is bigendian if set
65 || ||
66 || || ++---sample is float if set
67 || || ||
68 || || || +---sample bit size---+
69 || || || | |
70 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
71 \endverbatim
72 *
73 * There are macros in SDL 2.0 and later to query these bits.
74 */
76
77/**
78 * \name Audio flags
79 */
80/* @{ */
81
82#define SDL_AUDIO_MASK_BITSIZE (0xFF)
83#define SDL_AUDIO_MASK_DATATYPE (1<<8)
84#define SDL_AUDIO_MASK_ENDIAN (1<<12)
85#define SDL_AUDIO_MASK_SIGNED (1<<15)
86#define SDL_AUDIO_BITSIZE(x) (x & SDL_AUDIO_MASK_BITSIZE)
87#define SDL_AUDIO_ISFLOAT(x) (x & SDL_AUDIO_MASK_DATATYPE)
88#define SDL_AUDIO_ISBIGENDIAN(x) (x & SDL_AUDIO_MASK_ENDIAN)
89#define SDL_AUDIO_ISSIGNED(x) (x & SDL_AUDIO_MASK_SIGNED)
90#define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x))
91#define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x))
92#define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x))
93
94/**
95 * \name Audio format flags
96 *
97 * Defaults to LSB byte order.
98 */
99/* @{ */
100#define SDL_AUDIO_U8 0x0008 /**< Unsigned 8-bit samples */
101#define SDL_AUDIO_S8 0x8008 /**< Signed 8-bit samples */
102#define SDL_AUDIO_S16LSB 0x8010 /**< Signed 16-bit samples */
103#define SDL_AUDIO_S16MSB 0x9010 /**< As above, but big-endian byte order */
104#define SDL_AUDIO_S16 SDL_AUDIO_S16LSB
105/* @} */
106
107/**
108 * \name int32 support
109 */
110/* @{ */
111#define SDL_AUDIO_S32LSB 0x8020 /**< 32-bit integer samples */
112#define SDL_AUDIO_S32MSB 0x9020 /**< As above, but big-endian byte order */
113#define SDL_AUDIO_S32 SDL_AUDIO_S32LSB
114/* @} */
115
116/**
117 * \name float32 support
118 */
119/* @{ */
120#define SDL_AUDIO_F32LSB 0x8120 /**< 32-bit floating point samples */
121#define SDL_AUDIO_F32MSB 0x9120 /**< As above, but big-endian byte order */
122#define SDL_AUDIO_F32 SDL_AUDIO_F32LSB
123/* @} */
124
125/**
126 * \name Native audio byte ordering
127 */
128/* @{ */
129#if SDL_BYTEORDER == SDL_LIL_ENDIAN
130#define SDL_AUDIO_S16SYS SDL_AUDIO_S16LSB
131#define SDL_AUDIO_S32SYS SDL_AUDIO_S32LSB
132#define SDL_AUDIO_F32SYS SDL_AUDIO_F32LSB
133#else
134#define SDL_AUDIO_S16SYS SDL_AUDIO_S16MSB
135#define SDL_AUDIO_S32SYS SDL_AUDIO_S32MSB
136#define SDL_AUDIO_F32SYS SDL_AUDIO_F32MSB
137#endif
138/* @} */
139
140/* @} *//* Audio flags */
141
142/**
143 * SDL Audio Device instance IDs.
144 */
146
147#define SDL_AUDIO_DEVICE_DEFAULT_OUTPUT ((SDL_AudioDeviceID) 0xFFFFFFFF)
148#define SDL_AUDIO_DEVICE_DEFAULT_CAPTURE ((SDL_AudioDeviceID) 0xFFFFFFFE)
149
150typedef struct SDL_AudioSpec
151{
152 SDL_AudioFormat format; /**< Audio data format */
153 int channels; /**< Number of channels: 1 mono, 2 stereo, etc */
154 int freq; /**< sample rate: sample frames per second */
156
157/* SDL_AudioStream is an audio conversion interface.
158 - It can handle resampling data in chunks without generating
159 artifacts, when it doesn't have the complete buffer available.
160 - It can handle incoming data in any variable size.
161 - It can handle input/output format changes on the fly.
162 - You push data as you have it, and pull it when you need it
163 - It can also function as a basic audio data queue even if you
164 just have sound that needs to pass from one place to another.
165 - You can hook callbacks up to them when more data is added or
166 requested, to manage data on-the-fly.
167 */
168struct SDL_AudioStream; /* this is opaque to the outside world. */
170
171
172/* Function prototypes */
173
174/**
175 * \name Driver discovery functions
176 *
177 * These functions return the list of built in audio drivers, in the
178 * order that they are normally initialized by default.
179 */
180/* @{ */
181
182/**
183 * Use this function to get the number of built-in audio drivers.
184 *
185 * This function returns a hardcoded number. This never returns a negative
186 * value; if there are no drivers compiled into this build of SDL, this
187 * function returns zero. The presence of a driver in this list does not mean
188 * it will function, it just means SDL is capable of interacting with that
189 * interface. For example, a build of SDL might have esound support, but if
190 * there's no esound server available, SDL's esound driver would fail if used.
191 *
192 * By default, SDL tries all drivers, in its preferred order, until one is
193 * found to be usable.
194 *
195 * \returns the number of built-in audio drivers.
196 *
197 * \threadsafety It is safe to call this function from any thread.
198 *
199 * \since This function is available since SDL 3.0.0.
200 *
201 * \sa SDL_GetAudioDriver
202 */
203extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
204
205/**
206 * Use this function to get the name of a built in audio driver.
207 *
208 * The list of audio drivers is given in the order that they are normally
209 * initialized by default; the drivers that seem more reasonable to choose
210 * first (as far as the SDL developers believe) are earlier in the list.
211 *
212 * The names of drivers are all simple, low-ASCII identifiers, like "alsa",
213 * "coreaudio" or "xaudio2". These never have Unicode characters, and are not
214 * meant to be proper names.
215 *
216 * \param index the index of the audio driver; the value ranges from 0 to
217 * SDL_GetNumAudioDrivers() - 1
218 * \returns the name of the audio driver at the requested index, or NULL if an
219 * invalid index was specified.
220 *
221 * \threadsafety It is safe to call this function from any thread.
222 *
223 * \since This function is available since SDL 3.0.0.
224 *
225 * \sa SDL_GetNumAudioDrivers
226 */
227extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
228/* @} */
229
230/**
231 * Get the name of the current audio driver.
232 *
233 * The returned string points to internal static memory and thus never becomes
234 * invalid, even if you quit the audio subsystem and initialize a new driver
235 * (although such a case would return a different static string from another
236 * call to this function, of course). As such, you should not modify or free
237 * the returned string.
238 *
239 * \returns the name of the current audio driver or NULL if no driver has been
240 * initialized.
241 *
242 * \threadsafety It is safe to call this function from any thread.
243 *
244 * \since This function is available since SDL 3.0.0.
245 */
246extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
247
248/**
249 * Get a list of currently-connected audio output devices.
250 *
251 * This returns of list of available devices that play sound, perhaps to
252 * speakers or headphones ("output" devices). If you want devices that record
253 * audio, like a microphone ("capture" devices), use
254 * SDL_GetAudioCaptureDevices() instead.
255 *
256 * This only returns a list of physical devices; it will not have any device
257 * IDs returned by SDL_OpenAudioDevice().
258 *
259 * \param count a pointer filled in with the number of devices returned
260 * \returns a 0 terminated array of device instance IDs which should be freed
261 * with SDL_free(), or NULL on error; call SDL_GetError() for more
262 * details.
263 *
264 * \threadsafety It is safe to call this function from any thread.
265 *
266 * \since This function is available since SDL 3.0.0.
267 *
268 * \sa SDL_OpenAudioDevice
269 * \sa SDL_GetAudioCaptureDevices
270 */
271extern DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioOutputDevices(int *count);
272
273/**
274 * Get a list of currently-connected audio capture devices.
275 *
276 * This returns of list of available devices that record audio, like a
277 * microphone ("capture" devices). If you want devices that play sound,
278 * perhaps to speakers or headphones ("output" devices), use
279 * SDL_GetAudioOutputDevices() instead.
280 *
281 * This only returns a list of physical devices; it will not have any device
282 * IDs returned by SDL_OpenAudioDevice().
283 *
284 * \param count a pointer filled in with the number of devices returned
285 * \returns a 0 terminated array of device instance IDs which should be freed
286 * with SDL_free(), or NULL on error; call SDL_GetError() for more
287 * details.
288 *
289 * \threadsafety It is safe to call this function from any thread.
290 *
291 * \since This function is available since SDL 3.0.0.
292 *
293 * \sa SDL_OpenAudioDevice
294 * \sa SDL_GetAudioOutputDevices
295 */
296extern DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioCaptureDevices(int *count);
297
298/**
299 * Get the human-readable name of a specific audio device.
300 *
301 * The string returned by this function is UTF-8 encoded. The caller should
302 * call SDL_free on the return value when done with it.
303 *
304 * \param devid the instance ID of the device to query.
305 * \returns the name of the audio device, or NULL on error.
306 *
307 * \threadsafety It is safe to call this function from any thread.
308 *
309 * \since This function is available since SDL 3.0.0.
310 *
311 * \sa SDL_GetNumAudioDevices
312 * \sa SDL_GetDefaultAudioInfo
313 */
314extern DECLSPEC char *SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid);
315
316/**
317 * Get the current audio format of a specific audio device.
318 *
319 * For an opened device, this will report the format the device is currently
320 * using. If the device isn't yet opened, this will report the device's
321 * preferred format (or a reasonable default if this can't be determined).
322 *
323 * You may also specify SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
324 * SDL_AUDIO_DEVICE_DEFAULT_CAPTURE here, which is useful for getting a
325 * reasonable recommendation before opening the system-recommended default
326 * device.
327 *
328 * \param devid the instance ID of the device to query.
329 * \param spec On return, will be filled with device details.
330 * \returns 0 on success or a negative error code on failure; call
331 * SDL_GetError() for more information.
332 *
333 * \threadsafety It is safe to call this function from any thread.
334 *
335 * \since This function is available since SDL 3.0.0.
336 */
337extern DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec);
338
339
340/**
341 * Open a specific audio device.
342 *
343 * You can open both output and capture devices through this function. Output
344 * devices will take data from bound audio streams, mix it, and send it to the
345 * hardware. Capture devices will feed any bound audio streams with a copy of
346 * any incoming data.
347 *
348 * An opened audio device starts out with no audio streams bound. To start
349 * audio playing, bind a stream and supply audio data to it. Unlike SDL2,
350 * there is no audio callback; you only bind audio streams and make sure they
351 * have data flowing into them (although, as an optional feature, each audio
352 * stream may have its own callback, which can be used to simulate SDL2's
353 * semantics).
354 *
355 * If you don't care about opening a specific device, pass a `devid` of either
356 * `SDL_AUDIO_DEVICE_DEFAULT_OUTPUT` or `SDL_AUDIO_DEVICE_DEFAULT_CAPTURE`. In
357 * this case, SDL will try to pick the most reasonable default, and may also
358 * switch between physical devices seamlessly later, if the most reasonable
359 * default changes during the lifetime of this opened device (user changed the
360 * default in the OS's system preferences, the default got unplugged so the
361 * system jumped to a new default, the user plugged in headphones on a mobile
362 * device, etc). Unless you have a good reason to choose a specific device,
363 * this is probably what you want.
364 *
365 * You may request a specific format for the audio device, but there is no
366 * promise the device will honor that request for several reasons. As such,
367 * it's only meant to be a hint as to what data your app will provide. Audio
368 * streams will accept data in whatever format you specify and manage
369 * conversion for you as appropriate. SDL_GetAudioDeviceFormat can tell you
370 * the preferred format for the device before opening and the actual format
371 * the device is using after opening.
372 *
373 * It's legal to open the same device ID more than once; each successful open
374 * will generate a new logical SDL_AudioDeviceID that is managed separately
375 * from others on the same physical device. This allows libraries to open a
376 * device separately from the main app and bind its own streams without
377 * conflicting.
378 *
379 * It is also legal to open a device ID returned by a previous call to this
380 * function; doing so just creates another logical device on the same physical
381 * device. This may be useful for making logical groupings of audio streams.
382 *
383 * This function returns the opened device ID on success. This is a new,
384 * unique SDL_AudioDeviceID that represents a logical device.
385 *
386 * Some backends might offer arbitrary devices (for example, a networked audio
387 * protocol that can connect to an arbitrary server). For these, as a change
388 * from SDL2, you should open a default device ID and use an SDL hint to
389 * specify the target if you care, or otherwise let the backend figure out a
390 * reasonable default. Most backends don't offer anything like this, and often
391 * this would be an end user setting an environment variable for their custom
392 * need, and not something an application should specifically manage.
393 *
394 * When done with an audio device, possibly at the end of the app's life, one
395 * should call SDL_CloseAudioDevice() on the returned device id.
396 *
397 * \param devid the device instance id to open, or
398 * SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
399 * SDL_AUDIO_DEVICE_DEFAULT_CAPTURE for the most reasonable
400 * default device.
401 * \param spec the requested device configuration. Can be NULL to use
402 * reasonable defaults.
403 * \returns The device ID on success, 0 on error; call SDL_GetError() for more
404 * information.
405 *
406 * \threadsafety It is safe to call this function from any thread.
407 *
408 * \since This function is available since SDL 3.0.0.
409 *
410 * \sa SDL_CloseAudioDevice
411 * \sa SDL_GetAudioDeviceFormat
412 */
413extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec);
414
415/**
416 * Use this function to pause audio playback on a specified device.
417 *
418 * This function pauses audio processing for a given device. Any bound audio
419 * streams will not progress, and no audio will be generated. Pausing one
420 * device does not prevent other unpaused devices from running.
421 *
422 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
423 * has to bind a stream before any audio will flow. Pausing a paused device is
424 * a legal no-op.
425 *
426 * Pausing a device can be useful to halt all audio without unbinding all the
427 * audio streams. This might be useful while a game is paused, or a level is
428 * loading, etc.
429 *
430 * Physical devices can not be paused or unpaused, only logical devices
431 * created through SDL_OpenAudioDevice() can be.
432 *
433 * \param dev a device opened by SDL_OpenAudioDevice()
434 * \returns 0 on success or a negative error code on failure; call
435 * SDL_GetError() for more information.
436 *
437 * \threadsafety It is safe to call this function from any thread.
438 *
439 * \since This function is available since SDL 3.0.0.
440 *
441 * \sa SDL_ResumeAudioDevice
442 * \sa SDL_IsAudioDevicePaused
443 */
444extern DECLSPEC int SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev);
445
446/**
447 * Use this function to unpause audio playback on a specified device.
448 *
449 * This function unpauses audio processing for a given device that has
450 * previously been paused with SDL_PauseAudioDevice(). Once unpaused, any
451 * bound audio streams will begin to progress again, and audio can be
452 * generated.
453 *
454 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
455 * has to bind a stream before any audio will flow. Unpausing an unpaused
456 * device is a legal no-op.
457 *
458 * Physical devices can not be paused or unpaused, only logical devices
459 * created through SDL_OpenAudioDevice() can be.
460 *
461 * \param dev a device opened by SDL_OpenAudioDevice()
462 * \returns 0 on success or a negative error code on failure; call
463 * SDL_GetError() for more information.
464 *
465 * \threadsafety It is safe to call this function from any thread.
466 *
467 * \since This function is available since SDL 3.0.0.
468 *
469 * \sa SDL_ResumeAudioDevice
470 * \sa SDL_IsAudioDevicePaused
471 */
472extern DECLSPEC int SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev);
473
474/**
475 * Use this function to query if an audio device is paused.
476 *
477 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
478 * has to bind a stream before any audio will flow.
479 *
480 * Physical devices can not be paused or unpaused, only logical devices
481 * created through SDL_OpenAudioDevice() can be. Physical and invalid device
482 * IDs will report themselves as unpaused here.
483 *
484 * \param dev a device opened by SDL_OpenAudioDevice()
485 * \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise.
486 *
487 * \threadsafety It is safe to call this function from any thread.
488 *
489 * \since This function is available since SDL 3.0.0.
490 *
491 * \sa SDL_PauseAudioDevice
492 * \sa SDL_ResumeAudioDevice
493 * \sa SDL_IsAudioDevicePaused
494 */
496
497/**
498 * Close a previously-opened audio device.
499 *
500 * The application should close open audio devices once they are no longer
501 * needed.
502 *
503 * This function may block briefly while pending audio data is played by the
504 * hardware, so that applications don't drop the last buffer of data they
505 * supplied if terminating immediately afterwards.
506 *
507 * \param devid an audio device id previously returned by
508 * SDL_OpenAudioDevice()
509 *
510 * \threadsafety It is safe to call this function from any thread.
511 *
512 * \since This function is available since SDL 3.0.0.
513 *
514 * \sa SDL_OpenAudioDevice
515 */
516extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
517
518/**
519 * Bind a list of audio streams to an audio device.
520 *
521 * Audio data will flow through any bound streams. For an output device, data
522 * for all bound streams will be mixed together and fed to the device. For a
523 * capture device, a copy of recorded data will be provided to each bound
524 * stream.
525 *
526 * Audio streams can only be bound to an open device. This operation is
527 * atomic--all streams bound in the same call will start processing at the
528 * same time, so they can stay in sync. Also: either all streams will be bound
529 * or none of them will be.
530 *
531 * It is an error to bind an already-bound stream; it must be explicitly
532 * unbound first.
533 *
534 * Binding a stream to a device will set its output format for output devices,
535 * and its input format for capture devices, so they match the device's
536 * settings. The caller is welcome to change the other end of the stream's
537 * format at any time.
538 *
539 * \param devid an audio device to bind a stream to.
540 * \param streams an array of audio streams to unbind.
541 * \param num_streams Number streams listed in the `streams` array.
542 * \returns 0 on success, -1 on error; call SDL_GetError() for more
543 * information.
544 *
545 * \threadsafety It is safe to call this function from any thread.
546 *
547 * \since This function is available since SDL 3.0.0.
548 *
549 * \sa SDL_BindAudioStreams
550 * \sa SDL_UnbindAudioStreams
551 * \sa SDL_UnbindAudioStream
552 * \sa SDL_GetAudioStreamBinding
553 */
554extern DECLSPEC int SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams);
555
556/**
557 * Bind a single audio stream to an audio device.
558 *
559 * This is a convenience function, equivalent to calling
560 * `SDL_BindAudioStreams(devid, &stream, 1)`.
561 *
562 * \param devid an audio device to bind a stream to.
563 * \param stream an audio stream to bind to a device.
564 * \returns 0 on success, -1 on error; call SDL_GetError() for more
565 * information.
566 *
567 * \threadsafety It is safe to call this function from any thread.
568 *
569 * \since This function is available since SDL 3.0.0.
570 *
571 * \sa SDL_BindAudioStreams
572 * \sa SDL_UnbindAudioStreams
573 * \sa SDL_UnbindAudioStream
574 * \sa SDL_GetAudioStreamBinding
575 */
576extern DECLSPEC int SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream);
577
578/**
579 * Unbind a list of audio streams from their audio devices.
580 *
581 * The streams being unbound do not all have to be on the same device. All
582 * streams on the same device will be unbound atomically (data will stop
583 * flowing through them all unbound streams on the same device at the same
584 * time).
585 *
586 * Unbinding a stream that isn't bound to a device is a legal no-op.
587 *
588 * \param streams an array of audio streams to unbind.
589 * \param num_streams Number streams listed in the `streams` array.
590 *
591 * \threadsafety It is safe to call this function from any thread.
592 *
593 * \since This function is available since SDL 3.0.0.
594 *
595 * \sa SDL_BindAudioStreams
596 * \sa SDL_BindAudioStream
597 * \sa SDL_UnbindAudioStream
598 * \sa SDL_GetAudioStreamBinding
599 */
600extern DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams);
601
602/**
603 * Unbind a single audio stream from its audio device.
604 *
605 * This is a convenience function, equivalent to calling
606 * `SDL_UnbindAudioStreams(&stream, 1)`.
607 *
608 * \param stream an audio stream to unbind from a device.
609 *
610 * \threadsafety It is safe to call this function from any thread.
611 *
612 * \since This function is available since SDL 3.0.0.
613 *
614 * \sa SDL_BindAudioStream
615 * \sa SDL_BindAudioStreams
616 * \sa SDL_UnbindAudioStreams
617 * \sa SDL_GetAudioStreamBinding
618 */
619extern DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream);
620
621/**
622 * Query an audio stream for its currently-bound device.
623 *
624 * This reports the audio device that an audio stream is currently bound to.
625 *
626 * If not bound, or invalid, this returns zero, which is not a valid device
627 * ID.
628 *
629 * \param stream the audio stream to query.
630 * \returns The bound audio device, or 0 if not bound or invalid.
631 *
632 * \threadsafety It is safe to call this function from any thread.
633 *
634 * \since This function is available since SDL 3.0.0.
635 *
636 * \sa SDL_BindAudioStream
637 * \sa SDL_BindAudioStreams
638 * \sa SDL_UnbindAudioStream
639 * \sa SDL_UnbindAudioStreams
640 */
642
643
644/**
645 * Create a new audio stream.
646 *
647 * \param src_spec The format details of the input audio
648 * \param dst_spec The format details of the output audio
649 * \returns 0 on success, or -1 on error.
650 *
651 * \threadsafety It is safe to call this function from any thread.
652 *
653 * \since This function is available since SDL 3.0.0.
654 *
655 * \sa SDL_PutAudioStreamData
656 * \sa SDL_GetAudioStreamData
657 * \sa SDL_GetAudioStreamAvailable
658 * \sa SDL_FlushAudioStream
659 * \sa SDL_ClearAudioStream
660 * \sa SDL_ChangeAudioStreamOutput
661 * \sa SDL_DestroyAudioStream
662 */
663extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec);
664
665
666/**
667 * Query the current format of an audio stream.
668 *
669 * \param stream the SDL_AudioStream to query.
670 * \param src_spec Where to store the input audio format; ignored if NULL.
671 * \param dst_spec Where to store the output audio format; ignored if NULL.
672 * \returns 0 on success, or -1 on error.
673 *
674 * \threadsafety It is safe to call this function from any thread, as it holds
675 * a stream-specific mutex while running.
676 *
677 * \since This function is available since SDL 3.0.0.
678 */
679extern DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream,
680 SDL_AudioSpec *src_spec,
681 SDL_AudioSpec *dst_spec);
682
683/**
684 * Change the input and output formats of an audio stream.
685 *
686 * Future calls to and SDL_GetAudioStreamAvailable and SDL_GetAudioStreamData
687 * will reflect the new format, and future calls to SDL_PutAudioStreamData
688 * must provide data in the new input formats.
689 *
690 * \param stream The stream the format is being changed
691 * \param src_spec The new format of the audio input; if NULL, it is not
692 * changed.
693 * \param dst_spec The new format of the audio output; if NULL, it is not
694 * changed.
695 * \returns 0 on success, or -1 on error.
696 *
697 * \threadsafety It is safe to call this function from any thread, as it holds
698 * a stream-specific mutex while running.
699 *
700 * \since This function is available since SDL 3.0.0.
701 *
702 * \sa SDL_GetAudioStreamFormat
703 * \sa SDL_PutAudioStreamData
704 * \sa SDL_GetAudioStreamData
705 * \sa SDL_GetAudioStreamAvailable
706 */
707extern DECLSPEC int SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream,
708 const SDL_AudioSpec *src_spec,
709 const SDL_AudioSpec *dst_spec);
710
711/**
712 * Add data to be converted/resampled to the stream.
713 *
714 * This data must match the format/channels/samplerate specified in the latest
715 * call to SDL_SetAudioStreamFormat, or the format specified when creating the
716 * stream if it hasn't been changed.
717 *
718 * Note that this call simply queues unconverted data for later. This is
719 * different than SDL2, where data was converted during the Put call and the
720 * Get call would just dequeue the previously-converted data.
721 *
722 * \param stream The stream the audio data is being added to
723 * \param buf A pointer to the audio data to add
724 * \param len The number of bytes to write to the stream
725 * \returns 0 on success or a negative error code on failure; call
726 * SDL_GetError() for more information.
727 *
728 * \threadsafety It is safe to call this function from any thread, but if the
729 * stream has a callback set, the caller might need to manage
730 * extra locking.
731 *
732 * \since This function is available since SDL 3.0.0.
733 *
734 * \sa SDL_CreateAudioStream
735 * \sa SDL_GetAudioStreamData
736 * \sa SDL_GetAudioStreamAvailable
737 * \sa SDL_FlushAudioStream
738 * \sa SDL_ClearAudioStream
739 * \sa SDL_DestroyAudioStream
740 */
741extern DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len);
742
743/**
744 * Get converted/resampled data from the stream.
745 *
746 * The input/output data format/channels/samplerate is specified when creating
747 * the stream, and can be changed after creation by calling
748 * SDL_SetAudioStreamFormat.
749 *
750 * Note that any conversion and resampling necessary is done during this call,
751 * and SDL_PutAudioStreamData simply queues unconverted data for later. This
752 * is different than SDL2, where that work was done while inputting new data
753 * to the stream and requesting the output just copied the converted data.
754 *
755 * \param stream The stream the audio is being requested from
756 * \param buf A buffer to fill with audio data
757 * \param len The maximum number of bytes to fill
758 * \returns the number of bytes read from the stream, or -1 on error
759 *
760 * \threadsafety It is safe to call this function from any thread, but if the
761 * stream has a callback set, the caller might need to manage
762 * extra locking.
763 *
764 * \since This function is available since SDL 3.0.0.
765 *
766 * \sa SDL_CreateAudioStream
767 * \sa SDL_PutAudioStreamData
768 * \sa SDL_GetAudioStreamAvailable
769 * \sa SDL_SetAudioStreamFormat
770 * \sa SDL_FlushAudioStream
771 * \sa SDL_ClearAudioStream
772 * \sa SDL_DestroyAudioStream
773 */
774extern DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, void *buf, int len);
775
776/**
777 * Get the number of converted/resampled bytes available.
778 *
779 * The stream may be buffering data behind the scenes until it has enough to
780 * resample correctly, so this number might be lower than what you expect, or
781 * even be zero. Add more data or flush the stream if you need the data now.
782 *
783 * If the stream has so much data that it would overflow an int, the return
784 * value is clamped to a maximum value, but no queued data is lost; if there
785 * are gigabytes of data queued, the app might need to read some of it with
786 * SDL_GetAudioStreamData before this function's return value is no longer
787 * clamped.
788 *
789 * \param stream The audio stream to query
790 * \returns the number of converted/resampled bytes available.
791 *
792 * \threadsafety It is safe to call this function from any thread.
793 *
794 * \since This function is available since SDL 3.0.0.
795 *
796 * \sa SDL_CreateAudioStream
797 * \sa SDL_PutAudioStreamData
798 * \sa SDL_GetAudioStreamData
799 * \sa SDL_FlushAudioStream
800 * \sa SDL_ClearAudioStream
801 * \sa SDL_DestroyAudioStream
802 */
803extern DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *stream);
804
805/**
806 * Tell the stream that you're done sending data, and anything being buffered
807 * should be converted/resampled and made available immediately.
808 *
809 * It is legal to add more data to a stream after flushing, but there will be
810 * audio gaps in the output. Generally this is intended to signal the end of
811 * input, so the complete output becomes available.
812 *
813 * \param stream The audio stream to flush
814 * \returns 0 on success or a negative error code on failure; call
815 * SDL_GetError() for more information.
816 *
817 * \threadsafety It is safe to call this function from any thread.
818 *
819 * \since This function is available since SDL 3.0.0.
820 *
821 * \sa SDL_CreateAudioStream
822 * \sa SDL_PutAudioStreamData
823 * \sa SDL_GetAudioStreamData
824 * \sa SDL_GetAudioStreamAvailable
825 * \sa SDL_ClearAudioStream
826 * \sa SDL_DestroyAudioStream
827 */
828extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
829
830/**
831 * Clear any pending data in the stream without converting it
832 *
833 * \param stream The audio stream to clear
834 * \returns 0 on success or a negative error code on failure; call
835 * SDL_GetError() for more information.
836 *
837 * \threadsafety It is safe to call this function from any thread.
838 *
839 * \since This function is available since SDL 3.0.0.
840 *
841 * \sa SDL_CreateAudioStream
842 * \sa SDL_PutAudioStreamData
843 * \sa SDL_GetAudioStreamData
844 * \sa SDL_GetAudioStreamAvailable
845 * \sa SDL_FlushAudioStream
846 * \sa SDL_DestroyAudioStream
847 */
848extern DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
849
850/**
851 * Lock an audio stream for serialized access.
852 *
853 * Each SDL_AudioStream has an internal mutex it uses to protect its data
854 * structures from threading conflicts. This function allows an app to lock
855 * that mutex, which could be useful if registering callbacks on this stream.
856 *
857 * One does not need to lock a stream to use in it most cases, as the stream
858 * manages this lock internally. However, this lock is held during callbacks,
859 * which may run from arbitrary threads at any time, so if an app needs to
860 * protect shared data during those callbacks, locking the stream guarantees
861 * that the callback is not running while the lock is held.
862 *
863 * As this is just a wrapper over SDL_LockMutex for an internal lock, it has
864 * all the same attributes (recursive locks are allowed, etc).
865 *
866 * \param stream The audio stream to lock.
867 * \returns 0 on success or a negative error code on failure; call
868 * SDL_GetError() for more information.
869 *
870 * \threadsafety It is safe to call this function from any thread.
871 *
872 * \since This function is available since SDL 3.0.0.
873 *
874 * \sa SDL_UnlockAudioStream
875 * \sa SDL_SetAudioStreamPutCallback
876 * \sa SDL_SetAudioStreamGetCallback
877 */
878extern DECLSPEC int SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream);
879
880
881/**
882 * Unlock an audio stream for serialized access.
883 *
884 * This unlocks an audio stream after a call to SDL_LockAudioStream.
885 *
886 * \param stream The audio stream to unlock.
887 * \returns 0 on success or a negative error code on failure; call
888 * SDL_GetError() for more information.
889 *
890 * \threadsafety You should only call this from the same thread that
891 * previously called SDL_LockAudioStream.
892 *
893 * \since This function is available since SDL 3.0.0.
894 *
895 * \sa SDL_LockAudioStream
896 * \sa SDL_SetAudioStreamPutCallback
897 * \sa SDL_SetAudioStreamGetCallback
898 */
899extern DECLSPEC int SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream);
900
901/**
902 * A callback that fires when data passes through an SDL_AudioStream.
903 *
904 * Apps can (optionally) register a callback with an audio stream that
905 * is called when data is added with SDL_PutAudioStreamData, or requested
906 * with SDL_GetAudioStreamData. These callbacks may run from any
907 * thread, so if you need to protect shared data, you should use
908 * SDL_LockAudioStream to serialize access; this lock will be held by
909 * before your callback is called, so your callback does not need to
910 * manage the lock explicitly.
911 *
912 * \param stream The SDL audio stream associated with this callback.
913 * \param approx_request The _approximate_ amout of data, in bytes, that is requested.
914 * This might be slightly overestimated due to buffering or
915 * resampling, and may change from call to call anyhow.
916 * \param userdata An opaque pointer provided by the app for their personal use.
917 */
918typedef void (SDLCALL *SDL_AudioStreamRequestCallback)(SDL_AudioStream *stream, int approx_request, void *userdata);
919
920/**
921 * Set a callback that runs when data is requested from an audio stream.
922 *
923 * This callback is called _before_ data is obtained from the stream, giving
924 * the callback the chance to add more on-demand.
925 *
926 * The callback can (optionally) call SDL_PutAudioStreamData() to add more
927 * audio to the stream during this call; if needed, the request that triggered
928 * this callback will obtain the new data immediately.
929 *
930 * The callback's `approx_request` argument is roughly how many bytes of
931 * _unconverted_ data (in the stream's input format) is needed by the caller,
932 * although this may overestimate a little for safety. This takes into account
933 * how much is already in the stream and only asks for any extra necessary to
934 * resolve the request, which means the callback may be asked for zero bytes,
935 * and a different amount on each call.
936 *
937 * The callback is not required to supply exact amounts; it is allowed to
938 * supply too much or too little or none at all. The caller will get what's
939 * available, up to the amount they requested, regardless of this callback's
940 * outcome.
941 *
942 * Clearing or flushing an audio stream does not call this callback.
943 *
944 * This function obtains the stream's lock, which means any existing callback
945 * (get or put) in progress will finish running before setting the new
946 * callback.
947 *
948 * Setting a NULL function turns off the callback.
949 *
950 * \param stream the audio stream to set the new callback on.
951 * \param callback the new callback function to call when data is added to the
952 * stream.
953 * \param userdata an opaque pointer provided to the callback for its own
954 * personal use.
955 * \returns 0 on success, -1 on error. This only fails if `stream` is NULL.
956 *
957 * \threadsafety It is safe to call this function from any thread.
958 *
959 * \since This function is available since SDL 3.0.0.
960 *
961 * \sa SDL_SetAudioStreamPutCallback
962 */
963extern DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamRequestCallback callback, void *userdata);
964
965/**
966 * Set a callback that runs when data is added to an audio stream.
967 *
968 * This callback is called _after_ the data is added to the stream, giving the
969 * callback the chance to obtain it immediately.
970 *
971 * The callback can (optionally) call SDL_GetAudioStreamData() to obtain audio
972 * from the stream during this call.
973 *
974 * The callback's `approx_request` argument is how many bytes of _converted_
975 * data (in the stream's output format) was provided by the caller, although
976 * this may underestimate a little for safety. This value might be less than
977 * what is currently available in the stream, if data was already there, and
978 * might be less than the caller provided if the stream needs to keep a buffer
979 * to aid in resampling. Which means the callback may be provided with zero
980 * bytes, and a different amount on each call.
981 *
982 * The callback may call SDL_GetAudioStreamAvailable to see the total amount
983 * currently available to read from the stream, instead of the total provided
984 * by the current call.
985 *
986 * The callback is not required to obtain all data. It is allowed to read less
987 * or none at all. Anything not read now simply remains in the stream for
988 * later access.
989 *
990 * Clearing or flushing an audio stream does not call this callback.
991 *
992 * This function obtains the stream's lock, which means any existing callback
993 * (get or put) in progress will finish running before setting the new
994 * callback.
995 *
996 * Setting a NULL function turns off the callback.
997 *
998 * \param stream the audio stream to set the new callback on.
999 * \param callback the new callback function to call when data is added to the
1000 * stream.
1001 * \param userdata an opaque pointer provided to the callback for its own
1002 * personal use.
1003 * \returns 0 on success, -1 on error. This only fails if `stream` is NULL.
1004 *
1005 * \threadsafety It is safe to call this function from any thread.
1006 *
1007 * \since This function is available since SDL 3.0.0.
1008 *
1009 * \sa SDL_SetAudioStreamGetCallback
1010 */
1011extern DECLSPEC int SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamRequestCallback callback, void *userdata);
1012
1013
1014/**
1015 * Free an audio stream
1016 *
1017 * \param stream The audio stream to free
1018 *
1019 * \threadsafety It is safe to call this function from any thread.
1020 *
1021 * \since This function is available since SDL 3.0.0.
1022 *
1023 * \sa SDL_CreateAudioStream
1024 * \sa SDL_PutAudioStreamData
1025 * \sa SDL_GetAudioStreamData
1026 * \sa SDL_GetAudioStreamAvailable
1027 * \sa SDL_FlushAudioStream
1028 * \sa SDL_ClearAudioStream
1029 */
1030extern DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream);
1031
1032
1033/**
1034 * Convenience function to create and bind an audio stream in one step.
1035 *
1036 * This manages the creation of an audio stream, and setting its format
1037 * correctly to match both the app and the audio device's needs. This is
1038 * optional, but slightly less cumbersome to set up for a common use case.
1039 *
1040 * The `spec` parameter represents the app's side of the audio stream. That
1041 * is, for recording audio, this will be the output format, and for playing
1042 * audio, this will be the input format. This function will set the other side
1043 * of the audio stream to the device's format.
1044 *
1045 * \param devid an audio device to bind a stream to. This must be an opened
1046 * device, and can not be zero.
1047 * \param spec the audio stream's input format
1048 * \returns a bound audio stream on success, ready to use. NULL on error; call
1049 * SDL_GetError() for more information.
1050 *
1051 * \threadsafety It is safe to call this function from any thread.
1052 *
1053 * \since This function is available since SDL 3.0.0.
1054 *
1055 * \sa SDL_BindAudioStreams
1056 * \sa SDL_UnbindAudioStreams
1057 * \sa SDL_UnbindAudioStream
1058 */
1060
1061
1062/**
1063 * Load the audio data of a WAVE file into memory.
1064 *
1065 * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
1066 * be valid pointers. The entire data portion of the file is then loaded into
1067 * memory and decoded if necessary.
1068 *
1069 * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
1070 * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
1071 * A-law and mu-law (8 bits). Other formats are currently unsupported and
1072 * cause an error.
1073 *
1074 * If this function succeeds, the return value is zero and the pointer to the
1075 * audio data allocated by the function is written to `audio_buf` and its
1076 * length in bytes to `audio_len`. The SDL_AudioSpec members `freq`,
1077 * `channels`, and `format` are set to the values of the audio data in the
1078 * buffer. The `samples` member is set to a sane default and all others are
1079 * set to zero.
1080 *
1081 * It's necessary to use SDL_free() to free the audio data returned in
1082 * `audio_buf` when it is no longer used.
1083 *
1084 * Because of the underspecification of the .WAV format, there are many
1085 * problematic files in the wild that cause issues with strict decoders. To
1086 * provide compatibility with these files, this decoder is lenient in regards
1087 * to the truncation of the file, the fact chunk, and the size of the RIFF
1088 * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
1089 * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
1090 * tune the behavior of the loading process.
1091 *
1092 * Any file that is invalid (due to truncation, corruption, or wrong values in
1093 * the headers), too big, or unsupported causes an error. Additionally, any
1094 * critical I/O error from the data source will terminate the loading process
1095 * with an error. The function returns NULL on error and in all cases (with
1096 * the exception of `src` being NULL), an appropriate error message will be
1097 * set.
1098 *
1099 * It is required that the data source supports seeking.
1100 *
1101 * Example:
1102 *
1103 * ```c
1104 * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
1105 * ```
1106 *
1107 * Note that the SDL_LoadWAV function does this same thing for you, but in a
1108 * less messy way:
1109 *
1110 * ```c
1111 * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
1112 * ```
1113 *
1114 * \param src The data source for the WAVE data
1115 * \param freesrc If SDL_TRUE, calls SDL_RWclose() on `src` before returning,
1116 * even in the case of an error
1117 * \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE
1118 * data's format details on successful return
1119 * \param audio_buf A pointer filled with the audio data, allocated by the
1120 * function
1121 * \param audio_len A pointer filled with the length of the audio data buffer
1122 * in bytes
1123 * \returns This function, if successfully called, returns 0. `audio_buf` will
1124 * be filled with a pointer to an allocated buffer containing the
1125 * audio data, and `audio_len` is filled with the length of that
1126 * audio buffer in bytes.
1127 *
1128 * This function returns -1 if the .WAV file cannot be opened, uses
1129 * an unknown data format, or is corrupt; call SDL_GetError() for
1130 * more information.
1131 *
1132 * When the application is done with the data returned in
1133 * `audio_buf`, it should call SDL_free() to dispose of it.
1134 *
1135 * \threadsafety It is safe to call this function from any thread.
1136 *
1137 * \since This function is available since SDL 3.0.0.
1138 *
1139 * \sa SDL_free
1140 * \sa SDL_LoadWAV
1141 */
1142extern DECLSPEC int SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, SDL_bool freesrc,
1143 SDL_AudioSpec * spec, Uint8 ** audio_buf,
1144 Uint32 * audio_len);
1145
1146/**
1147 * Loads a WAV from a file path.
1148 *
1149 * This is a convenience function that is effectively the same as:
1150 *
1151 * ```c
1152 * SDL_LoadWAV_RW(SDL_RWFromFile(path, "rb"), 1, spec, audio_buf, audio_len);
1153 * ```
1154 *
1155 * Note that in SDL2, this was a preprocessor macro and not a real function.
1156 *
1157 * \param path The file path of the WAV file to open.
1158 * \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE
1159 * data's format details on successful return.
1160 * \param audio_buf A pointer filled with the audio data, allocated by the
1161 * function.
1162 * \param audio_len A pointer filled with the length of the audio data buffer
1163 * in bytes
1164 * \returns This function, if successfully called, returns 0. `audio_buf` will
1165 * be filled with a pointer to an allocated buffer containing the
1166 * audio data, and `audio_len` is filled with the length of that
1167 * audio buffer in bytes.
1168 *
1169 * This function returns -1 if the .WAV file cannot be opened, uses
1170 * an unknown data format, or is corrupt; call SDL_GetError() for
1171 * more information.
1172 *
1173 * When the application is done with the data returned in
1174 * `audio_buf`, it should call SDL_free() to dispose of it.
1175 *
1176 * \threadsafety It is safe to call this function from any thread.
1177 *
1178 * \since This function is available since SDL 3.0.0.
1179 *
1180 * \sa SDL_free
1181 * \sa SDL_LoadWAV_RW
1182 */
1183extern DECLSPEC int SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * spec,
1184 Uint8 ** audio_buf, Uint32 * audio_len);
1185
1186
1187
1188#define SDL_MIX_MAXVOLUME 128
1189
1190/**
1191 * Mix audio data in a specified format.
1192 *
1193 * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
1194 * it into `dst`, performing addition, volume adjustment, and overflow
1195 * clipping. The buffer pointed to by `dst` must also be `len` bytes of
1196 * `format` data.
1197 *
1198 * This is provided for convenience -- you can mix your own audio data.
1199 *
1200 * Do not use this function for mixing together more than two streams of
1201 * sample data. The output from repeated application of this function may be
1202 * distorted by clipping, because there is no accumulator with greater range
1203 * than the input (not to mention this being an inefficient way of doing it).
1204 *
1205 * It is a common misconception that this function is required to write audio
1206 * data to an output stream in an audio callback. While you can do that,
1207 * SDL_MixAudioFormat() is really only needed when you're mixing a single
1208 * audio stream with a volume adjustment.
1209 *
1210 * \param dst the destination for the mixed audio
1211 * \param src the source audio buffer to be mixed
1212 * \param format the SDL_AudioFormat structure representing the desired audio
1213 * format
1214 * \param len the length of the audio buffer in bytes
1215 * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
1216 * for full audio volume
1217 * \returns 0 on success or a negative error code on failure; call
1218 * SDL_GetError() for more information.
1219 *
1220 * \threadsafety It is safe to call this function from any thread.
1221 *
1222 * \since This function is available since SDL 3.0.0.
1223 */
1224extern DECLSPEC int SDLCALL SDL_MixAudioFormat(Uint8 * dst,
1225 const Uint8 * src,
1226 SDL_AudioFormat format,
1227 Uint32 len, int volume);
1228
1229/**
1230 * Convert some audio data of one format to another format.
1231 *
1232 * Please note that this function is for convenience, but should not be used
1233 * to resample audio in blocks, as it will introduce audio artifacts on the
1234 * boundaries. You should only use this function if you are converting audio
1235 * data in its entirety in one call. If you want to convert audio in smaller
1236 * chunks, use an SDL_AudioStream, which is designed for this situation.
1237 *
1238 * Internally, this function creates and destroys an SDL_AudioStream on each
1239 * use, so it's also less efficient than using one directly, if you need to
1240 * convert multiple times.
1241 *
1242 * \param src_spec The format details of the input audio
1243 * \param src_data The audio data to be converted
1244 * \param src_len The len of src_data
1245 * \param dst_spec The format details of the output audio
1246 * \param dst_data Will be filled with a pointer to converted audio data,
1247 * which should be freed with SDL_free(). On error, it will be
1248 * NULL.
1249 * \param dst_len Will be filled with the len of dst_data
1250 * \returns 0 on success or a negative error code on failure; call
1251 * SDL_GetError() for more information.
1252 *
1253 * \threadsafety It is safe to call this function from any thread.
1254 *
1255 * \since This function is available since SDL 3.0.0.
1256 *
1257 * \sa SDL_CreateAudioStream
1258 */
1259extern DECLSPEC int SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec,
1260 const Uint8 *src_data,
1261 int src_len,
1262 const SDL_AudioSpec *dst_spec,
1263 Uint8 **dst_data,
1264 int *dst_len);
1265
1266
1267/**
1268 * Get the appropriate memset value for silencing an audio format.
1269 *
1270 * The value returned by this function can be used as the second argument to
1271 * memset (or SDL_memset) to set an audio buffer in a specific format to
1272 * silence.
1273 *
1274 * \param format the audio data format to query.
1275 * \returns A byte value that can be passed to memset.
1276 *
1277 * \threadsafety It is safe to call this function from any thread.
1278 *
1279 * \since This function is available since SDL 3.0.0.
1280 */
1281extern DECLSPEC int SDLCALL SDL_GetSilenceValueForFormat(SDL_AudioFormat format);
1282
1283
1284/* Ends C function definitions when using C++ */
1285#ifdef __cplusplus
1286}
1287#endif
1288#include <SDL3/SDL_close_code.h>
1289
1290#endif /* SDL_audio_h_ */
int SDL_UnlockAudioStream(SDL_AudioStream *stream)
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)
int SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec)
struct SDL_AudioStream SDL_AudioStream
Definition: SDL_audio.h:169
SDL_bool SDL_IsAudioDevicePaused(SDL_AudioDeviceID dev)
Uint16 SDL_AudioFormat
Audio format flags.
Definition: SDL_audio.h:75
int SDL_FlushAudioStream(SDL_AudioStream *stream)
int SDL_GetNumAudioDrivers(void)
char * SDL_GetAudioDeviceName(SDL_AudioDeviceID devid)
Uint32 SDL_AudioDeviceID
Definition: SDL_audio.h:145
int 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)
int SDL_GetSilenceValueForFormat(SDL_AudioFormat format)
const char * SDL_GetCurrentAudioDriver(void)
int SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream)
int SDL_PauseAudioDevice(SDL_AudioDeviceID dev)
int SDL_GetAudioStreamAvailable(SDL_AudioStream *stream)
SDL_AudioDeviceID * SDL_GetAudioCaptureDevices(int *count)
int SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
int SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len)
int SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams)
void SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams)
void SDL_DestroyAudioStream(SDL_AudioStream *stream)
int SDL_LockAudioStream(SDL_AudioStream *stream)
void SDL_CloseAudioDevice(SDL_AudioDeviceID devid)
int SDL_GetAudioStreamData(SDL_AudioStream *stream, void *buf, int len)
int SDL_LoadWAV_RW(SDL_RWops *src, SDL_bool freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
SDL_AudioDeviceID SDL_GetAudioStreamBinding(SDL_AudioStream *stream)
int SDL_ResumeAudioDevice(SDL_AudioDeviceID dev)
int SDL_ClearAudioStream(SDL_AudioStream *stream)
SDL_AudioDeviceID * SDL_GetAudioOutputDevices(int *count)
int SDL_MixAudioFormat(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, int volume)
void(* SDL_AudioStreamRequestCallback)(SDL_AudioStream *stream, int approx_request, void *userdata)
Definition: SDL_audio.h:918
SDL_AudioDeviceID SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec)
int SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec)
int SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec)
int SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamRequestCallback callback, void *userdata)
SDL_AudioStream * SDL_CreateAndBindAudioStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec)
int SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamRequestCallback callback, void *userdata)
Functions for reading and writing endian-specific values.
Functions to provide thread synchronization primitives.
This is a general header that includes C language support.
uint8_t Uint8
Definition: SDL_stdinc.h:147
uint16_t Uint16
Definition: SDL_stdinc.h:159
SDL_bool
Definition: SDL_stdinc.h:130
uint32_t Uint32
Definition: SDL_stdinc.h:171
Header for the SDL thread management routines.
SDL_AudioFormat format
Definition: SDL_audio.h:152