update SDL3 from 3.2.20 to 3.4.2

2026-04-01 18:25:03 +02:00
parent 1daf4d79f1
commit 05b19704f8
1626 changed files with 124218 additions and 191491 deletions
@@ -22,7 +22,7 @@ set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$<CONFIGURATION>")
 # This assumes the SDL source is available in vendored/SDL
 add_subdirectory(vendored/SDL EXCLUDE_FROM_ALL)

-# on Web targets, we need CMake to generate a HTML webpage. 
+# on Web targets, we need CMake to generate a HTML webpage.
 if(EMSCRIPTEN)
  set(CMAKE_EXECUTABLE_SUFFIX ".html" CACHE INTERNAL "")
 endif()
@@ -1,6 +1,6 @@
 # Introduction to SDL with MinGW

-Without getting deep into the history, MinGW is a long running project that aims to bring gcc to Windows. That said, there's many distributions, versions, and forks floating around. We recommend installing [MSYS2](https://www.msys2.org/), as it's the easiest way to get a modern toolchain with a package manager to help with dependency management. This would allow you to follow the MSYS2 section below. 
+Without getting deep into the history, MinGW is a long running project that aims to bring gcc to Windows. That said, there's many distributions, versions, and forks floating around. We recommend installing [MSYS2](https://www.msys2.org/), as it's the easiest way to get a modern toolchain with a package manager to help with dependency management. This would allow you to follow the MSYS2 section below.

 Otherwise you'll want to follow the "Other Distributions" section below.

@@ -89,7 +89,7 @@ This should print out which library directory we'll need to use when compiling,
 Now we should have everything needed to compile and run our program. You'll need to ensure to replace `<version>` with the version of the release of SDL3 you downloaded, as well as use the `<arch>` we learned in the previous section.

 ```sh
-gcc hello.c -o hello.exe -I SDL3-<version>/<arch>/include -L SDL3-<version>/<arch>/lib -lSDL3 -mwindows 
+gcc hello.c -o hello.exe -I SDL3-<version>/<arch>/include -L SDL3-<version>/<arch>/lib -lSDL3 -mwindows
 cp SDL3-<version>/<arch>/bin/SDL3.dll SDL3.dll
 ./hello.exe
 ```
@@ -149,7 +149,7 @@ target_link_libraries(yourgame PRIVATE SDL3::SDL3)

 If you use ndk-build, add the following before `include $(BUILD_SHARED_LIBRARY)` to your `Android.mk`:
 ```
-LOCAL_SHARED_LIBARARIES := SDL3 SDL3-Headers
+LOCAL_SHARED_LIBRARIES := SDL3 SDL3-Headers
 ```
 And add the following at the bottom:
 ```
@@ -598,7 +598,7 @@ The only caveat is that the APK's support a single architecture.

 When configuring the CMake project, you need to use the Android NDK CMake toolchain, and pass the Android home path through `SDL_ANDROID_HOME`.
 ```
