From b9bf7ffec755815c95b9d980dffe463f5717d149 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Sat, 28 Aug 2021 18:17:05 +0000
Subject: [PATCH] Sync wiki -> header
---
include/SDL_audio.h | 51 ---------------------------------------------
1 file changed, 51 deletions(-)
diff --git a/include/SDL_audio.h b/include/SDL_audio.h
index 0aa0017648..bf4479d054 100644
--- a/include/SDL_audio.h
+++ b/include/SDL_audio.h
@@ -462,57 +462,6 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
* hostname/IP address for a remote audio server, or a filename in the
* diskaudio driver.
*
- * When filling in the desired audio spec structure:
- *
- * - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
- * - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc).
- * - `desired->samples` is the desired size of the audio buffer, in _sample
- * frames_ (with stereo output, two samples--left and right--would make a
- * single sample frame). This number should be a power of two, and may be
- * adjusted by the audio driver to a value more suitable for the hardware.
- * Good values seem to range between 512 and 8096 inclusive, depending on
- * the application and CPU speed. Smaller values reduce latency, but can
- * lead to underflow if the application is doing heavy processing and cannot
- * fill the audio buffer in time. Note that the number of sample frames is
- * directly related to time by the following formula: `ms =
- * (sampleframes*1000)/freq`
- * - `desired->size` is the size in _bytes_ of the audio buffer, and is
- * calculated by SDL_OpenAudioDevice(). You don't initialize this.
- * - `desired->silence` is the value used to set the buffer to silence, and is
- * calculated by SDL_OpenAudioDevice(). You don't initialize this.
- * - `desired->callback` should be set to a function that will be called when
- * the audio device is ready for more data. It is passed a pointer to the
- * audio buffer, and the length in bytes of the audio buffer. This function
- * usually runs in a separate thread, and so you should protect data
- * structures that it accesses by calling SDL_LockAudioDevice() and
- * SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL
- * pointer here, and call SDL_QueueAudio() with some frequency, to queue
- * more audio samples to be played (or for capture devices, call
- * SDL_DequeueAudio() with some frequency, to obtain audio samples).
- * - `desired->userdata` is passed as the first parameter to your callback
- * function. If you passed a NULL callback, this value is ignored.
- *
- * `allowed_changes` can have the following flags OR'd together:
- *
- * - `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE`
- * - `SDL_AUDIO_ALLOW_FORMAT_CHANGE`
- * - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE`
- * - `SDL_AUDIO_ALLOW_ANY_CHANGE`
- *
- * These flags specify how SDL should behave when a device cannot offer a
- * specific feature. If the application requests a feature that the hardware
- * doesn't offer, SDL will always try to get the closest equivalent.
- *
- * For example, if you ask for float32 audio format, but the sound card only
- * supports int16, SDL will set the hardware to int16. If you had set
- * SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the `obtained`
- * structure. If that flag was *not* set, SDL will prepare to convert your
- * callback's float32 audio to int16 before feeding it to the hardware and
- * will keep the originally requested format in the `obtained` structure.
- *
- * If your application can only handle one specific data format, pass a zero
- * for `allowed_changes` and let SDL transparently handle any differences.
- *
* An opened audio device starts out paused, and should be enabled for playing
* by calling SDL_PauseAudioDevice(devid, 0) when you are ready for your audio
* callback function to be called. Since the audio driver may modify the