libs/SDL2/docs/README-versions.md

+# Versioning
+
+## Since 2.23.0
+
+SDL follows an "odd/even" versioning policy, similar to GLib, GTK, Flatpak
+and older versions of the Linux kernel:
+
+* The major version (first part) increases when backwards compatibility
+    is broken, which will happen infrequently.
+
+* If the minor version (second part) is divisible by 2
+    (for example 2.24.x, 2.26.x), this indicates a version of SDL that
+    is believed to be stable and suitable for production use.
+
+    * In stable releases, the patchlevel or micro version (third part)
+        indicates bugfix releases. Bugfix releases should not add or
+        remove ABI, so the ".0" release (for example 2.24.0) should be
+        forwards-compatible with all the bugfix releases from the
+        same cycle (for example 2.24.1).
+
+    * The minor version increases when new API or ABI is added, or when
+        other significant changes are made. Newer minor versions are
+        backwards-compatible, but not fully forwards-compatible.
+        For example, programs built against SDL 2.24.x should work fine
+        with SDL 2.26.x, but programs built against SDL 2.26.x will not
+        necessarily work with 2.24.x.
+
+* If the minor version (second part) is not divisible by 2
+    (for example 2.23.x, 2.25.x), this indicates a development prerelease
+    of SDL that is not suitable for stable software distributions.
+    Use with caution.
+
+    * The patchlevel or micro version (third part) increases with
+        each prerelease.
+
+    * Each prerelease might add new API and/or ABI.
+
+    * Prereleases are backwards-compatible with older stable branches.
+        For example, 2.25.x will be backwards-compatible with 2.24.x.
+
+    * Prereleases are not guaranteed to be backwards-compatible with
+        each other. For example, new API or ABI added in 2.25.1
+        might be removed or changed in 2.25.2.
+        If this would be a problem for you, please do not use prereleases.
+
+    * Only upgrade to a prerelease if you can guarantee that you will
+        promptly upgrade to the stable release that follows it.
+        For example, do not upgrade to 2.23.x unless you will be able to
+        upgrade to 2.24.0 when it becomes available.
+
+    * Software distributions that have a freeze policy (in particular Linux
+        distributions with a release cycle, such as Debian and Fedora)
+        should usually only package stable releases, and not prereleases.
+
+## Before 2.23.0
+
+Older versions of SDL followed a similar policy, but instead of the
+odd/even rule applying to the minor version, it applied to the patchlevel
+(micro version, third part). For example, 2.0.22 was a stable release
+and 2.0.21 was a prerelease.

libs/SDL2/docs/README-visualc.md