-cmake .. -DCMAKE_TOOLCHAIN_FILE=<path/to/android.toolchain.cmake> -DANDROID_ABI=<android-abi> -DSDL_ANDROID_HOME=<path-to-android-sdk-home> -DANDROID_PLATFORM=23 -DSDL_TESTS=ON
+cmake .. -DCMAKE_TOOLCHAIN_FILE=<path/to/android.toolchain.cmake> -DANDROID_ABI=<android-abi> -DSDL_ANDROID_HOME=<path-to-android-sdk-home> -DANDROID_PLATFORM=21 -DSDL_TESTS=ON
 ```

 Remarks:
@@ -4,3 +4,4 @@ SDL is fully supported on BSD platforms, and is built using [CMake](README-cmake

 If you want to run on the console, you can take a look at [KMSDRM support on BSD](README-kmsbsd.md)

+SDL is [not designed to be used in setuid or setgid executables](README-platforms.md#setuid).
@@ -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,8 +328,8 @@ 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.
-Other unix operationg systems should provide similar packages.
+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.

@@ -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)
@@ -156,6 +162,23 @@ wikiheaders will wordwrap header comments so they fit in 80 columns, so if you
 don't leave a blank line between paragraphs, they will smush into a single
 block of text when wordwrapping.

+## Lists must be the start of a new paragraph.
+
+If you write this:
+
+```
+Here is some text without a blank line
+before an unordered list!
+- item a
+- item b
+- item c
+```
+
+...then wikiheaders will word wrap this as a single paragraph, mangling the list.
+
+Put a blank line before the list, and everything will format and wrap correctly.
+
+This is a limitation of wikiheaders. Don't get bit by it!

 ## Don't worry about word wrapping.

@@ -251,6 +274,23 @@ comment. So don't mention the type a second time in the documentation if
 possible. It looks cluttered and repetitive to do so.


+## Keep `\param` and `\returns` sections short.
+
+These strings end up in a table that we don't want to be bulky.
+Try to keep these to one sentence/phrase where possible. If you need more
+detail--even extremely common details, like "you need to free the returned
+pointer"--put that information in the general Remarks section, where you
+can be as verbose as you like.
+
+(One exception for SDL: the return value almost always notes that on error,
+you should call SDL_GetError() to get more information. The documentation
+is so saturated with this that it's just the standard now.)
+
+Convention at the moment is that pointer params that are permitted to
+be NULL, which is somewhat uncommon, end with terse "May be NULL." sentence
+at the end, and pointers that must be non-NULL (most of them) say nothing.
+This is fine.
+
 ## Code examples go in the wiki.

 We don't want the headers cluttered up with code examples. These live on the
@@ -304,6 +344,21 @@ to the headers:
 - "Version"
 - "See Also"

+## Unrecognized sections are removed from the headers!
+
+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.

@@ -318,7 +373,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.

@@ -408,3 +463,19 @@ Beyond stripping the initial ` * ` portion off each line, these comments are
 treated as pure Markdown. They don't support any Doxygen tags like `\sa` or
 `\since`.

+## Enum/struct versioning
+
+If you have an enum or struct, it'll list its `\since` field as the first SDL
+release it was available in. However, we might later add new values to an enum
+or fields to a struct. These lines, arriving in a newer version, should have a
+note about that, like this one on SDL_SCALEMODE_PIXELART:
+
+```c
+typedef enum SDL_ScaleMode
+{
+    SDL_SCALEMODE_INVALID = -1,
+    SDL_SCALEMODE_NEAREST,  /**< nearest pixel sampling */
+    SDL_SCALEMODE_LINEAR,   /**< linear filtering */
+    SDL_SCALEMODE_PIXELART  /**< nearest pixel sampling with improved scaling for pixel art (since SDL 3.3.0) */
+} SDL_ScaleMode;
+```
@@ -101,9 +101,9 @@ don't want any shutdown code that might be sitting below this code
 to actually run if main() were to continue on, since we're just
 getting started.

-Another option is to use SDL' main callbacks, which handle this for you
+Another option is to use SDL's 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.


@@ -169,31 +169,33 @@ for several reasons, not the least of which being that no one likes when a
 random browser tab suddenly starts making noise and the user has to scramble
 to figure out which and silence it.

-SDL will allow you to open the audio device for playback in this
-circumstance, and your audio callback will fire, but SDL will throw the audio
-data away until the user interacts with the page. This helps apps that depend
-on the audio callback to make progress, and also keeps audio playback in sync
+SDL will allow you to open the audio device for playback in this circumstance,
+and your audio streams will consume data, but SDL will throw the audio data
+away until the user interacts with the page. This helps apps that depend on
+the audio callback to make progress, and also keeps audio playback in sync
 once the app is finally allowed to make noise.

 There are two reasonable ways to deal with the silence at the app level:
 if you are writing some sort of media player thing, where the user expects
 there to be a volume control when you mouseover the canvas, just default
 that control to a muted state; if the user clicks on the control to unmute
-it, on this first click, open the audio device. This allows the media to
+it, on this first click, adjust your app's volume appropriately, and SDL will
+also start actually feeding the data to the browser. This allows the media to
 play at start, and the user can reasonably opt-in to listening.

-Many games do not have this sort of UI, and are more rigid about starting
-audio along with everything else at the start of the process. For these, your
-best bet is to write a little Javascript that puts up a "Click here to play!"
-UI, and upon the user clicking, remove that UI and then call the Emscripten
-app's main() function. As far as the application knows, the audio device was
-available to be opened as soon as the program started, and since this magic
-happens in a little Javascript, you don't have to change your C/C++ code at
-all to make it happen.
+Many games do not have this sort of UI. For these, your best bet might be to
+write a little Javascript that puts up a "Click here to play!" UI, and upon
+the user clicking, remove that UI and then call the Emscripten app's main()
+function. As far as the application knows, audio was able to play as soon as
+the program started, and since this magic happens in a little Javascript, you
+don't have to change your C/C++ code at all to make it happen.

 Please see the discussion at https://github.com/libsdl-org/SDL/issues/6385
 for some Javascript code to steal for this approach.

+But if a game can just do without audio until the user clicks on the page,
+it will still operate correctly, as if the page was merely muted before then.
+

 ## Rendering

@@ -208,12 +210,35 @@ Calling SDL_RenderPresent (or SDL_GL_SwapWindow) will not actually
 present anything on the screen until your return from your mainloop
 function.

+Note that SDL attempts to default to vsync _off_ on all platforms. You almost
+certainly do _not_ want this in Emscripten, however, as it will affect the
+efficiency of the mainloop. If using OpenGL directly, you should call
+SDL_GL_SetSwapInterval(1) sometime near startup; if using the 2D render API,
+either create the renderer with with the property
+SDL_PROP_RENDERER_CREATE_PRESENT_VSYNC_NUMBER set to 1, or call
+SDL_SetRenderVSync(renderer, 1). If you don't explicitly set vsync, you'll get
+a higher (but perhaps unstable) framerate, and use more power, but it will
+still work. Choosing a vsync of 1 will use requestAnimationFrame if possible.
+
+If you're using the SDL main callbacks, the mainloop defaults to using
+requestAnimationFrame (effectively vsync), because it calls
+emscripten_set_main_loop() with a zero fps. This is almost certainly what you
+want to do! Do this even if you aren't using the main callbacks!
+SDL will attempt to accomodate the app if it messes with vsync settings, or
+doesn't use requestAnimationFrame, but modern thinking is that this is the
+most efficient, consistent, and correct way to run a game in a web browser.
+

 ## Building SDL/emscripten

+Use the latest stable Emscripten release!

-SDL currently requires at least Emscripten 3.16.0 to build. Newer versions
-are likely to work, as well.
+It's possible to build SDL with older Emscripten releases, such as 3.x, but
+several things will be silently broken, as bugs got fixed and web standards
+solidified over time. At the time of this writing, Emscripten 4.0.x is the
+current stable release. You're encouraged to install the latest stable release
+(`emsdk install latest ; emsdk activate latest` if using Emscripten's setup
+script), and make sure you're reasonably up to date as time goes on.


 Build:
@@ -230,7 +255,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
 ```

