Sync wiki -> header.

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

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!***

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

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

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 can't decide to use an
- * instruction set with an SDL_Has*() function, don't use that instruction
- * set with memory allocated through here.
+ * 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 can't decide to use an instruction set with an
+ * SDL_Has*() function, don't use that instruction set with memory allocated
+ * through here.
  *
  * SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't
  * out of memory, but you are not allowed to dereference it (because you only
@@ -499,12 +501,12 @@ extern DECLSPEC void * SDLCALL SDL_SIMDRealloc(void *mem, const size_t len);
  * However, SDL_SIMDFree(NULL) is a legal no-op.
  *
  * The memory pointed to by `ptr` is no longer valid for access upon return,
- * and may be returned to the system or reused by a future allocation.
- * The pointer passed to this function is no longer safe to dereference once
- * this function returns, and should be discarded.
+ * and may be returned to the system or reused by a future allocation. The
+ * pointer passed to this function is no longer safe to dereference once this
+ * function returns, and should be discarded.
  *
- * \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc,
- *            to deallocate. NULL is a legal no-op.
+ * \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc, to
+ *            deallocate. NULL is a legal no-op.
  *
  * \sa SDL_SIMDAlloc
  * \sa SDL_SIMDRealloc

include/SDL_error.h

@@ -44,8 +44,8 @@ extern "C" {
  *
  * Calling this function will replace any previous error message that was set.
  *
- * This function always returns -1, since SDL frequently uses -1 to signify
- * an failing result, leading to this idiom:
+ * This function always returns -1, since SDL frequently uses -1 to signify an
+ * failing result, leading to this idiom:
  *
  * ```c
  * if (error_code) {
@@ -54,26 +54,27 @@ extern "C" {
  * ```
  *
  * \param fmt a printf()-style message format string
- * \param ... additional parameters matching % tokens in the `fmt` string,
- *            if any
+ * \param ... additional parameters matching % tokens in the `fmt` string, if
+ *            any
  * \returns always -1.
  *
- * \sa  SDL_ClearError
- * \sa  SDL_GetError
+ * \sa SDL_ClearError
+ * \sa SDL_GetError
  */
 extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
 
 /**
- * Retrieve a message about the last error that occurred on the current thread.
+ * Retrieve a message about the last error that occurred on the current
+ * thread.
  *
  * It is possible for multiple errors to occur before calling SDL_GetError().
  * Only the last error is returned.
  *
  * The message is only applicable when an SDL function has signaled an error.
- * You must check the return values of SDL function calls to determine when
- * to appropriately call SDL_GetError(). You should _not_ use the results
- * of SDL_GetError() to decide if an error has occurred! Sometimes SDL will
- * set an error string even when reporting success.
+ * You must check the return values of SDL function calls to determine when to
+ * appropriately call SDL_GetError(). You should _not_ use the results of
+ * SDL_GetError() to decide if an error has occurred! Sometimes SDL will set
+ * an error string even when reporting success.
  *
  * SDL will _not_ clear the error string for successful API calls. You _must_
  * check return values for failure cases before you can assume the error
@@ -87,10 +88,10 @@ extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fm
  *
  * \returns a message with information about the specific error that occurred,
  *          or an empty string if there hasn't been an error message set since
- *          the last call to SDL_ClearError(). The message is only applicable when an
- *          SDL function has signaled an error. You must check the return
- *          values of SDL function calls to determine when to appropriately
- *          call SDL_GetError().
+ *          the last call to SDL_ClearError(). The message is only applicable
+ *          when an SDL function has signaled an error. You must check the
+ *          return values of SDL function calls to determine when to
+ *          appropriately call SDL_GetError().
  *
  * \sa SDL_ClearError
  * \sa SDL_SetError
@@ -100,11 +101,11 @@ extern DECLSPEC const char *SDLCALL SDL_GetError(void);
 /**
  * Get the last error message that was set for the current thread.
  *
- * This allows the caller to copy the error string into a provided buffer,
- * but otherwise operates exactly the same as SDL_GetError().
+ * This allows the caller to copy the error string into a provided buffer, but
+ * otherwise operates exactly the same as SDL_GetError().
  *
- * \param errstr A buffer to fill with the last error message that was set
- *                for the current thread
+ * \param errstr A buffer to fill with the last error message that was set for
+ *               the current thread
  * \param maxlen The size of the buffer pointed to by the errstr parameter
  * \returns the pointer passed in as the `errstr` parameter.
  *

include/SDL_events.h

@@ -671,8 +671,8 @@ typedef enum
  *
  * `action` may be any of the following:
  *
- * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of
- *   the event queue.
+ * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the
+ *   event queue.
  * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
  *   within the specified minimum and maximum type, will be returned to the
  *   caller and will _not_ be removed from the queue.
@@ -784,10 +784,10 @@ extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
 /**
  * Poll for currently pending events.
  *
- * If `event` is not NULL, the next event is removed from the queue and
- * stored in the SDL_Event structure pointed to by `event`. The 1 returned
- * refers to this event, immediately stored in the SDL Event structure -- not
- * an event to follow.
+ * If `event` is not NULL, the next event is removed from the queue and stored
+ * in the SDL_Event structure pointed to by `event`. The 1 returned refers to
+ * this event, immediately stored in the SDL Event structure -- not an event
+ * to follow.
  *
  * If `event` is NULL, it simply returns 1 if there is an event in the queue,
  * but will not remove it from the queue.
@@ -829,8 +829,8 @@ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
 /**
  * Wait indefinitely for the next available event.
  *
- * If `event` is not NULL, the next event is removed from the queue and
- * stored in the SDL_Event structure pointed to by `event`.
+ * If `event` is not NULL, the next event is removed from the queue and stored
+ * in the SDL_Event structure pointed to by `event`.
  *
  * As this function implicitly calls SDL_PumpEvents(), you can only call this
  * function in the thread that initialized the video subsystem.
@@ -847,11 +847,11 @@ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
 
 /**
- * Wait until the specified timeout (in milliseconds) for
- * the next available event.
+ * Wait until the specified timeout (in milliseconds) for the next available
+ * event.
  *
- * If `event` is not NULL, the next event is removed from the queue and
- * stored in the SDL_Event structure pointed to by `event`.
+ * If `event` is not NULL, the next event is removed from the queue and stored
+ * in the SDL_Event structure pointed to by `event`.
  *
  * As this function implicitly calls SDL_PumpEvents(), you can only call this
  * function in the thread that initialized the video subsystem.
@@ -933,10 +933,10 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
  * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
  * application at the next event poll.
  *
- * There is one caveat when dealing with the ::SDL_QuitEvent event type.  The
+ * There is one caveat when dealing with the ::SDL_QuitEvent event type. The
  * event filter is only called when the window manager desires to close the
- * application window.  If the event filter returns 1, then the window will
- * be closed, otherwise the window will remain open if possible.
+ * application window. If the event filter returns 1, then the window will be
+ * closed, otherwise the window will remain open if possible.
  *
  * Note: Disabled events never make it to the event filter function; see
  * SDL_EventState().
@@ -1004,8 +1004,7 @@ extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
                                                void *userdata);
 
 /**
- * Remove an event watch callback added with
- * SDL_AddEventWatch().
+ * Remove an event watch callback added with SDL_AddEventWatch().
  *
  * This function takes the same input as SDL_AddEventWatch() to identify and
  * delete the corresponding callback.
@@ -1019,8 +1018,8 @@ extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
                                                void *userdata);
 
 /**
- * Run a specific filter function on the current event
- * queue, removing any events for which the filter returns 0.
+ * Run a specific filter function on the current event queue, removing any
+ * events for which the filter returns 0.
  *
  * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(),
  * this function does not change the filter permanently, it only uses the

include/SDL_filesystem.h

@@ -63,8 +63,8 @@ extern "C" {
  * The returned path is guaranteed to end with a path separator ('\' on
  * Windows, '/' on most other platforms).
  *
- * The pointer returned is owned by the caller. Please call SDL_free() on
- * the pointer when done with it.
+ * The pointer returned is owned by the caller. Please call SDL_free() on the
+ * pointer when done with it.
  *
  * \returns an absolute path in UTF-8 encoding to the application data
  *          directory. NULL will be returned on error or when the platform
@@ -84,9 +84,9 @@ extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
  * files (preferences and save games, etc) that are specific to your
  * application. This directory is unique per user, per application.
  *
- * This function will decide the appropriate location in the native filesystem,
- * create the directory if necessary, and return a string of the absolute
- * path to the directory in UTF-8 encoding.
+ * This function will decide the appropriate location in the native
+ * filesystem, create the directory if necessary, and return a string of the
+ * absolute path to the directory in UTF-8 encoding.
  *
  * On Windows, the string might look like:
  *
@@ -119,8 +119,8 @@ extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
  * The returned path is guaranteed to end with a path separator ('\' on
  * Windows, '/' on most other platforms).
  *
- * The pointer returned is owned by the caller. Please call SDL_free() on
- * the pointer when done with it.
+ * The pointer returned is owned by the caller. Please call SDL_free() on the
+ * pointer when done with it.
  *
  * \param org the name of your organization
  * \param app the name of your application

include/SDL_gamecontroller.h

@@ -166,8 +166,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
 #define SDL_GameControllerAddMappingsFromFile(file)   SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)
 
 /**
- * Add support for controllers that SDL is unaware of or
- * to cause an existing controller to have a different binding.
+ * Add support for controllers that SDL is unaware of or to cause an existing
+ * controller to have a different binding.
  *
  * The mapping string has the format "GUID,name,mapping", where GUID is the
  * string value from SDL_JoystickGetGUIDString(), name is the human readable
@@ -202,8 +202,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void);
 /**
  * Get the mapping at a particular index.
  *
- * \returns the mapping string.  Must be freed with SDL_free().
- *          Returns NULL if the index is out of range.
+ * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
+ *          the index is out of range.
  */
 extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_index);
 
@@ -259,8 +259,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gam
 extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
 
 /**
- * Get the implementation dependent name for the game
- * controller.
+ * Get the implementation dependent name for the game controller.
  *
  * This function can be called before any controllers are opened.
  *
@@ -298,8 +297,8 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(in
  *
  * \param joystick_index the device_index of a device, from zero to
  *                       SDL_NumJoysticks()-1
- * \returns the mapping string. Must be freed with SDL_free(). Returns NULL
- *          if no mapping is available.
+ * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
+ *          no mapping is available.
  */
 extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index);
 