+Using SDL with Microsoft Visual C++
+===================================
+
+### by Lion Kimbro with additions by James Turk
+
+You can either use the precompiled libraries from the [SDL](https://www.libsdl.org/download.php) web site, or you can build SDL
+yourself.
+
+### Building SDL
+
+0. To build SDL, your machine must, at a minimum, have the DirectX9.0c SDK installed. It may or may not be retrievable from
+the [Microsoft](https://www.microsoft.com) website, so you might need to locate it [online](https://duckduckgo.com/?q=directx9.0c+sdk+download&t=h_&ia=web).
+_Editor's note: I've been able to successfully build SDL using Visual Studio 2019 **without** the DX9.0c SDK_
+
+1. Open the Visual Studio solution file at `./VisualC/SDL.sln`.
+
+2. Your IDE will likely prompt you to upgrade this solution file to whatever later version of the IDE you're using. In the `Retarget Projects` dialog,
+all of the affected project files should be checked allowing you to use the latest `Windows SDK Version` you have installed, along with
+the `Platform Toolset`.
+
+If you choose *NOT* to upgrade to use the latest `Windows SDK Version` or `Platform Toolset`, then you'll need the `Visual Studio 2010 Platform Toolset`.
+
+3. Build the `.dll` and `.lib` files by right clicking on each project in turn (Projects are listed in the _Workspace_
+panel in the _FileView_ tab), and selecting `Build`.
+
+You may get a few warnings, but you should not get any errors.
+
+Later, we will refer to the following `.lib` and `.dll` files that have just been generated:
+
+-   `./VisualC/Win32/Debug/SDL2.dll` or `./VisualC/Win32/Release/SDL2.dll`
+-   `./VisualC/Win32/Debug/SDL2.lib` or `./VisualC/Win32/Release/SDL2.lib`
+-   `./VisualC/Win32/Debug/SDL2main.lib` or `./VisualC/Win32/Release/SDL2main.lib`
+
+_Note for the `x64` versions, just replace `Win32` in the path with `x64`_
+
+### Creating a Project with SDL
+
+- Create a project as a `Win32 Application`.
+
+- Create a C++ file for your project.
+
+- Set the C runtime to `Multi-threaded DLL` in the menu:
+`Project|Settings|C/C++                  tab|Code Generation|Runtime Library `.
+
+- Add the SDL `include` directory to your list of includes in the menu:
+`Project|Settings|C/C++ tab|Preprocessor|Additional include directories `
+
+*VC7 Specific: Instead of doing this, I find it easier to add the
+include and library directories to the list that VC7 keeps. Do this by
+selecting Tools|Options|Projects|VC++ Directories and under the "Show
+Directories For:" dropbox select "Include Files", and click the "New
+Directory Icon" and add the [SDLROOT]\\include directory (e.g. If you
+installed to c:\\SDL\\ add c:\\SDL\\include). Proceed to change the
+dropbox selection to "Library Files" and add [SDLROOT]\\lib.*
+
+The "include directory" I am referring to is the `./include` folder.
+
+Now we're going to use the files that we had created earlier in the *Build SDL* step.
+
+Copy the following file into your Project directory:
+
+-   `SDL2.dll`
+
+Add the following files to your project (It is not necessary to copy them to your project directory):
+
+-   `SDL2.lib`
+-   `SDL2main.lib`
+
+To add them to your project, right click on your project, and select
+`Add files to project`.
+
+**Instead of adding the files to your project, it is more desirable to add them to the linker options: Project|Properties|Linker|Command Line
+and type the names of the libraries to link with in the "Additional Options:" box. Note: This must be done for each build configuration
+(e.g. Release,Debug).**
+
+### Hello SDL2
+
+Here's a sample SDL snippet to verify everything is setup in your IDE:
+
+```
+    #include "SDL.h"
+
+    int main( int argc, char* argv[] )
+    {
+        const int WIDTH = 640;
+        const int HEIGHT = 480;
+        SDL_Window* window = NULL;
+        SDL_Renderer* renderer = NULL;
+
+        SDL_Init(SDL_INIT_VIDEO);
+        window = SDL_CreateWindow("SDL2 Test", SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED, WIDTH, HEIGHT, SDL_WINDOW_SHOWN);
+        renderer = SDL_CreateRenderer(window, -1, SDL_RENDERER_ACCELERATED | SDL_RENDERER_PRESENTVSYNC);
+
+        SDL_DestroyRenderer(renderer);
+        SDL_DestroyWindow(window);
+        SDL_Quit();
+        return 0;
+    }
+ ```
+
+### That's it!
+
+I hope that this document has helped you get through the most difficult part of using the SDL: installing it.
+Suggestions for improvements should be posted to the [Github Issues](https://github.com/libsdl-org/SDL/issues).
+
+### Credits
+
+Thanks to [Paulus Esterhazy](mailto:pesterhazy@gmx.net), for the work on VC++ port.
+
+This document was originally called "VisualC.txt", and was written by [Sam Lantinga](mailto:slouken@libsdl.org).
+
+Later, it was converted to HTML and expanded into the document that you see today by [Lion Kimbro](mailto:snowlion@sprynet.com).
+
+Minor Fixes and Visual C++ 7 Information (In Green) was added by [James Turk](mailto:james@conceptofzero.net)

libs/SDL2/docs/README-vita.md

+PS Vita
+=======
+SDL port for the Sony Playstation Vita and Sony Playstation TV
+
+Credit to
+* xerpi, cpasjuste and rsn8887 for initial (vita2d) port
+* vitasdk/dolcesdk devs
+* CBPS discord (Namely Graphene and SonicMastr)
+
+Building
+--------
+To build for the PSVita, make sure you have vitasdk and cmake installed and run:
+```
+   cmake -S. -Bbuild -DCMAKE_TOOLCHAIN_FILE=${VITASDK}/share/vita.toolchain.cmake -DCMAKE_BUILD_TYPE=Release
+   cmake --build build
+   cmake --install build
+```
+
+
+Notes
+-----
+* gles1/gles2 support and renderers are disabled by default and can be enabled by configuring with `-DVIDEO_VITA_PVR=ON`
+  These renderers support 720p and 1080i resolutions. These can be specified with:
+  `SDL_setenv("VITA_RESOLUTION", "720", 1);` and `SDL_setenv("VITA_RESOLUTION", "1080", 1);`
+* Desktop GL 1.X and 2.X support and renderers are also disabled by default and also can be enabled with `-DVIDEO_VITA_PVR=ON` as long as gl4es4vita is present in your SDK.
+  They support the same resolutions as the gles1/gles2 backends and require specifying `SDL_setenv("VITA_PVR_OGL", "1", 1);`
+  anytime before video subsystem initialization.
+* gles2 support via PIB is disabled by default and can be enabled by configuring with `-DVIDEO_VITA_PIB=ON`
+* By default SDL emits mouse events for touch events on every touchscreen.
+  Vita has two touchscreens, so it's recommended to use `SDL_SetHint(SDL_HINT_TOUCH_MOUSE_EVENTS, "0");` and handle touch events instead.
+  Individual touchscreens can be disabled with:
+  `SDL_setenv("VITA_DISABLE_TOUCH_FRONT", "1", 1);` and `SDL_setenv("VITA_DISABLE_TOUCH_BACK", "1", 1);`
+* Support for L2/R2/R3/R3 buttons, haptic feedback and gamepad led only available on PSTV, or when using external ds4 gamepad on vita.

libs/SDL2/docs/README-windows.md

-Windows
-================================================================================
+# Windows
 
-================================================================================
-OpenGL ES 2.x support
-================================================================================
+## LLVM and Intel C++ compiler support
+
+SDL will build with the Visual Studio project files with LLVM-based compilers, such as the Intel oneAPI C++
+compiler, but you'll have to manually add the "-msse3" command line option
+to at least the SDL_audiocvt.c source file, and possibly others. This may
+not be necessary if you build SDL with CMake instead of the included Visual
+Studio solution.
+
+Details are here: https://github.com/libsdl-org/SDL/issues/5186
+
+
+## OpenGL ES 2.x support
 
 SDL has support for OpenGL ES 2.x under Windows via two alternative
 implementations.
+
 The most straightforward method consists in running your app in a system with
 a graphic card paired with a relatively recent (as of November of 2013) driver
 which supports the WGL_EXT_create_context_es2_profile extension. Vendors known
 to ship said extension on Windows currently include nVidia and Intel.
 
-The other method involves using the ANGLE library (https://code.google.com/p/angleproject/)
-If an OpenGL ES 2.x context is requested and no WGL_EXT_create_context_es2_profile
-extension is found, SDL will try to load the libEGL.dll library provided by
-ANGLE.
+The other method involves using the
+[ANGLE library](https://code.google.com/p/angleproject/). If an OpenGL ES 2.x
+context is requested and no WGL_EXT_create_context_es2_profile extension is
+found, SDL will try to load the libEGL.dll library provided by ANGLE.
+
 To obtain the ANGLE binaries, you can either compile from source from
-https://chromium.googlesource.com/angle/angle or copy the relevant binaries from
-a recent Chrome/Chromium install for Windows. The files you need are:
+https://chromium.googlesource.com/angle/angle or copy the relevant binaries
+from a recent Chrome/Chromium install for Windows. The files you need are:
 
-    * libEGL.dll
-    * libGLESv2.dll
-    * d3dcompiler_46.dll (supports Windows Vista or later, better shader compiler)
-    or...
-    * d3dcompiler_43.dll (supports Windows XP or later)
+- libEGL.dll
+- libGLESv2.dll
+- d3dcompiler_46.dll (supports Windows Vista or later, better shader
+  compiler) *or* d3dcompiler_43.dll (supports Windows XP or later)
 
 If you compile ANGLE from source, you can configure it so it does not need the
 d3dcompiler_* DLL at all (for details on this, see their documentation).
 However, by default SDL will try to preload the d3dcompiler_46.dll to
-comply with ANGLE's requirements. If you wish SDL to preload d3dcompiler_43.dll (to
-support Windows XP) or to skip this step at all, you can use the 
-SDL_HINT_VIDEO_WIN_D3DCOMPILER hint (see SDL_hints.h for more details).
+comply with ANGLE's requirements. If you wish SDL to preload
+d3dcompiler_43.dll (to support Windows XP) or to skip this step at all, you
+can use the SDL_HINT_VIDEO_WIN_D3DCOMPILER hint (see SDL_hints.h for more
+details).
 
 Known Bugs:
 
-    * SDL_GL_SetSwapInterval is currently a no op when using ANGLE. It appears
+- SDL_GL_SetSwapInterval is currently a no op when using ANGLE. It appears
   that there's a bug in the library which prevents the window contents from
   refreshing if this is set to anything other than the default value.
 
+## Vulkan Surface Support
+
+Support for creating Vulkan surfaces is configured on by default. To disable
+it change the value of `SDL_VIDEO_VULKAN` to 0 in `SDL_config_windows.h`. You
+must install the [Vulkan SDK](https://www.lunarg.com/vulkan-sdk/) in order to
+use Vulkan graphics in your application.
+

libs/SDL2/docs/README-winrt.md

@@ -2,44 +2,24 @@ WinRT
 =====
 
 This port allows SDL applications to run on Microsoft's platforms that require
-use of "Windows Runtime", aka. "WinRT", APIs.  WinRT apps are currently
-full-screen only, and run in what Microsoft sometimes refers to as their
-"Modern" (formerly, "Metro"), environment.  For Windows 8.x, Microsoft may also
-refer to them as "Windows Store" apps, due to them being distributed,
-primarily, via a Microsoft-run online store (of the same name).
+use of "Windows Runtime", aka. "WinRT", APIs.  Microsoft may, in some cases,
+refer to them as either "Windows Store", or for Windows 10, "UWP" apps.
 
-Some of the operating systems that include WinRT, are:
-
-* Windows 10, via its Universal Windows Platform (UWP) APIs
-* Windows 8.x
-* Windows RT 8.x (aka. Windows 8.x for ARM processors)
-* Windows Phone 8.x
+In the past, SDL has supported Windows RT 8.x, Windows Phone, etc, but in
+modern times this port is focused on UWP apps, which run on Windows 10,
+and modern Xbox consoles.
 
 
 Requirements
 ------------
 
-* Microsoft Visual C++ (aka Visual Studio), either 2015, 2013, or 2012
+* Microsoft Visual C++ (aka Visual Studio) 2019.
   - Free, "Community" or "Express" editions may be used, so long as they
     include support for either "Windows Store" or "Windows Phone" apps.
     "Express" versions marked as supporting "Windows Desktop" development
     typically do not include support for creating WinRT apps, to note.
     (The "Community" editions of Visual C++ do, however, support both
     desktop/Win32 and WinRT development).
-  - Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
-    or  Windows Phone.  8.0-targetted apps will run on devices running 8.1
-    editions of Windows, however they will not be able to take advantage of
-    8.1-specific features.
-  - Visual C++ 2013 cannot create app projects that target Windows 8.0.
-    Visual C++ 2013 Update 4, can create app projects for Windows Phone 8.0,
-    Windows Phone 8.1, and Windows 8.1, but not Windows 8.0.  An optional
-    Visual Studio add-in, "Tools for Maintaining Store apps for Windows 8",
-    allows Visual C++ 2013 to load and build Windows 8.0 projects that were
-    created with Visual C++ 2012, so long as Visual C++ 2012 is installed
-    on the same machine.  More details on targeting different versions of
-    Windows can found at the following web pages:
-      - [Develop apps by using Visual Studio 2013](http://msdn.microsoft.com/en-us/library/windows/apps/br211384.aspx)
-      - [To add the Tools for Maintaining Store apps for Windows 8](http://msdn.microsoft.com/en-us/library/windows/apps/dn263114.aspx#AddMaintenanceTools)
 * A valid Microsoft account - This requirement is not imposed by SDL, but
   rather by Microsoft's Visual C++ toolchain.  This is required to launch or
   debug apps.
@@ -48,10 +28,10 @@ Requirements
 Status
 ------
 
-Here is a rough list of what works, and what doens't:
+Here is a rough list of what works, and what doesn't:
 
 * What works:
-  * compilation via Visual C++ 2012 through 2015
+  * compilation via Visual C++ 2019.
   * compile-time platform detection for SDL programs.  The C/C++ #define,
     `__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
   * GPU-accelerated 2D rendering, via SDL_Renderer.
@@ -64,12 +44,18 @@ Here is a rough list of what works, and what doens't:
     SDL_GetPerformanceFrequency(), etc.)
   * file I/O via SDL_RWops
   * mouse input  (unsupported on Windows Phone)
-  * audio, via a modified version of SDL's XAudio2 backend
+  * audio, via SDL's WASAPI backend (if you want to record, your app must
+    have "Microphone" capabilities enabled in its manifest, and the user must
+    not have blocked access. Otherwise, capture devices will fail to work,
+    presenting as a device disconnect shortly after opening it.)
   * .DLL file loading.  Libraries *MUST* be packaged inside applications.  Loading
     anything outside of the app is not supported.
   * system path retrieval via SDL's filesystem APIs
   * game controllers.  Support is provided via the SDL_Joystick and
-    SDL_GameController APIs, and is backed by Microsoft's XInput API.
+    SDL_GameController APIs, and is backed by Microsoft's XInput API.  Please
+    note, however, that Windows limits game-controller support in UWP apps to,
+    "Xbox compatible controllers" (many controllers that work in Win32 apps,
+    do not work in UWP, due to restrictions in UWP itself.)
   * multi-touch input
   * app events.  SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
     appropriate.
@@ -82,7 +68,9 @@ Here is a rough list of what works, and what doens't:
 
 * What partially works:
   * keyboard input.  Most of WinRT's documented virtual keys are supported, as
-    well as many keys with documented hardware scancodes.
+    well as many keys with documented hardware scancodes.  Converting
+    SDL_Scancodes to or from SDL_Keycodes may not work, due to missing APIs
+    (MapVirtualKey()) in Microsoft's Windows Store / UWP APIs.
   * SDLmain.  WinRT uses a different signature for each app's main() function.
     SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
     (in `SDL\src\main\winrt\`) directly in order for their C-style main()
@@ -95,8 +83,10 @@ Here is a rough list of what works, and what doens't:
     SDL_CreateSystemCursor() (unsupported on Windows Phone)
   * SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal().  This are not currently
     supported by WinRT itself.
-  * joysticks and game controllers that aren't supported by Microsoft's XInput
-    API.
+  * joysticks and game controllers that either are not supported by
+    Microsoft's XInput API, or are not supported within UWP apps (many
+    controllers that work in Win32, do not work in UWP, due to restrictions in
+    UWP itself).
   * turning off VSync when rendering on Windows Phone.  Attempts to turn VSync
     off on Windows Phone result either in Direct3D not drawing anything, or it
     forcing VSync back on.  As such, SDL_RENDERER_PRESENTVSYNC will always get
@@ -160,7 +150,9 @@ following, at a high-level:
    the linker, and will copy SDL's .dll files to your app's final output.
 4. adjust your app's build settings, at minimum, telling it where to find SDL's
    header files.
-5. add a file that contains a WinRT-appropriate main function.
+5. add files that contains a WinRT-appropriate main function, along with some
+   data to make sure mouse-cursor-hiding (via SDL_ShowCursor(SDL_DISABLE) calls)
+   work properly.
 6. add SDL-specific app code.
 7. build and run your app.
 
@@ -216,13 +208,8 @@ To set this up for SDL/WinRT, you'll need to run through the following steps:
    "Solution Explorer")
 2. right click on your app's solution.
 3. navigate to "Add", then to "Existing Project..."
-4. find SDL/WinRT's Visual C++ project file and open it.  Different project
-   files exist for different WinRT platforms.  All of them are in SDL's
-   source distribution, in the following directories:
-    * `VisualC-WinRT/UWP_VS2015/`        - for Windows 10 / UWP apps
-    * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
-    * `VisualC-WinRT/WinRT80_VS2012/`    - for Windows 8.0 apps
-    * `VisualC-WinRT/WinRT81_VS2013/`    - for Windows 8.1 apps
+4. find SDL/WinRT's Visual C++ project file and open it, in the `VisualC-WinRT`
+   directory.
 5. once the project has been added, right-click on your app's project and
    select, "References..."
 6. click on the button titled, "Add New Reference..."
@@ -268,39 +255,41 @@ To change these settings:
 10. close the dialog, saving settings, by clicking the "OK" button
 
 
-### 5. Add a WinRT-appropriate main function to the app. ###
-
-C/C++-based WinRT apps do contain a `main` function that the OS will invoke when 
-the app starts launching. The parameters of WinRT main functions are different 
-than those found on other platforms, Win32 included.  SDL/WinRT provides a 
-platform-appropriate main function that will perform these actions, setup key 
-portions of the app, then invoke a classic, C/C++-style main function (that take 
-in "argc" and "argv" parameters).  The code for this file is contained inside 
-SDL's source distribution, under `src/main/winrt/SDL_winrt_main_NonXAML.cpp`.  
-You'll need to add this file, or a copy of it, to your app's project, and make 
-sure it gets compiled using a Microsoft-specific set of C++ extensions called 
-C++/CX.
+### 5. Add a WinRT-appropriate main function, and a blank-cursor image, to the app. ###
 
-**NOTE: C++/CX compilation is currently required in at least one file of your 
-app's project.  This is to make sure that Visual C++'s linker builds a 'Windows 
-Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.**
+A few files should be included directly in your app's MSVC project, specifically:
+1. a WinRT-appropriate main function (which is different than main() functions on
+   other platforms)
+2. a Win32-style cursor resource, used by SDL_ShowCursor() to hide the mouse cursor
+   (if and when the app needs to do so).  *If this cursor resource is not
+   included, mouse-position reporting may fail if and when the cursor is
+   hidden, due to possible bugs/design-oddities in Windows itself.*
 
-To include `SDL_winrt_main_NonXAML.cpp`:
+To include these files for C/C++ projects:
 
 1. right-click on your project (again, in Visual C++'s Solution Explorer),
    navigate to "Add", then choose "Existing Item...".
-2. open `SDL_winrt_main_NonXAML.cpp`, which is found inside SDL's source 
-   distribution, under `src/main/winrt/`.  Make sure that the open-file dialog 
-   closes, either by double-clicking on the file, or single-clicking on it and 
-   then clicking Add.
-3. right-click on the file (as listed in your project), then click on 
-   "Properties...".
+2. navigate to the directory containing SDL's source code, then into its
+   subdirectory, 'src/main/winrt/'.  Select, then add, the following files:
+   - `SDL_winrt_main_NonXAML.cpp`
+   - `SDL2-WinRTResources.rc`
+   - `SDL2-WinRTResource_BlankCursor.cur`
+3. right-click on the file `SDL_winrt_main_NonXAML.cpp` (as listed in your
+   project), then click on "Properties...".
 4. in the drop-down box next to "Configuration", choose, "All Configurations"
 5. in the drop-down box next to "Platform", choose, "All Platforms"
 6. in the left-hand list, click on "C/C++"
 7. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
 8. click the OK button.  This will close the dialog.
 
+**NOTE: C++/CX compilation is currently required in at least one file of your
+app's project.  This is to make sure that Visual C++'s linker builds a 'Windows
+Metadata' file (.winmd) for your app.  Not doing so can lead to build errors.**
+
+For non-C++ projects, you will need to call SDL_WinRTRunApp from your language's
+main function, and generate SDL2-WinRTResources.res manually by using `rc` via
+the Developer Command Prompt and including it as a <Win32Resource> within the
+first <PropertyGroup> block in your Visual Studio project file.
 
 ### 6. Add app code and assets ###
 
@@ -332,7 +321,7 @@ source file, such as, "main.cpp".
 your project, and open the file in Visual C++'s text editor.
 7. Copy and paste the following code into the new file, then save it.
 
-
+```c
 #include <SDL.h>
 
 int main(int argc, char **argv)
@@ -341,29 +330,32 @@ your project, and open the file in Visual C++'s text editor.
     SDL_Window * window = NULL;
     SDL_Renderer * renderer = NULL;
     SDL_Event evt;
+    SDL_bool keep_going = SDL_TRUE;
 
     if (SDL_Init(SDL_INIT_VIDEO) != 0) {
         return 1;
-        }
-    
-        if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
+    } else if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
         return 1;
-        }
-    
-        if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
+    } else if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
         return 1;
     }
 
-        while (1) {
+    while (keep_going) {
         while (SDL_PollEvent(&evt)) {
+            if ((evt.type == SDL_KEYDOWN) && (evt.key.keysym.sym == SDLK_ESCAPE)) {
+                keep_going = SDL_FALSE;
+            }
         }
 
         SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
         SDL_RenderClear(renderer);
         SDL_RenderPresent(renderer);
     }
-    }
 
+    SDL_Quit();
+    return 0;
+}
+```
 
 #### 6.B. Adding code and assets ####
 
@@ -466,3 +458,62 @@ section.
 
     /nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib
 
+
+#### Mouse-motion events fail to get sent, or SDL_GetMouseState() fails to return updated values
+
+This may be caused by a bug in Windows itself, whereby hiding the mouse
+cursor can cause mouse-position reporting to fail.
+
+SDL provides a workaround for this, but it requires that an app links to a
+set of Win32-style cursor image-resource files.  A copy of suitable resource
+files can be found in `src/main/winrt/`.  Adding them to an app's Visual C++
+project file should be sufficient to get the app to use them.
+
+
+#### SDL's Visual Studio project file fails to open, with message, "The system can't find the file specified."
+
+This can be caused for any one of a few reasons, which Visual Studio can
+report, but won't always do so in an up-front manner.
+
+To help determine why this error comes up:
+
+1. open a copy of Visual Studio without opening a project file.  This can be
+   accomplished via Windows' Start Menu, among other means.
+2. show Visual Studio's Output window.  This can be done by going to VS'
+   menu bar, then to View, and then to Output.
+3. try opening the SDL project file directly by going to VS' menu bar, then
+   to File, then to Open, then to Project/Solution.  When a File-Open dialog
+   appears, open the SDL project (such as the one in SDL's source code, in its
+   directory, VisualC-WinRT/UWP_VS2015/).
+4. after attempting to open SDL's Visual Studio project file, additional error
+   information will be output to the Output window.
+
+If Visual Studio reports (via its Output window) that the project:
+
+"could not be loaded because it's missing install components. To fix this launch Visual Studio setup with the following selections:
+Microsoft.VisualStudio.ComponentGroup.UWP.VC"
+
+... then you will need to re-launch Visual Studio's installer, and make sure that
+the workflow for "Universal Windows Platform development" is checked, and that its
+optional component, "C++ Universal Windows Platform tools" is also checked.  While
+you are there, if you are planning on targeting UWP / Windows 10, also make sure
+that you check the optional component, "Windows 10 SDK (10.0.10240.0)".  After
+making sure these items are checked as-appropriate, install them.
+
+Once you install these components, try re-launching Visual Studio, and re-opening
+the SDL project file.  If you still get the error dialog, try using the Output
+window, again, seeing what Visual Studio says about it.
+
+
+#### Game controllers / joysticks aren't working!
+
+Windows only permits certain game controllers and joysticks to work within
+WinRT / UWP apps.  Even if a game controller or joystick works in a Win32
+app, that device is not guaranteed to work inside a WinRT / UWP app.
+
+According to Microsoft, "Xbox compatible controllers" should work inside
+UWP apps, potentially with more working in the future.  This includes, but
+may not be limited to, Microsoft-made Xbox controllers and USB adapters.
+(Source: https://social.msdn.microsoft.com/Forums/en-US/9064838b-e8c3-4c18-8a83-19bf0dfe150d/xinput-fails-to-detect-game-controllers?forum=wpdevelop)
+
+

libs/SDL2/docs/README.md

-Simple DirectMedia Layer {#mainpage}
-========================
+# Simple DirectMedia Layer
 
-                                  (SDL)
-
-                                Version 2.0
-
----
-http://www.libsdl.org/
+https://www.libsdl.org/
 
 Simple DirectMedia Layer is a cross-platform development library designed
 to provide low level access to audio, keyboard, mouse, joystick, and graphics
@@ -14,14 +8,14 @@ hardware via OpenGL and Direct3D. It is used by video playback software,
 emulators, and popular games including Valve's award winning catalog
 and many Humble Bundle games.
 
-SDL officially supports Windows, Mac OS X, Linux, iOS, and Android.
+SDL officially supports Windows, macOS, Linux, iOS, and Android.
 Support for other platforms may be found in the source code.
 
 SDL is written in C, works natively with C++, and there are bindings 
 available for several other languages, including C# and Python.
 
 This library is distributed under the zlib license, which can be found
-in the file "COPYING.txt".
+in the file "LICENSE.txt".
 
 The best way to learn how to use SDL is to check out the header files in
 the "include" subdirectory and the programs in the "test" subdirectory.
@@ -34,30 +28,36 @@ More documentation and FAQs are available online at [the wiki](http://wiki.libsd
 - [DirectFB](README-directfb.md)
 - [DynAPI](README-dynapi.md)
 - [Emscripten](README-emscripten.md)
+- [GDK](README-gdk.md)
 - [Gesture](README-gesture.md)
-- [Mercurial](README-hg.md)
+- [Git](README-git.md)
 - [iOS](README-ios.md)
 - [Linux](README-linux.md)
-- [OS X](README-macosx.md)
+- [macOS](README-macos.md)
+- [OS/2](README-os2.md)
 - [Native Client](README-nacl.md)
 - [Pandora](README-pandora.md)
 - [Supported Platforms](README-platforms.md)
 - [Porting information](README-porting.md)
 - [PSP](README-psp.md)
+- [PS2](README-ps2.md)
 - [Raspberry Pi](README-raspberrypi.md)
 - [Touch](README-touch.md)
+- [Versions](README-versions.md)
 - [WinCE](README-wince.md)
 - [Windows](README-windows.md)
 - [WinRT](README-winrt.md)
+- [PSVita](README-vita.md)
+- [Nokia N-Gage](README-ngage.md)
 
 If you need help with the library, or just want to discuss SDL related
-issues, you can join the [developers mailing list](http://www.libsdl.org/mailing-list.php)
+issues, you can join the [SDL Discourse](https://discourse.libsdl.org/),
+which can be used as a web forum or a mailing list, at your preference.
 
 If you want to report bugs or contribute patches, please submit them to
-[bugzilla](http://bugzilla.libsdl.org/)
+[our bug tracker](https://github.com/libsdl-org/SDL/issues)
 
 Enjoy!
 
 
 Sam Lantinga <mailto:slouken@libsdl.org>
-

libs/SDL2/docs/doxyfile

@@ -640,6 +640,7 @@ EXCLUDE                = ../include/SDL_opengles2_gl2ext.h \
                          ../include/SDL_opengles.h \
                          ../include/SDL_opengl.h \
                          ../include/SDL_egl.h \
+                         ./release_checklist.md \
 
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or 

libs/SDL2/docs/release_checklist.md

+# Release checklist
+
+When changing the version, run `build-scripts/update-version.sh X Y Z`,
+where `X Y Z` are the major version, minor version, and patch level. So
+`2 28 1` means "change the version to 2.28.1". This script does much of the
+mechanical work.
+
+
+## New feature release
+
+* Update `WhatsNew.txt`
+
+* Bump version number to 2.EVEN.0:
+
+    * `./build-scripts/update-version.sh 2 EVEN 0`
+
+* Do the release
+
+* Update the website file include/header.inc.php to reflect the new version
+
+## New bugfix release
+
+* Check that no new API/ABI was added
+
+    * If it was, do a new feature release (see above) instead
+
+* Bump version number from 2.Y.Z to 2.Y.(Z+1) (Y is even)
+
+    * `./build-scripts/update-version.sh 2 Y Z+1`
+
+* Do the release
+
+* Update the website file include/header.inc.php to reflect the new version
+
+## After a feature release
+
+* Create a branch like `release-2.24.x`
+
+* Bump version number to 2.ODD.0 for next development branch
+
+    * `./build-scripts/update-version.sh 2 ODD 0`
+
+## New development prerelease
+
+* Bump version number from 2.Y.Z to 2.Y.(Z+1) (Y is odd)
+
+    * `./build-scripts/update-version.sh 2 Y Z+1`
+
+* Do the release

libs/SDL2/i686-w64-mingw32/bin/sdl2-config

 #!/bin/sh
 
-prefix=/usr/local/cross-tools/i686-w64-mingw32
+# Get the canonical path of the folder containing this script
+bindir=$(cd -P -- "$(dirname -- "$0")" && printf '%s\n' "$(pwd -P)")
+
+# Calculate the canonical path of the prefix, relative to the folder of this script
+prefix=$(cd -P -- "$bindir/.." && printf '%s\n' "$(pwd -P)")
 exec_prefix=${prefix}
 exec_prefix_set=no
 libdir=${exec_prefix}/lib
@@ -39,7 +43,7 @@ while test $# -gt 0; do
       echo $exec_prefix
       ;;
     --version)
-      echo 2.0.4
+      echo 2.28.5
       ;;
     --cflags)
       echo -I${prefix}/include/SDL2  -Dmain=SDL_main
@@ -49,7 +53,8 @@ while test $# -gt 0; do
       ;;
     --static-libs)
 #    --libs|--static-libs)
-      echo -L${exec_prefix}/lib  -lmingw32 -lSDL2main -lSDL2  -mwindows  -Wl,--no-undefined -lm -ldinput8 -ldxguid -ldxerr8 -luser32 -lgdi32 -lwinmm -limm32 -lole32 -loleaut32 -lshell32 -lversion -luuid -static-libgcc
+      sdl_static_libs=$(echo "-lmingw32 -lSDL2main -lSDL2 -mwindows  -Wl,--dynamicbase -Wl,--nxcompat -lm -ldinput8 -ldxguid -ldxerr8 -luser32 -lgdi32 -lwinmm -limm32 -lole32 -loleaut32 -lshell32 -lsetupapi -lversion -luuid" | sed -E "s#-lSDL2[ $]#$libdir/libSDL2.a #g")
+      echo -L${exec_prefix}/lib $sdl_static_libs
       ;;
     *)
       echo "${usage}" 1>&2

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 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
@@ -26,8 +26,8 @@
  */
 
 
-#ifndef _SDL_H
-#define _SDL_H
+#ifndef SDL_h_
+#define SDL_h_
 
 #include "SDL_main.h"
 #include "SDL_stdinc.h"
@@ -40,22 +40,29 @@
 #include "SDL_error.h"
 #include "SDL_events.h"
 #include "SDL_filesystem.h"
-#include "SDL_joystick.h"
 #include "SDL_gamecontroller.h"
+#include "SDL_guid.h"
 #include "SDL_haptic.h"
+#include "SDL_hidapi.h"
 #include "SDL_hints.h"
+#include "SDL_joystick.h"
 #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"
 #include "SDL_rwops.h"
+#include "SDL_sensor.h"
+#include "SDL_shape.h"
 #include "SDL_system.h"
 #include "SDL_thread.h"
 #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++ */
@@ -72,52 +79,146 @@ extern "C" {
  *  specify the subsystems which you will be using in your application.
  */
 /* @{ */
-#define SDL_INIT_TIMER          0x00000001
-#define SDL_INIT_AUDIO          0x00000010
-#define SDL_INIT_VIDEO          0x00000020  /**< SDL_INIT_VIDEO implies SDL_INIT_EVENTS */
-#define SDL_INIT_JOYSTICK       0x00000200  /**< SDL_INIT_JOYSTICK implies SDL_INIT_EVENTS */
-#define SDL_INIT_HAPTIC         0x00001000
-#define SDL_INIT_GAMECONTROLLER 0x00002000  /**< SDL_INIT_GAMECONTROLLER implies SDL_INIT_JOYSTICK */
-#define SDL_INIT_EVENTS         0x00004000
-#define SDL_INIT_NOPARACHUTE    0x00100000  /**< compatibility; this flag is ignored. */
+#define SDL_INIT_TIMER          0x00000001u
+#define SDL_INIT_AUDIO          0x00000010u
+#define SDL_INIT_VIDEO          0x00000020u  /**< SDL_INIT_VIDEO implies SDL_INIT_EVENTS */
+#define SDL_INIT_JOYSTICK       0x00000200u  /**< SDL_INIT_JOYSTICK implies SDL_INIT_EVENTS */
+#define SDL_INIT_HAPTIC         0x00001000u
+#define SDL_INIT_GAMECONTROLLER 0x00002000u  /**< SDL_INIT_GAMECONTROLLER implies SDL_INIT_JOYSTICK */
+#define SDL_INIT_EVENTS         0x00004000u
+#define SDL_INIT_SENSOR         0x00008000u
+#define SDL_INIT_NOPARACHUTE    0x00100000u  /**< compatibility; this flag is ignored. */
 #define SDL_INIT_EVERYTHING ( \
                 SDL_INIT_TIMER | SDL_INIT_AUDIO | SDL_INIT_VIDEO | SDL_INIT_EVENTS | \
-                SDL_INIT_JOYSTICK | SDL_INIT_HAPTIC | SDL_INIT_GAMECONTROLLER \
+                SDL_INIT_JOYSTICK | SDL_INIT_HAPTIC | SDL_INIT_GAMECONTROLLER | SDL_INIT_SENSOR \
             )
 /* @} */
 
 /**
- *  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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  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.
+ * \sa SDL_Init
+ * \sa SDL_Quit
+ * \sa SDL_QuitSubSystem
  */
 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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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
- *  previously been initialized.
+ * Get a mask of the specified subsystems which are currently initialized.
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it
+ *          returns the initialization status of the specified subsystems.
+ *
+ *          The return value does not include SDL_INIT_NOPARACHUTE.
  *
- *  If \c flags is 0, it returns a mask of all initialized subsystems.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Init
+ * \sa SDL_InitSubSystem
  */
 extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
 
 /**
- *  This function cleans up all initialized subsystems. You should
- *  call it upon all exit conditions.
+ * Clean up all initialized subsystems.
+ *
+ * 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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Init
+ * \sa SDL_QuitSubSystem
  */
 extern DECLSPEC void SDLCALL SDL_Quit(void);
 
@@ -127,6 +228,6 @@ extern DECLSPEC void SDLCALL SDL_Quit(void);
 #endif
 #include "close_code.h"
 
-#endif /* _SDL_H */
+#endif /* SDL_h_ */
 
 /* vi: set ts=4 sw=4 expandtab: */

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_assert.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 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
@@ -19,10 +19,10 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-#ifndef _SDL_assert_h
-#define _SDL_assert_h
+#ifndef SDL_assert_h_
+#define SDL_assert_h_
 
-#include "SDL_config.h"
+#include "SDL_stdinc.h"
 
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
@@ -51,9 +51,19 @@ assert can have unique static variables associated with it.
 /* Don't include intrin.h here because it contains C++ code */
     extern void __cdecl __debugbreak(void);
     #define SDL_TriggerBreakpoint() __debugbreak()
-#elif (!defined(__NACL__) && defined(__GNUC__) && (defined(__i386__) || defined(__x86_64__)))
+#elif _SDL_HAS_BUILTIN(__builtin_debugtrap)
+    #define SDL_TriggerBreakpoint() __builtin_debugtrap()
+#elif ( (!defined(__NACL__)) && ((defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))) )
     #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" )
-#elif defined(HAVE_SIGNAL_H)
+#elif (defined(__GNUC__) || defined(__clang__)) && defined(__riscv)
+    #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "ebreak\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__)
     #include <signal.h>
     #define SDL_TriggerBreakpoint() raise(SIGTRAP)
 #else
@@ -63,7 +73,7 @@ assert can have unique static variables associated with it.
 
 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */
 #   define SDL_FUNCTION __func__
-#elif ((__GNUC__ >= 2) || defined(_MSC_VER))
+#elif ((defined(__GNUC__) && (__GNUC__ >= 2)) || defined(_MSC_VER) || defined (__WATCOMC__))
 #   define SDL_FUNCTION __FUNCTION__
 #else
 #   define SDL_FUNCTION "???"
@@ -117,8 +127,6 @@ typedef struct SDL_AssertData
     const struct SDL_AssertData *next;
 } SDL_AssertData;
 
-#if (SDL_ASSERT_LEVEL > 0)
-
 /* Never call this directly. Use the SDL_assert* macros. */
 extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *,
                                                             const char *,
@@ -143,9 +151,7 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *,
 #define SDL_enabled_assert(condition) \
     do { \
         while ( !(condition) ) { \
-            static struct SDL_AssertData sdl_assert_data = { \
-                0, 0, #condition, 0, 0, 0, 0 \
-            }; \
+            static struct SDL_AssertData sdl_assert_data = { 0, 0, #condition, 0, 0, 0, 0 }; \
             const SDL_AssertState sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_FILE, SDL_LINE); \
             if (sdl_assert_state == SDL_ASSERTION_RETRY) { \
                 continue; /* go again. */ \
@@ -156,8 +162,6 @@ extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *,
         } \
     } while (SDL_NULL_WHILE_LOOP_CONDITION)
 
-#endif  /* enabled assertions support code */
-
 /* Enable various levels of assertions. */
 #if SDL_ASSERT_LEVEL == 0   /* assertions disabled */
 #   define SDL_assert(condition) SDL_disabled_assert(condition)
@@ -183,90 +187,119 @@ 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
- *  response to an assertion failure. If the app doesn't provide this, SDL
- *  will try to do the right thing, popping up a system-specific GUI dialog,
- *  and probably minimizing any fullscreen windows.
+ * This function allows an application to show its own assertion UI and/or
+ * force the response to an assertion failure. If the application doesn't
+ * provide this, SDL will try to do the right thing, popping up a
+ * 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
  * 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()!
  *
- *  \return SDL_AssertState value of how to handle the assertion failure.
+ * \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`
  *
- *  \param handler Callback function, called when an assertion fails.
- *  \param userdata A pointer passed to the callback as-is.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetAssertionHandler
  */
 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.
+ * 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.
+ *
+ * \returns the default SDL_AssertionHandler that is called when an assert
+ *          triggers.
  *
- *  \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().
+ * 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.
+ *
+ * \param puserdata pointer which is filled with the "userdata" pointer that
+ *                  was passed to SDL_SetAssertionHandler()
+ * \returns the SDL_AssertionHandler that is called when an assert triggers.
+ *
+ * \since This function is available since SDL 2.0.2.
  *
- *   \param puserdata 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.
- *  \return The SDL_AssertionHandler that is called when an assert triggers.
+ * \sa SDL_SetAssertionHandler
  */
 extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata);
 
 /**
- *  \brief Get a list of all assertion failures.
+ * Get a list of all assertion failures.
  *
- *  Get all assertions triggered since last call to SDL_ResetAssertionReport(),
- *  or the start of the program.
+ * This function gets all assertions triggered since the last call to
+ * SDL_ResetAssertionReport(), or the start of the program.
  *
  * The proper way to examine this data looks something like this:
  *
- *  <code>
+ * ```c
  * const SDL_AssertData *item = SDL_GetAssertionReport();
  * while (item) {
- *      printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\n",
+ *    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
+ *          memory should not be modified or freed by the application.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  \return List of all assertions.
  * \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.
+ *
+ * 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.
  *
- *  Reset list of all assertions triggered.
+ * \since This function is available since SDL 2.0.0.
  *
  * \sa SDL_GetAssertionReport
  */
