dep/msvc: Update SDL2 to 2.0.16

dep/msvc/sdl2/include/SDL.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -47,6 +47,7 @@
 #include "SDL_loadso.h"
 #include "SDL_log.h"
 #include "SDL_messagebox.h"
+#include "SDL_metal.h"
 #include "SDL_mutex.h"
 #include "SDL_power.h"
 #include "SDL_render.h"
@@ -58,6 +59,8 @@
 #include "SDL_timer.h"
 #include "SDL_version.h"
 #include "SDL_video.h"
+#include "SDL_locale.h"
+#include "SDL_misc.h"
 
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
@@ -90,37 +93,120 @@ extern "C" {
 /* @} */
 
 /**
- *  This function initializes  the subsystems specified by \c flags
+ * Initialize the SDL library.
+ *
+ * SDL_Init() simply forwards to calling SDL_InitSubSystem(). Therefore, the
+ * two may be used interchangeably. Though for readability of your code
+ * SDL_InitSubSystem() might be preferred.
+ *
+ * The file I/O (for example: SDL_RWFromFile) and threading (SDL_CreateThread)
+ * subsystems are initialized by default. Message boxes
+ * (SDL_ShowSimpleMessageBox) also attempt to work without initializing the
+ * video subsystem, in hopes of being useful in showing an error dialog when
+ * SDL_Init fails. You must specifically initialize other subsystems if you
+ * use them in your application.
+ *
+ * Logging (such as SDL_Log) works without initialization, too.
+ *
+ * `flags` may be any of the following OR'd together:
+ *
+ * - `SDL_INIT_TIMER`: timer subsystem
+ * - `SDL_INIT_AUDIO`: audio subsystem
+ * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events
+ *   subsystem
+ * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the
+ *   events subsystem
+ * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem
+ * - `SDL_INIT_GAMECONTROLLER`: controller subsystem; automatically
+ *   initializes the joystick subsystem
+ * - `SDL_INIT_EVENTS`: events subsystem
+ * - `SDL_INIT_EVERYTHING`: all of the above subsystems
+ * - `SDL_INIT_NOPARACHUTE`: compatibility; this flag is ignored
+ *
+ * Subsystem initialization is ref-counted, you must call SDL_QuitSubSystem()
+ * for each SDL_InitSubSystem() to correctly shutdown a subsystem manually (or
+ * call SDL_Quit() to force shutdown). If a subsystem is already loaded then
+ * this call will increase the ref-count and return.
+ *
+ * \param flags subsystem initialization flags
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_InitSubSystem
+ * \sa SDL_Quit
+ * \sa SDL_SetMainReady
+ * \sa SDL_WasInit
  */
 extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
 
 /**
- *  This function initializes specific SDL subsystems
+ * Compatibility function to initialize the SDL library.
+ *
+ * In SDL2, this function and SDL_Init() are interchangeable.
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  Subsystem initialization is ref-counted, you must call
+ * \sa SDL_Init
- *  SDL_QuitSubSystem() for each SDL_InitSubSystem() to correctly
+ * \sa SDL_Quit
- *  shutdown a subsystem manually (or call SDL_Quit() to force shutdown).
+ * \sa SDL_QuitSubSystem
- *  If a subsystem is already loaded then this call will
- *  increase the ref-count and return.
  */
 extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
 
 /**
- *  This function cleans up specific SDL subsystems
+ * Shut down specific SDL subsystems.
+ *
+ * If you start a subsystem using a call to that subsystem's init function
+ * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
+ * SDL_QuitSubSystem() and SDL_WasInit() will not work. You will need to use
+ * that subsystem's quit function (SDL_VideoQuit()) directly instead. But
+ * generally, you should not be using those functions directly anyhow; use
+ * SDL_Init() instead.
+ *
+ * You still need to call SDL_Quit() even if you close all open subsystems
+ * with SDL_QuitSubSystem().
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ *
+ * \sa SDL_InitSubSystem
+ * \sa SDL_Quit
  */
 extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
 
 /**
- *  This function returns a mask of the specified subsystems which have
+ * Get a mask of the specified subsystems which are currently initialized.
- *  previously been 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.
  *
- *  If \c flags is 0, it returns a mask of all initialized subsystems.
+ *          The return value does not include SDL_INIT_NOPARACHUTE.
+ *
+ * \sa SDL_Init
+ * \sa SDL_InitSubSystem
  */
 extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
 
 /**
- *  This function cleans up all initialized subsystems. You should
+ * Clean up all initialized subsystems.
- *  call it upon all exit conditions.
+ *
+ * You should call this function even if you have already shutdown each
+ * initialized subsystem with SDL_QuitSubSystem(). It is safe to call this
+ * function even in the case of errors in initialization.
+ *
+ * If you start a subsystem using a call to that subsystem's init function
+ * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
+ * then you must use that subsystem's quit function (SDL_VideoQuit()) to shut
+ * it down before calling SDL_Quit(). But generally, you should not be using
+ * those functions directly anyhow; use SDL_Init() instead.
+ *
+ * You can use this function with atexit() to ensure that it is run when your
+ * application is shutdown, but it is not wise to do this from a library or
+ * other dynamically loaded code.
+ *
+ * \sa SDL_Init
+ * \sa SDL_QuitSubSystem
  */
 extern DECLSPEC void SDLCALL SDL_Quit(void);
 

dep/msvc/sdl2/include/SDL_assert.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -53,6 +53,10 @@ assert can have unique static variables associated with it.
     #define SDL_TriggerBreakpoint() __debugbreak()
 #elif ( (!defined(__NACL__)) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))) )
     #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" )
+#elif ( defined(__APPLE__) && (defined(__arm64__) || defined(__aarch64__)) )  /* this might work on other ARM targets, but this is a known quantity... */
+    #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "brk #22\n\t" )
+#elif defined(__APPLE__) && defined(__arm__)
+    #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "bkpt #22\n\t" )
 #elif defined(__386__) && defined(__WATCOMC__)
     #define SDL_TriggerBreakpoint() { _asm { int 0x03 } }
 #elif defined(HAVE_SIGNAL_H) && !defined(__WATCOMC__)
@@ -185,92 +189,115 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *,
 #define SDL_assert_always(condition) SDL_enabled_assert(condition)
 
 
+/**
+ * A callback that fires when an SDL assertion fails.
+ *
+ * \param data a pointer to the SDL_AssertData structure corresponding to the
+ *             current assertion
+ * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler()
+ * \returns an SDL_AssertState value indicating how to handle the failure.
+ */
 typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
                                  const SDL_AssertData* data, void* userdata);
 
 /**
- *  \brief Set an application-defined assertion handler.
+ * Set an application-defined assertion handler.
  *
- *  This allows an app to show its own assertion UI and/or force the
+ * This function allows an application to show its own assertion UI and/or
- *  response to an assertion failure. If the app doesn't provide this, SDL
+ * force the response to an assertion failure. If the application doesn't
- *  will try to do the right thing, popping up a system-specific GUI dialog,
+ * provide this, SDL will try to do the right thing, popping up a
- *  and probably minimizing any fullscreen windows.
+ * system-specific GUI dialog, and probably minimizing any fullscreen windows.
  *
- *  This callback may fire from any thread, but it runs wrapped in a mutex, so
+ * This callback may fire from any thread, but it runs wrapped in a mutex, so
- *  it will only fire from one thread at a time.
+ * it will only fire from one thread at a time.
  *
- *  Setting the callback to NULL restores SDL's original internal handler.
+ * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
  *
- *  This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
+ * \param handler the SDL_AssertionHandler function to call when an assertion
+ *                fails or NULL for the default handler
+ * \param userdata a pointer that is passed to `handler`
  *
- *  Return SDL_AssertState value of how to handle the assertion failure.
+ * \sa SDL_GetAssertionHandler
- *
- *  \param handler Callback function, called when an assertion fails.
- *  \param userdata A pointer passed to the callback as-is.
  */
 extern DECLSPEC void SDLCALL SDL_SetAssertionHandler(
                                             SDL_AssertionHandler handler,
                                             void *userdata);
 
 /**
- *  \brief Get the default assertion handler.
+ * Get the default assertion handler.
+ *
+ * This returns the function pointer that is called by default when an
+ * assertion is triggered. This is an internal function provided by SDL, that
+ * is used for assertions when SDL_SetAssertionHandler() hasn't been used to
+ * provide a different function.
  *
- *  This returns the function pointer that is called by default when an
+ * \returns the default SDL_AssertionHandler that is called when an assert
- *   assertion is triggered. This is an internal function provided by SDL,
+ *          triggers.
- *   that is used for assertions when SDL_SetAssertionHandler() hasn't been
- *   used to provide a different function.
  *
- *  \return The default SDL_AssertionHandler that is called when an assert triggers.
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_GetAssertionHandler
  */
 extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void);
 
 /**
- *  \brief Get the current assertion handler.
+ * Get the current assertion handler.
+ *
+ * This returns the function pointer that is called when an assertion is
+ * triggered. This is either the value last passed to
+ * SDL_SetAssertionHandler(), or if no application-specified function is set,
+ * is equivalent to calling SDL_GetDefaultAssertionHandler().
+ *
+ * The parameter `puserdata` is a pointer to a void*, which will store the
+ * "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value
+ * will always be NULL for the default handler. If you don't care about this
+ * data, it is safe to pass a NULL pointer to this function to ignore it.
  *
- *  This returns the function pointer that is called when an assertion is
+ * \param puserdata pointer which is filled with the "userdata" pointer that
- *   triggered. This is either the value last passed to
+ *                  was passed to SDL_SetAssertionHandler()
- *   SDL_SetAssertionHandler(), or if no application-specified function is
+ * \returns the SDL_AssertionHandler that is called when an assert triggers.
- *   set, is equivalent to calling SDL_GetDefaultAssertionHandler().
  *
- *   \param puserdata Pointer to a void*, which will store the "userdata"
+ * \since This function is available since SDL 2.0.2.
- *                    pointer that was passed to SDL_SetAssertionHandler().
+ *
- *                    This value will always be NULL for the default handler.
+ * \sa SDL_SetAssertionHandler
- *                    If you don't care about this data, it is safe to pass
- *                    a NULL pointer to this function to ignore it.
- *  \return The SDL_AssertionHandler that is called when an assert triggers.
  */
 extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata);
 
 /**
- *  \brief Get a list of all assertion failures.
+ * Get a list of all assertion failures.
+ *
+ * This function gets all assertions triggered since the last call to
+ * SDL_ResetAssertionReport(), or the start of the program.
  *
- *  Get all assertions triggered since last call to SDL_ResetAssertionReport(),
+ * The proper way to examine this data looks something like this:
- *  or the start of the program.
  *
- *  The proper way to examine this data looks something like this:
+ * ```c
+ * const SDL_AssertData *item = SDL_GetAssertionReport();
+ * while (item) {
+ *    printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
+ *           item->condition, item->function, item->filename,
+ *           item->linenum, item->trigger_count,
+ *           item->always_ignore ? "yes" : "no");
+ *    item = item->next;
+ * }
+ * ```
  *
- *  <code>
+ * \returns a list of all failed assertions or NULL if the list is empty. This
- *  const SDL_AssertData *item = SDL_GetAssertionReport();
+ *          memory should not be modified or freed by the application.
- *  while (item) {
- *      printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
- *             item->condition, item->function, item->filename,
- *             item->linenum, item->trigger_count,
- *             item->always_ignore ? "yes" : "no");
- *      item = item->next;
- *  }
- *  </code>
  *
- *  \return List of all assertions.
+ * \sa SDL_ResetAssertionReport
- *  \sa SDL_ResetAssertionReport
  */
 extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void);
 
 /**
- *  \brief Reset the list of all assertion failures.
+ * Clear the list of all assertion failures.
  *
- *  Reset list of all assertions triggered.
+ * This function will clear the list of all assertions triggered up to that
+ * point. Immediately following this call, SDL_GetAssertionReport will return
+ * no items. In addition, any previously-triggered assertions will be reset to
+ * a trigger_count of zero, and their always_ignore state will be false.
  *
- *  \sa SDL_GetAssertionReport
+ * \sa SDL_GetAssertionReport
  */
 extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void);
 

dep/msvc/sdl2/include/SDL_atomic.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -89,25 +89,47 @@ extern "C" {
 typedef int SDL_SpinLock;
 
 /**
- * \brief Try to lock a spin lock by setting it to a non-zero value.
+ * Try to lock a spin lock by setting it to a non-zero value.
  *
- * \param lock Points to the lock.
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
  *
- * \return SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already held.
+ * \param lock a pointer to a lock variable
+ * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already
+ *          held.
+ *
+ * \sa SDL_AtomicLock
+ * \sa SDL_AtomicUnlock
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *lock);
 
 /**
- * \brief Lock a spin lock by setting it to a non-zero value.
+ * Lock a spin lock by setting it to a non-zero value.
+ *
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
  *
- * \param lock Points to the lock.
+ * \param lock a pointer to a lock variable
+ *
+ * \sa SDL_AtomicTryLock
+ * \sa SDL_AtomicUnlock
  */
 extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
 
 /**
- * \brief Unlock a spin lock by setting it to 0. Always returns immediately
+ * Unlock a spin lock by setting it to 0.
+ *
+ * Always returns immediately.
+ *
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
+ *
+ * \param lock a pointer to a lock variable
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- * \param lock Points to the lock.
+ * \sa SDL_AtomicLock
+ * \sa SDL_AtomicTryLock
  */
 extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
 
@@ -137,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,
+ * A typical pattern would be for thread A to write some data and a flag, and
- * and for thread B to read the flag and get the data. In this case you
+ * for thread B to read the flag and get the data. In this case you would
- * would insert a release barrier between writing the data and the flag,
+ * 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
+ * written, and you would insert an acquire barrier between reading the flag
- * flag and reading the data, to ensure that all the reads associated
+ * and reading the data, to ensure that all the reads associated with the flag
- * with the flag have completed.
+ * have completed.
  *
- * In this pattern you should always see a release barrier paired with
+ * In this pattern you should always see a release barrier paired with an
- * an acquire barrier and you should gate the data reads/writes with a
+ * acquire barrier and you should gate the data reads/writes with a single
- * single flag variable.
+ * flag variable.
  *
  * For more information on these semantics, take a look at the blog post:
  * http://preshing.com/20120913/acquire-and-release-semantics
@@ -216,32 +238,67 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
 typedef struct { int value; } SDL_atomic_t;
 
 /**
- * \brief 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.
  *
- * \return SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
  *
- * \note If you don't know what this function is for, you shouldn't use it!
+ * \param a a pointer to an SDL_atomic_t variable to be modified
-*/
+ * \param oldval the old value
+ * \param newval the new value
+ * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicGet
+ * \sa SDL_AtomicSet
+ */
 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int newval);
 
 /**
- * \brief Set an atomic variable to a value.
+ * Set an atomic variable to a value.
+ *
+ * This function also acts as a full memory barrier.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param v the desired value
+ * \returns the previous value of the atomic variable.
  *
- * \return The previous value of the atomic variable.
+ * \sa SDL_AtomicGet
  */
 extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v);
 
 /**
- * \brief Get the value of an atomic variable
+ * Get the value of an atomic variable.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to an SDL_atomic_t variable
+ * \returns the current value of an atomic variable.
+ *
+ * \sa SDL_AtomicSet
  */
 extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a);
 
 /**
- * \brief Add to an atomic variable.
+ * Add to an atomic variable.
+ *
+ * This function also acts as a full memory barrier.
  *
- * \return The previous value of the atomic variable.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
  *
- * \note This same style can be used for any number operation
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param v the desired value to add
+ * \returns the previous value of the atomic variable.
+ *
+ * \sa SDL_AtomicDecRef
+ * \sa SDL_AtomicIncRef
  */
 extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
 
@@ -263,23 +320,50 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
 #endif
 
 /**
- * \brief 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.
  *
- * \return SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
  *
- * \note If you don't know what this function is for, you shouldn't use it!
+ * \param a a pointer to a pointer
-*/
+ * \param oldval the old pointer value
+ * \param newval the new pointer value
+ * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicCAS
+ * \sa SDL_AtomicGetPtr
+ * \sa SDL_AtomicSetPtr
+ */
 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void *newval);
 
 /**
- * \brief Set a pointer to a value atomically.
+ * Set a pointer to a value atomically.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to a pointer
+ * \param v the desired pointer value
+ * \returns the previous value of the pointer.
  *
- * \return The previous value of the pointer.
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicGetPtr
  */
 extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v);
 
 /**
- * \brief Get the value of a pointer atomically.
+ * Get the value of a pointer atomically.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to a pointer
+ * \returns the current value of a pointer.
+ *
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicSetPtr
  */
 extern DECLSPEC void* SDLCALL SDL_AtomicGetPtr(void **a);
 

dep/msvc/sdl2/include/SDL_bits.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -45,13 +45,12 @@ extern "C" {
  *  with 0. This operation can also be stated as "count leading zeroes" and
  *  "log base 2".
  *
- *  \return Index of the most significant bit, or -1 if the value is 0.
+ *  \return the index of the most significant bit, or -1 if the value is 0.
  */
 #if defined(__WATCOMC__) && defined(__386__)
-extern _inline int _SDL_clz_watcom (Uint32);
+extern _inline int _SDL_bsr_watcom (Uint32);
-#pragma aux _SDL_clz_watcom = \
+#pragma aux _SDL_bsr_watcom = \
     "bsr eax, eax" \
-    "xor eax, 31" \
     parm [eax] nomemory \
     value [eax] \
     modify exact [eax] nomemory;
@@ -72,7 +71,13 @@ SDL_MostSignificantBitIndex32(Uint32 x)
     if (x == 0) {
         return -1;
     }
-    return 31 - _SDL_clz_watcom(x);
+    return _SDL_bsr_watcom(x);
+#elif defined(_MSC_VER)
+    unsigned long index;
+    if (_BitScanReverse(&index, x)) {
+        return index;
+    }
+    return -1;
 #else
     /* Based off of Bit Twiddling Hacks by Sean Eron Anderson
      * <seander@cs.stanford.edu>, released in the public domain.

dep/msvc/sdl2/include/SDL_blendmode.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -50,6 +50,9 @@ typedef enum
     SDL_BLENDMODE_MOD = 0x00000004,      /**< color modulate
                                               dstRGB = srcRGB * dstRGB
                                               dstA = dstA */
+    SDL_BLENDMODE_MUL = 0x00000008,      /**< color multiply
+                                              dstRGB = (srcRGB * dstRGB) + (dstRGB * (1-srcA))
+                                              dstA = (srcA * dstA) + (dstA * (1-srcA)) */
     SDL_BLENDMODE_INVALID = 0x7FFFFFFF
 
     /* Additional custom blend modes can be returned by SDL_ComposeCustomBlendMode() */
@@ -88,19 +91,96 @@ typedef enum
 } SDL_BlendFactor;
 
 /**
- *  \brief Create a custom blend mode, which may or may not be supported by a given renderer
+ * Compose a custom blend mode for renderers.
- *
+ *
- *  \param srcColorFactor source color factor
+ * The functions SDL_SetRenderDrawBlendMode and SDL_SetTextureBlendMode accept
- *  \param dstColorFactor destination color factor
+ * the SDL_BlendMode returned by this function if the renderer supports it.
- *  \param colorOperation color operation
+ *
- *  \param srcAlphaFactor source alpha factor
+ * A blend mode controls how the pixels from a drawing operation (source) get
- *  \param dstAlphaFactor destination alpha factor
+ * combined with the pixels from the render target (destination). First, the
- *  \param alphaOperation alpha operation
+ * components of the source and destination pixels get multiplied with their
- *
+ * blend factors. Then, the blend operation takes the two products and
- *  The result of the blend mode operation will be:
+ * calculates the result that will get stored in the render target.
- *      dstRGB = dstRGB * dstColorFactor colorOperation srcRGB * srcColorFactor
+ *
- *  and
+ * Expressed in pseudocode, it would look like this:
- *      dstA = dstA * dstAlphaFactor alphaOperation srcA * srcAlphaFactor
+ *
+ * ```c
+ * dstRGB = colorOperation(srcRGB * srcColorFactor, dstRGB * dstColorFactor);
+ * dstA = alphaOperation(srcA * srcAlphaFactor, dstA * dstAlphaFactor);
+ * ```
+ *
+ * Where the functions `colorOperation(src, dst)` and `alphaOperation(src,
+ * dst)` can return one of the following:
+ *
+ * - `src + dst`
+ * - `src - dst`
+ * - `dst - src`
+ * - `min(src, dst)`
+ * - `max(src, dst)`
+ *
+ * The red, green, and blue components are always multiplied with the first,
+ * second, and third components of the SDL_BlendFactor, respectively. The
+ * fourth component is not used.
+ *
+ * The alpha component is always multiplied with the fourth component of the
+ * SDL_BlendFactor. The other components are not used in the alpha
+ * calculation.
+ *
+ * Support for these blend modes varies for each renderer. To check if a
+ * specific SDL_BlendMode is supported, create a renderer and pass it to
+ * either SDL_SetRenderDrawBlendMode or SDL_SetTextureBlendMode. They will
+ * return with an error if the blend mode is not supported.
+ *
+ * This list describes the support of custom blend modes for each renderer in
+ * SDL 2.0.6. All renderers support the four blend modes listed in the
+ * SDL_BlendMode enumeration.
+ *
+ * - **direct3d**: Supports `SDL_BLENDOPERATION_ADD` with all factors.
+ * - **direct3d11**: Supports all operations with all factors. However, some
+ *   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.
+ * - **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`
+ *   and `SDL_BLENDOPERATION_REV_SUBTRACT`. May support color and alpha
+ *   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.
+ * - **psp**: No custom blend mode support.
+ * - **software**: No custom blend mode support.
+ *
+ * Some renderers do not provide an alpha component for the default render
+ * target. The `SDL_BLENDFACTOR_DST_ALPHA` and
+ * `SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA` factors do not have an effect in this
+ * case.
+ *
+ * \param srcColorFactor the SDL_BlendFactor applied to the red, green, and
+ *                       blue components of the source pixels
+ * \param dstColorFactor the SDL_BlendFactor applied to the red, green, and
+ *                       blue components of the destination pixels
+ * \param colorOperation the SDL_BlendOperation used to combine the red,
+ *                       green, and blue components of the source and
+ *                       destination pixels
+ * \param srcAlphaFactor the SDL_BlendFactor applied to the alpha component of
+ *                       the source pixels
+ * \param dstAlphaFactor the SDL_BlendFactor applied to the alpha component of
+ *                       the destination pixels
+ * \param alphaOperation the SDL_BlendOperation used to combine the alpha
+ *                       component of the source and destination pixels
+ * \returns an SDL_BlendMode that represents the chosen factors and
+ *          operations.
+ *
+ * \since This function is available in SDL 2.0.6.
+ *
+ * \sa SDL_SetRenderDrawBlendMode
+ * \sa SDL_GetRenderDrawBlendMode
+ * \sa SDL_SetTextureBlendMode
+ * \sa SDL_GetTextureBlendMode
  */
 extern DECLSPEC SDL_BlendMode SDLCALL SDL_ComposeCustomBlendMode(SDL_BlendFactor srcColorFactor,
                                                                  SDL_BlendFactor dstColorFactor,

dep/msvc/sdl2/include/SDL_clipboard.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -39,23 +39,41 @@ extern "C" {
 /* Function prototypes */
 
 /**
- * \brief Put UTF-8 text into the clipboard
+ * Put UTF-8 text into the clipboard.
  *
- * \sa SDL_GetClipboardText()
+ * \param text the text to store in the clipboard
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_GetClipboardText
+ * \sa SDL_HasClipboardText
  */
 extern DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
 
 /**
- * \brief Get UTF-8 text from the clipboard, which must be freed with SDL_free()
+ * Get UTF-8 text from the clipboard, which must be freed with SDL_free().
+ *
+ * This functions returns NULL if there was not enough memory left for a copy
+ * of the clipboard's content.
+ *
+ * \returns the clipboard text on success or NULL on failure; call
+ *          SDL_GetError() for more information. Caller must call SDL_free()
+ *          on the returned pointer when done with it.
  *
- * \sa SDL_SetClipboardText()
+ * \sa SDL_HasClipboardText
+ * \sa SDL_SetClipboardText
  */
 extern DECLSPEC char * SDLCALL SDL_GetClipboardText(void);
 
 /**
- * \brief Returns a flag indicating whether the clipboard exists and contains a text string that is non-empty
+ * Query whether the clipboard exists and contains a non-empty text string.
+ *
+ * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- * \sa SDL_GetClipboardText()
+ * \sa SDL_GetClipboardText
+ * \sa SDL_SetClipboardText
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void);
 

dep/msvc/sdl2/include/SDL_config.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_config_android.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -71,6 +71,7 @@
 #define HAVE_STRCHR 1
 #define HAVE_STRRCHR    1
 #define HAVE_STRSTR 1
+#define HAVE_STRTOK_R 1
 #define HAVE_STRTOL 1
 #define HAVE_STRTOUL    1
 #define HAVE_STRTOLL    1
@@ -110,8 +111,12 @@
 #define HAVE_LOGF   1
 #define HAVE_LOG10  1
 #define HAVE_LOG10F 1
+#define HAVE_LROUND 1
+#define HAVE_LROUNDF 1
 #define HAVE_POW    1
 #define HAVE_POWF   1
+#define HAVE_ROUND  1
+#define HAVE_ROUNDF 1
 #define HAVE_SCALBN 1
 #define HAVE_SCALBNF    1
 #define HAVE_SIN    1
@@ -120,23 +125,31 @@
 #define HAVE_SQRTF  1
 #define HAVE_TAN    1
 #define HAVE_TANF   1
+#define HAVE_TRUNC    1
+#define HAVE_TRUNCF   1
 #define HAVE_SIGACTION 1
 #define HAVE_SETJMP 1
 #define HAVE_NANOSLEEP  1
 #define HAVE_SYSCONF    1
 #define HAVE_CLOCK_GETTIME  1
 
+#ifdef __LP64__
+#define SIZEOF_VOIDP 8
+#else
 #define SIZEOF_VOIDP 4
+#endif
 
 /* Enable various audio drivers */
 #define SDL_AUDIO_DRIVER_ANDROID    1
 #define SDL_AUDIO_DRIVER_OPENSLES   1
+#define SDL_AUDIO_DRIVER_AAUDIO     0
 #define SDL_AUDIO_DRIVER_DUMMY  1
 
 /* Enable various input drivers */
 #define SDL_JOYSTICK_ANDROID    1
-#define SDL_JOYSTICK_HIDAPI    1
+#define SDL_JOYSTICK_HIDAPI     1
-#define SDL_HAPTIC_ANDROID    1
+#define SDL_JOYSTICK_VIRTUAL    1
+#define SDL_HAPTIC_ANDROID  1
 
 /* Enable sensor driver */
 #define SDL_SENSOR_ANDROID  1

dep/msvc/sdl2/include/SDL_config_iphoneos.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -71,6 +71,7 @@
 #define HAVE_STRCHR 1
 #define HAVE_STRRCHR    1
 #define HAVE_STRSTR 1
+#define HAVE_STRTOK_R 1
 #define HAVE_STRTOL 1
 #define HAVE_STRTOUL    1
 #define HAVE_STRTOLL    1
@@ -111,8 +112,12 @@
 #define HAVE_LOGF   1
 #define HAVE_LOG10  1
 #define HAVE_LOG10F 1
+#define HAVE_LROUND 1
+#define HAVE_LROUNDF 1
 #define HAVE_POW    1
 #define HAVE_POWF   1
+#define HAVE_ROUND 1
+#define HAVE_ROUNDF 1
 #define HAVE_SCALBN 1
 #define HAVE_SCALBNF    1
 #define HAVE_SIN    1
@@ -121,6 +126,8 @@
 #define HAVE_SQRTF  1
 #define HAVE_TAN    1
 #define HAVE_TANF   1
+#define HAVE_TRUNC  1
+#define HAVE_TRUNCF 1
 #define HAVE_SIGACTION  1
 #define HAVE_SETJMP 1
 #define HAVE_NANOSLEEP  1
@@ -135,9 +142,11 @@
 /* Enable the stub haptic driver (src/haptic/dummy/\*.c) */
 #define SDL_HAPTIC_DUMMY 1
 
-/* Enable MFi joystick support */
+/* Enable joystick support */
-#define SDL_JOYSTICK_MFI 1
+/* Only enable HIDAPI support if you want to support Steam Controllers on iOS and tvOS */
 /*#define SDL_JOYSTICK_HIDAPI 1*/
+#define SDL_JOYSTICK_MFI 1
+#define SDL_JOYSTICK_VIRTUAL    1
 
 #ifdef __TVOS__
 #define SDL_SENSOR_DUMMY    1
@@ -161,13 +170,17 @@
 #define SDL_VIDEO_DRIVER_DUMMY  1
 
 /* Enable OpenGL ES */
+#if !TARGET_OS_MACCATALYST
 #define SDL_VIDEO_OPENGL_ES2 1
 #define SDL_VIDEO_OPENGL_ES 1
 #define SDL_VIDEO_RENDER_OGL_ES 1
 #define SDL_VIDEO_RENDER_OGL_ES2    1
+#endif
 
-/* Metal supported on 64-bit devices running iOS 8.0 and tvOS 9.0 and newer */
+/* Metal supported on 64-bit devices running iOS 8.0 and tvOS 9.0 and newer
-#if !TARGET_OS_SIMULATOR && !TARGET_CPU_ARM && ((__IPHONE_OS_VERSION_MIN_REQUIRED >= 80000) || (__TV_OS_VERSION_MIN_REQUIRED >= 90000))
+   Also supported in simulator from iOS 13.0 and tvOS 13.0
+ */
+#if (TARGET_OS_SIMULATOR && ((__IPHONE_OS_VERSION_MIN_REQUIRED >= 130000) || (__TV_OS_VERSION_MIN_REQUIRED >= 130000))) || (!TARGET_CPU_ARM && ((__IPHONE_OS_VERSION_MIN_REQUIRED >= 80000) || (__TV_OS_VERSION_MIN_REQUIRED >= 90000)))
 #define SDL_PLATFORM_SUPPORTS_METAL	1
 #else
 #define SDL_PLATFORM_SUPPORTS_METAL	0
@@ -181,6 +194,10 @@
 #define SDL_VIDEO_VULKAN 1
 #endif
 
+#if SDL_PLATFORM_SUPPORTS_METAL
+#define SDL_VIDEO_METAL 1
+#endif
+
 /* Enable system power support */
 #define SDL_POWER_UIKIT 1
 
@@ -190,11 +207,6 @@
 /* enable iOS extended launch screen */
 #define SDL_IPHONE_LAUNCHSCREEN 1
 
-/* Set max recognized G-force from accelerometer
-   See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed
- */
-#define SDL_IPHONE_MAX_GFORCE 5.0
-
 /* enable filesystem support */
 #define SDL_FILESYSTEM_COCOA   1
 

dep/msvc/sdl2/include/SDL_config_macosx.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -74,6 +74,7 @@
 #define HAVE_STRCHR 1
 #define HAVE_STRRCHR    1
 #define HAVE_STRSTR 1
+#define HAVE_STRTOK_R 1
 #define HAVE_STRTOL 1
 #define HAVE_STRTOUL    1
 #define HAVE_STRTOLL    1
@@ -114,8 +115,12 @@
 #define HAVE_LOGF   1
 #define HAVE_LOG10  1
 #define HAVE_LOG10F 1
+#define HAVE_LROUND 1
+#define HAVE_LROUNDF 1
 #define HAVE_POW    1
 #define HAVE_POWF   1
+#define HAVE_ROUND 1
+#define HAVE_ROUNDF 1
 #define HAVE_SCALBN 1
 #define HAVE_SCALBNF    1
 #define HAVE_SIN    1
@@ -124,22 +129,38 @@
 #define HAVE_SQRTF  1
 #define HAVE_TAN    1
 #define HAVE_TANF   1
+#define HAVE_TRUNC    1
+#define HAVE_TRUNCF   1
 #define HAVE_SIGACTION  1
 #define HAVE_SETJMP 1
 #define HAVE_NANOSLEEP  1
 #define HAVE_SYSCONF    1
 #define HAVE_SYSCTLBYNAME 1
 
+#if defined(__has_include) && (defined(__i386__) || defined(__x86_64))
+# if __has_include(<immintrin.h>)
+#   define HAVE_IMMINTRIN_H 1
+# endif
+#endif
+
+#define HAVE_GCC_ATOMICS 1
+
 /* Enable various audio drivers */
 #define SDL_AUDIO_DRIVER_COREAUDIO  1
 #define SDL_AUDIO_DRIVER_DISK   1
 #define SDL_AUDIO_DRIVER_DUMMY  1
 
 /* Enable various input drivers */
+#define SDL_JOYSTICK_HIDAPI 1
 #define SDL_JOYSTICK_IOKIT  1
-#define SDL_JOYSTICK_HIDAPI  1
+#define SDL_JOYSTICK_VIRTUAL    1
 #define SDL_HAPTIC_IOKIT    1
 
+/* The MFI controller support requires ARC Objective C runtime */
+#if MAC_OS_X_VERSION_MIN_REQUIRED >= 1080 && !defined(__i386__)
+#define SDL_JOYSTICK_MFI 1
+#endif
+
 /* Enable the dummy sensor driver */
 #define SDL_SENSOR_DUMMY  1
 
@@ -157,13 +178,13 @@
 #define SDL_VIDEO_DRIVER_COCOA  1
 #define SDL_VIDEO_DRIVER_DUMMY  1
 #undef SDL_VIDEO_DRIVER_X11
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC "/usr/X11R6/lib/libX11.6.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC "/opt/X11/lib/libX11.6.dylib"
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XEXT "/usr/X11R6/lib/libXext.6.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XEXT "/opt/X11/lib/libXext.6.dylib"
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XINERAMA "/usr/X11R6/lib/libXinerama.1.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XINERAMA "/opt/X11/lib/libXinerama.1.dylib"
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XINPUT2 "/usr/X11R6/lib/libXi.6.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XINPUT2 "/opt/X11/lib/libXi.6.dylib"
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XRANDR "/usr/X11R6/lib/libXrandr.2.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XRANDR "/opt/X11/lib/libXrandr.2.dylib"
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XSS "/usr/X11R6/lib/libXss.1.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XSS "/opt/X11/lib/libXss.1.dylib"
-#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XVIDMODE "/usr/X11R6/lib/libXxf86vm.1.dylib"
+#define SDL_VIDEO_DRIVER_X11_DYNAMIC_XVIDMODE "/opt/X11/lib/libXxf86vm.1.dylib"
 #define SDL_VIDEO_DRIVER_X11_XDBE 1
 #define SDL_VIDEO_DRIVER_X11_XINERAMA 1
 #define SDL_VIDEO_DRIVER_X11_XRANDR 1
@@ -191,9 +212,15 @@
 #define SDL_VIDEO_RENDER_OGL_ES2 1
 #endif
 
-#ifndef SDL_VIDEO_RENDER_METAL
 /* Metal only supported on 64-bit architectures with 10.11+ */
-#if TARGET_CPU_X86_64 && (MAC_OS_X_VERSION_MAX_ALLOWED >= 101100)
+#if TARGET_RT_64_BIT && (MAC_OS_X_VERSION_MAX_ALLOWED >= 101100)
+#define SDL_PLATFORM_SUPPORTS_METAL    1
+#else
+#define SDL_PLATFORM_SUPPORTS_METAL    0
+#endif
+
+#ifndef SDL_VIDEO_RENDER_METAL
+#if SDL_PLATFORM_SUPPORTS_METAL
 #define SDL_VIDEO_RENDER_METAL    1
 #else
 #define SDL_VIDEO_RENDER_METAL    0
@@ -217,13 +244,22 @@
 #define SDL_VIDEO_OPENGL_GLX    1
 #endif
 
-/* Enable Vulkan support */
+/* Enable Vulkan and Metal support */
-/* Metal/Vulkan Portability only supported on 64-bit architectures with 10.11+ */
+#ifndef SDL_VIDEO_VULKAN
-#if TARGET_CPU_X86_64 && (MAC_OS_X_VERSION_MAX_ALLOWED >= 101100)
+#if SDL_PLATFORM_SUPPORTS_METAL
 #define SDL_VIDEO_VULKAN 1
 #else
 #define SDL_VIDEO_VULKAN 0
 #endif
+#endif
+
+#ifndef SDL_VIDEO_METAL
+#if SDL_PLATFORM_SUPPORTS_METAL
+#define SDL_VIDEO_METAL 1
+#else
+#define SDL_VIDEO_METAL 0
+#endif
+#endif
 
 /* Enable system power support */
 #define SDL_POWER_MACOSX 1

dep/msvc/sdl2/include/SDL_config_minimal.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_config_os2.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -25,35 +25,39 @@
 
 #include "SDL_platform.h"
 
+#define SIZEOF_VOIDP 4
+
 #define SDL_AUDIO_DRIVER_DUMMY 1
 #define SDL_AUDIO_DRIVER_DISK 1
+#define SDL_AUDIO_DRIVER_OS2 1
 
 #define SDL_POWER_DISABLED  1
-#define SDL_JOYSTICK_DISABLED 1
 #define SDL_HAPTIC_DISABLED 1
+#define SDL_JOYSTICK_DISABLED 1
+/*#undef SDL_JOYSTICK_OS2 */
 /*#undef SDL_JOYSTICK_HIDAPI */
+/*#undef SDL_JOYSTICK_VIRTUAL */
 
 #define SDL_SENSOR_DUMMY 1
 #define SDL_VIDEO_DRIVER_DUMMY 1
+#define SDL_VIDEO_DRIVER_OS2 1
 
 /* Enable OpenGL support */
 /* #undef SDL_VIDEO_OPENGL */
 
-/* Enable Vulkan support */
+#define SDL_THREAD_OS2 1
-/* #undef SDL_VIDEO_VULKAN */
+#define SDL_LOADSO_OS2 1
-
+#define SDL_TIMER_OS2 1
-#define SDL_LOADSO_DISABLED 1
+#define SDL_FILESYSTEM_OS2 1
-#define SDL_THREADS_DISABLED 1
-#define SDL_TIMERS_DISABLED 1
-#define SDL_FILESYSTEM_DUMMY 1
 
 /* Enable assembly routines */
 #define SDL_ASSEMBLY_ROUTINES 1
 
-/* #undef HAVE_LIBSAMPLERATE_H */
+/* use libsamplerate for audio rate conversion. */
+/*#define HAVE_LIBSAMPLERATE_H 1 */
 
 /* Enable dynamic libsamplerate support */
-/* #undef SDL_LIBSAMPLERATE_DYNAMIC */
+#define SDL_LIBSAMPLERATE_DYNAMIC "SAMPRATE.DLL"
 
 #define HAVE_LIBC 1
 
@@ -99,17 +103,28 @@
 #define HAVE_WCSLCPY 1
 #define HAVE_WCSLCAT 1
 #define HAVE_WCSCMP 1
+#define HAVE__WCSICMP 1
+#define HAVE__WCSNICMP 1
+#define HAVE_WCSLEN 1
+#define HAVE_WCSLCPY 1
+#define HAVE_WCSLCAT 1
+/* #undef HAVE_WCSDUP */
+#define HAVE__WCSDUP 1
+#define HAVE_WCSSTR 1
+#define HAVE_WCSCMP 1
+#define HAVE_WCSNCMP 1
 #define HAVE_STRLEN 1
 #define HAVE_STRLCPY 1
 #define HAVE_STRLCAT 1
 #define HAVE__STRREV 1
 #define HAVE__STRUPR 1
 #define HAVE__STRLWR 1
-#define HAVE_INDEX 1
+/* #undef HAVE_INDEX */
-#define HAVE_RINDEX 1
+/* #undef HAVE_RINDEX */
 #define HAVE_STRCHR 1
 #define HAVE_STRRCHR 1
 #define HAVE_STRSTR 1
+/* #undef HAVE_STRTOK_R */
 #define HAVE_ITOA 1
 #define HAVE__LTOA 1
 #define HAVE__ULTOA 1
@@ -127,7 +142,8 @@
 #define HAVE_STRICMP 1
 #define HAVE_STRCASECMP 1
 #define HAVE_STRNCASECMP 1
-#define HAVE_SSCANF 1
+#define HAVE_SSCANF  1
+#define HAVE_VSSCANF 1
 #define HAVE_SNPRINTF 1
 #define HAVE_VSNPRINTF 1
 #define HAVE_SETJMP 1
@@ -166,5 +182,11 @@
 /* #undef HAVE_SQRTF */
 #define HAVE_TAN 1
 /* #undef HAVE_TANF */
+/* #undef HAVE_TRUNC */
+/* #undef HAVE_TRUNCF */
+/* #undef HAVE_LROUND */
+/* #undef HAVE_LROUNDF */
+/* #undef HAVE_ROUND */
+/* #undef HAVE_ROUNDF */
 
 #endif /* SDL_config_os2_h_ */

dep/msvc/sdl2/include/SDL_config_pandora.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -95,6 +95,10 @@
 #define HAVE_FLOOR 1
 #define HAVE_LOG 1
 #define HAVE_LOG10 1
+#define HAVE_LROUND 1
+#define HAVE_LROUNDF 1
+#define HAVE_ROUND 1
+#define HAVE_ROUNDF 1
 #define HAVE_SCALBN 1
 #define HAVE_SIN 1
 #define HAVE_SINF 1
@@ -102,6 +106,8 @@
 #define HAVE_SQRTF 1
 #define HAVE_TAN 1
 #define HAVE_TANF 1
+#define HAVE_TRUNC 1
+#define HAVE_TRUNCF 1
 #define HAVE_SIGACTION 1
 #define HAVE_SETJMP 1
 #define HAVE_NANOSLEEP 1
@@ -110,8 +116,8 @@
 #define SDL_AUDIO_DRIVER_OSS 1
 
 #define SDL_INPUT_LINUXEV 1
-#define SDL_INPUT_TSLIB 1
 #define SDL_JOYSTICK_LINUX 1
+#define SDL_JOYSTICK_VIRTUAL 1
 #define SDL_HAPTIC_LINUX 1
 
 #define SDL_SENSOR_DUMMY 1

dep/msvc/sdl2/include/SDL_config_psp.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -136,6 +136,7 @@
 
 /* Enable the PSP joystick driver (src/joystick/psp/\*.c) */
 #define SDL_JOYSTICK_PSP        1
+#define SDL_JOYSTICK_VIRTUAL    1
 
 /* Enable the dummy sensor driver */
 #define SDL_SENSOR_DUMMY  1

dep/msvc/sdl2/include/SDL_config_windows.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -28,7 +28,7 @@
 /* This is a set of defines to configure the SDL features */
 
 #if !defined(_STDINT_H_) && (!defined(HAVE_STDINT_H) || !_HAVE_STDINT_H)
-#if defined(__GNUC__) || defined(__DMC__) || defined(__WATCOMC__)
+#if defined(__GNUC__) || defined(__DMC__) || defined(__WATCOMC__) || defined(__clang__)
 #define HAVE_STDINT_H   1
 #elif defined(_MSC_VER)
 typedef signed __int8 int8_t;
@@ -84,7 +84,14 @@ typedef unsigned int uintptr_t;
 #define HAVE_XINPUT_H 1
 #define HAVE_MMDEVICEAPI_H 1
 #define HAVE_AUDIOCLIENT_H 1
-#define HAVE_ENDPOINTVOLUME_H 1
+#define HAVE_SENSORSAPI_H 1
+#if (defined(_M_IX86) || defined(_M_X64) || defined(_M_AMD64)) && (defined(_MSC_VER) && _MSC_VER >= 1600)
+#define HAVE_IMMINTRIN_H 1
+#elif defined(__has_include) && (defined(__i386__) || defined(__x86_64))
+# if __has_include(<immintrin.h>)
+#   define HAVE_IMMINTRIN_H 1
+# endif
+#endif
 
 /* This is disabled by default to avoid C runtime dependencies and manifest requirements */
 #ifdef HAVE_LIBC
@@ -118,6 +125,7 @@ typedef unsigned int uintptr_t;
 #define HAVE_STRCHR 1
 #define HAVE_STRRCHR 1
 #define HAVE_STRSTR 1
+/* #undef HAVE_STRTOK_R */
 /* These functions have security warnings, so we won't use them */
 /* #undef HAVE__LTOA */
 /* #undef HAVE__ULTOA */
@@ -130,6 +138,9 @@ typedef unsigned int uintptr_t;
 #define HAVE_STRNCMP 1
 #define HAVE__STRICMP 1
 #define HAVE__STRNICMP 1
+#define HAVE__WCSICMP 1
+#define HAVE__WCSNICMP 1
+#define HAVE__WCSDUP 1
 #define HAVE_ACOS   1
 #define HAVE_ACOSF  1
 #define HAVE_ASIN   1
@@ -139,7 +150,7 @@ typedef unsigned int uintptr_t;
 #define HAVE_ATAN2  1
 #define HAVE_ATAN2F 1
 #define HAVE_CEILF  1
-#define HAVE__COPYSIGN  1
+#define HAVE__COPYSIGN 1
 #define HAVE_COS    1
 #define HAVE_COSF   1
 #define HAVE_EXP    1
@@ -166,9 +177,16 @@ typedef unsigned int uintptr_t;
 /* These functions were added with the VC++ 2013 C runtime library */
 #if _MSC_VER >= 1800
 #define HAVE_STRTOLL 1
+#define HAVE_STRTOULL 1
 #define HAVE_VSSCANF 1
+#define HAVE_LROUND 1
+#define HAVE_LROUNDF 1
+#define HAVE_ROUND 1
+#define HAVE_ROUNDF 1
 #define HAVE_SCALBN 1
-#define HAVE_SCALBNF    1
+#define HAVE_SCALBNF 1
+#define HAVE_TRUNC  1
+#define HAVE_TRUNCF 1
 #endif
 /* This function is available with at least the VC++ 2008 C runtime library */
 #if _MSC_VER >= 1400
@@ -183,6 +201,20 @@ typedef unsigned int uintptr_t;
 #define HAVE_STDDEF_H   1
 #endif
 
+/* Check to see if we have Windows 10 build environment */
+#if defined(_MSC_VER) && (_MSC_VER >= 1911)        /* Visual Studio 15.3 */
+#include <sdkddkver.h>
+#if _WIN32_WINNT >= 0x0601  /* Windows 7 */
+#define SDL_WINDOWS7_SDK
+#endif
+#if _WIN32_WINNT >= 0x0602  /* Windows 8 */
+#define SDL_WINDOWS8_SDK
+#endif
+#if _WIN32_WINNT >= 0x0A00  /* Windows 10 */
+#define SDL_WINDOWS10_SDK
+#endif
+#endif /* _MSC_VER >= 1911 */
+
 /* Enable various audio drivers */
 #define SDL_AUDIO_DRIVER_WASAPI 1
 #define SDL_AUDIO_DRIVER_DSOUND 1
@@ -192,18 +224,26 @@ typedef unsigned int uintptr_t;
 
 /* Enable various input drivers */
 #define SDL_JOYSTICK_DINPUT 1
-#define SDL_JOYSTICK_XINPUT 1
 #define SDL_JOYSTICK_HIDAPI 1
+#ifndef __WINRT__
+#define SDL_JOYSTICK_RAWINPUT   1
+#endif
+#define SDL_JOYSTICK_VIRTUAL    1
+#ifdef SDL_WINDOWS10_SDK
+#define SDL_JOYSTICK_WGI    1
+#endif
+#define SDL_JOYSTICK_XINPUT 1
 #define SDL_HAPTIC_DINPUT   1
 #define SDL_HAPTIC_XINPUT   1
 
-/* Enable the dummy sensor driver */
+/* Enable the sensor driver */
-#define SDL_SENSOR_DUMMY  1
+#define SDL_SENSOR_WINDOWS  1
 
 /* Enable various shared object loading systems */
 #define SDL_LOADSO_WINDOWS  1
 
 /* Enable various threading systems */
+#define SDL_THREAD_GENERIC_COND_SUFFIX 1
 #define SDL_THREAD_WINDOWS  1
 
 /* Enable various timer systems */
@@ -216,8 +256,8 @@ typedef unsigned int uintptr_t;
 #ifndef SDL_VIDEO_RENDER_D3D
 #define SDL_VIDEO_RENDER_D3D    1
 #endif
-#ifndef SDL_VIDEO_RENDER_D3D11
+#ifdef SDL_WINDOWS7_SDK
-#define SDL_VIDEO_RENDER_D3D11  0
+#define SDL_VIDEO_RENDER_D3D11  1
 #endif
 
 /* Enable OpenGL support */
@@ -255,3 +295,5 @@ typedef unsigned int uintptr_t;
 #endif
 
 #endif /* SDL_config_windows_h_ */
+
+/* vi: set ts=4 sw=4 expandtab: */

dep/msvc/sdl2/include/SDL_config_winrt.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -100,7 +100,6 @@ typedef unsigned int uintptr_t;
 
 #define HAVE_MMDEVICEAPI_H 1
 #define HAVE_AUDIOCLIENT_H 1
-#define HAVE_ENDPOINTVOLUME_H 1
 
 #define HAVE_LIBC 1
 #define STDC_HEADERS 1
@@ -127,16 +126,13 @@ typedef unsigned int uintptr_t;
 #define HAVE_STRLEN 1
 #define HAVE__STRREV 1
 #define HAVE__STRUPR 1
-//#define HAVE__STRLWR 1    // TODO, WinRT: consider using _strlwr_s instead
 #define HAVE_STRCHR 1
 #define HAVE_STRRCHR 1
 #define HAVE_STRSTR 1
-//#define HAVE_ITOA 1   // TODO, WinRT: consider using _itoa_s instead
-//#define HAVE__LTOA 1  // TODO, WinRT: consider using _ltoa_s instead
-//#define HAVE__ULTOA 1 // TODO, WinRT: consider using _ultoa_s instead
 #define HAVE_STRTOL 1
 #define HAVE_STRTOUL 1
-//#define HAVE_STRTOLL 1
+/* #undef HAVE_STRTOLL */
+/* #undef HAVE_STRTOULL */
 #define HAVE_STRTOD 1
 #define HAVE_ATOI 1
 #define HAVE_ATOF 1
@@ -145,7 +141,12 @@ typedef unsigned int uintptr_t;
 #define HAVE__STRICMP 1
 #define HAVE__STRNICMP 1
 #define HAVE_VSNPRINTF 1
-//#define HAVE_SSCANF 1 // TODO, WinRT: consider using sscanf_s instead
+/* TODO, WinRT: consider using ??_s versions of the following */
+/* #undef HAVE__STRLWR */
+/* #undef HAVE_ITOA */
+/* #undef HAVE__LTOA */
+/* #undef HAVE__ULTOA */
+/* #undef HAVE_SSCANF */
 #define HAVE_M_PI 1
 #define HAVE_ACOS   1
 #define HAVE_ACOSF  1
@@ -172,8 +173,12 @@ typedef unsigned int uintptr_t;
 #define HAVE_LOGF   1
 #define HAVE_LOG10  1
 #define HAVE_LOG10F 1
+#define HAVE_LROUND 1
+#define HAVE_LROUNDF 1
 #define HAVE_POW    1
 #define HAVE_POWF   1
+#define HAVE_ROUND 1
+#define HAVE_ROUNDF 1
 #define HAVE__SCALB 1
 #define HAVE_SIN    1
 #define HAVE_SINF   1
@@ -181,6 +186,8 @@ typedef unsigned int uintptr_t;
 #define HAVE_SQRTF  1
 #define HAVE_TAN    1
 #define HAVE_TANF   1
+#define HAVE_TRUNC  1
+#define HAVE_TRUNCF 1
 #define HAVE__FSEEKI64 1
 
 /* Enable various audio drivers */
@@ -193,6 +200,7 @@ typedef unsigned int uintptr_t;
 #define SDL_JOYSTICK_DISABLED 1
 #define SDL_HAPTIC_DISABLED 1
 #else
+#define SDL_JOYSTICK_VIRTUAL    1
 #define SDL_JOYSTICK_XINPUT 1
 #define SDL_HAPTIC_XINPUT   1
 #endif
@@ -205,6 +213,7 @@ typedef unsigned int uintptr_t;
 
 /* Enable various threading systems */
 #if (NTDDI_VERSION >= NTDDI_WINBLUE)
+#define SDL_THREAD_GENERIC_COND_SUFFIX 1
 #define SDL_THREAD_WINDOWS  1
 #else
 /* WinRT on Windows 8.0 and Windows Phone 8.0 don't support CreateThread() */

dep/msvc/sdl2/include/SDL_config_wiz.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -67,6 +67,7 @@
 #define HAVE_STRCHR 1
 #define HAVE_STRRCHR 1
 #define HAVE_STRSTR 1
+#define HAVE_STRTOK_R 1
 #define HAVE_STRTOL 1
 #define HAVE_STRTOUL 1
 #define HAVE_STRTOLL 1
@@ -106,8 +107,12 @@
 #define HAVE_LOGF   1
 #define HAVE_LOG10  1
 #define HAVE_LOG10F 1
+#define HAVE_LROUND 1
+#define HAVE_LROUNDF 1
 #define HAVE_POW    1
 #define HAVE_POWF   1
+#define HAVE_ROUND 1
+#define HAVE_ROUNDF 1
 #define HAVE_SCALBN 1
 #define HAVE_SCALBNF    1
 #define HAVE_SIN    1
@@ -116,6 +121,8 @@
 #define HAVE_SQRTF  1
 #define HAVE_TAN    1
 #define HAVE_TANF   1
+#define HAVE_TRUNC    1
+#define HAVE_TRUNCF   1
 #define HAVE_SIGACTION 1
 #define HAVE_SETJMP 1
 #define HAVE_NANOSLEEP 1
@@ -125,8 +132,8 @@
 #define SDL_AUDIO_DRIVER_OSS 1
 
 #define SDL_INPUT_LINUXEV 1
-#define SDL_INPUT_TSLIB 1
 #define SDL_JOYSTICK_LINUX 1
+#define SDL_JOYSTICK_VIRTUAL 1
 #define SDL_HAPTIC_LINUX 1
 
 #define SDL_SENSOR_DUMMY  1

dep/msvc/sdl2/include/SDL_copying.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_cpuinfo.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -34,11 +34,20 @@
 /* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */
 #if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64))
 #ifdef __clang__
-/* Many of the intrinsics SDL uses are not implemented by clang with Visual Studio */
+/* As of Clang 11, '_m_prefetchw' is conflicting with the winnt.h's version,
-#undef __MMX__
+   so we define the needed '_m_prefetch' here as a pseudo-header, until the issue is fixed. */
-#undef __SSE__
+
-#undef __SSE2__
+#ifndef __PRFCHWINTRIN_H
-#else
+#define __PRFCHWINTRIN_H
+
+static __inline__ void __attribute__((__always_inline__, __nodebug__))
+_m_prefetch(void *__P)
+{
+  __builtin_prefetch (__P, 0, 3 /* _MM_HINT_T0 */);
+}
+
+#endif /* __PRFCHWINTRIN_H */
+#endif /* __clang__ */
 #include <intrin.h>
 #ifndef _WIN64
 #ifndef __MMX__
@@ -54,9 +63,11 @@
 #ifndef __SSE2__
 #define __SSE2__
 #endif
-#endif /* __clang__ */
 #elif defined(__MINGW64_VERSION_MAJOR)
 #include <intrin.h>
+#if !defined(SDL_DISABLE_ARM_NEON_H) && defined(__ARM_NEON)
+#  include <arm_neon.h>
+#endif
 #else
 /* altivec.h redefining bool causes a number of problems, see bugs 3993 and 4392, so you need to explicitly define SDL_ENABLE_ALTIVEC_H to have it included. */
 #if defined(HAVE_ALTIVEC_H) && defined(__ALTIVEC__) && !defined(__APPLE_ALTIVEC__) && defined(SDL_ENABLE_ALTIVEC_H)
@@ -74,11 +85,13 @@
 #    endif
 #    if defined (_M_ARM64)
 #      include <arm64intr.h>
-#      include <arm_neon.h>
+#      include <arm64_neon.h>
 #      define __ARM_NEON 1 /* Set __ARM_NEON so that it can be used elsewhere, at compile time */
 #    endif
 #  endif
 #endif
+#endif /* compiler version */
+
 #if defined(__3dNOW__) && !defined(SDL_DISABLE_MM3DNOW_H)
 #include <mm3dnow.h>
 #endif
@@ -98,7 +111,6 @@
 #include <pmmintrin.h>
 #endif
 #endif /* HAVE_IMMINTRIN_H */
-#endif /* compiler version */
 
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
@@ -114,151 +126,393 @@ extern "C" {
 #define SDL_CACHELINE_SIZE  128
 
 /**
- *  This function returns the number of CPU cores available.
+ * Get the number of CPU cores available.
+ *
+ * \returns the total number of logical CPU cores. On CPUs that include
+ *          technologies such as hyperthreading, the number of logical cores
+ *          may be more than the number of physical cores.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC int SDLCALL SDL_GetCPUCount(void);
 
 /**
- *  This function returns the L1 cache line size of the CPU
+ * Determine the L1 cache line size of the CPU.
+ *
+ * This is useful for determining multi-threaded structure padding or SIMD
+ * prefetch sizes.
  *
- *  This is useful for determining multi-threaded structure padding
+ * \returns the L1 cache line size of the CPU, in bytes.
- *  or SIMD prefetch sizes.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void);
 
 /**
- *  This function returns true if the CPU has the RDTSC instruction.
+ * Determine whether the CPU has the RDTSC instruction.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has the RDTSC instruction or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
 
 /**
- *  This function returns true if the CPU has AltiVec features.
+ * Determine whether the CPU has AltiVec features.
+ *
+ * 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.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void);
 
 /**
- *  This function returns true if the CPU has MMX features.
+ * Determine whether the CPU has MMX features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void);
 
 /**
- *  This function returns true if the CPU has 3DNow! features.
+ * Determine whether the CPU has 3DNow! features.
+ *
+ * This always returns false on CPUs that aren't using AMD instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has 3DNow! features or SDL_FALSE if not.
+ *
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void);
 
 /**
- *  This function returns true if the CPU has SSE features.
+ * Determine whether the CPU has SSE features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void);
 
 /**
- *  This function returns true if the CPU has SSE2 features.
+ * Determine whether the CPU has SSE2 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void);
 
 /**
- *  This function returns true if the CPU has SSE3 features.
+ * Determine whether the CPU has SSE3 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void);
 
 /**
- *  This function returns true if the CPU has SSE4.1 features.
+ * Determine whether the CPU has SSE4.1 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE42
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void);
 
 /**
- *  This function returns true if the CPU has SSE4.2 features.
+ * Determine whether the CPU has SSE4.2 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void);
 
 /**
- *  This function returns true if the CPU has AVX features.
+ * Determine whether the CPU has AVX features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void);
 
 /**
- *  This function returns true if the CPU has AVX2 features.
+ * Determine whether the CPU has AVX2 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void);
 
 /**
- *  This function returns true if the CPU has AVX-512F (foundation) features.
+ * Determine whether the CPU has AVX-512F (foundation) features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not.
+ *
+ * \sa SDL_HasAVX
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void);
 
 /**
- *  This function returns true if the CPU has NEON (ARM SIMD) features.
+ * Determine whether the CPU has ARM SIMD (ARMv6) features.
+ *
+ * This is different from ARM NEON, which is a different instruction set.
+ *
+ * This always returns false on CPUs that aren't using ARM instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not.
+ *
+ * \sa SDL_HasNEON
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void);
+
+/**
+ * Determine whether the CPU has NEON (ARM SIMD) features.
+ *
+ * This always returns false on CPUs that aren't using ARM instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void);
 
 /**
- *  This function returns the amount of RAM configured in the system, in MB.
+ * Get the amount of RAM configured in the system.
+ *
+ * \returns the amount of RAM configured in the system in MB.
+ *
+ * \since This function is available since SDL 2.0.1.
  */
 extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
 
 /**
- * \brief Report the alignment this system needs for SIMD allocations.
+ * 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.
+ * aligned to be compatible with SIMD instructions on the current machine. For
- *  For example, if the machine supports SSE only, it will return 16, but if
+ * example, if the machine supports SSE only, it will return 16, but if it
- *  it supports AVX-512F, it'll return 64 (etc). This only reports values for
+ * 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
+ * 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
+ * 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.
+ * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
- *  Plan accordingly.
+ * Plan accordingly.
+ *
+ * \returns the alignment in bytes needed for available, known SIMD
+ *          instructions.
  */
 extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
 
 /**
- * \brief Allocate memory in a SIMD-friendly way.
+ * 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
+ * instructions. Specifically, it will be properly aligned and padded for the
- *  the system's supported vector instructions.
+ * system's supported vector instructions.
  *
- * The memory returned will be padded such that it is safe to read or write
+ * The memory returned will be padded such that it is safe to read or write an
- *  an incomplete vector at the end of the memory block. This can be useful
+ * incomplete vector at the end of the memory block. This can be useful so you
- *  so you don't have to drop back to a scalar fallback at the end of your
+ * don't have to drop back to a scalar fallback at the end of your SIMD
- *  SIMD processing loop to deal with the final elements without overflowing
+ * processing loop to deal with the final elements without overflowing the
- *  the allocated buffer.
+ * allocated buffer.
  *
- * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free()
+ * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free() or
- *  or delete[], etc.
+ * delete[], etc.
  *
- * Note that SDL will only deal with SIMD instruction sets it is aware of;
+ * Note that SDL will only deal with SIMD instruction sets it is aware of; for
- *  for example, SDL 2.0.8 knows that SSE wants 16-byte vectors
+ * example, SDL 2.0.8 knows that SSE wants 16-byte vectors (SDL_HasSSE()), and
- *  (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't
+ * AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't know that AVX-512 wants
- *  know that AVX-512 wants 64. To be clear: if you can't decide to use an
+ * 64. To be clear: if you can't decide to use an instruction set with an
- *  instruction set with an SDL_Has*() function, don't use that instruction
+ * SDL_Has*() function, don't use that instruction set with memory allocated
- *  set with memory allocated through here.
+ * through here.
  *
  * SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't
- *  out of memory.
+ * out of memory, but you are not allowed to dereference it (because you only
+ * own zero bytes of that buffer).
  *
- *  \param len The length, in bytes, of the block to allocated. The actual
+ * \param len The length, in bytes, of the block to allocate. The actual
- *             allocated block might be larger due to padding, etc.
+ *            allocated block might be larger due to padding, etc.
- * \return Pointer to newly-allocated block, NULL if out of memory.
+ * \returns a pointer to thenewly-allocated block, NULL if out of memory.
  *
  * \sa SDL_SIMDAlignment
+ * \sa SDL_SIMDRealloc
  * \sa SDL_SIMDFree
  */
 extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
 
 /**
- * \brief Deallocate memory obtained from SDL_SIMDAlloc
+ * Reallocate memory obtained from SDL_SIMDAlloc
  *
  * It is not valid to use this function on a pointer from anything but
- *  SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
+ * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
- *  SDL_malloc, memalign, new[], etc.
+ * SDL_malloc, memalign, new[], etc.
+ *
+ * \param mem The pointer obtained from SDL_SIMDAlloc. This function also
+ *            accepts NULL, at which point this function is the same as
+ *            calling SDL_SIMDAlloc with a NULL pointer.
+ * \param len The length, in bytes, of the block to allocated. The actual
+ *            allocated block might be larger due to padding, etc. Passing 0
+ *            will return a non-NULL pointer, assuming the system isn't out of
+ *            memory.
+ * \returns a pointer to the newly-reallocated block, NULL if out of memory.
+ *
+ * \sa SDL_SIMDAlignment
+ * \sa SDL_SIMDAlloc
+ * \sa SDL_SIMDFree
+ */
+extern DECLSPEC void * SDLCALL SDL_SIMDRealloc(void *mem, const size_t len);
+
+/**
+ * Deallocate memory obtained from SDL_SIMDAlloc
+ *
+ * It is not valid to use this function on a pointer from anything but
+ * SDL_SIMDAlloc() or SDL_SIMDRealloc(). It can't be used on pointers from
+ * malloc, realloc, SDL_malloc, memalign, new[], etc.
  *
  * 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.
+ *
+ * \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
  */
 extern DECLSPEC void SDLCALL SDL_SIMDFree(void *ptr);
 
-/* vi: set ts=4 sw=4 expandtab: */
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

dep/msvc/sdl2/include/SDL_egl.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -390,6 +390,9 @@ typedef enum {
 #ifndef WIN32_LEAN_AND_MEAN
 #define WIN32_LEAN_AND_MEAN 1
 #endif
+#ifndef NOMINMAX   /* don't define min() and max(). */
+#define NOMINMAX
+#endif
 #include <windows.h>
 
 #if __WINRT__

dep/msvc/sdl2/include/SDL_endian.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -30,6 +30,26 @@
 
 #include "SDL_stdinc.h"
 
+#ifdef _MSC_VER
+/* As of Clang 11, '_m_prefetchw' is conflicting with the winnt.h's version,
+   so we define the needed '_m_prefetch' here as a pseudo-header, until the issue is fixed. */
+
+#ifdef __clang__
+#ifndef __PRFCHWINTRIN_H
+#define __PRFCHWINTRIN_H
+
+static __inline__ void __attribute__((__always_inline__, __nodebug__))
+_m_prefetch(void *__P)
+{
+  __builtin_prefetch (__P, 0, 3 /* _MM_HINT_T0 */);
+}
+
+#endif /* __PRFCHWINTRIN_H */
+#endif /* __clang__ */
+
+#include <intrin.h>
+#endif
+
 /**
  *  \name The two types of endianness
  */
@@ -42,10 +62,16 @@
 #ifdef __linux__
 #include <endian.h>
 #define SDL_BYTEORDER  __BYTE_ORDER
-#else /* __linux__ */
+#elif defined(__OpenBSD__)
+#include <endian.h>
+#define SDL_BYTEORDER  BYTE_ORDER
+#elif defined(__FreeBSD__) || defined(__NetBSD__)
+#include <sys/endian.h>
+#define SDL_BYTEORDER  BYTE_ORDER
+#else
 #if defined(__hppa__) || \
     defined(__m68k__) || defined(mc68000) || defined(_M_M68K) || \
-    (defined(__MIPS__) && defined(__MISPEB__)) || \
+    (defined(__MIPS__) && defined(__MIPSEB__)) || \
     defined(__ppc__) || defined(__POWERPC__) || defined(_M_PPC) || \
     defined(__sparc__)
 #define SDL_BYTEORDER   SDL_BIG_ENDIAN
@@ -65,8 +91,11 @@ extern "C" {
 /**
  *  \file SDL_endian.h
  */
-#if defined(__GNUC__) && defined(__i386__) && \
+#if (defined(__clang__) && (__clang_major__ > 3 || (__clang_major__ == 3 && __clang_minor__ >= 2))) || \
-   !(__GNUC__ == 2 && __GNUC_MINOR__ == 95 /* broken gcc version */)
+    (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 8)))
+#define SDL_Swap16(x) __builtin_bswap16(x)
+#elif defined(__GNUC__) && defined(__i386__) && \
+   !(__GNUC__ == 2 && __GNUC_MINOR__ <= 95 /* broken gcc version */)
 SDL_FORCE_INLINE Uint16
 SDL_Swap16(Uint16 x)
 {
@@ -89,13 +118,23 @@ SDL_Swap16(Uint16 x)
   __asm__("rlwimi %0,%2,8,16,23": "=&r"(result):"0"(x >> 8), "r"(x));
     return (Uint16)result;
 }
-#elif defined(__GNUC__) && (defined(__M68000__) || defined(__M68020__)) && !defined(__mcoldfire__)
+#elif defined(__GNUC__) && defined(__aarch64__)
+SDL_FORCE_INLINE Uint16
+SDL_Swap16(Uint16 x)
+{
+  __asm__("rev16 %w1, %w0" : "=r"(x) : "r"(x));
+  return x;
+}
+#elif defined(__GNUC__) && (defined(__m68k__) && !defined(__mcoldfire__))
 SDL_FORCE_INLINE Uint16
 SDL_Swap16(Uint16 x)
 {
   __asm__("rorw #8,%0": "=d"(x): "0"(x):"cc");
     return x;
 }
+#elif defined(_MSC_VER)
+#pragma intrinsic(_byteswap_ushort)
+#define SDL_Swap16(x) _byteswap_ushort(x)
 #elif defined(__WATCOMC__) && defined(__386__)
 extern _inline Uint16 SDL_Swap16(Uint16);
 #pragma aux SDL_Swap16 = \
@@ -110,7 +149,11 @@ SDL_Swap16(Uint16 x)
 }
 #endif
 
-#if defined(__GNUC__) && defined(__i386__)
+#if (defined(__clang__) && (__clang_major__ > 2 || (__clang_major__ == 2 && __clang_minor__ >= 6))) || \
+    (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)))
+#define SDL_Swap32(x) __builtin_bswap32(x)
+#elif defined(__GNUC__) && defined(__i386__) && \
+   !(__GNUC__ == 2 && __GNUC_MINOR__ <= 95 /* broken gcc version */)
 SDL_FORCE_INLINE Uint32
 SDL_Swap32(Uint32 x)
 {
@@ -130,12 +173,19 @@ SDL_Swap32(Uint32 x)
 {
     Uint32 result;
 
-  __asm__("rlwimi %0,%2,24,16,23": "=&r"(result):"0"(x >> 24), "r"(x));
+  __asm__("rlwimi %0,%2,24,16,23": "=&r"(result): "0" (x>>24),  "r"(x));
-  __asm__("rlwimi %0,%2,8,8,15": "=&r"(result):"0"(result), "r"(x));
+  __asm__("rlwimi %0,%2,8,8,15"  : "=&r"(result): "0" (result), "r"(x));
-  __asm__("rlwimi %0,%2,24,0,7": "=&r"(result):"0"(result), "r"(x));
+  __asm__("rlwimi %0,%2,24,0,7"  : "=&r"(result): "0" (result), "r"(x));
     return result;
 }
-#elif defined(__GNUC__) && (defined(__M68000__) || defined(__M68020__)) && !defined(__mcoldfire__)
+#elif defined(__GNUC__) && defined(__aarch64__)
+SDL_FORCE_INLINE Uint32
+SDL_Swap32(Uint32 x)
+{
+  __asm__("rev %w1, %w0": "=r"(x):"r"(x));
+  return x;
+}
+#elif defined(__GNUC__) && (defined(__m68k__) && !defined(__mcoldfire__))
 SDL_FORCE_INLINE Uint32
 SDL_Swap32(Uint32 x)
 {
@@ -144,19 +194,13 @@ SDL_Swap32(Uint32 x)
 }
 #elif defined(__WATCOMC__) && defined(__386__)
 extern _inline Uint32 SDL_Swap32(Uint32);
-#ifndef __SW_3 /* 486+ */
 #pragma aux SDL_Swap32 = \
   "bswap eax"  \
   parm   [eax] \
   modify [eax];
-#else  /* 386-only */
+#elif defined(_MSC_VER)
-#pragma aux SDL_Swap32 = \
+#pragma intrinsic(_byteswap_ulong)
-  "xchg al, ah"  \
+#define SDL_Swap32(x) _byteswap_ulong(x)
-  "ror  eax, 16" \
-  "xchg al, ah"  \
-  parm   [eax]   \
-  modify [eax];
-#endif
 #else
 SDL_FORCE_INLINE Uint32
 SDL_Swap32(Uint32 x)
@@ -166,22 +210,24 @@ SDL_Swap32(Uint32 x)
 }
 #endif
 
-#if defined(__GNUC__) && defined(__i386__)
+#if (defined(__clang__) && (__clang_major__ > 2 || (__clang_major__ == 2 && __clang_minor__ >= 6))) || \
+    (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)))
+#define SDL_Swap64(x) __builtin_bswap64(x)
+#elif defined(__GNUC__) && defined(__i386__) && \
+   !(__GNUC__ == 2 && __GNUC_MINOR__ <= 95 /* broken gcc version */)
 SDL_FORCE_INLINE Uint64
 SDL_Swap64(Uint64 x)
 {
-    union
+    union {
-    {
+        struct {
-        struct
-        {
             Uint32 a, b;
         } s;
         Uint64 u;
     } v;
     v.u = x;
-  __asm__("bswapl %0 ; bswapl %1 ; xchgl %0,%1": "=r"(v.s.a), "=r"(v.s.b):"0"(v.s.a),
+  __asm__("bswapl %0 ; bswapl %1 ; xchgl %0,%1"
-            "1"(v.s.
+          : "=r"(v.s.a), "=r"(v.s.b)
-                b));
+          : "0" (v.s.a),  "1"(v.s.b));
     return v.u;
 }
 #elif defined(__GNUC__) && defined(__x86_64__)
@@ -191,6 +237,17 @@ SDL_Swap64(Uint64 x)
   __asm__("bswapq %0": "=r"(x):"0"(x));
     return x;
 }
+#elif defined(__WATCOMC__) && defined(__386__)
+extern _inline Uint64 SDL_Swap64(Uint64);
+#pragma aux SDL_Swap64 = \
+  "bswap eax"     \
+  "bswap edx"     \
+  "xchg eax,edx"  \
+  parm [eax edx]  \
+  modify [eax edx];
+#elif defined(_MSC_VER)
+#pragma intrinsic(_byteswap_uint64)
+#define SDL_Swap64(x) _byteswap_uint64(x)
 #else
 SDL_FORCE_INLINE Uint64
 SDL_Swap64(Uint64 x)
@@ -212,8 +269,7 @@ SDL_Swap64(Uint64 x)
 SDL_FORCE_INLINE float
 SDL_SwapFloat(float x)
 {
-    union
+    union {
-    {
         float f;
         Uint32 ui32;
     } swapper;
@@ -229,22 +285,22 @@ SDL_SwapFloat(float x)
  */
 /* @{ */
 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
-#define SDL_SwapLE16(X) (X)
+#define SDL_SwapLE16(X)     (X)
-#define SDL_SwapLE32(X) (X)
+#define SDL_SwapLE32(X)     (X)
-#define SDL_SwapLE64(X) (X)
+#define SDL_SwapLE64(X)     (X)
 #define SDL_SwapFloatLE(X)  (X)
-#define SDL_SwapBE16(X) SDL_Swap16(X)
+#define SDL_SwapBE16(X)     SDL_Swap16(X)
-#define SDL_SwapBE32(X) SDL_Swap32(X)
+#define SDL_SwapBE32(X)     SDL_Swap32(X)
-#define SDL_SwapBE64(X) SDL_Swap64(X)
+#define SDL_SwapBE64(X)     SDL_Swap64(X)
 #define SDL_SwapFloatBE(X)  SDL_SwapFloat(X)
 #else
-#define SDL_SwapLE16(X) SDL_Swap16(X)
+#define SDL_SwapLE16(X)     SDL_Swap16(X)
-#define SDL_SwapLE32(X) SDL_Swap32(X)
+#define SDL_SwapLE32(X)     SDL_Swap32(X)
-#define SDL_SwapLE64(X) SDL_Swap64(X)
+#define SDL_SwapLE64(X)     SDL_Swap64(X)
 #define SDL_SwapFloatLE(X)  SDL_SwapFloat(X)
-#define SDL_SwapBE16(X) (X)
+#define SDL_SwapBE16(X)     (X)
-#define SDL_SwapBE32(X) (X)
+#define SDL_SwapBE32(X)     (X)
-#define SDL_SwapBE64(X) (X)
+#define SDL_SwapBE64(X)     (X)
 #define SDL_SwapFloatBE(X)  (X)
 #endif
 /* @} *//* Swap to native */

dep/msvc/sdl2/include/SDL_error.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -37,9 +37,88 @@ extern "C" {
 #endif
 
 /* Public functions */
-/* SDL_SetError() unconditionally returns -1. */
+
+
+/**
+ * Set the SDL error message for the current thread.
+ *
+ * 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:
+ *
+ * ```c
+ * if (error_code) {
+ *     return SDL_SetError("This operation has failed: %d", error_code);
+ * }
+ * ```
+ *
+ * \param fmt a printf()-style message format string
+ * \param ... additional parameters matching % tokens in the `fmt` string, if
+ *            any
+ * \returns always -1.
+ *
+ * \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.
+ *
+ * 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.
+ *
+ * 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
+ * string applies.
+ *
+ * Error strings are set per-thread, so an error set in a different thread
+ * will not interfere with the current thread's operation.
+ *
+ * The returned string is internally allocated and must not be freed by the
+ * application.
+ *
+ * \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().
+ *
+ * \sa SDL_ClearError
+ * \sa SDL_SetError
+ */
 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().
+ *
+ * \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.
+ *
+ * \sa SDL_GetError
+ */
+extern DECLSPEC char * SDLCALL SDL_GetErrorMsg(char *errstr, int maxlen);
+
+/**
+ * Clear any previous error message for this thread.
+ *
+ * \sa SDL_GetError
+ * \sa SDL_SetError
+ */
 extern DECLSPEC void SDLCALL SDL_ClearError(void);
 
 /**

dep/msvc/sdl2/include/SDL_events.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -50,7 +50,7 @@ extern "C" {
 #define SDL_PRESSED 1
 
 /**
- * \brief The types of events that can be delivered.
+ * The types of events that can be delivered.
  */
 typedef enum
 {
@@ -85,6 +85,8 @@ typedef enum
                                      Called on Android in onResume()
                                 */
 
+    SDL_LOCALECHANGED,  /**< The user's locale preferences have changed. */
+
     /* Display events */
     SDL_DISPLAYEVENT   = 0x150,  /**< Display state change */
 
@@ -123,6 +125,10 @@ typedef enum
     SDL_CONTROLLERDEVICEADDED,         /**< A new Game controller has been inserted into the system */
     SDL_CONTROLLERDEVICEREMOVED,       /**< An opened Game controller has been removed */
     SDL_CONTROLLERDEVICEREMAPPED,      /**< The controller mapping was updated */
+    SDL_CONTROLLERTOUCHPADDOWN,        /**< Game controller touchpad was touched */
+    SDL_CONTROLLERTOUCHPADMOTION,      /**< Game controller touchpad finger was moved */
+    SDL_CONTROLLERTOUCHPADUP,          /**< Game controller touchpad finger was lifted */
+    SDL_CONTROLLERSENSORUPDATE,        /**< Game controller sensor was updated */
 
     /* Touch events */
     SDL_FINGERDOWN      = 0x700,
@@ -413,6 +419,33 @@ typedef struct SDL_ControllerDeviceEvent
     Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
 } SDL_ControllerDeviceEvent;
 
+/**
+ *  \brief Game controller touchpad event structure (event.ctouchpad.*)
+ */
+typedef struct SDL_ControllerTouchpadEvent
+{
+    Uint32 type;        /**< ::SDL_CONTROLLERTOUCHPADDOWN or ::SDL_CONTROLLERTOUCHPADMOTION or ::SDL_CONTROLLERTOUCHPADUP */
+    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
+    SDL_JoystickID which; /**< The joystick instance id */
+    Sint32 touchpad;    /**< The index of the touchpad */
+    Sint32 finger;      /**< The index of the finger on the touchpad */
+    float x;            /**< Normalized in the range 0...1 with 0 being on the left */
+    float y;            /**< Normalized in the range 0...1 with 0 being at the top */
+    float pressure;     /**< Normalized in the range 0...1 */
+} SDL_ControllerTouchpadEvent;
+
+/**
+ *  \brief Game controller sensor event structure (event.csensor.*)
+ */
+typedef struct SDL_ControllerSensorEvent
+{
+    Uint32 type;        /**< ::SDL_CONTROLLERSENSORUPDATE */
+    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
+    SDL_JoystickID which; /**< The joystick instance id */
+    Sint32 sensor;      /**< The type of the sensor, one of the values of ::SDL_SensorType */
+    float data[3];      /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */
+} SDL_ControllerSensorEvent;
+
 /**
  *  \brief Audio device event structure (event.adevice.*)
  */
@@ -442,6 +475,7 @@ typedef struct SDL_TouchFingerEvent
     float dx;           /**< Normalized in the range -1...1 */
     float dy;           /**< Normalized in the range -1...1 */
     float pressure;     /**< Normalized in the range 0...1 */
+    Uint32 windowID;    /**< The window underneath the finger, if any */
 } SDL_TouchFingerEvent;
 
 
@@ -556,56 +590,77 @@ typedef struct SDL_SysWMEvent
  */
 typedef union SDL_Event
 {
-    Uint32 type;                    /**< Event type, shared with all events */
+    Uint32 type;                            /**< Event type, shared with all events */
-    SDL_CommonEvent common;         /**< Common event data */
+    SDL_CommonEvent common;                 /**< Common event data */
-    SDL_DisplayEvent display;       /**< Window event data */
+    SDL_DisplayEvent display;               /**< Display event data */
-    SDL_WindowEvent window;         /**< Window event data */
+    SDL_WindowEvent window;                 /**< Window event data */
-    SDL_KeyboardEvent key;          /**< Keyboard event data */
+    SDL_KeyboardEvent key;                  /**< Keyboard event data */
-    SDL_TextEditingEvent edit;      /**< Text editing event data */
+    SDL_TextEditingEvent edit;              /**< Text editing event data */
-    SDL_TextInputEvent text;        /**< Text input event data */
+    SDL_TextInputEvent text;                /**< Text input event data */
-    SDL_MouseMotionEvent motion;    /**< Mouse motion event data */
+    SDL_MouseMotionEvent motion;            /**< Mouse motion event data */
-    SDL_MouseButtonEvent button;    /**< Mouse button event data */
+    SDL_MouseButtonEvent button;            /**< Mouse button event data */
-    SDL_MouseWheelEvent wheel;      /**< Mouse wheel event data */
+    SDL_MouseWheelEvent wheel;              /**< Mouse wheel event data */
-    SDL_JoyAxisEvent jaxis;         /**< Joystick axis event data */
+    SDL_JoyAxisEvent jaxis;                 /**< Joystick axis event data */
-    SDL_JoyBallEvent jball;         /**< Joystick ball event data */
+    SDL_JoyBallEvent jball;                 /**< Joystick ball event data */
-    SDL_JoyHatEvent jhat;           /**< Joystick hat event data */
+    SDL_JoyHatEvent jhat;                   /**< Joystick hat event data */
-    SDL_JoyButtonEvent jbutton;     /**< Joystick button event data */
+    SDL_JoyButtonEvent jbutton;             /**< Joystick button event data */
-    SDL_JoyDeviceEvent jdevice;     /**< Joystick device change event data */
+    SDL_JoyDeviceEvent jdevice;             /**< Joystick device change event data */
-    SDL_ControllerAxisEvent caxis;      /**< Game Controller axis event data */
+    SDL_ControllerAxisEvent caxis;          /**< Game Controller axis event data */
-    SDL_ControllerButtonEvent cbutton;  /**< Game Controller button event data */
+    SDL_ControllerButtonEvent cbutton;      /**< Game Controller button event data */
-    SDL_ControllerDeviceEvent cdevice;  /**< Game Controller device event data */
+    SDL_ControllerDeviceEvent cdevice;      /**< Game Controller device event data */
-    SDL_AudioDeviceEvent adevice;   /**< Audio device event data */
+    SDL_ControllerTouchpadEvent ctouchpad;  /**< Game Controller touchpad event data */
-    SDL_SensorEvent sensor;         /**< Sensor event data */
+    SDL_ControllerSensorEvent csensor;      /**< Game Controller sensor event data */
-    SDL_QuitEvent quit;             /**< Quit request event data */
+    SDL_AudioDeviceEvent adevice;           /**< Audio device event data */
-    SDL_UserEvent user;             /**< Custom event data */
+    SDL_SensorEvent sensor;                 /**< Sensor event data */
-    SDL_SysWMEvent syswm;           /**< System dependent window event data */
+    SDL_QuitEvent quit;                     /**< Quit request event data */
-    SDL_TouchFingerEvent tfinger;   /**< Touch finger event data */
+    SDL_UserEvent user;                     /**< Custom event data */
-    SDL_MultiGestureEvent mgesture; /**< Gesture event data */
+    SDL_SysWMEvent syswm;                   /**< System dependent window event data */
-    SDL_DollarGestureEvent dgesture; /**< Gesture event data */
+    SDL_TouchFingerEvent tfinger;           /**< Touch finger event data */
-    SDL_DropEvent drop;             /**< Drag and drop event data */
+    SDL_MultiGestureEvent mgesture;         /**< Gesture event data */
-
+    SDL_DollarGestureEvent dgesture;        /**< Gesture event data */
-    /* This is necessary for ABI compatibility between Visual C++ and GCC
+    SDL_DropEvent drop;                     /**< Drag and drop event data */
-       Visual C++ will respect the push pack pragma and use 52 bytes for
+
-       this structure, and GCC will use the alignment of the largest datatype
+    /* This is necessary for ABI compatibility between Visual C++ and GCC.
-       within the union, which is 8 bytes.
+       Visual C++ will respect the push pack pragma and use 52 bytes (size of
+       SDL_TextEditingEvent, the largest structure for 32-bit and 64-bit
+       architectures) for this union, and GCC will use the alignment of the
+       largest datatype within the union, which is 8 bytes on 64-bit
+       architectures.
 
        So... we'll add padding to force the size to be 56 bytes for both.
+
+       On architectures where pointers are 16 bytes, this needs rounding up to
+       the next multiple of 16, 64, and on architectures where pointers are
+       even larger the size of SDL_UserEvent will dominate as being 3 pointers.
     */
-    Uint8 padding[56];
+    Uint8 padding[sizeof(void *) <= 8 ? 56 : sizeof(void *) == 16 ? 64 : 3 * sizeof(void *)];
 } SDL_Event;
 
 /* Make sure we haven't broken binary compatibility */
-SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == 56);
+SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NULL)->padding));
 
 
 /* Function prototypes */
 
 /**
- *  Pumps the event loop, gathering events from the input devices.
+ * Pump the event loop, gathering events from the input devices.
  *
- *  This function updates the event queue and internal input device state.
+ * This function updates the event queue and internal input device state.
  *
- *  This should only be run in the thread that sets the video mode.
+ * **WARNING**: This should only be run in the thread that initialized the
+ * video subsystem, and for extra safety, you should consider only doing those
+ * things on the main thread in any case.
+ *
+ * SDL_PumpEvents() gathers all the pending input information from devices and
+ * places it in the event queue. Without calls to SDL_PumpEvents() no events
+ * would ever be placed on the queue. Often the need for calls to
+ * SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and
+ * SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not
+ * polling or waiting for events (e.g. you are filtering them), then you must
+ * call SDL_PumpEvents() to force an event queue update.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_WaitEvent
  */
 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
 
@@ -618,22 +673,40 @@ typedef enum
 } SDL_eventaction;
 
 /**
- *  Checks the event queue for messages and optionally returns them.
+ * Check the event queue for messages and optionally return them.
+ *
+ * `action` may be any of the following:
  *
- *  If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
+ * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the
- *  the back of the event queue.
+ *   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.
+ * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
+ *   within the specified minimum and maximum type, will be returned to the
+ *   caller and will be removed from the queue.
  *
- *  If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
+ * You may have to call SDL_PumpEvents() before calling this function.
- *  of the event queue, within the specified minimum and maximum type,
+ * Otherwise, the events may not be ready to be filtered when you call
- *  will be returned and will not be removed from the queue.
+ * SDL_PeepEvents().
  *
- *  If \c action is ::SDL_GETEVENT, up to \c numevents events at the front
+ * This function is thread-safe.
- *  of the event queue, within the specified minimum and maximum type,
- *  will be returned and will be removed from the queue.
  *
- *  \return The number of events actually stored, or -1 if there was an error.
+ * \param events destination buffer for the retrieved events
+ * \param numevents if action is SDL_ADDEVENT, the number of events to add
+ *                  back to the event queue; if action is SDL_PEEKEVENT or
+ *                  SDL_GETEVENT, the maximum number of events to retrieve
+ * \param action action to take; see [[#action|Remarks]] for details
+ * \param minType minimum value of the event type to be considered;
+ *                SDL_FIRSTEVENT is a safe choice
+ * \param maxType maximum value of the event type to be considered;
+ *                SDL_LASTEVENT is a safe choice
+ * \returns the number of events actually stored or a negative error code on
+ *          failure; call SDL_GetError() for more information.
  *
- *  This function is thread-safe.
+ * \sa SDL_PollEvent
+ * \sa SDL_PumpEvents
+ * \sa SDL_PushEvent
  */
 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
                                            SDL_eventaction action,
@@ -641,113 +714,328 @@ extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
 /* @} */
 
 /**
- *  Checks to see if certain event types are in the event queue.
+ * Check for the existence of a certain event type in the event queue.
+ *
+ * If you need to check for a range of event types, use SDL_HasEvents()
+ * instead.
+ *
+ * \param type the type of event to be queried; see SDL_EventType for details
+ * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if
+ *          events matching `type` are not present.
+ *
+ * \sa SDL_HasEvents
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
+
+
+/**
+ * Check for the existence of certain event types in the event queue.
+ *
+ * If you need to check for a single event type, use SDL_HasEvent() instead.
+ *
+ * \param minType the low end of event type to be queried, inclusive; see
+ *                SDL_EventType for details
+ * \param maxType the high end of event type to be queried, inclusive; see
+ *                SDL_EventType for details
+ * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
+ *          present, or SDL_FALSE if not.
+ *
+ * \sa SDL_HasEvents
+ */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
 
 /**
- *  This function clears events from the event queue
+ * Clear events of a specific type from the event queue.
- *  This function only affects currently queued events. If you want to make
+ *
- *  sure that all pending OS events are flushed, you can call SDL_PumpEvents()
+ * This will unconditionally remove any events from the queue that match
- *  on the main thread immediately before the flush call.
+ * `type`. If you need to remove a range of event types, use SDL_FlushEvents()
+ * instead.
+ *
+ * It's also normal to just ignore events you don't care about in your event
+ * loop without calling this function.
+ *
+ * This function only affects currently queued events. If you want to make
+ * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
+ * on the main thread immediately before the flush call.
+ *
+ * \param type the type of event to be cleared; see SDL_EventType for details
+ *
+ * \sa SDL_FlushEvents
  */
 extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
+
+/**
+ * Clear events of a range of types from the event queue.
+ *
+ * This will unconditionally remove any events from the queue that are in the
+ * range of `minType` to `maxType`, inclusive. If you need to remove a single
+ * event type, use SDL_FlushEvent() instead.
+ *
+ * It's also normal to just ignore events you don't care about in your event
+ * loop without calling this function.
+ *
+ * This function only affects currently queued events. If you want to make
+ * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
+ * on the main thread immediately before the flush call.
+ *
+ * \param minType the low end of event type to be cleared, inclusive; see
+ *                SDL_EventType for details
+ * \param maxType the high end of event type to be cleared, inclusive; see
+ *                SDL_EventType for details
+ *
+ * \sa SDL_FlushEvent
+ */
 extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
 
 /**
- *  \brief Polls for currently pending events.
+ * 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 NULL, it simply returns 1 if there is an event in the queue,
+ * but will not remove it from the queue.
+ *
+ * As this function implicitly calls SDL_PumpEvents(), you can only call this
+ * function in the thread that set the video mode.
+ *
+ * SDL_PollEvent() is the favored way of receiving system events since it can
+ * be done from the main loop and does not suspend the main loop while waiting
+ * on an event to be posted.
  *
- *  \return 1 if there are any pending events, or 0 if there are none available.
+ * The common practice is to fully process the event queue once every frame,
+ * usually as a first step before updating the game's state:
  *
- *  \param event If not NULL, the next event is removed from the queue and
+ * ```c
- *               stored in that area.
+ * while (game_is_still_running) {
+ *     SDL_Event event;
+ *     while (SDL_PollEvent(&event)) {  // poll until all events are handled!
+ *         // decide what to do with this event.
+ *     }
+ *
+ *     // update game state, draw the current frame
+ * }
+ * ```
+ *
+ * \param event the SDL_Event structure to be filled with the next event from
+ *              the queue, or NULL
+ * \returns 1 if there is a pending event or 0 if there are none available.
+ *
+ * \sa SDL_GetEventFilter
+ * \sa SDL_PeepEvents
+ * \sa SDL_PushEvent
+ * \sa SDL_SetEventFilter
+ * \sa SDL_WaitEvent
+ * \sa SDL_WaitEventTimeout
  */
 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
 
 /**
- *  \brief Waits indefinitely for the next available event.
+ * Wait indefinitely for the next available event.
  *
- *  \return 1, or 0 if there was an error while waiting for 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`.
  *
- *  \param event If not NULL, the next event is removed from the queue and
+ * As this function implicitly calls SDL_PumpEvents(), you can only call this
- *               stored in that area.
+ * function in the thread that initialized the video subsystem.
+ *
+ * \param event the SDL_Event structure to be filled in with the next event
+ *              from the queue, or NULL
+ * \returns 1 on success or 0 if there was an error while waiting for events;
+ *          call SDL_GetError() for more information.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_PumpEvents
+ * \sa SDL_WaitEventTimeout
  */
 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
 
 /**
- *  \brief Waits until the specified timeout (in milliseconds) for the next
+ * Wait until the specified timeout (in milliseconds) for the next available
- *         available event.
+ * 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`.
  *
- *  \return 1, or 0 if there was an error while waiting for events.
+ * As this function implicitly calls SDL_PumpEvents(), you can only call this
+ * function in the thread that initialized the video subsystem.
  *
- *  \param event If not NULL, the next event is removed from the queue and
+ * \param event the SDL_Event structure to be filled in with the next event
- *               stored in that area.
+ *              from the queue, or NULL
- *  \param timeout The timeout (in milliseconds) to wait for next event.
+ * \param timeout the maximum number of milliseconds to wait for the next
+ *                available event
+ * \returns 1 on success or 0 if there was an error while waiting for events;
+ *          call SDL_GetError() for more information. This also returns 0 if
+ *          the timeout elapsed without an event arriving.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_PumpEvents
+ * \sa SDL_WaitEvent
  */
 extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
                                                  int timeout);
 
 /**
- *  \brief Add an event to the event queue.
+ * Add an event to the event queue.
+ *
+ * The event queue can actually be used as a two way communication channel.
+ * Not only can events be read from the queue, but the user can also push
+ * their own events onto it. `event` is a pointer to the event structure you
+ * wish to push onto the queue. The event is copied into the queue, and the
+ * caller may dispose of the memory pointed to after SDL_PushEvent() returns.
+ *
+ * Note: Pushing device input events onto the queue doesn't modify the state
+ * of the device within SDL.
+ *
+ * This function is thread-safe, and can be called from other threads safely.
+ *
+ * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
+ * the event filter but events added with SDL_PeepEvents() do not.
  *
- *  \return 1 on success, 0 if the event was filtered, or -1 if the event queue
+ * For pushing application-specific events, please use SDL_RegisterEvents() to
- *          was full or there was some other error.
+ * get an event type that does not conflict with other code that also wants
+ * its own custom event types.
+ *
+ * \param event the SDL_Event to be added to the queue
+ * \returns 1 on success, 0 if the event was filtered, or a negative error
+ *          code on failure; call SDL_GetError() for more information. A
+ *          common reason for error is the event queue being full.
+ *
+ * \sa SDL_PeepEvents
+ * \sa SDL_PollEvent
+ * \sa SDL_RegisterEvents
  */
 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
 
+/**
+ * A function pointer used for callbacks that watch the event queue.
+ *
+ * \param userdata what was passed as `userdata` to SDL_SetEventFilter()
+ *        or SDL_AddEventWatch, etc
+ * \param event the event that triggered the callback
+ * \returns 1 to permit event to be added to the queue, and 0 to disallow
+ *          it. When used with SDL_AddEventWatch, the return value is ignored.
+ *
+ * \sa SDL_SetEventFilter
+ * \sa SDL_AddEventWatch
+ */
 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
 
 /**
- *  Sets up a filter to process all events before they change internal state and
+ * Set up a filter to process all events before they change internal state and
- *  are posted to the internal event queue.
+ * are posted to the internal event queue.
  *
- *  The filter is prototyped as:
+ * If the filter function returns 1 when called, then the event will be added
- *  \code
+ * to the internal queue. If it returns 0, then the event will be dropped from
- *      int SDL_EventFilter(void *userdata, SDL_Event * event);
+ * the queue, but the internal state will still be updated. This allows
- *  \endcode
+ * selective filtering of dynamically arriving events.
  *
- *  If the filter returns 1, then the event will be added to the internal queue.
+ * **WARNING**: Be very careful of what you do in the event filter function,
- *  If it returns 0, then the event will be dropped from the queue, but the
+ * as it may run in a different thread!
- *  internal state will still be updated.  This allows selective filtering of
- *  dynamically arriving events.
  *
- *  \warning  Be very careful of what you do in the event filter function, as
+ * On platforms that support it, if the quit event is generated by an
- *            it may run in a different thread!
+ * 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
+ * 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
+ * application window. If the event filter returns 1, then the window will be
- *  be closed, otherwise the window will remain open if possible.
+ * closed, otherwise the window will remain open if possible.
  *
- *  If the quit event is generated by an interrupt signal, it will bypass the
+ * Note: Disabled events never make it to the event filter function; see
- *  internal queue and be delivered to the application at the next event poll.
+ * SDL_EventState().
+ *
+ * Note: If you just want to inspect events without filtering, you should use
+ * SDL_AddEventWatch() instead.
+ *
+ * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
+ * the event filter, but events pushed onto the queue with SDL_PeepEvents() do
+ * not.
+ *
+ * \param filter An SDL_EventFilter function to call when an event happens
+ * \param userdata a pointer that is passed to `filter`
+ *
+ * \sa SDL_AddEventWatch
+ * \sa SDL_EventState
+ * \sa SDL_GetEventFilter
+ * \sa SDL_PeepEvents
+ * \sa SDL_PushEvent
  */
 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
                                                 void *userdata);
 
 /**
- *  Return the current event filter - can be used to "chain" filters.
+ * Query the current event filter.
- *  If there is no event filter set, this function returns SDL_FALSE.
+ *
+ * This function can be used to "chain" filters, by saving the existing filter
+ * before replacing it with a function that will call that saved filter.
+ *
+ * \param filter the current callback function will be stored here
+ * \param userdata the pointer that is passed to the current event filter will
+ *                 be stored here
+ * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set.
+ *
+ * \sa SDL_SetEventFilter
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
                                                     void **userdata);
 
 /**
- *  Add a function which is called when an event is added to the queue.
+ * Add a callback to be triggered when an event is added to the event queue.
+ *
+ * `filter` will be called when an event happens, and its return value is
+ * ignored.
+ *
+ * **WARNING**: Be very careful of what you do in the event filter function,
+ * as it may run in a different thread!
+ *
+ * If the quit event is generated by a signal (e.g. SIGINT), it will bypass
+ * the internal queue and be delivered to the watch callback immediately, and
+ * arrive at the next event poll.
+ *
+ * Note: the callback is called for events posted by the user through
+ * SDL_PushEvent(), but not for disabled events, nor for events by a filter
+ * callback set with SDL_SetEventFilter(), nor for events posted by the user
+ * through SDL_PeepEvents().
+ *
+ * \param filter an SDL_EventFilter function to call when an event happens.
+ * \param userdata a pointer that is passed to `filter`
+ *
+ * \sa SDL_DelEventWatch
+ * \sa SDL_SetEventFilter
  */
 extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
                                                void *userdata);
 
 /**
- *  Remove an event watch function 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.
+ *
+ * \param filter the function originally passed to SDL_AddEventWatch()
+ * \param userdata the pointer originally passed to SDL_AddEventWatch()
+ *
+ * \sa SDL_AddEventWatch
  */
 extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
                                                void *userdata);
 
 /**
- *  Run the filter function on the current event queue, removing any
+ * Run a specific filter function on the current event queue, removing any
- *  events for which the filter returns 0.
+ * 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
+ * supplied filter until this function returns.
+ *
+ * \param filter the SDL_EventFilter function to call when an event happens
+ * \param userdata a pointer that is passed to `filter`
+ *
+ * \sa SDL_GetEventFilter
+ * \sa SDL_SetEventFilter
  */
 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
                                               void *userdata);
@@ -759,24 +1047,43 @@ extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
 #define SDL_ENABLE   1
 
 /**
- *  This function allows you to set the state of processing certain events.
+ * Set the state of processing events by type.
- *   - If \c state is set to ::SDL_IGNORE, that event will be automatically
+ *
- *     dropped from the event queue and will not be filtered.
+ * `state` may be any of the following:
- *   - If \c state is set to ::SDL_ENABLE, that event will be processed
+ *
- *     normally.
+ * - `SDL_QUERY`: returns the current processing state of the specified event
- *   - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the
+ * - `SDL_IGNORE` (aka `SDL_DISABLE`): the event will automatically be dropped
- *     current processing state of the specified event.
+ *   from the event queue and will not be filtered
+ * - `SDL_ENABLE`: the event will be processed normally
+ *
+ * \param type the type of event; see SDL_EventType for details
+ * \param state how to process the event
+ * \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state
+ *          of the event before this function makes any changes to it.
+ *
+ * \sa SDL_GetEventState
  */
 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
 /* @} */
 #define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
 
 /**
- *  This function allocates a set of user-defined events, and returns
+ * Allocate a set of user-defined events, and return the beginning event
- *  the beginning event number for that set of events.
+ * number for that set of events.
+ *
+ * Calling this function with `numevents` <= 0 is an error and will return
+ * (Uint32)-1.
+ *
+ * Note, (Uint32)-1 means the maximum unsigned 32-bit integer value (or
+ * 0xFFFFFFFF), but is clearer to write.
+ *
+ * \param numevents the number of events to be allocated
+ * \returns the beginning event number, or (Uint32)-1 if there are not enough
+ *          user-defined events left.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  If there aren't enough user-defined events left, this function
+ * \sa SDL_PushEvent
- *  returns (Uint32)-1
  */
 extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
 

dep/msvc/sdl2/include/SDL_filesystem.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -38,88 +38,97 @@ extern "C" {
 #endif
 
 /**
- * \brief Get the path where the application resides.
+ * Get the directory where the application was run from.
  *
- * Get the "base path". This is the directory where the application was run
+ * This is not necessarily a fast call, so you should call this once near
- *  from, which is probably the installation directory, and may or may not
+ * startup and save the string if you need it.
- *  be the process's current working directory.
  *
- * This returns an absolute path in UTF-8 encoding, and is guaranteed to
+ * **Mac OS X and iOS Specific Functionality**: If the application is in a
- *  end with a path separator ('\\' on Windows, '/' most other places).
+ * ".app" bundle, this function returns the Resource directory (e.g.
+ * MyApp.app/Contents/Resources/). This behaviour can be overridden by adding
+ * a property to the Info.plist file. Adding a string key with the name
+ * SDL_FILESYSTEM_BASE_DIR_TYPE with a supported value will change the
+ * behaviour.
  *
- * The pointer returned by this function is owned by you. Please call
+ * Supported values for the SDL_FILESYSTEM_BASE_DIR_TYPE property (Given an
- *  SDL_free() on the pointer when you are done with it, or it will be a
+ * application in /Applications/SDLApp/MyApp.app):
- *  memory leak. This is not necessarily a fast call, though, so you should
- *  call this once near startup and save the string if you need it.
  *
- * Some platforms can't determine the application's path, and on other
+ * - `resource`: bundle resource directory (the default). For example:
- *  platforms, this might be meaningless. In such cases, this function will
+ *   `/Applications/SDLApp/MyApp.app/Contents/Resources`
- *  return NULL.
+ * - `bundle`: the Bundle directory. Fpr example:
+ *   `/Applications/SDLApp/MyApp.app/`
+ * - `parent`: the containing directory of the bundle. For example:
+ *   `/Applications/SDLApp/`
  *
- *  \return String of base dir in UTF-8 encoding, or NULL on error.
+ * 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.
+ *
+ * \returns an absolute path in UTF-8 encoding to the application data
+ *          directory. NULL will be returned on error or when the platform
+ *          doesn't implement this functionality, call SDL_GetError() for more
+ *          information.
+ *
+ * \since This function is available since SDL 2.0.1.
  *
  * \sa SDL_GetPrefPath
  */
 extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
 
 /**
- * \brief Get the user-and-app-specific path where files can be written.
+ * Get the user-and-app-specific path where files can be written.
  *
  * Get the "pref dir". This is meant to be where users can write personal
- *  files (preferences and save games, etc) that are specific to your
+ * files (preferences and save games, etc) that are specific to your
- *  application. This directory is unique per user, per application.
+ * application. This directory is unique per user, per application.
  *
- * This function will decide the appropriate location in the native filesystem,
+ * This function will decide the appropriate location in the native
- *  create the directory if necessary, and return a string of the absolute
+ * filesystem, create the directory if necessary, and return a string of the
- *  path to the directory in UTF-8 encoding.
+ * absolute path to the directory in UTF-8 encoding.
  *
  * On Windows, the string might look like:
- *  "C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\"
  *
- * On Linux, the string might look like:
+ * `C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\`
- *  "/home/bob/.local/share/My Program Name/"
+ *
+ * On Linux, the string might look like"
+ *
+ * `/home/bob/.local/share/My Program Name/`
  *
  * On Mac OS X, the string might look like:
- *  "/Users/bob/Library/Application Support/My Program Name/"
+ *
- *
+ * `/Users/bob/Library/Application Support/My Program Name/`
- * (etc.)
+ *
- *
+ * You should assume the path returned by this function is the only safe place
- * You specify the name of your organization (if it's not a real organization,
+ * to write files (and that SDL_GetBasePath(), while it might be writable, or
- *  your name or an Internet domain you own might do) and the name of your
+ * even the parent of the returned path, isn't where you should be writing
- *  application. These should be untranslated proper names.
+ * things).
- *
+ *
- * Both the org and app strings may become part of a directory name, so
+ * Both the org and app strings may become part of a directory name, so please
- *  please follow these rules:
+ * follow these rules:
- *
+ *
- *    - Try to use the same org string (including case-sensitivity) for
+ * - Try to use the same org string (_including case-sensitivity_) for all
- *      all your applications that use this function.
+ *   your applications that use this function.
- *    - Always use a unique app string for each one, and make sure it never
+ * - Always use a unique app string for each one, and make sure it never
- *      changes for an app once you've decided on it.
+ *   changes for an app once you've decided on it.
- *    - Unicode characters are legal, as long as it's UTF-8 encoded, but...
+ * - Unicode characters are legal, as long as it's UTF-8 encoded, but...
- *    - ...only use letters, numbers, and spaces. Avoid punctuation like
+ * - ...only use letters, numbers, and spaces. Avoid punctuation like "Game
- *      "Game Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
+ *   Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
- *
+ *
- * This returns an absolute path in UTF-8 encoding, and is guaranteed to
+ * The returned path is guaranteed to end with a path separator ('\' on
- *  end with a path separator ('\\' on Windows, '/' most other places).
+ * Windows, '/' on most other platforms).
- *
+ *
- * The pointer returned by this function is owned by you. Please call
+ * The pointer returned is owned by the caller. Please call SDL_free() on the
- *  SDL_free() on the pointer when you are done with it, or it will be a
+ * pointer when done with it.
- *  memory leak. This is not necessarily a fast call, though, so you should
+ *
- *  call this once near startup and save the string if you need it.
+ * \param org the name of your organization
- *
+ * \param app the name of your application
- * You should assume the path returned by this function is the only safe
+ * \returns a UTF-8 string of the user directory in platform-dependent
- *  place to write files (and that SDL_GetBasePath(), while it might be
+ *          notation. NULL if there's a problem (creating directory failed,
- *  writable, or even the parent of the returned path, aren't where you
+ *          etc.).
- *  should be writing things).
+ *
- *
+ * \since This function is available since SDL 2.0.1.
- * Some platforms can't determine the pref path, and on other
- *  platforms, this might be meaningless. In such cases, this function will
- *  return NULL.
- *
- *   \param org The name of your organization.
- *   \param app The name of your application.
- *  \return UTF-8 string of user dir in platform-dependent notation. NULL
- *          if there's a problem (creating directory failed, etc).
  *
  * \sa SDL_GetBasePath
  */

dep/msvc/sdl2/include/SDL_gamecontroller.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -31,6 +31,7 @@
 #include "SDL_stdinc.h"
 #include "SDL_error.h"
 #include "SDL_rwops.h"
+#include "SDL_sensor.h"
 #include "SDL_joystick.h"
 
 #include "begin_code.h"
@@ -57,6 +58,19 @@ extern "C" {
 struct _SDL_GameController;
 typedef struct _SDL_GameController SDL_GameController;
 
+typedef enum
+{
+    SDL_CONTROLLER_TYPE_UNKNOWN = 0,
+    SDL_CONTROLLER_TYPE_XBOX360,
+    SDL_CONTROLLER_TYPE_XBOXONE,
+    SDL_CONTROLLER_TYPE_PS3,
+    SDL_CONTROLLER_TYPE_PS4,
+    SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_PRO,
+    SDL_CONTROLLER_TYPE_VIRTUAL,
+    SDL_CONTROLLER_TYPE_PS5,
+    SDL_CONTROLLER_TYPE_AMAZON_LUNA,
+    SDL_CONTROLLER_TYPE_GOOGLE_STADIA
+} SDL_GameControllerType;
 
 typedef enum
 {
@@ -87,6 +101,8 @@ typedef struct SDL_GameControllerButtonBind
 
 /**
  *  To count the number of game controllers in the system for the following:
+ *
+ *  ```c
  *  int nJoysticks = SDL_NumJoysticks();
  *  int nGameControllers = 0;
  *  for (int i = 0; i < nJoysticks; i++) {
@@ -94,6 +110,7 @@ typedef struct SDL_GameControllerButtonBind
  *          nGameControllers++;
  *      }
  *  }
+ *  ```
  *
  *  Using the SDL_HINT_GAMECONTROLLERCONFIG hint or the SDL_GameControllerAddMapping() you can add support for controllers SDL is unaware of or cause an existing controller to have a different binding. The format is:
  *  guid,name,mappings
@@ -107,17 +124,39 @@ typedef struct SDL_GameControllerButtonBind
  *  Buttons can be used as a controller axis and vice versa.
  *
  *  This string shows an example of a valid mapping for a controller
- *  "03000000341a00003608000000000000,PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7",
  *
+ * ```c
+ * "03000000341a00003608000000000000,PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7",
+ * ```
  */
 
 /**
- *  Load a set of mappings from a seekable SDL data stream (memory or file), filtered by the current SDL_GetPlatform()
+ * Load a set of Game Controller mappings from a seekable SDL data stream.
- *  A community sourced database of controllers is available at https://raw.github.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt
+ *
+ * You can call this function several times, if needed, to load different
+ * database files.
+ *
+ * If a new mapping is loaded for an already known controller GUID, the later
+ * version will overwrite the one currently loaded.
+ *
+ * Mappings not belonging to the current platform or with no platform field
+ * specified will be ignored (i.e. mappings for Linux will be ignored in
+ * Windows, etc).
  *
- *  If \c freerw is non-zero, the stream will be closed after being read.
+ * This function will load the text database entirely in memory before
- * 
+ * processing it, so take this into consideration if you are in a memory
- * \return number of mappings added, -1 on error
+ * constrained environment.
+ *
+ * \param rw the data stream for the mappings to be added
+ * \param freerw non-zero to close the stream after being read
+ * \returns the number of mappings added or -1 on error; call SDL_GetError()
+ *          for more information.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_GameControllerAddMapping
+ * \sa SDL_GameControllerAddMappingsFromFile
+ * \sa SDL_GameControllerMappingForGUID
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw);
 
@@ -129,133 +168,338 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
 #define SDL_GameControllerAddMappingsFromFile(file)   SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)
 
 /**
- *  Add or update an existing mapping configuration
+ * 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
+ * string for the device and mappings are controller mappings to joystick
+ * ones. Under Windows there is a reserved GUID of "xinput" that covers all
+ * XInput devices. The mapping format for joystick is: {| |bX |a joystick
+ * button, index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick
+ * |} Buttons can be used as a controller axes and vice versa.
+ *
+ * This string shows an example of a valid mapping for a controller:
  *
- * \return 1 if mapping is added, 0 if updated, -1 on error
+ * ```c
+ * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
+ * ```
+ *
+ * \param mappingString the mapping string
+ * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
+ *          -1 on error; call SDL_GetError() for more information.
+ *
+ * \sa SDL_GameControllerMapping
+ * \sa SDL_GameControllerMappingForGUID
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString);
 
 /**
- *  Get the number of mappings installed
+ * Get the number of mappings installed.
  *
- *  \return the number of mappings
+ * \returns the number of mappings.
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void);
 
 /**
- *  Get the mapping at a particular index.
+ * Get the mapping at a particular index.
  *
- *  \return 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);
 
 /**
- *  Get a mapping string for a GUID
+ * Get the game controller mapping string for a given GUID.
+ *
+ * The returned string must be freed with SDL_free().
  *
- *  \return the mapping string.  Must be freed with SDL_free().  Returns NULL if no mapping is available
+ * \param guid a structure containing the GUID for which a mapping is desired
+ * \returns a mapping string or NULL on error; call SDL_GetError() for more
+ *          information.
+ *
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUID
  */
 extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID guid);
 
 /**
- *  Get a mapping string for an open GameController
+ * Get the current mapping of a Game Controller.
+ *
+ * The returned string must be freed with SDL_free().
  *
- *  \return the mapping string.  Must be freed with SDL_free().  Returns NULL if no mapping is available
+ * Details about mappings are discussed with SDL_GameControllerAddMapping().
+ *
+ * \param gamecontroller the game controller you want to get the current
+ *                       mapping for
+ * \returns a string that has the controller's mapping or NULL if no mapping
+ *          is available; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerAddMapping
+ * \sa SDL_GameControllerMappingForGUID
  */
-extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController * gamecontroller);
+extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gamecontroller);
 
 /**
- *  Is the joystick on this index supported by the game controller interface?
+ * Check if the given joystick is supported by the game controller interface.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * \param joystick_index the device_index of a device, up to
+ *                       SDL_NumJoysticks()
+ * \returns SDL_TRUE if the given joystick is supported by the game controller
+ *          interface, SDL_FALSE if it isn't or it's an invalid index.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_GameControllerOpen
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
 
 /**
- *  Get the implementation dependent name of a game controller.
+ * Get the implementation dependent name for the game controller.
- *  This can be called before any controllers are opened.
+ *
- *  If no name can be found, this function returns NULL.
+ * This function can be called before any controllers are opened.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ *                       SDL_NumJoysticks()-1
+ * \returns the implementation-dependent name for the game controller, or NULL
+ *          if there is no name or the index is invalid.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerName
+ * \sa SDL_GameControllerOpen
+ * \sa SDL_IsGameController
  */
 extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_index);
 
 /**
- *  Get the mapping of a game controller.
+ * Get the type of a game controller.
- *  This can be called before any controllers are opened.
+ *
+ * This can be called before any controllers are opened.
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ *                       SDL_NumJoysticks()-1
+ * \returns the controller type.
+ */
+extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(int joystick_index);
+
+/**
+ * Get the mapping of a game controller.
+ *
+ * This can be called before any controllers are opened.
  *
- *  \return the mapping string.  Must be freed with SDL_free().  Returns NULL if no mapping is available
+ * \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.
  */
 extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index);
 
 /**
- *  Open a game controller for use.
+ * Open a game controller for use.
- *  The index passed as an argument refers to the N'th game controller on the system.
+ *
- *  This index is not the value which will identify this controller in future
+ * `joystick_index` is the same as the `device_index` passed to
- *  controller events.  The joystick's instance id (::SDL_JoystickID) will be
+ * SDL_JoystickOpen().
- *  used there instead.
+ *
+ * The index passed as an argument refers to the N'th game controller on the
+ * system. This index is not the value which will identify this controller in
+ * future controller events. The joystick's instance id (SDL_JoystickID) will
+ * be used there instead.
  *
- *  \return A controller identifier, or NULL if an error occurred.
+ * \param joystick_index the device_index of a device, up to
+ *                       SDL_NumJoysticks()
+ * \returns a gamecontroller identifier or NULL if an error occurred; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerClose
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_IsGameController
  */
 extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_index);
 
 /**
- * Return the SDL_GameController associated with an instance id.
+ * Get the SDL_GameController associated with an instance id.
+ *
+ * \param joyid the instance id to get the SDL_GameController for
+ * \returns an SDL_GameController on success or NULL on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
  */
 extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromInstanceID(SDL_JoystickID joyid);
 
 /**
- *  Return the name for this currently opened controller
+ * 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!
+ *
+ * \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
+ * \sa SDL_GameControllerSetPlayerIndex
+ */
+extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(int player_index);
+
+/**
+ * Get the implementation-dependent name for an opened game controller.
+ *
+ * This is the same name as returned by SDL_GameControllerNameForIndex(), but
+ * it takes a controller identifier instead of the (unstable) device index.
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ *                       SDL_GameControllerOpen()
+ * \returns the implementation dependent name for the game controller, or NULL
+ *          if there is no name or the identifier passed is invalid.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_GameControllerOpen
  */
 extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *gamecontroller);
 
 /**
- *  Get the player index of an opened game controller, or -1 if it's not available
+ * Get the type of this currently opened controller
  *
- *  For XInput controllers this returns the XInput user index.
+ * This is the same name as returned by SDL_GameControllerTypeForIndex(), but
+ * it takes a controller identifier instead of the (unstable) device index.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \returns the controller type.
+ */
+extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller);
+
+/**
+ * Get the player index of an opened game controller.
+ *
+ * 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.
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller);
 
 /**
- *  Get the USB vendor ID of an opened controller, if available.
+ * Set the player index of an opened game controller.
- *  If the vendor ID isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to adjust.
+ * \param player_index Player index to assign to this controller.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController * gamecontroller);
+extern DECLSPEC void SDLCALL SDL_GameControllerSetPlayerIndex(SDL_GameController *gamecontroller, int player_index);
 
 /**
- *  Get the USB product ID of an opened controller, if available.
+ * Get the USB vendor ID of an opened controller, if available.
- *  If the product ID isn't available this function returns 0.
+ *
+ * If the vendor ID isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the USB vendor ID, or zero if unavailable.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController * gamecontroller);
+extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *gamecontroller);
 
 /**
- *  Get the product version of an opened controller, if available.
+ * Get the USB product ID of an opened controller, if available.
- *  If the product version isn't available this function returns 0.
+ *
+ * If the product ID isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the USB product ID, or zero if unavailable.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController * gamecontroller);
+extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *gamecontroller);
 
 /**
- *  Returns SDL_TRUE if the controller has been opened and currently connected,
+ * Get the product version of an opened controller, if available.
- *  or SDL_FALSE if it has not.
+ *
+ * If the product version isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the USB product version, or zero if unavailable.
+ */
+extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController *gamecontroller);
+
+/**
+ * Get the serial number of an opened controller, if 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.
+ */
+extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller);
+
+/**
+ * Check if a controller has been opened and is currently connected.
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ *                       SDL_GameControllerOpen()
+ * \returns SDL_TRUE if the controller has been opened and is currently
+ *          connected, or SDL_FALSE if not.
+ *
+ * \sa SDL_GameControllerClose
+ * \sa SDL_GameControllerOpen
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameController *gamecontroller);
 
 /**
- *  Get the underlying joystick object used by a controller
+ * Get the Joystick ID from a Game Controller.
+ *
+ * This function will give you a SDL_Joystick object, which allows you to use
+ * the SDL_Joystick functions with a SDL_GameController object. This would be
+ * useful for getting a joystick's position at any given time, even if it
+ * hasn't moved (moving it would produce an event, which would have the axis'
+ * value).
+ *
+ * The pointer returned is owned by the SDL_GameController. You should not
+ * call SDL_JoystickClose() on it, for example, since doing so will likely
+ * cause SDL to crash.
+ *
+ * \param gamecontroller the game controller object that you want to get a
+ *                       joystick from
+ * \returns a SDL_Joystick object; call SDL_GetError() for more information.
  */
 extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameController *gamecontroller);
 
 /**
- *  Enable/disable controller event polling.
+ * Query or change current state of Game Controller events.
+ *
+ * If controller events are disabled, you must call SDL_GameControllerUpdate()
+ * yourself and check the state of the controller when you want controller
+ * information.
  *
- *  If controller events are disabled, you must call SDL_GameControllerUpdate()
+ * Any number can be passed to SDL_GameControllerEventState(), but only -1, 0,
- *  yourself and check the state of the controller when you want controller
+ * and 1 will have any effect. Other numbers will just be returned.
- *  information.
  *
- *  The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
+ * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
+ * \returns the same value passed to the function, with exception to -1
+ *          (SDL_QUERY), which will return the current state.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickEventState
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerEventState(int state);
 
 /**
- *  Update the current state of the open game controllers.
+ * Manually pump game controller updates if not using the loop.
  *
- *  This is called automatically by the event loop if any game controller
+ * This function is called automatically by the event loop if events are
- *  events are enabled.
+ * enabled. Under such circumstances, it will not be necessary to call this
+ * function.
  */
 extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void);
 
@@ -282,33 +526,88 @@ typedef enum
 } SDL_GameControllerAxis;
 
 /**
- *  turn this string into a axis mapping
+ * Convert a string into SDL_GameControllerAxis enum.
+ *
+ * This function is called internally to translate SDL_GameController mapping
+ * strings for the underlying joystick device into the consistent
+ * SDL_GameController mapping. You do not normally need to call this function
+ * unless you are parsing SDL_GameController mappings in your own code.
+ *
+ * Note specially that "righttrigger" and "lefttrigger" map to
+ * `SDL_CONTROLLER_AXIS_TRIGGERRIGHT` and `SDL_CONTROLLER_AXIS_TRIGGERLEFT`,
+ * respectively.
+ *
+ * \param str string representing a SDL_GameController axis
+ * \returns the SDL_GameControllerAxis enum corresponding to the input string,
+ *          or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
+ *
+ * \sa SDL_GameControllerGetStringForAxis
  */
-extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *pchString);
+extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *str);
 
 /**
- *  turn this axis enum into a string mapping
+ * Convert from an SDL_GameControllerAxis enum to a string.
+ *
+ * The caller should not SDL_free() the returned string.
+ *
+ * \param axis an enum value for a given SDL_GameControllerAxis
+ * \returns a string for the given axis, or NULL if an invalid axis is
+ *          specified. The string returned is of the format used by
+ *          SDL_GameController mapping strings.
+ *
+ * \sa SDL_GameControllerGetAxisFromString
  */
 extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameControllerAxis axis);
 
 /**
- *  Get the SDL joystick layer binding for this controller button mapping
+ * Get the SDL joystick layer binding for a controller axis mapping.
+ *
+ * \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`.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetBindForButton
  */
 extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
 SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller,
                                  SDL_GameControllerAxis axis);
 
 /**
- *  Get the current state of an axis control on a game controller.
+ * Query whether a game controller has a given axis.
  *
- *  The state is a value ranging from -32768 to 32767 (except for the triggers,
+ * This merely reports whether the controller's mapping defined this axis, as
- *  which range from 0 to 32767).
+ * that is all the information SDL has about the physical device.
  *
- *  The axis indices start at index 0.
+ * \param gamecontroller a game controller
+ * \param axis an axis enum value (an SDL_GameControllerAxis value)
+ * \returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise.
+ */
+extern DECLSPEC SDL_bool SDLCALL
+SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
+
+/**
+ * Get the current state of an axis control on a game controller.
+ *
+ * The axis indices start at index 0.
+ *
+ * The state is a value ranging from -32768 to 32767. Triggers, however, range
+ * from 0 to 32767 (they never return a negative value).
+ *
+ * \param gamecontroller a game controller
+ * \param axis an axis index (one of the SDL_GameControllerAxis values)
+ * \returns axis state (including 0) on success or 0 (also) on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetButton
  */
 extern DECLSPEC Sint16 SDLCALL
-SDL_GameControllerGetAxis(SDL_GameController *gamecontroller,
+SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
-                          SDL_GameControllerAxis axis);
 
 /**
  *  The list of buttons available from a controller
@@ -331,53 +630,234 @@ typedef enum
     SDL_CONTROLLER_BUTTON_DPAD_DOWN,
     SDL_CONTROLLER_BUTTON_DPAD_LEFT,
     SDL_CONTROLLER_BUTTON_DPAD_RIGHT,
+    SDL_CONTROLLER_BUTTON_MISC1,    /* Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button */
+    SDL_CONTROLLER_BUTTON_PADDLE1,  /* Xbox Elite paddle P1 */
+    SDL_CONTROLLER_BUTTON_PADDLE2,  /* Xbox Elite paddle P3 */
+    SDL_CONTROLLER_BUTTON_PADDLE3,  /* Xbox Elite paddle P2 */
+    SDL_CONTROLLER_BUTTON_PADDLE4,  /* Xbox Elite paddle P4 */
+    SDL_CONTROLLER_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */
     SDL_CONTROLLER_BUTTON_MAX
 } SDL_GameControllerButton;
 
 /**
- *  turn this string into a button mapping
+ * Convert a string into an SDL_GameControllerButton enum.
+ *
+ * This function is called internally to translate SDL_GameController mapping
+ * strings for the underlying joystick device into the consistent
+ * SDL_GameController mapping. You do not normally need to call this function
+ * unless you are parsing SDL_GameController mappings in your own code.
+ *
+ * \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 *pchString);
+extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *str);
 
 /**
- *  turn this button enum into a string mapping
+ * Convert from an SDL_GameControllerButton enum to a string.
+ *
+ * The caller should not SDL_free() the returned string.
+ *
+ * \param button an enum value for a given SDL_GameControllerButton
+ * \returns a string for the given button, or NULL if an invalid axis is
+ *          specified. The string returned is of the format used by
+ *          SDL_GameController mapping strings.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetButtonFromString
  */
 extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_GameControllerButton button);
 
 /**
- *  Get the SDL joystick layer binding for this controller button mapping
+ * Get the SDL joystick layer binding for a controller button mapping.
+ *
+ * \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`.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetBindForAxis
  */
 extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
 SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller,
                                    SDL_GameControllerButton button);
 
+/**
+ * Query whether a game controller has a given button.
+ *
+ * This merely reports whether the controller's mapping defined this button,
+ * as that is all the information SDL has about the physical device.
+ *
+ * \param gamecontroller a game controller
+ * \param button a button enum value (an SDL_GameControllerButton value)
+ * \returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController *gamecontroller,
+                                                             SDL_GameControllerButton button);
 
 /**
- *  Get the current state of a button on a game controller.
+ * Get the current state of a button on a game controller.
+ *
+ * \param gamecontroller a game controller
+ * \param button a button index (one of the SDL_GameControllerButton values)
+ * \returns 1 for pressed state or 0 for not pressed state or error; call
+ *          SDL_GetError() for more information.
  *
- *  The button indices start at index 0.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetAxis
  */
 extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *gamecontroller,
                                                           SDL_GameControllerButton button);
 
 /**
- *  Trigger a rumble effect
+ * Get the number of touchpads on a game controller.
- *  Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller);
+
+/**
+ * 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);
+
+/**
+ * Get the current state of a finger on a touchpad on a game controller.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameController *gamecontroller, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure);
+
+/**
+ * Return whether a game controller has a particular sensor.
  *
- *  \param gamecontroller The controller to vibrate
+ * \param gamecontroller The controller to query
- *  \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
+ * \param type The type of sensor to query
- *  \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
+ * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
- *  \param duration_ms The duration of the rumble effect, in milliseconds
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController *gamecontroller, SDL_SensorType type);
+
+/**
+ * Set whether data reporting for a game controller sensor is enabled.
+ *
+ * \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);
+
+/**
+ * Query whether sensor data reporting is enabled for a game controller.
+ *
+ * \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);
+
+/**
+ * Get the data rate (number of events per second) of a game controller
+ * sensor.
+ *
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \return the data rate, or 0.0f if the data rate is not available.
+ */
+extern DECLSPEC float SDLCALL SDL_GameControllerGetSensorDataRate(SDL_GameController *gamecontroller, SDL_SensorType type);
+
+/**
+ * Get the current state of a game controller sensor.
+ *
+ * The number of values and interpretation of the data is sensor dependent.
+ * See SDL_sensor.h for the details for each type of sensor.
+ *
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \param data A pointer filled with the current sensor state
+ * \param num_values The number of values to write to data
+ * \return 0 or -1 if an error occurred.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController *gamecontroller, SDL_SensorType type, float *data, int num_values);
+
+/**
+ * Start a rumble effect on a game controller.
  *
- *  \return 0, or -1 if rumble isn't supported on this joystick
+ * Each call to this function cancels any previous rumble effect, and calling
+ * it with 0 intensity stops any rumbling.
+ *
+ * \param gamecontroller The controller to vibrate
+ * \param low_frequency_rumble The intensity of the low frequency (left)
+ *                             rumble motor, from 0 to 0xFFFF
+ * \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 controller
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecontroller, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
 
 /**
- *  Close a controller previously opened with SDL_GameControllerOpen().
+ * Start a rumble effect in the game controller's triggers.
+ *
+ * Each call to this function cancels any previous trigger rumble effect, and
+ * calling it with 0 intensity stops any rumbling.
+ *
+ * Note that this is rumbling of the _triggers_ and not the game controller as
+ * a whole. The first controller to offer this feature was the PlayStation 5's
+ * DualShock 5.
+ *
+ * \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 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);
+
+/**
+ * Query whether a game controller has an LED.
+ *
+ * \param gamecontroller The controller to query
+ * \returns SDL_TRUE, or SDL_FALSE if this controller does not have a
+ *          modifiable LED
  */
-extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller);
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *gamecontroller);
+
+/**
+ * Update a game controller's LED color.
+ *
+ * \param gamecontroller The controller to update
+ * \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, or -1 if this controller does not have a modifiable LED
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecontroller, Uint8 red, Uint8 green, Uint8 blue);
+
+/**
+ * Send a controller specific effect packet
+ *
+ * \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
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gamecontroller, const void *data, int size);
 
+/**
+ * Close a game controller previously opened with SDL_GameControllerOpen().
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ *                       SDL_GameControllerOpen()
+ *
+ * \sa SDL_GameControllerOpen
+ */
+extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller);
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

dep/msvc/sdl2/include/SDL_gesture.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -46,36 +46,66 @@ typedef Sint64 SDL_GestureID;
 /* Function prototypes */
 
 /**
- *  \brief Begin Recording a gesture on the specified touch, or all touches (-1)
+ * Begin recording a gesture on a specified touch device or all touch devices.
  *
+ * If the parameter `touchId` is -1 (i.e., all devices), this function will
+ * always return 1, regardless of whether there actually are any devices.
  *
+ * \param touchId the touch device id, or -1 for all touch devices
+ * \returns 1 on success or 0 if the specified device could not be found.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetTouchDevice
  */
 extern DECLSPEC int SDLCALL SDL_RecordGesture(SDL_TouchID touchId);
 
 
 /**
- *  \brief Save all currently loaded Dollar Gesture templates
+ * Save all currently loaded Dollar Gesture templates.
+ *
+ * \param dst a SDL_RWops to save to
+ * \returns the number of saved templates on success or 0 on failure; call
+ *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
  *
+ * \sa SDL_LoadDollarTemplates
+ * \sa SDL_SaveDollarTemplate
  */
 extern DECLSPEC int SDLCALL SDL_SaveAllDollarTemplates(SDL_RWops *dst);
 
 /**
- *  \brief Save a currently loaded Dollar Gesture template
+ * Save a currently loaded Dollar Gesture template.
  *
+ * \param gestureId a gesture id
+ * \param dst a SDL_RWops to save to
+ * \returns 1 on success or 0 on failure; call SDL_GetError() for more
+ *          information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadDollarTemplates
+ * \sa SDL_SaveAllDollarTemplates
  */
 extern DECLSPEC int SDLCALL SDL_SaveDollarTemplate(SDL_GestureID gestureId,SDL_RWops *dst);
 
 
 /**
- *  \brief Load Dollar Gesture templates from a file
+ * Load Dollar Gesture templates from a file.
+ *
+ * \param touchId a touch id
+ * \param src a SDL_RWops to load from
+ * \returns the number of loaded templates on success or a negative error code
+ *          (or 0) on failure; call SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
  *
+ * \sa SDL_SaveAllDollarTemplates
+ * \sa SDL_SaveDollarTemplate
  */
 extern DECLSPEC int SDLCALL SDL_LoadDollarTemplates(SDL_TouchID touchId, SDL_RWops *src);
 
-
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

dep/msvc/sdl2/include/SDL_haptic.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -336,6 +336,14 @@ typedef struct _SDL_Haptic SDL_Haptic;
  */
 #define SDL_HAPTIC_SPHERICAL  2
 
+/**
+ *  \brief Use this value to play an effect on the steering wheel axis. This 
+ *  provides better compatibility across platforms and devices as SDL will guess 
+ *  the correct axis.
+ *  \sa SDL_HapticDirection
+ */
+#define SDL_HAPTIC_STEERING_AXIS 3
+
 /* @} *//* Direction encodings */
 
 /* @} *//* Haptic features */
@@ -444,6 +452,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
  *  \sa SDL_HAPTIC_POLAR
  *  \sa SDL_HAPTIC_CARTESIAN
  *  \sa SDL_HAPTIC_SPHERICAL
+ *  \sa SDL_HAPTIC_STEERING_AXIS
  *  \sa SDL_HapticEffect
  *  \sa SDL_HapticNumAxes
  */
@@ -812,418 +821,491 @@ typedef union SDL_HapticEffect
 
 /* Function prototypes */
 /**
- *  \brief Count the number of haptic devices attached to the system.
+ * Count the number of haptic devices attached to the system.
  *
- *  \return Number of haptic devices detected on the system.
+ * \returns the number of haptic devices detected on the system or a negative
+ *          error code on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticName
  */
 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
 
 /**
- *  \brief Get the implementation dependent name of a haptic device.
+ * Get the implementation dependent name of a haptic device.
+ *
+ * This can be called before any joysticks are opened. If no name can be
+ * found, this function returns NULL.
  *
- *  This can be called before any joysticks are opened.
+ * \param device_index index of the device to query.
- *  If no name can be found, this function returns NULL.
+ * \returns the name of the device or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
- *  \param device_index Index of the device to get its name.
+ * \since This function is available since SDL 2.0.0.
- *  \return Name of the device or NULL on error.
  *
- *  \sa SDL_NumHaptics
+ * \sa SDL_NumHaptics
  */
 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
 
 /**
- *  \brief Opens a haptic device for use.
+ * Open a haptic device for use.
  *
- *  The index passed as an argument refers to the N'th haptic device on this
+ * The index passed as an argument refers to the N'th haptic device on this
- *  system.
+ * system.
  *
- *  When opening a haptic device, its gain will be set to maximum and
+ * When opening a haptic device, its gain will be set to maximum and
- *  autocenter will be disabled.  To modify these values use
+ * autocenter will be disabled. To modify these values use SDL_HapticSetGain()
- *  SDL_HapticSetGain() and SDL_HapticSetAutocenter().
+ * and SDL_HapticSetAutocenter().
  *
- *  \param device_index Index of the device to open.
+ * \param device_index index of the device to open
- *  \return Device identifier or NULL on error.
+ * \returns the device identifier or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
- *  \sa SDL_HapticIndex
+ * \since This function is available since SDL 2.0.0.
- *  \sa SDL_HapticOpenFromMouse
+ *
- *  \sa SDL_HapticOpenFromJoystick
+ * \sa SDL_HapticClose
- *  \sa SDL_HapticClose
+ * \sa SDL_HapticIndex
- *  \sa SDL_HapticSetGain
+ * \sa SDL_HapticOpenFromJoystick
- *  \sa SDL_HapticSetAutocenter
+ * \sa SDL_HapticOpenFromMouse
- *  \sa SDL_HapticPause
+ * \sa SDL_HapticPause
- *  \sa SDL_HapticStopAll
+ * \sa SDL_HapticSetAutocenter
+ * \sa SDL_HapticSetGain
+ * \sa SDL_HapticStopAll
  */
 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
 
 /**
- *  \brief Checks if the haptic device at index has been opened.
+ * Check if the haptic device at the designated index has been opened.
  *
- *  \param device_index Index to check to see if it has been opened.
+ * \param device_index the index of the device to query
- *  \return 1 if it has been opened or 0 if it hasn't.
+ * \returns 1 if it has been opened, 0 if it hasn't or on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticOpen
+ * \since This function is available since SDL 2.0.0.
- *  \sa SDL_HapticIndex
+ *
+ * \sa SDL_HapticIndex
+ * \sa SDL_HapticOpen
  */
 extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
 
 /**
- *  \brief Gets the index of a haptic device.
+ * Get the index of a haptic device.
  *
- *  \param haptic Haptic device to get the index of.
+ * \param haptic the SDL_Haptic device to query
- *  \return The index of the haptic device or -1 on error.
+ * \returns the index of the specified haptic device or a negative error code
+ *          on failure; call SDL_GetError() for more information.
  *
- *  \sa SDL_HapticOpen
+ * \since This function is available since SDL 2.0.0.
- *  \sa SDL_HapticOpened
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_HapticOpened
  */
 extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
 
 /**
- *  \brief Gets whether or not the current mouse has haptic capabilities.
+ * Query whether or not the current mouse has haptic capabilities.
+ *
+ * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't.
  *
- *  \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HapticOpenFromMouse
+ * \sa SDL_HapticOpenFromMouse
  */
 extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
 
 /**
- *  \brief Tries to open a haptic device from the current mouse.
+ * Try to open a haptic device from the current mouse.
  *
- *  \return The haptic device identifier or NULL on error.
+ * \returns the haptic device identifier or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_MouseIsHaptic
+ * \since This function is available since SDL 2.0.0.
- *  \sa SDL_HapticOpen
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_MouseIsHaptic
  */
 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
 
 /**
- *  \brief Checks to see if a joystick has haptic features.
+ * Query if a joystick has haptic features.
  *
- *  \param joystick Joystick to test for haptic capabilities.
+ * \param joystick the SDL_Joystick to test for haptic capabilities
- *  \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
+ * \returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't, or a
- *          or -1 if an error occurred.
+ *          negative error code on failure; call SDL_GetError() for more
+ *          information.
  *
- *  \sa SDL_HapticOpenFromJoystick
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpenFromJoystick
  */
 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
 
 /**
- *  \brief Opens a haptic device for use from a joystick device.
+ * Open a haptic device for use from a joystick device.
  *
- *  You must still close the haptic device separately.  It will not be closed
+ * You must still close the haptic device separately. It will not be closed
- *  with the joystick.
+ * with the joystick.
  *
- *  When opening from a joystick you should first close the haptic device before
+ * When opened from a joystick you should first close the haptic device before
- *  closing the joystick device.  If not, on some implementations the haptic
+ * closing the joystick device. If not, on some implementations the haptic
- *  device will also get unallocated and you'll be unable to use force feedback
+ * device will also get unallocated and you'll be unable to use force feedback
- *  on that device.
+ * on that device.
  *
- *  \param joystick Joystick to create a haptic device from.
+ * \param joystick the SDL_Joystick to create a haptic device from
- *  \return A valid haptic device identifier on success or NULL on error.
+ * \returns a valid haptic device identifier on success or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
- *  \sa SDL_HapticOpen
+ * \since This function is available since SDL 2.0.0.
- *  \sa SDL_HapticClose
+ *
+ * \sa SDL_HapticClose
+ * \sa SDL_HapticOpen
+ * \sa SDL_JoystickIsHaptic
  */
 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
                                                                joystick);
 
 /**
- *  \brief Closes a haptic device previously opened with SDL_HapticOpen().
+ * Close a haptic device previously opened with SDL_HapticOpen().
  *
- *  \param haptic Haptic device to close.
+ * \param haptic the SDL_Haptic device to close
+ *
+ * \sa SDL_HapticOpen
  */
 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
 
 /**
- *  \brief Returns the number of effects a haptic device can store.
+ * Get the number of effects a haptic device can store.
+ *
+ * On some platforms this isn't fully supported, and therefore is an
+ * approximation. Always check to see if your created effect was actually
+ * created and do not rely solely on SDL_HapticNumEffects().
  *
- *  On some platforms this isn't fully supported, and therefore is an
+ * \param haptic the SDL_Haptic device to query
- *  approximation.  Always check to see if your created effect was actually
+ * \returns the number of effects the haptic device can store or a negative
- *  created and do not rely solely on SDL_HapticNumEffects().
+ *          error code on failure; call SDL_GetError() for more information.
  *
- *  \param haptic The haptic device to query effect max.
+ * \since This function is available since SDL 2.0.0.
- *  \return The number of effects the haptic device can store or
- *          -1 on error.
  *
- *  \sa SDL_HapticNumEffectsPlaying
+ * \sa SDL_HapticNumEffectsPlaying
- *  \sa SDL_HapticQuery
+ * \sa SDL_HapticQuery
  */
 extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
 
 /**
- *  \brief Returns the number of effects a haptic device can play at the same
+ * Get the number of effects a haptic device can play at the same time.
- *         time.
+ *
+ * This is not supported on all platforms, but will always return a value.
  *
- *  This is not supported on all platforms, but will always return a value.
+ * \param haptic the SDL_Haptic device to query maximum playing effects
- *  Added here for the sake of completeness.
+ * \returns the number of effects the haptic device can play at the same time
+ *          or a negative error code on failure; call SDL_GetError() for more
+ *          information.
  *
- *  \param haptic The haptic device to query maximum playing effects.
+ * \since This function is available since SDL 2.0.0.
- *  \return The number of effects the haptic device can play at the same time
- *          or -1 on error.
  *
- *  \sa SDL_HapticNumEffects
+ * \sa SDL_HapticNumEffects
- *  \sa SDL_HapticQuery
+ * \sa SDL_HapticQuery
  */
 extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
 
 /**
- *  \brief Gets the haptic device's supported features in bitwise manner.
+ * Get the haptic device's supported features in bitwise manner.
  *
- *  Example:
+ * \param haptic the SDL_Haptic device to query
- *  \code
+ * \returns a list of supported haptic features in bitwise manner (OR'd), or 0
- *  if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {
+ *          on failure; call SDL_GetError() for more information.
- *      printf("We have constant haptic effect!\n");
- *  }
- *  \endcode
  *
- *  \param haptic The haptic device to query.
+ * \since This function is available since SDL 2.0.0.
- *  \return Haptic features in bitwise manner (OR'd).
  *
- *  \sa SDL_HapticNumEffects
+ * \sa SDL_HapticEffectSupported
- *  \sa SDL_HapticEffectSupported
+ * \sa SDL_HapticNumEffects
  */
 extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
 
 
 /**
- *  \brief Gets the number of haptic axes the device has.
+ * Get the number of haptic axes the device has.
  *
- *  \sa SDL_HapticDirection
+ * The number of haptic axes might be useful if working with the
+ * SDL_HapticDirection effect.
+ *
+ * \param haptic the SDL_Haptic device to query
+ * \returns the number of axes on success or a negative error code on failure;
+ *          call SDL_GetError() for more information.
  */
 extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
 
 /**
- *  \brief Checks to see if effect is supported by haptic.
+ * 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
+ * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
+ *          negative error code on failure; call SDL_GetError() for more
+ *          information.
  *
- *  \param haptic Haptic device to check on.
+ * \since This function is available since SDL 2.0.0.
- *  \param effect Effect to check to see if it is supported.
- *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
  *
- *  \sa SDL_HapticQuery
+ * \sa SDL_HapticNewEffect
- *  \sa SDL_HapticNewEffect
+ * \sa SDL_HapticQuery
  */
 extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
                                                       SDL_HapticEffect *
                                                       effect);
 
 /**
- *  \brief Creates a new haptic effect on the device.
+ * Create a new haptic effect on a specified device.
  *
- *  \param haptic Haptic device to create the effect on.
+ * \param haptic an SDL_Haptic device to create the effect on
- *  \param effect Properties of the effect to create.
+ * \param effect an SDL_HapticEffect structure containing the properties of
- *  \return The identifier of the effect on success or -1 on error.
+ *               the effect to create
+ * \returns the ID of the effect on success or a negative error code on
+ *          failure; call SDL_GetError() for more information.
  *
- *  \sa SDL_HapticUpdateEffect
+ * \sa SDL_HapticDestroyEffect
- *  \sa SDL_HapticRunEffect
+ * \sa SDL_HapticRunEffect
- *  \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticUpdateEffect
  */
 extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
                                                 SDL_HapticEffect * effect);
 
 /**
- *  \brief Updates the properties of an effect.
+ * Update the properties of an effect.
  *
- *  Can be used dynamically, although behavior when dynamically changing
+ * Can be used dynamically, although behavior when dynamically changing
- *  direction may be strange.  Specifically the effect may reupload itself
+ * direction may be strange. Specifically the effect may re-upload itself and
- *  and start playing from the start.  You cannot change the type either when
+ * start playing from the start. You also cannot change the type either when
- *  running SDL_HapticUpdateEffect().
+ * running SDL_HapticUpdateEffect().
  *
- *  \param haptic Haptic device that has the effect.
+ * \param haptic the SDL_Haptic device that has the effect
- *  \param effect Identifier of the effect to update.
+ * \param effect the identifier of the effect to update
- *  \param data New effect properties to use.
+ * \param data an SDL_HapticEffect structure containing the new effect
- *  \return 0 on success or -1 on error.
+ *             properties to use
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticNewEffect
+ * \since This function is available since SDL 2.0.0.
- *  \sa SDL_HapticRunEffect
+ *
- *  \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticNewEffect
+ * \sa SDL_HapticRunEffect
  */
 extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
                                                    int effect,
                                                    SDL_HapticEffect * data);
 
 /**
- *  \brief Runs the haptic effect on its associated haptic device.
+ * Run the haptic effect on its associated haptic device.
  *
- *  If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
+ * To repeat the effect over and over indefinitely, set `iterations` to
- *  repeating the envelope (attack and fade) every time.  If you only want the
+ * `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make
- *  effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
+ * one instance of the effect last indefinitely (so the effect does not fade),
- *  parameter.
+ * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY`
+ * instead.
  *
- *  \param haptic Haptic device to run the effect on.
+ * \param haptic the SDL_Haptic device to run the effect on
- *  \param effect Identifier of the haptic effect to run.
+ * \param effect the ID of the haptic effect to run
- *  \param iterations Number of iterations to run the effect. Use
+ * \param iterations the number of iterations to run the effect; use
- *         ::SDL_HAPTIC_INFINITY for infinity.
+ *                   `SDL_HAPTIC_INFINITY` to repeat forever
- *  \return 0 on success or -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticStopEffect
+ * \since This function is available since SDL 2.0.0.
- *  \sa SDL_HapticDestroyEffect
+ *
- *  \sa SDL_HapticGetEffectStatus
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticGetEffectStatus
+ * \sa SDL_HapticStopEffect
  */
 extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
                                                 int effect,
                                                 Uint32 iterations);
 
 /**
- *  \brief Stops the haptic effect on its associated haptic device.
+ * 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
+ *          SDL_GetError() for more information.
  *
- *  \param haptic Haptic device to stop the effect on.
+ * \since This function is available since SDL 2.0.0.
- *  \param effect Identifier of the effect to stop.
- *  \return 0 on success or -1 on error.
  *
- *  \sa SDL_HapticRunEffect
+ * \sa SDL_HapticDestroyEffect
- *  \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticRunEffect
  */
 extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
                                                  int effect);
 
 /**
- *  \brief Destroys a haptic effect on the device.
+ * Destroy a haptic effect on the device.
+ *
+ * This will stop the effect if it's running. Effects are automatically
+ * destroyed when the device is closed.
  *
- *  This will stop the effect if it's running.  Effects are automatically
+ * \param haptic the SDL_Haptic device to destroy the effect on
- *  destroyed when the device is closed.
+ * \param effect the ID of the haptic effect to destroy
  *
- *  \param haptic Device to destroy the effect on.
+ * \since This function is available since SDL 2.0.0.
- *  \param effect Identifier of the effect to destroy.
  *
- *  \sa SDL_HapticNewEffect
+ * \sa SDL_HapticNewEffect
  */
 extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
                                                      int effect);
 
 /**
- *  \brief Gets the status of the current effect on the haptic device.
+ * Get the status of the current effect on the specified haptic device.
+ *
+ * Device must support the SDL_HAPTIC_STATUS feature.
  *
- *  Device must support the ::SDL_HAPTIC_STATUS feature.
+ * \param haptic the SDL_Haptic device to query for the effect status on
+ * \param effect the ID of the haptic effect to query its status
+ * \returns 0 if it isn't playing, 1 if it is playing, or a negative error
+ *          code on failure; call SDL_GetError() for more information.
  *
- *  \param haptic Haptic device to query the effect status on.
+ * \since This function is available since SDL 2.0.0.
- *  \param effect Identifier of the effect to query its status.
- *  \return 0 if it isn't playing, 1 if it is playing or -1 on error.
  *
- *  \sa SDL_HapticRunEffect
+ * \sa SDL_HapticRunEffect
- *  \sa SDL_HapticStopEffect
+ * \sa SDL_HapticStopEffect
  */
 extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
                                                       int effect);
 
 /**
- *  \brief Sets the global gain of the device.
+ * Set the global gain of the specified haptic device.
+ *
+ * Device must support the SDL_HAPTIC_GAIN feature.
  *
- *  Device must support the ::SDL_HAPTIC_GAIN feature.
+ * The user may specify the maximum gain by setting the environment variable
+ * `SDL_HAPTIC_GAIN_MAX` which should be between 0 and 100. All calls to
+ * SDL_HapticSetGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the
+ * maximum.
  *
- *  The user may specify the maximum gain by setting the environment variable
+ * \param haptic the SDL_Haptic device to set the gain on
- *  SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
+ * \param gain value to set the gain to, should be between 0 and 100 (0 - 100)
- *  SDL_HapticSetGain() will scale linearly using SDL_HAPTIC_GAIN_MAX as the
+ * \returns 0 on success or a negative error code on failure; call
- *  maximum.
+ *          SDL_GetError() for more information.
  *
- *  \param haptic Haptic device to set the gain on.
+ * \since This function is available since SDL 2.0.0.
- *  \param gain Value to set the gain to, should be between 0 and 100.
- *  \return 0 on success or -1 on error.
  *
- *  \sa SDL_HapticQuery
+ * \sa SDL_HapticQuery
  */
 extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
 
 /**
- *  \brief Sets the global autocenter of the device.
+ * Set the global autocenter of the device.
  *
- *  Autocenter should be between 0 and 100.  Setting it to 0 will disable
+ * Autocenter should be between 0 and 100. Setting it to 0 will disable
- *  autocentering.
+ * autocentering.
  *
- *  Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
+ * Device must support the SDL_HAPTIC_AUTOCENTER feature.
  *
- *  \param haptic Haptic device to set autocentering on.
+ * \param haptic the SDL_Haptic device to set autocentering on
- *  \param autocenter Value to set autocenter to, 0 disables autocentering.
+ * \param autocenter value to set autocenter to (0-100)
- *  \return 0 on success or -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticQuery
+ * \sa SDL_HapticQuery
  */
 extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
                                                     int autocenter);
 
 /**
- *  \brief Pauses a haptic device.
+ * Pause a haptic device.
  *
- *  Device must support the ::SDL_HAPTIC_PAUSE feature.  Call
+ * Device must support the `SDL_HAPTIC_PAUSE` feature. Call
- *  SDL_HapticUnpause() to resume playback.
+ * SDL_HapticUnpause() to resume playback.
  *
- *  Do not modify the effects nor add new ones while the device is paused.
+ * Do not modify the effects nor add new ones while the device is paused. That
- *  That can cause all sorts of weird errors.
+ * can cause all sorts of weird errors.
  *
- *  \param haptic Haptic device to pause.
+ * \param haptic the SDL_Haptic device to pause
- *  \return 0 on success or -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticUnpause
+ * \sa SDL_HapticUnpause
  */
 extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
 
 /**
- *  \brief Unpauses a haptic device.
+ * Unpause a haptic device.
  *
- *  Call to unpause after SDL_HapticPause().
+ * Call to unpause after SDL_HapticPause().
  *
- *  \param haptic Haptic device to unpause.
+ * \param haptic the SDL_Haptic device to unpause
- *  \return 0 on success or -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticPause
+ * \sa SDL_HapticPause
  */
 extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
 
 /**
- *  \brief Stops all the currently playing effects on a haptic device.
+ * Stop all the currently playing effects on a haptic device.
  *
- *  \param haptic Haptic device to stop.
+ * \param haptic the SDL_Haptic device to stop
- *  \return 0 on success or -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  */
 extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
 
 /**
- *  \brief Checks to see if rumble is supported on a haptic device.
+ * Check whether rumble is supported on a haptic device.
  *
- *  \param haptic Haptic device to check to see if it supports rumble.
+ * \param haptic haptic device to check for rumble support
- *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
+ * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
+ *          negative error code on failure; call SDL_GetError() for more
+ *          information.
  *
- *  \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumbleInit
- *  \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumblePlay
- *  \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleStop
  */
 extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
 
 /**
- *  \brief Initializes the haptic device for simple rumble playback.
+ * Initialize a haptic device for simple rumble playback.
  *
- *  \param haptic Haptic device to initialize for simple rumble playback.
+ * \param haptic the haptic device to initialize for simple rumble playback
- *  \return 0 on success or -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticOpen
+ * \since This function is available since SDL 2.0.0.
- *  \sa SDL_HapticRumbleSupported
+ *
- *  \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticOpen
- *  \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleSupported
  */
 extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
 
 /**
- *  \brief Runs simple rumble on a haptic device
+ * Run a simple rumble effect on a haptic device.
  *
- *  \param haptic Haptic device to play rumble effect on.
+ * \param haptic the haptic device to play the rumble effect on
- *  \param strength Strength of the rumble to play as a 0-1 float value.
+ * \param strength strength of the rumble to play as a 0-1 float value
- *  \param length Length of the rumble to play in milliseconds.
+ * \param length length of the rumble to play in milliseconds
- *  \return 0 on success or -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticRumbleSupported
+ * \sa SDL_HapticRumbleInit
- *  \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumbleStop
- *  \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleSupported
  */
 extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
 
 /**
- *  \brief Stops the simple rumble on a haptic device.
+ * Stop the simple rumble on a haptic device.
  *
- *  \param haptic Haptic to stop the rumble on.
+ * \param haptic the haptic device to stop the rumble effect on
- *  \return 0 on success or -1 on error.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticRumbleSupported
+ * \sa SDL_HapticRumbleInit
- *  \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumblePlay
- *  \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleSupported
  */
 extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
 

dep/msvc/sdl2/include/SDL_joystick.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -30,10 +30,12 @@
  * The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
  *   then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
  *
+ * The term "player_index" is the number assigned to a player on a specific
+ *   controller. For XInput controllers this returns the XInput user index.
+ *   Many joysticks will not be able to supply this information.
+ *
  * The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of
  *   the device (a X360 wired controller for example). This identifier is platform dependent.
- *
- *
  */
 
 #ifndef SDL_joystick_h_
@@ -105,6 +107,12 @@ typedef enum
     SDL_JOYSTICK_POWER_MAX
 } SDL_JoystickPowerLevel;
 
+/* Set max recognized G-force from accelerometer
+   See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed
+ */
+#define SDL_IPHONE_MAX_GFORCE 5.0
+
+
 /* Function prototypes */
 
 /**
@@ -118,208 +126,524 @@ typedef enum
  * and game controller events will not be delivered.
  */
 extern DECLSPEC void SDLCALL SDL_LockJoysticks(void);
+
+
+/**
+ * Unlocking for multi-threaded access to the joystick API
+ *
+ * If you are using the joystick API or handling events from multiple threads
+ * you should use these locking functions to protect access to the joysticks.
+ *
+ * In particular, you are guaranteed that the joystick list won't change, so
+ * the API functions that take a joystick index will be valid, and joystick
+ * and game controller events will not be delivered.
+ */
 extern DECLSPEC void SDLCALL SDL_UnlockJoysticks(void);
 
 /**
- *  Count the number of joysticks attached to the system right now
+ * Count the number of joysticks attached to the system.
+ *
+ * \returns the number of attached joysticks on success or a negative error
+ *          code on failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickName
+ * \sa SDL_JoystickOpen
  */
 extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
 
 /**
- *  Get the implementation dependent name of a joystick.
+ * Get the implementation dependent name of a joystick.
- *  This can be called before any joysticks are opened.
+ *
- *  If no name can be found, this function returns NULL.
+ * This can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ *                     on the system)
+ * \returns the name of the selected joystick. If no name can be found, this
+ *          function returns NULL; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickName
+ * \sa SDL_JoystickOpen
  */
 extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
 
 /**
- *  Get the player index of a joystick, or -1 if it's not available
+ * Get the player index of a joystick, or -1 if it's not available This can be
- *  This can be called before any joysticks are opened.
+ * called before any joysticks are opened.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index);
 
 /**
- *  Return the GUID for the joystick at this index
+ * Get the implementation-dependent GUID for the joystick at a given device
- *  This can be called before any joysticks are opened.
+ * index.
+ *
+ * This function can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ *                     on the system
+ * \returns the GUID of the selected joystick. If called on an invalid index,
+ *          this function returns a zero GUID
+ *
+ * \sa SDL_JoystickGetGUID
+ * \sa SDL_JoystickGetGUIDString
  */
 extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_index);
 
 /**
- *  Get the USB vendor ID of a joystick, if available.
+ * 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
+ * \returns the USB vendor ID of the selected joystick. If called on an
+ *          invalid index, this function returns zero
  */
 extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index);
 
 /**
- *  Get the USB product ID of a joystick, if available.
+ * 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
+ * \returns the USB product ID of the selected joystick. If called on an
+ *          invalid index, this function returns zero
  */
 extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index);
 
 /**
- *  Get the product version of a joystick, if available.
+ * 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
+ * \returns the product version of the selected joystick. If called on an
+ *          invalid index, this function returns zero
  */
 extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProductVersion(int device_index);
 
 /**
- *  Get the type of a joystick, if available.
+ * Get the type of a joystick, if available.
- *  This can be called before any joysticks are opened.
+ *
+ * This can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ *                     on the system
+ * \returns the SDL_JoystickType of the selected joystick. If called on an
+ *          invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN`
  */
 extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_index);
 
 /**
- *  Get the instance ID of a joystick.
+ * 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
+ * \returns the instance id of the selected joystick. If called on an invalid
+ *          index, this function returns zero
  */
 extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickGetDeviceInstanceID(int device_index);
 
 /**
- *  Open a joystick for use.
+ * Open a joystick for use.
- *  The index passed as an argument refers to the N'th joystick on the system.
+ *
- *  This index is not the value which will identify this joystick in future
+ * The `device_index` argument refers to the N'th joystick presently
- *  joystick events.  The joystick's instance id (::SDL_JoystickID) will be used
+ * recognized by SDL on the system. It is **NOT** the same as the instance ID
- *  there instead.
+ * used to identify the joystick in future events. See
+ * SDL_JoystickInstanceID() for more details about instance IDs.
+ *
+ * The joystick subsystem must be initialized before a joystick can be opened
+ * for use.
+ *
+ * \param device_index the index of the joystick to query
+ * \returns a joystick identifier or NULL if an error occurred; call
+ *          SDL_GetError() for more information.
  *
- *  \return A joystick identifier, or NULL if an error occurred.
+ * \sa SDL_JoystickClose
+ * \sa SDL_JoystickInstanceID
  */
 extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index);
 
 /**
- * Return the SDL_Joystick associated with an instance id.
+ * Get the SDL_Joystick associated with an instance id.
+ *
+ * \param instance_id the instance id to get the SDL_Joystick for
+ * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
+ */
+extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID instance_id);
+
+/**
+ * Get the SDL_Joystick associated with a player index.
+ *
+ * \param player_index the player index to get the SDL_Joystick for
+ * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
+ *          for more information.
+ */
+extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromPlayerIndex(int player_index);
+
+/**
+ * Attach a new virtual joystick.
+ *
+ * \returns the joystick's device index, or -1 if an error occurred.
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type,
+                                                      int naxes,
+                                                      int nbuttons,
+                                                      int nhats);
+
+/**
+ * Detach a virtual joystick.
+ *
+ * \param device_index a value previously returned from
+ *                     SDL_JoystickAttachVirtual()
+ * \returns 0 on success, or -1 if an error occurred.
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickDetachVirtual(int device_index);
+
+/**
+ * Query whether or not the joystick at a given device index is virtual.
+ *
+ * \param device_index a joystick device index.
+ * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.
+ */
+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.
+ *
+ * \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.
+ * \returns 0 on success, -1 on error.
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value);
+
+/**
+ * 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.
+ *
+ * \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.
+ * \returns 0 on success, -1 on error.
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualButton(SDL_Joystick *joystick, int button, Uint8 value);
+
+/**
+ * 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.
+ *
+ * \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.
+ * \returns 0 on success, -1 on error.
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value);
+
+/**
+ * Get the implementation dependent name of a joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the name of the selected joystick. If no name can be found, this
+ *          function returns NULL; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickNameForIndex
+ * \sa SDL_JoystickOpen
+ */
+extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick *joystick);
+
+/**
+ * Get the player index of an opened joystick.
+ *
+ * For XInput controllers this returns the XInput user index. Many joysticks
+ * will not be able to supply this information.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the player index, or -1 if it's not available.
  */
-extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID joyid);
+extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick *joystick);
 
 /**
- *  Return the name for this currently opened joystick.
+ * Set the player index of an opened joystick.
- *  If no name can be found, this function returns NULL.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \param player_index the player index to set.
  */
-extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick * joystick);
+extern DECLSPEC void SDLCALL SDL_JoystickSetPlayerIndex(SDL_Joystick *joystick, int player_index);
 
 /**
- *  Get the player index of an opened joystick, or -1 if it's not available
+ * Get the implementation-dependent GUID for the joystick.
+ *
+ * This function requires an open joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the GUID of the given joystick. If called on an invalid index,
+ *          this function returns a zero GUID; call SDL_GetError() for more
+ *          information.
  *
- *  For XInput controllers this returns the XInput user index.
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUIDString
  */
-extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick * joystick);
+extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick *joystick);
 
 /**
- *  Return the GUID for this opened joystick
+ * Get the USB vendor ID of an opened joystick, if available.
+ *
+ * If the vendor ID isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the USB vendor ID of the selected joystick, or 0 if unavailable.
  */
-extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick * joystick);
+extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick *joystick);
 
 /**
- *  Get the USB vendor ID of an opened joystick, if available.
+ * Get the USB product ID of an opened joystick, if available.
- *  If the vendor ID isn't available this function returns 0.
+ *
+ * If the product ID isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the USB product ID of the selected joystick, or 0 if unavailable.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick * joystick);
+extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick);
 
 /**
- *  Get the USB product ID of an opened joystick, if available.
+ * Get the product version of an opened joystick, if available.
- *  If the product ID isn't available this function returns 0.
+ *
+ * If the product version isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the product version of the selected joystick, or 0 if unavailable.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick * joystick);
+extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joystick);
 
 /**
- *  Get the product version of an opened joystick, if available.
+ * Get the serial number of an opened joystick, if available.
- *  If the product version isn't available this function returns 0.
+ *
+ * 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.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick * joystick);
+extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystick);
 
 /**
- *  Get the type of an opened joystick.
+ * Get the type of an opened joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the SDL_JoystickType of the selected joystick.
  */
-extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick * joystick);
+extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick *joystick);
 
 /**
- *  Return a string representation for this guid. pszGUID must point to at least 33 bytes
+ * Get an ASCII string representation for a given SDL_JoystickGUID.
- *  (32 for the string plus a NULL terminator).
+ *
+ * You should supply at least 33 bytes for pszGUID.
+ *
+ * \param guid the SDL_JoystickGUID you wish to convert to string
+ * \param pszGUID buffer in which to write the ASCII string
+ * \param cbGUID the size of pszGUID
+ *
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUID
+ * \sa SDL_JoystickGetGUIDFromString
  */
 extern DECLSPEC void SDLCALL SDL_JoystickGetGUIDString(SDL_JoystickGUID guid, char *pszGUID, int cbGUID);
 
 /**
- *  Convert a string into a joystick guid
+ * Convert a GUID string into a SDL_JoystickGUID structure.
+ *
+ * Performs no error checking. If this function is given a string containing
+ * an invalid GUID, the function will silently succeed, but the GUID generated
+ * will not be useful.
+ *
+ * \param pchGUID string containing an ASCII representation of a GUID
+ * \returns a SDL_JoystickGUID structure.
+ *
+ * \sa SDL_JoystickGetGUIDString
  */
 extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUIDFromString(const char *pchGUID);
 
 /**
- *  Returns SDL_TRUE if the joystick has been opened and currently connected, or SDL_FALSE if it has not.
+ * Get the status of a specified joystick.
+ *
+ * \param joystick the joystick to query
+ * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not;
+ *          call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickClose
+ * \sa SDL_JoystickOpen
  */
-extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick * joystick);
+extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick *joystick);
 
 /**
- *  Get the instance ID of an opened joystick or -1 if the joystick is invalid.
+ * Get the instance ID of an opened joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the instance ID of the specified joystick on success or a negative
+ *          error code on failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickOpen
  */
-extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick * joystick);
+extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick *joystick);
 
 /**
- *  Get the number of general axis controls on a joystick.
+ * Get the number of general axis controls on a joystick.
+ *
+ * Often, the directional pad on a game controller will either look like 4
+ * separate buttons or a POV hat, and not axes, but all of this is up to the
+ * device and platform.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of axis controls/number of axes on success or a
+ *          negative error code on failure; call SDL_GetError() for more
+ *          information.
+ *
+ * \sa SDL_JoystickGetAxis
+ * \sa SDL_JoystickOpen
  */
-extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick * joystick);
+extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick);
 
 /**
- *  Get the number of trackballs on a joystick.
+ * Get the number of trackballs on a joystick.
+ *
+ * Joystick trackballs have only relative motion events associated with them
+ * and their state cannot be polled.
+ *
+ * Most joysticks do not have trackballs.
  *
- *  Joystick trackballs have only relative motion events associated
+ * \param joystick an SDL_Joystick structure containing joystick information
- *  with them and their state cannot be polled.
+ * \returns the number of trackballs on success or a negative error code on
+ *          failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickGetBall
  */
-extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick * joystick);
+extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick);
 
 /**
- *  Get the number of POV hats on a joystick.
+ * Get the number of POV hats on a joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of POV hats on success or a negative error code on
+ *          failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickGetHat
+ * \sa SDL_JoystickOpen
  */
-extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick * joystick);
+extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick);
 
 /**
- *  Get the number of buttons on a joystick.
+ * Get the number of buttons on a joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of buttons on success or a negative error code on
+ *          failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickGetButton
+ * \sa SDL_JoystickOpen
  */
-extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick * joystick);
+extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick);
 
 /**
- *  Update the current state of the open joysticks.
+ * Update the current state of the open joysticks.
+ *
+ * This is called automatically by the event loop if any joystick events are
+ * enabled.
  *
- *  This is called automatically by the event loop if any joystick
+ * \sa SDL_JoystickEventState
- *  events are enabled.
  */
 extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
 
 /**
- *  Enable/disable joystick event polling.
+ * Enable/disable joystick event polling.
+ *
+ * If joystick events are disabled, you must call SDL_JoystickUpdate()
+ * yourself and manually check the state of the joystick when you want
+ * joystick information.
+ *
+ * It is recommended that you leave joystick event handling enabled.
+ *
+ * **WARNING**: Calling this function may delete all events currently in SDL's
+ * event queue.
  *
- *  If joystick events are disabled, you must call SDL_JoystickUpdate()
+ * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
- *  yourself and check the state of the joystick when you want joystick
+ * \returns 1 if enabled, 0 if disabled, or a negative error code on failure;
- *  information.
+ *          call SDL_GetError() for more information.
  *
- *  The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
+ *          If `state` is `SDL_QUERY` then the current state is returned,
+ *          otherwise the new processing state is returned.
+ *
+ * \sa SDL_GameControllerEventState
  */
 extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
 
 #define SDL_JOYSTICK_AXIS_MAX   32767
 #define SDL_JOYSTICK_AXIS_MIN   -32768
 /**
- *  Get the current state of an axis control on a joystick.
+ * 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.
+ *
+ * The value returned by SDL_JoystickGetAxis() is a signed integer (-32768 to
+ * 32767) representing the current position of the axis. It may be necessary
+ * to impose certain tolerances on these values to account for jitter.
  *
- *  The state is a value ranging from -32768 to 32767.
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param axis the axis to query; the axis indices start at index 0
+ * \returns a 16-bit signed integer representing the current position of the
+ *          axis or 0 on failure; call SDL_GetError() for more information.
  *
- *  The axis indices start at index 0.
+ * \sa SDL_JoystickNumAxes
  */
-extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick * joystick,
+extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick,
                                                    int axis);
 
 /**
- *  Get the initial state of an axis control on a joystick.
+ * Get the initial state of an axis control on a joystick.
  *
- *  The state is a value ranging from -32768 to 32767.
+ * The state is a value ranging from -32768 to 32767.
  *
- *  The axis indices start at index 0.
+ * The axis indices start at index 0.
  *
- *  \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param axis the axis to query; the axis indices start at index 0
+ * \param state Upon return, the initial value is supplied here.
+ * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
  */
-extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick * joystick,
+extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *joystick,
                                                    int axis, Sint16 *state);
 
 /**
@@ -338,64 +662,153 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *
 /* @} */
 
 /**
- *  Get the current state of a POV hat on a joystick.
+ * Get the current state of a POV hat on a joystick.
+ *
+ * The returned value will be one of the following positions:
+ *
+ * - `SDL_HAT_CENTERED`
+ * - `SDL_HAT_UP`
+ * - `SDL_HAT_RIGHT`
+ * - `SDL_HAT_DOWN`
+ * - `SDL_HAT_LEFT`
+ * - `SDL_HAT_RIGHTUP`
+ * - `SDL_HAT_RIGHTDOWN`
+ * - `SDL_HAT_LEFTUP`
+ * - `SDL_HAT_LEFTDOWN`
  *
- *  The hat indices start at index 0.
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param hat the hat index to get the state from; indices start at index 0
+ * \returns the current hat position.
  *
- *  \return The return value is one of the following positions:
+ * \sa SDL_JoystickNumHats
- *           - ::SDL_HAT_CENTERED
- *           - ::SDL_HAT_UP
- *           - ::SDL_HAT_RIGHT
- *           - ::SDL_HAT_DOWN
- *           - ::SDL_HAT_LEFT
- *           - ::SDL_HAT_RIGHTUP
- *           - ::SDL_HAT_RIGHTDOWN
- *           - ::SDL_HAT_LEFTUP
- *           - ::SDL_HAT_LEFTDOWN
  */
-extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick * joystick,
+extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick,
                                                  int hat);
 
 /**
- *  Get the ball axis change since the last poll.
+ * Get the ball axis change since the last poll.
  *
- *  \return 0, or -1 if you passed it invalid parameters.
+ * Trackballs can only return relative motion since the last call to
+ * SDL_JoystickGetBall(), these motion deltas are placed into `dx` and `dy`.
  *
- *  The ball indices start at index 0.
+ * Most joysticks do not have trackballs.
+ *
+ * \param joystick the SDL_Joystick to query
+ * \param ball the ball index to query; ball indices start at index 0
+ * \param dx stores the difference in the x axis position since the last poll
+ * \param dy stores the difference in the y axis position since the last poll
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickNumBalls
  */
-extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick * joystick,
+extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick,
                                                 int ball, int *dx, int *dy);
 
 /**
- *  Get the current state of a button on a joystick.
+ * Get the current state of a button on a joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param button the button index to get the state from; indices start at
+ *               index 0
+ * \returns 1 if the specified button is pressed, 0 otherwise.
  *
- *  The button indices start at index 0.
+ * \sa SDL_JoystickNumButtons
  */
-extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick * joystick,
+extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick,
                                                     int button);
 
 /**
- *  Trigger a rumble effect
+ * Start a rumble effect.
- *  Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
  *
- *  \param joystick The joystick to vibrate
+ * Each call to this function cancels any previous rumble effect, and calling
- *  \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
+ * it with 0 intensity stops any rumbling.
- *  \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
  *
- *  \return 0, or -1 if rumble isn't supported on this joystick
+ * \param joystick The joystick to vibrate
+ * \param low_frequency_rumble The intensity of the low frequency (left)
+ *                             rumble motor, from 0 to 0xFFFF
+ * \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);
+extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
 
 /**
- *  Close a joystick previously opened with SDL_JoystickOpen().
+ * 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.
+ *
+ * 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.
+ *
+ * \param joystick The joystick 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 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 void SDLCALL SDL_JoystickClose(SDL_Joystick * joystick);
+extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
 
 /**
- *  Return the battery level of this joystick
+ * Query whether a joystick has an LED.
+ *
+ * An example of a joystick LED is the light on the back of a PlayStation 4's
+ * DualShock 4 controller.
+ *
+ * \param joystick The joystick to query
+ * \return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick);
+
+/**
+ * Update a joystick's LED color.
+ *
+ * An example of a joystick LED is the light on the back of a PlayStation 4's
+ * DualShock 4 controller.
+ *
+ * \param joystick The joystick to update
+ * \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);
+
+/**
+ * Send a joystick specific effect packet
+ *
+ * \param joystick The joystick to affect
+ * \param data The data to send to the joystick
+ * \param size The size of the data to send to the joystick
+ * \returns 0, or -1 if this joystick or driver doesn't support effect packets
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickSendEffect(SDL_Joystick *joystick, const void *data, int size);
+
+/**
+ * Close a joystick previously opened with SDL_JoystickOpen().
+ *
+ * \param joystick The joystick device to close
+ *
+ * \sa SDL_JoystickOpen
+ */
+extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick);
+
+/**
+ * Get the battery level of a joystick as SDL_JoystickPowerLevel.
+ *
+ * \param joystick the SDL_Joystick to query
+ * \returns the current battery level as SDL_JoystickPowerLevel on success or
+ *          `SDL_JOYSTICK_POWER_UNKNOWN` if it is unknown
+ *
+ * \since This function is available since SDL 2.0.4.
  */
-extern DECLSPEC SDL_JoystickPowerLevel SDLCALL SDL_JoystickCurrentPowerLevel(SDL_Joystick * joystick);
+extern DECLSPEC SDL_JoystickPowerLevel SDLCALL SDL_JoystickCurrentPowerLevel(SDL_Joystick *joystick);
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

dep/msvc/sdl2/include/SDL_keyboard.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -55,154 +55,231 @@ typedef struct SDL_Keysym
 /* Function prototypes */
 
 /**
- *  \brief Get the window which currently has keyboard focus.
+ * Query the window which currently has keyboard focus.
+ *
+ * \returns the window with keyboard focus.
  */
 extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
 
 /**
- *  \brief Get a snapshot of the current state of the keyboard.
+ * 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.
+ *
+ * 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
+ * SDL_Scancode values.
  *
- *  \param numkeys if non-NULL, receives the length of the returned array.
+ * Use SDL_PumpEvents() to update the state array.
  *
- *  \return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
+ * This function gives you the current state after all events have been
+ * processed, so if a key or button has been pressed and released before you
+ * process events, then the pressed state will never show up in the
+ * SDL_GetKeyboardState() calls.
  *
- *  \b Example:
+ * Note: This function doesn't take into account whether shift has been
- *  \code
+ * pressed or not.
- *  const Uint8 *state = SDL_GetKeyboardState(NULL);
+ *
- *  if ( state[SDL_SCANCODE_RETURN] )   {
+ * \param numkeys if non-NULL, receives the length of the returned array
- *      printf("<RETURN> is pressed.\n");
+ * \returns a pointer to an array of key states.
- *  }
+ *
- *  \endcode
+ * \sa SDL_PumpEvents
  */
 extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
 
 /**
- *  \brief Get the current key modifier state for the keyboard.
+ * Get the current key modifier state for the keyboard.
+ *
+ * \returns an OR'd combination of the modifier keys for the keyboard. See
+ *          SDL_Keymod for details.
+ *
+ * \sa SDL_GetKeyboardState
+ * \sa SDL_SetModState
  */
 extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
 
 /**
- *  \brief Set the current key modifier state for the keyboard.
+ * Set the current key modifier state for the keyboard.
+ *
+ * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose
+ * modifier key states on your application. Simply pass your desired modifier
+ * states into `modstate`. This value may be a bitwise, OR'd combination of
+ * SDL_Keymod values.
+ *
+ * This does not change the keyboard state, only the key modifier flags that
+ * SDL reports.
  *
- *  \note This does not change the keyboard state, only the key modifier flags.
+ * \param modstate the desired SDL_Keymod for the keyboard
+ *
+ * \sa SDL_GetModState
  */
 extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
 
 /**
- *  \brief Get the key code corresponding to the given scancode according
+ * Get the key code corresponding to the given scancode according to the
- *         to the current keyboard layout.
+ * current keyboard layout.
+ *
+ * See SDL_Keycode for details.
  *
- *  See ::SDL_Keycode for details.
+ * \param scancode the desired SDL_Scancode to query
+ * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
  *
- *  \sa SDL_GetKeyName()
+ * \sa SDL_GetKeyName
+ * \sa SDL_GetScancodeFromKey
  */
 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
 
 /**
- *  \brief Get the scancode corresponding to the given key code according to the
+ * Get the scancode corresponding to the given key code according to the
- *         current keyboard layout.
+ * current keyboard layout.
  *
- *  See ::SDL_Scancode for details.
+ * See SDL_Scancode for details.
  *
- *  \sa SDL_GetScancodeName()
+ * \param key the desired SDL_Keycode to query
+ * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
+ *
+ * \sa SDL_GetKeyFromScancode
+ * \sa SDL_GetScancodeName
  */
 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key);
 
 /**
- *  \brief Get a human-readable name for a scancode.
+ * Get a human-readable name for a scancode.
+ *
+ * See SDL_Scancode for details.
+ *
+ * **Warning**: The returned name is by design not stable across platforms,
+ * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
+ * Windows" under Microsoft Windows, and some scancodes like
+ * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even
+ * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and
+ * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore
+ * unsuitable for creating a stable cross-platform two-way mapping between
+ * strings and scancodes.
  *
- *  \return A pointer to the name for the scancode.
+ * \param scancode the desired SDL_Scancode to query
- *          If the scancode doesn't have a name, this function returns
+ * \returns a pointer to the name for the scancode. If the scancode doesn't
- *          an empty string ("").
+ *          have a name this function returns an empty string ("").
  *
- *  \sa SDL_Scancode
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetScancodeFromKey
+ * \sa SDL_GetScancodeFromName
  */
 extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
 
 /**
- *  \brief Get a scancode from a human-readable name
+ * Get a scancode from a human-readable name.
+ *
+ * \param name the human-readable scancode name
+ * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
+ *          recognized; call SDL_GetError() for more information.
  *
- *  \return scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_Scancode
+ * \sa SDL_GetKeyFromName
+ * \sa SDL_GetScancodeFromKey
+ * \sa SDL_GetScancodeName
  */
 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
 
 /**
- *  \brief Get a human-readable name for a key.
+ * Get a human-readable name for a key.
+ *
+ * See SDL_Scancode and SDL_Keycode for details.
  *
- *  \return A pointer to a UTF-8 string that stays valid at least until the next
+ * \param key the desired SDL_Keycode to query
- *          call to this function. If you need it around any longer, you must
+ * \returns a pointer to a UTF-8 string that stays valid at least until the
- *          copy it.  If the key doesn't have a name, this function returns an
+ *          next call to this function. If you need it around any longer, you
- *          empty string ("").
+ *          must copy it. If the key doesn't have a name, this function
+ *          returns an empty string ("").
  *
- *  \sa SDL_Keycode
+ * \sa SDL_GetKeyFromName
+ * \sa SDL_GetKeyFromScancode
+ * \sa SDL_GetScancodeFromKey
  */
 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
 
 /**
- *  \brief Get a key code from a human-readable name
+ * Get a key code from a human-readable name.
  *
- *  \return key code, or SDLK_UNKNOWN if the name wasn't recognized
+ * \param name the human-readable key name
+ * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_Keycode
+ * \sa SDL_GetKeyFromScancode
+ * \sa SDL_GetKeyName
+ * \sa SDL_GetScancodeFromName
  */
 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
 
 /**
- *  \brief Start accepting Unicode text input events.
+ * Start accepting Unicode text input events.
- *         This function will show the on-screen keyboard if supported.
  *
- *  \sa SDL_StopTextInput()
+ * This function will start accepting Unicode text input events in the focused
- *  \sa SDL_SetTextInputRect()
+ * SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and
- *  \sa SDL_HasScreenKeyboardSupport()
+ * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in
+ * pair with SDL_StopTextInput().
+ *
+ * On some platforms using this function activates the screen keyboard.
+ *
+ * \sa SDL_SetTextInputRect
+ * \sa SDL_StopTextInput
  */
 extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
 
 /**
- *  \brief Return whether or not Unicode text input events are enabled.
+ * Check whether or not Unicode text input events are enabled.
+ *
+ * \returns SDL_TRUE if text input events are enabled else SDL_FALSE.
  *
- *  \sa SDL_StartTextInput()
+ * \since This function is available since SDL 2.0.0.
- *  \sa SDL_StopTextInput()
+ *
+ * \sa SDL_StartTextInput
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
 
 /**
- *  \brief Stop receiving any text input events.
+ * Stop receiving any text input events.
- *         This function will hide the on-screen keyboard if supported.
  *
- *  \sa SDL_StartTextInput()
+ * \sa SDL_StartTextInput
- *  \sa SDL_HasScreenKeyboardSupport()
  */
 extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
 
 /**
- *  \brief Set the rectangle used to type Unicode text inputs.
+ * Set the rectangle used to type Unicode text inputs.
- *         This is used as a hint for IME and on-screen keyboard placement.
+ *
+ * \param rect the SDL_Rect structure representing the rectangle to receive
+ *             text (ignored if NULL)
  *
- *  \sa SDL_StartTextInput()
+ * \sa SDL_StartTextInput
  */
 extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
 
 /**
- *  \brief Returns whether the platform has some screen keyboard support.
+ * Check whether the platform has screen keyboard support.
  *
- *  \return SDL_TRUE if some keyboard support is available else SDL_FALSE.
+ * \returns SDL_TRUE if the platform has some screen keyboard support or
+ *          SDL_FALSE if not.
  *
- *  \note Not all screen keyboard functions are supported on all platforms.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_IsScreenKeyboardShown()
+ * \sa SDL_StartTextInput
+ * \sa SDL_IsScreenKeyboardShown
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
 
 /**
- *  \brief Returns whether the screen keyboard is shown for given window.
+ * Check whether the screen keyboard is shown for given window.
  *
- *  \param window The window for which screen keyboard should be queried.
+ * \param window the window for which screen keyboard should be queried
+ * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.
  *
- *  \return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HasScreenKeyboardSupport()
+ * \sa SDL_HasScreenKeyboardSupport
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
 

dep/msvc/sdl2/include/SDL_keycode.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -47,12 +47,12 @@ typedef Sint32 SDL_Keycode;
 #define SDLK_SCANCODE_MASK (1<<30)
 #define SDL_SCANCODE_TO_KEYCODE(X)  (X | SDLK_SCANCODE_MASK)
 
-enum
+typedef enum
 {
     SDLK_UNKNOWN = 0,
 
     SDLK_RETURN = '\r',
-    SDLK_ESCAPE = '\033',
+    SDLK_ESCAPE = '\x1B',
     SDLK_BACKSPACE = '\b',
     SDLK_TAB = '\t',
     SDLK_SPACE = ' ',
@@ -88,9 +88,11 @@ enum
     SDLK_GREATER = '>',
     SDLK_QUESTION = '?',
     SDLK_AT = '@',
+
     /*
        Skip uppercase letters
      */
+
     SDLK_LEFTBRACKET = '[',
     SDLK_BACKSLASH = '\\',
     SDLK_RIGHTBRACKET = ']',
@@ -145,7 +147,7 @@ enum
     SDLK_INSERT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT),
     SDLK_HOME = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME),
     SDLK_PAGEUP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP),
-    SDLK_DELETE = '\177',
+    SDLK_DELETE = '\x7F',
     SDLK_END = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END),
     SDLK_PAGEDOWN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN),
     SDLK_RIGHT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT),
@@ -317,7 +319,7 @@ enum
 
     SDLK_AUDIOREWIND = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AUDIOREWIND),
     SDLK_AUDIOFASTFORWARD = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AUDIOFASTFORWARD)
-};
+} SDL_KeyCode;
 
 /**
  * \brief Enumeration of valid key mods (possibly OR'd together).
@@ -336,13 +338,13 @@ typedef enum
     KMOD_NUM = 0x1000,
     KMOD_CAPS = 0x2000,
     KMOD_MODE = 0x4000,
-    KMOD_RESERVED = 0x8000
+    KMOD_RESERVED = 0x8000,
-} SDL_Keymod;
 
-#define KMOD_CTRL   (KMOD_LCTRL|KMOD_RCTRL)
+    KMOD_CTRL = KMOD_LCTRL | KMOD_RCTRL,
-#define KMOD_SHIFT  (KMOD_LSHIFT|KMOD_RSHIFT)
+    KMOD_SHIFT = KMOD_LSHIFT | KMOD_RSHIFT,
-#define KMOD_ALT    (KMOD_LALT|KMOD_RALT)
+    KMOD_ALT = KMOD_LALT | KMOD_RALT,
-#define KMOD_GUI    (KMOD_LGUI|KMOD_RGUI)
+    KMOD_GUI = KMOD_LGUI | KMOD_RGUI
+} SDL_Keymod;
 
 #endif /* SDL_keycode_h_ */
 

dep/msvc/sdl2/include/SDL_loadso.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -51,22 +51,50 @@ extern "C" {
 #endif
 
 /**
- *  This function dynamically loads a shared object and returns a pointer
+ * Dynamically load a shared object.
- *  to the object handle (or NULL if there was an error).
+ *
- *  The 'sofile' parameter is a system dependent name of the object file.
+ * \param sofile a system-dependent name of the object file
+ * \returns an opaque pointer to the object handle or NULL if there was an
+ *          error; call SDL_GetError() for more information.
+ *
+ * \sa SDL_LoadFunction
+ * \sa SDL_UnloadObject
  */
 extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile);
 
 /**
- *  Given an object handle, this function looks up the address of the
+ * Look up the address of the named function in a shared object.
- *  named function in the shared object and returns it.  This address
+ *
- *  is no longer valid after calling SDL_UnloadObject().
+ * This function pointer is no longer valid after calling SDL_UnloadObject().
+ *
+ * This function can only look up C function names. Other languages may have
+ * name mangling and intrinsic language support that varies from compiler to
+ * compiler.
+ *
+ * Make sure you declare your function pointers with the same calling
+ * convention as the actual library function. Your code will crash
+ * mysteriously if you do not do this.
+ *
+ * If the requested function doesn't exist, NULL is returned.
+ *
+ * \param handle a valid shared object handle returned by SDL_LoadObject()
+ * \param name the name of the function to look up
+ * \returns a pointer to the function or NULL if there was an error; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_LoadObject
+ * \sa SDL_UnloadObject
  */
 extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle,
                                                const char *name);
 
 /**
- *  Unload a shared object from memory.
+ * Unload a shared object from memory.
+ *
+ * \param handle a valid shared object handle returned by SDL_LoadObject()
+ *
+ * \sa SDL_LoadFunction
+ * \sa SDL_LoadObject
  */
 extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle);
 

dep/msvc/sdl2/include/SDL_locale.h

@@ -0,0 +1,101 @@
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+
+/**
+ *  \file SDL_locale.h
+ *
+ *  Include file for SDL locale services
+ */
+
+#ifndef _SDL_locale_h
+#define _SDL_locale_h
+
+#include "SDL_stdinc.h"
+#include "SDL_error.h"
+
+#include "begin_code.h"
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+/* *INDENT-OFF* */
+extern "C" {
+/* *INDENT-ON* */
+#endif
+
+
+typedef struct SDL_Locale
+{
+    const char *language;  /**< A language name, like "en" for English. */
+    const char *country;  /**< A country, like "US" for America. Can be NULL. */
+} SDL_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.
+ *
+ * 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.
+ *
+ * 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 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.
+ */
+extern DECLSPEC SDL_Locale * SDLCALL SDL_GetPreferredLocales(void);
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+/* *INDENT-OFF* */
+}
+/* *INDENT-ON* */
+#endif
+#include "close_code.h"
+
+#endif /* _SDL_locale_h */
+
+/* vi: set ts=4 sw=4 expandtab: */

dep/msvc/sdl2/include/SDL_log.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -61,7 +61,7 @@ extern "C" {
  *  at the VERBOSE level and all other categories are enabled at the
  *  CRITICAL level.
  */
-enum
+typedef enum
 {
     SDL_LOG_CATEGORY_APPLICATION,
     SDL_LOG_CATEGORY_ERROR,
@@ -94,7 +94,7 @@ enum
        };
      */
     SDL_LOG_CATEGORY_CUSTOM
-};
+} SDL_LogCategory;
 
 /**
  *  \brief The predefined log priorities
@@ -112,90 +112,255 @@ typedef enum
 
 
 /**
- *  \brief Set the priority of all log categories
+ * Set the priority of all log categories.
+ *
+ * \param priority the SDL_LogPriority to assign
+ *
+ * \sa SDL_LogSetPriority
  */
 extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority);
 
 /**
- *  \brief Set the priority of a particular log category
+ * Set the priority of a particular log category.
+ *
+ * \param category the category to assign a priority to
+ * \param priority the SDL_LogPriority to assign
+ *
+ * \sa SDL_LogGetPriority
+ * \sa SDL_LogSetAllPriority
  */
 extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category,
                                                 SDL_LogPriority priority);
 
 /**
- *  \brief Get the priority of a particular log category
+ * Get the priority of a particular log category.
+ *
+ * \param category the category to query
+ * \returns the SDL_LogPriority for the requested category
+ *
+ * \sa SDL_LogSetPriority
  */
 extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category);
 
 /**
- *  \brief Reset all priorities to default.
+ * Reset all priorities to default.
  *
- *  \note This is called in SDL_Quit().
+ * This is called by SDL_Quit().
+ *
+ * \sa SDL_LogSetAllPriority
+ * \sa SDL_LogSetPriority
  */
 extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
 
 /**
- *  \brief Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO
+ * 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
+ *
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
 
 /**
- *  \brief Log a message with SDL_LOG_PRIORITY_VERBOSE
+ * Log a message with SDL_LOG_PRIORITY_VERBOSE.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- *  \brief Log a message with SDL_LOG_PRIORITY_DEBUG
+ * Log a message with SDL_LOG_PRIORITY_DEBUG.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- *  \brief Log a message with SDL_LOG_PRIORITY_INFO
+ * Log a message with SDL_LOG_PRIORITY_INFO.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- *  \brief Log a message with SDL_LOG_PRIORITY_WARN
+ * Log a message with SDL_LOG_PRIORITY_WARN.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
  */
 extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- *  \brief Log a message with SDL_LOG_PRIORITY_ERROR
+ * Log a message with SDL_LOG_PRIORITY_ERROR.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- *  \brief Log a message with SDL_LOG_PRIORITY_CRITICAL
+ * Log a message with SDL_LOG_PRIORITY_CRITICAL.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- *  \brief Log a message with the specified category and priority.
+ * Log a message with the specified category and priority.
+ *
+ * \param category the category of the message
+ * \param priority the priority of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogMessage(int category,
                                             SDL_LogPriority priority,
                                             SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
 
 /**
- *  \brief Log a message with the specified category and priority.
+ * Log a message with the specified category and priority.
+ *
+ * \param category the category of the message
+ * \param priority the priority of the message
+ * \param fmt a printf() style message format string
+ * \param ap a variable argument list
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
                                              SDL_LogPriority priority,
                                              const char *fmt, va_list ap);
 
 /**
- *  \brief The prototype for the log output function
+ * The prototype for the log output callback function.
+ *
+ * This function is called by SDL when there is new text to be logged.
+ *
+ * \param userdata what was passed as `userdata` to SDL_LogSetOutputFunction()
+ * \param category the category of the message
+ * \param priority the priority of the message
+ * \param message the message being output
  */
 typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
 
 /**
- *  \brief Get the current log output function.
+ * Get the current log output function.
+ *
+ * \param callback an SDL_LogOutputFunction filled in with the current log
+ *                 callback
+ * \param userdata a pointer filled in with the pointer that is passed to
+ *                 `callback`
+ *
+ * \sa SDL_LogSetOutputFunction
  */
 extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
 
 /**
- *  \brief This function allows you to replace the default log output
+ * Replace the default log output function with one of your own.
- *         function with one of your own.
+ *
+ * \param callback an SDL_LogOutputFunction to call instead of the default
+ * \param userdata a pointer that is passed to `callback`
+ *
+ * \sa SDL_LogGetOutputFunction
  */
 extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata);
 

dep/msvc/sdl2/include/SDL_main.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -122,18 +122,22 @@ extern SDLMAIN_DECLSPEC int SDL_main(int argc, char *argv[]);
 
 
 /**
- *  This is called by the real SDL main function to let the rest of the
+ * Circumvent failure of SDL_Init() when not using SDL_main() as an entry
- *  library know that initialization was done properly.
+ * point.
  *
- *  Calling this yourself without knowing what you're doing can cause
+ * This function is defined in SDL_main.h, along with the preprocessor rule to
- *  crashes and hard to diagnose problems with your application.
+ * redefine main() as SDL_main(). Thus to ensure that your main() function
+ * will not be changed it is necessary to define SDL_MAIN_HANDLED before
+ * including SDL.h.
+ *
+ * \sa SDL_Init
  */
 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);
@@ -144,12 +148,14 @@ extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
 #ifdef __WINRT__
 
 /**
- *  \brief Initializes and launches an SDL/WinRT application.
+ * Initialize and launch an SDL/WinRT application.
+ *
+ * \param mainFunction the SDL app's C-style main(), an SDL_main_func
+ * \param reserved reserved for future use; should be NULL
+ * \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve
+ *          more information on the failure.
  *
- *  \param mainFunction The SDL app's C-style main().
+ * \since This function is available since SDL 2.0.3.
- *  \param reserved Reserved for future use; should be NULL
- *  \return 0 on success, -1 on failure.  On failure, use SDL_GetError to retrieve more
- *      information on the failure.
  */
 extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * reserved);
 
@@ -158,12 +164,12 @@ extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * r
 #if defined(__IPHONEOS__)
 
 /**
- *  \brief Initializes and launches an SDL application.
+ * Initializes and launches an SDL application.
  *
- *  \param argc The argc parameter from the application's main() function
+ * \param argc The argc parameter from the application's main() function
- *  \param argv The argv parameter from the application's main() function
+ * \param argv The argv parameter from the application's main() function
- *  \param mainFunction The SDL app's C-style main().
+ * \param mainFunction The SDL app's C-style main(), an SDL_main_func
- *  \return the return value from mainFunction
+ * \return the return value from mainFunction
  */
 extern DECLSPEC int SDLCALL SDL_UIKitRunApp(int argc, char *argv[], SDL_main_func mainFunction);
 

dep/msvc/sdl2/include/SDL_messagebox.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -32,17 +32,19 @@ extern "C" {
 #endif
 
 /**
- * \brief SDL_MessageBox flags. If supported will display warning icon, etc.
+ * SDL_MessageBox flags. If supported will display warning icon, etc.
  */
 typedef enum
 {
-    SDL_MESSAGEBOX_ERROR        = 0x00000010,   /**< error dialog */
+    SDL_MESSAGEBOX_ERROR                 = 0x00000010,   /**< error dialog */
-    SDL_MESSAGEBOX_WARNING      = 0x00000020,   /**< warning dialog */
+    SDL_MESSAGEBOX_WARNING               = 0x00000020,   /**< warning dialog */
-    SDL_MESSAGEBOX_INFORMATION  = 0x00000040    /**< informational dialog */
+    SDL_MESSAGEBOX_INFORMATION           = 0x00000040,   /**< informational dialog */
+    SDL_MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT = 0x00000080,   /**< buttons placed left to right */
+    SDL_MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT = 0x00000100    /**< buttons placed right to left */
 } SDL_MessageBoxFlags;
 
 /**
- * \brief Flags for SDL_MessageBoxButtonData.
+ * Flags for SDL_MessageBoxButtonData.
  */
 typedef enum
 {
@@ -51,7 +53,7 @@ typedef enum
 } SDL_MessageBoxButtonFlags;
 
 /**
- *  \brief Individual button data.
+ * Individual button data.
  */
 typedef struct
 {
@@ -61,7 +63,7 @@ typedef struct
 } SDL_MessageBoxButtonData;
 
 /**
- * \brief RGB value used in a message box color scheme
+ * RGB value used in a message box color scheme
  */
 typedef struct
 {
@@ -79,7 +81,7 @@ typedef enum
 } SDL_MessageBoxColorType;
 
 /**
- * \brief A set of colors to use for message box dialogs
+ * A set of colors to use for message box dialogs
  */
 typedef struct
 {
@@ -87,7 +89,7 @@ typedef struct
 } SDL_MessageBoxColorScheme;
 
 /**
- *  \brief MessageBox structure containing title, text, window, etc.
+ * MessageBox structure containing title, text, window, etc.
  */
 typedef struct
 {
@@ -103,32 +105,77 @@ typedef struct
 } SDL_MessageBoxData;
 
 /**
- *  \brief Create a modal message box.
+ * Create a modal message box.
  *
- *  \param messageboxdata The SDL_MessageBoxData structure with title, text, etc.
+ * If your needs aren't complex, it might be easier to use
- *  \param buttonid The pointer to which user id of hit button should be copied.
+ * SDL_ShowSimpleMessageBox.
  *
- *  \return -1 on error, otherwise 0 and buttonid contains user id of button
+ * This function should be called on the thread that created the parent
- *          hit or -1 if dialog was closed.
+ * window, or on the main thread if the messagebox has no parent. It will
+ * block execution of that thread until the user clicks a button or closes the
+ * messagebox.
  *
- *  \note This function should be called on the thread that created the parent
+ * This function may be called at any time, even before SDL_Init(). This makes
- *        window, or on the main thread if the messagebox has no parent.  It will
+ * it useful for reporting errors like a failure to create a renderer or
- *        block execution of that thread until the user clicks a button or
+ * OpenGL context.
- *        closes the messagebox.
+ *
+ * On X11, SDL rolls its own dialog box with X11 primitives instead of a
+ * formal toolkit like GTK+ or Qt.
+ *
+ * Note that if SDL_Init() would fail because there isn't any available video
+ * target, this function is likely to fail for the same reasons. If this is a
+ * concern, check the return value from this function and fall back to writing
+ * to stderr if you can.
+ *
+ * \param messageboxdata the SDL_MessageBoxData structure with title, text and
+ *                       other options
+ * \param buttonid the pointer to which user id of hit button should be copied
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_ShowSimpleMessageBox
  */
 extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid);
 
 /**
- *  \brief Create a simple modal message box
+ * Display a simple modal message box.
+ *
+ * If your needs aren't complex, this function is preferred over
+ * SDL_ShowMessageBox.
+ *
+ * `flags` may be any of the following:
+ *
+ * - `SDL_MESSAGEBOX_ERROR`: error dialog
+ * - `SDL_MESSAGEBOX_WARNING`: warning dialog
+ * - `SDL_MESSAGEBOX_INFORMATION`: informational dialog
+ *
+ * This function should be called on the thread that created the parent
+ * window, or on the main thread if the messagebox has no parent. It will
+ * block execution of that thread until the user clicks a button or closes the
+ * messagebox.
+ *
+ * This function may be called at any time, even before SDL_Init(). This makes
+ * it useful for reporting errors like a failure to create a renderer or
+ * OpenGL context.
+ *
+ * On X11, SDL rolls its own dialog box with X11 primitives instead of a
+ * formal toolkit like GTK+ or Qt.
  *
- *  \param flags    ::SDL_MessageBoxFlags
+ * Note that if SDL_Init() would fail because there isn't any available video
- *  \param title    UTF-8 title text
+ * target, this function is likely to fail for the same reasons. If this is a
- *  \param message  UTF-8 message text
+ * concern, check the return value from this function and fall back to writing
- *  \param window   The parent window, or NULL for no parent
+ * to stderr if you can.
  *
- *  \return 0 on success, -1 on error
+ * \param flags an SDL_MessageBoxFlags value
+ * \param title UTF-8 title text
+ * \param message UTF-8 message text
+ * \param window the parent window, or NULL for no parent
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_ShowMessageBox
+ * \sa SDL_ShowMessageBox
  */
 extern DECLSPEC int SDLCALL SDL_ShowSimpleMessageBox(Uint32 flags, const char *title, const char *message, SDL_Window *window);
 

dep/msvc/sdl2/include/SDL_metal.h

@@ -0,0 +1,104 @@
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+
+/**
+ *  \file SDL_metal.h
+ *
+ *  Header file for functions to creating Metal layers and views on SDL windows.
+ */
+
+#ifndef SDL_metal_h_
+#define SDL_metal_h_
+
+#include "SDL_video.h"
+
+#include "begin_code.h"
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ *  \brief A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS).
+ *
+ *  \note This can be cast directly to an NSView or UIView.
+ */
+typedef void *SDL_MetalView;
+
+/**
+ *  \name Metal support functions
+ */
+/* @{ */
+
+/**
+ * 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.
+ *
+ * The returned handle can be casted directly to a NSView or UIView. To access
+ * the backing CAMetalLayer, call SDL_Metal_GetLayer().
+ *
+ * \sa SDL_Metal_DestroyView
+ * \sa SDL_Metal_GetLayer
+ */
+extern DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * window);
+
+/**
+ * Destroy an existing SDL_MetalView object.
+ *
+ * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was
+ * called after SDL_CreateWindow.
+ *
+ * \sa SDL_Metal_CreateView
+ */
+extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view);
+
+/**
+ * Get a pointer to the backing CAMetalLayer for the given view.
+ *
+ * \sa SDL_MetalCreateView
+ */
+extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(SDL_MetalView view);
+
+/**
+ * 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
+ *
+ * \sa SDL_GetWindowSize
+ * \sa SDL_CreateWindow
+ */
+extern DECLSPEC void SDLCALL SDL_Metal_GetDrawableSize(SDL_Window* window, int *w,
+                                                       int *h);
+
+/* @} *//* Metal support functions */
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+}
+#endif
+#include "close_code.h"
+
+#endif /* SDL_metal_h_ */

dep/msvc/sdl2/include/SDL_misc.h

@@ -0,0 +1,79 @@
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+
+/**
+ *  \file SDL_misc.h
+ *
+ *  \brief Include file for SDL API functions that don't fit elsewhere.
+ */
+
+#ifndef SDL_misc_h_
+#define SDL_misc_h_
+
+#include "SDL_stdinc.h"
+
+#include "begin_code.h"
+
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Open a URL/URI in the browser or other appropriate external application.
+ *
+ * Open a URL in a separate, system-provided application. How this works will
+ * vary wildly depending on the platform. This will likely launch what makes
+ * sense to handle a specific URL's protocol (a web browser for `http://`,
+ * etc), but it might also be able to launch file managers for directories and
+ * other things.
+ *
+ * What happens when you open a URL varies wildly as well: your game window
+ * may lose focus (and may or may not lose focus if your game was fullscreen
+ * or grabbing input at the time). On mobile devices, your app will likely
+ * move to the background or your process might be paused. Any given platform
+ * may or may not handle a given URL.
+ *
+ * If this is unimplemented (or simply unavailable) for a platform, this will
+ * fail with an error. A successful result does not mean the URL loaded, just
+ * that we launched _something_ to handle it (or at least believe we did).
+ *
+ * All this to say: this function can be useful, but you should definitely
+ * test it on every platform you target.
+ *
+ * \param url A valid URL/URI to open. Use `file:///full/path/to/file` for
+ *            local files, if supported.
+ * \returns 0 on success, or -1 on error; call SDL_GetError() for more
+ *          information.
+ *
+ * \since This function is available in SDL 2.0.14 and newer
+ */
+extern DECLSPEC int SDLCALL SDL_OpenURL(const char *url);
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+}
+#endif
+#include "close_code.h"
+
+#endif /* SDL_misc_h_ */
+
+/* vi: set ts=4 sw=4 expandtab: */

dep/msvc/sdl2/include/SDL_mouse.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -72,150 +72,226 @@ typedef enum
 /* Function prototypes */
 
 /**
- *  \brief Get the window which currently has mouse focus.
+ * Get the window which currently has mouse focus.
+ *
+ * \returns the window with mouse focus.
  */
 extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
 
 /**
- *  \brief Retrieve the current state of the mouse.
+ * Retrieve the current state of the mouse.
+ *
+ * The current button state is returned as a button bitmask, which can be
+ * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
+ * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
+ * mouse cursor position relative to the focus window. You can pass NULL for
+ * either `x` or `y`.
+ *
+ * \param x the x coordinate of the mouse cursor position relative to the
+ *          focus window
+ * \param y the y coordinate of the mouse cursor position relative to the
+ *          focus window
+ * \returns a 32-bit button bitmask of the current button state.
  *
- *  The current button state is returned as a button bitmask, which can
+ * \sa SDL_GetGlobalMouseState
- *  be tested using the SDL_BUTTON(X) macros, and x and y are set to the
+ * \sa SDL_GetRelativeMouseState
- *  mouse cursor position relative to the focus window for the currently
+ * \sa SDL_PumpEvents
- *  selected mouse.  You can pass NULL for either x or y.
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
 
 /**
- *  \brief Get the current state of the mouse, in relation to the desktop
+ * Get the current state of the mouse in relation to the desktop.
- *
+ *
- *  This works just like SDL_GetMouseState(), but the coordinates will be
+ * This works similarly to SDL_GetMouseState(), but the coordinates will be
- *  reported relative to the top-left of the desktop. This can be useful if
+ * reported relative to the top-left of the desktop. This can be useful if you
- *  you need to track the mouse outside of a specific window and
+ * need to track the mouse outside of a specific window and SDL_CaptureMouse()
- *  SDL_CaptureMouse() doesn't fit your needs. For example, it could be
+ * doesn't fit your needs. For example, it could be useful if you need to
- *  useful if you need to track the mouse while dragging a window, where
+ * track the mouse while dragging a window, where coordinates relative to a
- *  coordinates relative to a window might not be in sync at all times.
+ * window might not be in sync at all times.
- *
+ *
- *  \note SDL_GetMouseState() returns the mouse position as SDL understands
+ * Note: SDL_GetMouseState() returns the mouse position as SDL understands it
- *        it from the last pump of the event queue. This function, however,
+ * from the last pump of the event queue. This function, however, queries the
- *        queries the OS for the current mouse position, and as such, might
+ * OS for the current mouse position, and as such, might be a slightly less
- *        be a slightly less efficient function. Unless you know what you're
+ * efficient function. Unless you know what you're doing and have a good
- *        doing and have a good reason to use this function, you probably want
+ * reason to use this function, you probably want SDL_GetMouseState() instead.
- *        SDL_GetMouseState() instead.
+ *
- *
+ * \param x filled in with the current X coord relative to the desktop; can be
- *  \param x Returns the current X coord, relative to the desktop. Can be NULL.
+ *          NULL
- *  \param y Returns the current Y coord, relative to the desktop. Can be NULL.
+ * \param y filled in with the current Y coord relative to the desktop; can be
- *  \return The current button state as a bitmask, which can be tested using the SDL_BUTTON(X) macros.
+ *          NULL
- *
+ * \returns the current button state as a bitmask which can be tested using
- *  \sa SDL_GetMouseState
+ *          the SDL_BUTTON(X) macros.
+ *
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_CaptureMouse
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y);
 
 /**
- *  \brief Retrieve the relative state of the mouse.
+ * Retrieve the relative state of the mouse.
+ *
+ * The current button state is returned as a button bitmask, which can be
+ * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
+ * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
+ * mouse deltas since the last call to SDL_GetRelativeMouseState() or since
+ * event initialization. You can pass NULL for either `x` or `y`.
  *
- *  The current button state is returned as a button bitmask, which can
+ * \param x a pointer filled with the last recorded x coordinate of the mouse
- *  be tested using the SDL_BUTTON(X) macros, and x and y are set to the
+ * \param y a pointer filled with the last recorded y coordinate of the mouse
- *  mouse deltas since the last call to SDL_GetRelativeMouseState().
+ * \returns a 32-bit button bitmask of the relative button state.
+ *
+ * \sa SDL_GetMouseState
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
 
 /**
- *  \brief Moves the mouse to the given position within the window.
+ * Move the mouse cursor to the given position within the window.
+ *
+ * This function generates a mouse motion event.
+ *
+ * Note that this function will appear to succeed, but not actually move the
+ * mouse when used over Microsoft Remote Desktop.
  *
- *  \param window The window to move the mouse into, or NULL for the current mouse focus
+ * \param window the window to move the mouse into, or NULL for the current
- *  \param x The x coordinate within the window
+ *               mouse focus
- *  \param y The y coordinate within the window
+ * \param x the x coordinate within the window
+ * \param y the y coordinate within the window
  *
- *  \note This function generates a mouse motion event
+ * \sa SDL_WarpMouseGlobal
  */
 extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
                                                    int x, int y);
 
 /**
- *  \brief Moves the mouse to the given position in global screen space.
+ * Move the mouse to the given position in global screen space.
  *
- *  \param x The x coordinate
+ * This function generates a mouse motion event.
- *  \param y The y coordinate
- *  \return 0 on success, -1 on error (usually: unsupported by a platform).
  *
- *  \note This function generates a mouse motion event
+ * A failure of this function usually means that it is unsupported by a
+ * platform.
+ *
+ * Note that this function will appear to succeed, but not actually move the
+ * mouse when used over Microsoft Remote Desktop.
+ *
+ * \param x the x coordinate
+ * \param y the y coordinate
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_WarpMouseInWindow
  */
 extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(int x, int y);
 
 /**
- *  \brief Set relative mouse mode.
+ * Set relative mouse mode.
+ *
+ * While the mouse is in relative mode, the cursor is hidden, and the driver
+ * will try to report continuous motion in the current window. Only relative
+ * motion events will be delivered, the mouse position will not change.
  *
- *  \param enabled Whether or not to enable relative mode
+ * Note that this function will not be able to provide continuous relative
+ * motion when used over Microsoft Remote Desktop, instead motion is limited
+ * to the bounds of the screen.
  *
- *  \return 0 on success, or -1 if relative mode is not supported.
+ * This function will flush any pending mouse motion.
  *
- *  While the mouse is in relative mode, the cursor is hidden, and the
+ * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable.
- *  driver will try to report continuous motion in the current window.
+ * \returns 0 on success or a negative error code on failure; call
- *  Only relative motion events will be delivered, the mouse position
+ *          SDL_GetError() for more information.
- *  will not change.
  *
- *  \note This function will flush any pending mouse motion.
+ *          If relative mode is not supported, this returns -1.
  *
- *  \sa SDL_GetRelativeMouseMode()
+ * \sa SDL_GetRelativeMouseMode
  */
 extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
 
 /**
- *  \brief Capture the mouse, to track input outside an SDL window.
+ * Capture the mouse and to track input outside an SDL window.
+ *
+ * Capturing enables your app to obtain mouse events globally, instead of just
+ * within your window. Not all video targets support this function. When
+ * capturing is enabled, the current window will get all mouse events, but
+ * unlike relative mode, no change is made to the cursor and it is not
+ * restrained to your window.
  *
- *  \param enabled Whether or not to enable capturing
+ * This function may also deny mouse input to other windows--both those in
+ * your application and others on the system--so you should use this function
+ * sparingly, and in small bursts. For example, you might want to track the
+ * mouse while the user is dragging something, until the user releases a mouse
+ * button. It is not recommended that you capture the mouse for long periods
+ * of time, such as the entire time your app is running. For that, you should
+ * probably use SDL_SetRelativeMouseMode() or SDL_SetWindowGrab(), depending
+ * on your goals.
  *
- *  Capturing enables your app to obtain mouse events globally, instead of
+ * While captured, mouse events still report coordinates relative to the
- *  just within your window. Not all video targets support this function.
+ * current (foreground) window, but those coordinates may be outside the
- *  When capturing is enabled, the current window will get all mouse events,
+ * bounds of the window (including negative values). Capturing is only allowed
- *  but unlike relative mode, no change is made to the cursor and it is
+ * for the foreground window. If the window loses focus while capturing, the
- *  not restrained to your window.
+ * capture will be disabled automatically.
  *
- *  This function may also deny mouse input to other windows--both those in
+ * While capturing is enabled, the current window will have the
- *  your application and others on the system--so you should use this
+ * `SDL_WINDOW_MOUSE_CAPTURE` flag set.
- *  function sparingly, and in small bursts. For example, you might want to
- *  track the mouse while the user is dragging something, until the user
- *  releases a mouse button. It is not recommended that you capture the mouse
- *  for long periods of time, such as the entire time your app is running.
  *
- *  While captured, mouse events still report coordinates relative to the
+ * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable.
- *  current (foreground) window, but those coordinates may be outside the
+ * \returns 0 on success or -1 if not supported; call SDL_GetError() for more
- *  bounds of the window (including negative values). Capturing is only
+ *          information.
- *  allowed for the foreground window. If the window loses focus while
- *  capturing, the capture will be disabled automatically.
  *
- *  While capturing is enabled, the current window will have the
+ * \since This function is available since SDL 2.0.4.
- *  SDL_WINDOW_MOUSE_CAPTURE flag set.
  *
- *  \return 0 on success, or -1 if not supported.
+ * \sa SDL_GetGlobalMouseState
  */
 extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
 
 /**
- *  \brief Query whether relative mouse mode is enabled.
+ * Query whether relative mouse mode is enabled.
  *
- *  \sa SDL_SetRelativeMouseMode()
+ * \returns SDL_TRUE if relative mode is enabled or SDL_FALSE otherwise.
+ *
+ * \sa SDL_SetRelativeMouseMode
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
 
 /**
- *  \brief Create a cursor, using the specified bitmap data and
+ * Create a cursor using the specified bitmap data and mask (in MSB format).
- *         mask (in MSB format).
+ *
- *
+ * `mask` has to be in MSB (Most Significant Bit) format.
- *  The cursor width must be a multiple of 8 bits.
+ *
- *
+ * The cursor width (`w`) must be a multiple of 8 bits.
- *  The cursor is created in black and white according to the following:
+ *
- *  <table>
+ * The cursor is created in black and white according to the following:
- *  <tr><td> data </td><td> mask </td><td> resulting pixel on screen </td></tr>
+ *
- *  <tr><td>  0   </td><td>  1   </td><td> White </td></tr>
+ * - data=0, mask=1: white
- *  <tr><td>  1   </td><td>  1   </td><td> Black </td></tr>
+ * - data=1, mask=1: black
- *  <tr><td>  0   </td><td>  0   </td><td> Transparent </td></tr>
+ * - data=0, mask=0: transparent
- *  <tr><td>  1   </td><td>  0   </td><td> Inverted color if possible, black
+ * - data=1, mask=0: inverted color if possible, black if not.
- *                                         if not. </td></tr>
+ *
- *  </table>
+ * Cursors created with this function must be freed with SDL_FreeCursor().
- *
+ *
- *  \sa SDL_FreeCursor()
+ * If you want to have a color cursor, or create your cursor from an
+ * SDL_Surface, you should use SDL_CreateColorCursor(). Alternately, you can
+ * hide the cursor and draw your own as part of your game's rendering, but it
+ * will be bound to the framerate.
+ *
+ * Also, since SDL 2.0.0, SDL_CreateSystemCursor() is available, which
+ * provides twelve readily available system cursors to pick from.
+ *
+ * \param data the color value for each pixel of the cursor
+ * \param mask the mask value for each pixel of the cursor
+ * \param w the width of the cursor
+ * \param h the height of the cursor
+ * \param hot_x the X-axis location of the upper left corner of the cursor
+ *              relative to the actual mouse position
+ * \param hot_y the Y-axis location of the upper left corner of the cursor
+ *              relative to the actual mouse position
+ * \returns a new cursor with the specified parameters on success or NULL on
+ *          failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_FreeCursor
+ * \sa SDL_SetCursor
+ * \sa SDL_ShowCursor
  */
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
                                                      const Uint8 * mask,
@@ -223,60 +299,115 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
                                                      int hot_y);
 
 /**
- *  \brief Create a color cursor.
+ * Create a color cursor.
+ *
+ * \param surface an SDL_Surface structure representing the cursor image
+ * \param hot_x the x position of the cursor hot spot
+ * \param hot_y the y position of the cursor hot spot
+ * \returns the new cursor on success or NULL on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_FreeCursor()
+ * \sa SDL_CreateCursor
+ * \sa SDL_FreeCursor
  */
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface,
                                                           int hot_x,
                                                           int hot_y);
 
 /**
- *  \brief Create a system cursor.
+ * Create a system cursor.
  *
- *  \sa SDL_FreeCursor()
+ * \param id an SDL_SystemCursor enum value
+ * \returns a cursor on success or NULL on failure; call SDL_GetError() for
+ *          more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_FreeCursor
  */
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id);
 
 /**
- *  \brief Set the active cursor.
+ * Set the active cursor.
+ *
+ * This function sets the currently active cursor to the specified one. If the
+ * cursor is currently visible, the change will be immediately represented on
+ * 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
+ *
+ * \sa SDL_CreateCursor
+ * \sa SDL_GetCursor
+ * \sa SDL_ShowCursor
  */
 extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);
 
 /**
- *  \brief Return the active cursor.
+ * Get the active cursor.
+ *
+ * This function returns a pointer to the current cursor which is owned by the
+ * library. It is not necessary to free the cursor with SDL_FreeCursor().
+ *
+ * \returns the active cursor or NULL if there is no mouse.
+ *
+ * \sa SDL_SetCursor
  */
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
 
 /**
- *  \brief Return the default cursor.
+ * Get the default cursor.
+ *
+ * \returns the default cursor on success or NULL on failure.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateSystemCursor
  */
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
 
 /**
- *  \brief Frees a cursor created with SDL_CreateCursor() or similar functions.
+ * Free a previously-created cursor.
+ *
+ * Use this function to free cursor resources created with SDL_CreateCursor(),
+ * SDL_CreateColorCursor() or SDL_CreateSystemCursor().
  *
- *  \sa SDL_CreateCursor()
+ * \param cursor the cursor to free
- *  \sa SDL_CreateColorCursor()
+ *
- *  \sa SDL_CreateSystemCursor()
+ * \sa SDL_CreateColorCursor
+ * \sa SDL_CreateCursor
+ * \sa SDL_CreateSystemCursor
  */
 extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
 
 /**
- *  \brief Toggle whether or not the cursor is shown.
+ * Toggle whether or not the cursor is shown.
+ *
+ * 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.
  *
- *  \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current
+ * \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it,
- *                state.
+ *               `SDL_QUERY` to query the current state without changing it.
+ * \returns `SDL_ENABLE` if the cursor is shown, or `SDL_DISABLE` if the
+ *          cursor is hidden, or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \return 1 if the cursor is shown, or 0 if the cursor is hidden.
+ * \sa SDL_CreateCursor
+ * \sa SDL_SetCursor
  */
 extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
 
 /**
- *  Used as a mask when testing buttons in buttonstate.
+ * Used as a mask when testing buttons in buttonstate.
- *   - Button 1:  Left mouse button
+ *
- *   - Button 2:  Middle mouse button
+ * - Button 1:  Left mouse button
- *   - Button 3:  Right mouse button
+ * - Button 2:  Middle mouse button
+ * - Button 3:  Right mouse button
  */
 #define SDL_BUTTON(X)       (1 << ((X)-1))
 #define SDL_BUTTON_LEFT     1
@@ -290,7 +421,6 @@ extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
 #define SDL_BUTTON_X1MASK   SDL_BUTTON(SDL_BUTTON_X1)
 #define SDL_BUTTON_X2MASK   SDL_BUTTON(SDL_BUTTON_X2)
 
-
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

dep/msvc/sdl2/include/SDL_mutex.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -59,38 +59,95 @@ struct SDL_mutex;
 typedef struct SDL_mutex SDL_mutex;
 
 /**
- *  Create a mutex, initialized unlocked.
+ * Create a new mutex.
+ *
+ * All newly-created mutexes begin in the _unlocked_ state.
+ *
+ * Calls to SDL_LockMutex() will not return while the mutex is locked by
+ * another thread. See SDL_TryLockMutex() to attempt to lock without blocking.
+ *
+ * SDL mutexes are reentrant.
+ *
+ * \returns the initialized and unlocked mutex or NULL on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_DestroyMutex
+ * \sa SDL_LockMutex
+ * \sa SDL_TryLockMutex
+ * \sa SDL_UnlockMutex
  */
 extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
 
 /**
- *  Lock the mutex.
+ * Lock the mutex.
+ *
+ * This will block until the mutex is available, which is to say it is in the
+ * unlocked state and the OS has chosen the caller as the next thread to lock
+ * it. Of all threads waiting to lock the mutex, only one may do so at a time.
  *
- *  \return 0, or -1 on error.
+ * 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").
+ *
+ * \param mutex the mutex to lock
+ * \return 0, or -1 on error.
  */
-#define SDL_mutexP(m)   SDL_LockMutex(m)
 extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex);
+#define SDL_mutexP(m)   SDL_LockMutex(m)
 
 /**
- *  Try to lock the mutex
+ * Try to lock a mutex without blocking.
+ *
+ * This works just like SDL_LockMutex(), but if the mutex is not available,
+ * this function returns `SDL_MUTEX_TIMEOUT` immediately.
+ *
+ * This technique is useful if you need exclusive access to a resource but
+ * 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.
  *
- *  \return 0, SDL_MUTEX_TIMEDOUT, or -1 on error
+ * \sa SDL_CreateMutex
+ * \sa SDL_DestroyMutex
+ * \sa SDL_LockMutex
+ * \sa SDL_UnlockMutex
  */
 extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex);
 
 /**
- *  Unlock the mutex.
+ * Unlock the mutex.
  *
- *  \return 0, or -1 on error.
+ * 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").
  *
- *  \warning It is an error to unlock a mutex that has not been locked by
+ * It is an error to unlock a mutex that has not been locked by the current
- *           the current thread, and doing so results in undefined behavior.
+ * thread, and doing so results in undefined behavior.
+ *
+ * It is also an error to unlock a mutex that isn't locked at all.
+ *
+ * \param mutex the mutex to unlock.
+ * \returns 0, or -1 on error.
  */
-#define SDL_mutexV(m)   SDL_UnlockMutex(m)
 extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex);
+#define SDL_mutexV(m)   SDL_UnlockMutex(m)
 
 /**
- *  Destroy a mutex.
+ * Destroy a mutex created with SDL_CreateMutex().
+ *
+ * This function must be called on any mutex that is no longer needed. Failure
+ * to destroy a mutex will result in a system memory or resource leak. While
+ * it is safe to destroy a mutex that is _unlocked_, it is not safe to attempt
+ * to destroy a locked mutex, and may result in undefined behavior depending
+ * on the platform.
+ *
+ * \param mutex the mutex to destroy
+ *
+ * \sa SDL_CreateMutex
+ * \sa SDL_LockMutex
+ * \sa SDL_TryLockMutex
+ * \sa SDL_UnlockMutex
  */
 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
 
@@ -107,50 +164,137 @@ struct SDL_semaphore;
 typedef struct SDL_semaphore SDL_sem;
 
 /**
- *  Create a semaphore, initialized with value, returns NULL on failure.
+ * Create a semaphore.
+ *
+ * This function creates a new semaphore and initializes it with the value
+ * `initial_value`. Each wait operation on the semaphore will atomically
+ * decrement the semaphore value and potentially block if the semaphore value
+ * is 0. Each post operation will atomically increment the semaphore value and
+ * wake waiting threads and allow them to retry the wait operation.
+ *
+ * \param initial_value the starting value of the semaphore
+ * \returns a new semaphore or NULL on failure; call SDL_GetError() for more
+ *          information.
+ *
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
  */
 extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
 
 /**
- *  Destroy a semaphore.
+ * Destroy a semaphore.
+ *
+ * It is not safe to destroy a semaphore if there are threads currently
+ * waiting on it.
+ *
+ * \param sem the semaphore to destroy
+ *
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
  */
 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
 
 /**
- *  This function suspends the calling thread until the semaphore pointed
+ * Wait until a semaphore has a positive value and then decrements it.
- *  to by \c sem has a positive count. It then atomically decreases the
+ *
- *  semaphore count.
+ * This function suspends the calling thread until either the semaphore
+ * pointed to by `sem` has a positive value or the call is interrupted by a
+ * signal or error. If the call is successful it will atomically decrement the
+ * semaphore value.
+ *
+ * This function is the equivalent of calling SDL_SemWaitTimeout() with a time
+ * length of `SDL_MUTEX_MAXWAIT`.
+ *
+ * \param sem the semaphore wait on
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
  */
 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
 
 /**
- *  Non-blocking variant of SDL_SemWait().
+ * See if a semaphore has a positive value and decrement it if it does.
+ *
+ * This function checks to see if the semaphore pointed to by `sem` has a
+ * positive value and atomically decrements the semaphore value if it does. If
+ * the semaphore doesn't have a positive value, the function immediately
+ * returns SDL_MUTEX_TIMEDOUT.
  *
- *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would
+ * \param sem the semaphore to wait on
- *          block, and -1 on error.
+ * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would
+ *          block, or a negative error code on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
  */
 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
 
 /**
- *  Variant of SDL_SemWait() with a timeout in milliseconds.
+ * 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
+ * signal or error, or the specified time has elapsed. If the call is
+ * successful it will atomically decrement the semaphore value.
  *
- *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not
+ * \param sem the semaphore to wait on
- *          succeed in the allotted time, and -1 on error.
+ * \param ms the length of the timeout, in milliseconds
+ * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not
+ *          succeed in the allotted time, or a negative error code on failure;
+ *          call SDL_GetError() for more information.
  *
- *  \warning On some platforms this function is implemented by looping with a
+ * \sa SDL_CreateSemaphore
- *           delay of 1 ms, and so should be avoided if possible.
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
  */
 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
 
 /**
- *  Atomically increases the semaphore's count (not blocking).
+ * Atomically increment a semaphore's value and wake waiting threads.
+ *
+ * \param sem the semaphore to increment
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \return 0, or -1 on error.
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
  */
 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
 
 /**
- *  Returns the current count of the semaphore.
+ * Get the current value of a semaphore.
+ *
+ * \param sem the semaphore to query
+ * \returns the current value of the semaphore.
+ *
+ * \sa SDL_CreateSemaphore
  */
 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
 
@@ -167,72 +311,112 @@ struct SDL_cond;
 typedef struct SDL_cond SDL_cond;
 
 /**
- *  Create a condition variable.
+ * Create a condition variable.
- *
- *  Typical use of condition variables:
  *
- *  Thread A:
+ * \returns a new condition variable or NULL on failure; call SDL_GetError()
- *    SDL_LockMutex(lock);
+ *          for more information.
- *    while ( ! condition ) {
- *        SDL_CondWait(cond, lock);
- *    }
- *    SDL_UnlockMutex(lock);
  *
- *  Thread B:
+ * \sa SDL_CondBroadcast
- *    SDL_LockMutex(lock);
+ * \sa SDL_CondSignal
- *    ...
+ * \sa SDL_CondWait
- *    condition = true;
+ * \sa SDL_CondWaitTimeout
- *    ...
+ * \sa SDL_DestroyCond
- *    SDL_CondSignal(cond);
- *    SDL_UnlockMutex(lock);
- *
- *  There is some discussion whether to signal the condition variable
- *  with the mutex locked or not.  There is some potential performance
- *  benefit to unlocking first on some platforms, but there are some
- *  potential race conditions depending on how your code is structured.
- *
- *  In general it's safer to signal the condition variable while the
- *  mutex is locked.
  */
 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
 
 /**
- *  Destroy a condition variable.
+ * Destroy a condition variable.
+ *
+ * \param cond the condition variable to destroy
+ *
+ * \sa SDL_CondBroadcast
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_CreateCond
  */
 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
 
 /**
- *  Restart one of the threads that are waiting on the condition variable.
+ * Restart one of the threads that are waiting on the condition variable.
+ *
+ * \param cond the condition variable to signal
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \return 0 or -1 on error.
+ * \sa SDL_CondBroadcast
+ * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
  */
 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
 
 /**
- *  Restart all threads that are waiting on the condition variable.
+ * Restart all threads that are waiting on the condition variable.
+ *
+ * \param cond the condition variable to signal
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \return 0 or -1 on error.
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
  */
 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
 
 /**
- *  Wait on the condition variable, unlocking the provided mutex.
+ * Wait until a condition variable is signaled.
  *
- *  \warning The mutex must be locked before entering this function!
+ * 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 is re-locked once the condition variable is signaled.
+ * The mutex must be locked before calling this function.
  *
- *  \return 0 when it is signaled, or -1 on error.
+ * This function is the equivalent of calling SDL_CondWaitTimeout() with a
+ * time length of `SDL_MUTEX_MAXWAIT`.
+ *
+ * \param cond the condition variable to wait on
+ * \param mutex the mutex used to coordinate thread access
+ * \returns 0 when it is signaled or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_CondBroadcast
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
  */
 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
 
 /**
- *  Waits for at most \c ms milliseconds, and returns 0 if the condition
+ * Wait until a condition variable is signaled or a certain time has passed.
- *  variable is signaled, ::SDL_MUTEX_TIMEDOUT if the condition is not
+ *
- *  signaled in the allotted time, and -1 on error.
+ * 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.
+ *
+ * \param cond the condition variable to wait on
+ * \param mutex the mutex used to coordinate thread access
+ * \param ms the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT`
+ *           to wait indefinitely
+ * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
+ *          the condition is not signaled in the allotted time, or a negative
+ *          error code on failure; call SDL_GetError() for more information.
  *
- *  \warning On some platforms this function is implemented by looping with a
+ * \sa SDL_CondBroadcast
- *           delay of 1 ms, and so should be avoided if possible.
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWait
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
  */
 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
                                                 SDL_mutex * mutex, Uint32 ms);

dep/msvc/sdl2/include/SDL_name.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_opengl.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_opengl_glext.h

@@ -40,6 +40,9 @@ extern "C" {
 #ifndef WIN32_LEAN_AND_MEAN
 #define WIN32_LEAN_AND_MEAN 1
 #endif
+#ifndef NOMINMAX   /* don't define min() and max(). */
+#define NOMINMAX
+#endif
 #include <windows.h>
 #endif
 

dep/msvc/sdl2/include/SDL_opengles.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_opengles2.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_pixels.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -48,7 +48,7 @@ extern "C" {
 /* @} */
 
 /** Pixel type. */
-enum
+typedef enum
 {
     SDL_PIXELTYPE_UNKNOWN,
     SDL_PIXELTYPE_INDEX1,
@@ -62,18 +62,18 @@ enum
     SDL_PIXELTYPE_ARRAYU32,
     SDL_PIXELTYPE_ARRAYF16,
     SDL_PIXELTYPE_ARRAYF32
-};
+} SDL_PixelType;
 
 /** Bitmap pixel order, high bit -> low bit. */
-enum
+typedef enum
 {
     SDL_BITMAPORDER_NONE,
     SDL_BITMAPORDER_4321,
     SDL_BITMAPORDER_1234
-};
+} SDL_BitmapOrder;
 
 /** Packed component order, high bit -> low bit. */
-enum
+typedef enum
 {
     SDL_PACKEDORDER_NONE,
     SDL_PACKEDORDER_XRGB,
@@ -84,12 +84,12 @@ enum
     SDL_PACKEDORDER_BGRX,
     SDL_PACKEDORDER_ABGR,
     SDL_PACKEDORDER_BGRA
-};
+} SDL_PackedOrder;
 
 /** Array component order, low byte -> high byte. */
 /* !!! FIXME: in 2.1, make these not overlap differently with
    !!! FIXME:  SDL_PACKEDORDER_*, so we can simplify SDL_ISPIXELFORMAT_ALPHA */
-enum
+typedef enum
 {
     SDL_ARRAYORDER_NONE,
     SDL_ARRAYORDER_RGB,
@@ -98,10 +98,10 @@ enum
     SDL_ARRAYORDER_BGR,
     SDL_ARRAYORDER_BGRA,
     SDL_ARRAYORDER_ABGR
-};
+} SDL_ArrayOrder;
 
 /** Packed component layout. */
-enum
+typedef enum
 {
     SDL_PACKEDLAYOUT_NONE,
     SDL_PACKEDLAYOUT_332,
@@ -112,7 +112,7 @@ enum
     SDL_PACKEDLAYOUT_8888,
     SDL_PACKEDLAYOUT_2101010,
     SDL_PACKEDLAYOUT_1010102
-};
+} SDL_PackedLayout;
 
 #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D)
 
@@ -188,15 +188,22 @@ typedef enum
     SDL_PIXELFORMAT_RGB332 =
         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED8, SDL_PACKEDORDER_XRGB,
                                SDL_PACKEDLAYOUT_332, 8, 1),
-    SDL_PIXELFORMAT_RGB444 =
+    SDL_PIXELFORMAT_XRGB4444 =
         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
                                SDL_PACKEDLAYOUT_4444, 12, 2),
-    SDL_PIXELFORMAT_RGB555 =
+    SDL_PIXELFORMAT_RGB444 = SDL_PIXELFORMAT_XRGB4444,
+    SDL_PIXELFORMAT_XBGR4444 =
+        SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
+                               SDL_PACKEDLAYOUT_4444, 12, 2),
+    SDL_PIXELFORMAT_BGR444 = SDL_PIXELFORMAT_XBGR4444,
+    SDL_PIXELFORMAT_XRGB1555 =
         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XRGB,
                                SDL_PACKEDLAYOUT_1555, 15, 2),
-    SDL_PIXELFORMAT_BGR555 =
+    SDL_PIXELFORMAT_RGB555 = SDL_PIXELFORMAT_XRGB1555,
+    SDL_PIXELFORMAT_XBGR1555 =
         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_XBGR,
                                SDL_PACKEDLAYOUT_1555, 15, 2),
+    SDL_PIXELFORMAT_BGR555 = SDL_PIXELFORMAT_XBGR1555,
     SDL_PIXELFORMAT_ARGB4444 =
         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED16, SDL_PACKEDORDER_ARGB,
                                SDL_PACKEDLAYOUT_4444, 16, 2),
@@ -233,15 +240,17 @@ typedef enum
     SDL_PIXELFORMAT_BGR24 =
         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_ARRAYU8, SDL_ARRAYORDER_BGR, 0,
                                24, 3),
-    SDL_PIXELFORMAT_RGB888 =
+    SDL_PIXELFORMAT_XRGB8888 =
         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB,
                                SDL_PACKEDLAYOUT_8888, 24, 4),
+    SDL_PIXELFORMAT_RGB888 = SDL_PIXELFORMAT_XRGB8888,
     SDL_PIXELFORMAT_RGBX8888 =
         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBX,
                                SDL_PACKEDLAYOUT_8888, 24, 4),
-    SDL_PIXELFORMAT_BGR888 =
+    SDL_PIXELFORMAT_XBGR8888 =
         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR,
                                SDL_PACKEDLAYOUT_8888, 24, 4),
+    SDL_PIXELFORMAT_BGR888 = SDL_PIXELFORMAT_XBGR8888,
     SDL_PIXELFORMAT_BGRX8888 =
         SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRX,
                                SDL_PACKEDLAYOUT_8888, 24, 4),
@@ -336,16 +345,29 @@ typedef struct SDL_PixelFormat
 } SDL_PixelFormat;
 
 /**
- * \brief Get the human readable name of a pixel format
+ * Get the human readable name of a pixel format.
+ *
+ * \param format the pixel format to query
+ * \returns the human readable name of the specified pixel format or
+ *          `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
 
 /**
- *  \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
+ * Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
  *
- *  \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
+ * \param format one of the SDL_PixelFormatEnum values
+ * \param bpp a bits per pixel value; usually 15, 16, or 32
+ * \param Rmask a pointer filled in with the red mask for the format
+ * \param Gmask a pointer filled in with the green mask for the format
+ * \param Bmask a pointer filled in with the blue mask for the format
+ * \param Amask a pointer filled in with the alpha mask for the format
+ * \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't
+ *          possible; call SDL_GetError() for more information.
  *
- *  \sa SDL_MasksToPixelFormatEnum()
+ * \sa SDL_MasksToPixelFormatEnum
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
                                                             int *bpp,
@@ -355,12 +377,19 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
                                                             Uint32 * Amask);
 
 /**
- *  \brief Convert a bpp and RGBA masks to an enumerated pixel format.
+ * Convert a bpp value and RGBA masks to an enumerated pixel format.
  *
- *  \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
+ * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't
- *          wasn't possible.
+ * possible.
  *
- *  \sa SDL_PixelFormatEnumToMasks()
+ * \param bpp a bits per pixel value; usually 15, 16, or 32
+ * \param Rmask the red mask for the format
+ * \param Gmask the green mask for the format
+ * \param Bmask the blue mask for the format
+ * \param Amask the alpha mask for the format
+ * \returns one of the SDL_PixelFormatEnum values
+ *
+ * \sa SDL_PixelFormatEnumToMasks
  */
 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
                                                           Uint32 Rmask,
@@ -369,84 +398,193 @@ extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
                                                           Uint32 Amask);
 
 /**
- *  \brief Create an SDL_PixelFormat structure from a pixel format enum.
+ * Create an SDL_PixelFormat structure corresponding to a pixel format.
+ *
+ * Returned structure may come from a shared global cache (i.e. not newly
+ * allocated), and hence should not be modified, especially the palette. Weird
+ * errors such as `Blit combination not supported` may occur.
+ *
+ * \param pixel_format one of the SDL_PixelFormatEnum values
+ * \returns the new SDL_PixelFormat structure or NULL on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_FreeFormat
  */
 extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format);
 
 /**
- *  \brief Free an SDL_PixelFormat structure.
+ * Free an SDL_PixelFormat structure allocated by SDL_AllocFormat().
+ *
+ * \param format the SDL_PixelFormat structure to free
+ *
+ * \sa SDL_AllocFormat
  */
 extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format);
 
 /**
- *  \brief Create a palette structure with the specified number of color
+ * Create a palette structure with the specified number of color entries.
- *         entries.
  *
- *  \return A new palette, or NULL if there wasn't enough memory.
+ * The palette entries are initialized to white.
  *
- *  \note The palette entries are initialized to white.
+ * \param ncolors represents the number of color entries in the color palette
+ * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if
+ *          there wasn't enough memory); call SDL_GetError() for more
+ *          information.
  *
- *  \sa SDL_FreePalette()
+ * \sa SDL_FreePalette
  */
 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
 
 /**
- *  \brief Set the palette for a pixel format structure.
+ * Set the palette for a pixel format structure.
+ *
+ * \param format the SDL_PixelFormat structure that will use the palette
+ * \param palette the SDL_Palette structure that will be used
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_AllocPalette
+ * \sa SDL_FreePalette
  */
 extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
                                                       SDL_Palette *palette);
 
 /**
- *  \brief Set a range of colors in a palette.
+ * Set a range of colors in a palette.
  *
- *  \param palette    The palette to modify.
+ * \param palette the SDL_Palette structure to modify
- *  \param colors     An array of colors to copy into the palette.
+ * \param colors an array of SDL_Color structures to copy into the palette
- *  \param firstcolor The index of the first palette entry to modify.
+ * \param firstcolor the index of the first palette entry to modify
- *  \param ncolors    The number of entries to modify.
+ * \param ncolors the number of entries to modify
+ * \returns 0 on success or a negative error code if not all of the colors
+ *          could be set; call SDL_GetError() for more information.
  *
- *  \return 0 on success, or -1 if not all of the colors could be set.
+ * \sa SDL_AllocPalette
+ * \sa SDL_CreateRGBSurface
  */
 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
                                                  const SDL_Color * colors,
                                                  int firstcolor, int ncolors);
 
 /**
- *  \brief Free a palette created with SDL_AllocPalette().
+ * Free a palette created with SDL_AllocPalette().
+ *
+ * \param palette the SDL_Palette structure to be freed
  *
- *  \sa SDL_AllocPalette()
+ * \sa SDL_AllocPalette
  */
 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
 
 /**
- *  \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
+ * Map an RGB triple to an opaque pixel value for a given pixel format.
  *
- *  \sa SDL_MapRGBA
+ * This function maps the RGB color value to the specified pixel format and
+ * returns the pixel value best approximating the given RGB color value for
+ * the given pixel format.
+ *
+ * If the format has a palette (8-bit) the index of the closest matching color
+ * in the palette will be returned.
+ *
+ * If the specified pixel format has an alpha component it will be returned as
+ * all 1 bits (fully opaque).
+ *
+ * If the pixel format bpp (color depth) is less than 32-bpp then the unused
+ * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
+ * format the return value can be assigned to a Uint16, and similarly a Uint8
+ * for an 8-bpp format).
+ *
+ * \param format an SDL_PixelFormat structure describing the pixel format
+ * \param r the red component of the pixel in the range 0-255
+ * \param g the green component of the pixel in the range 0-255
+ * \param b the blue component of the pixel in the range 0-255
+ * \returns a pixel value
+ *
+ * \sa SDL_GetRGB
+ * \sa SDL_GetRGBA
+ * \sa SDL_MapRGBA
  */
 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
                                           Uint8 r, Uint8 g, Uint8 b);
 
 /**
- *  \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
+ * Map an RGBA quadruple to a pixel value for a given pixel format.
+ *
+ * This function maps the RGBA color value to the specified pixel format and
+ * returns the pixel value best approximating the given RGBA color value for
+ * the given pixel format.
+ *
+ * If the specified pixel format has no alpha component the alpha value will
+ * be ignored (as it will be in formats with a palette).
+ *
+ * If the format has a palette (8-bit) the index of the closest matching color
+ * in the palette will be returned.
+ *
+ * If the pixel format bpp (color depth) is less than 32-bpp then the unused
+ * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
+ * format the return value can be assigned to a Uint16, and similarly a Uint8
+ * for an 8-bpp format).
  *
- *  \sa SDL_MapRGB
+ * \param format an SDL_PixelFormat structure describing the format of the
+ *               pixel
+ * \param r the red component of the pixel in the range 0-255
+ * \param g the green component of the pixel in the range 0-255
+ * \param b the blue component of the pixel in the range 0-255
+ * \param a the alpha component of the pixel in the range 0-255
+ * \returns a pixel value
+ *
+ * \sa SDL_GetRGB
+ * \sa SDL_GetRGBA
+ * \sa SDL_MapRGB
  */
 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
                                            Uint8 r, Uint8 g, Uint8 b,
                                            Uint8 a);
 
 /**
- *  \brief Get the RGB components from a pixel of the specified format.
+ * Get RGB values from a pixel in the specified format.
+ *
+ * This function uses the entire 8-bit [0..255] range when converting color
+ * components from pixel formats with less than 8-bits per RGB component
+ * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
+ * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
  *
- *  \sa SDL_GetRGBA
+ * \param pixel a pixel value
+ * \param format an SDL_PixelFormat structure describing the format of the
+ *               pixel
+ * \param r a pointer filled in with the red component
+ * \param g a pointer filled in with the green component
+ * \param b a pointer filled in with the blue component
+ *
+ * \sa SDL_GetRGBA
+ * \sa SDL_MapRGB
+ * \sa SDL_MapRGBA
  */
 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
                                         const SDL_PixelFormat * format,
                                         Uint8 * r, Uint8 * g, Uint8 * b);
 
 /**
- *  \brief Get the RGBA components from a pixel of the specified format.
+ * Get RGBA values from a pixel in the specified format.
+ *
+ * This function uses the entire 8-bit [0..255] range when converting color
+ * components from pixel formats with less than 8-bits per RGB component
+ * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
+ * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
  *
- *  \sa SDL_GetRGB
+ * If the surface has no alpha component, the alpha will be returned as 0xff
+ * (100% opaque).
+ *
+ * \param pixel a pixel value
+ * \param format an SDL_PixelFormat structure describing the format of the
+ *               pixel
+ * \param r a pointer filled in with the red component
+ * \param g a pointer filled in with the green component
+ * \param b a pointer filled in with the blue component
+ * \param a a pointer filled in with the alpha component
+ *
+ * \sa SDL_GetRGB
+ * \sa SDL_MapRGB
+ * \sa SDL_MapRGBA
  */
 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
                                          const SDL_PixelFormat * format,
@@ -454,7 +592,12 @@ extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
                                          Uint8 * a);
 
 /**
- *  \brief Calculate a 256 entry gamma ramp for a gamma value.
+ * Calculate a 256 entry gamma ramp for a gamma value.
+ *
+ * \param gamma a gamma value where 0.0 is black and 1.0 is identity
+ * \param ramp an array of 256 values filled in with the gamma ramp
+ *
+ * \sa SDL_SetWindowGammaRamp
  */
 extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
 

dep/msvc/sdl2/include/SDL_platform.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -70,6 +70,27 @@
 /* lets us know what version of Mac OS X we're compiling on */
 #include "AvailabilityMacros.h"
 #include "TargetConditionals.h"
+
+/* Fix building with older SDKs that don't define these
+   See this for more information:
+   https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets
+*/
+#ifndef TARGET_OS_MACCATALYST
+#define TARGET_OS_MACCATALYST 0
+#endif
+#ifndef TARGET_OS_IOS
+#define TARGET_OS_IOS 0
+#endif
+#ifndef TARGET_OS_IPHONE
+#define TARGET_OS_IPHONE 0
+#endif
+#ifndef TARGET_OS_TV
+#define TARGET_OS_TV 0
+#endif
+#ifndef TARGET_OS_SIMULATOR
+#define TARGET_OS_SIMULATOR 0
+#endif
+
 #if TARGET_OS_TV
 #undef __TVOS__
 #define __TVOS__ 1
@@ -175,6 +196,9 @@
 #define __SDL_NOGETPROCADDR__
 #endif
 
+#if defined(__vita__)
+#define __VITA__ 1
+#endif
 
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
@@ -183,7 +207,18 @@ extern "C" {
 #endif
 
 /**
- *  \brief Gets the name of the platform.
+ * Get the name of the platform.
+ *
+ * Here are the names returned for some (but not all) supported platforms:
+ *
+ * - "Windows"
+ * - "Mac OS X"
+ * - "Linux"
+ * - "iOS"
+ * - "Android"
+ *
+ * \returns the name of the platform. If the correct platform name is not
+ *          available, returns a string beginning with the text "Unknown".
  */
 extern DECLSPEC const char * SDLCALL SDL_GetPlatform (void);
 

dep/msvc/sdl2/include/SDL_power.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -37,7 +37,7 @@ extern "C" {
 #endif
 
 /**
- *  \brief The basic state for the system's power supply.
+ *  The basic state for the system's power supply.
  */
 typedef enum
 {
@@ -50,17 +50,28 @@ typedef enum
 
 
 /**
- *  \brief Get the current power supply details.
+ * Get the current power supply details.
  *
- *  \param secs Seconds of battery life left. You can pass a NULL here if
+ * You should never take a battery status as absolute truth. Batteries
- *              you don't care. Will return -1 if we can't determine a
+ * (especially failing batteries) are delicate hardware, and the values
- *              value, or we're not running on a battery.
+ * reported here are best estimates based on what that hardware reports. It's
+ * not uncommon for older batteries to lose stored power much faster than it
+ * reports, or completely drain when reporting it has 20 percent left, etc.
  *
- *  \param pct Percentage of battery life left, between 0 and 100. You can
+ * Battery status can change at any time; if you are concerned with power
- *             pass a NULL here if you don't care. Will return -1 if we
+ * state, you should call this function frequently, and perhaps ignore changes
- *             can't determine a value, or we're not running on a battery.
+ * until they seem to be stable for a few seconds.
  *
- *  \return The state of the battery (if any).
+ * It's possible a platform can only report battery percentage or time left
+ * but not both.
+ *
+ * \param secs seconds of battery life left, you can pass a NULL here if you
+ *             don't care, will return -1 if we can't determine a value, or
+ *             we're not running on a battery
+ * \param pct percentage of battery life left, between 0 and 100, you can pass
+ *            a NULL here if you don't care, will return -1 if we can't
+ *            determine a value, or we're not running on a battery
+ * \returns an SDL_PowerState enum representing the current battery state.
  */
 extern DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *secs, int *pct);
 

dep/msvc/sdl2/include/SDL_quit.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_rect.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -40,10 +40,10 @@ extern "C" {
 #endif
 
 /**
- *  \brief  The structure that defines a point (integer)
+ * The structure that defines a point (integer)
  *
- *  \sa SDL_EnclosePoints
+ * \sa SDL_EnclosePoints
- *  \sa SDL_PointInRect
+ * \sa SDL_PointInRect
  */
 typedef struct SDL_Point
 {
@@ -52,10 +52,10 @@ typedef struct SDL_Point
 } SDL_Point;
 
 /**
- *  \brief  The structure that defines a point (floating point)
+ * The structure that defines a point (floating point)
  *
- *  \sa SDL_EnclosePoints
+ * \sa SDL_EnclosePoints
- *  \sa SDL_PointInRect
+ * \sa SDL_PointInRect
  */
 typedef struct SDL_FPoint
 {
@@ -65,14 +65,14 @@ typedef struct SDL_FPoint
 
 
 /**
- *  \brief A rectangle, with the origin at the upper left (integer).
+ * A rectangle, with the origin at the upper left (integer).
- *
+ *
- *  \sa SDL_RectEmpty
+ * \sa SDL_RectEmpty
- *  \sa SDL_RectEquals
+ * \sa SDL_RectEquals
- *  \sa SDL_HasIntersection
+ * \sa SDL_HasIntersection
- *  \sa SDL_IntersectRect
+ * \sa SDL_IntersectRect
- *  \sa SDL_UnionRect
+ * \sa SDL_UnionRect
- *  \sa SDL_EnclosePoints
+ * \sa SDL_EnclosePoints
  */
 typedef struct SDL_Rect
 {
@@ -82,7 +82,7 @@ typedef struct SDL_Rect
 
 
 /**
- *  \brief A rectangle, with the origin at the upper left (floating point).
+ * A rectangle, with the origin at the upper left (floating point).
  */
 typedef struct SDL_FRect
 {
@@ -94,7 +94,7 @@ typedef struct SDL_FRect
 
 
 /**
- *  \brief Returns true if point resides inside a rectangle.
+ * Returns true if point resides inside a rectangle.
  */
 SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
 {
@@ -103,7 +103,7 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
 }
 
 /**
- *  \brief Returns true if the rectangle has no area.
+ * Returns true if the rectangle has no area.
  */
 SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
 {
@@ -111,7 +111,7 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
 }
 
 /**
- *  \brief Returns true if the two rectangles are equal.
+ * Returns true if the two rectangles are equal.
  */
 SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b)
 {
@@ -120,33 +120,66 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b)
 }
 
 /**
- *  \brief Determine whether two rectangles intersect.
+ * Determine whether two rectangles intersect.
+ *
+ * If either pointer is NULL the function will return SDL_FALSE.
+ *
+ * \param A an SDL_Rect structure representing the first rectangle
+ * \param B an SDL_Rect structure representing the second rectangle
+ * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  *
- *  \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_IntersectRect
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A,
                                                      const SDL_Rect * B);
 
 /**
- *  \brief Calculate the intersection of two rectangles.
+ * Calculate the intersection of two rectangles.
+ *
+ * If `result` is NULL then this function will return SDL_FALSE.
  *
- *  \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
+ * \param A an SDL_Rect structure representing the first rectangle
+ * \param B an SDL_Rect structure representing the second rectangle
+ * \param result an SDL_Rect structure filled in with the intersection of
+ *               rectangles `A` and `B`
+ * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HasIntersection
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A,
                                                    const SDL_Rect * B,
                                                    SDL_Rect * result);
 
 /**
- *  \brief Calculate the union of two rectangles.
+ * Calculate the union of two rectangles.
+ *
+ * \param A an SDL_Rect structure representing the first rectangle
+ * \param B an SDL_Rect structure representing the second rectangle
+ * \param result an SDL_Rect structure filled in with the union of rectangles
+ *               `A` and `B`
  */
 extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A,
                                            const SDL_Rect * B,
                                            SDL_Rect * result);
 
 /**
- *  \brief Calculate a minimal rectangle enclosing a set of points
+ * Calculate a minimal rectangle enclosing a set of points.
  *
- *  \return SDL_TRUE if any points were within the clipping rect
+ * 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
+ * \param count the number of structures in the `points` array
+ * \param clip an SDL_Rect used for clipping or NULL to enclose all points
+ * \param result an SDL_Rect structure filled in with the minimal enclosing
+ *               rectangle
+ * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
+ *          points were outside of the clipping rectangle.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points,
                                                    int count,
@@ -154,9 +187,20 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points,
                                                    SDL_Rect * result);
 
 /**
- *  \brief Calculate the intersection of a rectangle and line segment.
+ * Calculate the intersection of a rectangle and line segment.
+ *
+ * This function is used to clip a line segment to a rectangle. A line segment
+ * contained entirely within the rectangle or that does not intersect will
+ * remain unchanged. A line segment that crosses the rectangle at either or
+ * both ends will be clipped to the boundary of the rectangle and the new
+ * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
  *
- *  \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
+ * \param rect an SDL_Rect structure representing the rectangle to intersect
+ * \param X1 a pointer to the starting X-coordinate of the line
+ * \param Y1 a pointer to the starting Y-coordinate of the line
+ * \param X2 a pointer to the ending X-coordinate of the line
+ * \param Y2 a pointer to the ending Y-coordinate of the line
+ * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRectAndLine(const SDL_Rect *
                                                           rect, int *X1,

dep/msvc/sdl2/include/SDL_revision.h

@@ -1,2 +1,2 @@
-#define SDL_REVISION "hg-12952:bc90ce38f1e2"
+#define SDL_REVISION "https://github.com/libsdl-org/SDL.git@25f9ed87ff6947d9576fc9d79dee0784e638ac58"
-#define SDL_REVISION_NUMBER 12952
+#define SDL_REVISION_NUMBER 0

dep/msvc/sdl2/include/SDL_rwops.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -45,6 +45,9 @@ extern "C" {
 #define SDL_RWOPS_JNIFILE   3U  /**< Android asset */
 #define SDL_RWOPS_MEMORY    4U  /**< Memory stream */
 #define SDL_RWOPS_MEMORY_RO 5U  /**< Read-Only memory stream */
+#if defined(__VITA__)
+#define SDL_RWOPS_VITAFILE  6U  /**< Vita file */
+#endif
 
 /**
  * This is the read/write operation structure -- very basic.
@@ -96,15 +99,7 @@ typedef struct SDL_RWops
 #if defined(__ANDROID__)
         struct
         {
-            void *fileNameRef;
+            void *asset;
-            void *inputStreamRef;
-            void *readableByteChannelRef;
-            void *readMethod;
-            void *assetFileDescriptorRef;
-            long position;
-            long size;
-            long offset;
-            int fd;
         } androidio;
 #elif defined(__WIN32__)
         struct
@@ -118,6 +113,17 @@ typedef struct SDL_RWops
                 size_t left;
             } buffer;
         } windowsio;
+#elif defined(__VITA__)
+        struct
+        {
+            int h;
+            struct
+            {
+                void *data;
+                size_t size;
+                size_t left;
+            } buffer;
+        } vitaio;
 #endif
 
 #ifdef HAVE_STDIO_H
@@ -176,77 +182,192 @@ extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
 #define RW_SEEK_END 2       /**< Seek relative to the end of data */
 
 /**
- *  Return the size of the file in this rwops, or -1 if unknown
+ * Use this macro to get the size of the data stream in an SDL_RWops.
+ *
+ * \param context the SDL_RWops to get the size of the data stream from
+ * \returns the size of the data stream in the SDL_RWops on success, -1 if
+ *          unknown or a negative error code on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
 
 /**
- *  Seek to \c offset relative to \c whence, one of stdio's whence values:
+ * Seek within an SDL_RWops data stream.
- *  RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
+ *
+ * This function seeks to byte `offset`, relative to `whence`.
+ *
+ * `whence` may be any of the following values:
+ *
+ * - `RW_SEEK_SET`: seek from the beginning of data
+ * - `RW_SEEK_CUR`: seek relative to current read point
+ * - `RW_SEEK_END`: seek relative to the end of data
+ *
+ * If this stream can not seek, it will return -1.
+ *
+ * SDL_RWseek() is actually a wrapper function that calls the SDL_RWops's
+ * `seek` method appropriately, to simplify application development.
+ *
+ * \param context a pointer to an SDL_RWops structure
+ * \param offset an offset in bytes, relative to **whence** location; can be
+ *               negative
+ * \param whence any of `RW_SEEK_SET`, `RW_SEEK_CUR`, `RW_SEEK_END`
+ * \returns the final offset in the data stream after the seek or -1 on error.
  *
- *  \return the final offset in the data stream, or -1 on error.
+ * \sa SDL_RWclose
+ * \sa SDL_RWFromConstMem
+ * \sa SDL_RWFromFile
+ * \sa SDL_RWFromFP
+ * \sa SDL_RWFromMem
+ * \sa SDL_RWread
+ * \sa SDL_RWtell
+ * \sa SDL_RWwrite
  */
 extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context,
                                           Sint64 offset, int whence);
 
 /**
- *  Return the current offset in the data stream, or -1 on error.
+ * 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
+ * application development.
+ *
+ * \param context a SDL_RWops data stream object from which to get the current
+ *                offset
+ * \returns the current offset in the stream, or -1 if the information can not
+ *          be determined.
+ *
+ * \sa SDL_RWclose
+ * \sa SDL_RWFromConstMem
+ * \sa SDL_RWFromFile
+ * \sa SDL_RWFromFP
+ * \sa SDL_RWFromMem
+ * \sa SDL_RWread
+ * \sa SDL_RWseek
+ * \sa SDL_RWwrite
  */
 extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context);
 
 /**
- *  Read up to \c maxnum objects each of size \c size from the data
+ * Read from a data source.
- *  stream to the area pointed at by \c ptr.
+ *
+ * This function reads up to `maxnum` objects each of size `size` from the
+ * data source to the area pointed at by `ptr`. This function may read less
+ * objects than requested. It will return zero when there has been an error or
+ * the data stream is completely read.
+ *
+ * SDL_RWread() is actually a function wrapper that calls the SDL_RWops's
+ * `read` method appropriately, to simplify application development.
  *
- *  \return the number of objects read, or 0 at error or end of file.
+ * \param context a pointer to an SDL_RWops structure
+ * \param ptr a pointer to a buffer to read data into
+ * \param size the size of each object to read, in bytes
+ * \param maxnum the maximum number of objects to be read
+ * \returns the number of objects read, or 0 at error or end of file; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_RWclose
+ * \sa SDL_RWFromConstMem
+ * \sa SDL_RWFromFile
+ * \sa SDL_RWFromFP
+ * \sa SDL_RWFromMem
+ * \sa SDL_RWseek
+ * \sa SDL_RWwrite
  */
 extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context,
-                                          void *ptr, size_t size, size_t maxnum);
+                                          void *ptr, size_t size,
+                                          size_t maxnum);
 
 /**
- *  Write exactly \c num objects each of size \c size from the area
+ * Write to an SDL_RWops data stream.
- *  pointed at by \c ptr to 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`.
+ *
+ * SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's
+ * `write` method appropriately, to simplify application development.
+ *
+ * \param context a pointer to an SDL_RWops structure
+ * \param ptr a pointer to a buffer containing data to write
+ * \param size the size of an object to write, in bytes
+ * \param num the number of objects to write
+ * \returns the number of objects written, which will be less than **num** on
+ *          error; call SDL_GetError() for more information.
  *
- *  \return the number of objects written, or 0 at error or end of file.
+ * \sa SDL_RWclose
+ * \sa SDL_RWFromConstMem
+ * \sa SDL_RWFromFile
+ * \sa SDL_RWFromFP
+ * \sa SDL_RWFromMem
+ * \sa SDL_RWread
+ * \sa SDL_RWseek
  */
 extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context,
-                                           const void *ptr, size_t size, size_t num);
+                                           const void *ptr, size_t size,
+                                           size_t num);
 
 /**
- *  Close and free an allocated SDL_RWops structure.
+ * Close and free an allocated SDL_RWops structure.
  *
- *  \return 0 if successful or -1 on write error when flushing data.
+ * SDL_RWclose() closes and cleans up the SDL_RWops stream. It releases any
+ * resources used by the stream and frees the SDL_RWops itself with
+ * SDL_FreeRW(). This returns 0 on success, or -1 if the stream failed to
+ * flush to its output (e.g. to disk).
+ *
+ * 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.
+ *
+ * \param context SDL_RWops structure to close
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_RWFromConstMem
+ * \sa SDL_RWFromFile
+ * \sa SDL_RWFromFP
+ * \sa SDL_RWFromMem
+ * \sa SDL_RWread
+ * \sa SDL_RWseek
+ * \sa SDL_RWwrite
  */
 extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context);
 
 /**
- *  Load all the data from an SDL data stream.
+ * Load all the data from an SDL data stream.
  *
- *  The data is allocated with a zero byte at the end (null terminated)
+ * The data is allocated with a zero byte at the end (null terminated) for
+ * convenience. This extra byte is not included in the value reported via
+ * `datasize`.
  *
- *  If \c datasize is not NULL, it is filled with the size of the data read.
+ * The data should be freed with SDL_free().
  *
- *  If \c freesrc is non-zero, the stream will be closed after being read.
+ * \param src the SDL_RWops to read all available data from
- *
+ * \param datasize if not NULL, will store the number of bytes read
- *  The data should be freed with SDL_free().
+ * \param freesrc if non-zero, calls SDL_RWclose() on `src` before returning
- *
+ * \returns the data, or NULL if there was an error.
- *  \return the data, or NULL if there was an error.
  */
-extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops * src, size_t *datasize,
+extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops *src,
-                                                    int freesrc);
+                                              size_t *datasize,
+                                              int freesrc);
 
 /**
- *  Load an entire file.
+ * Load all the data from a file path.
- *
- *  The data is allocated with a zero byte at the end (null terminated)
- *
- *  If \c datasize is not NULL, it is filled with the size of the data read.
  *
- *  If \c freesrc is non-zero, the stream will be closed after being read.
+ * The data is allocated with a zero byte at the end (null terminated) for
+ * convenience. This extra byte is not included in the value reported via
+ * `datasize`.
  *
- *  The data should be freed with SDL_free().
+ * The data should be freed with SDL_free().
  *
- *  \return the data, or NULL if there was an error.
+ * \param file the path to read all available data from
+ * \param datasize if not NULL, will store the number of bytes read
+ * \returns the data, or NULL if there was an error.
  */
 extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize);
 

dep/msvc/sdl2/include/SDL_scancode.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_sensor.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -78,14 +78,16 @@ typedef enum
  * Accelerometer sensor
  *
  * The accelerometer returns the current acceleration in SI meters per
- * second squared. This includes gravity, so a device at rest will have
+ * second squared. This measurement includes the force of gravity, so
- * an acceleration of SDL_STANDARD_GRAVITY straight down.
+ * a device at rest will have an value of SDL_STANDARD_GRAVITY away
+ * from the center of the earth.
  *
  * values[0]: Acceleration on the x axis
  * values[1]: Acceleration on the y axis
  * values[2]: Acceleration on the z axis
  *
- * For phones held in portrait mode, the axes are defined as follows:
+ * For phones held in portrait mode and game controllers held in front of you,
+ * the axes are defined as follows:
  * -X ... +X : left ... right
  * -Y ... +Y : bottom ... top
  * -Z ... +Z : farther ... closer
@@ -105,16 +107,17 @@ typedef enum
  * see positive rotation on that axis when it appeared to be rotating
  * counter-clockwise.
  *
- * values[0]: Angular speed around the x axis
+ * values[0]: Angular speed around the x axis (pitch)
- * values[1]: Angular speed around the y axis
+ * values[1]: Angular speed around the y axis (yaw)
- * values[2]: Angular speed around the z axis
+ * values[2]: Angular speed around the z axis (roll)
  *
- * For phones held in portrait mode, the axes are defined as follows:
+ * For phones held in portrait mode and game controllers held in front of you,
+ * the axes are defined as follows:
  * -X ... +X : left ... right
  * -Y ... +Y : bottom ... top
  * -Z ... +Z : farther ... closer
  * 
- * The axis data is not changed when the phone is rotated.
+ * The axis data is not changed when the phone or controller is rotated.
  *
  * \sa SDL_GetDisplayOrientation()
  */
@@ -122,118 +125,135 @@ typedef enum
 /* Function prototypes */
 
 /**
- *  \brief Count the number of sensors attached to the system right now
+ * Locking for multi-threaded access to the sensor API
+ *
+ * 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.
+ */
+extern DECLSPEC void SDLCALL SDL_LockSensors(void);
+extern DECLSPEC void SDLCALL SDL_UnlockSensors(void);
+
+/**
+ * Count the number of sensors attached to the system right now.
+ *
+ * \returns the number of sensors detected.
  */
 extern DECLSPEC int SDLCALL SDL_NumSensors(void);
 
 /**
- *  \brief Get the implementation dependent name of a sensor.
+ * Get the implementation dependent name of a sensor.
  *
- *  This can be called before any sensors are opened.
+ * \param device_index The sensor to obtain name from
- * 
+ * \returns the sensor name, or NULL if `device_index` is out of range.
- *  \return The sensor name, or NULL if device_index is out of range.
  */
 extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index);
 
 /**
- *  \brief Get the type of a sensor.
+ * Get the type of a sensor.
- *
- *  This can be called before any sensors are opened.
  *
- *  \return The sensor type, or SDL_SENSOR_INVALID if device_index is out of range.
+ * \param device_index The sensor to get the type from
+ * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `device_index` is
+ *          out of range.
  */
 extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index);
 
 /**
- *  \brief Get the platform dependent type of a sensor.
+ * Get the platform dependent type of a sensor.
  *
- *  This can be called before any sensors are opened.
+ * \param device_index The sensor to check
- *
+ * \returns the sensor platform dependent type, or -1 if `device_index` is out
- *  \return The sensor platform dependent type, or -1 if device_index is out of range.
+ *          of range.
  */
 extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index);
 
 /**
- *  \brief Get the instance ID of a sensor.
+ * Get the instance ID of a sensor.
- *
- *  This can be called before any sensors are opened.
  *
- *  \return The sensor instance ID, or -1 if device_index is out of range.
+ * \param device_index The sensor to get instance id from
+ * \returns the sensor instance ID, or -1 if `device_index` is out of range.
  */
 extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_index);
 
 /**
- *  \brief Open a sensor for use.
+ * Open a sensor for use.
- *
- *  The index passed as an argument refers to the N'th sensor on the system.
  *
- *  \return A sensor identifier, or NULL if an error occurred.
+ * \param device_index The sensor to open
+ * \returns an SDL_Sensor sensor object, or NULL if an error occurred.
  */
 extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorOpen(int device_index);
 
 /**
  * Return the SDL_Sensor associated with an instance id.
+ *
+ * \param instance_id The sensor from instance id
+ * \returns an SDL_Sensor object.
  */
 extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instance_id);
 
 /**
- *  \brief Get the implementation dependent name of a sensor.
+ * Get the implementation dependent name of a sensor
  *
- *  \return The sensor name, or NULL if the sensor is NULL.
+ * \param sensor The SDL_Sensor object
+ * \returns the sensor name, or NULL if `sensor` is NULL.
  */
 extern DECLSPEC const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor);
 
 /**
- *  \brief Get the type of a sensor.
+ * Get the type of a sensor.
- *
- *  This can be called before any sensors are opened.
  *
- *  \return The sensor type, or SDL_SENSOR_INVALID if the sensor is NULL.
+ * \param sensor The SDL_Sensor object to inspect
+ * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is
+ *          NULL.
  */
 extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(SDL_Sensor *sensor);
 
 /**
- *  \brief Get the platform dependent type of a sensor.
+ * Get the platform dependent type of a sensor.
  *
- *  This can be called before any sensors are opened.
+ * \param sensor The SDL_Sensor object to inspect
- *
+ * \returns the sensor platform dependent type, or -1 if `sensor` is NULL.
- *  \return The sensor platform dependent type, or -1 if the sensor is NULL.
  */
 extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(SDL_Sensor *sensor);
 
 /**
- *  \brief Get the instance ID of a sensor.
+ * Get the instance ID of a sensor.
- *
- *  This can be called before any sensors are opened.
  *
- *  \return The sensor instance ID, or -1 if the sensor is NULL.
+ * \param sensor The SDL_Sensor object to inspect
+ * \returns the sensor instance ID, or -1 if `sensor` is NULL.
  */
 extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor);
 
 /**
- *  Get the current state of an opened 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 sensor to query
+ * \param sensor The SDL_Sensor object to query
- *  \param data A pointer filled with the current sensor state
+ * \param data A pointer filled with the current sensor state
- *  \param num_values The number of values to write to data
+ * \param num_values The number of values to write to data
- *
+ * \returns 0 or -1 if an error occurred.
- *  \return 0 or -1 if an error occurred.
  */
 extern DECLSPEC int SDLCALL SDL_SensorGetData(SDL_Sensor * sensor, float *data, int num_values);
 
 /**
- *  Close a sensor previously opened with SDL_SensorOpen()
+ * Close a sensor previously opened with SDL_SensorOpen().
+ *
+ * \param sensor The SDL_Sensor object to close
  */
 extern DECLSPEC void SDLCALL SDL_SensorClose(SDL_Sensor * sensor);
 
 /**
- *  Update the current state of the open sensors.
+ * Update the current state of the open sensors.
  *
- *  This is called automatically by the event loop if sensor events are enabled.
+ * This is called automatically by the event loop if sensor events are
+ * enabled.
  *
- *  This needs to be called from the thread that initialized the sensor subsystem.
+ * This needs to be called from the thread that initialized the sensor
+ * subsystem.
  */
 extern DECLSPEC void SDLCALL SDL_SensorUpdate(void);
 

dep/msvc/sdl2/include/SDL_shape.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -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 title The title of the window, in UTF-8 encoding.
- *  \param x     The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
+ * \param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
- *               ::SDL_WINDOWPOS_UNDEFINED.
+ *          ::SDL_WINDOWPOS_UNDEFINED.
- *  \param y     The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
+ * \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
- *               ::SDL_WINDOWPOS_UNDEFINED.
+ *          ::SDL_WINDOWPOS_UNDEFINED.
- *  \param w     The width of the window.
+ * \param w The width of the window.
- *  \param h     The height 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:
+ * \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with
- *               ::SDL_WINDOW_OPENGL,     ::SDL_WINDOW_INPUT_GRABBED,
+ *              any of the following: ::SDL_WINDOW_OPENGL,
- *               ::SDL_WINDOW_HIDDEN,     ::SDL_WINDOW_RESIZABLE,
+ *              ::SDL_WINDOW_INPUT_GRABBED, ::SDL_WINDOW_HIDDEN,
- *               ::SDL_WINDOW_MAXIMIZED,  ::SDL_WINDOW_MINIMIZED,
+ *              ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED,
- *       ::SDL_WINDOW_BORDERLESS is always set, and ::SDL_WINDOW_FULLSCREEN is always unset.
+ *              ::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
- * \return SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if the window is unshaped or NULL.
+ *         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
- * \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape argument, or SDL_NONSHAPEABLE_WINDOW
+ *         argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
- *           if the SDL_Window given does not reference a valid shaped window.
+ *         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.
+ * \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
+ * \return 0 if the window has a shape and, provided shape_mode was not NULL,
- *           data, SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped window, or SDL_WINDOW_LACKS_SHAPE if
+ *         shape_mode has been filled with the mode data,
- *           the SDL_Window given is a shapeable window currently lacking a shape.
+ *         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

dep/msvc/sdl2/include/SDL_stdinc.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -30,6 +30,12 @@
 
 #include "SDL_config.h"
 
+#ifdef __APPLE__
+#ifndef _DARWIN_C_SOURCE
+#define _DARWIN_C_SOURCE 1 /* for memset_pattern4() */
+#endif
+#endif
+
 #ifdef HAVE_SYS_TYPES_H
 #include <sys/types.h>
 #endif
@@ -217,7 +223,7 @@ typedef uint64_t Uint64;
 
 /* @} *//* Basic data types */
 
-/* Make sure we have macros for printing 64 bit values.
+/* Make sure we have macros for printing width-based integers.
  * <stdint.h> should define these but this is not true all platforms.
  * (for example win32) */
 #ifndef SDL_PRIs64
@@ -264,6 +270,34 @@ typedef uint64_t Uint64;
 #define SDL_PRIX64 "llX"
 #endif
 #endif
+#ifndef SDL_PRIs32
+#ifdef PRId32
+#define SDL_PRIs32 PRId32
+#else
+#define SDL_PRIs32 "d"
+#endif
+#endif
+#ifndef SDL_PRIu32
+#ifdef PRIu32
+#define SDL_PRIu32 PRIu32
+#else
+#define SDL_PRIu32 "u"
+#endif
+#endif
+#ifndef SDL_PRIx32
+#ifdef PRIx32
+#define SDL_PRIx32 PRIx32
+#else
+#define SDL_PRIx32 "x"
+#endif
+#endif
+#ifndef SDL_PRIX32
+#ifdef PRIX32
+#define SDL_PRIX32 PRIX32
+#else
+#define SDL_PRIX32 "X"
+#endif
+#endif
 
 /* Annotations to help code analysis tools */
 #ifdef SDL_DISABLE_ANALYZE_MACROS
@@ -332,7 +366,7 @@ SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8);
 
 /** \cond */
 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
-#if !defined(__ANDROID__)
+#if !defined(__ANDROID__) && !defined(__VITA__)
    /* TODO: include/SDL_stdinc.h:174: error: size of array 'SDL_dummy_enum' is negative */
 typedef enum
 {
@@ -369,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,
@@ -377,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
+ * 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.
  */
 extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
                                                    SDL_calloc_func calloc_func,
@@ -390,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);
 
@@ -406,20 +435,35 @@ extern DECLSPEC int SDLCALL SDL_abs(int x);
 #define SDL_min(x, y) (((x) < (y)) ? (x) : (y))
 #define SDL_max(x, y) (((x) > (y)) ? (x) : (y))
 
+extern DECLSPEC int SDLCALL SDL_isalpha(int x);
+extern DECLSPEC int SDLCALL SDL_isalnum(int x);
+extern DECLSPEC int SDLCALL SDL_isblank(int x);
+extern DECLSPEC int SDLCALL SDL_iscntrl(int x);
 extern DECLSPEC int SDLCALL SDL_isdigit(int x);
+extern DECLSPEC int SDLCALL SDL_isxdigit(int x);
+extern DECLSPEC int SDLCALL SDL_ispunct(int x);
 extern DECLSPEC int SDLCALL SDL_isspace(int x);
+extern DECLSPEC int SDLCALL SDL_isupper(int x);
+extern DECLSPEC int SDLCALL SDL_islower(int x);
+extern DECLSPEC int SDLCALL SDL_isprint(int x);
+extern DECLSPEC int SDLCALL SDL_isgraph(int x);
 extern DECLSPEC int SDLCALL SDL_toupper(int x);
 extern DECLSPEC int SDLCALL SDL_tolower(int x);
 
+extern DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t len);
+
 extern DECLSPEC void *SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len);
 
 #define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x)))
 #define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x)))
+#define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x)))
 
 /* Note that memset() is a byte assignment and this is a 32-bit assignment, so they're not directly equivalent. */
 SDL_FORCE_INLINE void SDL_memset4(void *dst, Uint32 val, size_t dwords)
 {
-#if defined(__GNUC__) && defined(i386)
+#ifdef __APPLE__
+    memset_pattern4(dst, &val, dwords * 4);
+#elif defined(__GNUC__) && defined(__i386__)
     int u0, u1, u2;
     __asm__ __volatile__ (
         "cld \n\t"
@@ -432,16 +476,28 @@ SDL_FORCE_INLINE void SDL_memset4(void *dst, Uint32 val, size_t dwords)
     size_t _n = (dwords + 3) / 4;
     Uint32 *_p = SDL_static_cast(Uint32 *, dst);
     Uint32 _val = (val);
-    if (dwords == 0)
+    if (dwords == 0) {
         return;
-    switch (dwords % 4)
+    }
-    {
+
+    /* !!! FIXME: there are better ways to do this, but this is just to clean this up for now. */
+    #ifdef __clang__
+    #pragma clang diagnostic push
+    #pragma clang diagnostic ignored "-Wimplicit-fallthrough"
+    #endif
+
+    switch (dwords % 4) {
         case 0: do {    *_p++ = _val;   /* fallthrough */
         case 3:         *_p++ = _val;   /* fallthrough */
         case 2:         *_p++ = _val;   /* fallthrough */
         case 1:         *_p++ = _val;   /* fallthrough */
         } while ( --_n );
     }
+
+    #ifdef __clang__
+    #pragma clang diagnostic pop
+    #endif
+
 #endif
 }
 
@@ -450,11 +506,16 @@ extern DECLSPEC void *SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_
 extern DECLSPEC void *SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len);
 extern DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len);
 
-extern DECLSPEC wchar_t *SDLCALL SDL_wcsdup(const wchar_t *wstr);
 extern DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr);
 extern DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen);
 extern DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen);
+extern DECLSPEC wchar_t *SDLCALL SDL_wcsdup(const wchar_t *wstr);
+extern DECLSPEC wchar_t *SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle);
+
 extern DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2);
+extern DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen);
+extern DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2);
+extern DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t len);
 
 extern DECLSPEC size_t SDLCALL SDL_strlen(const char *str);
 extern DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen);
@@ -467,6 +528,7 @@ extern DECLSPEC char *SDLCALL SDL_strlwr(char *str);
 extern DECLSPEC char *SDLCALL SDL_strchr(const char *str, int c);
 extern DECLSPEC char *SDLCALL SDL_strrchr(const char *str, int c);
 extern DECLSPEC char *SDLCALL SDL_strstr(const char *haystack, const char *needle);
+extern DECLSPEC char *SDLCALL SDL_strtokr(char *s1, const char *s2, char **saveptr);
 extern DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str);
 
 extern DECLSPEC char *SDLCALL SDL_itoa(int value, char *str, int radix);
@@ -520,6 +582,8 @@ extern DECLSPEC double SDLCALL SDL_fabs(double x);
 extern DECLSPEC float SDLCALL SDL_fabsf(float x);
 extern DECLSPEC double SDLCALL SDL_floor(double x);
 extern DECLSPEC float SDLCALL SDL_floorf(float x);
+extern DECLSPEC double SDLCALL SDL_trunc(double x);
+extern DECLSPEC float SDLCALL SDL_truncf(float x);
 extern DECLSPEC double SDLCALL SDL_fmod(double x, double y);
 extern DECLSPEC float SDLCALL SDL_fmodf(float x, float y);
 extern DECLSPEC double SDLCALL SDL_log(double x);
@@ -528,6 +592,10 @@ extern DECLSPEC double SDLCALL SDL_log10(double x);
 extern DECLSPEC float SDLCALL SDL_log10f(float x);
 extern DECLSPEC double SDLCALL SDL_pow(double x, double y);
 extern DECLSPEC float SDLCALL SDL_powf(float x, float y);
+extern DECLSPEC double SDLCALL SDL_round(double x);
+extern DECLSPEC float SDLCALL SDL_roundf(float x);
+extern DECLSPEC long SDLCALL SDL_lround(double x);
+extern DECLSPEC long SDLCALL SDL_lroundf(float x);
 extern DECLSPEC double SDLCALL SDL_scalbn(double x, int n);
 extern DECLSPEC float SDLCALL SDL_scalbnf(float x, int n);
 extern DECLSPEC double SDLCALL SDL_sin(double x);
@@ -552,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
+ * This function converts a string between encodings in one pass, returning a
- *  string that must be freed with SDL_free() or NULL on error.
+ * 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,
@@ -566,6 +634,17 @@ extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode,
 /* force builds using Clang's static analysis tools to use literal C runtime
    here, since there are possibly tests that are ineffective otherwise. */
 #if defined(__clang_analyzer__) && !defined(SDL_DISABLE_ANALYZE_MACROS)
+
+/* The analyzer knows about strlcpy even when the system doesn't provide it */
+#ifndef HAVE_STRLCPY
+size_t strlcpy(char* dst, const char* src, size_t size);
+#endif
+
+/* The analyzer knows about strlcat even when the system doesn't provide it */
+#ifndef HAVE_STRLCAT
+size_t strlcat(char* dst, const char* src, size_t size);
+#endif
+
 #define SDL_malloc malloc
 #define SDL_calloc calloc
 #define SDL_realloc realloc
@@ -574,15 +653,23 @@ extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode,
 #define SDL_memcpy memcpy
 #define SDL_memmove memmove
 #define SDL_memcmp memcmp
-#define SDL_strlen strlen
 #define SDL_strlcpy strlcpy
 #define SDL_strlcat strlcat
+#define SDL_strlen strlen
+#define SDL_wcslen wcslen
+#define SDL_wcslcpy wcslcpy
+#define SDL_wcslcat wcslcat
 #define SDL_strdup strdup
+#define SDL_wcsdup wcsdup
 #define SDL_strchr strchr
 #define SDL_strrchr strrchr
 #define SDL_strstr strstr
+#define SDL_wcsstr wcsstr
+#define SDL_strtokr strtok_r
 #define SDL_strcmp strcmp
+#define SDL_wcscmp wcscmp
 #define SDL_strncmp strncmp
+#define SDL_wcsncmp wcsncmp
 #define SDL_strcasecmp strcasecmp
 #define SDL_strncasecmp strncasecmp
 #define SDL_sscanf sscanf

dep/msvc/sdl2/include/SDL_surface.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -80,7 +80,9 @@ typedef struct SDL_Surface
 
     /** information needed for surfaces requiring locks */
     int locked;                 /**< Read-only */
-    void *lock_data;            /**< Read-only */
+
+    /** list of BlitMap that hold a reference to this surface */
+    void *list_blitmap;         /**< Private */
 
     /** clipping information */
     SDL_Rect clip_rect;         /**< Read-only */
@@ -110,31 +112,101 @@ typedef enum
 } SDL_YUV_CONVERSION_MODE;
 
 /**
- *  Allocate and free an RGB surface.
+ * Allocate a new RGB surface.
+ *
+ * If `depth` is 4 or 8 bits, an empty palette is allocated for the surface.
+ * If `depth` is greater than 8 bits, the pixel format is set using the
+ * [RGBA]mask parameters.
+ *
+ * The [RGBA]mask parameters are the bitmasks used to extract that color from
+ * a pixel. For instance, `Rmask` being 0xFF000000 means the red data is
+ * stored in the most significant byte. Using zeros for the RGB masks sets a
+ * default value, based on the depth. For example:
+ *
+ * ```c++
+ * SDL_CreateRGBSurface(0,w,h,32,0,0,0,0);
+ * ```
+ *
+ * However, using zero for the Amask results in an Amask of 0.
+ *
+ * By default surfaces with an alpha mask are set up for blending as with:
+ *
+ * ```c++
+ * SDL_SetSurfaceBlendMode(surface, SDL_BLENDMODE_BLEND)
+ * ```
  *
- *  If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
+ * You can change this by calling SDL_SetSurfaceBlendMode() and selecting a
- *  If the depth is greater than 8 bits, the pixel format is set using the
+ * different `blendMode`.
- *  flags '[RGB]mask'.
  *
- *  If the function runs out of memory, it will return NULL.
+ * \param flags the flags are unused and should be set to 0
+ * \param width the width of the surface
+ * \param height the height of the surface
+ * \param depth the depth of the surface in bits
+ * \param Rmask the red mask for the pixels
+ * \param Gmask the green mask for the pixels
+ * \param Bmask the blue mask for the pixels
+ * \param Amask the alpha mask for the pixels
+ * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ *          call SDL_GetError() for more information.
  *
- *  \param flags The \c flags are obsolete and should be set to 0.
+ * \sa SDL_CreateRGBSurfaceFrom
- *  \param width The width in pixels of the surface to create.
+ * \sa SDL_CreateRGBSurfaceWithFormat
- *  \param height The height in pixels of the surface to create.
+ * \sa SDL_FreeSurface
- *  \param depth The depth in bits of the surface to create.
- *  \param Rmask The red mask of the surface to create.
- *  \param Gmask The green mask of the surface to create.
- *  \param Bmask The blue mask of the surface to create.
- *  \param Amask The alpha mask of the surface to create.
  */
 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
     (Uint32 flags, int width, int height, int depth,
      Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
 
+
 /* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */
+/**
+ * Allocate a new RGB surface with a specific pixel format.
+ *
+ * This function operates mostly like SDL_CreateRGBSurface(), except instead
+ * of providing pixel color masks, you provide it with a predefined format
+ * from SDL_PixelFormatEnum.
+ *
+ * \param flags the flags are unused and should be set to 0
+ * \param width the width of the surface
+ * \param height the height of the surface
+ * \param depth the depth of the surface in bits
+ * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
+ * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ *          call SDL_GetError() for more information.
+ *
+ * \sa SDL_CreateRGBSurface
+ * \sa SDL_CreateRGBSurfaceFrom
+ * \sa SDL_FreeSurface
+ */
 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat
     (Uint32 flags, int width, int height, int depth, Uint32 format);
 
+/**
+ * Allocate a new RGB surface with existing pixel data.
+ *
+ * This function operates mostly like SDL_CreateRGBSurface(), except it does
+ * 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.
+ *
+ * \param pixels a pointer to existing pixel data
+ * \param width the width of the surface
+ * \param height the height of the surface
+ * \param depth the depth of the surface in bits
+ * \param pitch the pitch of the surface in bytes
+ * \param Rmask the red mask for the pixels
+ * \param Gmask the green mask for the pixels
+ * \param Bmask the blue mask for the pixels
+ * \param Amask the alpha mask for the pixels
+ * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ *          call SDL_GetError() for more information.
+ *
+ * \sa SDL_CreateRGBSurface
+ * \sa SDL_CreateRGBSurfaceWithFormat
+ * \sa SDL_FreeSurface
+ */
 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
                                                               int width,
                                                               int height,
@@ -144,74 +216,133 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
                                                               Uint32 Gmask,
                                                               Uint32 Bmask,
                                                               Uint32 Amask);
+
+/* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */
+/**
+ * Allocate a new RGB surface with with a specific pixel format and existing
+ * pixel data.
+ *
+ * This function operates mostly like SDL_CreateRGBSurfaceFrom(), except
+ * 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.
+ *
+ * \param pixels a pointer to existing pixel data
+ * \param width the width of the surface
+ * \param height the height of the surface
+ * \param depth the depth of the surface in bits
+ * \param pitch the pitch of the surface in bytes
+ * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
+ * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ *          call SDL_GetError() for more information.
+ *
+ * \sa SDL_CreateRGBSurfaceFrom
+ * \sa SDL_CreateRGBSurfaceWithFormat
+ * \sa SDL_FreeSurface
+ */
 extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormatFrom
     (void *pixels, int width, int height, int depth, int pitch, Uint32 format);
+
+/**
+ * Free an RGB surface.
+ *
+ * It is safe to pass NULL to this function.
+ *
+ * \param surface the SDL_Surface to free.
+ *
+ * \sa SDL_CreateRGBSurface
+ * \sa SDL_CreateRGBSurfaceFrom
+ * \sa SDL_LoadBMP
+ * \sa SDL_LoadBMP_RW
+ */
 extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
 
 /**
- *  \brief Set the palette used by a surface.
+ * Set the palette used by a surface.
  *
- *  \return 0, or -1 if the surface format doesn't use a palette.
+ * A single palette can be shared with many surfaces.
  *
- *  \note A single palette can be shared with many surfaces.
+ * \param surface the SDL_Surface structure to update
+ * \param palette the SDL_Palette structure to use
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  */
 extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
                                                   SDL_Palette * palette);
 
 /**
- *  \brief Sets up a surface for directly accessing the pixels.
+ * Set up a surface for directly accessing the pixels.
- *
- *  Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write
- *  to and read from \c surface->pixels, using the pixel format stored in
- *  \c surface->format.  Once you are done accessing the surface, you should
- *  use SDL_UnlockSurface() to release it.
  *
- *  Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
+ * Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write to
- *  to 0, then you can read and write to the surface at any time, and the
+ * and read from `surface->pixels`, using the pixel format stored in
- *  pixel format of the surface will not change.
+ * `surface->format`. Once you are done accessing the surface, you should use
+ * SDL_UnlockSurface() to release it.
  *
- *  No operating system or library calls should be made between lock/unlock
+ * Not all surfaces require locking. If `SDL_MUSTLOCK(surface)` evaluates to
- *  pairs, as critical system locks may be held during this time.
+ * 0, then you can read and write to the surface at any time, and the pixel
+ * format of the surface will not change.
  *
- *  SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
+ * \param surface the SDL_Surface structure to be locked
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_UnlockSurface()
+ * \sa SDL_MUSTLOCK
+ * \sa SDL_UnlockSurface
  */
 extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
-/** \sa SDL_LockSurface() */
+
+/**
+ * Release a surface after directly accessing the pixels.
+ *
+ * \param surface the SDL_Surface structure to be unlocked
+ *
+ * \sa SDL_LockSurface
+ */
 extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
 
 /**
- *  Load a surface from a seekable SDL data stream (memory or file).
+ * Load a BMP image from a seekable SDL data stream.
  *
- *  If \c freesrc is non-zero, the stream will be closed after being read.
+ * The new surface should be freed with SDL_FreeSurface().
  *
- *  The new surface should be freed with SDL_FreeSurface().
+ * \param src the data stream for the surface
+ * \param freesrc non-zero to close the stream after being read
+ * \returns a pointer to a new SDL_Surface structure or NULL if there was an
+ *          error; call SDL_GetError() for more information.
  *
- *  \return the new surface, or NULL if there was an error.
+ * \sa SDL_FreeSurface
+ * \sa SDL_LoadBMP
+ * \sa SDL_SaveBMP_RW
  */
 extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
                                                     int freesrc);
 
 /**
- *  Load a surface from a file.
+ * Load a surface from a file.
  *
- *  Convenience macro.
+ * Convenience macro.
  */
 #define SDL_LoadBMP(file)   SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
 
 /**
- *  Save a surface to a seekable SDL data stream (memory or file).
+ * Save a surface to a seekable SDL data stream in BMP format.
  *
- *  Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the
+ * Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the
- *  BMP directly. Other RGB formats with 8-bit or higher get converted to a
+ * BMP directly. Other RGB formats with 8-bit or higher get converted to a
- *  24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit
+ * 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit
- *  surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
+ * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
- *  not supported.
+ * not supported.
  *
- *  If \c freedst is non-zero, the stream will be closed after being written.
+ * \param surface the SDL_Surface structure containing the image to be saved
+ * \param dst a data stream to save to
+ * \param freedst non-zero to close the stream after being written
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \return 0 if successful or -1 if there was an error.
+ * \sa SDL_LoadBMP_RW
+ * \sa SDL_SaveBMP
  */
 extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
     (SDL_Surface * surface, SDL_RWops * dst, int freedst);
@@ -225,183 +356,303 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
         SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
 
 /**
- *  \brief Sets the RLE acceleration hint for a surface.
+ * Set the RLE acceleration hint for a surface.
+ *
+ * If RLE is enabled, color key and alpha blending blits are much faster, but
+ * the surface must be locked before directly accessing the pixels.
  *
- *  \return 0 on success, or -1 if the surface is not valid
+ * \param surface the SDL_Surface structure to optimize
+ * \param flag 0 to disable, non-zero to enable RLE acceleration
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \note If RLE is enabled, colorkey and alpha blending blits are much faster,
+ * \sa SDL_BlitSurface
- *        but the surface must be locked before directly accessing the pixels.
+ * \sa SDL_LockSurface
+ * \sa SDL_UnlockSurface
  */
 extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface,
                                               int flag);
 
 /**
- *  \brief Sets the color key (transparent pixel) in a blittable surface.
+ * Returns whether the surface is RLE enabled
+ *
+ * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
+ *
+ * \param surface the SDL_Surface structure to query
+ * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise.
+ *
+ * \sa SDL_SetSurfaceRLE
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasSurfaceRLE(SDL_Surface * surface);
+
+/**
+ * Set the color key (transparent pixel) in a surface.
  *
- *  \param surface The surface to update
+ * The color key defines a pixel value that will be treated as transparent in
- *  \param flag Non-zero to enable colorkey and 0 to disable colorkey
+ * a blit. For example, one can use this to specify that cyan pixels should be
- *  \param key The transparent pixel in the native surface format
+ * considered transparent, and therefore not rendered.
  *
- *  \return 0 on success, or -1 if the surface is not valid
+ * It is a pixel of the format used by the surface, as generated by
+ * SDL_MapRGB().
  *
- *  You can pass SDL_RLEACCEL to enable RLE accelerated blits.
+ * RLE acceleration can substantially speed up blitting of images with large
+ * horizontal runs of transparent pixels. See SDL_SetSurfaceRLE() for details.
+ *
+ * \param surface the SDL_Surface structure to update
+ * \param flag SDL_TRUE to enable color key, SDL_FALSE to disable color key
+ * \param key the transparent pixel
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_BlitSurface
+ * \sa SDL_GetColorKey
  */
 extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
                                             int flag, Uint32 key);
 
 /**
- *  \brief Returns whether the surface has a color key
+ * Returns whether the surface has a color key
+ *
+ * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
  *
- *  \return SDL_TRUE if the surface has a color key, or SDL_FALSE if the surface is NULL or has no color key
+ * \param surface the SDL_Surface structure to query
+ * \return SDL_TRUE if the surface has a color key, SDL_FALSE otherwise.
+ *
+ * \sa SDL_SetColorKey
+ * \sa SDL_GetColorKey
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasColorKey(SDL_Surface * surface);
 
 /**
- *  \brief Gets the color key (transparent pixel) in a blittable surface.
+ * Get the color key (transparent pixel) for a surface.
+ *
+ * The color key is a pixel of the format used by the surface, as generated by
+ * SDL_MapRGB().
  *
- *  \param surface The surface to update
+ * If the surface doesn't have color key enabled this function returns -1.
- *  \param key A pointer filled in with the transparent pixel in the native
- *             surface format
  *
- *  \return 0 on success, or -1 if the surface is not valid or colorkey is not
+ * \param surface the SDL_Surface structure to query
- *          enabled.
+ * \param key a pointer filled in with the transparent pixel
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_BlitSurface
+ * \sa SDL_SetColorKey
  */
 extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
                                             Uint32 * key);
 
 /**
- *  \brief Set an additional color value used in blit operations.
+ * Set an additional color value multiplied into blit operations.
+ *
+ * When this surface is blitted, during the blit operation each source color
+ * channel is modulated by the appropriate color value according to the
+ * following formula:
  *
- *  \param surface The surface to update.
+ * `srcC = srcC * (color / 255)`
- *  \param r The red color value multiplied into blit operations.
- *  \param g The green color value multiplied into blit operations.
- *  \param b The blue color value multiplied into blit operations.
  *
- *  \return 0 on success, or -1 if the surface is not valid.
+ * \param surface the SDL_Surface structure to update
+ * \param r the red color value multiplied into blit operations
+ * \param g the green color value multiplied into blit operations
+ * \param b the blue color value multiplied into blit operations
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_GetSurfaceColorMod()
+ * \sa SDL_GetSurfaceColorMod
+ * \sa SDL_SetSurfaceAlphaMod
  */
 extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
                                                    Uint8 r, Uint8 g, Uint8 b);
 
 
 /**
- *  \brief Get the additional color value used in blit operations.
+ * Get the additional color value multiplied into blit operations.
  *
- *  \param surface The surface to query.
+ * \param surface the SDL_Surface structure to query
- *  \param r A pointer filled in with the current red color value.
+ * \param r a pointer filled in with the current red color value
- *  \param g A pointer filled in with the current green color value.
+ * \param g a pointer filled in with the current green color value
- *  \param b A pointer filled in with the current blue color value.
+ * \param b a pointer filled in with the current blue color value
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \return 0 on success, or -1 if the surface is not valid.
+ * \sa SDL_GetSurfaceAlphaMod
- *
+ * \sa SDL_SetSurfaceColorMod
- *  \sa SDL_SetSurfaceColorMod()
  */
 extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
                                                    Uint8 * r, Uint8 * g,
                                                    Uint8 * b);
 
 /**
- *  \brief Set an additional alpha value used in blit operations.
+ * Set an additional alpha value used in blit operations.
+ *
+ * When this surface is blitted, during the blit operation the source alpha
+ * value is modulated by this alpha value according to the following formula:
  *
- *  \param surface The surface to update.
+ * `srcA = srcA * (alpha / 255)`
- *  \param alpha The alpha value multiplied into blit operations.
  *
- *  \return 0 on success, or -1 if the surface is not valid.
+ * \param surface the SDL_Surface structure to update
+ * \param alpha the alpha value multiplied into blit operations
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_GetSurfaceAlphaMod()
+ * \sa SDL_GetSurfaceAlphaMod
+ * \sa SDL_SetSurfaceColorMod
  */
 extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
                                                    Uint8 alpha);
 
 /**
- *  \brief Get the additional alpha value used in blit operations.
+ * Get the additional alpha value used in blit operations.
- *
- *  \param surface The surface to query.
- *  \param alpha A pointer filled in with the current alpha value.
  *
- *  \return 0 on success, or -1 if the surface is not valid.
+ * \param surface the SDL_Surface structure to query
+ * \param alpha a pointer filled in with the current alpha value
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_SetSurfaceAlphaMod()
+ * \sa SDL_GetSurfaceColorMod
+ * \sa SDL_SetSurfaceAlphaMod
  */
 extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
                                                    Uint8 * alpha);
 
 /**
- *  \brief Set the blend mode used for blit operations.
+ * Set the blend mode used for blit operations.
  *
- *  \param surface The surface to update.
+ * To copy a surface to another surface (or texture) without blending with the
- *  \param blendMode ::SDL_BlendMode to use for blit blending.
+ * existing data, the blendmode of the SOURCE surface should be set to
+ * `SDL_BLENDMODE_NONE`.
  *
- *  \return 0 on success, or -1 if the parameters are not valid.
+ * \param surface the SDL_Surface structure to update
+ * \param blendMode the SDL_BlendMode to use for blit blending
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_GetSurfaceBlendMode()
+ * \sa SDL_GetSurfaceBlendMode
  */
 extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
                                                     SDL_BlendMode blendMode);
 
 /**
- *  \brief Get the blend mode used for blit operations.
+ * Get the blend mode used for blit operations.
  *
- *  \param surface   The surface to query.
+ * \param surface the SDL_Surface structure to query
- *  \param blendMode A pointer filled in with the current blend mode.
+ * \param blendMode a pointer filled in with the current SDL_BlendMode
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \return 0 on success, or -1 if the surface is not valid.
+ * \sa SDL_SetSurfaceBlendMode
- *
- *  \sa SDL_SetSurfaceBlendMode()
  */
 extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
                                                     SDL_BlendMode *blendMode);
 
 /**
- *  Sets the clipping rectangle for the destination surface in a blit.
+ * 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.
  *
- *  If the clip rectangle is NULL, clipping will be disabled.
+ * Note that blits are automatically clipped to the edges of the source and
+ * destination surfaces.
  *
- *  If the clip rectangle doesn't intersect the surface, the function will
+ * \param surface the SDL_Surface structure to be clipped
- *  return SDL_FALSE and blits will be completely clipped.  Otherwise the
+ * \param rect the SDL_Rect structure representing the clipping rectangle, or
- *  function returns SDL_TRUE and blits to the surface will be clipped to
+ *             NULL to disable clipping
- *  the intersection of the surface area and the clipping rectangle.
+ * \returns SDL_TRUE if the rectangle intersects the surface, otherwise
+ *          SDL_FALSE and blits will be completely clipped.
  *
- *  Note that blits are automatically clipped to the edges of the source
+ * \sa SDL_BlitSurface
- *  and destination surfaces.
+ * \sa SDL_GetClipRect
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
                                                  const SDL_Rect * rect);
 
 /**
- *  Gets the clipping rectangle for the destination surface in a blit.
+ * 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.
  *
- *  \c rect must be a pointer to a valid rectangle which will be filled
+ * \param surface the SDL_Surface structure representing the surface to be
- *  with the correct values.
+ *                clipped
+ * \param rect an SDL_Rect structure filled in with the clipping rectangle for
+ *             the surface
+ *
+ * \sa SDL_BlitSurface
+ * \sa SDL_SetClipRect
  */
 extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
                                              SDL_Rect * rect);
 
 /*
- * Creates a new surface identical to the existing surface
+ * Creates a new surface identical to the existing surface.
+ *
+ * The returned surface should be freed with SDL_FreeSurface().
+ *
+ * \param surface the surface to duplicate.
+ * \returns a copy of the surface, or NULL on failure; call SDL_GetError() for
+ *          more information.
  */
 extern DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface * surface);
 
 /**
- *  Creates a new surface of the specified format, and then copies and maps
+ * Copy an existing surface to a new surface of the specified format.
- *  the given surface to it so the blit of the converted surface will be as
- *  fast as possible.  If this function fails, it returns NULL.
  *
- *  The \c flags parameter is passed to SDL_CreateRGBSurface() and has those
+ * This function is used to optimize images for faster *repeat* blitting. This
- *  semantics.  You can also pass ::SDL_RLEACCEL in the flags parameter and
+ * is accomplished by converting the original and storing the result as a new
- *  SDL will try to RLE accelerate colorkey and alpha blits in the resulting
+ * surface. The new, optimized surface can then be used as the source for
- *  surface.
+ * future blits, making them faster.
+ *
+ * \param src the existing SDL_Surface structure to convert
+ * \param fmt the SDL_PixelFormat structure that the new surface is optimized
+ *            for
+ * \param flags the flags are unused and should be set to 0; this is a
+ *              leftover from SDL 1.2's API
+ * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ *          call SDL_GetError() for more information.
+ *
+ * \sa SDL_AllocFormat
+ * \sa SDL_ConvertSurfaceFormat
+ * \sa SDL_CreateRGBSurface
  */
 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
     (SDL_Surface * src, const SDL_PixelFormat * fmt, Uint32 flags);
+
+/**
+ * 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
+ * information for the destination surface, in case that would be important.
+ *
+ * \param src the existing SDL_Surface structure to convert
+ * \param pixel_format the SDL_PixelFormatEnum that the new surface is
+ *                     optimized for
+ * \param flags the flags are unused and should be set to 0; this is a
+ *              leftover from SDL 1.2's API
+ * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ *          call SDL_GetError() for more information.
+ *
+ * \sa SDL_AllocFormat
+ * \sa SDL_ConvertSurfaceFormat
+ * \sa SDL_CreateRGBSurface
+ */
 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat
     (SDL_Surface * src, Uint32 pixel_format, Uint32 flags);
 
 /**
- * \brief Copy a block of pixels of one format to another format
+ * Copy a block of pixels of one format to another format.
  *
- *  \return 0 on success, or -1 if there was an error
+ * \param width the width of the block to copy, in pixels
+ * \param height the height of the block to copy, in pixels
+ * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format
+ * \param src a pointer to the source pixels
+ * \param src_pitch the pitch of the block to copy, in bytes
+ * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format
+ * \param dst a pointer to be filled in with new pixel data
+ * \param dst_pitch the pitch of the destination pixels, in bytes
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  */
 extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
                                               Uint32 src_format,
@@ -410,20 +661,54 @@ extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
                                               void * dst, int dst_pitch);
 
 /**
- *  Performs a fast fill of the given rectangle with \c color.
+ * Perform a fast fill of a rectangle with a specific color.
+ *
+ * `color` should be a pixel of the format used by the surface, and can be
+ * generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an
+ * alpha component then the destination is simply filled with that alpha
+ * information, no blending takes place.
  *
- *  If \c rect is NULL, the whole surface will be filled with \c color.
+ * If there is a clip rectangle set on the destination (set via
+ * SDL_SetClipRect()), then this function will fill based on the intersection
+ * of the clip rectangle and `rect`.
  *
- *  The color should be a pixel of the format used by the surface, and
+ * \param dst the SDL_Surface structure that is the drawing target
- *  can be generated by the SDL_MapRGB() function.
+ * \param rect the SDL_Rect structure representing the rectangle to fill, or
+ *             NULL to fill the entire surface
+ * \param color the color to fill with
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \return 0 on success, or -1 on error.
+ * \sa SDL_FillRects
  */
 extern DECLSPEC int SDLCALL SDL_FillRect
     (SDL_Surface * dst, const SDL_Rect * rect, Uint32 color);
+
+/**
+ * Perform a fast fill of a set of rectangles with a specific color.
+ *
+ * `color` should be a pixel of the format used by the surface, and can be
+ * generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an
+ * alpha component then the destination is simply filled with that alpha
+ * information, no blending takes place.
+ *
+ * If there is a clip rectangle set on the destination (set via
+ * SDL_SetClipRect()), then this function will fill based on the intersection
+ * of the clip rectangle and `rect`.
+ *
+ * \param dst the SDL_Surface structure that is the drawing target
+ * \param rects an array of SDL_Rects representing the rectangles to fill.
+ * \param count the number of rectangles in the array
+ * \param color the color to fill with
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_FillRect
+ */
 extern DECLSPEC int SDLCALL SDL_FillRects
     (SDL_Surface * dst, const SDL_Rect * rects, int count, Uint32 color);
 
+/* !!! FIXME: merge this documentation with the wiki */
 /**
  *  Performs a fast blit from the source surface to the destination surface.
  *
@@ -432,7 +717,7 @@ extern DECLSPEC int SDLCALL SDL_FillRects
  *  surface (\c src or \c dst) is copied.  The final blit rectangles are saved
  *  in \c srcrect and \c dstrect after all clipping is performed.
  *
- *  \return If the blit is successful, it returns 0, otherwise it returns -1.
+ *  \returns 0 if the blit is successful, otherwise it returns -1.
  *
  *  The blit function should not be called on a locked surface.
  *
@@ -484,62 +769,110 @@ extern DECLSPEC int SDLCALL SDL_FillRects
 #define SDL_BlitSurface SDL_UpperBlit
 
 /**
- *  This is the public blit function, SDL_BlitSurface(), and it performs
+ * Perform a fast blit from the source surface to the destination surface.
- *  rectangle validation and clipping before passing it to SDL_LowerBlit()
+ *
+ * SDL_UpperBlit() has been replaced by SDL_BlitSurface(), which is merely a
+ * macro for this function with a less confusing name.
+ *
+ * \sa SDL_BlitSurface
  */
 extern DECLSPEC int SDLCALL SDL_UpperBlit
     (SDL_Surface * src, const SDL_Rect * srcrect,
      SDL_Surface * dst, SDL_Rect * dstrect);
 
 /**
- *  This is a semi-private blit function and it performs low-level surface
+ * Perform low-level surface blitting only.
- *  blitting only.
+ *
+ * This is a semi-private blit function and it performs low-level surface
+ * blitting, assuming the input rectangles have already been clipped.
+ *
+ * Unless you know what you're doing, you should be using SDL_BlitSurface()
+ * instead.
+ *
+ * \param src the SDL_Surface structure to be copied from
+ * \param srcrect the SDL_Rect structure representing the rectangle to be
+ *                copied, or NULL to copy the entire surface
+ * \param dst the SDL_Surface structure that is the blit target
+ * \param dstrect the SDL_Rect structure representing the rectangle that is
+ *                copied into
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_BlitSurface
  */
 extern DECLSPEC int SDLCALL SDL_LowerBlit
     (SDL_Surface * src, SDL_Rect * srcrect,
      SDL_Surface * dst, SDL_Rect * dstrect);
 
+
+ /**
+  * Perform a fast, low quality, stretch blit between two surfaces of the
+  * same format.
+  *
+  * Please use SDL_BlitScaled() instead.
+  */
+extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
+                                            const SDL_Rect * srcrect,
+                                            SDL_Surface * dst,
+                                            const SDL_Rect * dstrect);
+
 /**
- *  \brief Perform a fast, low quality, stretch blit between two surfaces of the
+ * Perform bilinear scaling between two surfaces of the same format, 32BPP.
- *         same pixel format.
- *
- *  \note This function uses a static buffer, and is not thread-safe.
  */
-extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
+extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface * src,
                                             const SDL_Rect * srcrect,
                                             SDL_Surface * dst,
                                             const SDL_Rect * dstrect);
 
+
 #define SDL_BlitScaled SDL_UpperBlitScaled
 
 /**
- *  This is the public scaled blit function, SDL_BlitScaled(), and it performs
+ * Perform a scaled surface copy to a destination surface.
- *  rectangle validation and clipping before passing it to SDL_LowerBlitScaled()
+ *
+ * SDL_UpperBlitScaled() has been replaced by SDL_BlitScaled(), which is
+ * merely a macro for this function with a less confusing name.
+ *
+ * \sa SDL_BlitScaled
  */
 extern DECLSPEC int SDLCALL SDL_UpperBlitScaled
     (SDL_Surface * src, const SDL_Rect * srcrect,
     SDL_Surface * dst, SDL_Rect * dstrect);
 
 /**
- *  This is a semi-private blit function and it performs low-level surface
+ * Perform low-level surface scaled blitting only.
- *  scaled blitting only.
+ *
+ * This is a semi-private function and it performs low-level surface blitting,
+ * assuming the input rectangles have already been clipped.
+ *
+ * \param src the SDL_Surface structure to be copied from
+ * \param srcrect the SDL_Rect structure representing the rectangle to be
+ *                copied
+ * \param dst the SDL_Surface structure that is the blit target
+ * \param dstrect the SDL_Rect structure representing the rectangle that is
+ *                copied into
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \sa SDL_BlitScaled
  */
 extern DECLSPEC int SDLCALL SDL_LowerBlitScaled
     (SDL_Surface * src, SDL_Rect * srcrect,
     SDL_Surface * dst, SDL_Rect * dstrect);
 
 /**
- *  \brief Set the YUV conversion mode
+ * Set the YUV conversion mode
  */
 extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mode);
 
 /**
- *  \brief Get the YUV conversion mode
+ * Get the YUV conversion mode
  */
 extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void);
 
 /**
- *  \brief 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);
 

dep/msvc/sdl2/include/SDL_system.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -43,33 +43,78 @@ extern "C" {
 /* Platform specific functions for Windows */
 #ifdef __WIN32__
 	
-/**
-   \brief Set a function that is called for every windows message, before TranslateMessage()
-*/
 typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam);
-extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
 
 /**
-   \brief Returns the D3D9 adapter index that matches the specified display index.
+ * Set a callback for every Windows message, run before TranslateMessage().
+ *
+ * \param callback The SDL_WindowsMessageHook function to call.
+ * \param userdata a pointer to pass to every iteration of `callback`
+ */
+extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
 
-   This adapter index can be passed to IDirect3D9::CreateDevice and controls
+/**
-   on which monitor a full screen application will appear.
+ * Get the D3D9 adapter index that matches the specified display index.
-*/
+ *
+ * The returned adapter index can be passed to `IDirect3D9::CreateDevice` and
+ * controls on which monitor a full screen application will appear.
+ *
+ * \param displayIndex the display index for which to get the D3D9 adapter
+ *                     index
+ * \returns the D3D9 adapter index on success or a negative error code on
+ *          failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.1.
+ */
 extern DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex( int displayIndex );
 
 typedef struct IDirect3DDevice9 IDirect3DDevice9;
-/**
-   \brief Returns the D3D device associated with a renderer, or NULL if it's not a D3D renderer.
 
-   Once you are done using the device, you should release it to avoid a resource leak.
+/**
+ * Get the D3D9 device associated with a renderer.
+ *
+ * Once you are done using the device, you should release it to avoid a
+ * resource leak.
+ *
+ * \param renderer the renderer from which to get the associated D3D device
+ * \returns the D3D9 device associated with given renderer or NULL if it is
+ *          not a D3D9 renderer; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.1.
  */
 extern DECLSPEC IDirect3DDevice9* SDLCALL SDL_RenderGetD3D9Device(SDL_Renderer * renderer);
 
+typedef struct ID3D11Device ID3D11Device;
+
 /**
-   \brief Returns the DXGI Adapter and Output indices for the specified display index.
+ * Get the D3D11 device associated with a renderer.
+ *
+ * Once you are done using the device, you should release it to avoid a
+ * resource leak.
+ *
+ * \param renderer the renderer from which to get the associated D3D11 device
+ * \returns the D3D11 device associated with given renderer or NULL if it is
+ *          not a D3D11 renderer; call SDL_GetError() for more information.
+ */
+extern DECLSPEC ID3D11Device* SDLCALL SDL_RenderGetD3D11Device(SDL_Renderer * renderer);
 
-   These can be passed to EnumAdapters and EnumOutputs respectively to get the objects
+/**
-   required to create a DX10 or DX11 device and swap chain.
+ * Get the DXGI Adapter and Output indices for the specified display index.
+ *
+ * The DXGI Adapter and Output indices can be passed to `EnumAdapters` and
+ * `EnumOutputs` respectively to get the objects required to create a DX10 or
+ * DX11 device and swap chain.
+ *
+ * Before SDL 2.0.4 this function did not return a value. Since SDL 2.0.4 it
+ * returns an SDL_bool.
+ *
+ * \param displayIndex the display index for which to get both indices
+ * \param adapterIndex a pointer to be filled in with the adapter index
+ * \param outputIndex a pointer to be filled in with the output index
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \since This function is available since SDL 2.0.2.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *adapterIndex, int *outputIndex );
 
@@ -80,16 +125,20 @@ extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *a
 #ifdef __LINUX__
 
 /**
-   \brief Sets the UNIX nice value for a thread, using setpriority() if possible, and RealtimeKit if available.
+ * Sets the UNIX nice value for a thread.
-
+ *
-   \return 0 on success, or -1 on error.
+ * This uses setpriority() if possible, and RealtimeKit if available.
+ *
+ * \param threadID the Unix thread ID to change priority of.
+ * \param priority The new, Unix-specific, priority value.
+ * \returns 0 on success, or -1 on error.
  */
 extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int priority);
  
 #endif /* __LINUX__ */
 	
 /* Platform specific functions for iOS */
-#if defined(__IPHONEOS__) && __IPHONEOS__
+#ifdef __IPHONEOS__
 
 #define SDL_iOSSetAnimationCallback(window, interval, callback, callbackParam) SDL_iPhoneSetAnimationCallback(window, interval, callback, callbackParam)
 extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam);
@@ -101,42 +150,101 @@ extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool enabled);
 
 
 /* Platform specific functions for Android */
-#if defined(__ANDROID__) && __ANDROID__
+#ifdef __ANDROID__
 
 /**
-   \brief Get the JNI environment for the current thread
+ * Get the Android Java Native Interface Environment of the current thread.
-
+ *
-   This returns JNIEnv*, but the prototype is void* so we don't need jni.h
+ * This is the JNIEnv one needs to access the Java virtual machine from native
+ * code, and is needed for many Android APIs to be usable from C.
+ *
+ * The prototype of the function in SDL's code actually declare a void* return
+ * type, even if the implementation returns a pointer to a JNIEnv. The
+ * rationale being that the SDL headers can avoid including jni.h.
+ *
+ * \returns a pointer to Java native interface object (JNIEnv) to which the
+ *          current thread is attached, or 0 on error.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AndroidGetActivity
  */
 extern DECLSPEC void * SDLCALL SDL_AndroidGetJNIEnv(void);
 
 /**
-   \brief Get the SDL Activity object for the application
+ * Retrieve the Java instance of the Android activity class.
-
+ *
-   This returns jobject, but the prototype is void* so we don't need jni.h
+ * The prototype of the function in SDL's code actually declares a void*
-   The jobject returned by SDL_AndroidGetActivity is a local reference.
+ * return type, even if the implementation returns a jobject. The rationale
-   It is the caller's responsibility to properly release it
+ * being that the SDL headers can avoid including jni.h.
-   (using env->Push/PopLocalFrame or manually with env->DeleteLocalRef)
+ *
+ * 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
+ *
+ * \returns the jobject representing the instance of the Activity class of the
+ *          Android application, or NULL on error.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AndroidGetJNIEnv
  */
 extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void);
 
 /**
-   \brief Return true if the application is running on Android TV
+ * Query Android API level of the current device.
+ *
+ * - API level 30: Android 11
+ * - API level 29: Android 10
+ * - API level 28: Android 9
+ * - API level 27: Android 8.1
+ * - API level 26: Android 8.0
+ * - API level 25: Android 7.1
+ * - API level 24: Android 7.0
+ * - API level 23: Android 6.0
+ * - API level 22: Android 5.1
+ * - API level 21: Android 5.0
+ * - API level 20: Android 4.4W
+ * - API level 19: Android 4.4
+ * - API level 18: Android 4.3
+ * - API level 17: Android 4.2
+ * - API level 16: Android 4.1
+ * - API level 15: Android 4.0.3
+ * - API level 14: Android 4.0
+ * - API level 13: Android 3.2
+ * - API level 12: Android 3.1
+ * - API level 11: Android 3.0
+ * - API level 10: Android 2.3.3
+ *
+ * \returns the Android API level.
+ */
+extern DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void);
+
+/**
+ * Query if the application is running on Android TV.
+ *
+ * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void);
 
 /**
-   \brief Return true if the application is running on a Chromebook
+ * Query if the application is running on a Chromebook.
+ *
+ * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void);
 
 /**
-  \brief Return true is the application is running on a Samsung DeX docking station
+ * Query if the application is running on a Samsung DeX docking station.
+ *
+ * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
 
 /**
- \brief Trigger the Android system back button behavior.
+ * Trigger the Android system back button behavior.
  */
 extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
 
@@ -148,34 +256,95 @@ extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE  0x02
 
 /**
-   \brief Get the path used for internal storage for this application.
+ * Get the path used for internal storage for this application.
-
+ *
-   This path is unique to your application and cannot be written to
+ * This path is unique to your application and cannot be written to by other
-   by other applications.
+ * applications.
+ *
+ * Your internal storage path is typically:
+ * `/data/data/your.app.package/files`.
+ *
+ * \returns the path used for internal storage or NULL on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AndroidGetExternalStorageState
  */
 extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath(void);
 
 /**
-   \brief Get the current state of external storage, a bitmask of these values:
+ * Get the current state of external storage.
-    SDL_ANDROID_EXTERNAL_STORAGE_READ
+ *
-    SDL_ANDROID_EXTERNAL_STORAGE_WRITE
+ * The current state of external storage, a bitmask of these values:
-
+ * `SDL_ANDROID_EXTERNAL_STORAGE_READ`, `SDL_ANDROID_EXTERNAL_STORAGE_WRITE`.
-   If external storage is currently unavailable, this will return 0.
+ *
-*/
+ * If external storage is currently unavailable, this will return 0.
+ *
+ * \returns the current state of external storage on success or 0 on failure;
+ *          call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AndroidGetExternalStoragePath
+ */
 extern DECLSPEC int SDLCALL SDL_AndroidGetExternalStorageState(void);
 
 /**
-   \brief Get the path used for external storage for this application.
+ * Get the path used for external storage for this application.
-
+ *
-   This path is unique to your application, but is public and can be
+ * This path is unique to your application, but is public and can be written
-   written to by other applications.
+ * to by other applications.
+ *
+ * Your external storage path is typically:
+ * `/storage/sdcard0/Android/data/your.app.package/files`.
+ *
+ * \returns the path used for external storage for this application on success
+ *          or NULL on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AndroidGetExternalStorageState
  */
 extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void);
 
+/**
+ * Request permissions at runtime.
+ *
+ * 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.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permission);
+
+/**
+ * Shows an Android toast notification.
+ *
+ * Toasts are a sort of lightweight notification that are unique to Android.
+ *
+ * https://developer.android.com/guide/topics/ui/notifiers/toasts
+ *
+ * Shows toast in UI thread.
+ *
+ * For the `gravity` parameter, choose a value from here, or -1 if you don't
+ * have a preference:
+ *
+ * https://developer.android.com/reference/android/view/Gravity
+ *
+ * \param message text message to be shown
+ * \param duration 0=short, 1=long
+ * \param gravity where the notification should appear on the screen.
+ * \param xoffset set this parameter only when gravity >=0
+ * \param yoffset set this parameter only when gravity >=0
+ * \returns 0 if success, -1 if any error occurs.
+ */
+extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int duration, int gravity, int xoffset, int yoffset);
+
 #endif /* __ANDROID__ */
 
 /* Platform specific functions for WinRT */
-#if defined(__WINRT__) && __WINRT__
+#ifdef __WINRT__
 
 /**
  *  \brief WinRT / Windows Phone path types
@@ -221,53 +390,80 @@ typedef enum
 
 
 /**
- *  \brief Retrieves a WinRT defined path on the local file system
+ * Retrieve a WinRT defined path on the local file system.
- *
+ *
- *  \note Documentation on most app-specific path types on WinRT
+ * Not all paths are available on all versions of Windows. This is especially
- *      can be found on MSDN, at the URL:
+ * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path
- *      http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
+ * for more information on which path types are supported where.
- *
+ *
- *  \param pathType The type of path to retrieve.
+ * Documentation on most app-specific path types on WinRT can be found on
- *  \return A UCS-2 string (16-bit, wide-char) containing the path, or NULL
+ * MSDN, at the URL:
- *      if the path is not available for any reason.  Not all paths are
+ *
- *      available on all versions of Windows.  This is especially true on
+ * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
- *      Windows Phone.  Check the documentation for the given
+ *
- *      SDL_WinRT_Path for more information on which path types are
+ * \param pathType the type of path to retrieve, one of SDL_WinRT_Path
- *      supported where.
+ * \returns a UCS-2 string (16-bit, wide-char) containing the path, or NULL if
+ *          the path is not available for any reason; call SDL_GetError() for
+ *          more information.
+ *
+ * \since This function is available since SDL 2.0.3.
+ *
+ * \sa SDL_WinRTGetFSPathUTF8
  */
 extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path pathType);
 
 /**
- *  \brief Retrieves a WinRT defined path on the local file system
+ * Retrieve a WinRT defined path on the local file system.
- *
+ *
- *  \note Documentation on most app-specific path types on WinRT
+ * Not all paths are available on all versions of Windows. This is especially
- *      can be found on MSDN, at the URL:
+ * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path
- *      http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
+ * for more information on which path types are supported where.
- *
+ *
- *  \param pathType The type of path to retrieve.
+ * Documentation on most app-specific path types on WinRT can be found on
- *  \return A UTF-8 string (8-bit, multi-byte) containing the path, or NULL
+ * MSDN, at the URL:
- *      if the path is not available for any reason.  Not all paths are
+ *
- *      available on all versions of Windows.  This is especially true on
+ * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
- *      Windows Phone.  Check the documentation for the given
+ *
- *      SDL_WinRT_Path for more information on which path types are
+ * \param pathType the type of path to retrieve, one of SDL_WinRT_Path
- *      supported where.
+ * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if
+ *          the path is not available for any reason; call SDL_GetError() for
+ *          more information.
+ *
+ * \since This function is available since SDL 2.0.3.
+ *
+ * \sa SDL_WinRTGetFSPathUNICODE
  */
 extern DECLSPEC const char * SDLCALL SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathType);
 
 /**
- *  \brief Detects the device family of WinRT plattform on runtime
+ * Detects the device family of WinRT plattform at runtime.
  *
- *  \return Device family
+ * \returns a value from the SDL_WinRT_DeviceFamily enum.
  */
 extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily();
 
 #endif /* __WINRT__ */
 
 /**
- \brief Return true if the current device is a tablet.
+ * Query if the current device is a tablet.
+ *
+ * If SDL can't determine this, it will return SDL_FALSE.
+ *
+ * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void);
 
+/* Functions used by iOS application delegates to notify SDL about state changes */
+extern DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void);
+extern DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void);
+extern DECLSPEC void SDLCALL SDL_OnApplicationWillResignActive(void);
+extern DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void);
+extern DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void);
+extern DECLSPEC void SDLCALL SDL_OnApplicationDidBecomeActive(void);
+#ifdef __IPHONEOS__
+extern DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void);
+#endif
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

dep/msvc/sdl2/include/SDL_syswm.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -49,6 +49,9 @@ struct SDL_SysWMinfo;
 #ifndef WIN32_LEAN_AND_MEAN
 #define WIN32_LEAN_AND_MEAN
 #endif
+#ifndef NOMINMAX   /* don't define min() and max(). */
+#define NOMINMAX
+#endif
 #include <windows.h>
 #endif
 
@@ -103,8 +106,17 @@ typedef void *EGLSurface;
 #if defined(SDL_VIDEO_DRIVER_VIVANTE)
 #include "SDL_egl.h"
 #endif
+
+#if defined(SDL_VIDEO_DRIVER_OS2)
+#define INCL_WIN
+#include <os2.h>
+#endif
 #endif /* SDL_PROTOTYPES_ONLY */
 
+#if defined(SDL_VIDEO_DRIVER_KMSDRM)
+struct gbm_device;
+#endif
+
 
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
@@ -129,7 +141,9 @@ typedef enum
     SDL_SYSWM_WINRT,
     SDL_SYSWM_ANDROID,
     SDL_SYSWM_VIVANTE,
-    SDL_SYSWM_OS2
+    SDL_SYSWM_OS2,
+    SDL_SYSWM_HAIKU,
+    SDL_SYSWM_KMSDRM
 } SDL_SYSWM_TYPE;
 
 /**
@@ -182,6 +196,16 @@ struct SDL_SysWMmsg
             int dummy;
             /* No Vivante window events yet */
         } vivante;
+#endif
+#if defined(SDL_VIDEO_DRIVER_OS2)
+        struct
+        {
+            BOOL fFrame;                /**< TRUE if hwnd is a frame window */
+            HWND hwnd;                  /**< The window receiving the message */
+            ULONG msg;                  /**< The message identifier */
+            MPARAM mp1;                 /**< The first first message parameter */
+            MPARAM mp2;                 /**< The second first message parameter */
+        } os2;
 #endif
         /* Can't have an empty union */
         int dummy;
@@ -232,8 +256,12 @@ struct SDL_SysWMinfo
 #if defined(SDL_VIDEO_DRIVER_COCOA)
         struct
         {
-#if defined(__OBJC__) && defined(__has_feature) && __has_feature(objc_arc)
+#if defined(__OBJC__) && defined(__has_feature)
+        #if __has_feature(objc_arc)
             NSWindow __unsafe_unretained *window; /**< The Cocoa window */
+        #else
+            NSWindow *window;                     /**< The Cocoa window */
+        #endif
 #else
             NSWindow *window;                     /**< The Cocoa window */
 #endif
@@ -242,8 +270,12 @@ struct SDL_SysWMinfo
 #if defined(SDL_VIDEO_DRIVER_UIKIT)
         struct
         {
-#if defined(__OBJC__) && defined(__has_feature) && __has_feature(objc_arc)
+#if defined(__OBJC__) && defined(__has_feature)
+        #if __has_feature(objc_arc)
             UIWindow __unsafe_unretained *window; /**< The UIKit window */
+        #else
+            UIWindow *window;                     /**< The UIKit window */
+        #endif
 #else
             UIWindow *window;                     /**< The UIKit window */
 #endif
@@ -255,9 +287,11 @@ struct SDL_SysWMinfo
 #if defined(SDL_VIDEO_DRIVER_WAYLAND)
         struct
         {
-            struct wl_display *display;            /**< Wayland display */
+            struct wl_display *display;             /**< Wayland display */
-            struct wl_surface *surface;            /**< Wayland surface */
+            struct wl_surface *surface;             /**< Wayland surface */
-            struct wl_shell_surface *shell_surface; /**< Wayland shell_surface (window manager handle) */
+            void *shell_surface;                    /**< DEPRECATED Wayland shell_surface (window manager handle) */
+            struct wl_egl_window *egl_window;       /**< Wayland EGL window (native window) */
+            struct xdg_surface *xdg_surface;        /**< Wayland xdg surface (window manager handle) */
         } wl;
 #endif
 #if defined(SDL_VIDEO_DRIVER_MIR)  /* no longer available, left for API/ABI compatibility. Remove in 2.1! */
@@ -276,6 +310,14 @@ struct SDL_SysWMinfo
         } android;
 #endif
 
+#if defined(SDL_VIDEO_DRIVER_OS2)
+        struct
+        {
+            HWND hwnd;                  /**< The window handle */
+            HWND hwndFrame;             /**< The frame window handle */
+        } os2;
+#endif
+
 #if defined(SDL_VIDEO_DRIVER_VIVANTE)
         struct
         {
@@ -284,6 +326,15 @@ struct SDL_SysWMinfo
         } vivante;
 #endif
 
+#if defined(SDL_VIDEO_DRIVER_KMSDRM)
+        struct
+        {
+            int dev_index;               /**< Device index (ex: the X in /dev/dri/cardX) */
+            int drm_fd;                  /**< DRM FD (unavailable on Vulkan windows) */
+            struct gbm_device *gbm_dev;  /**< GBM device (unavailable on Vulkan windows) */
+        } kmsdrm;
+#endif
+
         /* Make sure this union is always 64 bytes (8 64-bit pointers). */
         /* Be careful not to overflow this if you add a new target! */
         Uint8 dummy[64];
@@ -294,23 +345,23 @@ struct SDL_SysWMinfo
 
 typedef struct SDL_SysWMinfo SDL_SysWMinfo;
 
-/* Function prototypes */
+
 /**
- *  \brief This function allows access to driver-dependent window information.
+ * Get driver-specific information about a window.
+ *
+ * You must include SDL_syswm.h for the declaration of SDL_SysWMinfo.
  *
- *  \param window The window about which information is being requested
+ * The caller must initialize the `info` structure's version by using
- *  \param info This structure must be initialized with the SDL version, and is
+ * `SDL_VERSION(&info.version)`, and then this function will fill in the rest
- *              then filled in with information about the given window.
+ * of the structure with information about the given window.
  *
- *  \return SDL_TRUE if the function is implemented and the version member of
+ * \param window the window about which information is being requested
- *          the \c info struct is valid, SDL_FALSE otherwise.
+ * \param info an SDL_SysWMinfo structure filled in with window information
+ * \returns SDL_TRUE if the function is implemented and the `version` member
+ *          of the `info` struct is valid, or SDL_FALSE if the information
+ *          could not be retrieved; call SDL_GetError() for more information.
  *
- *  You typically use this function like this:
+ * \since This function is available since SDL 2.0.0.
- *  \code
- *  SDL_SysWMinfo info;
- *  SDL_VERSION(&info.version);
- *  if ( SDL_GetWindowWMInfo(window, &info) ) { ... }
- *  \endcode
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_Window * window,
                                                      SDL_SysWMinfo * info);

dep/msvc/sdl2/include/SDL_test.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_test_assert.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -66,7 +66,7 @@ void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *as
  * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0).
  * \param assertDescription Message to log with the assert describing it.
  *
- * \returns Returns the assertCondition so it can be used to externally to break execution flow if desired.
+ * \returns the assertCondition so it can be used to externally to break execution flow if desired.
  */
 int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2);
 

dep/msvc/sdl2/include/SDL_test_common.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -37,6 +37,9 @@
 #if defined(__PSP__)
 #define DEFAULT_WINDOW_WIDTH  480
 #define DEFAULT_WINDOW_HEIGHT 272
+#elif defined(__VITA__)
+#define DEFAULT_WINDOW_WIDTH  960
+#define DEFAULT_WINDOW_HEIGHT 544
 #else
 #define DEFAULT_WINDOW_WIDTH  640
 #define DEFAULT_WINDOW_HEIGHT 480
@@ -61,6 +64,7 @@ typedef struct
     const char *window_title;
     const char *window_icon;
     Uint32 window_flags;
+    SDL_bool flash_on_focus_loss;
     int window_x;
     int window_y;
     int window_w;
@@ -126,7 +130,7 @@ extern "C" {
  * \param argv Array of command line parameters
  * \param flags Flags indicating which subsystem to initialize (i.e. SDL_INIT_VIDEO | SDL_INIT_AUDIO)
  *
- * \returns Returns a newly allocated common state object.
+ * \returns a newly allocated common state object.
  */
 SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
 
@@ -136,7 +140,7 @@ SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
  * \param state The common state describing the test window to create.
  * \param index The index of the argument to process in argv[].
  *
- * \returns The number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error.
+ * \returns the number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error.
  */
 int SDLTest_CommonArg(SDLTest_CommonState * state, int index);
 
@@ -155,12 +159,25 @@ int SDLTest_CommonArg(SDLTest_CommonState * state, int index);
  */
 void SDLTest_CommonLogUsage(SDLTest_CommonState * state, const char *argv0, const char **options);
 
+/**
+ * \brief Returns common usage information
+ *
+ * You should (probably) be using SDLTest_CommonLogUsage() instead, but this
+ *  function remains for binary compatibility. Strings returned from this
+ *  function are valid until SDLTest_CommonQuit() is called, in which case
+ *  those strings' memory is freed and can no longer be used.
+ *
+ * \param state The common state describing the test window to create.
+ * \returns a string with usage information
+ */
+const char *SDLTest_CommonUsage(SDLTest_CommonState * state);
+
 /**
  * \brief Open test window.
  *
  * \param state The common state describing the test window to create.
  *
- * \returns True if initialization succeeded, false otherwise
+ * \returns SDL_TRUE if initialization succeeded, false otherwise
  */
 SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state);
 
@@ -171,7 +188,7 @@ SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state);
  * \param argc argc, as supplied to SDL_main
  * \param argv argv, as supplied to SDL_main
  *
- * \returns False if app should quit, true otherwise.
+ * \returns SDL_FALSE if app should quit, true otherwise.
  */
 SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState * state, const int argc, char **argv);
 
@@ -193,6 +210,14 @@ void SDLTest_CommonEvent(SDLTest_CommonState * state, SDL_Event * event, int *do
  */
 void SDLTest_CommonQuit(SDLTest_CommonState * state);
 
+/**
+ * \brief Draws various window information (position, size, etc.) to the renderer.
+ *
+ * \param renderer The renderer to draw to.
+ * \param window The window whose information should be displayed.
+ *
+ */
+void SDLTest_CommonDrawWindowInfo(SDL_Renderer * renderer, SDL_Window * window);
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

dep/msvc/sdl2/include/SDL_test_compare.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_test_crc32.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_test_font.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -48,7 +48,7 @@ extern "C" {
  *  \param y The Y coordinate of the upper left corner of the character.
  *  \param c The character to draw.
  *
- *  \returns Returns 0 on success, -1 on failure.
+ *  \returns 0 on success, -1 on failure.
  */
 int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, char c);
 
@@ -60,7 +60,7 @@ int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, char c);
  *  \param y The Y coordinate of the upper left corner of the string.
  *  \param s The string to draw.
  *
- *  \returns Returns 0 on success, -1 on failure.
+ *  \returns 0 on success, -1 on failure.
  */
 int SDLTest_DrawString(SDL_Renderer *renderer, int x, int y, const char *s);
 

dep/msvc/sdl2/include/SDL_test_fuzzer.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -66,14 +66,14 @@ void SDLTest_FuzzerInit(Uint64 execKey);
 /**
  * Returns a random Uint8
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Uint8 SDLTest_RandomUint8(void);
 
 /**
  * Returns a random Sint8
  *
- * \returns Generated signed integer
+ * \returns a generated signed integer
  */
 Sint8 SDLTest_RandomSint8(void);
 
@@ -81,14 +81,14 @@ Sint8 SDLTest_RandomSint8(void);
 /**
  * Returns a random Uint16
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Uint16 SDLTest_RandomUint16(void);
 
 /**
  * Returns a random Sint16
  *
- * \returns Generated signed integer
+ * \returns a generated signed integer
  */
 Sint16 SDLTest_RandomSint16(void);
 
@@ -96,7 +96,7 @@ Sint16 SDLTest_RandomSint16(void);
 /**
  * Returns a random integer
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Sint32 SDLTest_RandomSint32(void);
 
@@ -104,14 +104,14 @@ Sint32 SDLTest_RandomSint32(void);
 /**
  * Returns a random positive integer
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Uint32 SDLTest_RandomUint32(void);
 
 /**
  * Returns random Uint64.
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Uint64 SDLTest_RandomUint64(void);
 
@@ -119,28 +119,28 @@ Uint64 SDLTest_RandomUint64(void);
 /**
  * Returns random Sint64.
  *
- * \returns Generated signed integer
+ * \returns a generated signed integer
  */
 Sint64 SDLTest_RandomSint64(void);
 
 /**
- * \returns random float in range [0.0 - 1.0[
+ * \returns a random float in range [0.0 - 1.0]
  */
 float SDLTest_RandomUnitFloat(void);
 
 /**
- * \returns random double in range [0.0 - 1.0[
+ * \returns a random double in range [0.0 - 1.0]
  */
 double SDLTest_RandomUnitDouble(void);
 
 /**
- * \returns random float.
+ * \returns a random float.
  *
  */
 float SDLTest_RandomFloat(void);
 
 /**
- * \returns random double.
+ * \returns a random double.
  *
  */
 double SDLTest_RandomDouble(void);
@@ -162,7 +162,7 @@ double SDLTest_RandomDouble(void);
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or 0 with error set
+ * \returns a random boundary value for the given range and domain or 0 with error set
  */
 Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_bool validDomain);
 
@@ -183,7 +183,7 @@ Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_boo
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or 0 with error set
+ * \returns a random boundary value for the given range and domain or 0 with error set
  */
 Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL_bool validDomain);
 
@@ -204,7 +204,7 @@ Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or 0 with error set
+ * \returns a random boundary value for the given range and domain or 0 with error set
  */
 Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL_bool validDomain);
 
@@ -225,7 +225,7 @@ Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or 0 with error set
+ * \returns a random boundary value for the given range and domain or 0 with error set
  */
 Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL_bool validDomain);
 
@@ -246,7 +246,7 @@ Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or SINT8_MIN with error set
+ * \returns a random boundary value for the given range and domain or SINT8_MIN with error set
  */
 Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_bool validDomain);
 
@@ -268,7 +268,7 @@ Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_boo
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or SINT16_MIN with error set
+ * \returns a random boundary value for the given range and domain or SINT16_MIN with error set
  */
 Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL_bool validDomain);
 
@@ -289,7 +289,7 @@ Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or SINT32_MIN with error set
+ * \returns a random boundary value for the given range and domain or SINT32_MIN with error set
  */
 Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL_bool validDomain);
 
@@ -310,7 +310,7 @@ Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or SINT64_MIN with error set
+ * \returns a random boundary value for the given range and domain or SINT64_MIN with error set
  */
 Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL_bool validDomain);
 
@@ -324,7 +324,7 @@ Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL
  * \param min Minimum inclusive value of returned random number
  * \param max Maximum inclusive value of returned random number
  *
- * \returns Generated random integer in range
+ * \returns a generated random integer in range
  */
 Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max);
 
@@ -336,7 +336,7 @@ Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max);
  *
  * Note: Returned string needs to be deallocated.
  *
- * \returns Newly allocated random string; or NULL if length was invalid or string could not be allocated.
+ * \returns a newly allocated random string; or NULL if length was invalid or string could not be allocated.
  */
 char * SDLTest_RandomAsciiString(void);
 
@@ -350,7 +350,7 @@ char * SDLTest_RandomAsciiString(void);
  *
  * \param maxLength The maximum length of the generated string.
  *
- * \returns Newly allocated random string; or NULL if maxLength was invalid or string could not be allocated.
+ * \returns a newly allocated random string; or NULL if maxLength was invalid or string could not be allocated.
  */
 char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
 
@@ -364,12 +364,14 @@ char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
  *
  * \param size The length of the generated string
  *
- * \returns Newly allocated random string; or NULL if size was invalid or string could not be allocated.
+ * \returns a newly allocated random string; or NULL if size was invalid or string could not be allocated.
  */
 char * SDLTest_RandomAsciiStringOfSize(int size);
 
 /**
- * Returns the invocation count for the fuzzer since last ...FuzzerInit.
+ * Get the invocation count for the fuzzer since last ...FuzzerInit.
+ *
+ * \returns the invocation count.
  */
 int SDLTest_GetFuzzerInvocationCount(void);
 

dep/msvc/sdl2/include/SDL_test_harness.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -105,7 +105,7 @@ typedef struct SDLTest_TestSuiteReference {
  *
  * \param length The length of the seed string to generate
  *
- * \returns The generated seed string
+ * \returns the generated seed string
  */
 char *SDLTest_GenerateRunSeed(const int length);
 
@@ -118,7 +118,7 @@ char *SDLTest_GenerateRunSeed(const int length);
  * \param filter Filter specification. NULL disables. Case sensitive.
  * \param testIterations Number of iterations to run each test case.
  *
- * \returns Test run result; 0 when all tests passed, 1 if any tests failed.
+ * \returns the test run result: 0 when all tests passed, 1 if any tests failed.
  */
 int SDLTest_RunSuites(SDLTest_TestSuiteReference *testSuites[], const char *userRunSeed, Uint64 userExecKey, const char *filter, int testIterations);
 

dep/msvc/sdl2/include/SDL_test_images.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_test_log.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_test_md5.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_test_memory.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_test_random.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -98,7 +98,7 @@ extern "C" {
  *
  *  \param rndContext     pointer to context structure
  *
- *  \returns A random number (32bit unsigned integer)
+ *  \returns a random number (32bit unsigned integer)
  *
  */
  unsigned int SDLTest_Random(SDLTest_RandomContext *rndContext);

dep/msvc/sdl2/include/SDL_thread.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -35,6 +35,17 @@
 #include "SDL_atomic.h"
 #include "SDL_mutex.h"
 
+#if defined(__WIN32__)
+#include <process.h> /* _beginthreadex() and _endthreadex() */
+#endif
+#if defined(__OS2__) /* for _beginthread() and _endthread() */
+#ifndef __EMX__
+#include <process.h>
+#else
+#include <stdlib.h>
+#endif
+#endif
+
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
 #ifdef __cplusplus
@@ -54,6 +65,11 @@ typedef unsigned int SDL_TLSID;
 /**
  *  The SDL thread priority.
  *
+ *  SDL will make system changes as necessary in order to apply the thread priority.
+ *  Code which attempts to control thread state related to priority should be aware
+ *  that calling SDL_SetThreadPriority may alter such state.
+ *  SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this behavior.
+ *
  *  \note On many systems you require special privileges to set high or time critical priority.
  */
 typedef enum {
@@ -64,12 +80,15 @@ typedef enum {
 } SDL_ThreadPriority;
 
 /**
- *  The function passed to SDL_CreateThread().
+ * The function passed to SDL_CreateThread().
- *  It is passed a void* user context parameter and returns an int.
+ *
+ * \param data what was passed as `data` to SDL_CreateThread()
+ * \returns a value that can be reported through SDL_WaitThread().
  */
 typedef int (SDLCALL * SDL_ThreadFunction) (void *data);
 
-#if defined(__WIN32__) && !defined(HAVE_LIBC)
+
+#if defined(__WIN32__)
 /**
  *  \file SDL_thread.h
  *
@@ -91,13 +110,19 @@ typedef int (SDLCALL * SDL_ThreadFunction) (void *data);
  *  library!
  */
 #define SDL_PASSED_BEGINTHREAD_ENDTHREAD
-#include <process.h> /* _beginthreadex() and _endthreadex() */
 
-typedef uintptr_t(__cdecl * pfnSDL_CurrentBeginThread)
+typedef uintptr_t (__cdecl * pfnSDL_CurrentBeginThread)
                    (void *, unsigned, unsigned (__stdcall *func)(void *),
                     void * /*arg*/, unsigned, unsigned * /* threadID */);
 typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code);
 
+#ifndef SDL_beginthread
+#define SDL_beginthread _beginthreadex
+#endif
+#ifndef SDL_endthread
+#define SDL_endthread _endthreadex
+#endif
+
 /**
  *  Create a thread.
  */
@@ -118,12 +143,12 @@ SDL_CreateThreadWithStackSize(int (SDLCALL * fn) (void *),
  */
 #if defined(SDL_CreateThread) && SDL_DYNAMIC_API
 #undef SDL_CreateThread
-#define SDL_CreateThread(fn, name, data) SDL_CreateThread_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)_beginthreadex, (pfnSDL_CurrentEndThread)_endthreadex)
+#define SDL_CreateThread(fn, name, data) SDL_CreateThread_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread)
 #undef SDL_CreateThreadWithStackSize
-#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize_REAL(fn, name, stacksize, data, (pfnSDL_CurrentBeginThread)_beginthreadex, (pfnSDL_CurrentEndThread)_endthreadex)
+#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize_REAL(fn, name, stacksize, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread)
 #else
-#define SDL_CreateThread(fn, name, data) SDL_CreateThread(fn, name, data, (pfnSDL_CurrentBeginThread)_beginthreadex, (pfnSDL_CurrentEndThread)_endthreadex)
+#define SDL_CreateThread(fn, name, data) SDL_CreateThread(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread)
-#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize(fn, name, data, (pfnSDL_CurrentBeginThread)_beginthreadex, (pfnSDL_CurrentEndThread)_endthreadex)
+#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize(fn, name, data, (pfnSDL_CurrentBeginThread)_beginthreadex, (pfnSDL_CurrentEndThread)SDL_endthread)
 #endif
 
 #elif defined(__OS2__)
@@ -132,13 +157,17 @@ SDL_CreateThreadWithStackSize(int (SDLCALL * fn) (void *),
  * into a dll with Watcom's runtime statically linked.
  */
 #define SDL_PASSED_BEGINTHREAD_ENDTHREAD
-#ifndef __EMX__
+
-#include <process.h>
-#else
-#include <stdlib.h>
-#endif
 typedef int (*pfnSDL_CurrentBeginThread)(void (*func)(void *), void *, unsigned, void * /*arg*/);
 typedef void (*pfnSDL_CurrentEndThread)(void);
+
+#ifndef SDL_beginthread
+#define SDL_beginthread _beginthread
+#endif
+#ifndef SDL_endthread
+#define SDL_endthread _endthread
+#endif
+
 extern DECLSPEC SDL_Thread *SDLCALL
 SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data,
                  pfnSDL_CurrentBeginThread pfnBeginThread,
@@ -147,52 +176,81 @@ extern DECLSPEC SDL_Thread *SDLCALL
 SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const size_t stacksize, void *data,
                  pfnSDL_CurrentBeginThread pfnBeginThread,
                  pfnSDL_CurrentEndThread pfnEndThread);
+
 #if defined(SDL_CreateThread) && SDL_DYNAMIC_API
 #undef SDL_CreateThread
-#define SDL_CreateThread(fn, name, data) SDL_CreateThread_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)_beginthread, (pfnSDL_CurrentEndThread)_endthread)
+#define SDL_CreateThread(fn, name, data) SDL_CreateThread_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread)
 #undef SDL_CreateThreadWithStackSize
-#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)_beginthread, (pfnSDL_CurrentEndThread)_endthread)
+#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread)
 #else
-#define SDL_CreateThread(fn, name, data) SDL_CreateThread(fn, name, data, (pfnSDL_CurrentBeginThread)_beginthread, (pfnSDL_CurrentEndThread)_endthread)
+#define SDL_CreateThread(fn, name, data) SDL_CreateThread(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread)
-#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize(fn, name, stacksize, data, (pfnSDL_CurrentBeginThread)_beginthread, (pfnSDL_CurrentEndThread)_endthread)
+#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize(fn, name, stacksize, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread)
 #endif
 
 #else
 
 /**
- *  Create a thread with a default stack size.
+ * Create a new thread with a default stack size.
+ *
+ * This is equivalent to calling:
+ *
+ * ```c
+ * SDL_CreateThreadWithStackSize(fn, name, 0, data);
+ * ```
+ *
+ * \param fn the SDL_ThreadFunction function to call in the new thread
+ * \param name the name of the thread
+ * \param data a pointer that is passed to `fn`
+ * \returns an opaque pointer to the new thread object on success, NULL if the
+ *          new thread could not be created; call SDL_GetError() for more
+ *          information.
  *
- *  This is equivalent to calling:
+ * \sa SDL_CreateThreadWithStackSize
- *  SDL_CreateThreadWithStackSize(fn, name, 0, data);
+ * \sa SDL_WaitThread
  */
 extern DECLSPEC SDL_Thread *SDLCALL
 SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data);
 
 /**
- *  Create a thread.
+ * 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:
+ *
+ * https://stackoverflow.com/questions/149932/naming-conventions-for-threads
  *
- *   Thread naming is a little complicated: Most systems have very small
+ * If a system imposes requirements, SDL will try to munge the string for it
- *    limits for the string length (Haiku has 32 bytes, Linux currently has 16,
+ * (truncate, etc), but the original string contents will be available from
- *    Visual C++ 6.0 has nine!), and possibly other arbitrary rules. You'll
+ * SDL_GetThreadName().
- *    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:
  *
- *    http://stackoverflow.com/questions/149932/naming-conventions-for-threads
+ * 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).
  *
- *   If a system imposes requirements, SDL will try to munge the string for
+ * In SDL 2.1, stack size will be folded into the original SDL_CreateThread
- *    it (truncate, etc), but the original string contents will be available
+ * function, but for backwards compatibility, this is currently a separate
- *    from SDL_GetThreadName().
+ * function.
  *
- *   The size (in bytes) of the new stack can be specified. Zero means "use
+ * \param fn the SDL_ThreadFunction function to call in the new thread
- *    the system default" which might be wildly different between platforms
+ * \param name the name of the thread
- *    (x86 Linux generally defaults to eight megabytes, an embedded device
+ * \param stacksize the size, in bytes, to allocate for the new thread stack.
- *    might be a few kilobytes instead).
+ * \param data a pointer that is passed to `fn`
+ * \returns an opaque pointer to the new thread object on success, NULL if the
+ *          new thread could not be created; call SDL_GetError() for more
+ *          information.
  *
- *   In SDL 2.1, stacksize will be folded into the original SDL_CreateThread
+ * \sa SDL_WaitThread
- *    function.
  */
 extern DECLSPEC SDL_Thread *SDLCALL
 SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const size_t stacksize, void *data);
@@ -200,137 +258,190 @@ SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz
 #endif
 
 /**
- * Get the thread name, as it was specified in SDL_CreateThread().
+ * Get the thread name as it was specified in SDL_CreateThread().
- *  This function returns a pointer to a UTF-8 string that names the
+ *
- *  specified thread, or NULL if it doesn't have a name. This is internal
+ * This is internal memory, not to be freed by the caller, and remains valid
- *  memory, not to be free()'d by the caller, and remains valid until the
+ * until the specified thread is cleaned up by SDL_WaitThread().
- *  specified thread is cleaned up by SDL_WaitThread().
+ *
+ * \param thread the thread to query
+ * \returns a pointer to a UTF-8 string that names the specified thread, or
+ *          NULL if it doesn't have a name.
+ *
+ * \sa SDL_CreateThread
  */
 extern DECLSPEC const char *SDLCALL SDL_GetThreadName(SDL_Thread *thread);
 
 /**
- *  Get the thread identifier for the current thread.
+ * Get the thread identifier for the current thread.
+ *
+ * This thread identifier is as reported by the underlying operating system.
+ * If SDL is running on a platform that does not support threads the return
+ * value will always be zero.
+ *
+ * This function also returns a valid thread ID when called from the main
+ * thread.
+ *
+ * \returns the ID of the current thread.
+ *
+ * \sa SDL_GetThreadID
  */
 extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(void);
 
 /**
- *  Get the thread identifier for the specified thread.
+ * Get the thread identifier for the specified thread.
+ *
+ * This thread identifier is as reported by the underlying operating system.
+ * If SDL is running on a platform that does not support threads the return
+ * value will always be zero.
+ *
+ * \param thread the thread to query
+ * \returns the ID of the specified thread, or the ID of the current thread if
+ *          `thread` is NULL.
  *
- *  Equivalent to SDL_ThreadID() if the specified thread is NULL.
+ * \sa SDL_ThreadID
  */
 extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread);
 
 /**
- *  Set the priority for the current 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.
+ *
+ * \param priority the SDL_ThreadPriority to set
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  */
 extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority);
 
 /**
- *  Wait for a thread to finish. Threads that haven't been detached will
+ * Wait for a thread to finish.
- *  remain (as a "zombie") until this function cleans them up. Not doing so
+ *
- *  is a resource leak.
+ * Threads that haven't been detached will remain (as a "zombie") until this
+ * function cleans them up. Not doing so is a resource leak.
+ *
+ * Once a thread has been cleaned up through this function, the SDL_Thread
+ * that references it becomes invalid and should not be referenced again. As
+ * such, only one thread may call SDL_WaitThread() on another.
  *
- *  Once a thread has been cleaned up through this function, the SDL_Thread
+ * The return code for the thread function is placed in the area pointed to by
- *  that references it becomes invalid and should not be referenced again.
+ * `status`, if `status` is not NULL.
- *  As such, only one thread may call SDL_WaitThread() on another.
  *
- *  The return code for the thread function is placed in the area
+ * You may not wait on a thread that has been used in a call to
- *  pointed to by \c status, if \c status is not NULL.
+ * SDL_DetachThread(). Use either that function or this one, but not both, or
+ * behavior is undefined.
  *
- *  You may not wait on a thread that has been used in a call to
+ * It is safe to pass a NULL thread to this function; it is a no-op.
- *  SDL_DetachThread(). Use either that function or this one, but not
- *  both, or behavior is undefined.
  *
- *  It is safe to pass NULL to this function; it is a no-op.
+ * Note that the thread pointer is freed by this function and is not valid
+ * afterward.
+ *
+ * \param thread the SDL_Thread pointer that was returned from the
+ *               SDL_CreateThread() call that started this thread
+ * \param status pointer to an integer that will receive the value returned
+ *               from the thread function by its 'return', or NULL to not
+ *               receive such value back.
+ *
+ * \sa SDL_CreateThread
+ * \sa SDL_DetachThread
  */
 extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status);
 
 /**
- *  A thread may be "detached" to signify that it should not remain until
+ * Let a thread clean up on exit without intervention.
- *  another thread has called SDL_WaitThread() on it. Detaching a thread
+ *
- *  is useful for long-running threads that nothing needs to synchronize
+ * A thread may be "detached" to signify that it should not remain until
- *  with or further manage. When a detached thread is done, it simply
+ * another thread has called SDL_WaitThread() on it. Detaching a thread is
- *  goes away.
+ * useful for long-running threads that nothing needs to synchronize with or
- *
+ * further manage. When a detached thread is done, it simply goes away.
- *  There is no way to recover the return code of a detached thread. If you
+ *
- *  need this, don't detach the thread and instead use SDL_WaitThread().
+ * There is no way to recover the return code of a detached thread. If you
- *
+ * need this, don't detach the thread and instead use SDL_WaitThread().
- *  Once a thread is detached, you should usually assume the SDL_Thread isn't
+ *
- *  safe to reference again, as it will become invalid immediately upon
+ * Once a thread is detached, you should usually assume the SDL_Thread isn't
- *  the detached thread's exit, instead of remaining until someone has called
+ * safe to reference again, as it will become invalid immediately upon the
- *  SDL_WaitThread() to finally clean it up. As such, don't detach the same
+ * detached thread's exit, instead of remaining until someone has called
- *  thread more than once.
+ * SDL_WaitThread() to finally clean it up. As such, don't detach the same
- *
+ * thread more than once.
- *  If a thread has already exited when passed to SDL_DetachThread(), it will
+ *
- *  stop waiting for a call to SDL_WaitThread() and clean up immediately.
+ * If a thread has already exited when passed to SDL_DetachThread(), it will
- *  It is not safe to detach a thread that might be used with SDL_WaitThread().
+ * stop waiting for a call to SDL_WaitThread() and clean up immediately. It is
- *
+ * not safe to detach a thread that might be used with SDL_WaitThread().
- *  You may not call SDL_WaitThread() on a thread that has been detached.
+ *
- *  Use either that function or this one, but not both, or behavior is
+ * You may not call SDL_WaitThread() on a thread that has been detached. Use
- *  undefined.
+ * either that function or this one, but not both, or behavior is undefined.
- *
+ *
- *  It is safe to pass NULL to this function; it is a no-op.
+ * It is safe to pass NULL to this function; it is a no-op.
+ *
+ * \param thread the SDL_Thread pointer that was returned from the
+ *               SDL_CreateThread() call that started this thread
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_CreateThread
+ * \sa SDL_WaitThread
  */
 extern DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread * thread);
 
 /**
- *  \brief Create an identifier that is globally visible to all threads but refers to data that is thread-specific.
+ * Create a piece of thread-local storage.
- *
+ *
- *  \return The newly created thread local storage identifier, or 0 on error
+ * This creates an identifier that is globally visible to all threads but
- *
+ * refers to data that is thread-specific.
- *  \code
+ *
- *  static SDL_SpinLock tls_lock;
+ * \returns the newly created thread local storage identifier or 0 on error.
- *  static SDL_TLSID thread_local_storage;
+ *
- * 
+ * \since This function is available since SDL 2.0.0.
- *  void SetMyThreadData(void *value)
+ *
- *  {
+ * \sa SDL_TLSGet
- *      if (!thread_local_storage) {
+ * \sa SDL_TLSSet
- *          SDL_AtomicLock(&tls_lock);
- *          if (!thread_local_storage) {
- *              thread_local_storage = SDL_TLSCreate();
- *          }
- *          SDL_AtomicUnlock(&tls_lock);
- *      }
- *      SDL_TLSSet(thread_local_storage, value, 0);
- *  }
- *  
- *  void *GetMyThreadData(void)
- *  {
- *      return SDL_TLSGet(thread_local_storage);
- *  }
- *  \endcode
- *
- *  \sa SDL_TLSGet()
- *  \sa SDL_TLSSet()
  */
 extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(void);
 
 /**
- *  \brief Get the value associated with a thread local storage ID for the current thread.
+ * Get the current thread's value associated with a thread local storage ID.
  *
- *  \param id The thread local storage ID
+ * \param id the thread local storage ID
+ * \returns the value associated with the ID for the current thread or NULL if
+ *          no value has been set; call SDL_GetError() for more information.
  *
- *  \return The value associated with the ID for the current thread, or NULL if no value has been set.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_TLSCreate()
+ * \sa SDL_TLSCreate
- *  \sa SDL_TLSSet()
+ * \sa SDL_TLSSet
  */
 extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id);
 
 /**
- *  \brief Set the value associated with a thread local storage ID for the current thread.
+ * Set the current thread's value associated with a thread local storage ID.
+ *
+ * The function prototype for `destructor` is:
  *
- *  \param id The thread local storage ID
+ * ```c
- *  \param value The value to associate with the ID for the current thread
+ * void destructor(void *value)
- *  \param destructor A function called when the thread exits, to free the value.
+ * ```
  *
- *  \return 0 on success, -1 on error
+ * where its parameter `value` is what was passed as `value` to SDL_TLSSet().
  *
- *  \sa SDL_TLSCreate()
+ * \param id the thread local storage ID
- *  \sa SDL_TLSGet()
+ * \param value the value to associate with the ID for the current thread
+ * \param destructor a function called when the thread exits, to free the
+ *                   value
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_TLSCreate
+ * \sa SDL_TLSGet
  */
 extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, void (SDLCALL *destructor)(void*));
 
+/**
+ * Cleanup all TLS data for this thread.
+ */
+extern DECLSPEC void SDLCALL SDL_TLSCleanup(void);
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

dep/msvc/sdl2/include/SDL_timer.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -38,45 +38,75 @@ extern "C" {
 #endif
 
 /**
- * \brief Get the number of milliseconds since the SDL library initialization.
+ * Get the number of milliseconds since SDL library initialization.
  *
- * \note This value wraps if the program runs for more than ~49 days.
+ * This value wraps if the program runs for more than ~49 days.
+ *
+ * \returns an unsigned 32-bit value representing the number of milliseconds
+ *          since the SDL library initialized.
+ *
+ * \sa SDL_TICKS_PASSED
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
 
 /**
- * \brief Compare SDL ticks values, and return true if A has passed B
+ * Compare SDL ticks values, and return true if `A` has passed `B`.
+ *
+ * For example, if you want to wait 100 ms, you could do this:
  *
- * e.g. if you want to wait 100 ms, you could do this:
+ * ```c++
- *  Uint32 timeout = SDL_GetTicks() + 100;
+ * Uint32 timeout = SDL_GetTicks() + 100;
- *  while (!SDL_TICKS_PASSED(SDL_GetTicks(), timeout)) {
+ * while (!SDL_TICKS_PASSED(SDL_GetTicks(), timeout)) {
- *      ... do work until timeout has elapsed
+ *     // ... do work until timeout has elapsed
- *  }
+ * }
+ * ```
  */
 #define SDL_TICKS_PASSED(A, B)  ((Sint32)((B) - (A)) <= 0)
 
 /**
- * \brief Get the current value of the high resolution counter
+ * Get the current value of the high resolution counter.
+ *
+ * This function is typically used for profiling.
+ *
+ * The counter values are only meaningful relative to each other. Differences
+ * between values can be converted to times by using
+ * SDL_GetPerformanceFrequency().
+ *
+ * \returns the current counter value.
+ *
+ * \sa SDL_GetPerformanceFrequency
  */
 extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void);
 
 /**
- * \brief Get the count per second of the high resolution counter
+ * Get the count per second of the high resolution counter.
+ *
+ * \returns a platform-specific count per second.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetPerformanceCounter
  */
 extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void);
 
 /**
- * \brief Wait a specified number of milliseconds before returning.
+ * Wait a specified number of milliseconds before returning.
+ *
+ * This function waits a specified number of milliseconds before returning. It
+ * waits at least the specified time, but possibly longer due to OS
+ * scheduling.
+ *
+ * \param ms the number of milliseconds to delay
  */
 extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
 
 /**
- *  Function prototype for the timer callback function.
+ * Function prototype for the timer callback function.
  *
- *  The callback function is passed the current timer interval and returns
+ * The callback function is passed the current timer interval and returns
- *  the next timer interval.  If the returned value is the same as the one
+ * the next timer interval. If the returned value is the same as the one
- *  passed in, the periodic alarm continues, otherwise a new alarm is
+ * passed in, the periodic alarm continues, otherwise a new alarm is
- *  scheduled.  If the callback returns 0, the periodic alarm is cancelled.
+ * scheduled. If the callback returns 0, the periodic alarm is cancelled.
  */
 typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param);
 
@@ -86,20 +116,47 @@ typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param);
 typedef int SDL_TimerID;
 
 /**
- * \brief Add a new timer to the pool of timers already running.
+ * Call a callback function at a future time.
+ *
+ * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init().
+ *
+ * The callback function is passed the current timer interval and the user
+ * supplied parameter from the SDL_AddTimer() call and should return the next
+ * timer interval. If the value returned from the callback is 0, the timer is
+ * canceled.
+ *
+ * The callback is run on a separate thread.
+ *
+ * Timers take into account the amount of time it took to execute the
+ * callback. For example, if the callback took 250 ms to execute and returned
+ * 1000 (ms), the timer would only wait another 750 ms before its next
+ * iteration.
+ *
+ * Timing may be inexact due to OS scheduling. Be sure to note the current
+ * time with SDL_GetTicks() or SDL_GetPerformanceCounter() in case your
+ * callback needs to adjust for variances.
+ *
+ * \param interval the timer delay, in milliseconds, passed to `callback`
+ * \param callback the SDL_TimerCallback function to call when the specified
+ *                 `interval` elapses
+ * \param param a pointer that is passed to `callback`
+ * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
+ *          information.
  *
- * \return A timer ID, or 0 when an error occurs.
+ * \sa SDL_RemoveTimer
  */
 extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval,
                                                  SDL_TimerCallback callback,
                                                  void *param);
 
 /**
- * \brief Remove a timer knowing its ID.
+ * Remove a timer created with SDL_AddTimer().
  *
- * \return A boolean value indicating success or failure.
+ * \param id the ID of the timer to remove
+ * \returns SDL_TRUE if the timer is removed or SDL_FALSE if the timer wasn't
+ *          found.
  *
- * \warning It is not safe to remove a timer multiple times.
+ * \sa SDL_AddTimer
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID id);
 

dep/msvc/sdl2/include/SDL_touch.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -64,30 +64,66 @@ typedef struct SDL_Finger
 #define SDL_MOUSE_TOUCHID ((Sint64)-1)
 
 
-/* Function prototypes */
-
 /**
- *  \brief Get the number of registered touch devices.
+ * Get the number of registered touch devices.
+ *
+ * On some platforms SDL first sees the touch device if it was actually used.
+ * Therefore SDL_GetNumTouchDevices() may return 0 although devices are
+ * available. After using all devices at least once the number will be
+ * correct.
+ *
+ * This was fixed for Android in SDL 2.0.1.
+ *
+ * \returns the number of registered touch devices.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetTouchDevice
  */
 extern DECLSPEC int SDLCALL SDL_GetNumTouchDevices(void);
 
 /**
- *  \brief Get the touch ID with the given index, or 0 if the index is invalid.
+ * Get the touch ID with the given index.
+ *
+ * \param index the touch device index
+ * \returns the touch ID with the given index on success or 0 if the index is
+ *          invalid; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetNumTouchDevices
  */
 extern DECLSPEC SDL_TouchID SDLCALL SDL_GetTouchDevice(int index);
 
 /**
- * \brief Get the type of the given touch device.
+ * Get the type of the given touch device.
  */
 extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID);
 
 /**
- *  \brief Get the number of active fingers for a given touch device.
+ * Get the number of active fingers for a given touch device.
+ *
+ * \param touchID the ID of a touch device
+ * \returns the number of active fingers for a given touch device on success
+ *          or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetTouchFinger
  */
 extern DECLSPEC int SDLCALL SDL_GetNumTouchFingers(SDL_TouchID touchID);
 
 /**
- *  \brief Get the finger object of the given touch, with the given index.
+ * Get the finger object for specified touch device ID and finger index.
+ *
+ * The returned resource is owned by SDL and should not be deallocated.
+ *
+ * \param touchID the ID of the requested touch device
+ * \param index the index of the requested finger
+ * \returns a pointer to the SDL_Finger object or NULL if no object at the
+ *          given ID and index could be found.
+ *
+ * \sa SDL_RecordGesture
  */
 extern DECLSPEC SDL_Finger * SDLCALL SDL_GetTouchFinger(SDL_TouchID touchID, int index);
 

dep/msvc/sdl2/include/SDL_types.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

dep/msvc/sdl2/include/SDL_version.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -37,16 +37,16 @@ extern "C" {
 #endif
 
 /**
- *  \brief Information the version of SDL in use.
+ * Information about the version of SDL in use.
  *
- *  Represents the library's version as three levels: major revision
+ * Represents the library's version as three levels: major revision
- *  (increments with massive changes, additions, and enhancements),
+ * (increments with massive changes, additions, and enhancements),
- *  minor revision (increments with backwards-compatible changes to the
+ * minor revision (increments with backwards-compatible changes to the
- *  major revision), and patchlevel (increments with fixes to the minor
+ * major revision), and patchlevel (increments with fixes to the minor
- *  revision).
+ * revision).
  *
- *  \sa SDL_VERSION
+ * \sa SDL_VERSION
- *  \sa SDL_GetVersion
+ * \sa SDL_GetVersion
  */
 typedef struct SDL_version
 {
@@ -59,22 +59,22 @@ typedef struct SDL_version
 */
 #define SDL_MAJOR_VERSION   2
 #define SDL_MINOR_VERSION   0
-#define SDL_PATCHLEVEL      10
+#define SDL_PATCHLEVEL      16
 
 /**
- *  \brief Macro to determine SDL version program was compiled against.
+ * Macro to determine SDL version program was compiled against.
  *
- *  This macro fills in a SDL_version structure with the version of the
+ * This macro fills in a SDL_version structure with the version of the
- *  library you compiled against. This is determined by what header the
+ * library you compiled against. This is determined by what header the
- *  compiler uses. Note that if you dynamically linked the library, you might
+ * compiler uses. Note that if you dynamically linked the library, you might
- *  have a slightly newer or older version at runtime. That version can be
+ * have a slightly newer or older version at runtime. That version can be
- *  determined with SDL_GetVersion(), which, unlike SDL_VERSION(),
+ * determined with SDL_GetVersion(), which, unlike SDL_VERSION(),
- *  is not a macro.
+ * is not a macro.
  *
- *  \param x A pointer to a SDL_version struct to initialize.
+ * \param x A pointer to a SDL_version struct to initialize.
  *
- *  \sa SDL_version
+ * \sa SDL_version
- *  \sa SDL_GetVersion
+ * \sa SDL_GetVersion
  */
 #define SDL_VERSION(x)                          \
 {                                   \
@@ -107,48 +107,58 @@ typedef struct SDL_version
     (SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
 
 /**
- *  \brief Get the version of SDL that is linked against your program.
+ * Get the version of SDL that is linked against your program.
  *
- *  If you are linking to SDL dynamically, then it is possible that the
+ * If you are linking to SDL dynamically, then it is possible that the current
- *  current version will be different than the version you compiled against.
+ * version will be different than the version you compiled against. This
- *  This function returns the current version, while SDL_VERSION() is a
+ * function returns the current version, while SDL_VERSION() is a macro that
- *  macro that tells you what version you compiled with.
+ * tells you what version you compiled with.
  *
- *  \code
+ * This function may be called safely at any time, even before SDL_Init().
- *  SDL_version compiled;
- *  SDL_version linked;
  *
- *  SDL_VERSION(&compiled);
+ * \param ver the SDL_version structure that contains the version information
- *  SDL_GetVersion(&linked);
- *  printf("We compiled against SDL version %d.%d.%d ...\n",
- *         compiled.major, compiled.minor, compiled.patch);
- *  printf("But we linked against SDL version %d.%d.%d.\n",
- *         linked.major, linked.minor, linked.patch);
- *  \endcode
  *
- *  This function may be called safely at any time, even before SDL_Init().
+ * \sa SDL_GetRevision
- *
- *  \sa SDL_VERSION
  */
 extern DECLSPEC void SDLCALL SDL_GetVersion(SDL_version * ver);
 
 /**
- *  \brief Get the code revision of SDL that is linked against your program.
+ * Get the code revision of SDL that is linked against your program.
+ *
+ * This value is the revision of the code you are linked with and may be
+ * different from the code you are compiling with, which is found in the
+ * constant SDL_REVISION.
+ *
+ * The revision is arbitrary string (a hash value) uniquely identifying the
+ * exact revision of the SDL library in use, and is only useful in comparing
+ * against other revisions. It is NOT an incrementing number.
+ *
+ * If SDL wasn't built from a git repository with the appropriate tools, this
+ * will return an empty string.
+ *
+ * Prior to SDL 2.0.16, before development moved to GitHub, this returned a
+ * hash for a Mercurial repository.
+ *
+ * You shouldn't use this function for anything but logging it for debugging
+ * purposes. The string is not intended to be reliable in any way.
+ *
+ * \returns an arbitrary string, uniquely identifying the exact revision of
+ *          the SDL library in use.
  *
- *  Returns an arbitrary string (a hash value) uniquely identifying the
+ * \sa SDL_GetVersion
- *  exact revision of the SDL library in use, and is only useful in comparing
- *  against other revisions. It is NOT an incrementing number.
  */
 extern DECLSPEC const char *SDLCALL SDL_GetRevision(void);
 
 /**
- *  \brief Get the revision number of SDL that is linked against your program.
+ * Obsolete function, do not use.
  *
- *  Returns a number uniquely identifying the exact revision of the SDL
+ * When SDL was hosted in a Mercurial repository, and was built carefully,
- *  library in use. It is an incrementing number based on commits to
+ * this would return the revision number that the build was created from.
- *  hg.libsdl.org.
+ * This number was not reliable for several reasons, but more importantly,
+ * SDL is now hosted in a git repository, which does not offer numbers at
+ * all, only hashes. This function only ever returns zero now. Don't use it.
  */
-extern DECLSPEC int SDLCALL SDL_GetRevisionNumber(void);
+extern SDL_DEPRECATED DECLSPEC int SDLCALL SDL_GetRevisionNumber(void);
 
 
 /* Ends C function definitions when using C++ */

dep/msvc/sdl2/include/SDL_vulkan.h

@@ -66,203 +66,138 @@ typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */
 /* @{ */
 
 /**
- *  \brief Dynamically load a Vulkan loader library.
+ * Dynamically load the Vulkan loader library.
- *
+ *
- *  \param [in] path The platform dependent Vulkan loader library name, or
+ * This should be called after initializing the video driver, but before
- *              \c NULL.
+ * creating any Vulkan windows. If no Vulkan loader library is loaded, the
- *
+ * default library will be loaded upon creation of the first Vulkan window.
- *  \return \c 0 on success, or \c -1 if the library couldn't be loaded.
+ *
- *
+ * It is fairly common for Vulkan applications to link with libvulkan instead
- *  If \a path is NULL SDL will use the value of the environment variable
+ * of explicitly loading it at run time. This will work with SDL provided the
- *  \c SDL_VULKAN_LIBRARY, if set, otherwise it loads the default Vulkan
+ * application links to a dynamic library and both it and SDL use the same
- *  loader library.
+ * search path.
- *
+ *
- *  This should be called after initializing the video driver, but before
+ * If you specify a non-NULL `path`, an application should retrieve all of the
- *  creating any Vulkan windows. If no Vulkan loader library is loaded, the
+ * Vulkan functions it uses from the dynamic library using
- *  default library will be loaded upon creation of the first Vulkan window.
+ * SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path` points
- *
+ * to the same vulkan loader library the application linked to.
- *  \note It is fairly common for Vulkan applications to link with \a libvulkan
+ *
- *        instead of explicitly loading it at run time. This will work with
+ * On Apple devices, if `path` is NULL, SDL will attempt to find the
- *        SDL provided the application links to a dynamic library and both it
+ * `vkGetInstanceProcAddr` address within all the Mach-O images of the current
- *        and SDL use the same search path.
+ * process. This is because it is fairly common for Vulkan applications to
- *
+ * link with libvulkan (and historically MoltenVK was provided as a static
- *  \note If you specify a non-NULL \c path, an application should retrieve all
+ * library). If it is not found, on macOS, SDL will attempt to load
- *        of the Vulkan functions it uses from the dynamic library using
+ * `vulkan.framework/vulkan`, `libvulkan.1.dylib`,
- *        \c SDL_Vulkan_GetVkGetInstanceProcAddr() unless you can guarantee
+ * `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that order. On
- *        \c path points to the same vulkan loader library the application
+ * iOS, SDL will attempt to load `libMoltenVK.dylib`. Applications using a
- *        linked to.
+ * dynamic framework or .dylib must ensure it is included in its application
- *
+ * bundle.
- *  \note On Apple devices, if \a path is NULL, SDL will attempt to find
+ *
- *        the vkGetInstanceProcAddr address within all the mach-o images of
+ * On non-Apple devices, application linking with a static libvulkan is not
- *        the current process. This is because it is fairly common for Vulkan
+ * supported. Either do not link to the Vulkan loader or link to a dynamic
- *        applications to link with libvulkan (and historically MoltenVK was
+ * library version.
- *        provided as a static library). If it is not found then, on macOS, SDL
+ *
- *        will attempt to load \c vulkan.framework/vulkan, \c libvulkan.1.dylib,
+ * \param path The platform dependent Vulkan loader library name or NULL
- *        followed by \c libvulkan.dylib, in that order.
+ * \returns 0 on success or -1 if the library couldn't be loaded; call
- *        On iOS SDL will attempt to load \c libvulkan.dylib only. Applications
+ *          SDL_GetError() for more information.
- *        using a dynamic framework or .dylib must ensure it is included in its
+ *
- *        application bundle.
+ * \since This function is available in SDL 2.0.8
- *
+ *
- *  \note On non-Apple devices, application linking with a static libvulkan is
+ * \sa SDL_Vulkan_GetVkInstanceProcAddr
- *        not supported. Either do not link to the Vulkan loader or link to a
+ * \sa SDL_Vulkan_UnloadLibrary
- *        dynamic library version.
- *
- *  \note This function will fail if there are no working Vulkan drivers
- *        installed.
- *
- *  \sa SDL_Vulkan_GetVkGetInstanceProcAddr()
- *  \sa SDL_Vulkan_UnloadLibrary()
  */
 extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
 
 /**
- *  \brief Get the address of the \c vkGetInstanceProcAddr function.
+ * Get the address of the `vkGetInstanceProcAddr` function.
  *
- *  \note This should be called after either calling SDL_Vulkan_LoadLibrary
+ * This should be called after either calling SDL_Vulkan_LoadLibrary() or
- *        or creating an SDL_Window with the SDL_WINDOW_VULKAN flag.
+ * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
+ *
+ * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error.
  */
 extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);
 
 /**
- *  \brief Unload the Vulkan loader library previously loaded by
+ * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary()
- *         \c SDL_Vulkan_LoadLibrary().
+ *
+ * \since This function is available in SDL 2.0.8
  *
- *  \sa SDL_Vulkan_LoadLibrary()
+ * \sa SDL_Vulkan_LoadLibrary
  */
 extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
 
 /**
- *  \brief Get the names of the Vulkan instance extensions needed to create
+ * Get the names of the Vulkan instance extensions needed to create a surface
- *         a surface with \c SDL_Vulkan_CreateSurface().
+ * with SDL_Vulkan_CreateSurface.
- *
+ *
- *  \param [in]     \c NULL or window Window for which the required Vulkan instance
+ * If `pNames` is NULL, then the number of required Vulkan instance extensions
- *                  extensions should be retrieved
+ * is returned in `pCount`. Otherwise, `pCount` must point to a variable set
- *  \param [in,out] pCount pointer to an \c unsigned related to the number of
+ * to the number of elements in the `pNames` array, and on return the variable
- *                  required Vulkan instance extensions
+ * is overwritten with the number of names actually written to `pNames`. If
- *  \param [out]    pNames \c NULL or a pointer to an array to be filled with the
+ * `pCount` is less than the number of required extensions, at most `pCount`
- *                  required Vulkan instance extensions
+ * structures will be written. If `pCount` is smaller than the number of
- *
+ * required extensions, SDL_FALSE will be returned instead of SDL_TRUE, to
- *  \return \c SDL_TRUE on success, \c SDL_FALSE on error.
+ * indicate that not all the required extensions were returned.
- *
+ *
- *  If \a pNames is \c NULL, then the number of required Vulkan instance
+ * The `window` parameter is currently needed to be valid as of SDL 2.0.8,
- *  extensions is returned in pCount. Otherwise, \a pCount must point to a
+ * however, this parameter will likely be removed in future releases
- *  variable set to the number of elements in the \a pNames array, and on
+ *
- *  return the variable is overwritten with the number of names actually
+ * \param window A window for which the required Vulkan instance extensions
- *  written to \a pNames. If \a pCount is less than the number of required
+ *               should be retrieved (will be deprecated in a future release)
- *  extensions, at most \a pCount structures will be written. If \a pCount
+ * \param pCount A pointer to an unsigned int corresponding to the number of
- *  is smaller than the number of required extensions, \c SDL_FALSE will be
+ *               extensions to be returned
- *  returned instead of \c SDL_TRUE, to indicate that not all the required
+ * \param pNames NULL or a pointer to an array to be filled with required
- *  extensions were returned.
+ *               Vulkan instance extensions
- *
+ * \returns SDL_TRUE on success, SDL_FALSE on error.
- *  \note If \c window is not NULL, it will be checked against its creation
+ *
- *        flags to ensure that the Vulkan flag is present. This parameter
+ * \since This function is available in SDL 2.0.8
- *        will be removed in a future major release.
+ *
- *
+ * \sa SDL_Vulkan_CreateSurface
- *  \note The returned list of extensions will contain \c VK_KHR_surface
- *        and zero or more platform specific extensions
- *
- *  \note The extension names queried here must be enabled when calling
- *        VkCreateInstance, otherwise surface creation will fail.
- *
- *  \note \c window should have been created with the \c SDL_WINDOW_VULKAN flag
- *        or be \c NULL
- *
- *  \code
- *  unsigned int count;
- *  // get count of required extensions
- *  if(!SDL_Vulkan_GetInstanceExtensions(NULL, &count, NULL))
- *      handle_error();
- *
- *  static const char *const additionalExtensions[] =
- *  {
- *      VK_EXT_DEBUG_REPORT_EXTENSION_NAME, // example additional extension
- *  };
- *  size_t additionalExtensionsCount = sizeof(additionalExtensions) / sizeof(additionalExtensions[0]);
- *  size_t extensionCount = count + additionalExtensionsCount;
- *  const char **names = malloc(sizeof(const char *) * extensionCount);
- *  if(!names)
- *      handle_error();
- *
- *  // get names of required extensions
- *  if(!SDL_Vulkan_GetInstanceExtensions(NULL, &count, names))
- *      handle_error();
- *
- *  // copy additional extensions after required extensions
- *  for(size_t i = 0; i < additionalExtensionsCount; i++)
- *      names[i + count] = additionalExtensions[i];
- *
- *  VkInstanceCreateInfo instanceCreateInfo = {};
- *  instanceCreateInfo.enabledExtensionCount = extensionCount;
- *  instanceCreateInfo.ppEnabledExtensionNames = names;
- *  // fill in rest of instanceCreateInfo
- *
- *  VkInstance instance;
- *  // create the Vulkan instance
- *  VkResult result = vkCreateInstance(&instanceCreateInfo, NULL, &instance);
- *  free(names);
- *  \endcode
- *
- *  \sa SDL_Vulkan_CreateSurface()
  */
-extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(
+extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(SDL_Window *window,
-														SDL_Window *window,
+                                                                  unsigned int *pCount,
-														unsigned int *pCount,
+                                                                  const char **pNames);
-														const char **pNames);
 
 /**
- *  \brief Create a Vulkan rendering surface for a window.
+ * Create a Vulkan rendering surface for a window.
- *
- *  \param [in]  window   SDL_Window to which to attach the rendering surface.
- *  \param [in]  instance handle to the Vulkan instance to use.
- *  \param [out] surface  pointer to a VkSurfaceKHR handle to receive the
- *                        handle of the newly created surface.
- *
- *  \return \c SDL_TRUE on success, \c SDL_FALSE on error.
  *
- *  \code
+ * The `window` must have been created with the `SDL_WINDOW_VULKAN` flag and
- *  VkInstance instance;
+ * `instance` must have been created with extensions returned by
- *  SDL_Window *window;
+ * SDL_Vulkan_GetInstanceExtensions() enabled.
  *
- *  // create instance and window
+ * \param window The window to which to attach the Vulkan surface
+ * \param instance The Vulkan instance handle
+ * \param surface A pointer to a VkSurfaceKHR handle to output the newly
+ *                created surface
+ * \returns SDL_TRUE on success, SDL_FALSE on error.
  *
- *  // create the Vulkan surface
+ * \since This function is available in SDL 2.0.8
- *  VkSurfaceKHR surface;
- *  if(!SDL_Vulkan_CreateSurface(window, instance, &surface))
- *      handle_error();
- *  \endcode
  *
- *  \note \a window should have been created with the \c SDL_WINDOW_VULKAN flag.
+ * \sa SDL_Vulkan_GetInstanceExtensions
- *
+ * \sa SDL_Vulkan_GetDrawableSize
- *  \note \a instance should have been created with the extensions returned
- *        by \c SDL_Vulkan_CreateSurface() enabled.
- *
- *  \sa SDL_Vulkan_GetInstanceExtensions()
  */
-extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(
+extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window,
-												SDL_Window *window,
+                                                          VkInstance instance,
-												VkInstance instance,
+                                                          VkSurfaceKHR* surface);
-												VkSurfaceKHR* surface);
 
 /**
- *  \brief Get the size of a window's underlying drawable in pixels (for use
+ * Get the size of the window's underlying drawable dimensions in pixels.
- *         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
+ * 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
+ * platform with high-DPI support (Apple calls this "Retina"), and not
- * by the \c SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
+ * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint.
+ *
+ * \param window an SDL_Window for which the size is to be queried
+ * \param w Pointer to the variable to write the width to or NULL
+ * \param h Pointer to the variable to write the height to or NULL
  *
- *  \note On macOS high-DPI support must be enabled for an application by
+ * \since This function is available in SDL 2.0.8
- *        setting NSHighResolutionCapable to true in its Info.plist.
  *
- *  \sa SDL_GetWindowSize()
+ * \sa SDL_GetWindowSize
- *  \sa SDL_CreateWindow()
+ * \sa SDL_CreateWindow
+ * \sa SDL_Vulkan_CreateSurface
  */
 extern DECLSPEC void SDLCALL SDL_Vulkan_GetDrawableSize(SDL_Window * window,
                                                         int *w, int *h);

dep/msvc/sdl2/include/begin_code.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -51,15 +51,11 @@
 
 /* Some compilers use a special export keyword */
 #ifndef DECLSPEC
-# if defined(__WIN32__) || defined(__WINRT__)
+# if defined(__WIN32__) || defined(__WINRT__) || defined(__CYGWIN__)
-#  ifdef __BORLANDC__
+#  ifdef DLL_EXPORT
-#   ifdef BUILD_SDL
-#    define DECLSPEC
-#   else
-#    define DECLSPEC    __declspec(dllimport)
-#   endif
-#  else
 #   define DECLSPEC __declspec(dllexport)
+#  else
+#   define DECLSPEC
 #  endif
 # elif defined(__OS2__)
 #   ifdef BUILD_SDL

dep/msvc/sdl2/include/close_code.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages