sdl2-compat: sync headers with latest SDL2. (77ea9)

From 77ea923e831a05803a44f652393f20b73fe8ad21 Mon Sep 17 00:00:00 2001
From: Ozkan Sezer <[EMAIL REDACTED]>
Date: Tue, 28 May 2024 00:56:50 +0300
Subject: [PATCH] sync headers with latest SDL2.

---
 include/SDL2/SDL.h                |    3 +-
 include/SDL2/SDL_atomic.h         |   44 +-
 include/SDL2/SDL_audio.h          |   76 +-
 include/SDL2/SDL_bits.h           |   10 +-
 include/SDL2/SDL_blendmode.h      |   11 +-
 include/SDL2/SDL_clipboard.h      |    2 +-
 include/SDL2/SDL_config.h         |    4 +-
 include/SDL2/SDL_config_minimal.h |    4 -
 include/SDL2/SDL_config_windows.h |    4 +-
 include/SDL2/SDL_cpuinfo.h        |   10 +-
 include/SDL2/SDL_egl.h            |    7 +-
 include/SDL2/SDL_endian.h         |   43 +-
 include/SDL2/SDL_error.h          |    4 +-
 include/SDL2/SDL_events.h         |  191 +-
 include/SDL2/SDL_filesystem.h     |    4 +-
 include/SDL2/SDL_gamecontroller.h |   33 +-
 include/SDL2/SDL_gesture.h        |    4 +-
 include/SDL2/SDL_guid.h           |   41 +-
 include/SDL2/SDL_haptic.h         |  654 ++++---
 include/SDL2/SDL_hidapi.h         |   66 +-
 include/SDL2/SDL_hints.h          | 3022 ++++++++++++++++-------------
 include/SDL2/SDL_joystick.h       |   60 +-
 include/SDL2/SDL_keyboard.h       |   17 +-
 include/SDL2/SDL_keycode.h        |   20 +-
 include/SDL2/SDL_loadso.h         |   34 +-
 include/SDL2/SDL_locale.h         |    4 +-
 include/SDL2/SDL_log.h            |   32 +-
 include/SDL2/SDL_main.h           |   10 +-
 include/SDL2/SDL_messagebox.h     |   10 +-
 include/SDL2/SDL_metal.h          |    9 +-
 include/SDL2/SDL_misc.h           |    4 +-
 include/SDL2/SDL_mouse.h          |   14 +-
 include/SDL2/SDL_mutex.h          |   10 +-
 include/SDL2/SDL_opengl.h         |   14 +-
 include/SDL2/SDL_opengles.h       |    7 +-
 include/SDL2/SDL_opengles2.h      |    7 +-
 include/SDL2/SDL_pixels.h         |   36 +-
 include/SDL2/SDL_platform.h       |   10 +-
 include/SDL2/SDL_power.h          |    6 +-
 include/SDL2/SDL_quit.h           |   34 +-
 include/SDL2/SDL_rect.h           |    4 +-
 include/SDL2/SDL_render.h         |   39 +-
 include/SDL2/SDL_rwops.h          |   19 +-
 include/SDL2/SDL_scancode.h       |   16 +-
 include/SDL2/SDL_sensor.h         |  115 +-
 include/SDL2/SDL_shape.h          |   18 +-
 include/SDL2/SDL_stdinc.h         |   51 +-
 include/SDL2/SDL_surface.h        |  142 +-
 include/SDL2/SDL_system.h         |   22 +-
 include/SDL2/SDL_syswm.h          |   33 +-
 include/SDL2/SDL_test.h           |    2 +-
 include/SDL2/SDL_test_assert.h    |   18 +-
 include/SDL2/SDL_test_common.h    |   20 +-
 include/SDL2/SDL_test_compare.h   |    4 +-
 include/SDL2/SDL_test_font.h      |   22 +-
 include/SDL2/SDL_test_fuzzer.h    |   57 +-
 include/SDL2/SDL_test_harness.h   |   10 +-
 include/SDL2/SDL_test_images.h    |    4 +-
 include/SDL2/SDL_test_log.h       |    6 +-
 include/SDL2/SDL_test_md5.h       |    8 +-
 include/SDL2/SDL_test_memory.h    |    6 +-
 include/SDL2/SDL_test_random.h    |    8 +-
 include/SDL2/SDL_thread.h         |   18 +-
 include/SDL2/SDL_timer.h          |   22 +-
 include/SDL2/SDL_touch.h          |    4 +-
 include/SDL2/SDL_types.h          |    7 +-
 include/SDL2/SDL_version.h        |   55 +-
 include/SDL2/SDL_video.h          |  110 +-
 include/SDL2/SDL_vulkan.h         |    6 +-
 include/SDL2/begin_code.h         |   10 +-
 70 files changed, 2984 insertions(+), 2447 deletions(-)