@@ -284,6 +317,6 @@ extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void);
 #endif
 #include "close_code.h"
 
-#endif /* _SDL_assert_h */
+#endif /* SDL_assert_h_ */
 
 /* vi: set ts=4 sw=4 expandtab: */

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_atomic.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 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
@@ -56,8 +56,8 @@
  * All of the atomic operations that modify memory are full memory barriers.
  */
 
-#ifndef _SDL_atomic_h_
-#define _SDL_atomic_h_
+#ifndef SDL_atomic_h_
+#define SDL_atomic_h_
 
 #include "SDL_stdinc.h"
 #include "SDL_platform.h"
@@ -89,25 +89,51 @@ 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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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.
  *
- * \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!***
+ *
+ * \param lock a pointer to a lock variable
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicLock
+ * \sa SDL_AtomicTryLock
  */
 extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
 
@@ -118,13 +144,16 @@ extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
  * The compiler barrier prevents the compiler from reordering
  * reads and writes to globally visible variables across the call.
  */
-#if defined(_MSC_VER) && (_MSC_VER > 1200)
+#if defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__)
 void _ReadWriteBarrier(void);
 #pragma intrinsic(_ReadWriteBarrier)
 #define SDL_CompilerBarrier()   _ReadWriteBarrier()
 #elif (defined(__GNUC__) && !defined(__EMSCRIPTEN__)) || (defined(__SUNPRO_C) && (__SUNPRO_C >= 0x5120))
 /* This is correct for all CPUs when using GCC or Solaris Studio 12.1+. */
 #define SDL_CompilerBarrier()   __asm__ __volatile__ ("" : : : "memory")
+#elif defined(__WATCOMC__)
+extern __inline void SDL_CompilerBarrier(void);
+#pragma aux SDL_CompilerBarrier = "" parm [] modify exact [];
 #else
 #define SDL_CompilerBarrier()   \
 { SDL_SpinLock _tmp = 0; SDL_AtomicLock(&_tmp); SDL_AtomicUnlock(&_tmp); }
@@ -134,33 +163,58 @@ void _ReadWriteBarrier(void);
  * Memory barriers are designed to prevent reads and writes from being
  * reordered by the compiler and being seen out of order on multi-core CPUs.
  *
- * A typical pattern would be for thread A to write some data and a flag,
- * and for thread B to read the flag and get the data. In this case you
- * would insert a release barrier between writing the data and the flag,
+ * A typical pattern would be for thread A to write some data and a flag, and
+ * for thread B to read the flag and get the data. In this case you would
+ * insert a release barrier between writing the data and the flag,
  * guaranteeing that the data write completes no later than the flag is
- * written, and you would insert an acquire barrier between reading the
- * flag and reading the data, to ensure that all the reads associated
- * with the flag have completed.
+ * written, and you would insert an acquire barrier between reading the flag
+ * and reading the data, to ensure that all the reads associated with the flag
+ * have completed.
  *
- * In this pattern you should always see a release barrier paired with
- * an acquire barrier and you should gate the data reads/writes with a
- * single flag variable.
+ * In this pattern you should always see a release barrier paired with an
+ * acquire barrier and you should gate the data reads/writes with a single
+ * flag variable.
  *
  * For more information on these semantics, take a look at the blog post:
  * http://preshing.com/20120913/acquire-and-release-semantics
+ *
+ * \since This function is available since SDL 2.0.6.
  */
+extern DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void);
+extern DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
+
 #if defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__))
 #define SDL_MemoryBarrierRelease()   __asm__ __volatile__ ("lwsync" : : : "memory")
 #define SDL_MemoryBarrierAcquire()   __asm__ __volatile__ ("lwsync" : : : "memory")
+#elif defined(__GNUC__) && defined(__aarch64__)
+#define SDL_MemoryBarrierRelease()   __asm__ __volatile__ ("dmb ish" : : : "memory")
+#define SDL_MemoryBarrierAcquire()   __asm__ __volatile__ ("dmb ish" : : : "memory")
 #elif defined(__GNUC__) && defined(__arm__)
-#if defined(__ARM_ARCH_7__) || defined(__ARM_ARCH_7A__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_7R__) || defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7S__)
+#if 0 /* defined(__LINUX__) || defined(__ANDROID__) */
+/* Information from:
+   https://chromium.googlesource.com/chromium/chromium/+/trunk/base/atomicops_internals_arm_gcc.h#19
+
+   The Linux kernel provides a helper function which provides the right code for a memory barrier,
+   hard-coded at address 0xffff0fa0
+*/
+typedef void (*SDL_KernelMemoryBarrierFunc)();
+#define SDL_MemoryBarrierRelease()	((SDL_KernelMemoryBarrierFunc)0xffff0fa0)()
+#define SDL_MemoryBarrierAcquire()	((SDL_KernelMemoryBarrierFunc)0xffff0fa0)()
+#elif 0 /* defined(__QNXNTO__) */
+#include <sys/cpuinline.h>
+
+#define SDL_MemoryBarrierRelease()   __cpu_membarrier()
+#define SDL_MemoryBarrierAcquire()   __cpu_membarrier()
+#else
+#if defined(__ARM_ARCH_7__) || defined(__ARM_ARCH_7A__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_7R__) || defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7S__) || defined(__ARM_ARCH_8A__)
 #define SDL_MemoryBarrierRelease()   __asm__ __volatile__ ("dmb ish" : : : "memory")
 #define SDL_MemoryBarrierAcquire()   __asm__ __volatile__ ("dmb ish" : : : "memory")
-#elif defined(__ARM_ARCH_6__) || defined(__ARM_ARCH_6J__) || defined(__ARM_ARCH_6K__) || defined(__ARM_ARCH_6T2__) || defined(__ARM_ARCH_6Z__) || defined(__ARM_ARCH_6ZK__)
+#elif defined(__ARM_ARCH_6__) || defined(__ARM_ARCH_6J__) || defined(__ARM_ARCH_6K__) || defined(__ARM_ARCH_6T2__) || defined(__ARM_ARCH_6Z__) || defined(__ARM_ARCH_6ZK__) || defined(__ARM_ARCH_5TE__)
 #ifdef __thumb__
 /* The mcr instruction isn't available in thumb mode, use real functions */
-extern DECLSPEC void SDLCALL SDL_MemoryBarrierRelease();
-extern DECLSPEC void SDLCALL SDL_MemoryBarrierAcquire();
+#define SDL_MEMORY_BARRIER_USES_FUNCTION
+#define SDL_MemoryBarrierRelease()   SDL_MemoryBarrierReleaseFunction()
+#define SDL_MemoryBarrierAcquire()   SDL_MemoryBarrierAcquireFunction()
 #else
 #define SDL_MemoryBarrierRelease()   __asm__ __volatile__ ("mcr p15, 0, %0, c7, c10, 5" : : "r"(0) : "memory")
 #define SDL_MemoryBarrierAcquire()   __asm__ __volatile__ ("mcr p15, 0, %0, c7, c10, 5" : : "r"(0) : "memory")