@@ -239,7 +264,7 @@ If you want to build with thread support, something like this works:
 ```bash
 mkdir build
 cd build
-emcmake cmake -DSDL_THREADS=ON ..
+emcmake cmake -DSDL_PTHREADS=ON ..
 # you can also do `emcmake cmake -G Ninja ..` and then use `ninja` instead of this command.
 emmake make -j4
 ```
@@ -322,6 +347,22 @@ all has to live in memory at runtime.
 gives other options and details, and is worth a read.


+## Customizing index.html
+
+You don't have to use the HTML that Emscripten produces; the above examples
+use `emcc -o index.html`, but you can `-o index.js` instead to just output
+code without an HTML page, and then provide your own. This is desirable for
+shipping products, even though the Emscripten-provided HTML is fine for
+prototyping. Certain things _must_ be in the HTML file or your program will
+not function correctly (or function at all). The specifics are beyond the
+scope of this document, but it's likely best to start with the Emscripten HTML
+and customize it, instead of starting from scratch.
+
+The `<canvas>` element in the HTML _must not_ have a border or padding, or
+things will break in unexpected ways. This can be surprising when customizing
+the page's look. Plan accordingly.
+
+
 ## Debugging

 Debugging web apps is a mixed bag. You should compile and link with
@@ -336,9 +377,9 @@ If you try debugging in Firefox and it doesn't work well for no apparent
 reason, try Chrome, and vice-versa. These tools are still relatively new,
 and improving all the time.

