mirrors/SDL
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> header

Browse Source
This commit is contained in:
Ryan C. Gordon 2023-09-12 14:27:21 -04:00
parent 2de2e9d031
commit a6e52f9e48
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
1 changed files with 21 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
include/SDL3/SDL_audio.h
View File

@ -1143,36 +1143,35 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio
* This is useful for accessing the final mix, perhaps for writing a
* visualizer or applying a final effect to the audio data before playback.
*
* The buffer is the final mix of all bound audio streams on an opened
* device; this callback will fire regularly for any device that is both
* opened and unpaused. If there is no new data to mix, either because no
* streams are bound to the device or all the streams are empty, this
* callback will still fire with the entire buffer set to silence.
* The buffer is the final mix of all bound audio streams on an opened device;
* this callback will fire regularly for any device that is both opened and
* unpaused. If there is no new data to mix, either because no streams are
* bound to the device or all the streams are empty, this callback will still
* fire with the entire buffer set to silence.
*
* This callback is allowed to make changes to the data; the contents of
* the buffer after this call is what is ultimately passed along to the
* hardware.
* This callback is allowed to make changes to the data; the contents of the
* buffer after this call is what is ultimately passed along to the hardware.
*
* The callback is always provided the data in float format (values from
* -1.0f to 1.0f), but the number of channels or sample rate may be
* different than the format the app requested when opening the device; SDL
* might have had to manage a conversion behind the scenes, or the playback
* might have jumped to new physical hardware when a system default changed,
* etc. These details may change between calls. Accordingly, the size of the
* buffer might change between calls as well.
* The callback is always provided the data in float format (values from -1.0f
* to 1.0f), but the number of channels or sample rate may be different than
* the format the app requested when opening the device; SDL might have had to
* manage a conversion behind the scenes, or the playback might have jumped to
* new physical hardware when a system default changed, etc. These details may
* change between calls. Accordingly, the size of the buffer might change
* between calls as well.
*
* This callback can run at any time, and from any thread; if you need to
* serialize access to your app's data, you should provide and use a mutex or
* other synchronization device.
*
* All of this to say: there are specific needs this callback can fulfill,
* but it is not the simplest interface. Apps should generally provide audio
* in their preferred format through an SDL_AudioStream and let SDL handle
* the difference.
* All of this to say: there are specific needs this callback can fulfill, but
* it is not the simplest interface. Apps should generally provide audio in
* their preferred format through an SDL_AudioStream and let SDL handle the
* difference.
*
* This function is extremely time-sensitive; the callback should do the
* least amount of work possible and return as quickly as it can. The longer
* the callback runs, the higher the risk of audio dropouts or other problems.
* This function is extremely time-sensitive; the callback should do the least
* amount of work possible and return as quickly as it can. The longer the
* callback runs, the higher the risk of audio dropouts or other problems.
*
* This function will block until the audio device is in between iterations,
* so any existing callback that might be running will finish before this