@@ -341,11 +340,11 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromInstanceID(SDL
 /**
  * Get the SDL_GameController associated with a player index.
  *
- * Please note that the player index is _not_ the device index, nor is it
- * the instance id!
+ * Please note that the player index is _not_ the device index, nor is it the
+ * instance id!
  *
- * \param player_index the player index, which is not the device index or
- *                     the instance id!
+ * \param player_index the player index, which is not the device index or the
+ *                     instance id!
  * \returns the SDL_GameController associated with a player index.
  *
  * \sa SDL_GameControllerGetPlayerIndex
@@ -383,9 +382,9 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *g
 extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller);
 
 /**
- *  Get the player index of an opened game controller.
+ * Get the player index of an opened game controller.
  *
- *  For XInput controllers this returns the XInput user index.
+ * For XInput controllers this returns the XInput user index.
  *
  * \param gamecontroller the game controller object to query.
  * \returns the player index for controller, or -1 if it's not available.
@@ -393,7 +392,7 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_Gam
 extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller);
 
 /**
- *  Set the player index of an opened game controller.
+ * Set the player index of an opened game controller.
  *
  * \param gamecontroller the game controller object to adjust.
  * \param player_index Player index to assign to this controller.
@@ -432,8 +431,9 @@ extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameContr
 
 /**
  * Get the serial number of an opened controller, if available.
- * 
- * Returns the serial number of the controller, or NULL if it is not available.
+ *
+ * Returns the serial number of the controller, or NULL if it is not
+ * available.
  *
  * \param gamecontroller the game controller object to query.
  * \return the serial number, or NULL if unavailable.
@@ -558,9 +558,9 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameC
  *
  * \param gamecontroller a game controller
  * \param axis an axis enum value (one of the SDL_GameControllerAxis values)
- * \returns a SDL_GameControllerButtonBind describing the bind. On
- *          failure (like the given Controller axis doesn't exist on the
- *          device), its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
+ * \returns a SDL_GameControllerButtonBind describing the bind. On failure
+ *          (like the given Controller axis doesn't exist on the device), its
+ *          `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
  *
  * \since This function is available since SDL 2.0.0.
  *
@@ -644,7 +644,6 @@ typedef enum
  * \param str string representing a SDL_GameController axis
  * \returns the SDL_GameControllerButton enum corresponding to the input
  *          string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
- *
  */
 extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *str);
 
@@ -669,9 +668,9 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_Gam
  *
  * \param gamecontroller a game controller
  * \param button an button enum value (an SDL_GameControllerButton value)
- * \returns a SDL_GameControllerButtonBind describing the bind. On
- *          failure (like the given Controller button doesn't exist on the
- *          device), its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
+ * \returns a SDL_GameControllerButtonBind describing the bind. On failure
+ *          (like the given Controller button doesn't exist on the device),
+ *          its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
  *
  * \since This function is available since SDL 2.0.0.
  *
@@ -715,7 +714,8 @@ extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *ga
 extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller);
 
 /**
- * Get the number of supported simultaneous fingers on a touchpad on a game controller.
+ * Get the number of supported simultaneous fingers on a touchpad on a game
+ * controller.
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameController *gamecontroller, int touchpad);
 
@@ -729,7 +729,6 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameControll
  *
  * \param gamecontroller The controller to query
  * \param type The type of sensor to query
- *
  * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController *gamecontroller, SDL_SensorType type);
@@ -740,7 +739,6 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController
  * \param gamecontroller The controller to update
  * \param type The type of sensor to enable/disable
  * \param enabled Whether data reporting should be enabled
- *
  * \returns 0 or -1 if an error occurred.
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type, SDL_bool enabled);
@@ -750,7 +748,6 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameControlle
  *
  * \param gamecontroller The controller to query
  * \param type The type of sensor to query
- *
  * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type);
@@ -798,9 +795,9 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecon
  * \param gamecontroller The controller to vibrate
  * \param left_rumble The intensity of the left trigger rumble motor, from 0
  *                    to 0xFFFF
- * \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF
+ * \param right_rumble The intensity of the right trigger rumble motor, from 0
+ *                     to 0xFFFF
  * \param duration_ms The duration of the rumble effect, in milliseconds
- *
  * \returns 0, or -1 if trigger rumble isn't supported on this controller
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController *gamecontroller, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
@@ -831,7 +828,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecon
  * \param gamecontroller The controller to affect
  * \param data The data to send to the controller
  * \param size The size of the data to send to the controller
- * \returns 0, or -1 if this controller or driver doesn't support effect packets
+ * \returns 0, or -1 if this controller or driver doesn't support effect
+ *          packets
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gamecontroller, const void *data, int size);
 

include/SDL_haptic.h

@@ -993,8 +993,7 @@ extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
 extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
 
 /**
- * Get the number of effects a haptic device can play at
- * the same time.
+ * Get the number of effects a haptic device can play at the same time.
  *
  * This is not supported on all platforms, but will always return a value.
  *
@@ -1038,8 +1037,7 @@ extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
 extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
 
 /**
- * Check to see if an effect is supported by a haptic
- * device.
+ * Check to see if an effect is supported by a haptic device.
  *
  * \param haptic the SDL_Haptic device to query
  * \param effect the desired effect to query
@@ -1125,7 +1123,9 @@ extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
 
 /**
  * Stop the haptic effect on its associated haptic device.
+ *
  * *
+ *
  * \param haptic the SDL_Haptic device to stop the effect on
  * \param effect the ID of the haptic effect to stop
  * \returns 0 on success or a negative error code on failure; call
@@ -1156,8 +1156,7 @@ extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
                                                      int effect);
 
 /**
- * Get the status of the current effect on the specified
- * haptic device.
+ * Get the status of the current effect on the specified haptic device.
  *
  * Device must support the SDL_HAPTIC_STATUS feature.
  *

include/SDL_hints.h

@@ -1770,7 +1770,7 @@ typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const
  *
  * \param name the hint to watch
  * \param callback An SDL_HintCallback function that will be called when the
- *        hint value changes
+ *                 hint value changes
  * \param userdata a pointer to pass to the callback function
  *
  * \since This function is available since SDL 2.0.0.
@@ -1786,7 +1786,7 @@ extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name,
  *
  * \param name the hint being watched
  * \param callback An SDL_HintCallback function that will be called when the
- *        hint value changes
+ *                 hint value changes
  * \param userdata a pointer being passed to the callback function
  *
  * \since This function is available since SDL 2.0.0.

include/SDL_joystick.h

@@ -167,14 +167,14 @@ extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
 extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
 
 /**
- *  Get the player index of a joystick, or -1 if it's not available
- *  This can be called before any joysticks are opened.
+ * Get the player index of a joystick, or -1 if it's not available This can be
+ * called before any joysticks are opened.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index);
 
 /**
- * Get the implementation-dependent GUID for the joystick
- * at a given device index.
+ * Get the implementation-dependent GUID for the joystick at a given device
+ * index.
  *
  * This function can be called before any joysticks are opened.
  *
@@ -191,8 +191,8 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_in
 /**
  * Get the USB vendor ID of a joystick, if available.
  *
- * This can be called before any joysticks are opened.
- * If the vendor ID isn't available this function returns 0.
+ * This can be called before any joysticks are opened. If the vendor ID isn't
+ * available this function returns 0.
  *
  * \param device_index the index of the joystick to query (the N'th joystick
  *                     on the system
@@ -204,8 +204,8 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index);
 /**
  * Get the USB product ID of a joystick, if available.
  *
- * This can be called before any joysticks are opened.
- * If the product ID isn't available this function returns 0.
+ * This can be called before any joysticks are opened. If the product ID isn't
+ * available this function returns 0.
  *
  * \param device_index the index of the joystick to query (the N'th joystick
  *                     on the system
@@ -217,8 +217,8 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index);
 /**
  * Get the product version of a joystick, if available.
  *
- * This can be called before any joysticks are opened.
- * If the product version isn't available this function returns 0.
+ * This can be called before any joysticks are opened. If the product version
+ * isn't available this function returns 0.
  *
  * \param device_index the index of the joystick to query (the N'th joystick
  *                     on the system
@@ -242,8 +242,8 @@ extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_in
 /**
  * Get the instance ID of a joystick.
  *
- * This can be called before any joysticks are opened.
- * If the index is out of range, this function will return -1.
+ * This can be called before any joysticks are opened. If the index is out of
+ * range, this function will return -1.
  *
  * \param device_index the index of the joystick to query (the N'th joystick
  *                     on the system
@@ -322,12 +322,12 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickIsVirtual(int device_index);
 /**
  * Set values on an opened, virtual-joystick's axis.
  *
- * Please note that values set here will not be applied until the next
- * call to SDL_JoystickUpdate, which can either be called directly,
- * or can be called indirectly through various other SDL APIs,
- * including, but not limited to the following: SDL_PollEvent,
- * SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
- * 
+ * Please note that values set here will not be applied until the next call to
+ * SDL_JoystickUpdate, which can either be called directly, or can be called
+ * indirectly through various other SDL APIs, including, but not limited to
+ * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
+ * SDL_WaitEvent.
+ *
  * \param joystick the virtual joystick on which to set state.
  * \param axis the specific axis on the virtual joystick to set.
  * \param value the new value for the specified axis.
@@ -338,12 +338,12 @@ extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualAxis(SDL_Joystick *joystick, i
 /**
  * Set values on an opened, virtual-joystick's button.
  *
- * Please note that values set here will not be applied until the next
- * call to SDL_JoystickUpdate, which can either be called directly,
- * or can be called indirectly through various other SDL APIs,
- * including, but not limited to the following: SDL_PollEvent,
- * SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
- * 
+ * Please note that values set here will not be applied until the next call to
+ * SDL_JoystickUpdate, which can either be called directly, or can be called
+ * indirectly through various other SDL APIs, including, but not limited to
+ * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
+ * SDL_WaitEvent.
+ *
  * \param joystick the virtual joystick on which to set state.
  * \param button the specific button on the virtual joystick to set.
  * \param value the new value for the specified button.
@@ -354,12 +354,12 @@ extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualButton(SDL_Joystick *joystick,
 /**
  * Set values on an opened, virtual-joystick's hat.
  *
- * Please note that values set here will not be applied until the next
- * call to SDL_JoystickUpdate, which can either be called directly,
- * or can be called indirectly through various other SDL APIs,
- * including, but not limited to the following: SDL_PollEvent,
- * SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
- * 
+ * Please note that values set here will not be applied until the next call to
+ * SDL_JoystickUpdate, which can either be called directly, or can be called
+ * indirectly through various other SDL APIs, including, but not limited to
+ * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
+ * SDL_WaitEvent.
+ *
  * \param joystick the virtual joystick on which to set state.
  * \param hat the specific hat on the virtual joystick to set.
  * \param value the new value for the specified hat.
@@ -437,6 +437,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick);
 
 /**
  * Get the product version of an opened joystick, if available.
+ *
  * If the product version isn't available this function returns 0.
  *
  * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
@@ -446,11 +447,12 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joyst
 
 /**
  * Get the serial number of an opened joystick, if available.
- * 
+ *
  * Returns the serial number of the joystick, or NULL if it is not available.
  *
  * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
- * \returns the serial number of the selected joystick, or NULL if unavailable.
+ * \returns the serial number of the selected joystick, or NULL if
+ *          unavailable.
  */
 extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystick);
 
