Revert "audio: Added SDL_SetAudioIterationCallbacks()."

This reverts commit 608f706a95.

Didn't end up using this in SDL3_mixer, and it's a super-awkward API if we
don't need it.

I _might_ bite the bullet and let people lock a physical audio device, though,
as I could see that being useful but less awkward for the same reasons I
originally wanted it.
This commit is contained in:
Ryan C. Gordon
2025-07-25 01:29:13 -04:00
parent e5d57d8ad6
commit c80d6954cb
6 changed files with 1 additions and 127 deletions

View File

@@ -2035,85 +2035,6 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream)
*/
extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata);
/**
* A callback that fires around an audio device's processing work.
*
* This callback fires when a logical audio device is about to start accessing
* its bound audio streams, and fires again when it has finished accessing
* them. It covers the range of one "iteration" of the audio device.
*
* It can be useful to use this callback to update state that must apply to
* all bound audio streams atomically: to make sure state changes don't happen
* while half of the streams are already processed for the latest audio
* buffer.
*
* This callback should run as quickly as possible and not block for any
* significant time, as this callback delays submission of data to the audio
* device, which can cause audio playback problems. This callback delays all
* audio processing across a single physical audio device: all its logical
* devices and all bound audio streams. Use it carefully.
*
* \param userdata a pointer provided by the app through
* SDL_SetAudioPostmixCallback, for its own use.
* \param devid the audio device this callback is running for.
* \param start true if this is the start of the iteration, false if the end.
*
* \threadsafety This will run from a background thread owned by SDL. The
* application is responsible for locking resources the callback
* touches that need to be protected.
*
* \since This datatype is available since SDL 3.4.0.
*
* \sa SDL_SetAudioIterationCallbacks
*/
typedef void (SDLCALL *SDL_AudioIterationCallback)(void *userdata, SDL_AudioDeviceID devid, bool start);
/**
* Set callbacks that fire around a new iteration of audio device processing.
*
* Two callbacks are provided here: one that runs when a device is about to
* process its bound audio streams, and another that runs when the device has
* finished processing them.
*
* These callbacks 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.
*
* Generally these callbacks are used to apply state that applies to multiple
* bound audio streams, with a guarantee that the audio device's thread isn't
* halfway through processing them. Generally a finer-grained lock through
* SDL_LockAudioStream() is more appropriate.
*
* The callbacks are 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
* function sets the new callback and returns.
*
* Physical devices do not accept these callbacks, only logical devices
* created through SDL_OpenAudioDevice() can be.
*
* Setting a NULL callback function disables any previously-set callback.
* Either callback may be NULL, and the same callback is permitted to be used
* for both.
*
* \param devid the ID of an opened audio device.
* \param start a callback function to be called at the start of an iteration.
* Can be NULL.
* \param end a callback function to be called at the end of an iteration. Can
* be NULL.
* \param userdata app-controlled pointer passed to callback. Can be NULL.
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.4.0.
*/
extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioIterationCallbacks(SDL_AudioDeviceID devid, SDL_AudioIterationCallback start, SDL_AudioIterationCallback end, void *userdata);
/**
* A callback that fires when data is about to be fed to an audio device.
*