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