SDL: Sync wiki -> header.

From c88eb7a8969d28e36f25ced936463c93de52c836 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 14 Jul 2021 17:07:04 -0400
Subject: [PATCH] Sync wiki -> header.

---
 include/SDL.h                |   5 +-
 include/SDL_atomic.h         |  24 ++-
 include/SDL_audio.h          | 289 ++++++++++++++++++-----------------
 include/SDL_blendmode.h      |  12 +-
 include/SDL_cpuinfo.h        |  52 ++++---
 include/SDL_error.h          |  39 ++---
 include/SDL_events.h         |  37 +++--
 include/SDL_filesystem.h     |  14 +-
 include/SDL_gamecontroller.h |  60 ++++----
 include/SDL_haptic.h         |  11 +-
 include/SDL_hints.h          |   4 +-
 include/SDL_joystick.h       |  90 ++++++-----
 include/SDL_keyboard.h       |  16 +-
 include/SDL_locale.h         |  62 ++++----
 include/SDL_log.h            |   7 +-
 include/SDL_main.h           |   5 +-
 include/SDL_metal.h          |  53 +++----
 include/SDL_mouse.h          |  15 +-
 include/SDL_mutex.h          |  31 ++--
 include/SDL_rect.h           |   4 +-
 include/SDL_render.h         | 103 +++++++------
 include/SDL_rwops.h          |  14 +-
 include/SDL_sensor.h         |   8 +-
 include/SDL_shape.h          |  63 ++++----
 include/SDL_stdinc.h         |  15 +-
 include/SDL_surface.h        |  29 ++--
 include/SDL_system.h         |   7 +-
 include/SDL_syswm.h          |   4 +-
 include/SDL_thread.h         |  49 +++---
 include/SDL_video.h          | 123 +++++++--------
 include/SDL_vulkan.h         |  70 +++++----
 31 files changed, 648 insertions(+), 667 deletions(-)

diff --git a/include/SDL.h b/include/SDL.h
index 633b5f4285..222a8bd999 100644
--- a/include/SDL.h
+++ b/include/SDL.h
@@ -178,9 +178,8 @@ extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
  * Get a mask of the specified subsystems which are currently initialized.
  *
  * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
- * \returns a mask of all initialized subsystems if `flags` is 0,
- *          otherwise it returns the initialization status of the specified
- *          subsystems.
+ * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it
+ *          returns the initialization status of the specified subsystems.
  *
  *          The return value does not include SDL_INIT_NOPARACHUTE.
  *
diff --git a/include/SDL_atomic.h b/include/SDL_atomic.h
index df2974bbb6..5e1eae7735 100644
--- a/include/SDL_atomic.h
+++ b/include/SDL_atomic.h
@@ -159,17 +159,17 @@ extern _inline void SDL_CompilerBarrier (void);
  * Memory barriers are designed to prevent reads and writes from being
  * reordered by the compiler and being seen out of order on multi-core CPUs.
  *
- * A typical pattern would be for thread A to write some data and a flag,
- * and for thread B to read the flag and get the data. In this case you
- * would insert a release barrier between writing the data and the flag,
+ * A typical pattern would be for thread A to write some data and a flag, and
+ * for thread B to read the flag and get the data. In this case you would
+ * insert a release barrier between writing the data and the flag,
  * guaranteeing that the data write completes no later than the flag is
- * written, and you would insert an acquire barrier between reading the
- * flag and reading the data, to ensure that all the reads associated
- * with the flag have completed.
+ * written, and you would insert an acquire barrier between reading the flag
+ * and reading the data, to ensure that all the reads associated with the flag
+ * have completed.
  *
- * In this pattern you should always see a release barrier paired with
- * an acquire barrier and you should gate the data reads/writes with a
- * single flag variable.
+ * In this pattern you should always see a release barrier paired with an
+ * acquire barrier and you should gate the data reads/writes with a single
+ * flag variable.
  *
  * For more information on these semantics, take a look at the blog post:
  * http://preshing.com/20120913/acquire-and-release-semantics
