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.)