@@ -168,6 +222,7 @@ extern DECLSPEC void SDLCALL SDL_MemoryBarrierAcquire();
 #else
 #define SDL_MemoryBarrierRelease()   __asm__ __volatile__ ("" : : : "memory")
 #define SDL_MemoryBarrierAcquire()   __asm__ __volatile__ ("" : : : "memory")
+#endif /* __LINUX__ || __ANDROID__ */
 #endif /* __GNUC__ && __arm__ */
 #else
 #if (defined(__SUNPRO_C) && (__SUNPRO_C >= 0x5120))
@@ -182,6 +237,25 @@ extern DECLSPEC void SDLCALL SDL_MemoryBarrierAcquire();
 #endif
 #endif
 
+/* "REP NOP" is PAUSE, coded for tools that don't know it by that name. */
+#if (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))
+    #define SDL_CPUPauseInstruction() __asm__ __volatile__("pause\n")  /* Some assemblers can't do REP NOP, so go with PAUSE. */
+#elif (defined(__arm__) && defined(__ARM_ARCH) && __ARM_ARCH >= 7) || defined(__aarch64__)
+    #define SDL_CPUPauseInstruction() __asm__ __volatile__("yield" ::: "memory")
+#elif (defined(__powerpc__) || defined(__powerpc64__))
+    #define SDL_CPUPauseInstruction() __asm__ __volatile__("or 27,27,27");
+#elif defined(_MSC_VER) && (defined(_M_IX86) || defined(_M_X64))
+    #define SDL_CPUPauseInstruction() _mm_pause()  /* this is actually "rep nop" and not a SIMD instruction. No inline asm in MSVC x86-64! */
+#elif defined(_MSC_VER) && (defined(_M_ARM) || defined(_M_ARM64))
+    #define SDL_CPUPauseInstruction() __yield()
+#elif defined(__WATCOMC__) && defined(__386__)
+    extern __inline void SDL_CPUPauseInstruction(void);
+    #pragma aux SDL_CPUPauseInstruction = ".686p" ".xmm2" "pause"
+#else
+    #define SDL_CPUPauseInstruction()
+#endif
+
+
 /**
  * \brief A type representing an atomic integer value.  It is a struct
  *        so people don't accidentally use numeric operations on it.
@@ -189,32 +263,73 @@ extern DECLSPEC void SDLCALL SDL_MemoryBarrierAcquire();
 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.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
  *
- * \return SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
+ * \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.
  *
- * \note If you don't know what this function is for, you shouldn't use it!
+ * \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!***
  *
- * \return The previous value of the atomic variable.
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \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.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
  *
- * \return The previous value of the atomic variable.
+ * \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.
  *
- * \note This same style can be used for any number operation
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_AtomicDecRef
+ * \sa SDL_AtomicIncRef
  */
 extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
 
@@ -236,23 +351,54 @@ 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.
+ *
+ * ***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.
  *
- * \return SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
+ * \since This function is available since SDL 2.0.0.
  *
- * \note If you don't know what this function is for, you shouldn't use it!
+ * \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.
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicSetPtr
  */
 extern DECLSPEC void* SDLCALL SDL_AtomicGetPtr(void **a);
 
@@ -263,6 +409,6 @@ extern DECLSPEC void* SDLCALL SDL_AtomicGetPtr(void **a);
 
 #include "close_code.h"
 
-#endif /* _SDL_atomic_h_ */
+#endif /* SDL_atomic_h_ */
 
 /* vi: set ts=4 sw=4 expandtab: */

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_audio.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 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
@@ -19,14 +19,16 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
+/* !!! FIXME: several functions in here need Doxygen comments. */
+
 /**
  *  \file SDL_audio.h
  *
  *  Access to the raw audio mixing buffer for the SDL library.
  */
 
-#ifndef _SDL_audio_h
-#define _SDL_audio_h
+#ifndef SDL_audio_h_
+#define SDL_audio_h_
 
 #include "SDL_stdinc.h"
 #include "SDL_error.h"
@@ -140,7 +142,8 @@ typedef Uint16 SDL_AudioFormat;
 #define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE    0x00000001
 #define SDL_AUDIO_ALLOW_FORMAT_CHANGE       0x00000002
 #define SDL_AUDIO_ALLOW_CHANNELS_CHANGE     0x00000004
-#define SDL_AUDIO_ALLOW_ANY_CHANGE          (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE)
+#define SDL_AUDIO_ALLOW_SAMPLES_CHANGE      0x00000008
+#define SDL_AUDIO_ALLOW_ANY_CHANGE          (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE|SDL_AUDIO_ALLOW_SAMPLES_CHANGE)
 /* @} */
 
 /* @} *//* Audio flags */
@@ -164,6 +167,15 @@ typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
 
 /**
  *  The calculated values in this structure are calculated by SDL_OpenAudio().
+ *
+ *  For multi-channel audio, the default SDL channel mapping is:
+ *  2:  FL  FR                          (stereo)
+ *  3:  FL  FR LFE                      (2.1 surround)
+ *  4:  FL  FR  BL  BR                  (quad)
+ *  5:  FL  FR LFE  BL  BR              (4.1 surround)
+ *  6:  FL  FR  FC LFE  SL  SR          (5.1 surround - last two can also be BL BR)
+ *  7:  FL  FR  FC LFE  BC  SL  SR      (6.1 surround)
+ *  8:  FL  FR  FC LFE  BL  BR  SL  SR  (7.1 surround)
  */
 typedef struct SDL_AudioSpec
 {
@@ -171,7 +183,7 @@ typedef struct SDL_AudioSpec
     SDL_AudioFormat format;     /**< Audio data format */
     Uint8 channels;             /**< Number of channels: 1 mono, 2 stereo */
     Uint8 silence;              /**< Audio buffer silence value (calculated) */
-    Uint16 samples;             /**< Audio buffer size in samples (power of 2) */
+    Uint16 samples;             /**< Audio buffer size in sample FRAMES (total samples divided by channel count) */
     Uint16 padding;             /**< Necessary for some compile environments */
     Uint32 size;                /**< Audio buffer size in bytes (calculated) */
     SDL_AudioCallback callback; /**< Callback that feeds the audio device (NULL to use SDL_QueueAudio()). */
@@ -184,11 +196,30 @@ typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
                                           SDL_AudioFormat format);
 
 /**
- *  A structure to hold a set of audio conversion filters and buffers.
+ *  \brief Upper limit of filters in SDL_AudioCVT
+ *
+ *  The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is
+ *  currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers,
+ *  one of which is the terminating NULL pointer.
+ */
+#define SDL_AUDIOCVT_MAX_FILTERS 9
+
+/**
+ *  \struct SDL_AudioCVT
+ *  \brief A structure to hold a set of audio conversion filters and buffers.
+ *
+ *  Note that various parts of the conversion pipeline can take advantage
+ *  of SIMD operations (like SSE2, for example). SDL_AudioCVT doesn't require
+ *  you to pass it aligned data, but can possibly run much faster if you
+ *  set both its (buf) field to a pointer that is aligned to 16 bytes, and its
+ *  (len) field to something that's a multiple of 16, if possible.
  */
-#ifdef __GNUC__
+#if defined(__GNUC__) && !defined(__CHERI_PURE_CAPABILITY__)
 /* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't
    pad it out to 88 bytes to guarantee ABI compatibility between compilers.
+   This is not a concern on CHERI architectures, where pointers must be stored
+   at aligned locations otherwise they will become invalid, and thus structs
+   containing pointers cannot be packed without giving a warning or error.
    vvv
    The next time we rev the ABI, make sure to size the ints and add padding.
 */
@@ -208,7 +239,7 @@ typedef struct SDL_AudioCVT
     int len_cvt;                /**< Length of converted audio buffer */
     int len_mult;               /**< buffer must be len*len_mult big */
     double len_ratio;           /**< Given len, final size is len*len_ratio */
-    SDL_AudioFilter filters[10];        /**< Filter list */
+    SDL_AudioFilter filters[SDL_AUDIOCVT_MAX_FILTERS + 1]; /**< NULL-terminated list of filter functions */
     int filter_index;           /**< Current audio conversion function */
 } SDL_AUDIOCVT_PACKED SDL_AudioCVT;
 
@@ -222,7 +253,48 @@ typedef struct SDL_AudioCVT
  *  order that they are normally initialized by default.
  */
 /* @{ */
+
+/**
+ * Use this function to get the number of built-in audio drivers.
+ *
+ * This function returns a hardcoded number. This never returns a negative
+ * value; if there are no drivers compiled into this build of SDL, this
+ * function returns zero. The presence of a driver in this list does not mean
+ * it will function, it just means SDL is capable of interacting with that
+ * interface. For example, a build of SDL might have esound support, but if
+ * there's no esound server available, SDL's esound driver would fail if used.
+ *
+ * By default, SDL tries all drivers, in its preferred order, until one is
+ * found to be usable.
+ *
+ * \returns the number of built-in audio drivers.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetAudioDriver
+ */
 extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
+
+/**
+ * Use this function to get the name of a built in audio driver.
+ *
+ * The list of audio drivers is given in the order that they are normally
+ * initialized by default; the drivers that seem more reasonable to choose
+ * first (as far as the SDL developers believe) are earlier in the list.
+ *
+ * The names of drivers are all simple, low-ASCII identifiers, like "alsa",
+ * "coreaudio" or "xaudio2". These never have Unicode characters, and are not
+ * meant to be proper names.
+ *
+ * \param index the index of the audio driver; the value ranges from 0 to
+ *              SDL_GetNumAudioDrivers() - 1
+ * \returns the name of the audio driver at the requested index, or NULL if an
+ *          invalid index was specified.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetNumAudioDrivers
+ */
 extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
 /* @} */
 
@@ -234,59 +306,103 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
  *            use.  You should normally use SDL_Init() or SDL_InitSubSystem().
  */
 /* @{ */
+
+/**
+ * Use this function to initialize a particular audio driver.
+ *
+ * This function is used internally, and should not be used unless you have a
+ * specific need to designate the audio driver you want to use. You should
+ * normally use SDL_Init() or SDL_InitSubSystem().
+ *
+ * \param driver_name the name of the desired audio driver
+ * \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_AudioQuit
+ */
 extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
+
+/**
+ * Use this function to shut down audio if you initialized it with
+ * SDL_AudioInit().
+ *
+ * This function is used internally, and should not be used unless you have a
+ * specific need to specify the audio driver you want to use. You should
+ * normally use SDL_Quit() or SDL_QuitSubSystem().
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AudioInit
+ */
 extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
 /* @} */
 
 /**
- *  This function returns the name of the current audio driver, or NULL
- *  if no driver has been initialized.
+ * Get the name of the current audio driver.
+ *
+ * The returned string points to internal static memory and thus never becomes
+ * invalid, even if you quit the audio subsystem and initialize a new driver
+ * (although such a case would return a different static string from another
+ * call to this function, of course). As such, you should not modify or free
+ * the returned string.
+ *
+ * \returns the name of the current audio driver or NULL if no driver has been
+ *          initialized.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AudioInit
  */
 extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
 
 /**
- *  This function opens the audio device with the desired parameters, and
- *  returns 0 if successful, placing the actual hardware parameters in the
- *  structure pointed to by \c obtained.  If \c obtained is NULL, the audio
- *  data passed to the callback function will be guaranteed to be in the
- *  requested format, and will be automatically converted to the hardware
- *  audio format if necessary.  This function returns -1 if it failed
- *  to open the audio device, or couldn't set up the audio thread.
- *
- *  When filling in the desired audio spec structure,
- *    - \c desired->freq should be the desired audio frequency in samples-per-
- *      second.
- *    - \c desired->format should be the desired audio format.
- *    - \c desired->samples is the desired size of the audio buffer, in
- *      samples.  This number should be a power of two, and may be adjusted by
- *      the audio driver to a value more suitable for the hardware.  Good values
- *      seem to range between 512 and 8096 inclusive, depending on the
- *      application and CPU speed.  Smaller values yield faster response time,
- *      but can lead to underflow if the application is doing heavy processing
- *      and cannot fill the audio buffer in time.  A stereo sample consists of
- *      both right and left channels in LR ordering.
- *      Note that the number of samples is directly related to time by the
- *      following formula:  \code ms = (samples*1000)/freq \endcode
- *    - \c desired->size is the size in bytes of the audio buffer, and is
- *      calculated by SDL_OpenAudio().
- *    - \c desired->silence is the value used to set the buffer to silence,
- *      and is calculated by SDL_OpenAudio().
- *    - \c desired->callback should be set to a function that will be called
- *      when the audio device is ready for more data.  It is passed a pointer
- *      to the audio buffer, and the length in bytes of the audio buffer.
- *      This function usually runs in a separate thread, and so you should
- *      protect data structures that it accesses by calling SDL_LockAudio()
- *      and SDL_UnlockAudio() in your code. Alternately, you may pass a NULL
- *      pointer here, and call SDL_QueueAudio() with some frequency, to queue
- *      more audio samples to be played.
- *    - \c desired->userdata is passed as the first parameter to your callback
- *      function. If you passed a NULL callback, this value is ignored.
+ * This function is a legacy means of opening the audio device.
+ *
+ * This function remains for compatibility with SDL 1.2, but also because it's
+ * slightly easier to use than the new functions in SDL 2.0. The new, more
+ * powerful, and preferred way to do this is SDL_OpenAudioDevice().
+ *
+ * This function is roughly equivalent to:
+ *
+ * ```c
+ * SDL_OpenAudioDevice(NULL, 0, desired, obtained, SDL_AUDIO_ALLOW_ANY_CHANGE);
+ * ```
+ *
+ * With two notable exceptions:
+ *
+ * - If `obtained` is NULL, we use `desired` (and allow no changes), which
+ *   means desired will be modified to have the correct values for silence,
+ *   etc, and SDL will convert any differences between your app's specific
+ *   request and the hardware behind the scenes.
+ * - The return value is always success or failure, and not a device ID, which
+ *   means you can only have one device open at a time with this function.
+ *
+ * \param desired an SDL_AudioSpec structure representing the desired output
+ *                format. Please refer to the SDL_OpenAudioDevice
+ *                documentation for details on how to prepare this structure.
+ * \param obtained an SDL_AudioSpec structure filled in with the actual
+ *                 parameters, or NULL.
+ * \returns 0 if successful, placing the actual hardware parameters in the
+ *          structure pointed to by `obtained`.
  *
- *  The audio device starts out playing silence when it's opened, and should
- *  be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready
- *  for your audio callback function to be called.  Since the audio driver
- *  may modify the requested size of the audio buffer, you should allocate
- *  any local mixing buffers after you open the audio device.
+ *          If `obtained` is NULL, the audio data passed to the callback
+ *          function will be guaranteed to be in the requested format, and
+ *          will be automatically converted to the actual hardware audio
+ *          format if necessary. If `obtained` is NULL, `desired` will have
+ *          fields modified.
+ *
+ *          This function returns a negative error code on failure to open the
+ *          audio device or failure to set up the audio thread; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CloseAudio
+ * \sa SDL_LockAudio
+ * \sa SDL_PauseAudio
+ * \sa SDL_UnlockAudio
  */
 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
                                           SDL_AudioSpec * obtained);