@@ -609,12 +611,11 @@ extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
 /**
  * Get the current state of an axis control on a joystick.
  *
- * SDL makes no promises about what part of the joystick any given axis
- * refers to. Your game should have some sort of configuration UI to let
- * users specify what each axis should be bound to. Alternately, SDL's
- * higher-level Game Controller API makes a great effort to apply order
- * to this lower-level interface, so you know that a specific axis is the
- * "left thumb stick," etc.
+ * SDL makes no promises about what part of the joystick any given axis refers
+ * to. Your game should have some sort of configuration UI to let users
+ * specify what each axis should be bound to. Alternately, SDL's higher-level
+ * Game Controller API makes a great effort to apply order to this lower-level
+ * interface, so you know that a specific axis is the "left thumb stick," etc.
  *
  * The value returned by SDL_JoystickGetAxis() is a signed integer (-32768 to
  * 32767) representing the current position of the axis. It may be necessary
@@ -688,8 +689,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick,
  * Get the ball axis change since the last poll.
  *
  * Trackballs can only return relative motion since the last call to
- * SDL_JoystickGetBall(), these motion deltas are placed into `dx` and
- * `dy`.
+ * SDL_JoystickGetBall(), these motion deltas are placed into `dx` and `dy`.
  *
  * Most joysticks do not have trackballs.
  *
@@ -730,7 +730,6 @@ extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick,
  * \param high_frequency_rumble The intensity of the high frequency (right)
  *                              rumble motor, from 0 to 0xFFFF
  * \param duration_ms The duration of the rumble effect, in milliseconds
- *
  * \returns 0, or -1 if rumble isn't supported on this joystick
  */
 extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
@@ -738,12 +737,13 @@ extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 lo
 /**
  * Start a rumble effect in the joystick's triggers
  *
- * Each call to this function cancels any previous trigger rumble effect,
- * and calling it with 0 intensity stops any rumbling.
+ * Each call to this function cancels any previous trigger rumble effect, and
+ * calling it with 0 intensity stops any rumbling.
  *
  * Note that this function is for _trigger_ rumble; the first joystick to
  * support this was the PlayStation 5's DualShock 5 controller. If you want
- * the (more common) whole-controller rumble, use SDL_JoystickRumble() instead.
+ * the (more common) whole-controller rumble, use SDL_JoystickRumble()
+ * instead.
  *
  * \param joystick The joystick to vibrate
  * \param left_rumble The intensity of the left trigger rumble motor, from 0
@@ -751,7 +751,6 @@ extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 lo
  * \param right_rumble The intensity of the right trigger rumble motor, from 0
  *                     to 0xFFFF
  * \param duration_ms The duration of the rumble effect, in milliseconds
- *
  * \returns 0, or -1 if trigger rumble isn't supported on this joystick
  */
 extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
@@ -777,7 +776,6 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick);
  * \param red The intensity of the red LED
  * \param green The intensity of the green LED
  * \param blue The intensity of the blue LED
- *
  * \returns 0 on success, -1 if this joystick does not have a modifiable LED
  */
 extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue);

include/SDL_keyboard.h

@@ -65,8 +65,8 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
  * Get a snapshot of the current state of the keyboard.
  *
  * The pointer returned is a pointer to an internal SDL array. It will be
- * valid for the whole lifetime of the application and should not be freed
- * by the caller.
+ * valid for the whole lifetime of the application and should not be freed by
+ * the caller.
  *
  * A array element with a value of 1 means that the key is pressed and a value
  * of 0 means that it is not. Indexes into this array are obtained by using
@@ -118,8 +118,8 @@ extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
 extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
 
 /**
- * Get the key code corresponding to the given scancode
- * according to the current keyboard layout.
+ * Get the key code corresponding to the given scancode according to the
+ * current keyboard layout.
  *
  * See SDL_Keycode for details.
  *
@@ -132,8 +132,8 @@ extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
 
 /**
- * Get the scancode corresponding to the given key code
- * according to the current keyboard layout.
+ * Get the scancode corresponding to the given key code according to the
+ * current keyboard layout.
  *
  * See SDL_Scancode for details.
  *
@@ -220,8 +220,8 @@ extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
  *
  * This function will start accepting Unicode text input events in the focused
  * SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and
- * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function
- * in pair with SDL_StopTextInput().
+ * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in
+ * pair with SDL_StopTextInput().
  *
  * On some platforms using this function activates the screen keyboard.
  *

include/SDL_locale.h

@@ -47,44 +47,44 @@ typedef struct SDL_Locale
 } SDL_Locale;
 
 /**
- *  \brief Report the user's preferred locale.
+ * Report the user's preferred locale.
  *
- *  This returns an array of SDL_Locale structs, the final item zeroed out.
- *  When the caller is done with this array, it should call SDL_free() on
- *  the returned value; all the memory involved is allocated in a single
- *  block, so a single SDL_free() will suffice.
+ * This returns an array of SDL_Locale structs, the final item zeroed out.
+ * When the caller is done with this array, it should call SDL_free() on the
+ * returned value; all the memory involved is allocated in a single block, so
+ * a single SDL_free() will suffice.
  *
- *  Returned language strings are in the format xx, where 'xx' is an ISO-639
- *  language specifier (such as "en" for English, "de" for German, etc).
- *  Country strings are in the format YY, where "YY" is an ISO-3166 country
- *  code (such as "US" for the United States, "CA" for Canada, etc). Country
- *  might be NULL if there's no specific guidance on them (so you might get
- *  { "en", "US" } for American English, but { "en", NULL } means "English
- *  language, generically"). Language strings are never NULL, except to
- *  terminate the array.
+ * Returned language strings are in the format xx, where 'xx' is an ISO-639
+ * language specifier (such as "en" for English, "de" for German, etc).
+ * Country strings are in the format YY, where "YY" is an ISO-3166 country
+ * code (such as "US" for the United States, "CA" for Canada, etc). Country
+ * might be NULL if there's no specific guidance on them (so you might get {
+ * "en", "US" } for American English, but { "en", NULL } means "English
+ * language, generically"). Language strings are never NULL, except to
+ * terminate the array.
  *
- *  Please note that not all of these strings are 2 characters; some are
- *  three or more.
+ * Please note that not all of these strings are 2 characters; some are three
+ * or more.
  *
- *  The returned list of locales are in the order of the user's preference.
- *  For example, a German citizen that is fluent in US English and knows
- *  enough Japanese to navigate around Tokyo might have a list like:
- *  { "de", "en_US", "jp", NULL }. Someone from England might prefer British
- *  English (where "color" is spelled "colour", etc), but will settle for
- *  anything like it: { "en_GB", "en", NULL }.
+ * The returned list of locales are in the order of the user's preference. For
+ * example, a German citizen that is fluent in US English and knows enough
+ * Japanese to navigate around Tokyo might have a list like: { "de", "en_US",
+ * "jp", NULL }. Someone from England might prefer British English (where
+ * "color" is spelled "colour", etc), but will settle for anything like it: {
+ * "en_GB", "en", NULL }.
  *
- *  This function returns NULL on error, including when the platform does not
- *  supply this information at all.
+ * This function returns NULL on error, including when the platform does not
+ * supply this information at all.
  *
- *  This might be a "slow" call that has to query the operating system. It's
- *  best to ask for this once and save the results. However, this list can
- *  change, usually because the user has changed a system preference outside
- *  of your program; SDL will send an SDL_LOCALECHANGED event in this case,
- *  if possible, and you can call this function again to get an updated copy
- *  of preferred locales.
+ * This might be a "slow" call that has to query the operating system. It's
+ * best to ask for this once and save the results. However, this list can
+ * change, usually because the user has changed a system preference outside of
+ * your program; SDL will send an SDL_LOCALECHANGED event in this case, if
+ * possible, and you can call this function again to get an updated copy of
+ * preferred locales.
  *
- *   \return array of locales, terminated with a locale with a NULL language
- *           field. Will return NULL on error.
+ * \return array of locales, terminated with a locale with a NULL language
+ *         field. Will return NULL on error.
  */
 extern DECLSPEC SDL_Locale * SDLCALL SDL_GetPreferredLocales(void);
 

include/SDL_log.h

@@ -155,9 +155,10 @@ extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
 /**
  * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
  *
-= * \param fmt a printf() style message format string
- * \param ... additional parameters matching % tokens in the `fmt` string,
- *            if any
+ * = * \param fmt a printf() style message format string
+ *
+ * \param ... additional parameters matching % tokens in the `fmt` string, if
+ *            any
  *
  * \sa SDL_LogCritical
  * \sa SDL_LogDebug

include/SDL_main.h

@@ -122,7 +122,8 @@ extern SDLMAIN_DECLSPEC int SDL_main(int argc, char *argv[]);
 
 
 /**
- * Circumvent failure of SDL_Init() when not using SDL_main() as an entry point.
+ * Circumvent failure of SDL_Init() when not using SDL_main() as an entry
+ * point.
  *
  * This function is defined in SDL_main.h, along with the preprocessor rule to
  * redefine main() as SDL_main(). Thus to ensure that your main() function
@@ -136,7 +137,7 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
 #ifdef __WIN32__
 
 /**
- *  This can be called to set the application class at startup
+ * This can be called to set the application class at startup
  */
 extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style, void *hInst);
 extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);