@@ -238,8 +238,7 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
 typedef struct { int value; } SDL_atomic_t;
 
 /**
- * Set an atomic variable to a new value if it is
- * currently an old value.
+ * Set an atomic variable to a new value if it is currently an old value.
  *
  * ***Note: If you don't know what this function is for, you shouldn't use
  * it!***
@@ -321,8 +320,7 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
 #endif
 
 /**
- * Set a pointer to a new value if it is currently an old
- * value.
+ * Set a pointer to a new value if it is currently an old value.
  *
  * ***Note: If you don't know what this function is for, you shouldn't use
  * it!***
diff --git a/include/SDL_audio.h b/include/SDL_audio.h
index 2d12fca2f1..05b482b023 100644
--- a/include/SDL_audio.h
+++ b/include/SDL_audio.h
@@ -307,8 +307,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
  *   means you can only have one device open at a time with this function.
  *
  * \param desired an SDL_AudioSpec structure representing the desired output
- *                format. Please refer to the SDL_OpenAudioDevice documentation
- *                for details on how to prepare this structure.
+ *                format. Please refer to the SDL_OpenAudioDevice
+ *                documentation for details on how to prepare this structure.
  * \param obtained an SDL_AudioSpec structure filled in with the actual
  *                 parameters, or NULL.
  * \returns 0 if successful, placing the actual hardware parameters in the
@@ -317,8 +317,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
  *          If `obtained` is NULL, the audio data passed to the callback
  *          function will be guaranteed to be in the requested format, and
  *          will be automatically converted to the actual hardware audio
- *          format if necessary. If `obtained` is NULL, `desired` will
- *          have fields modified.
+ *          format if necessary. If `obtained` is NULL, `desired` will have
+ *          fields modified.
  *
  *          This function returns a negative error code on failure to open the
  *          audio device or failure to set up the audio thread; call
@@ -350,8 +350,8 @@ typedef Uint32 SDL_AudioDeviceID;
  * subsystem.
  *
  * Note that audio capture support is not implemented as of SDL 2.0.4, so the
- * `iscapture` parameter is for future expansion and should always be zero
- * for now.
+ * `iscapture` parameter is for future expansion and should always be zero for
+ * now.
  *
  * This function will return -1 if an explicit list of devices can't be
  * determined. Returning -1 is not an error. For example, if SDL is set up to
@@ -463,31 +463,31 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
  *
  * - `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.
+ * - `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:
  *
@@ -502,11 +502,10 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
  *
  * 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.
+ * 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.
@@ -590,24 +589,24 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
 /**
  * Load the audio data of a WAVE file into memory.
  *
- * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len`
- * to be valid pointers. The entire data portion of the file is then loaded
- * into memory and decoded if necessary.
+ * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
+ * be valid pointers. The entire data portion of the file is then loaded into
+ * memory and decoded if necessary.
  *
  * If `freesrc` is non-zero, the data source gets automatically closed and
  * freed before the function returns.
  *
  * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
- * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits),
- * and A-law and mu-law (8 bits). Other formats are currently unsupported and
+ * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
+ * A-law and mu-law (8 bits). Other formats are currently unsupported and
  * cause an error.
  *
  * If this function succeeds, the pointer returned by it is equal to `spec`
  * and the pointer to the audio data allocated by the function is written to
  * `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec
- * members `freq`, `channels`, and `format` are set to the values of the
- * audio data in the buffer. The `samples` member is set to a sane default
- * and all others are set to zero.
+ * members `freq`, `channels`, and `format` are set to the values of the audio
+ * data in the buffer. The `samples` member is set to a sane default and all
+ * others are set to zero.
  *
  * It's necessary to use SDL_FreeWAV() to free the audio data returned in
  * `audio_buf` when it is no longer used.
@@ -616,19 +615,21 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
  * problematic files in the wild that cause issues with strict decoders. To
  * provide compatibility with these files, this decoder is lenient in regards
  * to the truncation of the file, the fact chunk, and the size of the RIFF
- * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`, `SDL_HINT_WAVE_TRUNCATION`,
- * and `SDL_HINT_WAVE_FACT_CHUNK` can be used to tune the behavior of the
- * loading process.
+ * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
+ * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
+ * tune the behavior of the loading process.
  *
  * Any file that is invalid (due to truncation, corruption, or wrong values in
  * the headers), too big, or unsupported causes an error. Additionally, any
  * critical I/O error from the data source will terminate the loading process
- * with an error. The function returns NULL on error and in all cases (with the
- * exception of `src` being NULL), an appropriate error message will be set.
+ * with an error. The function returns NULL on error and in all cases (with
+ * the exception of `src` being NULL), an appropriate error message will be
+ * set.
  *
  * It is required that the data source supports seeking.
  *
  * Example:
+ *
  * ```c++
  * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
  * ```
@@ -644,8 +645,10 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
  * \param freesrc If non-zero, SDL will _always_ free the data source
  * \param spec An SDL_AudioSpec that will be filled in with the wave file's
  *             format details
- * \param audio_buf A pointer filled with the audio data, allocated by the function.
- * \param audio_len A pointer filled with the length of the audio data buffer in bytes
+ * \param audio_buf A pointer filled with the audio data, allocated by the
+ *                  function.
+ * \param audio_len A pointer filled with the length of the audio data buffer
+ *                  in bytes
  * \returns This function, if successfully called, returns `spec`, which will
  *          be filled with the audio data format of the wave source data.
  *          `audio_buf` will be filled with a pointer to an allocated buffer
@@ -713,8 +716,7 @@ extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
  * \param dst_format the destination format of the audio data; for more info
  *                   see SDL_AudioFormat
  * \param dst_channels the number of channels in the destination
- * \param dst_rate the frequency (sample-frames-per-second) of the
- *                 destination
+ * \param dst_rate the frequency (sample-frames-per-second) of the destination
  * \returns 1 if the audio filter is prepared, 0 if no conversion is needed,
  *          or a negative error code on failure; call SDL_GetError() for more
  *          information.
@@ -749,8 +751,8 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
  * in-place, the application must allocate a buffer that will fully contain
  * the data during its largest conversion pass. After SDL_BuildAudioCVT()
  * returns, the application should set the `cvt->len` field to the size, in
- * bytes, of the source data, and allocate a buffer that is
- * `cvt->len * cvt->len_mult` bytes long for the `buf` field.
+ * bytes, of the source data, and allocate a buffer that is `cvt->len *
+ * cvt->len_mult` bytes long for the `buf` field.
  *
  * The source data should be copied into this buffer before the call to
  * SDL_ConvertAudio(). Upon successful return, this buffer will contain the
@@ -779,22 +781,22 @@ struct _SDL_AudioStream;
 typedef struct _SDL_AudioStream SDL_AudioStream;
 
 /**
- *  Create a new audio stream.
- *
- *  \param src_format The format of the source audio
- *  \param src_channels The number of channels of the source audio
- *  \param src_rate The sampling rate of the source audio
- *  \param dst_format The format of the desired audio output
- *  \param dst_channels The number of channels of the desired audio output
- *  \param dst_rate The sampling rate of the desired audio output
- *  \returns 0 on success, or -1 on error.
- *
- *  \sa SDL_AudioStreamPut
- *  \sa SDL_AudioStreamGet
- *  \sa SDL_AudioStreamAvailable
- *  \sa SDL_AudioStreamFlush
- *  \sa SDL_AudioStreamClear
- *  \sa SDL_FreeAudioStream
+ * Create a new audio stream.
+ *
+ * \param src_format The format of the source audio
+ * \param src_channels The number of channels of the source audio
+ * \param src_rate The sampling rate of the source audio
+ * \param dst_format The format of the desired audio output
+ * \param dst_channels The number of channels of the desired audio output
+ * \param dst_rate The sampling rate of the desired audio output
+ * \returns 0 on success, or -1 on error.
+ *
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
  */
 extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format,
                                            const Uint8 src_channels,