@@ -303,59 +419,259 @@ extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
 typedef Uint32 SDL_AudioDeviceID;
 
 /**
- *  Get the number of available devices exposed by the current driver.
- *  Only valid after a successfully initializing the audio subsystem.
- *  Returns -1 if an explicit list of devices can't be determined; this is
- *  not an error. For example, if SDL is set up to talk to a remote audio
- *  server, it can't list every one available on the Internet, but it will
- *  still allow a specific host to be specified to SDL_OpenAudioDevice().
+ * Get the number of built-in audio devices.
+ *
+ * This function is only valid after successfully initializing the audio
+ * subsystem.
+ *
+ * Note that audio capture support is not implemented as of SDL 2.0.4, so the
+ * `iscapture` parameter is for future expansion and should always be zero for
+ * now.
+ *
+ * This function will return -1 if an explicit list of devices can't be
+ * determined. Returning -1 is not an error. For example, if SDL is set up to
+ * talk to a remote audio server, it can't list every one available on the
+ * Internet, but it will still allow a specific host to be specified in
+ * SDL_OpenAudioDevice().
  *
  * In many common cases, when this function returns a value <= 0, it can still
  * successfully open the default device (NULL for first argument of
  * SDL_OpenAudioDevice()).
+ *
+ * This function may trigger a complete redetect of available hardware. It
+ * should not be called for each iteration of a loop, but rather once at the
+ * start of a loop:
+ *
+ * ```c
+ * // Don't do this:
+ * for (int i = 0; i < SDL_GetNumAudioDevices(0); i++)
+ *
+ * // do this instead:
+ * const int count = SDL_GetNumAudioDevices(0);
+ * for (int i = 0; i < count; ++i) { do_something_here(); }
+ * ```
+ *
+ * \param iscapture zero to request playback devices, non-zero to request
+ *                  recording devices
+ * \returns the number of available devices exposed by the current driver or
+ *          -1 if an explicit list of devices can't be determined. A return
+ *          value of -1 does not necessarily mean an error condition.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetAudioDeviceName
+ * \sa SDL_OpenAudioDevice
  */
 extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
 
 /**
  * Get the human-readable name of a specific audio device.
- *  Must be a value between 0 and (number of audio devices-1).
- *  Only valid after a successfully initializing the audio subsystem.
- *  The values returned by this function reflect the latest call to
- *  SDL_GetNumAudioDevices(); recall that function to redetect available
+ *
+ * This function is only valid after successfully initializing the audio
+ * subsystem. The values returned by this function reflect the latest call to
+ * SDL_GetNumAudioDevices(); re-call that function to redetect available
  * hardware.
  *
  * The string returned by this function is UTF-8 encoded, read-only, and
- *  managed internally. You are not to free it. If you need to keep the
- *  string for any length of time, you should make your own copy of it, as it
- *  will be invalid next time any of several other SDL functions is called.
+ * managed internally. You are not to free it. If you need to keep the string
+ * for any length of time, you should make your own copy of it, as it will be
+ * invalid next time any of several other SDL functions are called.
+ *
+ * \param index the index of the audio device; valid values range from 0 to
+ *              SDL_GetNumAudioDevices() - 1
+ * \param iscapture non-zero to query the list of recording devices, zero to
+ *                  query the list of output devices.
+ * \returns the name of the audio device at the requested index, or NULL on
+ *          error.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetNumAudioDevices
+ * \sa SDL_GetDefaultAudioInfo
  */
 extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
                                                            int iscapture);
 
+/**
+ * Get the preferred audio format of a specific audio device.
+ *
+ * This function is only valid after a successfully initializing the audio
+ * subsystem. The values returned by this function reflect the latest call to
+ * SDL_GetNumAudioDevices(); re-call that function to redetect available
+ * hardware.
+ *
+ * `spec` will be filled with the sample rate, sample format, and channel
+ * count.
+ *
+ * \param index the index of the audio device; valid values range from 0 to
+ *              SDL_GetNumAudioDevices() - 1
+ * \param iscapture non-zero to query the list of recording devices, zero to
+ *                  query the list of output devices.
+ * \param spec The SDL_AudioSpec to be initialized by this function.
+ * \returns 0 on success, nonzero on error
+ *
+ * \since This function is available since SDL 2.0.16.
+ *
+ * \sa SDL_GetNumAudioDevices
+ * \sa SDL_GetDefaultAudioInfo
+ */
+extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
+                                                   int iscapture,
+                                                   SDL_AudioSpec *spec);
+
 
 /**
- *  Open a specific audio device. Passing in a device name of NULL requests
- *  the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
+ * Get the name and preferred format of the default audio device.
+ *
+ * Some (but not all!) platforms have an isolated mechanism to get information
+ * about the "default" device. This can actually be a completely different
+ * device that's not in the list you get from SDL_GetAudioDeviceSpec(). It can
+ * even be a network address! (This is discussed in SDL_OpenAudioDevice().)
+ *
+ * As a result, this call is not guaranteed to be performant, as it can query
+ * the sound server directly every time, unlike the other query functions. You
+ * should call this function sparingly!
  *
- *  The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
+ * `spec` will be filled with the sample rate, sample format, and channel
+ * count, if a default device exists on the system. If `name` is provided,
+ * will be filled with either a dynamically-allocated UTF-8 string or NULL.
+ *
+ * \param name A pointer to be filled with the name of the default device (can
+ *             be NULL). Please call SDL_free() when you are done with this
+ *             pointer!
+ * \param spec The SDL_AudioSpec to be initialized by this function.
+ * \param iscapture non-zero to query the default recording device, zero to
+ *                  query the default output device.
+ * \returns 0 on success, nonzero on error
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GetAudioDeviceName
+ * \sa SDL_GetAudioDeviceSpec
+ * \sa SDL_OpenAudioDevice
+ */
+extern DECLSPEC int SDLCALL SDL_GetDefaultAudioInfo(char **name,
+                                                    SDL_AudioSpec *spec,
+                                                    int iscapture);
+
+
+/**
+ * Open a specific audio device.
+ *
+ * SDL_OpenAudio(), unlike this function, always acts on device ID 1. As such,
+ * this function will never return a 1 so as not to conflict with the legacy
+ * function.
+ *
+ * Please note that SDL 2.0 before 2.0.5 did not support recording; as such,
+ * this function would fail if `iscapture` was not zero. Starting with SDL
+ * 2.0.5, recording is implemented and this value can be non-zero.
+ *
+ * Passing in a `device` name of NULL requests the most reasonable default
+ * (and is equivalent to what SDL_OpenAudio() does to choose a device). The
+ * `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
  * some drivers allow arbitrary and driver-specific strings, such as a
  * hostname/IP address for a remote audio server, or a filename in the
  * diskaudio driver.
  *
- *  \return 0 on error, a valid device ID that is >= 2 on success.
+ * An opened audio device starts out paused, and should be enabled for playing
+ * by calling SDL_PauseAudioDevice(devid, 0) when you are ready for your audio
+ * callback function to be called. Since the audio driver may modify the
+ * requested size of the audio buffer, you should allocate any local mixing
+ * buffers after you open the audio device.
+ *
+ * The audio callback runs in a separate thread in most cases; you can prevent
+ * race conditions between your callback and other threads without fully
+ * pausing playback with SDL_LockAudioDevice(). For more information about the
+ * callback, see SDL_AudioSpec.
+ *
+ * Managing the audio spec via 'desired' and 'obtained':
+ *
+ * When filling in the desired audio spec structure:
+ *
+ * - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
+ * - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc).
+ * - `desired->samples` is the desired size of the audio buffer, in _sample
+ *   frames_ (with stereo output, two samples--left and right--would make a
+ *   single sample frame). This number should be a power of two, and may be
+ *   adjusted by the audio driver to a value more suitable for the hardware.
+ *   Good values seem to range between 512 and 8096 inclusive, depending on
+ *   the application and CPU speed. Smaller values reduce latency, but can
+ *   lead to underflow if the application is doing heavy processing and cannot
+ *   fill the audio buffer in time. Note that the number of sample frames is
+ *   directly related to time by the following formula: `ms =
+ *   (sampleframes*1000)/freq`
+ * - `desired->size` is the size in _bytes_ of the audio buffer, and is
+ *   calculated by SDL_OpenAudioDevice(). You don't initialize this.
+ * - `desired->silence` is the value used to set the buffer to silence, and is
+ *   calculated by SDL_OpenAudioDevice(). You don't initialize this.
+ * - `desired->callback` should be set to a function that will be called when
+ *   the audio device is ready for more data. It is passed a pointer to the
+ *   audio buffer, and the length in bytes of the audio buffer. This function
+ *   usually runs in a separate thread, and so you should protect data
+ *   structures that it accesses by calling SDL_LockAudioDevice() and
+ *   SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL
+ *   pointer here, and call SDL_QueueAudio() with some frequency, to queue
+ *   more audio samples to be played (or for capture devices, call
+ *   SDL_DequeueAudio() with some frequency, to obtain audio samples).
+ * - `desired->userdata` is passed as the first parameter to your callback
+ *   function. If you passed a NULL callback, this value is ignored.
+ *
+ * `allowed_changes` can have the following flags OR'd together:
  *
- *  SDL_OpenAudio(), unlike this function, always acts on device ID 1.
+ * - `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE`
+ * - `SDL_AUDIO_ALLOW_FORMAT_CHANGE`
+ * - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE`
+ * - `SDL_AUDIO_ALLOW_SAMPLES_CHANGE`
+ * - `SDL_AUDIO_ALLOW_ANY_CHANGE`
+ *
+ * These flags specify how SDL should behave when a device cannot offer a
+ * specific feature. If the application requests a feature that the hardware
+ * doesn't offer, SDL will always try to get the closest equivalent.
+ *
+ * For example, if you ask for float32 audio format, but the sound card only
+ * supports int16, SDL will set the hardware to int16. If you had set
+ * SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the `obtained`
+ * structure. If that flag was *not* set, SDL will prepare to convert your
+ * callback's float32 audio to int16 before feeding it to the hardware and
+ * will keep the originally requested format in the `obtained` structure.
+ *
+ * The resulting audio specs, varying depending on hardware and on what
+ * changes were allowed, will then be written back to `obtained`.
+ *
+ * If your application can only handle one specific data format, pass a zero
+ * for `allowed_changes` and let SDL transparently handle any differences.
+ *
+ * \param device a UTF-8 string reported by SDL_GetAudioDeviceName() or a
+ *               driver-specific name as appropriate. NULL requests the most
+ *               reasonable default device.
+ * \param iscapture non-zero to specify a device should be opened for
+ *                  recording, not playback
+ * \param desired an SDL_AudioSpec structure representing the desired output
+ *                format; see SDL_OpenAudio() for more information
+ * \param obtained an SDL_AudioSpec structure filled in with the actual output
+ *                 format; see SDL_OpenAudio() for more information
+ * \param allowed_changes 0, or one or more flags OR'd together
+ * \returns a valid device ID that is > 0 on success or 0 on failure; call
+ *          SDL_GetError() for more information.
+ *
+ *          For compatibility with SDL 1.2, this will never return 1, since
+ *          SDL reserves that ID for the legacy SDL_OpenAudio() function.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CloseAudioDevice
+ * \sa SDL_GetAudioDeviceName
+ * \sa SDL_LockAudioDevice
+ * \sa SDL_OpenAudio
+ * \sa SDL_PauseAudioDevice
+ * \sa SDL_UnlockAudioDevice
  */
-extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
-                                                              *device,
+extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(
+                                                  const char *device,
                                                   int iscapture,
-                                                              const
-                                                              SDL_AudioSpec *
-                                                              desired,
-                                                              SDL_AudioSpec *
-                                                              obtained,
-                                                              int
-                                                              allowed_changes);
+                                                  const SDL_AudioSpec *desired,
+                                                  SDL_AudioSpec *obtained,
+                                                  int allowed_changes);
 
 
 
@@ -371,10 +687,39 @@ typedef enum
     SDL_AUDIO_PLAYING,
     SDL_AUDIO_PAUSED
 } SDL_AudioStatus;
+
+/**
+ * This function is a legacy means of querying the audio device.
+ *
+ * New programs might want to use SDL_GetAudioDeviceStatus() instead. This
+ * function is equivalent to calling...
+ *
+ * ```c
+ * SDL_GetAudioDeviceStatus(1);
+ * ```
+ *
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
+ *
+ * \returns the SDL_AudioStatus of the audio device opened by SDL_OpenAudio().
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetAudioDeviceStatus
+ */
 extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
 
-extern DECLSPEC SDL_AudioStatus SDLCALL
-SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
+/**
+ * Use this function to get the current audio state of an audio device.
+ *
+ * \param dev the ID of an audio device previously opened with
+ *            SDL_OpenAudioDevice()
+ * \returns the SDL_AudioStatus of the specified audio device.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_PauseAudioDevice
+ */
+extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
 /* @} *//* Audio State */
 
 /**
@@ -387,29 +732,140 @@ SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
  *  Silence will be written to the audio device during the pause.
  */
 /* @{ */
+
+/**
+ * This function is a legacy means of pausing the audio device.
+ *
+ * New programs might want to use SDL_PauseAudioDevice() instead. This
+ * function is equivalent to calling...
+ *
+ * ```c
+ * SDL_PauseAudioDevice(1, pause_on);
+ * ```
+ *
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
+ *
+ * \param pause_on non-zero to pause, 0 to unpause
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetAudioStatus
+ * \sa SDL_PauseAudioDevice
+ */
 extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
+
+/**
+ * Use this function to pause and unpause audio playback on a specified
+ * device.
+ *
+ * This function pauses and unpauses the audio callback processing for a given
+ * device. Newly-opened audio devices start in the paused state, so you must
+ * call this function with **pause_on**=0 after opening the specified audio
+ * device to start playing sound. This allows you to safely initialize data
+ * for your callback function after opening the audio device. Silence will be
+ * written to the audio device while paused, and the audio callback is
+ * guaranteed to not be called. Pausing one device does not prevent other
+ * unpaused devices from running their callbacks.
+ *
+ * Pausing state does not stack; even if you pause a device several times, a
+ * single unpause will start the device playing again, and vice versa. This is
+ * different from how SDL_LockAudioDevice() works.
+ *
+ * If you just need to protect a few variables from race conditions vs your
+ * callback, you shouldn't pause the audio device, as it will lead to dropouts
+ * in the audio playback. Instead, you should use SDL_LockAudioDevice().
+ *
+ * \param dev a device opened by SDL_OpenAudioDevice()
+ * \param pause_on non-zero to pause, 0 to unpause
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LockAudioDevice
+ */
 extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
                                                   int pause_on);
 /* @} *//* Pause audio functions */
 
 /**
- *  This function loads a WAVE from the data source, automatically freeing
- *  that source if \c freesrc is non-zero.  For example, to load a WAVE file,
- *  you could do:
- *  \code
- *      SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
- *  \endcode
+ * Load the audio data of a WAVE file into memory.
+ *
+ * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
+ * be valid pointers. The entire data portion of the file is then loaded into
+ * memory and decoded if necessary.
+ *
+ * If `freesrc` is non-zero, the data source gets automatically closed and
+ * freed before the function returns.
+ *
+ * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
+ * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
+ * A-law and mu-law (8 bits). Other formats are currently unsupported and
+ * cause an error.
+ *
+ * If this function succeeds, the pointer returned by it is equal to `spec`
+ * and the pointer to the audio data allocated by the function is written to
+ * `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec
+ * members `freq`, `channels`, and `format` are set to the values of the audio
+ * data in the buffer. The `samples` member is set to a sane default and all
+ * others are set to zero.
+ *
+ * It's necessary to use SDL_FreeWAV() to free the audio data returned in
+ * `audio_buf` when it is no longer used.
+ *
+ * Because of the underspecification of the .WAV format, there are many
+ * problematic files in the wild that cause issues with strict decoders. To
+ * provide compatibility with these files, this decoder is lenient in regards
+ * to the truncation of the file, the fact chunk, and the size of the RIFF
+ * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
+ * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
+ * tune the behavior of the loading process.
+ *
+ * Any file that is invalid (due to truncation, corruption, or wrong values in
+ * the headers), too big, or unsupported causes an error. Additionally, any
+ * critical I/O error from the data source will terminate the loading process
+ * with an error. The function returns NULL on error and in all cases (with
+ * the exception of `src` being NULL), an appropriate error message will be
+ * set.
  *
- *  If this function succeeds, it returns the given SDL_AudioSpec,
- *  filled with the audio data format of the wave data, and sets
- *  \c *audio_buf to a malloc()'d buffer containing the audio data,
- *  and sets \c *audio_len to the length of that audio buffer, in bytes.
- *  You need to free the audio buffer with SDL_FreeWAV() when you are
- *  done with it.
+ * It is required that the data source supports seeking.
  *
- *  This function returns NULL and sets the SDL error message if the
- *  wave file cannot be opened, uses an unknown data format, or is
- *  corrupt.  Currently raw and MS-ADPCM WAVE files are supported.
+ * Example:
+ *
+ * ```c
+ * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
+ * ```
+ *
+ * Note that the SDL_LoadWAV macro does this same thing for you, but in a less
+ * messy way:
+ *
+ * ```c
+ * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
+ * ```
+ *
+ * \param src The data source for the WAVE data
+ * \param freesrc If non-zero, SDL will _always_ free the data source
+ * \param spec An SDL_AudioSpec that will be filled in with the wave file's
+ *             format details
+ * \param audio_buf A pointer filled with the audio data, allocated by the
+ *                  function.
+ * \param audio_len A pointer filled with the length of the audio data buffer
+ *                  in bytes
+ * \returns This function, if successfully called, returns `spec`, which will
+ *          be filled with the audio data format of the wave source data.
+ *          `audio_buf` will be filled with a pointer to an allocated buffer
+ *          containing the audio data, and `audio_len` is filled with the
+ *          length of that audio buffer in bytes.
+ *
+ *          This function returns NULL if the .WAV file cannot be opened, uses
+ *          an unknown data format, or is corrupt; call SDL_GetError() for
+ *          more information.
+ *
+ *          When the application is done with the data returned in
+ *          `audio_buf`, it should call SDL_FreeWAV() to dispose of it.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_FreeWAV
+ * \sa SDL_LoadWAV
  */
 extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
                                                       int freesrc,