diff --git a/include/SDL2/SDL.h b/include/SDL2/SDL.h
index 20c903b..c3eecbc 100644
--- a/include/SDL2/SDL.h
+++ b/include/SDL2/SDL.h
@@ -25,7 +25,6 @@
  *  Main include header for the SDL library
  */
 
-
 #ifndef SDL_h_
 #define SDL_h_
 
@@ -70,6 +69,8 @@
 extern "C" {
 #endif
 
+/* WIKI CATEGORY: Init */
+
 /* As of version 0.5, SDL is loaded dynamically into the application */
 
 /**
diff --git a/include/SDL2/SDL_atomic.h b/include/SDL2/SDL_atomic.h
index cb1cc6f..d8cb3c0 100644
--- a/include/SDL2/SDL_atomic.h
+++ b/include/SDL2/SDL_atomic.h
@@ -20,38 +20,29 @@
 */
 
 /**
- * \file SDL_atomic.h
+ * # CategoryAtomic
  *
  * Atomic operations.
  *
- * IMPORTANT:
- * If you are not an expert in concurrent lockless programming, you should
- * only be using the atomic lock and reference counting functions in this
- * file.  In all other cases you should be protecting your data structures
- * with full mutexes.
+ * IMPORTANT: If you are not an expert in concurrent lockless programming, you
+ * should not be using any functions in this file. You should be protecting
+ * your data structures with full mutexes instead.
  *
- * The list of "safe" functions to use are:
- *  SDL_AtomicLock()
- *  SDL_AtomicUnlock()
- *  SDL_AtomicIncRef()
- *  SDL_AtomicDecRef()
+ * ***Seriously, here be dragons!***
  *
- * Seriously, here be dragons!
- * ^^^^^^^^^^^^^^^^^^^^^^^^^^^
- *
- * You can find out a little more about lockless programming and the
- * subtle issues that can arise here:
- * http://msdn.microsoft.com/en-us/library/ee418650%28v=vs.85%29.aspx
+ * You can find out a little more about lockless programming and the subtle
+ * issues that can arise here:
+ * https://learn.microsoft.com/en-us/windows/win32/dxtecharts/lockless-programming
  *
  * There's also lots of good information here:
- * http://www.1024cores.net/home/lock-free-algorithms
- * http://preshing.com/
  *
- * These operations may or may not actually be implemented using
- * processor specific atomic operations. When possible they are
- * implemented as true processor specific atomic operations. When that
- * is not possible the are implemented using locks that *do* use the
- * available atomic operations.
+ * - https://www.1024cores.net/home/lock-free-algorithms
+ * - https://preshing.com/
+ *
+ * These operations may or may not actually be implemented using processor
+ * specific atomic operations. When possible they are implemented as true
+ * processor specific atomic operations. When that is not possible the are
+ * implemented using locks that *do* use the available atomic operations.
  *
  * All of the atomic operations that modify memory are full memory barriers.
  */
@@ -257,8 +248,9 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
 
 
 /**
- * \brief A type representing an atomic integer value.  It is a struct
- *        so people don't accidentally use numeric operations on it.
+ * A type representing an atomic integer value.
+ *
+ * It is a struct so people don't accidentally use numeric operations on it.
  */
 typedef struct SDL_atomic_t {
     int value;
diff --git a/include/SDL2/SDL_audio.h b/include/SDL2/SDL_audio.h
index df09c3a..936b78a 100644
--- a/include/SDL2/SDL_audio.h
+++ b/include/SDL2/SDL_audio.h
@@ -22,9 +22,9 @@
 /* !!! FIXME: several functions in here need Doxygen comments. */
 
 /**
- *  \file SDL_audio.h
+ * # CategoryAudio
  *
- *  Access to the raw audio mixing buffer for the SDL library.
+ * Access to the raw audio mixing buffer for the SDL library.
  */
 
 #ifndef SDL_audio_h_
@@ -149,33 +149,30 @@ typedef Uint16 SDL_AudioFormat;
 /* @} *//* Audio flags */
 
 /**
- *  This function is called when the audio device needs more data.
+ * This function is called when the audio device needs more data.
  *
- *  \param userdata An application-specific parameter saved in
- *                  the SDL_AudioSpec structure
- *  \param stream A pointer to the audio data buffer.
- *  \param len    The length of that buffer in bytes.
- *
- *  Once the callback returns, the buffer will no longer be valid.
- *  Stereo samples are stored in a LRLRLR ordering.
- *
- *  You can choose to avoid callbacks and use SDL_QueueAudio() instead, if
- *  you like. Just open your audio device with a NULL callback.
+ * \param userdata An application-specific parameter saved in the
+ *                 SDL_AudioSpec structure
+ * \param stream A pointer to the audio data buffer.
+ * \param len Length of **stream** in bytes.
  */
 typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
                                             int len);
 
 /**
- *  The calculated values in this structure are calculated by SDL_OpenAudio().
- *
- *  For multi-channel audio, the default SDL channel mapping is:
- *  2:  FL  FR                          (stereo)
- *  3:  FL  FR LFE                      (2.1 surround)
- *  4:  FL  FR  BL  BR                  (quad)
- *  5:  FL  FR LFE  BL  BR              (4.1 surround)
- *  6:  FL  FR  FC LFE  SL  SR          (5.1 surround - last two can also be BL BR)
- *  7:  FL  FR  FC LFE  BC  SL  SR      (6.1 surround)
- *  8:  FL  FR  FC LFE  BL  BR  SL  SR  (7.1 surround)
+ * The calculated values in this structure are calculated by SDL_OpenAudio().
+ *
+ * For multi-channel audio, the default SDL channel mapping is:
+ *
+ * ```
+ * 2:  FL  FR                          (stereo)
+ * 3:  FL  FR LFE                      (2.1 surround)
+ * 4:  FL  FR  BL  BR                  (quad)
+ * 5:  FL  FR LFE  BL  BR              (4.1 surround)
+ * 6:  FL  FR  FC LFE  SL  SR          (5.1 surround - last two can also be BL BR)
+ * 7:  FL  FR  FC LFE  BC  SL  SR      (6.1 surround)
+ * 8:  FL  FR  FC LFE  BL  BR  SL  SR  (7.1 surround)
+ * ```
  */
 typedef struct SDL_AudioSpec
 {
@@ -196,11 +193,11 @@ typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
                                           SDL_AudioFormat format);
 
 /**
- *  \brief Upper limit of filters in SDL_AudioCVT
+ * Upper limit of filters in SDL_AudioCVT
  *
- *  The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is
- *  currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers,
- *  one of which is the terminating NULL pointer.
+ * The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is
+ * currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers, one
+ * of which is the terminating NULL pointer.
  */
 #define SDL_AUDIOCVT_MAX_FILTERS 9
 
@@ -408,13 +405,13 @@ extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
                                           SDL_AudioSpec * obtained);
 
 /**
- *  SDL Audio Device IDs.
+ * SDL Audio Device IDs.
  *
- *  A successful call to SDL_OpenAudio() is always device id 1, and legacy
- *  SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
- *  always returns devices >= 2 on success. The legacy calls are good both
- *  for backwards compatibility and when you don't care about multiple,
- *  specific, or capture devices.
+ * A successful call to SDL_OpenAudio() is always device id 1, and legacy SDL
+ * audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
+ * always returns devices >= 2 on success. The legacy calls are good both for
+ * backwards compatibility and when you don't care about multiple, specific,
+ * or capture devices.
  */
 typedef Uint32 SDL_AudioDeviceID;
 