@@ -804,92 +806,93 @@ extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioForm
                                            const int dst_rate);
 
 /**
- *  Add data to be converted/resampled to the stream.
- *
- *  \param stream The stream the audio data is being added to
- *  \param buf A pointer to the audio data to add
- *  \param len The number of bytes to write to the stream
- *  \returns 0 on success, or -1 on error.
- *
- *  \sa SDL_NewAudioStream
- *  \sa SDL_AudioStreamGet
- *  \sa SDL_AudioStreamAvailable
- *  \sa SDL_AudioStreamFlush
- *  \sa SDL_AudioStreamClear
- *  \sa SDL_FreeAudioStream
+ * Add data to be converted/resampled to the stream.
+ *
+ * \param stream The stream the audio data is being added to
+ * \param buf A pointer to the audio data to add
+ * \param len The number of bytes to write to the stream
+ * \returns 0 on success, or -1 on error.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
  */
 extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len);
 
 /**
- *  Get converted/resampled data from the stream
- *
- *  \param stream The stream the audio is being requested from
- *  \param buf A buffer to fill with audio data
- *  \param len The maximum number of bytes to fill
- *  \returns the number of bytes read from the stream, or -1 on error
- *
- *  \sa SDL_NewAudioStream
- *  \sa SDL_AudioStreamPut
- *  \sa SDL_AudioStreamAvailable
- *  \sa SDL_AudioStreamFlush
- *  \sa SDL_AudioStreamClear
- *  \sa SDL_FreeAudioStream
+ * Get converted/resampled data from the stream
+ *
+ * \param stream The stream the audio is being requested from
+ * \param buf A buffer to fill with audio data
+ * \param len The maximum number of bytes to fill
+ * \returns the number of bytes read from the stream, or -1 on error
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
  */
 extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len);
 
 /**
- * Get the number of converted/resampled bytes available. The stream may be
- *  buffering data behind the scenes until it has enough to resample
- *  correctly, so this number might be lower than what you expect, or even
- *  be zero. Add more data or flush the stream if you need the data now.
- *
- *  \sa SDL_NewAudioStream
- *  \sa SDL_AudioStreamPut
- *  \sa SDL_AudioStreamGet
- *  \sa SDL_AudioStreamFlush
- *  \sa SDL_AudioStreamClear
- *  \sa SDL_FreeAudioStream
+ * Get the number of converted/resampled bytes available.
+ *
+ * The stream may be buffering data behind the scenes until it has enough to
+ * resample correctly, so this number might be lower than what you expect, or
+ * even be zero. Add more data or flush the stream if you need the data now.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
  */
 extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
 
 /**
  * Tell the stream that you're done sending data, and anything being buffered
- *  should be converted/resampled and made available immediately.
- *
- * It is legal to add more data to a stream after flushing, but there will
- *  be audio gaps in the output. Generally this is intended to signal the
- *  end of input, so the complete output becomes available.
- *
- *  \sa SDL_NewAudioStream
- *  \sa SDL_AudioStreamPut
- *  \sa SDL_AudioStreamGet
- *  \sa SDL_AudioStreamAvailable
- *  \sa SDL_AudioStreamClear
- *  \sa SDL_FreeAudioStream
+ * should be converted/resampled and made available immediately.
+ *
+ * It is legal to add more data to a stream after flushing, but there will be
+ * audio gaps in the output. Generally this is intended to signal the end of
+ * input, so the complete output becomes available.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
  */
 extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
 
 /**
- *  Clear any pending data in the stream without converting it
- *
- *  \sa SDL_NewAudioStream
- *  \sa SDL_AudioStreamPut
- *  \sa SDL_AudioStreamGet
- *  \sa SDL_AudioStreamAvailable
- *  \sa SDL_AudioStreamFlush
- *  \sa SDL_FreeAudioStream
+ * Clear any pending data in the stream without converting it
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_FreeAudioStream
  */
 extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
 
 /**
  * Free an audio stream
  *
- *  \sa SDL_NewAudioStream
- *  \sa SDL_AudioStreamPut
- *  \sa SDL_AudioStreamGet
- *  \sa SDL_AudioStreamAvailable
- *  \sa SDL_AudioStreamFlush
- *  \sa SDL_AudioStreamClear
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
  */
 extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
 