@@ -425,18 +881,53 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
     SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
 
 /**
- *  This function frees data previously allocated with SDL_LoadWAV_RW()
+ * Free data previously allocated with SDL_LoadWAV() or SDL_LoadWAV_RW().
+ *
+ * After a WAVE file has been opened with SDL_LoadWAV() or SDL_LoadWAV_RW()
+ * its data can eventually be freed with SDL_FreeWAV(). It is safe to call
+ * this function with a NULL pointer.
+ *
+ * \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or
+ *                  SDL_LoadWAV_RW()
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadWAV
+ * \sa SDL_LoadWAV_RW
  */
 extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
 
 /**
- *  This function takes a source format and rate and a destination format
- *  and rate, and initializes the \c cvt structure with information needed
- *  by SDL_ConvertAudio() to convert a buffer of audio data from one format
- *  to the other.
+ * Initialize an SDL_AudioCVT structure for conversion.
+ *
+ * Before an SDL_AudioCVT structure can be used to convert audio data it must
+ * be initialized with source and destination information.
+ *
+ * This function will zero out every field of the SDL_AudioCVT, so it must be
+ * called before the application fills in the final buffer information.
  *
- *  \return -1 if the format conversion is not supported, 0 if there's
- *  no conversion needed, or 1 if the audio filter is set up.
+ * Once this function has returned successfully, and reported that a
+ * conversion is necessary, the application fills in the rest of the fields in
+ * SDL_AudioCVT, now that it knows how large a buffer it needs to allocate,
+ * and then can call SDL_ConvertAudio() to complete the conversion.
+ *
+ * \param cvt an SDL_AudioCVT structure filled in with audio conversion
+ *            information
+ * \param src_format the source format of the audio data; for more info see
+ *                   SDL_AudioFormat
+ * \param src_channels the number of channels in the source
+ * \param src_rate the frequency (sample-frames-per-second) of the source
+ * \param dst_format the destination format of the audio data; for more info
+ *                   see SDL_AudioFormat
+ * \param dst_channels the number of channels in the destination
+ * \param dst_rate the frequency (sample-frames-per-second) of the destination
+ * \returns 1 if the audio filter is prepared, 0 if no conversion is needed,
+ *          or a negative error code on failure; call SDL_GetError() for more
+ *          information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_ConvertAudio
  */
 extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
                                               SDL_AudioFormat src_format,
@@ -447,32 +938,242 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
                                               int dst_rate);
 
 /**
- *  Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(),
- *  created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
- *  audio data in the source format, this function will convert it in-place
+ * Convert audio data to a desired audio format.
+ *
+ * This function does the actual audio data conversion, after the application
+ * has called SDL_BuildAudioCVT() to prepare the conversion information and
+ * then filled in the buffer details.
+ *
+ * Once the application has initialized the `cvt` structure using
+ * SDL_BuildAudioCVT(), allocated an audio buffer and filled it with audio
+ * data in the source format, this function will convert the buffer, in-place,
  * to the desired format.
  *
- *  The data conversion may expand the size of the audio data, so the buffer
- *  \c cvt->buf should be allocated after the \c cvt structure is initialized by
- *  SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
+ * The data conversion may go through several passes; any given pass may
+ * possibly temporarily increase the size of the data. For example, SDL might
+ * expand 16-bit data to 32 bits before resampling to a lower frequency,
+ * shrinking the data size after having grown it briefly. Since the supplied
+ * buffer will be both the source and destination, converting as necessary
+ * in-place, the application must allocate a buffer that will fully contain
+ * the data during its largest conversion pass. After SDL_BuildAudioCVT()
+ * returns, the application should set the `cvt->len` field to the size, in
+ * bytes, of the source data, and allocate a buffer that is `cvt->len *
+ * cvt->len_mult` bytes long for the `buf` field.
+ *
+ * The source data should be copied into this buffer before the call to
+ * SDL_ConvertAudio(). Upon successful return, this buffer will contain the
+ * converted audio, and `cvt->len_cvt` will be the size of the converted data,
+ * in bytes. Any bytes in the buffer past `cvt->len_cvt` are undefined once
+ * this function returns.
+ *
+ * \param cvt an SDL_AudioCVT structure that was previously set up by
+ *            SDL_BuildAudioCVT().
+ * \returns 0 if the conversion was completed successfully 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_BuildAudioCVT
  */
 extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
 
+/* SDL_AudioStream is a new audio conversion interface.
+   The benefits vs SDL_AudioCVT:
+    - it can handle resampling data in chunks without generating
+      artifacts, when it doesn't have the complete buffer available.
+    - it can handle incoming data in any variable size.
+    - You push data as you have it, and pull it when you need it
+ */
+/* this is opaque to the outside world. */
+struct _SDL_AudioStream;
+typedef struct _SDL_AudioStream SDL_AudioStream;
+
+/**
+ * Create a new audio stream.
+ *
+ * \param src_format The format of the source audio
+ * \param src_channels The number of channels of the source audio
+ * \param src_rate The sampling rate of the source audio
+ * \param dst_format The format of the desired audio output
+ * \param dst_channels The number of channels of the desired audio output
+ * \param dst_rate The sampling rate of the desired audio output
+ * \returns 0 on success, or -1 on error.
+ *
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
+ */
+extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format,
+                                           const Uint8 src_channels,
+                                           const int src_rate,
+                                           const SDL_AudioFormat dst_format,
+                                           const Uint8 dst_channels,
+                                           const int dst_rate);
+
+/**
+ * Add data to be converted/resampled to the stream.
+ *
+ * \param stream The stream the audio data is being added to
+ * \param buf A pointer to the audio data to add
+ * \param len The number of bytes to write to the stream
+ * \returns 0 on success, or -1 on error.
+ *
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
+ */
+extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len);
+
+/**
+ * Get converted/resampled data from the stream
+ *
+ * \param stream The stream the audio is being requested from
+ * \param buf A buffer to fill with audio data
+ * \param len The maximum number of bytes to fill
+ * \returns the number of bytes read from the stream, or -1 on error
+ *
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
+ */
+extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len);
+
+/**
+ * Get the number of converted/resampled bytes available.
+ *
+ * The stream may be buffering data behind the scenes until it has enough to
+ * resample correctly, so this number might be lower than what you expect, or
+ * even be zero. Add more data or flush the stream if you need the data now.
+ *
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
+ */
+extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
+
+/**
+ * Tell the stream that you're done sending data, and anything being buffered
+ * should be converted/resampled and made available immediately.
+ *
+ * It is legal to add more data to a stream after flushing, but there will be
+ * audio gaps in the output. Generally this is intended to signal the end of
+ * input, so the complete output becomes available.
+ *
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamClear
+ * \sa SDL_FreeAudioStream
+ */
+extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
+
+/**
+ * Clear any pending data in the stream without converting it
+ *
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_FreeAudioStream
+ */
+extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
+
+/**
+ * Free an audio stream
+ *
+ * \since This function is available since SDL 2.0.7.
+ *
+ * \sa SDL_NewAudioStream
+ * \sa SDL_AudioStreamPut
+ * \sa SDL_AudioStreamGet
+ * \sa SDL_AudioStreamAvailable
+ * \sa SDL_AudioStreamFlush
+ * \sa SDL_AudioStreamClear
+ */
+extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
+
 #define SDL_MIX_MAXVOLUME 128
+
 /**
- *  This takes two audio buffers of the playing audio format and mixes
- *  them, performing addition, volume adjustment, and overflow clipping.
- *  The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME
- *  for full audio volume.  Note this does not change hardware volume.
- *  This is provided for convenience -- you can mix your own audio data.
+ * This function is a legacy means of mixing audio.
+ *
+ * This function is equivalent to calling...
+ *
+ * ```c
+ * SDL_MixAudioFormat(dst, src, format, len, volume);
+ * ```
+ *
+ * ...where `format` is the obtained format of the audio device from the
+ * legacy SDL_OpenAudio() function.
+ *
+ * \param dst the destination for the mixed audio
+ * \param src the source audio buffer to be mixed
+ * \param len the length of the audio buffer in bytes
+ * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
+ *               for full audio volume
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_MixAudioFormat
  */
 extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
                                           Uint32 len, int volume);
 
 /**
- *  This works like SDL_MixAudio(), but you specify the audio format instead of
- *  using the format of audio device 1. Thus it can be used when no audio
- *  device is open at all.
+ * Mix audio data in a specified format.
+ *
+ * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
+ * it into `dst`, performing addition, volume adjustment, and overflow
+ * clipping. The buffer pointed to by `dst` must also be `len` bytes of
+ * `format` data.
+ *
+ * This is provided for convenience -- you can mix your own audio data.
+ *
+ * Do not use this function for mixing together more than two streams of
+ * sample data. The output from repeated application of this function may be
+ * distorted by clipping, because there is no accumulator with greater range
+ * than the input (not to mention this being an inefficient way of doing it).
+ *
+ * It is a common misconception that this function is required to write audio
+ * data to an output stream in an audio callback. While you can do that,
+ * SDL_MixAudioFormat() is really only needed when you're mixing a single
+ * audio stream with a volume adjustment.
+ *
+ * \param dst the destination for the mixed audio
+ * \param src the source audio buffer to be mixed
+ * \param format the SDL_AudioFormat structure representing the desired audio
+ *               format
+ * \param len the length of the audio buffer in bytes
+ * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
+ *               for full audio volume
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
                                                 const Uint8 * src,
@@ -482,93 +1183,164 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
 /**
  * Queue more audio on non-callback devices.
  *
+ * If you are looking to retrieve queued audio from a non-callback capture
+ * device, you want SDL_DequeueAudio() instead. SDL_QueueAudio() will return
+ * -1 to signify an error if you use it with capture devices.
+ *
  * SDL offers two ways to feed audio to the device: you can either supply a
- *  callback that SDL triggers with some frequency to obtain more audio
- *  (pull method), or you can supply no callback, and then SDL will expect
- *  you to supply data at regular intervals (push method) with this function.
+ * callback that SDL triggers with some frequency to obtain more audio (pull
+ * method), or you can supply no callback, and then SDL will expect you to
+ * supply data at regular intervals (push method) with this function.
  *
  * There are no limits on the amount of data you can queue, short of
  * exhaustion of address space. Queued data will drain to the device as
- *  necessary without further intervention from you. If the device needs
- *  audio but there is not enough queued, it will play silence to make up
- *  the difference. This means you will have skips in your audio playback
- *  if you aren't routinely queueing sufficient data.
+ * necessary without further intervention from you. If the device needs audio
+ * but there is not enough queued, it will play silence to make up the
+ * difference. This means you will have skips in your audio playback if you
+ * aren't routinely queueing sufficient data.
  *
- *  This function copies the supplied data, so you are safe to free it when
- *  the function returns. This function is thread-safe, but queueing to the
- *  same device from two threads at once does not promise which buffer will
- *  be queued first.
+ * This function copies the supplied data, so you are safe to free it when the
+ * function returns. This function is thread-safe, but queueing to the same
+ * device from two threads at once does not promise which buffer will be
+ * queued first.
  *
  * You may not queue audio on a device that is using an application-supplied
- *  callback; doing so returns an error. You have to use the audio callback
- *  or queue audio with this function, but not both.
+ * callback; doing so returns an error. You have to use the audio callback or
+ * queue audio with this function, but not both.
  *
  * You should not call SDL_LockAudio() on the device before queueing; SDL
  * handles locking internally for this function.
  *
- *  \param dev The device ID to which we will queue audio.
- *  \param data The data to queue to the device for later playback.
- *  \param len The number of bytes (not samples!) to which (data) points.
- *  \return zero on success, -1 on error.
+ * Note that SDL2 does not support planar audio. You will need to resample
+ * from planar audio formats into a non-planar one (see SDL_AudioFormat)
+ * before queuing audio.
+ *
+ * \param dev the device ID to which we will queue audio
+ * \param data the data to queue to the device for later playback
+ * \param len the number of bytes (not samples!) to which `data` points
+ * \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_GetQueuedAudioSize
  * \sa SDL_ClearQueuedAudio
+ * \sa SDL_GetQueuedAudioSize
  */
 extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
 
+/**
+ * Dequeue more audio on non-callback devices.
+ *
+ * If you are looking to queue audio for output on a non-callback playback
+ * device, you want SDL_QueueAudio() instead. SDL_DequeueAudio() will always
+ * return 0 if you use it with playback devices.
+ *
+ * SDL offers two ways to retrieve audio from a capture device: you can either
+ * supply a callback that SDL triggers with some frequency as the device
+ * records more audio data, (push method), or you can supply no callback, and
+ * then SDL will expect you to retrieve data at regular intervals (pull
+ * method) with this function.
+ *
+ * There are no limits on the amount of data you can queue, short of
+ * exhaustion of address space. Data from the device will keep queuing as
+ * necessary without further intervention from you. This means you will
+ * eventually run out of memory if you aren't routinely dequeueing data.
+ *
+ * Capture devices will not queue data when paused; if you are expecting to
+ * not need captured audio for some length of time, use SDL_PauseAudioDevice()
+ * to stop the capture device from queueing more data. This can be useful
+ * during, say, level loading times. When unpaused, capture devices will start
+ * queueing data from that point, having flushed any capturable data available
+ * while paused.
+ *
+ * This function is thread-safe, but dequeueing from the same device from two
+ * threads at once does not promise which thread will dequeue data first.
+ *
+ * You may not dequeue audio from a device that is using an
+ * application-supplied callback; doing so returns an error. You have to use
+ * the audio callback, or dequeue audio with this function, but not both.
+ *
+ * You should not call SDL_LockAudio() on the device before dequeueing; SDL
+ * handles locking internally for this function.
+ *
+ * \param dev the device ID from which we will dequeue audio
+ * \param data a pointer into where audio data should be copied
+ * \param len the number of bytes (not samples!) to which (data) points
+ * \returns the number of bytes dequeued, which could be less than requested;
+ *          call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.5.
+ *
+ * \sa SDL_ClearQueuedAudio
+ * \sa SDL_GetQueuedAudioSize
+ */
+extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
+
 /**
  * Get the number of bytes of still-queued audio.
  *
- *  This is the number of bytes that have been queued for playback with
- *  SDL_QueueAudio(), but have not yet been sent to the hardware.
+ * For playback devices: this is the number of bytes that have been queued for
+ * playback with SDL_QueueAudio(), but have not yet been sent to the hardware.
  *
  * Once we've sent it to the hardware, this function can not decide the exact
  * byte boundary of what has been played. It's possible that we just gave the
  * hardware several kilobytes right before you called this function, but it
  * hasn't played any of it yet, or maybe half of it, etc.
  *
- *  You may not queue audio on a device that is using an application-supplied
- *  callback; calling this function on such a device always returns 0.
- *  You have to use the audio callback or queue audio with SDL_QueueAudio(),
- *  but not both.
+ * For capture devices, this is the number of bytes that have been captured by
+ * the device and are waiting for you to dequeue. This number may grow at any
+ * time, so this only informs of the lower-bound of available data.
+ *
+ * You may not queue or dequeue audio on a device that is using an
+ * application-supplied callback; calling this function on such a device
+ * always returns 0. You have to use the audio callback or queue audio, but
+ * not both.
  *
  * You should not call SDL_LockAudio() on the device before querying; SDL
  * handles locking internally for this function.
  *
- *  \param dev The device ID of which we will query queued audio size.
- *  \return Number of bytes (not samples!) of queued audio.
+ * \param dev the device ID of which we will query queued audio size
+ * \returns the number of bytes (not samples!) of queued audio.
+ *
+ * \since This function is available since SDL 2.0.4.
  *
- *  \sa SDL_QueueAudio
  * \sa SDL_ClearQueuedAudio
+ * \sa SDL_QueueAudio
+ * \sa SDL_DequeueAudio
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
 
 /**
  * Drop any queued audio data waiting to be sent to the hardware.
  *
- *  Immediately after this call, SDL_GetQueuedAudioSize() will return 0 and
- *  the hardware will start playing silence if more audio isn't queued.
+ * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
+ * output devices, the hardware will start playing silence if more audio isn't
+ * queued. For capture devices, the hardware will start filling the empty
+ * queue with new data if the capture device isn't paused.
  *
- *  This will not prevent playback of queued audio that's already been sent
- *  to the hardware, as we can not undo that, so expect there to be some
- *  fraction of a second of audio that might still be heard. This can be
- *  useful if you want to, say, drop any pending music during a level change
- *  in your game.
+ * This will not prevent playback of queued audio that's already been sent to
+ * the hardware, as we can not undo that, so expect there to be some fraction
+ * of a second of audio that might still be heard. This can be useful if you
+ * want to, say, drop any pending music or any unprocessed microphone input
+ * during a level change in your game.
  *
- *  You may not queue audio on a device that is using an application-supplied
- *  callback; calling this function on such a device is always a no-op.
- *  You have to use the audio callback or queue audio with SDL_QueueAudio(),
- *  but not both.
+ * You may not queue or dequeue audio on a device that is using an
+ * application-supplied callback; calling this function on such a device
+ * always returns 0. You have to use the audio callback or queue audio, but
+ * not both.
  *
  * You should not call SDL_LockAudio() on the device before clearing the
  * queue; SDL handles locking internally for this function.
  *
  * This function always succeeds and thus returns void.
  *
- *  \param dev The device ID of which to clear the audio queue.
+ * \param dev the device ID of which to clear the audio queue
+ *
+ * \since This function is available since SDL 2.0.4.
  *
- *  \sa SDL_QueueAudio
  * \sa SDL_GetQueuedAudioSize
+ * \sa SDL_QueueAudio
+ * \sa SDL_DequeueAudio
  */
 extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
 