include/SDL_metal.h

@@ -49,59 +49,46 @@ typedef void *SDL_MetalView;
 /* @{ */
 
 /**
- *  \brief Create a CAMetalLayer-backed NSView/UIView and attach it to the
- *        specified window.
+ * Create a CAMetalLayer-backed NSView/UIView and attach it to the specified
+ * window.
  *
- *  On macOS, this does *not* associate a MTLDevice with the CAMetalLayer on its
- *  own. It is up to user code to do that.
+ * On macOS, this does *not* associate a MTLDevice with the CAMetalLayer on
+ * its own. It is up to user code to do that.
  *
- *  The returned handle can be casted directly to a NSView or UIView.
- *  To access the backing CAMetalLayer, call SDL_Metal_GetLayer().
+ * The returned handle can be casted directly to a NSView or UIView. To access
+ * the backing CAMetalLayer, call SDL_Metal_GetLayer().
  *
- *  \note \a window must be created with the SDL_WINDOW_METAL flag.
- *
- *  \sa SDL_Metal_DestroyView
- *  \sa SDL_Metal_GetLayer
+ * \sa SDL_Metal_DestroyView
+ * \sa SDL_Metal_GetLayer
  */
 extern DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * window);
 
 /**
- *  \brief Destroy an existing SDL_MetalView object.
+ * Destroy an existing SDL_MetalView object.
  *
- *  This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was
- *  called after SDL_CreateWindow.
+ * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was
+ * called after SDL_CreateWindow.
  *
- *  \sa SDL_Metal_CreateView
+ * \sa SDL_Metal_CreateView
  */
 extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view);
 
 /**
- *  \brief Get a pointer to the backing CAMetalLayer for the given view.
+ * Get a pointer to the backing CAMetalLayer for the given view.
  *
- *  \sa SDL_MetalCreateView
+ * \sa SDL_MetalCreateView
  */
 extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(SDL_MetalView view);
 
 /**
- *  \brief Get the size of a window's underlying drawable in pixels (for use
- *         with setting viewport, scissor & etc).
- *
- *  \param window   SDL_Window from which the drawable size should be queried
- *  \param w        Pointer to variable for storing the width in pixels,
- *                  may be NULL
- *  \param h        Pointer to variable for storing the height in pixels,
- *                  may be NULL
- *
- * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
- * drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a
- * platform with high-DPI support (Apple calls this "Retina"), and not disabled
- * by the \c SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
+ * Get the size of a window's underlying drawable in pixels (for use with
+ * setting viewport, scissor & etc).
  *
- *  \note On macOS high-DPI support must be enabled for an application by
- *        setting NSHighResolutionCapable to true in its Info.plist.
+ * \param window SDL_Window from which the drawable size should be queried
+ * \param w Pointer to variable for storing the width in pixels, may be NULL
  *
- *  \sa SDL_GetWindowSize()
- *  \sa SDL_CreateWindow()
+ * \sa SDL_GetWindowSize
+ * \sa SDL_CreateWindow
  */
 extern DECLSPEC void SDLCALL SDL_Metal_GetDrawableSize(SDL_Window* window, int *w,
                                                        int *h);

include/SDL_mouse.h

@@ -110,9 +110,9 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
  * window might not be in sync at all times.
  *
  * Note: SDL_GetMouseState() returns the mouse position as SDL understands it
- * from the last pump of the event queue. This function, however, queries
- * the OS for the current mouse position, and as such, might be a slightly
- * less efficient function. Unless you know what you're doing and have a good
+ * from the last pump of the event queue. This function, however, queries the
+ * OS for the current mouse position, and as such, might be a slightly less
+ * efficient function. Unless you know what you're doing and have a good
  * reason to use this function, you probably want SDL_GetMouseState() instead.
  *
  * \param x filled in with the current X coord relative to the desktop; can be
@@ -245,8 +245,7 @@ extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
 extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
 
 /**
- * Create a cursor using the specified bitmap data and
- * mask (in MSB format).
+ * Create a cursor using the specified bitmap data and mask (in MSB format).
  *
  * `mask` has to be in MSB (Most Significant Bit) format.
  *
@@ -328,7 +327,7 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id);
  * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if
  * this is desired for any reason.
  *
- * \param cursor a  cursor to make active
+ * \param cursor a cursor to make active
  *
  * \sa SDL_CreateCursor
  * \sa SDL_GetCursor
@@ -379,8 +378,8 @@ extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
  * The cursor starts off displayed but can be turned off. Passing `SDL_ENABLE`
  * displays the cursor and passing `SDL_DISABLE` hides it.
  *
- * The current state of the mouse cursor can be queried by passing `SDL_QUERY`;
- * either `SDL_DISABLE` or `SDL_ENABLE` will be returned.
+ * The current state of the mouse cursor can be queried by passing
+ * `SDL_QUERY`; either `SDL_DISABLE` or `SDL_ENABLE` will be returned.
  *
  * \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it,
  *               `SDL_QUERY` to query the current state without changing it.

include/SDL_mutex.h

@@ -86,8 +86,8 @@ extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
  * it. Of all threads waiting to lock the mutex, only one may do so at a time.
  *
  * It is legal for the owning thread to lock an already-locked mutex. It must
- * unlock it the same number of times before it is actually made available
- * for other threads in the system (this is known as a "recursive mutex").
+ * unlock it the same number of times before it is actually made available for
+ * other threads in the system (this is known as a "recursive mutex").
  *
  * \param mutex the mutex to lock
  * \return 0, or -1 on error.
@@ -105,8 +105,8 @@ extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex);
  * don't want to wait for it, and will return to it to try again later.
  *
  * \param mutex the mutex to try to lock
- * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call
- *          SDL_GetError() for more information.
+ * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for
+ *          more information.
  *
  * \sa SDL_CreateMutex
  * \sa SDL_DestroyMutex
@@ -119,8 +119,8 @@ extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex);
  * Unlock the mutex.
  *
  * It is legal for the owning thread to lock an already-locked mutex. It must
- * unlock it the same number of times before it is actually made available
- * for other threads in the system (this is known as a "recursive mutex").
+ * unlock it the same number of times before it is actually made available for
+ * other threads in the system (this is known as a "recursive mutex").
  *
  * It is an error to unlock a mutex that has not been locked by the current
  * thread, and doing so results in undefined behavior.
@@ -250,8 +250,7 @@ extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
 
 /**
- * Wait until a semaphore has a positive value and then
- * decrements it.
+ * Wait until a semaphore has a positive value and then decrements it.
  *
  * This function suspends the calling thread until either the semaphore
  * pointed to by `sem` has a positive value, the call is interrupted by a
@@ -371,10 +370,10 @@ extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
 /**
  * Wait until a condition variable is signaled.
  *
- * This function unlocks the specified `mutex` and waits for another thread
- * to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
- * `cond`. Once the condition variable is signaled, the mutex is re-locked
- * and the function returns.
+ * This function unlocks the specified `mutex` and waits for another thread to
+ * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
+ * `cond`. Once the condition variable is signaled, the mutex is re-locked and
+ * the function returns.
  *
  * The mutex must be locked before calling this function.
  *
@@ -397,10 +396,10 @@ extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
 /**
  * Wait until a condition variable is signaled or a certain time has passed.
  *
- * This function unlocks the specified `mutex` and waits for another thread
- * to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
- * `cond`, or for the specified time to elapse. Once the condition variable
- * is signaled or the time elapsed, the mutex is re-locked and the function
+ * This function unlocks the specified `mutex` and waits for another thread to
+ * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
+ * `cond`, or for the specified time to elapse. Once the condition variable is
+ * signaled or the time elapsed, the mutex is re-locked and the function
  * returns.
  *
  * The mutex must be locked before calling this function.

include/SDL_rect.h

@@ -169,8 +169,8 @@ extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A,
 /**
  * Calculate a minimal rectangle enclosing a set of points.
  *
- * If `clip` is not NULL then only points inside of the clipping rectangle
- * are considered.
+ * If `clip` is not NULL then only points inside of the clipping rectangle are
+ * considered.
  *
  * \param points an array of SDL_Point structures representing points to be
  *               enclosed

include/SDL_render.h

@@ -411,8 +411,7 @@ extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture,
                                                    Uint8 alpha);
 
 /**
- * Get the additional alpha value multiplied into render
- * copy operations.
+ * Get the additional alpha value multiplied into render copy operations.
  *
  * \param texture the texture to query
  * \param alpha a pointer filled in with the current alpha value
@@ -426,8 +425,7 @@ extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture,
                                                    Uint8 * alpha);
 
 /**
- * Set the blend mode for a texture, used by
- * SDL_RenderCopy().
+ * Set the blend mode for a texture, used by SDL_RenderCopy().
  *
  * If the blend mode is not supported, the closest supported mode is chosen
  * and this function returns -1.
@@ -465,7 +463,7 @@ extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture * texture,
  * \param scaleMode the SDL_ScaleMode to use for texture scaling.
  * \returns 0 on success, or -1 if the texture is not valid.
  *
- * \sa SDL_GetTextureScaleMode()
+ * \sa SDL_GetTextureScaleMode
  */
 extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture,
                                                     SDL_ScaleMode scaleMode);
@@ -477,7 +475,7 @@ extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture,
  * \param scaleMode a pointer filled in with the current scale mode.
  * \return 0 on success, or -1 if the texture is not valid.
  *
- * \sa SDL_SetTextureScaleMode()
+ * \sa SDL_SetTextureScaleMode
  */
 extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture * texture,
                                                     SDL_ScaleMode *scaleMode);
