Merge commit 'b22c6238d5eb65ced42808ec326aae75d0d5c9ed' into back-to-imgui

external/SDL/docs/README-cmake.md

@@ -157,7 +157,7 @@ flags to the compiler.
 - Use [`CMAKE_EXE_LINKER_FLAGS`](https://cmake.org/cmake/help/latest/variable/CMAKE_EXE_LINKER_FLAGS.html) to pass extra option to the linker for executables.
 - Use [`CMAKE_SHARED_LINKER_FLAGS`](https://cmake.org/cmake/help/latest/variable/CMAKE_SHARED_LINKER_FLAGS.html) to pass extra options to the linker for shared libraries.
 
-#### Examples
+#### Compile Options Examples
 
 - build a SDL library optimized for (more) modern x64 microprocessor architectures.
 
@@ -240,7 +240,7 @@ Append with a version number to target a specific SDK revision: e.g. `iphoneos12
 
 CMake documentation: [link](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_SYSROOT.html)
 
-#### Examples
+#### Apple Examples
 
 - for macOS, building a dylib and/or static library for x86_64 and arm64:
 
@@ -328,7 +328,7 @@ Configure your project with `-DSDL_LIBC=ON` to make use of sanitizers.
 ### CMake fails to build without X11 or Wayland support
 
 Install the required system packages prior to running CMake.
-See [README-linux](linux#build-dependencies) for the list of dependencies on Linux.
+See [README-linux.md](README-linux.md#build-dependencies) for the list of dependencies on Linux.
 Other unix operating systems should provide similar packages.
 
 If you **really** don't need to show windows, add `-DSDL_UNIX_CONSOLE_BUILD=ON` to the CMake configure command.

external/SDL/docs/README-documentation-rules.md

@@ -34,6 +34,12 @@ things, you might confuse it. This is to the benefit of documentation, though,
 where we would rather you not do surprising things.
 
 
+## UTF-8 only!
+
+All text must be UTF-8 encoded. The wiki will refuse to update files that are
+malformed.
+
+
 ## We _sort of_ write in Doxygen format.
 
 To document a symbol, we use something that looks like Doxygen (and Javadoc)
@@ -327,6 +333,16 @@ If you add Doxygen with a `##` (`###`, etc) section header, it'll
 migrate to the wiki and be _removed_ from the headers. Generally
 the correct thing to do is _never use section headers in the Doxygen_.
 
+## wikiheaders will reorder standard sections.
+
+The standard sections are always kept in a consistent order by
+wikiheaders, both in the headers and the wiki. If they're placed in
+a non-standard order, wikiheaders will reorder them.
+
+For sections that aren't standard, wikiheaders will place them at
+the end of the wiki page, in the order they were seen when it loaded
+the page for processing.
+
 ## It's okay to repeat yourself.
 
 Each individual piece of documentation becomes a separate page on the wiki, so
@@ -340,7 +356,7 @@ through, header users can search for the function name.
 
 You might be reading this document on the wiki! Any `README-*.md` files in
 the docs directory are bridged to the wiki, so `docs/README-linux.md` lands
-at https://wiki.libsdl.org/SDL3/README/linux ...these are just copied directly
+at https://wiki.libsdl.org/SDL3/README-linux ...these are just copied directly
 without any further processing by wikiheaders, and changes go in both
 directions.
 

external/SDL/docs/README-emscripten.md

@@ -103,7 +103,7 @@ getting started.
 
 Another option is to use SDL' main callbacks, which handle this for you
 without platform-specific code in your app. Please refer to
-[the wiki](https://wiki.libsdl.org/SDL3/README/main-functions#main-callbacks-in-sdl3)
+[the wiki](https://wiki.libsdl.org/SDL3/README-main-functions#main-callbacks-in-sdl3)
 or `docs/README-main-functions.md` in the SDL source code.
 
 
@@ -230,7 +230,7 @@ tools.
 mkdir build
 cd build
 emcmake cmake ..
-# you can also do `emcmake cmake -G Ninja ..` and then use `ninja` instead of this command.
+# you can also try `emcmake cmake -G Ninja ..` and then use `ninja` instead of this command.
 emmake make -j4
 ```
 

external/SDL/docs/README-linux.md

@@ -46,6 +46,7 @@ openSUSE Tumbleweed:
     libgbm-devel pipewire-devel libpulse-devel sndio-devel Mesa-libEGL-devel
 
 Arch:
+
     sudo pacman -S alsa-lib cmake hidapi ibus jack libdecor libgl libpulse libusb libx11 libxcursor libxext libxinerama libxkbcommon libxrandr libxrender libxss libxtst mesa ninja pipewire sndio vulkan-driver vulkan-headers wayland wayland-protocols
 
 

external/SDL/docs/README-ngage.md

@@ -1,5 +1,64 @@
-Support for the Nokia N-Gage has been removed from SDL3 (but will make a
-comeback when newer compilers are available for the platform).
+# Nokia N-Gage
 
-SDL2 still supports this platform.
+SDL port for the Nokia N-Gage
+[Homebrew toolchain](https://github.com/ngagesdk/ngage-toolchain)
+contributed by:
 
+- [Michael Fitzmayer](https://github.com/mupfdev)
+
+- [Anonymous Maarten](https://github.com/madebr)
+
+Many thanks to:
+
+- icculus and slouken for always making room for us, even when we show up in 2025
+ still waving the N-Gage flag.
+
+- The Nokia N-Gage [Discord community](https://discord.gg/dbUzqJ26vs)
+ who keeps the platform alive.
+
+- The staff and supporters of the
+ [Suomen pelimuseo](https://www.vapriikki.fi/nayttelyt/fantastinen-floppi/), and
+ to Heikki Jungmann, for their ongoing love and dedication for the Nokia N-Gage --
+ you guys are awesome!
+
+## History
+
+When SDL support was discontinued due to the lack of C99 support at the time,
+this version was rebuilt from the ground up after resolving the compiler issues.
+
+In contrast to the earlier SDL2 port, this version features a dedicated rendering
+backend and a functional, albeit limited, audio interface.  Support for the
+software renderer has been removed.
+
+The outcome is a significantly leaner and more efficient SDL port, which we hope
+will breathe new life into this beloved yet obscure platform.
+
+## To the Stubborn Legends of the DC Scene
+
+This port is lovingly dedicated to the ever-nostalgic Dreamcast homebrew scene --
+because if we managed to pull this off for the N-Gage (yes, the N-Gage), surely
+you guys can stop clinging to SDL2 like it's a rare Shenmue prototype and finally
+make the leap to SDL3.  It's 2025, not 1999 -- and let's be honest, you're rocking
+a state-of-the-art C23 compiler.  The irony writes itself.
+
+## Existing Issues and Limitations
+
+- For now, the new
+ [SDL3 main callbacks](https://wiki.libsdl.org/SDL3/README/main-functions#how-to-use-main-callbacks-in-sdl3)
+ are not optional and must be used. This is important as the callbacks
+ are optional on other platforms.
+
+- If the application is put in the background while sound is playing,
+ some of the audio is looped until the app is back in focus.
+
+- It is recommended initialising SDLs audio sub-system even when it
+ is not required. The backend is started at a higher level.  Initialising
+ SDLs audio sub-system ensures that the backend is properly deinitialised.
+
+- Because the audio sample rate can change during phone calls, the sample
+ rate is currently fixed at 8kHz to ensure stable behavior.  Although
+ dynamically adjusting the sample rate is theoretically possible, the
+ current implementation doesn't support it yet.  This limitation is
+ expected to be resolved in a future update.
+
+- Dependency tracking is currently non-functional.

external/SDL/docs/README-platforms.md

@@ -11,7 +11,7 @@
 - [macOS](README-macos.md)
 - [NetBSD](README-bsd.md)
 - [Nintendo Switch](README-switch.md)
-- [Nintendo 3DS](README-3ds.md)
+- [Nintendo 3DS](README-n3ds.md)
 - [OpenBSD](README-bsd.md)
 - [PlayStation 2](README-ps2.md)
 - [PlayStation 4](README-ps4.md)
@@ -24,6 +24,7 @@
 - [Windows](README-windows.md)
 - [Windows GDK](README-gdk.md)
 - [Xbox](README-gdk.md)
+- [Nokia N-Gage](README-ngage.md)
 
 ## Unsupported Platforms
 
@@ -33,7 +34,6 @@ All of these still work with [SDL2](/SDL2), which is an incompatible API, but an
 
 - Google Stadia
 - NaCL
-- Nokia N-Gage
 - OS/2
 - QNX
 - WinPhone

external/SDL/docs/README-wayland.md

@@ -59,6 +59,15 @@ encounter limitations or behavior that is different from other windowing systems
   `SDL_APP_ID` hint string, the desktop entry file name should match the application ID. For example, if your
   application ID is set to `org.my_org.sdl_app`, the desktop entry file should be named `org.my_org.sdl_app.desktop`.
 
+### The application progress bar can't be set via ```SDL_SetWindowProgressState()``` or ```SDL_SetWindowProgressValue()```
+
+- Only some Desktop Environemnts support the underlying API. Known compatible DEs: Unity, KDE
+- The underlying API requires a desktop entry file, aka a `.desktop` file.
+  Please see the [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/) for
+  more information on the format of this file. Note that if your application manually sets the application ID via the
+  `SDL_APP_ID` hint string, the desktop entry file name should match the application ID. For example, if your
+  application ID is set to `org.my_org.sdl_app`, the desktop entry file should be named `org.my_org.sdl_app.desktop`.
+
 ### Keyboard grabs don't work when running under XWayland
 
 - On GNOME based desktops, the dconf setting `org/gnome/mutter/wayland/xwayland-allow-grabs` must be enabled.