@@ -582,16 +1354,139 @@ extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
  *  function or you will cause deadlock.
  */
 /* @{ */
+
+/**
+ * This function is a legacy means of locking the audio device.
+ *
+ * New programs might want to use SDL_LockAudioDevice() instead. This function
+ * is equivalent to calling...
+ *
+ * ```c
+ * SDL_LockAudioDevice(1);
+ * ```
+ *
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LockAudioDevice
+ * \sa SDL_UnlockAudio
+ * \sa SDL_UnlockAudioDevice
+ */
 extern DECLSPEC void SDLCALL SDL_LockAudio(void);
+
+/**
+ * Use this function to lock out the audio callback function for a specified
+ * device.
+ *
+ * The lock manipulated by these functions protects the audio callback
+ * function specified in SDL_OpenAudioDevice(). During a
+ * SDL_LockAudioDevice()/SDL_UnlockAudioDevice() pair, you can be guaranteed
+ * that the callback function for that device is not running, even if the
+ * device is not paused. While a device is locked, any other unpaused,
+ * unlocked devices may still run their callbacks.
+ *
+ * Calling this function from inside your audio callback is unnecessary. SDL
+ * obtains this lock before calling your function, and releases it when the
+ * function returns.
+ *
+ * You should not hold the lock longer than absolutely necessary. If you hold
+ * it too long, you'll experience dropouts in your audio playback. Ideally,
+ * your application locks the device, sets a few variables and unlocks again.
+ * Do not do heavy work while holding the lock for a device.
+ *
+ * It is safe to lock the audio device multiple times, as long as you unlock
+ * it an equivalent number of times. The callback will not run until the
+ * device has been unlocked completely in this way. If your application fails
+ * to unlock the device appropriately, your callback will never run, you might
+ * hear repeating bursts of audio, and SDL_CloseAudioDevice() will probably
+ * deadlock.
+ *
+ * Internally, the audio device lock is a mutex; if you lock from two threads
+ * at once, not only will you block the audio callback, you'll block the other
+ * thread.
+ *
+ * \param dev the ID of the device to be locked
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_UnlockAudioDevice
+ */
 extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
+
+/**
+ * This function is a legacy means of unlocking the audio device.
+ *
+ * New programs might want to use SDL_UnlockAudioDevice() instead. This
+ * function is equivalent to calling...
+ *
+ * ```c
+ * SDL_UnlockAudioDevice(1);
+ * ```
+ *
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LockAudio
+ * \sa SDL_UnlockAudioDevice
+ */
 extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
+
+/**
+ * Use this function to unlock the audio callback function for a specified
+ * device.
+ *
+ * This function should be paired with a previous SDL_LockAudioDevice() call.
+ *
+ * \param dev the ID of the device to be unlocked
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LockAudioDevice
+ */
 extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
 /* @} *//* Audio lock functions */
 
 /**
- *  This function shuts down audio processing and closes the audio device.
+ * This function is a legacy means of closing the audio device.
+ *
+ * This function is equivalent to calling...
+ *
+ * ```c
+ * SDL_CloseAudioDevice(1);
+ * ```
+ *
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_OpenAudio
  */
 extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
+
+/**
+ * Use this function to shut down audio processing and close the audio device.
+ *
+ * The application should close open audio devices once they are no longer
+ * needed. Calling this function will wait until the device's audio callback
+ * is not running, release the audio hardware and then clean up internal
+ * state. No further audio will play from this device once this function
+ * returns.
+ *
+ * This function may block briefly while pending audio data is played by the
+ * hardware, so that applications don't drop the last buffer of data they
+ * supplied.
+ *
+ * The device ID is invalid as soon as the device is closed, and is eligible
+ * for reuse in a new SDL_OpenAudioDevice() call immediately.
+ *
+ * \param dev an audio device previously opened with SDL_OpenAudioDevice()
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_OpenAudioDevice
+ */
 extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
 
 /* Ends C function definitions when using C++ */
@@ -600,6 +1495,6 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
 #endif
 #include "close_code.h"
 
-#endif /* _SDL_audio_h */
+#endif /* SDL_audio_h_ */
 
 /* vi: set ts=4 sw=4 expandtab: */

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_bits.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 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,8 +25,8 @@
  *  Functions for fiddling with bits and bitmasks.
  */
 
-#ifndef _SDL_bits_h
-#define _SDL_bits_h
+#ifndef SDL_bits_h_
+#define SDL_bits_h_
 
 #include "SDL_stdinc.h"
 
@@ -45,12 +45,21 @@ 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_bsr_watcom(Uint32);
+#pragma aux _SDL_bsr_watcom = \
+    "bsr eax, eax" \
+    parm [eax] nomemory \
+    value [eax] \
+    modify exact [eax] nomemory;
+#endif
+
 SDL_FORCE_INLINE int
 SDL_MostSignificantBitIndex32(Uint32 x)
 {
-#if defined(__GNUC__) && __GNUC__ >= 4
+#if defined(__GNUC__) && (__GNUC__ >= 4 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4))
     /* Count Leading Zeroes builtin in GCC.
      * http://gcc.gnu.org/onlinedocs/gcc-4.3.4/gcc/Other-Builtins.html
      */
@@ -58,6 +67,17 @@ SDL_MostSignificantBitIndex32(Uint32 x)
         return -1;
     }
     return 31 - __builtin_clz(x);
+#elif defined(__WATCOMC__) && defined(__386__)
+    if (x == 0) {
+        return -1;
+    }
+    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.
@@ -86,12 +106,21 @@ SDL_MostSignificantBitIndex32(Uint32 x)
 #endif
 }
 
+SDL_FORCE_INLINE SDL_bool
+SDL_HasExactlyOneBitSet32(Uint32 x)
+{
+    if (x && !(x & (x - 1))) {
+        return SDL_TRUE;
+    }
+    return SDL_FALSE;
+}
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }
 #endif
 #include "close_code.h"
 
-#endif /* _SDL_bits_h */
+#endif /* SDL_bits_h_ */
 
 /* vi: set ts=4 sw=4 expandtab: */

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_blendmode.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 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,8 +25,8 @@
  *  Header file declaring the SDL_BlendMode enumeration
  */
 
-#ifndef _SDL_blendmode_h
-#define _SDL_blendmode_h
+#ifndef SDL_blendmode_h_
+#define SDL_blendmode_h_
 
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
@@ -47,17 +47,152 @@ typedef enum
     SDL_BLENDMODE_ADD = 0x00000002,      /**< additive blending
                                               dstRGB = (srcRGB * srcA) + dstRGB
                                               dstA = dstA */
-    SDL_BLENDMODE_MOD = 0x00000004       /**< color modulate
+    SDL_BLENDMODE_MOD = 0x00000004,      /**< color modulate
                                               dstRGB = srcRGB * dstRGB
                                               dstA = dstA */
+    SDL_BLENDMODE_MUL = 0x00000008,      /**< color multiply
+                                              dstRGB = (srcRGB * dstRGB) + (dstRGB * (1-srcA))
+                                              dstA = dstA */
+    SDL_BLENDMODE_INVALID = 0x7FFFFFFF
+
+    /* Additional custom blend modes can be returned by SDL_ComposeCustomBlendMode() */
+
 } SDL_BlendMode;
 
+/**
+ *  \brief The blend operation used when combining source and destination pixel components
+ */
+typedef enum
+{
+    SDL_BLENDOPERATION_ADD              = 0x1,  /**< dst + src: supported by all renderers */
+    SDL_BLENDOPERATION_SUBTRACT         = 0x2,  /**< dst - src : supported by D3D9, D3D11, OpenGL, OpenGLES */
+    SDL_BLENDOPERATION_REV_SUBTRACT     = 0x3,  /**< src - dst : supported by D3D9, D3D11, OpenGL, OpenGLES */
+    SDL_BLENDOPERATION_MINIMUM          = 0x4,  /**< min(dst, src) : supported by D3D9, D3D11 */
+    SDL_BLENDOPERATION_MAXIMUM          = 0x5   /**< max(dst, src) : supported by D3D9, D3D11 */
+} SDL_BlendOperation;
+
+/**
+ *  \brief The normalized factor used to multiply pixel components
+ */
+typedef enum
+{
+    SDL_BLENDFACTOR_ZERO                = 0x1,  /**< 0, 0, 0, 0 */
+    SDL_BLENDFACTOR_ONE                 = 0x2,  /**< 1, 1, 1, 1 */
+    SDL_BLENDFACTOR_SRC_COLOR           = 0x3,  /**< srcR, srcG, srcB, srcA */
+    SDL_BLENDFACTOR_ONE_MINUS_SRC_COLOR = 0x4,  /**< 1-srcR, 1-srcG, 1-srcB, 1-srcA */
+    SDL_BLENDFACTOR_SRC_ALPHA           = 0x5,  /**< srcA, srcA, srcA, srcA */
+    SDL_BLENDFACTOR_ONE_MINUS_SRC_ALPHA = 0x6,  /**< 1-srcA, 1-srcA, 1-srcA, 1-srcA */
+    SDL_BLENDFACTOR_DST_COLOR           = 0x7,  /**< dstR, dstG, dstB, dstA */
+    SDL_BLENDFACTOR_ONE_MINUS_DST_COLOR = 0x8,  /**< 1-dstR, 1-dstG, 1-dstB, 1-dstA */
+    SDL_BLENDFACTOR_DST_ALPHA           = 0x9,  /**< dstA, dstA, dstA, dstA */
+    SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA = 0xA   /**< 1-dstA, 1-dstA, 1-dstA, 1-dstA */
+} SDL_BlendFactor;
+
+/**
+ * Compose a custom blend mode for renderers.
+ *
+ * The functions SDL_SetRenderDrawBlendMode and SDL_SetTextureBlendMode accept
+ * the SDL_BlendMode returned by this function if the renderer supports it.
+ *
+ * A blend mode controls how the pixels from a drawing operation (source) get
+ * combined with the pixels from the render target (destination). First, the
+ * components of the source and destination pixels get multiplied with their
+ * blend factors. Then, the blend operation takes the two products and
+ * calculates the result that will get stored in the render target.
+ *
+ * Expressed in pseudocode, it would look like this:
+ *
+ * ```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 all operations with all factors. However, some
+ *   factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and
+ *   `SDL_BLENDOPERATION_MAXIMUM`.
+ * - **direct3d11**: Same as Direct3D 9.
+ * - **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 since 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,
+                                                                 SDL_BlendOperation colorOperation,
+                                                                 SDL_BlendFactor srcAlphaFactor,
+                                                                 SDL_BlendFactor dstAlphaFactor,
+                                                                 SDL_BlendOperation alphaOperation);
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }
 #endif
 #include "close_code.h"
 
-#endif /* _SDL_blendmode_h */
+#endif /* SDL_blendmode_h_ */
 
 /* vi: set ts=4 sw=4 expandtab: */

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_clipboard.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 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,8 +25,8 @@
  * Include file for SDL clipboard handling
  */
 
-#ifndef _SDL_clipboard_h
-#define _SDL_clipboard_h
+#ifndef SDL_clipboard_h_
+#define SDL_clipboard_h_
 
 #include "SDL_stdinc.h"
 
@@ -39,26 +39,96 @@ 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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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 empty string if there was not enough memory left for
+ * a copy of the clipboard's content.
+ *
+ * \returns the clipboard text on success or an empty string on failure; call
+ *          SDL_GetError() for more information. Caller must call SDL_free()
+ *          on the returned pointer when done with it (even if there was an
+ *          error).
  *
- * \sa SDL_SetClipboardText()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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);
 
+/**
+ * Put UTF-8 text into the primary selection.
+ *
+ * \param text the text to store in the primary selection
+ * \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.26.0.
+ *
+ * \sa SDL_GetPrimarySelectionText
+ * \sa SDL_HasPrimarySelectionText
+ */
+extern DECLSPEC int SDLCALL SDL_SetPrimarySelectionText(const char *text);
+
+/**
+ * Get UTF-8 text from the primary selection, which must be freed with
+ * SDL_free().
+ *
+ * This functions returns empty string if there was not enough memory left for
+ * a copy of the primary selection's content.
+ *
+ * \returns the primary selection text on success or an empty string on
+ *          failure; call SDL_GetError() for more information. Caller must
+ *          call SDL_free() on the returned pointer when done with it (even if
+ *          there was an error).
+ *
+ * \since This function is available since SDL 2.26.0.
+ *
+ * \sa SDL_HasPrimarySelectionText
+ * \sa SDL_SetPrimarySelectionText
+ */
+extern DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void);
+
+/**
+ * Query whether the primary selection exists and contains a non-empty text
+ * string.
+ *
+ * \returns SDL_TRUE if the primary selection has text, or SDL_FALSE if it
+ *          does not.
+ *
+ * \since This function is available since SDL 2.26.0.
+ *
+ * \sa SDL_GetPrimarySelectionText
+ * \sa SDL_SetPrimarySelectionText
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void);
+
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
@@ -66,6 +136,6 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void);
 #endif
 #include "close_code.h"
 
-#endif /* _SDL_clipboard_h */
+#endif /* SDL_clipboard_h_ */
 
 /* vi: set ts=4 sw=4 expandtab: */

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_config.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 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
@@ -19,17 +19,42 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-#ifndef _SDL_config_windows_h
-#define _SDL_config_windows_h
+#ifndef SDL_config_windows_h_
+#define SDL_config_windows_h_
+#define SDL_config_h_
 
 #include "SDL_platform.h"
 
+/* winsdkver.h defines _WIN32_MAXVER for SDK version detection. It is present since at least the Windows 7 SDK,
+ * but out of caution we'll only use it if the compiler supports __has_include() to confirm its presence.
+ * If your compiler doesn't support __has_include() but you have winsdkver.h, define HAVE_WINSDKVER_H.  */
+#if !defined(HAVE_WINSDKVER_H) && defined(__has_include)
+#if __has_include(<winsdkver.h>)
+#define HAVE_WINSDKVER_H 1
+#endif
+#endif
+
+#ifdef HAVE_WINSDKVER_H
+#include <winsdkver.h>
+#endif
+
+/* sdkddkver.h defines more specific SDK version numbers. This is needed because older versions of the
+ * Windows 10 SDK have broken declarations for the C API for DirectX 12. */
+#if !defined(HAVE_SDKDDKVER_H) && defined(__has_include)
+#if __has_include(<sdkddkver.h>)
+#define HAVE_SDKDDKVER_H 1
+#endif
+#endif
+
+#ifdef HAVE_SDKDDKVER_H
+#include <sdkddkver.h>
+#endif
+
 /* 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__)
-#define HAVE_STDINT_H   1
-#elif defined(_MSC_VER)
+#if !defined(HAVE_STDINT_H) && !defined(_STDINT_H_)
+/* Most everything except Visual Studio 2008 and earlier has stdint.h now */
+#if defined(_MSC_VER) && (_MSC_VER < 1600)
 typedef signed __int8 int8_t;
 typedef unsigned __int8 uint8_t;
 typedef signed __int16 int16_t;
@@ -46,28 +71,9 @@ typedef unsigned int uintptr_t;
 #endif
 #define _UINTPTR_T_DEFINED
 #endif
-/* Older Visual C++ headers don't have the Win64-compatible typedefs... */
-#if ((_MSC_VER <= 1200) && (!defined(DWORD_PTR)))
-#define DWORD_PTR DWORD
-#endif
-#if ((_MSC_VER <= 1200) && (!defined(LONG_PTR)))
-#define LONG_PTR LONG
-#endif
-#else /* !__GNUC__ && !_MSC_VER */
-typedef signed char int8_t;
-typedef unsigned char uint8_t;
-typedef signed short int16_t;
-typedef unsigned short uint16_t;
-typedef signed int int32_t;
-typedef unsigned int uint32_t;
-typedef signed long long int64_t;
-typedef unsigned long long uint64_t;
-#ifndef _SIZE_T_DEFINED_
-#define _SIZE_T_DEFINED_
-typedef unsigned int size_t;
-#endif
-typedef unsigned int uintptr_t;
-#endif /* __GNUC__ || _MSC_VER */
+#else
+#define HAVE_STDINT_H 1
+#endif /* Visual Studio 2008 */
 #endif /* !_STDINT_H_ && !HAVE_STDINT_H */
 
 #ifdef _WIN64
@@ -76,21 +82,53 @@ typedef unsigned int uintptr_t;
 # define SIZEOF_VOIDP 4
 #endif
 