@@ -514,8 +512,8 @@ extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture,
                                               const void *pixels, int pitch);
 
 /**
- * Update a rectangle within a planar YV12 or IYUV
- * texture with new pixel data.
+ * Update a rectangle within a planar YV12 or IYUV texture with new pixel
+ * data.
  *
  * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
  * block of Y and U/V planes in the proper order, but this function is
@@ -557,9 +555,11 @@ extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture,
  * \param rect a pointer to the rectangle of pixels to update, or NULL to
  *             update the entire texture.
  * \param Yplane the raw pixel data for the Y plane.
- * \param Ypitch the number of bytes between rows of pixel data for the Y plane.
+ * \param Ypitch the number of bytes between rows of pixel data for the Y
+ *               plane.
  * \param UVplane the raw pixel data for the UV plane.
- * \param UVpitch the number of bytes between rows of pixel data for the UV plane.
+ * \param UVpitch the number of bytes between rows of pixel data for the UV
+ *                plane.
  * \return 0 on success, or -1 if the texture is not valid.
  */
 extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture,
@@ -590,7 +590,7 @@ extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture,
  *          or was not created with `SDL_TEXTUREACCESS_STREAMING`; call
  *          SDL_GetError() for more information.
  *
- * \sa  SDL_UnlockTexture
+ * \sa SDL_UnlockTexture
  */
 extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture,
                                             const SDL_Rect * rect,
@@ -623,8 +623,8 @@ extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture,
  * \returns 0 on success, or -1 if the texture is not valid or was not created
  *          with `SDL_TEXTUREACCESS_STREAMING`
  *
- * \sa SDL_LockTexture()
- * \sa SDL_UnlockTexture()
+ * \sa SDL_LockTexture
+ * \sa SDL_UnlockTexture
  */
 extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture,
                                             const SDL_Rect *rect,
@@ -638,8 +638,8 @@ extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture,
  * be provided. You must fully initialize any area of a texture that you lock
  * before unlocking it, as the pixels might otherwise be uninitialized memory.
  *
- * Which is to say: locking and immediately unlocking a texture can result
- * in corrupted textures, depending on the renderer in use.
+ * Which is to say: locking and immediately unlocking a texture can result in
+ * corrupted textures, depending on the renderer in use.
  *
  * \param texture a texture locked by SDL_LockTexture()
  *
@@ -663,8 +663,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *rendere
  * Set a texture as the current rendering target.
  *
  * Before using this function, you should check the
- * `SDL_RENDERER_TARGETTEXTURE` bit in the flags of SDL_RendererInfo to see
- * if render targets are supported.
+ * `SDL_RENDERER_TARGETTEXTURE` bit in the flags of SDL_RendererInfo to see if
+ * render targets are supported.
  *
  * The default render target is the window for which the renderer was created.
  * To stop rendering to a texture and render to the window again, call this
@@ -672,8 +672,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *rendere
  *
  * \param renderer the rendering context
  * \param texture the targeted texture, which must be created with the