@@ -874,8 +871,9 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
                                                       Uint32 * audio_len);
 
 /**
- *  Loads a WAV from a file.
- *  Compatibility convenience function.
+ * Loads a WAV from a file.
+ *
+ * Compatibility convenience function.
  */
 #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
     SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
@@ -1118,6 +1116,9 @@ extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
  */
 extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
 
+/**
+ * Maximum volume allowed in calls to SDL_MixAudio and SDL_MixAudioFormat.
+ */
 #define SDL_MIX_MAXVOLUME 128
 
 /**
@@ -1170,8 +1171,9 @@ extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
  * \param format the SDL_AudioFormat structure representing the desired audio
  *               format
  * \param len the length of the audio buffer in bytes
- * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
- *               for full audio volume
+ * \param volume ranges from -128 - ∞ (at -128, the volume is at 0%, at 0 -
+ *               100% and the higher the number, the bigger the %), and should
+ *               be set to SDL_MIX_MAXVOLUME for full audio volume
  *
  * \since This function is available since SDL 2.0.0.
  */
diff --git a/include/SDL2/SDL_bits.h b/include/SDL2/SDL_bits.h
index 83e8a78..0b22131 100644
--- a/include/SDL2/SDL_bits.h
+++ b/include/SDL2/SDL_bits.h
@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_bits.h
+ * # CategoryBits
  *