@@ -920,8 +923,8 @@ extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
 /**
  * Mix audio data in a specified format.
  *
- * This takes an audio buffer `src` of `len` bytes of `format` data and
- * mixes it into `dst`, performing addition, volume adjustment, and overflow
+ * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
+ * it into `dst`, performing addition, volume adjustment, and overflow
  * clipping. The buffer pointed to by `dst` must also be `len` bytes of
  * `format` data.
  *
@@ -981,6 +984,11 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
  * You should not call SDL_LockAudio() on the device before queueing; SDL
  * handles locking internally for this function.
  *
+ * Note that SDL2
+ * [https://discourse.libsdl.org/t/sdl2-support-for-planar-audio/31263/3 does
+ * not support planar audio]. You will need to resample from planar audio
+ * formats into a non-planar one (see SDL_AudioFormat) before queuing audio.
+ *
  * \param dev the device ID to which we will queue audio
  * \param data the data to queue to the device for later playback
  * \param len the number of bytes (not samples!) to which `data` points
@@ -1032,8 +1040,8 @@ extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *da
  * \param dev the device ID from which we will dequeue audio
  * \param data a pointer into where audio data should be copied
  * \param len the number of bytes (not samples!) to which (data) points
- * \returns the number of bytes dequeued, which could be less than requested; call
- *          SDL_GetError() for more information.
+ * \returns the number of bytes dequeued, which could be less than requested;
+ *          call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 2.0.5.
  *
@@ -1045,9 +1053,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *dat
 /**
  * Get the number of bytes of still-queued audio.
  *
- * For playback devices: this is the number of bytes that have been queued
- * for playback with SDL_QueueAudio(), but have not yet been sent to the
- * hardware.
+ * For playback devices: this is the number of bytes that have been queued for
+ * playback with SDL_QueueAudio(), but have not yet been sent to the hardware.
  *
  * Once we've sent it to the hardware, this function can not decide the exact
  * byte boundary of what has been played. It's possible that we just gave the
diff --git a/include/SDL_blendmode.h b/include/SDL_blendmode.h
index 7627e324c0..374f225a0b 100644
--- a/include/SDL_blendmode.h
+++ b/include/SDL_blendmode.h
@@ -109,8 +109,8 @@ typedef enum
  * dstA = alphaOperation(srcA * srcAlphaFactor, dstA * dstAlphaFactor);
  * ```
  *
- * Where the functions `colorOperation(src, dst)` and
- * `alphaOperation(src, dst)` can return one of the following:
+ * Where the functions `colorOperation(src, dst)` and `alphaOperation(src,
+ * dst)` can return one of the following:
  *
  * - `src + dst`
  * - `src - dst`
@@ -140,8 +140,8 @@ typedef enum
  *   factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and
  *   `SDL_BLENDOPERATION_MAXIMUM`.
  * - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
- *   factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with
- *   SDL 2.0.6.
+ *   factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with SDL
+ *   2.0.6.
  * - **opengles**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
  *   factors. Color and alpha factors need to be the same. OpenGL ES 1
  *   implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT`
@@ -149,8 +149,8 @@ typedef enum
  *   operations being different from each other. May support color and alpha
  *   factors being different from each other.
  * - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`,
- *   `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT` operations
- *   with all factors.
+ *   `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT`
+ *   operations with all factors.
  * - **psp**: No custom blend mode support.
  * - **software**: No custom blend mode support.
  *
diff --git a/include/SDL_cpuinfo.h b/include/SDL_cpuinfo.h
index 8fa8a2e8b2..4401c37963 100644
--- a/include/SDL_cpuinfo.h
+++ b/include/SDL_cpuinfo.h
@@ -171,7 +171,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
 /**
  * Determine whether the CPU has AltiVec features.
  *
- * This always returns false on CPUs that aren't using PowerPC instruction sets.
+ * This always returns false on CPUs that aren't using PowerPC instruction
+ * sets.
  *
  * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not.
  *
@@ -418,15 +419,16 @@ extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
  * Report the alignment this system needs for SIMD allocations.
  *
  * This will return the minimum number of bytes to which a pointer must be
- * aligned to be compatible with SIMD instructions on the current machine.
- * For example, if the machine supports SSE only, it will return 16, but if
- * it supports AVX-512F, it'll return 64 (etc). This only reports values for
+ * aligned to be compatible with SIMD instructions on the current machine. For
+ * example, if the machine supports SSE only, it will return 16, but if it
+ * supports AVX-512F, it'll return 64 (etc). This only reports values for
  * instruction sets SDL knows about, so if your SDL build doesn't have
  * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
  * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
  * Plan accordingly.
  *
- * \returns the alignment in bytes needed for available, known SIMD instructions.
+ * \returns the alignment in bytes needed for available, known SIMD
+ *          instructions.
  */
 extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
 