- *                `SDL_TEXTUREACCESS_TARGET` flag, or NULL
- *                to render to the window instead of a texture.
+ *                `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the
+ *                window instead of a texture.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -704,7 +704,7 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer
  *
  * This function uses the viewport and scaling functionality to allow a fixed
  * logical resolution for rendering, regardless of the actual output
- * resolution.  If the actual output resolution doesn't have the same aspect
+ * resolution. If the actual output resolution doesn't have the same aspect
  * ratio the output rendering will be centered within the output display.
  *
  * If the output display is a window, mouse and touch events in the window
@@ -779,8 +779,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * render
 /**
  * Set the drawing area for rendering on the current target.
  *
- * When the window is resized, the viewport is reset to fill the entire
- * new window size.
+ * When the window is resized, the viewport is reset to fill the entire new
+ * window size.
  *
  * \param renderer the rendering context
  * \param rect the SDL_Rect structure representing the drawing area, or NULL
@@ -891,8 +891,8 @@ extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer,
 /**
  * Set the color used for drawing operations (Rect, Line and Clear).
  *
- * Set the color for drawing or filling rectangles, lines, and points,
- * and for SDL_RenderClear().
+ * Set the color for drawing or filling rectangles, lines, and points, and for
+ * SDL_RenderClear().
  *
  * \param renderer the rendering context
  * \param r the red value used to draw on the rendering target
@@ -1234,9 +1234,9 @@ extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer,
  * Copy a portion of the texture to the current rendering, with optional
  * rotation and flipping.
  *
- * Copy a portion of the texture to the current rendering
- * target, optionally rotating it by angle around the given center and also
- * flipping it top-bottom and/or left-right.
+ * Copy a portion of the texture to the current rendering target, optionally
+ * rotating it by angle around the given center and also flipping it
+ * top-bottom and/or left-right.
  *
  * The texture is blended with the destination based on its blend mode set
  * with SDL_SetTextureBlendMode().
@@ -1329,7 +1329,8 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer,
  * Draw a rectangle on the current rendering target at subpixel precision.
  *
  * \param renderer The renderer which should draw a rectangle.
- * \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target.
+ * \param rect A pointer to the destination rectangle, or NULL to outline the
+ *             entire rendering target.
  * \return 0 on success, or -1 on error
  */
 extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer,
@@ -1349,8 +1350,8 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer,
                                                  int count);
 
 /**
- * Fill a rectangle on the current rendering target with the drawing color
- * at subpixel precision.
+ * Fill a rectangle on the current rendering target with the drawing color at
+ * subpixel precision.
  *
  * \param renderer The renderer which should fill a rectangle.
  * \param rect A pointer to the destination rectangle, or NULL for the entire
@@ -1391,8 +1392,8 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
                                             const SDL_FRect * dstrect);
 
 /**
- * Copy a portion of the source texture to the current rendering target,
- * with rotation and flipping, at subpixel precision.
+ * Copy a portion of the source texture to the current rendering target, with
+ * rotation and flipping, at subpixel precision.
  *
  * \param renderer The renderer which should copy parts of a texture.
  * \param texture The source texture.
@@ -1400,10 +1401,13 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
  *                texture.
  * \param dstrect A pointer to the destination rectangle, or NULL for the
  *                entire rendering target.
- * \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction
- * \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2).
- * \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture
- *
+ * \param angle An angle in degrees that indicates the rotation that will be
+ *              applied to dstrect, rotating it in a clockwise direction
+ * \param center A pointer to a point indicating the point around which
+ *               dstrect will be rotated (if NULL, rotation will be done
+ *               around dstrect.w/2, dstrect.h/2).
+ * \param flip An SDL_RendererFlip value stating which flipping actions should
+ *             be performed on the texture
  * \return 0 on success, or -1 on error
  */
 extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer,
@@ -1443,8 +1447,7 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer,
                                                  void *pixels, int pitch);
 
 /**
- * Update the screen with any rendering performed since
- * the previous call.
+ * Update the screen with any rendering performed since the previous call.
  *
  * SDL's rendering functions operate on a backbuffer; that is, calling a
  * rendering function such as SDL_RenderDrawLine() does not directly put a
@@ -1504,9 +1507,9 @@ extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer);
  * Force the rendering context to flush any pending commands to the underlying
  * rendering API.
  *
- * You do not need to (and in fact, shouldn't) call this function unless
- * you are planning to call into OpenGL/Direct3D/Metal/whatever directly
- * in addition to using an SDL_Renderer.
+ * You do not need to (and in fact, shouldn't) call this function unless you
+ * are planning to call into OpenGL/Direct3D/Metal/whatever directly in
+ * addition to using an SDL_Renderer.
  *
  * This is for a very-specific case: if you are using SDL's render API, you
  * asked for a specific renderer backend (OpenGL, Direct3D, etc), you set
@@ -1519,9 +1522,9 @@ extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer);
  * maximum performance out of a specific situation. In all other cases, SDL
  * will do the right thing, perhaps at a performance loss.
  *
- * This function is first available in SDL 2.0.10, and is not needed in
- * 2.0.9 and earlier, as earlier versions did not queue rendering commands
- * at all, instead flushing them to the OS immediately.
+ * This function is first available in SDL 2.0.10, and is not needed in 2.0.9
+ * and earlier, as earlier versions did not queue rendering commands at all,
+ * instead flushing them to the OS immediately.
  *
  * \param renderer the rendering context
  * \returns 0 on success or a negative error code on failure; call
@@ -1589,10 +1592,10 @@ extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture);
  * headers, but it can be safely cast to a `CAMetalLayer *`.
  *
  * \param renderer The renderer to query
- * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a Metal
- *          renderer
+ * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a
+ *          Metal renderer
  *
- * \sa SDL_RenderGetMetalCommandEncoder()
+ * \sa SDL_RenderGetMetalCommandEncoder
  */
 extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
 
@@ -1603,10 +1606,10 @@ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
  * headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
  *
  * \param renderer The renderer to query
- * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the renderer
- *          isn't a Metal renderer.
+ * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the
+ *          renderer isn't a Metal renderer.
  *
- *  \sa SDL_RenderGetMetalLayer()
+ * \sa SDL_RenderGetMetalLayer
  */
 extern DECLSPEC void *SDLCALL SDL_RenderGetMetalCommandEncoder(SDL_Renderer * renderer);
 

include/SDL_rwops.h

@@ -230,8 +230,8 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context,
 /**
  * Determine the current read/write offset in an SDL_RWops data stream.
  *
- * SDL_RWtell is actually a wrapper function that calls the SDL_RWops's
- * `seek` method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify
+ * SDL_RWtell is actually a wrapper function that calls the SDL_RWops's `seek`
+ * method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify
  * application development.
  *
  * \param context a SDL_RWops data stream object from which to get the current
@@ -284,9 +284,9 @@ extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context,
  * Write to an SDL_RWops data stream.
  *
  * This function writes exactly `num` objects each of size `size` from the
- * area pointed at by `ptr` to the stream. If this fails for any reason,
- * it'll return less than `num` to demonstrate how far the write progressed.
- * On success, it returns `num`.
+ * area pointed at by `ptr` to the stream. If this fails for any reason, it'll
+ * return less than `num` to demonstrate how far the write progressed. On
+ * success, it returns `num`.
  *
  * SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's
  * `write` method appropriately, to simplify application development.
@@ -321,8 +321,8 @@ extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context,
  * Note that if this fails to flush the stream to disk, this function reports
  * an error, but the SDL_RWops is still invalid once this function returns.
  *
- * SDL_RWclose() is actually a macro that calls the SDL_RWops's `close`
- * method appropriately, to simplify application development.
+ * SDL_RWclose() is actually a macro that calls the SDL_RWops's `close` method
+ * appropriately, to simplify application development.
  *
  * \param context SDL_RWops structure to close
  * \returns 0 on success or a negative error code on failure; call

include/SDL_sensor.h

@@ -130,9 +130,9 @@ typedef enum
  * If you are using the sensor API or handling events from multiple threads
  * you should use these locking functions to protect access to the sensors.
  *
- * In particular, you are guaranteed that the sensor list won't change, so
- * the API functions that take a sensor index will be valid, and sensor
- * events will not be delivered.
+ * In particular, you are guaranteed that the sensor list won't change, so the
+ * API functions that take a sensor index will be valid, and sensor events
+ * will not be delivered.
  */
 extern DECLSPEC void SDLCALL SDL_LockSensors(void);
 extern DECLSPEC void SDLCALL SDL_UnlockSensors(void);
@@ -230,7 +230,7 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor)
 /**
  * Get the current state of an opened sensor.
  *
- *  The number of values and interpretation of the data is sensor dependent.
+ * The number of values and interpretation of the data is sensor dependent.
  *
  * \param sensor The SDL_Sensor object to query
  * \param data A pointer filled with the current sensor state

include/SDL_shape.h

@@ -44,33 +44,34 @@ extern "C" {
 #define SDL_WINDOW_LACKS_SHAPE -3
 
 /**
- *  \brief Create a window that can be shaped with the specified position, dimensions, and flags.
+ * Create a window that can be shaped with the specified position, dimensions,
+ * and flags.
  *
- *  \param title The title of the window, in UTF-8 encoding.
- *  \param x     The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
- *               ::SDL_WINDOWPOS_UNDEFINED.
- *  \param y     The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
- *               ::SDL_WINDOWPOS_UNDEFINED.
- *  \param w     The width of the window.
- *  \param h     The height of the window.
- *  \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with any of the following:
- *               ::SDL_WINDOW_OPENGL,     ::SDL_WINDOW_INPUT_GRABBED,
- *               ::SDL_WINDOW_HIDDEN,     ::SDL_WINDOW_RESIZABLE,
- *               ::SDL_WINDOW_MAXIMIZED,  ::SDL_WINDOW_MINIMIZED,
- *       ::SDL_WINDOW_BORDERLESS is always set, and ::SDL_WINDOW_FULLSCREEN is always unset.
+ * \param title The title of the window, in UTF-8 encoding.
+ * \param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
+ *          ::SDL_WINDOWPOS_UNDEFINED.
+ * \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
+ *          ::SDL_WINDOWPOS_UNDEFINED.
+ * \param w The width of the window.
+ * \param h The height of the window.
+ * \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with
+ *              any of the following: ::SDL_WINDOW_OPENGL,
+ *              ::SDL_WINDOW_INPUT_GRABBED, ::SDL_WINDOW_HIDDEN,
+ *              ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED,
+ *              ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_BORDERLESS is always set,
+ *              and ::SDL_WINDOW_FULLSCREEN is always unset.
+ * \return the window created, or NULL if window creation failed.
  *
- *  \return the window created, or NULL if window creation failed.
- *
- *  \sa SDL_DestroyWindow()
+ * \sa SDL_DestroyWindow
  */
 extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,unsigned int x,unsigned int y,unsigned int w,unsigned int h,Uint32 flags);
 
 /**
- * \brief Return whether the given window is a shaped window.
+ * Return whether the given window is a shaped window.
  *
  * \param window The window to query for being shaped.
- *
- * \return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if the window is unshaped or NULL.
+ * \return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if
+ *         the window is unshaped or NULL.
  *
  * \sa SDL_CreateShapedWindow
  */
@@ -106,29 +107,31 @@ typedef struct SDL_WindowShapeMode {
 } SDL_WindowShapeMode;
 
 /**
- * \brief Set the shape and parameters of a shaped window.
+ * Set the shape and parameters of a shaped window.
  *
  * \param window The shaped window whose parameters should be set.
  * \param shape A surface encoding the desired shape for the window.
  * \param shape_mode The parameters to set for the shaped window.
- *
- * \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape argument, or SDL_NONSHAPEABLE_WINDOW
- *           if the SDL_Window given does not reference a valid shaped window.
+ * \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape
+ *         argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
+ *         not reference a valid shaped window.
  *
  * \sa SDL_WindowShapeMode
- * \sa SDL_GetShapedWindowMode.
+ * \sa [[SDL_GetShapedWindowMode.]]
  */
 extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *shape,SDL_WindowShapeMode *shape_mode);
 
 /**
- * \brief Get the shape parameters of a shaped window.
+ * Get the shape parameters of a shaped window.
  *
  * \param window The shaped window whose parameters should be retrieved.
- * \param shape_mode An empty shape-mode structure to fill, or NULL to check whether the window has a shape.
- *
- * \return 0 if the window has a shape and, provided shape_mode was not NULL, shape_mode has been filled with the mode
- *           data, SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped window, or SDL_WINDOW_LACKS_SHAPE if
- *           the SDL_Window given is a shapeable window currently lacking a shape.
+ * \param shape_mode An empty shape-mode structure to fill, or NULL to check
+ *                   whether the window has a shape.
+ * \return 0 if the window has a shape and, provided shape_mode was not NULL,
+ *         shape_mode has been filled with the mode data,
+ *         SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped
+ *         window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a
+ *         shapeable window currently lacking a shape.
  *
  * \sa SDL_WindowShapeMode
  * \sa SDL_SetWindowShape

include/SDL_stdinc.h

@@ -403,7 +403,7 @@ typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size);
 typedef void (SDLCALL *SDL_free_func)(void *mem);
 
 /**
- *  \brief Get the current set of SDL memory functions
+ * Get the current set of SDL memory functions
  */
 extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func,
                                                     SDL_calloc_func *calloc_func,
@@ -411,12 +411,7 @@ extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func
                                                     SDL_free_func *free_func);
 
 /**
- *  \brief Replace SDL's memory allocation functions with a custom set
- *
- *  \note If you are replacing SDL's memory functions, you should call
- *        SDL_GetNumAllocations() and be very careful if it returns non-zero.
- *        That means that your free function will be called with memory
- *        allocated by the previous memory allocation functions.
+ * Replace SDL's memory allocation functions with a custom set
  */
 extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
                                                    SDL_calloc_func calloc_func,
@@ -424,7 +419,7 @@ extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
                                                    SDL_free_func free_func);
 
 /**
- *  \brief Get the number of outstanding (unfreed) allocations
+ * Get the number of outstanding (unfreed) allocations
  */
 extern DECLSPEC int SDLCALL SDL_GetNumAllocations(void);
 
@@ -625,8 +620,8 @@ extern DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf,
                                          size_t * inbytesleft, char **outbuf,
                                          size_t * outbytesleft);
 /**
- *  This function converts a string between encodings in one pass, returning a
- *  string that must be freed with SDL_free() or NULL on error.
+ * This function converts a string between encodings in one pass, returning a
+ * string that must be freed with SDL_free() or NULL on error.
  */
 extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode,
                                                const char *fromcode,

include/SDL_surface.h

@@ -188,8 +188,8 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat
  * not allocate memory for the pixel data, instead the caller provides an
  * existing buffer of data for the surface to use.
  *
- * No copy is made of the pixel data. Pixel data is not managed
- * automatically; you must free the surface before you free the pixel data.
+ * No copy is made of the pixel data. Pixel data is not managed automatically;
+ * you must free the surface before you free the pixel data.
  *
  * \param pixels a pointer to existing pixel data
  * \param width the width of the surface
@@ -226,8 +226,8 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
  * instead of providing pixel color masks, you provide it with a predefined
  * format from SDL_PixelFormatEnum.
  *
- * No copy is made of the pixel data. Pixel data is not managed
- * automatically; you must free the surface before you free the pixel data.
+ * No copy is made of the pixel data. Pixel data is not managed automatically;
+ * you must free the surface before you free the pixel data.
  *
  * \param pixels a pointer to existing pixel data
  * \param width the width of the surface
@@ -298,7 +298,7 @@ extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
  *
  * \param surface the SDL_Surface structure to be unlocked
  *
- * \sa SDL_LockSurface()
+ * \sa SDL_LockSurface
  */
 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
 
@@ -545,8 +545,8 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
 /**
  * Set the clipping rectangle for a surface.
  *
- * When `surface` is the destination of a blit, only the area within the
- * clip rectangle is drawn into.
+ * When `surface` is the destination of a blit, only the area within the clip
+ * rectangle is drawn into.
  *
  * Note that blits are automatically clipped to the edges of the source and
  * destination surfaces.
@@ -566,8 +566,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
 /**
  * Get the clipping rectangle for a surface.
  *
- * When `surface` is the destination of a blit, only the area within the
- * clip rectangle is drawn into.
+ * When `surface` is the destination of a blit, only the area within the clip
+ * rectangle is drawn into.
  *
  * \param surface the SDL_Surface structure representing the surface to be
  *                clipped
@@ -618,8 +618,8 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
  * Copy an existing surface to a new surface of the specified format enum.
  *
  * This function operates just like SDL_ConvertSurface(), but accepts an
- * SDL_PixelFormatEnum value instead of an SDL_PixelFormat structure. As
- * such, it might be easier to call but it doesn't have access to palette
+ * SDL_PixelFormatEnum value instead of an SDL_PixelFormat structure. As such,
+ * it might be easier to call but it doesn't have access to palette
  * information for the destination surface, in case that would be important.
  *
  * \param src the existing SDL_Surface structure to convert
@@ -768,8 +768,8 @@ extern DECLSPEC int SDLCALL SDL_FillRects
 /**
  * Perform a fast blit from the source surface to the destination surface.
  *
- * SDL_UpperBlit() has been replaced by SDL_BlitSurface(), which is merely
- * a macro for this function with a less confusing name.
+ * SDL_UpperBlit() has been replaced by SDL_BlitSurface(), which is merely a
+ * macro for this function with a less confusing name.
  *
  * \sa SDL_BlitSurface
  */
@@ -868,7 +868,8 @@ extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mo
 extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void);
 
 /**
- * Get the YUV conversion mode, returning the correct mode for the resolution when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
+ * Get the YUV conversion mode, returning the correct mode for the resolution
+ * when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
  */
 extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionModeForResolution(int width, int height);
 

include/SDL_system.h

@@ -178,8 +178,8 @@ extern DECLSPEC void * SDLCALL SDL_AndroidGetJNIEnv(void);
  * return type, even if the implementation returns a jobject. The rationale
  * being that the SDL headers can avoid including jni.h.
  *
- * The jobject returned by the function is a local reference and must
- * be released by the caller. See the PushLocalFrame() and PopLocalFrame() or
+ * The jobject returned by the function is a local reference and must be
+ * released by the caller. See the PushLocalFrame() and PopLocalFrame() or
  * DeleteLocalRef() functions of the Java native interface:
  *
  * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
@@ -311,8 +311,7 @@ extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void);
 /**
  * Request permissions at runtime.
  *
- * This blocks the calling thread until the permission is granted or
- * denied.
+ * This blocks the calling thread until the permission is granted or denied.
  *
  * \param permission The permission to request.
  * \returns SDL_TRUE if the permission was granted, SDL_FALSE otherwise.

include/SDL_syswm.h

@@ -351,8 +351,8 @@ typedef struct SDL_SysWMinfo SDL_SysWMinfo;
  * You must include SDL_syswm.h for the declaration of SDL_SysWMinfo.
  *
  * The caller must initialize the `info` structure's version by using
- * `SDL_VERSION(&info.version)`, and then this function will fill in the
- * rest of the structure with information about the given window.
+ * `SDL_VERSION(&info.version)`, and then this function will fill in the rest
+ * of the structure with information about the given window.
  *
  * \param window the window about which information is being requested
  * \param info an SDL_SysWMinfo structure filled in with window information

include/SDL_thread.h

@@ -214,30 +214,29 @@ SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data);
 /**
  * Create a new thread with a specific stack size.
  *
- * SDL makes an attempt to report `name` to the system, so that debuggers
- * can display it. Not all platforms support this.
- *
- * Thread naming is a little complicated: Most systems have very small
- * limits for the string length (Haiku has 32 bytes, Linux currently has 16,
- * Visual C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll
- * have to see what happens with your system's debugger. The name should be
- * UTF-8 (but using the naming limits of C identifiers is a better bet).
- * There are no requirements for thread naming conventions, so long as the
- * string is null-terminated UTF-8, but these guidelines are helpful in
- * choosing a name:
+ * SDL makes an attempt to report `name` to the system, so that debuggers can
+ * display it. Not all platforms support this.
+ *
+ * Thread naming is a little complicated: Most systems have very small limits
+ * for the string length (Haiku has 32 bytes, Linux currently has 16, Visual
+ * C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll have to
+ * see what happens with your system's debugger. The name should be UTF-8 (but
+ * using the naming limits of C identifiers is a better bet). There are no
+ * requirements for thread naming conventions, so long as the string is
+ * null-terminated UTF-8, but these guidelines are helpful in choosing a name:
  *
  * https://stackoverflow.com/questions/149932/naming-conventions-for-threads
  *
- * If a system imposes requirements, SDL will try to munge the string for
- * it (truncate, etc), but the original string contents will be available
- * from SDL_GetThreadName().
+ * If a system imposes requirements, SDL will try to munge the string for it
+ * (truncate, etc), but the original string contents will be available from
+ * SDL_GetThreadName().
  *
- * The size (in bytes) of the new stack can be specified. Zero means "use
- * the system default" which might be wildly different between platforms.
- * x86 Linux generally defaults to eight megabytes, an embedded device
- * might be a few kilobytes instead. You generally need to specify a stack
- * that is a multiple of the system's page size (in many cases, this is 4
- * kilobytes, but check your system documentation).
+ * The size (in bytes) of the new stack can be specified. Zero means "use the
+ * system default" which might be wildly different between platforms. x86
+ * Linux generally defaults to eight megabytes, an embedded device might be a
+ * few kilobytes instead. You generally need to specify a stack that is a
+ * multiple of the system's page size (in many cases, this is 4 kilobytes, but
+ * check your system documentation).
  *
  * In SDL 2.1, stack size will be folded into the original SDL_CreateThread
  * function, but for backwards compatibility, this is currently a separate
@@ -307,8 +306,8 @@ extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread);
  * Set the priority for the current thread.
  *
  * Note that some platforms will not let you alter the priority (or at least,
- * promote the thread to a higher priority) at all, and some require you
- * to be an administrator account. Be prepared for this to fail.
+ * promote the thread to a higher priority) at all, and some require you to be
+ * an administrator account. Be prepared for this to fail.
  *
  * \param priority the SDL_ThreadPriority to set
  * \returns 0 on success or a negative error code on failure; call
@@ -388,8 +387,8 @@ extern DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread * thread);
 /**
  * Create a piece of thread-local storage.
  *
- * This creates an identifier that is globally visible to all
- * threads but refers to data that is thread-specific.
+ * This creates an identifier that is globally visible to all threads but
+ * refers to data that is thread-specific.
  *
  * \returns the newly created thread local storage identifier or 0 on error.
  *
@@ -440,7 +439,7 @@ extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id);
 extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, void (SDLCALL *destructor)(void*));
 
 /**
- *  \brief Cleanup all TLS data for this thread.
+ * Cleanup all TLS data for this thread.
  */
 extern DECLSPEC void SDLCALL SDL_TLSCleanup(void);
 

include/SDL_video.h

@@ -443,7 +443,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayDPI(int displayIndex, float * ddpi, fl
  * \returns The SDL_DisplayOrientation enum value of the display, or
  *          `SDL_ORIENTATION_UNKNOWN` if it isn't available.
  *
- * \sa SDL_GetNumVideoDisplays()
+ * \sa SDL_GetNumVideoDisplays
  */
 extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int displayIndex);
 
@@ -532,12 +532,12 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_Disp
 /**
  * Get the closest match to the requested display mode.
  *
- * The available display modes are scanned and `closest` is filled in with
- * the closest mode matching the requested mode and returned. The mode format
- * and refresh rate default to the desktop mode if they are set to 0. The
- * modes are scanned with size being first priority, format being second
- * priority, and finally checking the refresh rate. If all the available modes
- * are too small, then NULL is returned.
+ * The available display modes are scanned and `closest` is filled in with the
+ * closest mode matching the requested mode and returned. The mode format and
+ * refresh rate default to the desktop mode if they are set to 0. The modes
+ * are scanned with size being first priority, format being second priority,
+ * and finally checking the refresh rate. If all the available modes are too
+ * small, then NULL is returned.
  *
  * \param displayIndex the index of the display to query
  * \param mode an SDL_DisplayMode structure containing the desired display
@@ -547,8 +547,8 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_Disp
  * \returns the passed in value `closest` or NULL if no matching video mode
  *          was available; call SDL_GetError() for more information.
  *
- * \sa  SDL_GetDisplayMode
- * \sa  SDL_GetNumDisplayModes
+ * \sa SDL_GetDisplayMode
+ * \sa SDL_GetNumDisplayModes
  */
 extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest);
 
@@ -638,13 +638,13 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
  *
  * If the window is created with the `SDL_WINDOW_ALLOW_HIGHDPI` flag, its size
  * in pixels may differ from its size in screen coordinates on platforms with
- * high-DPI support (e.g. iOS and macOS). Use SDL_GetWindowSize() to query
- * the client area's size in screen coordinates, and SDL_GL_GetDrawableSize()
- * or SDL_GetRendererOutputSize() to query the drawable size in pixels.
+ * high-DPI support (e.g. iOS and macOS). Use SDL_GetWindowSize() to query the
+ * client area's size in screen coordinates, and SDL_GL_GetDrawableSize() or
+ * SDL_GetRendererOutputSize() to query the drawable size in pixels.
  *
  * If the window is set fullscreen, the width and height parameters `w` and
- * `h` will not be used. However, invalid size parameters (e.g. too large)
- * may still fail. Window size is actually limited to 16384 x 16384 for all
+ * `h` will not be used. However, invalid size parameters (e.g. too large) may
+ * still fail. Window size is actually limited to 16384 x 16384 for all
  * platforms at window creation.
  *
  * If the window is created with any of the SDL_WINDOW_OPENGL or
@@ -722,8 +722,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window);
  * these events to specific SDL_Window objects.
  *
  * \param id the ID of the window
- * \returns the window associated with `id` or NULL if it doesn't exist;
- *          call SDL_GetError() for more information.
+ * \returns the window associated with `id` or NULL if it doesn't exist; call
+ *          SDL_GetError() for more information.
  *
  * \sa SDL_GetWindowID
  */
@@ -1083,8 +1083,8 @@ extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window);
  *
  * \param window the window to restore
  *
- * \sa  SDL_MaximizeWindow
- * \sa  SDL_MinimizeWindow
+ * \sa SDL_MaximizeWindow
+ * \sa SDL_MinimizeWindow
  */
 extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window);
 
@@ -1190,8 +1190,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window,
 /**
  * Set a window's keyboard grab mode.
  *
- * If the caller enables a grab while another window is currently grabbed,
- * the other window loses its grab in favor of the caller's window.
+ * If the caller enables a grab while another window is currently grabbed, the
+ * other window loses its grab in favor of the caller's window.
  *
  * \param window The window for which the keyboard grab mode should be set.
  * \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release.
@@ -1207,10 +1207,6 @@ extern DECLSPEC void SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window * window,
  * Set a window's mouse grab mode.
  *
  * \param window The window for which the mouse grab mode should be set.
- * \param grabbed This is SDL_TRUE to grab mouse, and SDL_FALSE to release.
- *
- * If the caller enables a grab while another window is currently grabbed,
- * the other window loses its grab in favor of the caller's window.
  *
  * \sa SDL_GetWindowMouseGrab
  * \sa SDL_SetWindowKeyboardGrab
@@ -1513,12 +1509,12 @@ extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window,
 /**
  * Request a window to demand attention from the user.
  *
+ * \param window the window to request the flashing for
+ * \param flash_count number of times the window gets flashed on systems that
+ *                    support flashing the window multiple times, like
+ *                    Windows, else it is ignored
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
- *
- * \param window the window to request the flashing for
- * \param flash_count number of times the window gets flashed on systems that support flashing the
- *                    window multiple times, like Windows, else it is ignored
  */
 extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, Uint32 flash_count);
 
@@ -1615,34 +1611,34 @@ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
  * these quirks without any platform-specific code, though:
  *
  * - On Windows, function pointers are specific to the current GL context;
- * this means you need to have created a GL context and made it current before
- * calling SDL_GL_GetProcAddress(). If you recreate your context or create a
- * second context, you should assume that any existing function pointers
- * aren't valid to use with it. This is (currently) a Windows-specific
- * limitation, and in practice lots of drivers don't suffer this limitation,
- * but it is still the way the wgl API is documented to work and you should
- * expect crashes if you don't respect it. Store a copy of the function
- * pointers that comes and goes with context lifespan.
+ *   this means you need to have created a GL context and made it current
+ *   before calling SDL_GL_GetProcAddress(). If you recreate your context or
+ *   create a second context, you should assume that any existing function
+ *   pointers aren't valid to use with it. This is (currently) a
+ *   Windows-specific limitation, and in practice lots of drivers don't suffer
+ *   this limitation, but it is still the way the wgl API is documented to
+ *   work and you should expect crashes if you don't respect it. Store a copy
+ *   of the function pointers that comes and goes with context lifespan.
  * - On X11, function pointers returned by this function are valid for any
- * context, and can even be looked up before a context is created at all. This
- * means that, for at least some common OpenGL implementations, if you look up
- * a function that doesn't exist, you'll get a non-NULL result that is _NOT_
- * safe to call. You must always make sure the function is actually available
- * for a given GL context before calling it, by checking for the existence of
- * the appropriate extension with SDL_GL_ExtensionSupported(), or verifying
- * that the version of OpenGL you're using offers the function as core
- * functionality.
+ *   context, and can even be looked up before a context is created at all.
+ *   This means that, for at least some common OpenGL implementations, if you
+ *   look up a function that doesn't exist, you'll get a non-NULL result that
+ *   is _NOT_ safe to call. You must always make sure the function is actually
+ *   available for a given GL context before calling it, by checking for the
+ *   existence of the appropriate extension with SDL_GL_ExtensionSupported(),
+ *   or verifying that the version of OpenGL you're using offers the function
+ *   as core functionality.
  * - Some OpenGL drivers, on all platforms, *will* return NULL if a function
- * isn't supported, but you can't count on this behavior. Check for extensions
- * you use, and if you get a NULL anyway, act as if that extension wasn't
- * available. This is probably a bug in the driver, but you can code
- * defensively for this scenario anyhow.
+ *   isn't supported, but you can't count on this behavior. Check for
+ *   extensions you use, and if you get a NULL anyway, act as if that
+ *   extension wasn't available. This is probably a bug in the driver, but you
+ *   can code defensively for this scenario anyhow.
  * - Just because you're on Linux/Unix, don't assume you'll be using X11.
- * Next-gen display servers are waiting to replace it, and may or may not make
- * the same promises about function pointers.
+ *   Next-gen display servers are waiting to replace it, and may or may not
+ *   make the same promises about function pointers.
  * - OpenGL function pointers must be declared `APIENTRY` as in the example
- * code. This will ensure the proper calling convention is followed on
- * platforms where this matters (Win32) thereby avoiding stack corruption.
+ *   code. This will ensure the proper calling convention is followed on
+ *   platforms where this matters (Win32) thereby avoiding stack corruption.
  *
  * \param proc the name of an OpenGL function
  * \returns a pointer to the named OpenGL function. The returned pointer
@@ -1690,18 +1686,17 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char
  *
  * \sa SDL_GL_GetAttribute
  * \sa SDL_GL_SetAttribute
- * \sa <!-- #Remove this section if empty -->
+ * \sa [[<!-- #Remove this section if empty -->]]
  */
 extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void);
 
 /**
  * Set an OpenGL window attribute before window creation.
  *
- * This function sets the OpenGL attribute `attr` to `value`. The
- * requested attributes should be set before creating an OpenGL window. You
- * should use SDL_GL_GetAttribute() to check the values after creating the
- * OpenGL context, since the values obtained can differ from the requested
- * ones.
+ * This function sets the OpenGL attribute `attr` to `value`. The requested
+ * attributes should be set before creating an OpenGL window. You should use
+ * SDL_GL_GetAttribute() to check the values after creating the OpenGL
+ * context, since the values obtained can differ from the requested ones.
  *
  * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to set
  * \param value the desired value for the attribute
@@ -1738,8 +1733,8 @@ extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value);
  * SDL_GLContext is an alias for `void *`. It's opaque to the application.
  *
  * \param window the window to associate with the context
- * \returns the OpenGL context associated with `window` or NULL on error;
- *          call SDL_GetError() for more details.
+ * \returns the OpenGL context associated with `window` or NULL on error; call
+ *          SDL_GetError() for more details.
  *
  * \sa SDL_GL_DeleteContext
  * \sa SDL_GL_MakeCurrent
@@ -1813,8 +1808,8 @@ extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w,
  * Some systems allow specifying -1 for the interval, to enable adaptive
  * vsync. Adaptive vsync works the same as vsync, but if you've already missed
  * the vertical retrace for a given frame, it swaps buffers immediately, which
- * might be less jarring for the user during occasional framerate drops. If
- * an application requests adaptive vsync and the system does not support it,
+ * might be less jarring for the user during occasional framerate drops. If an
+ * application requests adaptive vsync and the system does not support it,
  * this function will fail and return -1. In such a case, you should probably
  * retry the call with 1 for the interval.
  *
@@ -1863,8 +1858,8 @@ extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void);
  *
  * This is used with double-buffered OpenGL contexts, which are the default.
  *
- * On macOS, make sure you bind 0 to the draw framebuffer before swapping
- * the window, otherwise nothing will happen. If you aren't using
+ * On macOS, make sure you bind 0 to the draw framebuffer before swapping the
+ * window, otherwise nothing will happen. If you aren't using
  * glBindFramebuffer(), this is the default and you won't have to do anything
  * extra.
  *

include/SDL_vulkan.h

@@ -77,21 +77,21 @@ typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */
  * application links to a dynamic library and both it and SDL use the same
  * search path.
  *
- * If you specify a non-NULL `path`, an application should retrieve
- * all of the Vulkan functions it uses from the dynamic library using
- * SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path`
- * points to the same vulkan loader library the application linked to.
+ * If you specify a non-NULL `path`, an application should retrieve all of the
+ * Vulkan functions it uses from the dynamic library using
+ * SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path` points
+ * to the same vulkan loader library the application linked to.
  *
  * On Apple devices, if `path` is NULL, SDL will attempt to find the
- * `vkGetInstanceProcAddr` address within all the Mach-O images of the
- * current process. This is because it is fairly common for Vulkan
- * applications to link with libvulkan (and historically MoltenVK was provided
- * as a static library). If it is not found, on macOS, SDL will attempt
- * to load `vulkan.framework/vulkan`, `libvulkan.1.dylib`,
- * `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that
- * order. On iOS, SDL will attempt to load `libMoltenVK.dylib`.
- * Applications using a dynamic framework or .dylib must ensure it is included
- * in its application bundle.
+ * `vkGetInstanceProcAddr` address within all the Mach-O images of the current
+ * process. This is because it is fairly common for Vulkan applications to
+ * link with libvulkan (and historically MoltenVK was provided as a static
+ * library). If it is not found, on macOS, SDL will attempt to load
+ * `vulkan.framework/vulkan`, `libvulkan.1.dylib`,
+ * `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that order. On
+ * iOS, SDL will attempt to load `libMoltenVK.dylib`. Applications using a
+ * dynamic framework or .dylib must ensure it is included in its application
+ * bundle.
  *
  * On non-Apple devices, application linking with a static libvulkan is not
  * supported. Either do not link to the Vulkan loader or link to a dynamic
@@ -111,8 +111,8 @@ extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
 /**
  * Get the address of the `vkGetInstanceProcAddr` function.
  *
- * This should be called after either calling SDL_Vulkan_LoadLibrary()
- * or creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
+ * This should be called after either calling SDL_Vulkan_LoadLibrary() or
+ * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
  *
  * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error.
  */
@@ -128,29 +128,27 @@ extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);
 extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
 
 /**
- * Get the names of the Vulkan instance extensions needed
- * to create a surface with SDL_Vulkan_CreateSurface.
- *
- * If `pNames` is NULL, then the number of required Vulkan instance
- * extensions is returned in `pCount`. Otherwise, `pCount` must point
- * to a variable set to the number of elements in the `pNames` array, and
- * on return the variable is overwritten with the number of names actually
- * written to `pNames`. If `pCount` is less than the number of
- * required extensions, at most `pCount` structures will be written. If
- * `pCount` is smaller than the number of required extensions,
- * SDL_FALSE will be returned instead of SDL_TRUE, to indicate
- * that not all the required extensions were returned.
- *
- * The `window` parameter is currently needed to be valid as of
- * SDL 2.0.8, however, this parameter will likely be removed in future
- * releases
+ * Get the names of the Vulkan instance extensions needed to create a surface
+ * with SDL_Vulkan_CreateSurface.
+ *
+ * If `pNames` is NULL, then the number of required Vulkan instance extensions
+ * is returned in `pCount`. Otherwise, `pCount` must point to a variable set
+ * to the number of elements in the `pNames` array, and on return the variable
+ * is overwritten with the number of names actually written to `pNames`. If
+ * `pCount` is less than the number of required extensions, at most `pCount`
+ * structures will be written. If `pCount` is smaller than the number of
+ * required extensions, SDL_FALSE will be returned instead of SDL_TRUE, to
+ * indicate that not all the required extensions were returned.
+ *
+ * The `window` parameter is currently needed to be valid as of SDL 2.0.8,
+ * however, this parameter will likely be removed in future releases
  *
  * \param window A window for which the required Vulkan instance extensions
  *               should be retrieved (will be deprecated in a future release)
- * \param pCount A pointer to an unsigned int corresponding to the
- *               number of extensions to be returned
+ * \param pCount A pointer to an unsigned int corresponding to the number of
+ *               extensions to be returned
  * \param pNames NULL or a pointer to an array to be filled with required
- *              Vulkan instance extensions
+ *               Vulkan instance extensions
  * \returns SDL_TRUE on success, SDL_FALSE on error.
  *
  * \since This function is available in SDL 2.0.8
@@ -187,8 +185,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window,
  * Get the size of the window's underlying drawable dimensions in pixels.
  *
  * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
- * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI`
- * on a platform with high-DPI support (Apple calls this "Retina"), and not
+ * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a
+ * platform with high-DPI support (Apple calls this "Retina"), and not
  * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint.
  *
  * \param window an SDL_Window for which the size is to be queried