-SDL_Log() (or even plain old printf) will write to the Javascript console,
-and honestly I find printf-style debugging to be easier than setting up a build
-for proper debugging, so use whatever tools work best for you.
+SDL_Log() (or printf) will write to the Javascript console,
+so printf-style debugging can be easier than setting up a build
+for proper debugging. Use whatever tools work best for you.


 ## Questions?
@@ -12,9 +12,44 @@ Instructions:
 2. Select your desired target, and hit build.


-Using the Simple DirectMedia Layer for iOS
+Using the Simple DirectMedia Layer for iOS with the SDL3 xcFramework
 ==============================================================================

+The recommended way to use SDL for iOS is by including the SDL3.xcframework which is now a build target of the SDL.xcodeproj file. An xcframework is a new (Xcode 11) uber-framework which can handle any combination of processor type and target OS platform.
+You can either build the SDL3.xcframework yourself or download the latest release disk image asset (*.dmg).
+
+In the past, iOS devices were always an ARM variant processor, and the simulator was always i386 or x86_64, and thus libraries could be combined into a single framework for both simulator and device. With the introduction of the Apple Silicon ARM-based machines, regular frameworks would collide as CPU type was no longer sufficient to differentiate the platform. So Apple created the new xcframework library package.
+
+The xcframework target builds into a Products directory alongside the SDL.xcodeproj file, as SDL3.xcframework. This can be brought in to any iOS project and will function properly for both simulator and device, no matter their CPUs. Note that Intel Macs cannot cross-compile for Apple Silicon Macs. If you need AS compatibility, perform this build on an Apple Silicon Mac.
+
+This target requires Xcode 11 or later. The target will simply fail to build if attempted on older Xcodes.
+
+In addition, on Apple platforms, main() cannot be in a dynamically loaded library.
+However, unlike in SDL2, in SDL3 SDL_main is implemented inline in SDL_main.h, so you don't need to link against a static libSDL3main.lib, and you don't need to copy a .c file from the SDL3 source either.
+This means that iOS apps which used the statically-linked libSDL3.lib and now link with the xcframwork can just `#include <SDL3/SDL_main.h>` in the source file that contains their standard `int main(int argc, char *argv[])` function to get a header-only SDL_main implementation that calls the `SDL_RunApp()` with your standard main function.
+
+To use the SDL3.xcframework follow these steps:
+
+1. Run Xcode and create a new project using the iOS Game template, selecting the Objective C language and Metal game technology.
+2. In the main view, delete all files except for Assets and LaunchScreen
+3. Select the project in the main view, go to the "General" tab, scroll down to "Frameworks, Libraries, and Embedded Content", and drag and drop the SDL3.xcframework
+4. Still in "Frameworks, Libraries, and Embedded Content", select "Embed & Sign" for the SDL3.xcframework.
+5. Add the source files that you would normally have for an SDL program, making sure to have #include <SDL3/SDL_main.h> at the top of the file containing your main() function.
+6. Add any assets that your application needs.
+7. Enjoy!
+
+Using an xcFramework is similar to using a regular framework. However, issues have been seen with the build system not seeing the headers in the xcFramework. To remedy this, add the path to the xcFramework in your app's target ==> Build Settings ==> Framework Search Paths and mark it recursive (this is critical). Also critical is to remove "*.framework" from Build Settings ==> Sub-Directories to Exclude in Recursive Searches. Clean the build folder, and on your next build the build system should be able to see any of these in your code, as expected:
+
+#include "SDL3/SDL_main.h"
+#include <SDL3/SDL.h>
+#include <SDL3/SDL_main.h>
+
+
+Using the Simple DirectMedia Layer for iOS by adding the SDL3 Xcode project
+==============================================================================
+
+To maintain compatibility with older Xcode versions than version 11 you can add the SDL3 Xcode project file to your project:
+
 1. Run Xcode and create a new project using the iOS Game template, selecting the Objective C language and Metal game technology.
 2. In the main view, delete all files except for Assets and LaunchScreen
 3. Right click the project in the main view, select "Add Files...", and add the SDL project, Xcode/SDL/SDL.xcodeproj
@@ -26,6 +61,18 @@ Using the Simple DirectMedia Layer for iOS
 9. Add any assets that your application needs.
 10. Enjoy!