- *  Functions for fiddling with bits and bitmasks.
+ * Functions for fiddling with bits and bitmasks.
  */
 
 #ifndef SDL_bits_h_
@@ -56,6 +56,12 @@ extern __inline int _SDL_bsr_watcom(Uint32);
     modify exact [eax] nomemory;
 #endif
 
+/**
+ * Use this function to get the index of the most significant (set) bit in a
+ *
+ * \param x the number to find the MSB of
+ * \returns the index of the most significant bit of x, or -1 if x is 0.
+ */
 SDL_FORCE_INLINE int
 SDL_MostSignificantBitIndex32(Uint32 x)
 {
diff --git a/include/SDL2/SDL_blendmode.h b/include/SDL2/SDL_blendmode.h
index 1709b56..75d21fe 100644
--- a/include/SDL2/SDL_blendmode.h
+++ b/include/SDL2/SDL_blendmode.h
@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_blendmode.h
+ * # CategoryBlendmode
  *
- *  Header file declaring the SDL_BlendMode enumeration
+ * Header file declaring the SDL_BlendMode enumeration
  */
 
 #ifndef SDL_blendmode_h_
@@ -35,7 +35,7 @@ extern "C" {
 #endif
 
 /**
- *  \brief The blend mode used in SDL_RenderCopy() and drawing operations.
+ * The blend mode used in SDL_RenderCopy() and drawing operations.
  */
 typedef enum SDL_BlendMode
 {
@@ -60,7 +60,8 @@ typedef enum SDL_BlendMode
 } SDL_BlendMode;
 
 /**
- *  \brief The blend operation used when combining source and destination pixel components
+ * The blend operation used when combining source and destination pixel
+ * components
  */
 typedef enum SDL_BlendOperation
 {
@@ -72,7 +73,7 @@ typedef enum SDL_BlendOperation
 } SDL_BlendOperation;
 
 /**
- *  \brief The normalized factor used to multiply pixel components
+ * The normalized factor used to multiply pixel components
  */
 typedef enum SDL_BlendFactor
 {
diff --git a/include/SDL2/SDL_clipboard.h b/include/SDL2/SDL_clipboard.h
index bd4b044..3a02774 100644
--- a/include/SDL2/SDL_clipboard.h
+++ b/include/SDL2/SDL_clipboard.h
@@ -20,7 +20,7 @@
 */
 
 /**
- * \file SDL_clipboard.h
+ * # CategoryClipboard
  *
  * Include file for SDL clipboard handling
  */
diff --git a/include/SDL2/SDL_config.h b/include/SDL2/SDL_config.h
index 49605b1..dde6edd 100644
--- a/include/SDL2/SDL_config.h
+++ b/include/SDL2/SDL_config.h
@@ -24,9 +24,7 @@
 
 #include "SDL_platform.h"
 
-/**
- *  \file SDL_config.h
- */
+/* WIKI CATEGORY: - */
 
 /* Add any platform that doesn't build using the configure system. */
 #if defined(__WIN32__)
diff --git a/include/SDL2/SDL_config_minimal.h b/include/SDL2/SDL_config_minimal.h
index a1b1c59..ceedda2 100644
--- a/include/SDL2/SDL_config_minimal.h
+++ b/include/SDL2/SDL_config_minimal.h
@@ -62,8 +62,6 @@ typedef unsigned int uintptr_t;
 #define HAVE_GCC_SYNC_LOCK_TEST_AND_SET 1
 #endif
 
-#if 0 /* Don't mark subsystems disabled for SDL applications */
-
 /* Enable the dummy audio driver (src/audio/dummy/\*.c) */
 #define SDL_AUDIO_DRIVER_DUMMY  1
 
@@ -94,6 +92,4 @@ typedef unsigned int uintptr_t;
 /* Enable the dummy filesystem driver (src/filesystem/dummy/\*.c) */
 #define SDL_FILESYSTEM_DUMMY  1
 
-#endif /* 0 */
-
 #endif /* SDL_config_minimal_h_ */
diff --git a/include/SDL2/SDL_config_windows.h b/include/SDL2/SDL_config_windows.h
index dba7808..aae52eb 100644
--- a/include/SDL2/SDL_config_windows.h
+++ b/include/SDL2/SDL_config_windows.h
@@ -99,9 +99,11 @@ typedef unsigned int uintptr_t;
 #define HAVE_D3D11_H 1
 #define HAVE_ROAPI_H 1
 #endif
-#if defined(WDK_NTDDI_VERSION) && WDK_NTDDI_VERSION > 0x0A000008 /* 10.0.19041.0 */
+#if defined(__has_include)
+#if __has_include(<d3d12.h>) && __has_include(<d3d12sdklayers.h>)
 #define HAVE_D3D12_H 1
 #endif
+#endif
 #if defined(_WIN32_MAXVER) && _WIN32_MAXVER >= 0x0603  /* Windows 8.1 SDK */
 #define HAVE_SHELLSCALINGAPI_H 1
 #endif
diff --git a/include/SDL2/SDL_cpuinfo.h b/include/SDL2/SDL_cpuinfo.h
index 2a9dd38..b9d0958 100644
--- a/include/SDL2/SDL_cpuinfo.h
+++ b/include/SDL2/SDL_cpuinfo.h
@@ -19,10 +19,16 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
+/* WIKI CATEGORY: CPUInfo */
+
 /**
- *  \file SDL_cpuinfo.h
+ * # CategoryCPUInfo
+ *
+ * CPU feature detection for SDL.
  *
- *  CPU feature detection for SDL.
+ * These functions are largely concerned with reporting if the system has
+ * access to various SIMD instruction sets, but also has other important info
+ * to share, such as number of logical CPU cores.
  */
 
 #ifndef SDL_cpuinfo_h_
diff --git a/include/SDL2/SDL_egl.h b/include/SDL2/SDL_egl.h
index a4276e6..84c1f1b 100644
--- a/include/SDL2/SDL_egl.h
+++ b/include/SDL2/SDL_egl.h
@@ -19,11 +19,10 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/**
- *  \file SDL_egl.h
- *
- *  This is a simple file to encapsulate the EGL API headers.
+/*
+ * This is a simple file to encapsulate the EGL API headers.
  */
+
 #if !defined(_MSC_VER) && !defined(__ANDROID__) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS)
 
 #if defined(__vita__) || defined(__psp2__)
diff --git a/include/SDL2/SDL_endian.h b/include/SDL2/SDL_endian.h
index 591ccac..38ae231 100644
--- a/include/SDL2/SDL_endian.h
+++ b/include/SDL2/SDL_endian.h
@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_endian.h
+ * # CategoryEndian
  *
- *  Functions for reading and writing endian-specific values
+ * Functions for reading and writing endian-specific values
  */
 
 #ifndef SDL_endian_h_
@@ -180,6 +180,16 @@ extern __inline Uint16 SDL_Swap16(Uint16);
   parm   [ax]   \
   modify [ax];
 #else
+
+/**
+ * Use this function to swap the byte order of a 16-bit value.
+ *
+ * \param x the value to be swapped
+ * \returns the swapped value.
+ *
+ * \sa SDL_SwapBE16
+ * \sa SDL_SwapLE16
+ */
 SDL_FORCE_INLINE Uint16
 SDL_Swap16(Uint16 x)
 {
@@ -231,6 +241,16 @@ extern __inline Uint32 SDL_Swap32(Uint32);
   parm   [eax] \
   modify [eax];
 #else
+
+/**
+ * Use this function to swap the byte order of a 32-bit value.
+ *
+ * \param x the value to be swapped
+ * \returns the swapped value.
+ *
+ * \sa SDL_SwapBE32
+ * \sa SDL_SwapLE32
+ */
 SDL_FORCE_INLINE Uint32
 SDL_Swap32(Uint32 x)
 {
@@ -276,6 +296,16 @@ extern __inline Uint64 SDL_Swap64(Uint64);
   parm [eax edx]  \
   modify [eax edx];
 #else
+
+/**
+ * Use this function to swap the byte order of a 64-bit value.
+ *
+ * \param x the value to be swapped
+ * \returns the swapped value.
+ *
+ * \sa SDL_SwapBE64
+ * \sa SDL_SwapLE64
+ */
 SDL_FORCE_INLINE Uint64
 SDL_Swap64(Uint64 x)
 {
@@ -293,6 +323,15 @@ SDL_Swap64(Uint64 x)
 #endif
 
 
+/**
+ * Use this function to swap the byte order of a floating point value.
+ *
+ * \param x the value to be swapped
+ * \returns the swapped value.
+ *
+ * \sa SDL_SwapFloatBE
+ * \sa SDL_SwapFloatLE
+ */
 SDL_FORCE_INLINE float
 SDL_SwapFloat(float x)
 {
diff --git a/include/SDL2/SDL_error.h b/include/SDL2/SDL_error.h
index 2df6463..aca98f7 100644
--- a/include/SDL2/SDL_error.h
+++ b/include/SDL2/SDL_error.h
@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_error.h
+ * # CategoryError
  *
- *  Simple error message routines for SDL.
+ * Simple error message routines for SDL.
  */
 
 #ifndef SDL_error_h_
diff --git a/include/SDL2/SDL_events.h b/include/SDL2/SDL_events.h
index a504d83..ada011a 100644
--- a/include/SDL2/SDL_events.h
+++ b/include/SDL2/SDL_events.h
@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_events.h
+ * # CategoryEvents
  *
- *  Include file for SDL event handling.
+ * Include file for SDL event handling.
  */
 
 #ifndef SDL_events_h_
@@ -167,7 +167,7 @@ typedef enum SDL_EventType
     /* Internal events */
     SDL_POLLSENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */
 
-    /** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use,
+    /** Events SDL_USEREVENT through SDL_LASTEVENT are for your use,
      *  and should be allocated with SDL_RegisterEvents()
      */
     SDL_USEREVENT    = 0x8000,
@@ -179,7 +179,7 @@ typedef enum SDL_EventType
 } SDL_EventType;
 
 /**
- *  \brief Fields shared by every event
+ * Fields shared by every event
  */
 typedef struct SDL_CommonEvent
 {
@@ -188,14 +188,14 @@ typedef struct SDL_CommonEvent
 } SDL_CommonEvent;
 
 /**
- *  \brief Display state change event data (event.display.*)
+ * Display state change event data (event.display.*)
  */
 typedef struct SDL_DisplayEvent
 {
-    Uint32 type;        /**< ::SDL_DISPLAYEVENT */
+    Uint32 type;        /**< SDL_DISPLAYEVENT */
     Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
     Uint32 display;     /**< The associated display index */
-    Uint8 event;        /**< ::SDL_DisplayEventID */
+    Uint8 event;        /**< SDL_DisplayEventID */
     Uint8 padding1;
     Uint8 padding2;
     Uint8 padding3;
@@ -203,14 +203,14 @@ typedef struct SDL_DisplayEvent
 } SDL_DisplayEvent;
 
 /**
- *  \brief Window state change event data (event.window.*)
+ * Window state change event data (event.window.*)
  */
 typedef struct SDL_WindowEvent
 {
-    Uint32 type;        /**< ::SDL_WINDOWEVENT */
+    Uint32 type;        /**< SDL_WINDOWEVENT */
     Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
     Uint32 windowID;    /**< The associated window */
-    Uint8 event;        /**< ::SDL_WindowEventID */
+    Uint8 event;        /**< SDL_WindowEventID */
     Uint8 padding1;
     Uint8 padding2;
     Uint8 padding3;
@@ -219,14 +219,14 @@ typedef struct SDL_WindowEvent
 } SDL_WindowEvent;
 
 /**
- *  \brief Keyboard button event structure (event.key.*)
+ * Keyboard button event structure (event.key.*)
  */
 typedef struct SDL_KeyboardEvent
 {
-    Uint32 type;        /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
+    Uint32 type;        /**< SDL_KEYDOWN or SDL_KEYUP */
     Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
     Uint32 windowID;    /**< The window with keyboard focus, if any */
-    Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
+    Uint8 state;        /**< SDL_PRESSED or SDL_RELEASED */
     Uint8 repeat;       /**< Non-zero if this is a key repeat */
     Uint8 padding2;
     Uint8 padding3;
@@ -234,12 +234,13 @@ typedef struct SDL_KeyboardEvent
 } SDL_KeyboardEvent;
 
 #define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
+
 /**
- *  \brief Keyboard text editing event structure (event.edit.*)
+ * Keyboard text editing event structure (event.edit.*)
  */
 typedef struct SDL_TextEditingEvent
 {
-    Uint32 type;                                /**< ::SDL_TEXTEDITING */
+    Uint32 type;                                /**< SDL_TEXTEDITING */
     Uint32 timestamp;                           /**< In milliseconds, populated using SDL_GetTicks() */
     Uint32 windowID;                            /**< The window with keyboard focus, if any */
     char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE];  /**< The editing text */
@@ -248,12 +249,12 @@ typedef struct SDL_TextEditingEvent
 } SDL_TextEditingEvent;
 
 /**
- *  \brief Extended keyboard text editing event structure (event.editExt.*) when text would be
- *  truncated if stored in the text buffer SDL_TextEditingEvent
+ * Extended keyboard text editing event structure (event.editExt.*) when text
+ * would be truncated if stored in the text buffer SDL_TextEditingEvent
  */
 typedef struct SDL_TextEditingExtEvent
 {
-    Uint32 type;                                /**< ::SDL_TEXTEDITING_EXT */
+    Uint32 type;                                /**< SDL_TEXTEDITING_EXT */
     Uint32 timestamp;                           /**< In milliseconds, populated using SDL_GetTicks() */
     Uint32 windowID;                            /**< The window with keyboard focus, if any */
     char* text;                                 /**< The editing text, which should be freed with SDL_free(), and will not be NULL */
@@ -261,24 +262,43 @@ typedef struct SDL_TextEditingExtEvent
     Sint32 length;                              /**< The length of selected editing text */
 } SDL_TextEditingExtEvent;
 
+/**
+ * The maximum bytes of text that can be supplied in an SDL_TextInputEvent.
+ */
 #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
+
 /**
- *  \brief Keyboard text input event structure (event.text.*)
+ * Keyboard text input event structure (event.text.*)
+ *
+ * `text` is limited to SDL_TEXTINPUTEVENT_TEXT_SIZE bytes. If the incoming
+ * string is larger than this, SDL will split it and send it in pieces, across
+ * multiple events. The string is in UTF-8 format, and if split, SDL
+ * guarantees that it will not split in the middle of a UTF-8 sequence, so any
+ * event will only contain complete codepoints. However, if there are several
+ * codepoints that go together into a single glyph (like an emoji "thumbs up"
+ * followed by a skin color), they may be split between events.
+ *
+ * This event will never be delivered unless text input is enabled by calling
+ * SDL_StartTextInput(). Text input is enabled by default on desktop
+ * platforms, and disabled by default on mobile platforms!
+ *
+ * \sa SDL_StartTextInput
+ * \sa SDL_StopTextInput
  */
 typedef struct SDL_TextInputEvent
 {
-    Uint32 type;                              /**< ::SDL_TEXTINPUT */
+    Uint32 type;                              /**< SDL_TEXTINPUT */
     Uint32 timestamp;                         /**< In milliseconds, populated using SDL_GetTicks() */
     Uint32 windowID;                          /**< The window with keyboard focus, if any */
-    char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text */
+    char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text; UTF-8 encoded. */
 } SDL_TextInputEvent;
 
 /**
- *  \brief Mouse motion event structure (event.motion.*)
+ * Mouse motion event structure (event.motion.*)
  */
 typedef struct SDL_MouseMotionEvent
 {
-    Uint32 type;        /**< ::SDL_MOUSEMOTION */
+    Uint32 type;        /**< SDL_MOUSEMOTION */
     Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
     Uint32 windowID;    /**< The window with mouse focus, if any */
     Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
@@ -290,16 +310,16 @@ typedef struct SDL_MouseMotionEvent
 } SDL_MouseMotionEvent;
 
 /**
- *  \brief Mouse button event structure (event.button.*)
+ * Mouse button event structure (event.button.*)
  */
 typedef struct SDL_MouseButtonEvent
 {
-    Uint32 type;        /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
+    Uint32 type;        /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
     Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
     Uint32 windowID;    /**< The window with mouse focus, if any */
     Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
     Uint8 button;       /**< The mouse button index */
-    Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
+    Uint8 state;        /**< SDL_PRESSED or SDL_RELEASED */
     Uint8 clicks;       /**< 1 for single-click, 2 for double-click, etc. */
     Uint8 padding1;
     Sint32 x;           /**< X coordinate, relative to window */
@@ -307,11 +327,11 @@ typedef struct SDL_MouseButtonEvent
 } SDL_MouseButtonEvent;
 
 /**
- *  \brief Mouse wheel event structure (event.wheel.*)
+ * Mouse wheel event structure (event.wheel.*)
  */
 typedef struct SDL_MouseWheelEvent
 {
-    Uint32 type;        /**< ::SDL_MOUSEWHEEL */
+    Uint32 type;        /**< SDL_MOUSEWHEEL */
     Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
     Uint32 windowID;    /**< The window with mouse focus, if any */
     Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
@@ -325,11 +345,11 @@ typedef struct SDL_MouseWheelEvent
 } SDL_MouseWheelEvent;
 
 /**
- *  \brief Joystick axis motion event structure (event.jaxis.*)
+ * Joystick axis motion event structure (event.jaxis.*)
  */
 typedef struct SDL_JoyAxisEvent
 {
-    Uint32 type;        /**< ::SDL_JOYAXISMOTION */
+    Uint32 type;        /**< SDL_JOYAXISMOTION */
     Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
     SDL_JoystickID which; /**< The joystick instance id */
     Uint8 axis;         /**< The joystick axis index */
@@ -341,11 +361,11 @@ typedef struct SDL_JoyAxisEvent
 } SDL_JoyAxisEvent;
 
 /**
- *  \brief Joystick trackball motion event structure (event.jball.*)
+ * Joystick trackball motion event structure (event.jball.*)
  */
 typedef struct SDL_JoyBallEvent
 {
-    Uint32 type;        /**< ::SDL_JOYBALLMOTION */
+    Uint32 type;        /**< SDL_JOYBALLMOTION */
     Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
     SDL_JoystickID which; /**< The joystick instance id */
     Uint8 ball;         /**< The joystick trackball index */
@@ -357,18 +377,18 @@ typedef struct SDL_JoyBallEvent
 } SDL_JoyBallEvent;
 
 /**
- *  \brief Joystick hat position change event structure (event.jhat.*)
+ * Joystick hat position change event structure (event.jhat.*)
  */
 typedef struct SDL_JoyHatEvent
 {
-    Uint32 type;        /**< ::SDL_JOYHATMOTION */
+    Uint32 type;        /**< SDL_JOYHATMOTION */
     Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
     SDL_JoystickID which; /**< The joystick instance id */
     Uint8 hat;          /**< The joystick hat index */
     Uint8 value;        /**< The hat position value.
-                         *   \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
-                         *   \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
-                         *   \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
+                         *   \sa SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP
+                         *   \sa SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT
+                         *   \sa SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN
                          *
                          *   Note that zero means the POV is centered.
                          */
@@ -377,46 +397,46 @@ typedef struct SDL_JoyHatEvent
 } SDL_JoyHatEvent;
 
 /**
- *  \brief Joystick button event structure (event.jbutton.*)
+ * Joystick button event structure (event.jbutton.*)
  */
 typedef struct SDL_JoyButtonEvent
 {
-    Uint32 type;        /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
+    Uint32 type;        /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
     Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
     SDL_JoystickID which; /**< The joystick instance id */
     Uint8 button;       /**< The joystick button index */
-    Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
+    Uint8 state;        /**< SDL_PRESSED or SDL_RELEASED */
     Uint8 padding1;
     Uint8 padding2;
 } SDL_JoyButtonEvent;
 
 /**
- *  \brief Joystick device event structure (event.jdevice.*)
+ * Joystick device event structure (event.jdevice.*)
  */
 typedef struct SDL_JoyDeviceEvent
 {
-    Uint32 type;        /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */
+    Uint32 type;        /**< SDL_JOYDEVICEADDED or SDL_JOYDEVICEREMOVED */
     Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
     Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
 } SDL_JoyDeviceEvent;
 
 /**
- *  \brief Joysick battery level change event structure (event.jbattery.*)
+ * Joysick battery level change event structure 

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