+#ifdef __clang__
+# define HAVE_GCC_ATOMICS 1
+#endif
+
 #define HAVE_DDRAW_H 1
 #define HAVE_DINPUT_H 1
 #define HAVE_DSOUND_H 1
+#ifndef __WATCOMC__
 #define HAVE_DXGI_H 1
 #define HAVE_XINPUT_H 1
+#if defined(_WIN32_MAXVER) && _WIN32_MAXVER >= 0x0A00  /* Windows 10 SDK */
+#define HAVE_WINDOWS_GAMING_INPUT_H 1
+#endif
+#if defined(_WIN32_MAXVER) && _WIN32_MAXVER >= 0x0602  /* Windows 8 SDK */
+#define HAVE_D3D11_H 1
+#define HAVE_ROAPI_H 1
+#endif
+#if defined(WDK_NTDDI_VERSION) && WDK_NTDDI_VERSION > 0x0A000008 /* 10.0.19041.0 */
+#define HAVE_D3D12_H 1
+#endif
+#if defined(_WIN32_MAXVER) && _WIN32_MAXVER >= 0x0603  /* Windows 8.1 SDK */
+#define HAVE_SHELLSCALINGAPI_H 1
+#endif
+#define HAVE_MMDEVICEAPI_H 1
+#define HAVE_AUDIOCLIENT_H 1
+#define HAVE_TPCSHRD_H 1
+#define HAVE_SENSORSAPI_H 1
+#endif
+#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
 /* Useful headers */
-#define HAVE_STDIO_H 1
 #define STDC_HEADERS 1
-#define HAVE_STRING_H 1
 #define HAVE_CTYPE_H 1
+#define HAVE_FLOAT_H 1
+#define HAVE_LIMITS_H 1
 #define HAVE_MATH_H 1
 #define HAVE_SIGNAL_H 1
+#define HAVE_STDIO_H 1
+#define HAVE_STRING_H 1
 
 /* C library functions */
 #define HAVE_MALLOC 1
@@ -98,7 +136,11 @@ typedef unsigned int uintptr_t;
 #define HAVE_REALLOC 1
 #define HAVE_FREE 1
 #define HAVE_ALLOCA 1
+/* OpenWatcom requires specific calling conventions for qsort and bsearch */
+#ifndef __WATCOMC__
 #define HAVE_QSORT 1
+#define HAVE_BSEARCH 1
+#endif
 #define HAVE_ABS 1
 #define HAVE_MEMSET 1
 #define HAVE_MEMCPY 1
@@ -106,13 +148,16 @@ typedef unsigned int uintptr_t;
 #define HAVE_MEMCMP 1
 #define HAVE_STRLEN 1
 #define HAVE__STRREV 1
-#define HAVE__STRUPR 1
-#define HAVE__STRLWR 1
+/* These functions have security warnings, so we won't use them */
+/* #undef HAVE__STRUPR */
+/* #undef HAVE__STRLWR */
 #define HAVE_STRCHR 1
 #define HAVE_STRRCHR 1
 #define HAVE_STRSTR 1
-#define HAVE__LTOA 1
-#define HAVE__ULTOA 1
+/* #undef HAVE_STRTOK_R */
+/* These functions have security warnings, so we won't use them */
+/* #undef HAVE__LTOA */
+/* #undef HAVE__ULTOA */
 #define HAVE_STRTOL 1
 #define HAVE_STRTOUL 1
 #define HAVE_STRTOD 1
@@ -122,30 +167,75 @@ typedef unsigned int uintptr_t;
 #define HAVE_STRNCMP 1
 #define HAVE__STRICMP 1
 #define HAVE__STRNICMP 1
-#define HAVE_ATAN 1
-#define HAVE_ATAN2 1
+#define HAVE__WCSICMP 1
+#define HAVE__WCSNICMP 1
+#define HAVE__WCSDUP 1
 #define HAVE_ACOS   1
 #define HAVE_ASIN   1
+#define HAVE_ATAN   1
+#define HAVE_ATAN2  1
 #define HAVE_CEIL   1
 #define HAVE_COS    1
-#define HAVE_COSF 1
+#define HAVE_EXP    1
 #define HAVE_FABS   1
 #define HAVE_FLOOR  1
+#define HAVE_FMOD   1
 #define HAVE_LOG    1
+#define HAVE_LOG10  1
 #define HAVE_POW    1
 #define HAVE_SIN    1
-#define HAVE_SINF 1
 #define HAVE_SQRT   1
-#define HAVE_SQRTF 1
 #define HAVE_TAN    1
+#ifndef __WATCOMC__
+#define HAVE_ACOSF  1
+#define HAVE_ASINF  1
+#define HAVE_ATANF  1
+#define HAVE_ATAN2F 1
+#define HAVE_CEILF  1
+#define HAVE__COPYSIGN 1
+#define HAVE_COSF   1
+#define HAVE_EXPF   1
+#define HAVE_FABSF  1
+#define HAVE_FLOORF 1
+#define HAVE_FMODF  1
+#define HAVE_LOGF   1
+#define HAVE_LOG10F 1
+#define HAVE_POWF   1
+#define HAVE_SINF   1
+#define HAVE_SQRTF  1
 #define HAVE_TANF   1
+#endif
+#if defined(_MSC_VER)
+/* 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_COPYSIGN 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_TRUNC  1
+#define HAVE_TRUNCF 1
+#endif
+/* This function is available with at least the VC++ 2008 C runtime library */
+#if _MSC_VER >= 1400
+#define HAVE__FSEEKI64 1
 #endif
-#if !defined(_MSC_VER) || defined(_USE_MATH_DEFINES)
+#ifdef _USE_MATH_DEFINES
+#define HAVE_M_PI 1
+#endif
+#elif defined(__WATCOMC__)
+#define HAVE__FSEEKI64 1
+#define HAVE_STRTOLL 1
+#define HAVE_STRTOULL 1
+#define HAVE_VSSCANF 1
+#define HAVE_ROUND 1
+#define HAVE_SCALBN 1
+#define HAVE_TRUNC  1
+#else
 #define HAVE_M_PI 1
 #endif
 #else
@@ -154,22 +244,40 @@ typedef unsigned int uintptr_t;
 #endif
 
 /* Enable various audio drivers */
+#if defined(HAVE_MMDEVICEAPI_H) && defined(HAVE_AUDIOCLIENT_H)
+#define SDL_AUDIO_DRIVER_WASAPI 1
+#endif
 #define SDL_AUDIO_DRIVER_DSOUND 1
-#define SDL_AUDIO_DRIVER_XAUDIO2    1
 #define SDL_AUDIO_DRIVER_WINMM  1
 #define SDL_AUDIO_DRIVER_DISK   1
 #define SDL_AUDIO_DRIVER_DUMMY  1
 
 /* Enable various input drivers */
 #define SDL_JOYSTICK_DINPUT 1
+#define SDL_JOYSTICK_HIDAPI 1
+#ifndef __WINRT__
+#define SDL_JOYSTICK_RAWINPUT   1
+#endif
+#define SDL_JOYSTICK_VIRTUAL    1
+#ifdef HAVE_WINDOWS_GAMING_INPUT_H
+#define SDL_JOYSTICK_WGI    1
+#endif
 #define SDL_JOYSTICK_XINPUT 1
 #define SDL_HAPTIC_DINPUT   1
 #define SDL_HAPTIC_XINPUT   1
 
+/* Enable the sensor driver */
+#ifdef HAVE_SENSORSAPI_H
+#define SDL_SENSOR_WINDOWS  1
+#else
+#define SDL_SENSOR_DUMMY    1
+#endif
+
 /* 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 */
@@ -182,8 +290,11 @@ typedef unsigned int uintptr_t;
 #ifndef SDL_VIDEO_RENDER_D3D
 #define SDL_VIDEO_RENDER_D3D    1
 #endif
-#ifndef SDL_VIDEO_RENDER_D3D11
-#define SDL_VIDEO_RENDER_D3D11	0
+#if !defined(SDL_VIDEO_RENDER_D3D11) && defined(HAVE_D3D11_H)
+#define SDL_VIDEO_RENDER_D3D11  1
+#endif
+#if !defined(SDL_VIDEO_RENDER_D3D12) && defined(HAVE_D3D12_H)
+#define SDL_VIDEO_RENDER_D3D12  1
 #endif
 
 /* Enable OpenGL support */
@@ -206,6 +317,8 @@ typedef unsigned int uintptr_t;
 #define SDL_VIDEO_OPENGL_EGL    1
 #endif
 
+/* Enable Vulkan support */
+#define SDL_VIDEO_VULKAN 1
 
 /* Enable system power support */
 #define SDL_POWER_WINDOWS 1
@@ -213,9 +326,6 @@ typedef unsigned int uintptr_t;
 /* Enable filesystem support */
 #define SDL_FILESYSTEM_WINDOWS  1
 
-/* Enable assembly routines (Win64 doesn't have inline asm) */
-#ifndef _WIN64
-#define SDL_ASSEMBLY_ROUTINES   1
-#endif
+#endif /* SDL_config_windows_h_ */
 
-#endif /* _SDL_config_windows_h */
+/* vi: set ts=4 sw=4 expandtab: */

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_cpuinfo.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 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,43 +25,104 @@
  *  CPU feature detection for SDL.
  */
 
-#ifndef _SDL_cpuinfo_h
-#define _SDL_cpuinfo_h
+#ifndef SDL_cpuinfo_h_
+#define SDL_cpuinfo_h_
 
 #include "SDL_stdinc.h"
 
 /* Need to do this here because intrin.h has C++ code in it */
 /* 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__
+/* 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. */
+
+#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>
 #ifndef _WIN64
+#ifndef __MMX__
 #define __MMX__
+#endif
+#ifndef __3dNOW__
 #define __3dNOW__
 #endif
+#endif
+#ifndef __SSE__
 #define __SSE__
+#endif
+#ifndef __SSE2__
 #define __SSE2__
+#endif
+#ifndef __SSE3__
+#define __SSE3__
+#endif
 #elif defined(__MINGW64_VERSION_MAJOR)
 #include <intrin.h>
+#if !defined(SDL_DISABLE_ARM_NEON_H) && defined(__ARM_NEON)
+#  include <arm_neon.h>
+#endif
 #else
-#ifdef __ALTIVEC__
-#if HAVE_ALTIVEC_H && !defined(__APPLE_ALTIVEC__)
+/* 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)
 #include <altivec.h>
-#undef pixel
+#endif
+#if !defined(SDL_DISABLE_ARM_NEON_H)
+#  if defined(__ARM_NEON)
+#    include <arm_neon.h>
+#  elif defined(__WINDOWS__) || defined(__WINRT__) || defined(__GDK__)
+/* Visual Studio doesn't define __ARM_ARCH, but _M_ARM (if set, always 7), and _M_ARM64 (if set, always 1). */
+#    if defined(_M_ARM)
+#      include <armintr.h>
+#      include <arm_neon.h>
+#      define __ARM_NEON 1 /* Set __ARM_NEON so that it can be used elsewhere, at compile time */
+#    endif
+#    if defined (_M_ARM64)
+#      include <arm64intr.h>
+#      include <arm64_neon.h>
+#      define __ARM_NEON 1 /* Set __ARM_NEON so that it can be used elsewhere, at compile time */
+#      define __ARM_ARCH 8
 #    endif
 #  endif
-#ifdef __MMX__
-#include <mmintrin.h>
 #endif
-#ifdef __3dNOW__
+#endif /* compiler version */
+
+#if defined(__3dNOW__) && !defined(SDL_DISABLE_MM3DNOW_H)
 #include <mm3dnow.h>
 #endif
-#ifdef __SSE__
+#if defined(__loongarch_sx) && !defined(SDL_DISABLE_LSX_H)
+#include <lsxintrin.h>
+#define __LSX__
+#endif
+#if defined(__loongarch_asx) && !defined(SDL_DISABLE_LASX_H)
+#include <lasxintrin.h>
+#define __LASX__
+#endif
+#if defined(HAVE_IMMINTRIN_H) && !defined(SDL_DISABLE_IMMINTRIN_H)
+#include <immintrin.h>
+#else
+#if defined(__MMX__) && !defined(SDL_DISABLE_MMINTRIN_H)
+#include <mmintrin.h>
+#endif
+#if defined(__SSE__) && !defined(SDL_DISABLE_XMMINTRIN_H)
 #include <xmmintrin.h>
 #endif
-#ifdef __SSE2__
+#if defined(__SSE2__) && !defined(SDL_DISABLE_EMMINTRIN_H)
 #include <emmintrin.h>
 #endif
+#if defined(__SSE3__) && !defined(SDL_DISABLE_PMMINTRIN_H)
+#include <pmmintrin.h>
 #endif
+#endif /* HAVE_IMMINTRIN_H */
 
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
@@ -77,78 +138,450 @@ 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
- *  or SIMD prefetch sizes.
+ * \returns the L1 cache line size of the CPU, in bytes.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \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 the amount of RAM configured in the system, in MB.
+ * 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.
+ *
+ * \since This function is available since SDL 2.0.9.
+ *
+ * \sa SDL_HasAVX
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void);
+
+/**
+ * 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.
+ *
+ * \since This function is available since SDL 2.0.12.
+ *
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.6.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void);
+
+/**
+ * Determine whether the CPU has LSX (LOONGARCH SIMD) features.
+ *
+ * This always returns false on CPUs that aren't using LOONGARCH instruction
+ * sets.
+ *
+ * \returns SDL_TRUE if the CPU has LOONGARCH LSX features or SDL_FALSE if
+ *          not.
+ *
+ * \since This function is available since SDL 2.24.0.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void);
+
+/**
+ * Determine whether the CPU has LASX (LOONGARCH SIMD) features.
+ *
+ * This always returns false on CPUs that aren't using LOONGARCH instruction
+ * sets.
+ *
+ * \returns SDL_TRUE if the CPU has LOONGARCH LASX features or SDL_FALSE if
+ *          not.
+ *
+ * \since This function is available since SDL 2.24.0.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasLASX(void);
+
+/**
+ * Get the amount of RAM configured in the system.
+ *
+ * \returns the amount of RAM configured in the system in MiB.
+ *
+ * \since This function is available since SDL 2.0.1.
  */
 extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
 
+/**
+ * Report the alignment this system needs for SIMD allocations.
+ *
+ * This will return the minimum number of bytes to which a pointer must be
+ * aligned to be compatible with SIMD instructions on the current machine. For
+ * example, if the machine supports SSE only, it will return 16, but if it
+ * supports AVX-512F, it'll return 64 (etc). This only reports values for
+ * instruction sets SDL knows about, so if your SDL build doesn't have
+ * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
+ * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
+ * Plan accordingly.
+ *
+ * \returns the alignment in bytes needed for available, known SIMD
+ *          instructions.
+ *
+ * \since This function is available since SDL 2.0.10.
+ */
+extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
+
+/**
+ * Allocate memory in a SIMD-friendly way.
+ *
+ * This will allocate a block of memory that is suitable for use with SIMD
+ * instructions. Specifically, it will be properly aligned and padded for the
+ * system's supported vector instructions.
+ *
+ * The memory returned will be padded such that it is safe to read or write an
+ * incomplete vector at the end of the memory block. This can be useful so you
+ * don't have to drop back to a scalar fallback at the end of your SIMD
+ * processing loop to deal with the final elements without overflowing the
+ * allocated buffer.
+ *
+ * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free() or
+ * delete[], etc.
+ *
+ * Note that SDL will only deal with SIMD instruction sets it is aware of; for
+ * example, SDL 2.0.8 knows that SSE wants 16-byte vectors (SDL_HasSSE()), and
+ * AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't know that AVX-512 wants
+ * 64. To be clear: if you can't decide to use an instruction set with an
+ * SDL_Has*() function, don't use that instruction set with memory allocated
+ * through here.
+ *
+ * SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't
+ * out of memory, but you are not allowed to dereference it (because you only
+ * own zero bytes of that buffer).
+ *
+ * \param len The length, in bytes, of the block to allocate. The actual
+ *            allocated block might be larger due to padding, etc.
+ * \returns a pointer to the newly-allocated block, NULL if out of memory.
+ *
+ * \since This function is available since SDL 2.0.10.
+ *
+ * \sa SDL_SIMDGetAlignment
+ * \sa SDL_SIMDRealloc
+ * \sa SDL_SIMDFree
+ */
+extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
+
+/**
+ * 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_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.
+ *
+ * \since This function is available since SDL 2.0.14.
+ *
+ * \sa SDL_SIMDGetAlignment
+ * \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.
+ *
+ * \since This function is available since SDL 2.0.10.
+ *
+ * \sa SDL_SIMDAlloc
+ * \sa SDL_SIMDRealloc
+ */
+extern DECLSPEC void SDLCALL SDL_SIMDFree(void *ptr);
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
@@ -156,6 +589,6 @@ extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
 #endif
 #include "close_code.h"
 
-#endif /* _SDL_cpuinfo_h */
+#endif /* SDL_cpuinfo_h_ */
 
 /* vi: set ts=4 sw=4 expandtab: */