@@ -434,24 +436,24 @@ extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
  * Allocate memory in a SIMD-friendly way.
  *
  * This will allocate a block of memory that is suitable for use with SIMD
- * instructions. Specifically, it will be properly aligned and padded for
- * the system's supported vector instructions.
+ * instructions. Specifically, it will be properly aligned and padded for the
+ * system's supported vector instructions.
  *
- * The memory returned will be padded such that it is safe to read or write
- * an incomplete vector at the end of the memory block. This can be useful
- * so you don't have to drop back to a scalar fallback at the end of your
- * SIMD processing loop to deal with the final elements without overflowing
- * the allocated buffer.
+ * The memory returned will be padded such that it is safe to read or write an
+ * incomplete vector at the end of the memory block. This can be useful so you
+ * don't have to drop back to a scalar fallback at the end of your SIMD
+ * processing loop to deal with the final elements without overflowing the
+ * allocated buffer.
  *
- * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free()
- * or delete[], etc.
+ * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free() or
+ * delete[], etc.
  *
- * Note that SDL will only deal with SIMD instruction sets it is aware of;
- * for example, SDL 2.0.8 knows that SSE wants 16-byte vectors
- * (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't
- * know that AVX-512 wants 64. To be clear: if you 

(Patch may be truncated, please check the link at the top of this post.)