+Notes for distributing your iOS app on the AppStore when using the embedded SDL3 Xcode project:
+Embedding the SDL3 Xcode project makes SDL3.framework a target of your app, so it will be included in the archive created during the "Archive" step required for App Store submission. As this prevents successful distribution, remove the framework via a script in the Build Phase after the "Embed & Sign" step.
+
+1. Select the project in the main view, go to the "Build Phases" tab, click on the big '+' in this tab and click "New Run Script Phase".
+2. Scroll down to "Run Script" (after the "Embed SDL3 Framework") and enter the following script:
+```
+    if [ -d "$INSTALL_ROOT/Library" ]; then
+        echo "Removing SDL3.framework from INSTALL_ROOT for archiving"
+        rm -rf "$INSTALL_ROOT/Library"
+    fi
+```
+3. Below the script entry uncheck the "Run Script:" options "For install builds only" and "Based on dependency analysis"

 TODO: Add information regarding App Store requirements such as icons, etc.

@@ -154,26 +201,7 @@ More information on this subject is available here:
 http://developer.apple.com/library/ios/#documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/Introduction/Introduction.html


-Notes -- xcFramework
-==============================================================================

-The SDL.xcodeproj file now includes a target to build SDL3.xcframework. An xcframework is a new (Xcode 11) uber-framework which can handle any combination of processor type and target OS platform.
-
-In the past, iOS devices were always an ARM variant processor, and the simulator was always i386 or x86_64, and thus libraries could be combined into a single framework for both simulator and device. With the introduction of the Apple Silicon ARM-based machines, regular frameworks would collide as CPU type was no longer sufficient to differentiate the platform. So Apple created the new xcframework library package.
-
-The xcframework target builds into a Products directory alongside the SDL.xcodeproj file, as SDL3.xcframework. This can be brought in to any iOS project and will function properly for both simulator and device, no matter their CPUs. Note that Intel Macs cannot cross-compile for Apple Silicon Macs. If you need AS compatibility, perform this build on an Apple Silicon Mac.
-
-This target requires Xcode 11 or later. The target will simply fail to build if attempted on older Xcodes.
-
-In addition, on Apple platforms, main() cannot be in a dynamically loaded library.
-However, unlike in SDL2, in SDL3 SDL_main is implemented inline in SDL_main.h, so you don't need to link against a static libSDL3main.lib, and you don't need to copy a .c file from the SDL3 source either.
-This means that iOS apps which used the statically-linked libSDL3.lib and now link with the xcframwork can just `#include <SDL3/SDL_main.h>` in the source file that contains their standard `int main(int argc, char *argv[])` function to get a header-only SDL_main implementation that calls the `SDL_RunApp()` with your standard main function.
-
-Using an xcFramework is similar to using a regular framework. However, issues have been seen with the build system not seeing the headers in the xcFramework. To remedy this, add the path to the xcFramework in your app's target ==> Build Settings ==> Framework Search Paths and mark it recursive (this is critical). Also critical is to remove "*.framework" from Build Settings ==> Sub-Directories to Exclude in Recursive Searches. Clean the build folder, and on your next build the build system should be able to see any of these in your code, as expected:
-
-#include "SDL_main.h"
-#include <SDL.h>
-#include <SDL_main.h>


 Notes -- iPhone SDL limitations
@@ -8,6 +8,7 @@ system does not have the XRandR libraries installed, it will be disabled
 at runtime, and you won't get a missing library error, at least with the
 default configuration parameters.

+SDL is [not designed to be used in setuid or setgid executables](README-platforms.md#setuid).

 Build Dependencies
 --------------------------------------------------------------------------------
@@ -16,26 +17,28 @@ Ubuntu 18.04, all available features enabled:

    sudo apt-get install build-essential git make \
    pkg-config cmake ninja-build gnome-desktop-testing libasound2-dev libpulse-dev \
-    libaudio-dev libjack-dev libsndio-dev libx11-dev libxext-dev \
-    libxrandr-dev libxcursor-dev libxfixes-dev libxi-dev libxss-dev \
+    libaudio-dev libfribidi-dev libjack-dev libsndio-dev libx11-dev libxext-dev \
+    libxrandr-dev libxcursor-dev libxfixes-dev libxi-dev libxss-dev libxtst-dev \
    libxkbcommon-dev libdrm-dev libgbm-dev libgl1-mesa-dev libgles2-mesa-dev \
-    libegl1-mesa-dev libdbus-1-dev libibus-1.0-dev libudev-dev
+    libegl1-mesa-dev libdbus-1-dev libibus-1.0-dev libudev-dev libthai-dev

 Ubuntu 22.04+ can also add `libpipewire-0.3-dev libwayland-dev libdecor-0-dev liburing-dev` to that command line.

 Fedora 35, all available features enabled:

-    sudo yum install gcc git-core make cmake \
-    alsa-lib-devel pulseaudio-libs-devel nas-devel pipewire-devel \
+    sudo dnf install gcc git-core make cmake \
+    alsa-lib-devel fribidi-devel pulseaudio-libs-devel pipewire-devel \
    libX11-devel libXext-devel libXrandr-devel libXcursor-devel libXfixes-devel \
-    libXi-devel libXScrnSaver-devel dbus-devel ibus-devel \
+    libXi-devel libXScrnSaver-devel libXtst-devel dbus-devel ibus-devel \
    systemd-devel mesa-libGL-devel libxkbcommon-devel mesa-libGLES-devel \
    mesa-libEGL-devel vulkan-devel wayland-devel wayland-protocols-devel \
-    libdrm-devel mesa-libgbm-devel libusb-devel libdecor-devel \
-    pipewire-jack-audio-connection-kit-devel \
+    libdrm-devel mesa-libgbm-devel libusb1-devel libdecor-devel \
+    pipewire-jack-audio-connection-kit-devel libthai-devel

 Fedora 39+ can also add `liburing-devel` to that command line.

+Fedora 40+ needs `zlib-ng-compat-static` to be added to that command line.
+
 NOTES:
 - The sndio audio target is unavailable on Fedora (but probably not what you
  should want to use anyhow).
@@ -43,10 +46,12 @@ NOTES:
 openSUSE Tumbleweed:

    sudo zypper in libunwind-devel libusb-1_0-devel Mesa-libGL-devel libxkbcommon-devel libdrm-devel \
-    libgbm-devel pipewire-devel libpulse-devel sndio-devel Mesa-libEGL-devel
+    libgbm-devel pipewire-devel libpulse-devel sndio-devel Mesa-libEGL-devel alsa-devel xwayland-devel \
+    wayland-devel wayland-protocols-devel libthai-devel fribidi-devel

 Arch:
-    sudo pacman -S alsa-lib cmake hidapi ibus jack libdecor libgl libpulse libusb libx11 libxcursor libxext libxinerama libxkbcommon libxrandr libxrender libxss mesa ninja pipewire sndio vulkan-driver vulkan-headers wayland wayland-protocols
+
+    sudo pacman -S alsa-lib cmake hidapi ibus jack libdecor libthai fribidi libgl libpulse libusb libx11 libxcursor libxext libxfixes libxi libxinerama libxkbcommon libxrandr libxrender libxss libxtst mesa ninja pipewire sndio vulkan-driver vulkan-headers wayland wayland-protocols


 Joystick does not work
@@ -73,6 +73,8 @@ NSApplicationDelegate implementation:
 }
 ```

+SDL is [not designed to be used in setuid or setgid executables](README-platforms.md#setuid).
+
 # Using the Simple DirectMedia Layer with a traditional Makefile

 An existing build system for your SDL app has good chances to work almost
@@ -206,6 +206,13 @@ The SDL_AppResult value that terminated the app is provided here, in case
 it's useful to know if this was a successful or failing run of the app.


+## Using main functions from other languages
+
+If you're not using C/C++, using SDL's entry points is still possible but is
+more complex. Please refer to https://wiki.libsdl.org/SDL3/NonstandardStartup
+for the technical details.
+
+
 ## Summary and Best Practices

 - **Always Include SDL_main.h in One Source File:** When working with SDL,
@@ -611,6 +611,9 @@ The following enums have been renamed:
 The following structures have been renamed:
 * SDL_GameController => SDL_Gamepad

+The following structures have been removed:
+* SDL_GameControllerButtonBind - replaced with SDL_GamepadBinding
+
 The following functions have been renamed:
 * SDL_GameControllerAddMapping() => SDL_AddGamepadMapping()
 * SDL_GameControllerAddMappingsFromFile() => SDL_AddGamepadMappingsFromFile()
@@ -1459,7 +1462,7 @@ The following symbols have been removed:
 * SDL_RENDERER_PRESENTVSYNC - replaced with SDL_PROP_RENDERER_CREATE_PRESENT_VSYNC_NUMBER during renderer creation and SDL_PROP_RENDERER_VSYNC_NUMBER after renderer creation
 * SDL_RENDERER_SOFTWARE - you can check whether the name of the renderer is `SDL_SOFTWARE_RENDERER`
 * SDL_RENDERER_TARGETTEXTURE - all renderers support target texture functionality
-* SDL_ScaleModeBest = use SDL_SCALEMODE_LINEAR instead
+* SDL_ScaleModeBest - use SDL_SCALEMODE_LINEAR instead

 ## SDL_rwops.h

@@ -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#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.
@@ -2,39 +2,61 @@

 ## Supported Platforms

+SDL3 has been known to work on the following platforms at some point:
+
 - [Android](README-android.md)
- [Emscripten](README-emscripten.md)
+- [Emscripten](README-emscripten.md) (Web browsers)
 - [FreeBSD](README-bsd.md)
 - [Haiku OS](README-haiku.md)
 - [iOS](README-ios.md)
 - [Linux](README-linux.md)
- [macOS](README-macos.md)
+- [macOS](README-macos.md) (10.14 and later)
 - [NetBSD](README-bsd.md)
- [Nintendo Switch](README-switch.md)
- [Nintendo 3DS](README-n3ds.md)
+- [Nintendo Switch](README-switch.md) (Separate NDA-only fork)
+- [Nintendo 3DS](README-n3ds.md) (Homebrew)
+- [Nokia N-Gage](README-ngage.md)
 - [OpenBSD](README-bsd.md)
- [PlayStation 2](README-ps2.md)
- [PlayStation 4](README-ps4.md)
- [PlayStation 5](README-ps5.md)
- [PlayStation Portable](README-psp.md)
- [PlayStation Vita](README-vita.md)
+- [PlayStation 2](README-ps2.md) (Homebrew)
+- [PlayStation 4](README-ps4.md) (Separate NDA-only fork)
+- [PlayStation 5](README-ps5.md) (Separate NDA-only fork)
+- [PlayStation Portable](README-psp.md) (Homebrew)
+- [PlayStation Vita](README-vita.md) (Homebrew)
 - [RISC OS](README-riscos.md)
 - [SteamOS](README-steamos.md)
 - [tvOS](README-ios.md)
- [Windows](README-windows.md)
+- [visionOS](README-ios.md)
+- [Windows](README-windows.md) (XP and later)
 - [Windows GDK](README-gdk.md)
 - [Xbox](README-gdk.md)

+Note that the SDL maintainers do not test on all these platforms; if a less-common system breaks, [please let us know](https://github.com/libsdl-org/SDL/issues/new) and send patches if you can.
+
+If you'd like to port SDL to a new platform, feel free to get in touch! [A guide to porting SDL2](https://discourse.libsdl.org/t/port-sdl-2-0-to-bios/25453/2) was written a while ago, and most of it still applies to SDL3.
+
 ## Unsupported Platforms

 If your favorite system is listed below, we aren't working on it. However, if you send reasonable patches and are willing to support the port in the long term, we are happy to take a look!

 All of these still work with [SDL2](/SDL2), which is an incompatible API, but an option if you need to support these platforms still.

+- QNX
 - Google Stadia
 - NaCL
- Nokia N-Gage
 - OS/2
- QNX
 - WinPhone
 - WinRT/UWP
+
+## General notes for Unix platforms
+
+Some aspects of SDL functionality are common to all Unix-based platforms.
+
+### <a name=setuid></a>Privileged processes (setuid, setgid, setcap)
+
+SDL is not designed to be used in programs with elevated privileges,
+such as setuid (`chmod u+s`) or setgid (`chmod g+s`) executables,
+or executables with file-based capabilities
+(`setcap cap_sys_nice+ep` or similar).
+It does not make any attempt to avoid trusting environment variables
+or other aspects of the inherited execution environment.
+Programs running with elevated privileges in an attacker-controlled
+execution environment should not call SDL functions.
@@ -11,11 +11,20 @@ Credit to
 ## Building
 To build SDL library for the PS2, make sure you have the latest PS2Dev status and run:
 ```bash
-cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=$PS2DEV/ps2sdk/ps2dev.cmake
+export PS2DEV=/usr/local/ps2dev # or wherever your ps2dev installation is
+export PS2SDK=$PS2DEV/ps2sdk
+export PATH=$PATH:$PS2DEV/bin:$PS2DEV/ee/bin:$PS2DEV/iop/bin:$PS2DEV/dvp/bin:$PS2SDK/bin
+cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=$PS2DEV/share/ps2dev.cmake
 cmake --build build
 cmake --install build
 ```

+## Hints
+- `SDL_HINT_PS2_GS_WIDTH`: Width of the framebuffer. Defaults to 640.
+- `SDL_HINT_PS2_GS_HEIGHT`: Height of the framebuffer. Defaults to 448.
+- `SDL_HINT_PS2_GS_PROGRESSIVE`: Whether to use progressive, instead of interlaced. Defaults to 0.
+- `SDL_HINT_PS2_GS_MODE`: Regional standard of the signal. "NTSC" (60hz), "PAL" (50hz) or "" (the console's region, default).
+
 ## Notes
 If you trying to debug a SDL app through [ps2client](https://github.com/ps2dev/ps2client) you need to avoid the IOP reset, otherwise you will lose the connection with your computer.
 So to avoid the reset of the IOP CPU, you need to call to the macro `SDL_PS2_SKIP_IOP_RESET();`.
@@ -1,13 +1,13 @@
 PSP
 ======
 SDL port for the Sony PSP contributed by:
- Captian Lex
+- Captain Lex
 - Francisco Javier Trujillo Mata
 - Wouter Wijsman


 Credit to
-   Marcus R.Brown,Jim Paris,Matthew H for the original SDL 1.2 for PSP
+   Marcus R.Brown, Jim Paris, Matthew H for the original SDL 1.2 for PSP
   Geecko for his PSP GU lib "Glib2d"

 ## Building
@@ -1,3 +1,3 @@
 # Nintendo Switch

-SDL3 runs on the Nintendo Switch! There are commercial games shipping with this port. This port is kept in a separate repository, but is available for free, under the zlib license, to anyone that is under NDA for Switch development with Nintendo. Please contact Ryan (icculus at icculus dot org) for details.
+SDL3 runs on the Nintendo Switch! Both Switch and Switch 2 are supported. There are commercial games shipping with this port. This port is kept in a separate repository, but is available for free, under the zlib license, to anyone that is under the appropriate NDAs with Nintendo. Please contact Ryan (icculus at icculus dot org) for details.
@@ -47,8 +47,15 @@ encounter limitations or behavior that is different from other windowing systems

 ### Warping the mouse cursor to or from a point outside the window doesn't work

- The cursor can be warped only within the window with mouse focus, provided that the `zwp_pointer_confinement_v1`
-  protocol is supported by the compositor.
+- Warping the cursor on Wayland requires that either the `wp_pointer_warp_v1` or `zwp_pointer_confinement_v1` protocol
+  is supported by the compositor. Compositors typically restrict pointer warps to be within the window that currently
+  has mouse focus.
+
+### Minimize/Restored window events are not sent, and the ```SDL_WINDOW_MINIMIZED``` flag is not set.
+
+- Wayland windows do not currently report the minimized state, aside from when it is activated programmatically via
+  ```SDL_MinimizeWindow()```. Minimizing a window from the window controls or a desktop shortcut will not send a
+  minimized event or flag the window as being minimized.

 ### The application icon can't be set via ```SDL_SetWindowIcon()```

@@ -59,6 +66,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.
@@ -1,5 +1,5 @@
 /*
-  Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2026 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
@@ -15,6 +15,8 @@

 * Create a GitHub release and attach the archives you just generated.

+* If this is a feature release, also tag the sdlwiki with the same tag.
+
 ## New feature release

 * Update `WhatsNew.txt`