iris/kaizen
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Merge commit '28d94e8b86cef2f86bff054565179fc2027db8cd' into dev

Browse Source
This commit is contained in:
SimoZ64
2025-04-15 09:23:03 +02:00
parent 541eb8b772 28d94e8b86
commit f1d58ffe88
751 changed files with 60484 additions and 32976 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
external/SDL/docs/INTRO-androidstudio.md vendored Normal file
View File

@@ -0,0 +1,17 @@
# Introduction to SDL with Android Studio
We'll start by creating a simple project to build and run [hello.c](hello.c)
- Use our handy script to create a template project:
```sh
./build-scripts/create-android-project.py org.libsdl.hello docs/hello.c
```
- Run Android Studio and open the newly created build/org.libsdl.hello directory
- Build and run!
A more complete example is available at:
https://github.com/Ravbug/sdl3-sample
Additional information and troubleshooting is available in [README-android.md](README-android.md)

57
external/SDL/docs/INTRO-cmake.md vendored Normal file
View File

@@ -0,0 +1,57 @@
# Introduction to SDL with CMake
The easiest way to use SDL is to include it as a subproject in your project.
We'll start by creating a simple project to build and run [hello.c](hello.c)
# Get a copy of the SDL source:
```sh
git clone https://github.com/libsdl-org/SDL.git vendored/SDL
```
# Create the file CMakeLists.txt
```cmake
cmake_minimum_required(VERSION 3.16)
project(hello)
# set the output directory for built objects.
# This makes sure that the dynamic library goes into the build directory automatically.
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$<CONFIGURATION>")
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)
# Create your game executable target as usual
add_executable(hello WIN32 hello.c)
# Link to the actual SDL3 library.
target_link_libraries(hello PRIVATE SDL3::SDL3)
```
# Configure and Build:
```sh
cmake -S . -B build
cmake --build build
```
# Run:
The executable should be in the `build` directory:
```sh
cd build
./hello
```
If there wasn't an executable there despite the above Build section running successfully, it's likely because you're following this guide using the Visual Studio toolchain, it should instead be in the `build/Debug` directory:
```sh
cd build/Debug
./hello
```
A more complete example is available at:
https://github.com/Ravbug/sdl3-sample
Additional information and troubleshooting is available in [README-cmake.md](README-cmake.md)

50
external/SDL/docs/INTRO-emscripten.md vendored Normal file
View File

@@ -0,0 +1,50 @@
# Introduction to SDL with Emscripten
The easiest way to use SDL is to include it as a subproject in your project.
We'll start by creating a simple project to build and run [hello.c](hello.c)
First, you should have the Emscripten SDK installed from:
https://emscripten.org/docs/getting_started/downloads.html
Create the file CMakeLists.txt
```cmake
cmake_minimum_required(VERSION 3.16)
project(hello)
# set the output directory for built objects.
# This makes sure that the dynamic library goes into the build directory automatically.
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$<CONFIGURATION>")
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.
if(EMSCRIPTEN)
set(CMAKE_EXECUTABLE_SUFFIX ".html" CACHE INTERNAL "")
endif()
# Create your game executable target as usual
add_executable(hello WIN32 hello.c)
# Link to the actual SDL3 library.
target_link_libraries(hello PRIVATE SDL3::SDL3)
```
Build:
```sh
emcmake cmake -S . -B build
cd build
emmake make
```
You can now run your app by pointing a webserver at your build directory and connecting a web browser to it, opening hello.html
A more complete example is available at:
https://github.com/Ravbug/sdl3-sample
Additional information and troubleshooting is available in [README-emscripten.md](README-emscripten.md)

95
external/SDL/docs/INTRO-mingw.md vendored Normal file
View File

@@ -0,0 +1,95 @@
# 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.
Otherwise you'll want to follow the "Other Distributions" section below.
We'll start by creating a simple project to build and run [hello.c](hello.c).
# MSYS2
Open the `MSYS2 UCRT64` prompt and then ensure you've installed the following packages. This will get you working toolchain, CMake, Ninja, and of course SDL3.
```sh
pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-ninja mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-sdl3
```
## Create the file CMakeLists.txt
```cmake
cmake_minimum_required(VERSION 3.26)
project(hello C CXX)
find_package(SDL3 REQUIRED)
add_executable(hello)
target_sources(hello
PRIVATE
hello.c
)
target_link_libraries(hello SDL3::SDL3)
```
## Configure and Build:
```sh
cmake -S . -B build
cmake --build build
```
## Run:
The executable is in the `build` directory:
```sh
cd build
./hello
```
# Other Distributions
Things can get quite complicated with other distributions of MinGW. If you can't follow [the cmake intro](INTRO-cmake.md), perhaps due to issues getting cmake to understand your toolchain, this section should work.
## Acquire SDL
Download the `SDL3-devel-<version>-mingw.zip` asset from [the latest release.](https://github.com/libsdl-org/SDL/releases/latest) Then extract it inside your project folder such that the output of `ls SDL3-<version>` looks like `INSTALL.md LICENSE.txt Makefile README.md cmake i686-w64-mingw32 x86_64-w64-mingw32`.
## Know your Target Architecture
It is not uncommon for folks to not realize their distribution is targeting 32bit Windows despite things like the name of the toolchain, or the fact that they're running on a 64bit system. We'll ensure we know up front what we need:
Create a file named `arch.c` with the following contents:
```c
#include <stddef.h>
#include <stdio.h>
int main() {
#if defined(__x86_64__) || defined(_M_X64) || defined(i386) || defined(__i386__) || defined(__i386) || defined(_M_IX86)
size_t ptr_size = sizeof(int*);
if (4 == ptr_size) puts("i686-w64-mingw32");
else if (8 == ptr_size) puts("x86_64-w64-mingw32");
else puts("Unknown Architecture");
#else
puts("Unknown Architecture");
#endif
return 0;
}
```
Then run
```sh
gcc arch.c
./a.exe
```
This should print out which library directory we'll need to use when compiling, keep this value in mind, you'll need to use it when compiling in the next section as `<arch>`. If you get "Unknown Architecture" please [report a bug](https://github.com/libsdl-org/SDL/issues).
## Build and Run
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
cp SDL3-<version>/<arch>/bin/SDL3.dll SDL3.dll
./hello.exe
```

16
external/SDL/docs/INTRO-visualstudio.md vendored Normal file
View File

@@ -0,0 +1,16 @@
# Introduction to SDL with Visual Studio
The easiest way to use SDL is to include it as a subproject in your project.
We'll start by creating a simple project to build and run [hello.c](hello.c)
- Get a copy of the SDL source, you can clone the repo, or download the "Source Code" asset from [the latest release.](https://github.com/libsdl-org/SDL/releases/latest)
- If you've downloaded a release, make sure to extract the contents somewhere you can find it.
- Create a new project in Visual Studio, using the C++ Empty Project template
- Add hello.c to the Source Files
- Right click the solution, select add an existing project, navigate to `VisualC/SDL` from within the source you cloned or downloaded above and add SDL.vcxproj
- Select your main project and go to Project -> Add -> Reference and select SDL3
- Select your main project and go to Project -> Properties, set the filter at the top to "All Configurations" and "All Platforms", select C/C++ -> General and add the SDL include directory to "Additional Include Directories"
- Build and run!

16
external/SDL/docs/INTRO-xcode.md vendored Normal file
View File

@@ -0,0 +1,16 @@
# Introduction to SDL with Xcode
The easiest way to use SDL is to include it as a subproject in your project.
We'll start by creating a simple project to build and run [hello.c](hello.c)
- Create a new project in Xcode, using the App template and selecting Objective C as the language
- Remove the .h and .m files that were automatically added to the project
- Remove the main storyboard that was automatically added to the project
- On iOS projects, select the project, select the main target, select the Info tab, look for "Custom iOS Target Properties", and remove "Main storyboard base file name" and "Application Scene Manifest"
- Right click the project and select "Add Files to [project]", navigate to the SDL docs directory and add the file hello.c
- Right click the project and select "Add Files to [project]", navigate to the SDL Xcode/SDL directory and add SDL.xcodeproj
- Select the project, select the main target, select the General tab, look for "Frameworks, Libaries, and Embedded Content", and add SDL3.framework
- Build and run!

58
external/SDL/docs/README-android.md vendored
View File

@@ -37,7 +37,7 @@ dispatches to native functions implemented in the SDL library:
src/core/android/SDL_android.c
Building an app
Building a simple app
================================================================================
For simple projects you can use the script located at build-scripts/create-android-project.py
@@ -67,40 +67,38 @@ Finally, a word of caution: re running create-android-project.py wipes any chang
done in the build directory for the app!
Building a more complex app
================================================================================
For more complex projects, follow these instructions:
1. Get the source code for SDL and copy the 'android-project' directory located at SDL/android-project to a suitable location. Also make sure to rename it to your project name (In these examples: YOURPROJECT).
1. Get the source code for SDL and copy the 'android-project' directory located at SDL/android-project to a suitable location in your project.
(The 'android-project' directory can basically be seen as a sort of starting point for the android-port of your project. It contains the glue code between the Android Java 'frontend' and the SDL code 'backend'. It also contains some standard behaviour, like how events should be handled, which you will be able to change.)
The 'android-project' directory can basically be seen as a sort of starting point for the android-port of your project. It contains the glue code between the Android Java 'frontend' and the SDL code 'backend'. It also contains some standard behaviour, like how events should be handled, which you will be able to change.
2. Move or [symlink](https://en.wikipedia.org/wiki/Symbolic_link) the SDL directory into the "YOURPROJECT/app/jni" directory
2. If you are _not_ already building SDL as a part of your project (e.g. via CMake add_subdirectory() or FetchContent) move or [symlink](https://en.wikipedia.org/wiki/Symbolic_link) the SDL directory into the 'android-project/app/jni' directory. Alternatively you can [use the SDL3 Android Archive (.aar)](#using-the-sdl3-android-archive-aar), see bellow for more details.
(This is needed as the source of SDL has to be compiled by the Android compiler)
This is needed as SDL has to be compiled by the Android compiler.
3. Edit "YOURPROJECT/app/jni/src/Android.mk" to include your source files.
3. Edit 'android-project/app/build.gradle' to include any assets that your app needs by adding 'assets.srcDirs' in 'sourceSets.main'.
(They should be separated by spaces after the "LOCAL_SRC_FILES := " declaration)
For example: `assets.srcDirs = ['../../assets', '../../shaders']`
4a. If you want to use Android Studio, simply open your 'YOURPROJECT' directory and start building.
If using CMake:
4b. If you want to build manually, run './gradlew installDebug' in the project directory. This compiles the .java, creates an .apk with the native code embedded, and installs it on any connected Android device
4. Edit 'android-project/app/build.gradle' to set 'buildWithCMake' to true and set 'externalNativeBuild' cmake path to your top level CMakeLists.txt.
For example: `path '../../CMakeLists.txt'`
If you already have a project that uses CMake, the instructions change somewhat:
5. Change the target containing your main function to be built as a shared library called "main" when compiling for Android. (e.g. add_executable(MyGame main.c) should become add_library(main SHARED main.c) on Android)
1. Do points 1 and 2 from the instruction above.
2. Edit "YOURPROJECT/app/build.gradle" to comment out or remove sections containing ndk-build
and uncomment the cmake sections. Add arguments to the CMake invocation as needed.
3. Edit "YOURPROJECT/app/jni/CMakeLists.txt" to include your project (it defaults to
adding the "src" subdirectory). Note that you'll have SDL3 and SDL3-static
as targets in your project, so you should have "target_link_libraries(yourgame SDL3)"
in your CMakeLists.txt file. Also be aware that you should use add_library() instead of
add_executable() for the target containing your "main" function.
If using Android Makefiles:
If you wish to use Android Studio, you can skip the last step.
4. Edit 'android-project/app/jni/src/Android.mk' to include your source files. They should be separated by spaces after the 'LOCAL_SRC_FILES := ' declaration.
4. Run './gradlew installDebug' or './gradlew installRelease' in the project directory. It will build and install your .apk on any
connected Android device
To build your app, run `./gradlew installDebug` or `./gradlew installRelease` in the project directory. It will build and install your .apk on any connected Android device. If you want to use Android Studio, simply open your 'android-project' directory and start building.
Additionally the [SDL_helloworld](https://github.com/libsdl-org/SDL_helloworld) project contains a small example program with a functional Android port that you can use as a reference.
Here's an explanation of the files in the Android project, so you can customize them:
@@ -151,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:
```
@@ -244,7 +242,7 @@ not give you any processing time after the events are delivered.
e.g.
int HandleAppEvents(void *userdata, SDL_Event *event)
bool HandleAppEvents(void *userdata, SDL_Event *event)
{
switch (event->type)
{
@@ -252,12 +250,12 @@ e.g.
/* Terminate the app.
Shut everything down before returning from this function.
*/
return 0;
return false;
case SDL_EVENT_LOW_MEMORY:
/* You will get this when your app is paused and iOS wants more memory.
Release as much memory as possible.
*/
return 0;
return false;
case SDL_EVENT_WILL_ENTER_BACKGROUND:
/* Prepare your app to go into the background. Stop loops, etc.
This gets called when the user hits the home button, or gets a call.
@@ -266,15 +264,15 @@ e.g.
in addition, you should set the render target to NULL, if you're using
it, e.g. call SDL_SetRenderTarget(renderer, NULL).
*/
return 0;
return false;
case SDL_EVENT_DID_ENTER_BACKGROUND:
/* Your app is NOT active at this point. */
return 0;
return false;
case SDL_EVENT_WILL_ENTER_FOREGROUND:
/* This call happens when your app is coming back to the foreground.
Restore all your state here.
*/
return 0;
return false;
case SDL_EVENT_DID_ENTER_FOREGROUND:
/* Restart your loops here.
Your app is interactive and getting CPU again.
@@ -285,10 +283,10 @@ e.g.
event SDL_EVENT_RENDER_DEVICE_RESET and recreate your OpenGL context and
restore your textures when you get it, or quit the app.
*/
return 0;
return false;
default:
/* No special processing, add it to the event queue */
return 1;
return true;
}
}

6
external/SDL/docs/README-bsd.md vendored Normal file
View File

@@ -0,0 +1,6 @@
# FreeBSD / OpenBSD / NetBSD
SDL is fully supported on BSD platforms, and is built using [CMake](README-cmake.md).
If you want to run on the console, you can take a look at [KMSDRM support on BSD](README-kmsbsd.md)

182
external/SDL/docs/README-cmake.md vendored
View File

@@ -2,60 +2,72 @@
[www.cmake.org](https://www.cmake.org/)
The CMake build system is supported on the following platforms:
The CMake build system is supported with the following environments:
* FreeBSD
* Linux
* Microsoft Visual C
* MinGW and Msys
* macOS, iOS, tvOS, and visionOS with support for XCode
* Android
* Emscripten
* NetBSD
* FreeBSD
* Haiku
* Linux
* macOS, iOS, tvOS, and visionOS with support for XCode
* Microsoft Visual Studio
* MinGW and Msys
* NetBSD
* Nintendo 3DS
* PlayStation 2
* PlayStation Portable
* PlayStation Vita
* QNX 7.x/8.x
* RiscOS
* RISC OS
## Building SDL
## Building SDL on Windows
Assuming the source tree of SDL is located at `~/sdl`,
this will configure and build SDL in the `~/build` directory:
Assuming you're in the SDL source directory, building and installing to C:/SDL can be done with:
```sh
cmake -S ~/sdl -B ~/build
cmake --build ~/build
cmake -S . -B build
cmake --build build --config RelWithDebInfo
cmake --install build --config RelWithDebInfo --prefix C:/SDL
```
Installation can be done using:
## Building SDL on UNIX
SDL will build with very few dependencies, but for full functionality you should install the packages detailed in [README-linux.md](README-linux.md).
Assuming you're in the SDL source directory, building and installing to /usr/local can be done with:
```sh
cmake --install ~/build --prefix /usr/local # '--install' requires CMake 3.15, or newer
cmake -S . -B build
cmake --build build
sudo cmake --install build --prefix /usr/local
```
This will install SDL to /usr/local.
## Building SDL on macOS
### Building SDL tests
Assuming you're in the SDL source directory, building and installing to ~/SDL can be done with:
```sh
cmake -S . -B build -DSDL_FRAMEWORK=ON -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
cmake --build build
cmake --install build --prefix ~/SDL
```
## Building SDL tests
You can build the SDL test programs by adding `-DSDL_TESTS=ON` to the first cmake command above:
```sh
cmake -S ~/sdl -B ~/build -DSDL_TEST_LIBRARY=ON -DSDL_TESTS=ON
cmake -S . -B build -DSDL_TESTS=ON
```
and then building normally. In this example, the test programs will be built and can be run from `~/build/tests/`.
and then building normally. The test programs will be built and can be run from `build/test/`.
### Building SDL examples
## Building SDL examples
You can build the SDL example programs by adding `-DSDL_EXAMPLES=ON` to the first cmake command above:
```sh
cmake -S ~/sdl -B ~/build -DSDL_EXAMPLES=ON
cmake -S . -B build -DSDL_EXAMPLES=ON
```
and then building normally. In this example, the example programs will be built and can be run from `~/build/examples/`.
and then building normally. The example programs will be built and can be run from `build/examples/`.
## Including SDL in your project
SDL can be included in your project in 2 major ways:
- using a system SDL library, provided by your (*nix) distribution or a package manager
- using a system SDL library, provided by your (UNIX) distribution or a package manager
- using a vendored SDL library: this is SDL copied or symlinked in a subfolder.
The following CMake script supports both, depending on the value of `MYGAME_VENDORED`.
@@ -131,6 +143,13 @@ Exceptions exist:
- some platforms don't support dynamic libraries, so only `-DSDL_STATIC=ON` makes sense.
- a static Apple framework is not supported
### Man pages
Configuring with `-DSDL_INSTALL_DOCS=TRUE` installs man pages.
We recommend package managers of unix distributions to install SDL3's man pages.
This adds an extra build-time dependency on Perl.
### Pass custom compile options to the compiler
- Use [`CMAKE_<LANG>_FLAGS`](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html) to pass extra
@@ -174,7 +193,7 @@ Only shared frameworks are supported, no static ones.
#### Platforms
Use `-DCMAKE_PLATFORM_NAME=<value>` to configure the platform. CMake can target only one platform at a time.
Use `-DCMAKE_SYSTEM_NAME=<value>` to configure the platform. CMake can target only one platform at a time.
| Apple platform | `CMAKE_SYSTEM_NAME` value |
|-----------------|---------------------------|
@@ -310,7 +329,7 @@ Configure your project with `-DSDL_LIBC=ON` to make use of sanitizers.
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.
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.
@@ -343,114 +362,3 @@ However, by default CMake builds static libraries as non-relocatable.
Configuring SDL with `-DCMAKE_POSITION_INDEPENDENT_CODE=ON` will result in a static `libSDL3.a` library
which you can link against to create a shared library.
## Help, it doesn't work!
Below, a SDL3 CMake project can be found that builds 99.9% of time (assuming you have internet connectivity).
When you have a problem with building or using SDL, please modify it until it reproduces your issue.
```cmake
cmake_minimum_required(VERSION 3.16)
project(sdl_issue)
# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
# !!!!!! !!!!!!
# !!!!!! This CMake script is not using "CMake best practices". !!!!!!
# !!!!!! Don't use it in your project. !!!!!!
# !!!!!! !!!!!!
# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
# 1. Try system SDL3 package first
find_package(SDL3 QUIET)
if(SDL3_FOUND)
message(STATUS "Using SDL3 via find_package")
endif()
# 2. Try using a vendored SDL library
if(NOT SDL3_FOUND AND EXISTS "${CMAKE_CURRENT_LIST_DIR}/SDL/CMakeLists.txt")
add_subdirectory(SDL EXCLUDE_FROM_ALL)
message(STATUS "Using SDL3 via add_subdirectory")
set(SDL3_FOUND TRUE)
endif()
# 3. Download SDL, and use that.
if(NOT SDL3_FOUND)
include(FetchContent)
set(SDL_SHARED TRUE CACHE BOOL "Build a SDL shared library (if available)")
set(SDL_STATIC TRUE CACHE BOOL "Build a SDL static library (if available)")
FetchContent_Declare(
SDL
GIT_REPOSITORY https://github.com/libsdl-org/SDL.git
GIT_TAG main # Replace this with a particular git tag or git hash
GIT_SHALLOW TRUE
GIT_PROGRESS TRUE
)
message(STATUS "Using SDL3 via FetchContent")
FetchContent_MakeAvailable(SDL)
set_property(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/_deps/sdl-src" PROPERTY EXCLUDE_FROM_ALL TRUE)
endif()
file(WRITE main.c [===========================================[
/**
* Modify this source such that it reproduces your problem.
*/
/* START of source modifications */
#include <SDL3/SDL.h>
/*
* SDL3/SDL_main.h is explicitly not included such that a terminal window would appear on Windows.
*/
int main(int argc, char *argv[]) {
(void)argc;
(void)argv;
if (!SDL_Init(SDL_INIT_VIDEO)) {
SDL_Log("SDL_Init failed (%s)", SDL_GetError());
return 1;
}
SDL_Window *window = NULL;
SDL_Renderer *renderer = NULL;
if (!SDL_CreateWindowAndRenderer("SDL issue", 640, 480, 0, &window, &renderer)) {
SDL_Log("SDL_CreateWindowAndRenderer failed (%s)", SDL_GetError());
SDL_Quit();
return 1;
}
while (1) {
int finished = 0;
SDL_Event event;
while (SDL_PollEvent(&event)) {
if (event.type == SDL_EVENT_QUIT) {
finished = 1;
break;
}
}
if (finished) {
break;
}
SDL_SetRenderDrawColor(renderer, 80, 80, 80, SDL_ALPHA_OPAQUE);
SDL_RenderClear(renderer);
SDL_RenderPresent(renderer);
}
SDL_DestroyRenderer(renderer);
SDL_DestroyWindow(window);
SDL_Quit();
return 0;
}
/* END of source modifications */
]===========================================])
add_executable(sdl_issue main.c)
target_link_libraries(sdl_issue PRIVATE SDL3::SDL3)
# target_link_libraries(sdl_issue PRIVATE SDL3::SDL3-shared)
# target_link_libraries(sdl_issue PRIVATE SDL3::SDL3-static)
```

2
external/SDL/docs/README-contributing.md vendored
View File

@@ -57,7 +57,7 @@ If you had already forked the repository, you may update it from the web page us
Code formatting is done using a custom `.clang-format` file, you can learn more about how to run it [here](https://clang.llvm.org/docs/ClangFormat.html).
Some legacy code may not be formatted, as such avoid formatting the whole file at once and only format around your changes.
Some legacy code may not be formatted, so please avoid formatting the whole file at once and only format around your changes.
For your commit message to be properly displayed on GitHub, it should contain:

22
external/SDL/docs/README-documentation-rules.md vendored
View File

@@ -156,6 +156,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.
@@ -304,6 +321,11 @@ 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_.
## It's okay to repeat yourself.

6
external/SDL/docs/README-emscripten.md vendored
View File

@@ -239,13 +239,13 @@ 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_THREADS=ON ..
# you can also do `emcmake cmake -G Ninja ..` and then use `ninja` instead of this command.
emmake make -j4
```
To build the tests, add `-DSDL_TESTS=On` to the `emcmake cmake` command line.
To build the examples, add `-DSDL_EXAMPLES=On` to the `emcmake cmake` command line.
To build the tests, add `-DSDL_TESTS=ON` to the `emcmake cmake` command line.
To build the examples, add `-DSDL_EXAMPLES=ON` to the `emcmake cmake` command line.
## Building your app

16
external/SDL/docs/README-git.md vendored
View File

@@ -1,16 +0,0 @@
git
=========
The latest development version of SDL is available via git.
Git allows you to get up-to-the-minute fixes and enhancements;
as a developer works on a source tree, you can use "git" to mirror that
source tree instead of waiting for an official release. Please look
at the Git website ( https://git-scm.com/ ) for more
information on using git, where you can also download software for
macOS, Windows, and Unix systems.
git clone https://github.com/libsdl-org/SDL
There is a web interface to the Git repository at:
http://github.com/libsdl-org/SDL/

4
external/SDL/docs/README-haiku.md vendored Normal file
View File

@@ -0,0 +1,4 @@
# Haiku OS
SDL is fully supported on Haiku OS, and is built using [CMake](README-cmake.md).

56
external/SDL/docs/README-highdpi.md vendored
View File

@@ -1,32 +1,6 @@
SDL 3.0 has new support for high DPI displays. Interfaces provided by SDL uses the platform's native coordinates unless otherwise specified.
To reconcile platform differences in their approach to high-density scaling, SDL provides the following interfaces:
- `SDL_GetWindowSize()` retrieves the window dimensions in native coordinates.
- `SDL_GetWindowSizeInPixels()` retrieves the window dimensions in pixels-addressable.
- `SDL_GetDisplayContentScale()` retrieves the suggested amplification factor when drawing in native coordinates.
- `SDL_GetWindowDisplayScale()` retrieves the suggested amplification factor when drawing in pixels-addressable.
- `SDL_GetWindowPixelDensity()` retrieves how many addressable pixels correspond to one unit of native coordinates.
- `SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED` is emitted when the value retrievable from `SDL_GetWindowSizeInPixels()` changes.
- `SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED` is emitted when the value retrievable from `SDL_GetWindowDisplayScale()` changes.
- Windows created with `SDL_WINDOW_HIGH_PIXEL_DENSITY` will ask the platform to display addressable pixels at their natural scale.
## Numeric example
Given a fullscreen window spanning a 3840x2160 monitor set to 2x display or 200% scaling, the following tabulates the effect of creating a window with or without `SDL_WINDOW_HIGH_PIXEL_DENSITY` on MacOS and Win32:
| Value | MacOS (Default) | MacOS (HD) | Win32 (Default & HD) |
|--------------------------------|-----------------|------------|----------------------|
| `SDL_GetWindowSize()` | 1920x1080 | 1920x1080 | 3840x2160 |
| `SDL_GetWindowSizeInPixels()` | 1920x1080 | 3840x2160 | 3840x2160 |
| `SDL_GetDisplayContentScale()` | 1.0 | 1.0 | 2.0 |
| `SDL_GetWindowDisplayScale()` | 1.0 | 2.0 | 2.0 |
| `SDL_GetWindowPixelDensity()` | 1.0 | 2.0 | 1.0 |
Observe the philosophical difference between the approaches taken by MacOS and Win32:
- Win32 coordinate system always deals in physical device pixels, high DPI support is achieved by providing an advisory hint for the developer to enlarge drawn objects. Ignoring the advisory scale factor results in graphics appearing tiny.
- MacOS coordinate system always deals in physical content sizes, high DPI support is achieved by providing an optional flag for the developer to request finer granularity. Omitting the granularity request results in graphics appearing coarse.
## Explanation
Displays now have a content display scale, which is the expected scale for content based on the DPI settings of the display. For example, a 4K display might have a 2.0 (200%) display scale, which means that the user expects UI elements to be twice as big on this display, to aid in readability. You can query the display content scale using `SDL_GetDisplayContentScale()`, and when this changes you get an `SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED` event.
@@ -34,3 +8,33 @@ Displays now have a content display scale, which is the expected scale for conte
The window size is now distinct from the window pixel size, and the ratio between the two is the window pixel density. If the window is created with the `SDL_WINDOW_HIGH_PIXEL_DENSITY` flag, SDL will try to match the native pixel density for the display, otherwise it will try to have the pixel size match the window size. You can query the window pixel density using `SDL_GetWindowPixelDensity()`. You can query the window pixel size using `SDL_GetWindowSizeInPixels()`, and when this changes you get an `SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED` event. You are guaranteed to get a `SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED` event when a window is created and resized, and you can use this event to create and resize your graphics context for the window.
The window has a display scale, which is the scale from the pixel resolution to the desired content size, e.g. the combination of the pixel density and the content scale. For example, a 3840x2160 window displayed at 200% on Windows, and a 1920x1080 window with the high density flag on a 2x display on macOS will both have a pixel size of 3840x2160 and a display scale of 2.0. You can query the window display scale using `SDL_GetWindowDisplayScale()`, and when this changes you get an `SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED` event.
## Numeric example
Given a window spanning a 3840x2160 monitor set to 2x display or 200% scaling, the following tabulates the effect of creating a window with or without `SDL_WINDOW_HIGH_PIXEL_DENSITY` on macOS and Windows:
| Value | macOS (Default) | macOS (HD) | Windows (Default & HD) |
|--------------------------------|-----------------|------------|------------------------|
| `SDL_GetWindowSize()` | 1920x1080 | 1920x1080 | 3840x2160 |
| `SDL_GetWindowSizeInPixels()` | 1920x1080 | 3840x2160 | 3840x2160 |
| `SDL_GetDisplayContentScale()` | 1.0 | 1.0 | 2.0 |
| `SDL_GetWindowDisplayScale()` | 1.0 | 2.0 | 2.0 |
| `SDL_GetWindowPixelDensity()` | 1.0 | 2.0 | 1.0 |
Observe the difference between the approaches taken by macOS and Windows:
- The Windows and Android coordinate system always deals in physical device pixels, high DPI support is achieved by providing a content scale that tells the developer to draw objects larger. Ignoring this scale factor results in graphics appearing tiny.
- The macOS and iOS coordinate system always deals in window coordinates, high DPI support is achieved by providing an optional flag for the developer to request more pixels. Omitting this flag results in graphics having low detail.
- On Linux, X11 uses a similar approach to Windows and Wayland uses a similar approach to macOS.
## Solution
Proper high DPI support takes into account both the content scale and the pixel density.
First, you'd create your window with the `SDL_WINDOW_HIGH_PIXEL_DENSITY` flag, assuming you want the highest detail possible. Then you'd get the window display scale to see how much your UI elements should be enlarged to be readable.
If you're using the SDL 2D renderer, SDL provides the function `SDL_ConvertEventToRenderCoordinates()` to convert mouse coordinates between window coordinates and rendering coordinates, and the more general functions `SDL_RenderCoordinatesFromWindow()` and `SDL_RenderCoordinatesToWindow()` to do other conversion between them.
If you're not using the 2D renderer, you can implement this yourself using `SDL_GetWindowPixelDensity()` as scale factor to convert from window coordinates to pixels.
Finally you'll want to test on both Windows and macOS if possible to make sure your high DPI support works in all environments.

25
external/SDL/docs/README-ios.md vendored
View File

@@ -1,10 +1,10 @@
iOS
======
Building the Simple DirectMedia Layer for iOS 9.0+
Building the Simple DirectMedia Layer for iOS 11.0+
==============================================================================
Requirements: macOS 10.9 or later and the iOS 9.0 or newer SDK.
Please note that building SDL requires at least Xcode 12.2 and the iOS 14.2 SDK.
Instructions:
@@ -65,7 +65,7 @@ not give you any processing time after the events are delivered.
e.g.
int HandleAppEvents(void *userdata, SDL_Event *event)
bool HandleAppEvents(void *userdata, SDL_Event *event)
{
switch (event->type)
{
@@ -73,37 +73,37 @@ e.g.
/* Terminate the app.
Shut everything down before returning from this function.
*/
return 0;
return false;
case SDL_EVENT_LOW_MEMORY:
/* You will get this when your app is paused and iOS wants more memory.
Release as much memory as possible.
*/
return 0;
return false;
case SDL_EVENT_WILL_ENTER_BACKGROUND:
/* Prepare your app to go into the background. Stop loops, etc.
This gets called when the user hits the home button, or gets a call.
*/
return 0;
return false;
case SDL_EVENT_DID_ENTER_BACKGROUND:
/* This will get called if the user accepted whatever sent your app to the background.
If the user got a phone call and canceled it, you'll instead get an SDL_EVENT_DID_ENTER_FOREGROUND event and restart your loops.
When you get this, you have 5 seconds to save all your state or the app will be terminated.
Your app is NOT active at this point.
*/
return 0;
return false;
case SDL_EVENT_WILL_ENTER_FOREGROUND:
/* This call happens when your app is coming back to the foreground.
Restore all your state here.
*/
return 0;
return false;
case SDL_EVENT_DID_ENTER_FOREGROUND:
/* Restart your loops here.
Your app is interactive and getting CPU again.
*/
return 0;
return false;
default:
/* No special processing, add it to the event queue */
return 1;
return true;
}
}
@@ -185,9 +185,6 @@ Windows:
Textures:
The optimal texture formats on iOS are SDL_PIXELFORMAT_ABGR8888, SDL_PIXELFORMAT_ABGR8888, SDL_PIXELFORMAT_XBGR8888, and SDL_PIXELFORMAT_RGB24 pixel formats.
Loading Shared Objects:
This is disabled by default since it seems to break the terms of the iOS SDK agreement for iOS versions prior to iOS 8. It can be re-enabled in SDL_config_ios.h.
Notes -- CoreBluetooth.framework
==============================================================================
@@ -249,7 +246,7 @@ Note that if you are using main callbacks instead of a standard C main() functio
Deploying to older versions of iOS
==============================================================================
SDL supports deploying to older versions of iOS than are supported by the latest version of Xcode, all the way back to iOS 8.0
SDL supports deploying to older versions of iOS than are supported by the latest version of Xcode, all the way back to iOS 11.0
In order to do that you need to download an older version of Xcode:
https://developer.apple.com/download/more/?name=Xcode

10
external/SDL/docs/README-linux.md vendored
View File

@@ -17,9 +17,9 @@ 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 \
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 fcitx-libs-dev
libegl1-mesa-dev libdbus-1-dev libibus-1.0-dev libudev-dev
Ubuntu 22.04+ can also add `libpipewire-0.3-dev libwayland-dev libdecor-0-dev liburing-dev` to that command line.
@@ -28,7 +28,7 @@ Fedora 35, all available features enabled:
sudo yum install gcc git-core make cmake \
alsa-lib-devel pulseaudio-libs-devel nas-devel pipewire-devel \
libX11-devel libXext-devel libXrandr-devel libXcursor-devel libXfixes-devel \
libXi-devel libXScrnSaver-devel dbus-devel ibus-devel fcitx-devel \
libXi-devel libXScrnSaver-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 \
@@ -45,6 +45,10 @@ 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
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
Joystick does not work
--------------------------------------------------------------------------------

9
external/SDL/docs/README-macos.md vendored
View File

@@ -13,7 +13,7 @@ To build SDL using the command line, use the CMake build script:
```bash
mkdir build
cd build
cmake .. -DCMAKE_OSX_DEPLOYMENT_TARGET=10.11
cmake .. -DCMAKE_OSX_DEPLOYMENT_TARGET=10.13
cmake --build .
sudo cmake --install .
```
@@ -25,15 +25,12 @@ You can also build SDL as a Universal library (a single binary for both
```bash
mkdir build
cd build
cmake .. "-DCMAKE_OSX_ARCHITECTURES=arm64;x86_64" -DCMAKE_OSX_DEPLOYMENT_TARGET=10.11
cmake .. "-DCMAKE_OSX_ARCHITECTURES=arm64;x86_64" -DCMAKE_OSX_DEPLOYMENT_TARGET=10.13
cmake --build .
sudo cmake --install .
```
Please note that building SDL requires at least Xcode 12.2 and the 11.0 SDK.
PowerPC support for macOS has been officially dropped as of SDL 2.0.2.
32-bit Intel and macOS 10.8 runtime support has been officially dropped as
of SDL 2.24.0.
Please note that building SDL requires at least Xcode 12.2 and the macOS 11.0 SDK.
To use the library once it's built, you essential have two possibilities:
use the traditional autoconf/automake/make method, or use Xcode.

32
external/SDL/docs/README-migration.md vendored
View File

@@ -193,7 +193,7 @@ Rather than iterating over audio devices using a device index, there are new fun
if (devices) {
for (i = 0; i < num_devices; ++i) {
SDL_AudioDeviceID instance_id = devices[i];
SDL_Log("AudioDevice %" SDL_PRIu32 ": %s\n", instance_id, SDL_GetAudioDeviceName(instance_id));
SDL_Log("AudioDevice %" SDL_PRIu32 ": %s", instance_id, SDL_GetAudioDeviceName(instance_id));
}
SDL_free(devices);
}
@@ -411,7 +411,7 @@ The iscapture field of SDL_AudioDeviceEvent has been renamed recording.
SDL_QUERY, SDL_IGNORE, SDL_ENABLE, and SDL_DISABLE have been removed. You can use the functions SDL_SetEventEnabled() and SDL_EventEnabled() to set and query event processing state.
SDL_AddEventWatch() now returns SDL_FALSE_ if it fails because it ran out of memory and couldn't add the event watch callback.
SDL_AddEventWatch() now returns false if it fails because it ran out of memory and couldn't add the event watch callback.
SDL_RegisterEvents() now returns 0 if it couldn't allocate any user events.
@@ -749,7 +749,7 @@ Rather than iterating over haptic devices using device index, there is a new fun
if (haptics) {
for (i = 0; i < num_haptics; ++i) {
SDL_HapticID instance_id = haptics[i];
SDL_Log("Haptic %" SDL_PRIu32 ": %s\n", instance_id, SDL_GetHapticNameForID(instance_id));
SDL_Log("Haptic %" SDL_PRIu32 ": %s", instance_id, SDL_GetHapticNameForID(instance_id));
}
SDL_free(haptics);
}
@@ -917,7 +917,7 @@ Rather than iterating over joysticks using device index, there is a new function
const char *name = SDL_GetJoystickNameForID(instance_id);
const char *path = SDL_GetJoystickPathForID(instance_id);
SDL_Log("Joystick %" SDL_PRIu32 ": %s%s%s VID 0x%.4x, PID 0x%.4x\n",
SDL_Log("Joystick %" SDL_PRIu32 ": %s%s%s VID 0x%.4x, PID 0x%.4x",
instance_id, name ? name : "Unknown", path ? ", " : "", path ? path : "", SDL_GetJoystickVendorForID(instance_id), SDL_GetJoystickProductForID(instance_id));
}
SDL_free(joysticks);
@@ -1031,6 +1031,9 @@ The following structures have been removed:
SDL_Keycode is now Uint32 and the SDLK_* constants are now defines instead of an enum, to more clearly reflect that they are a subset of the possible values of an SDL_Keycode.
In addition to the `SDLK_SCANCODE_MASK` bit found on key codes that directly map to scancodes, there is now the
`SDLK_EXTENDED_MASK` bit used to denote key codes that don't have a corresponding scancode, and aren't a unicode value.
The following symbols have been removed:
* KMOD_RESERVED - No replacement. A bit named "RESERVED" probably shouldn't be used in an app, but if you need it, this was equivalent to KMOD_SCROLL (0x8000) in SDL2.
@@ -1262,6 +1265,7 @@ The following symbols have been renamed:
The following functions have been removed:
* SDL_FreeFormat()
* SDL_SetPixelFormatPalette()
* SDL_CalculateGammaRamp()
The following macros have been removed:
* SDL_Colour - use SDL_Color instead
@@ -1455,7 +1459,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
@@ -1692,7 +1696,7 @@ Rather than iterating over sensors using device index, there is a new function S
SDL_SensorID *sensors = SDL_GetSensors(&num_sensors);
if (sensors) {
for (i = 0; i < num_sensors; ++i) {
SDL_Log("Sensor %" SDL_PRIu32 ": %s, type %d, platform type %d\n",
SDL_Log("Sensor %" SDL_PRIu32 ": %s, type %d, platform type %d",
sensors[i],
SDL_GetSensorNameForID(sensors[i]),
SDL_GetSensorTypeForID(sensors[i]),
@@ -1841,8 +1845,6 @@ SDL_BlitSurface() and SDL_BlitSurfaceScaled() now have a const `dstrect` paramet
SDL_BlitSurfaceScaled() and SDL_BlitSurfaceUncheckedScaled() now take a scale parameter.
SDL_SoftStretch() now takes a scale parameter.
SDL_PixelFormat is used instead of Uint32 for API functions that refer to pixel format by enumerated value.
SDL_SetSurfaceColorKey() takes an bool to enable and disable colorkey. RLE acceleration isn't controlled by the parameter, you should use SDL_SetSurfaceRLE() to change that separately.
@@ -1876,8 +1878,8 @@ The following functions have been removed:
* SDL_GetYUVConversionMode()
* SDL_GetYUVConversionModeForResolution()
* SDL_SetYUVConversionMode() - use SDL_SetSurfaceColorspace() to set the surface colorspace and SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER with SDL_CreateTextureWithProperties() to set the texture colorspace. The default colorspace for YUV pixel formats is SDL_COLORSPACE_JPEG.
* SDL_SoftStretch() - use SDL_BlitSurfaceScaled() with SDL_SCALEMODE_NEAREST
* SDL_SoftStretchLinear() - use SDL_BlitSurfaceScaled() with SDL_SCALEMODE_LINEAR
* SDL_SoftStretch() - use SDL_StretchSurface() with SDL_SCALEMODE_NEAREST
* SDL_SoftStretchLinear() - use SDL_StretchSurface() with SDL_SCALEMODE_LINEAR
The following symbols have been renamed:
* SDL_PREALLOC => SDL_SURFACE_PREALLOCATED
@@ -2117,7 +2119,7 @@ Rather than iterating over displays using display index, there is a new function
SDL_DisplayID instance_id = displays[i];
const char *name = SDL_GetDisplayName(instance_id);
SDL_Log("Display %" SDL_PRIu32 ": %s\n", instance_id, name ? name : "Unknown");
SDL_Log("Display %" SDL_PRIu32 ": %s", instance_id, name ? name : "Unknown");
}
SDL_free(displays);
}
@@ -2163,7 +2165,7 @@ Rather than iterating over display modes using an index, there is a new function
if (modes) {
for (i = 0; i < num_modes; ++i) {
SDL_DisplayMode *mode = modes[i];
SDL_Log("Display %" SDL_PRIu32 " mode %d: %dx%d@%gx %gHz\n",
SDL_Log("Display %" SDL_PRIu32 " mode %d: %dx%d@%gx %gHz",
display, i, mode->w, mode->h, mode->pixel_density, mode->refresh_rate);
}
SDL_free(modes);
@@ -2177,7 +2179,7 @@ Windows now have an explicit fullscreen mode that is set, using SDL_SetWindowFul
SDL_WINDOW_FULLSCREEN_DESKTOP has been removed, and you can call SDL_GetWindowFullscreenMode() to see whether an exclusive fullscreen mode will be used or the borderless fullscreen desktop mode will be used when the window is fullscreen.
SDL_SetWindowBrightness and SDL_SetWindowGammaRamp have been removed from the API, because they interact poorly with modern operating systems and aren't able to limit their effects to the SDL window.
SDL_SetWindowBrightness(), SDL_GetWindowBrightness, SDL_SetWindowGammaRamp(), and SDL_GetWindowGammaRamp have been removed from the API, because they interact poorly with modern operating systems and aren't able to limit their effects to the SDL window.
Programs which have access to shaders can implement more robust versions of those functions using custom shader code rendered as a post-process effect.
@@ -2221,6 +2223,10 @@ The following functions have been removed:
* SDL_CreateWindowFrom() - use SDL_CreateWindowWithProperties() with the properties that allow you to wrap an existing window
* SDL_SetWindowInputFocus() - use SDL_RaiseWindow() instead
* SDL_SetWindowModalFor() - use SDL_SetWindowParent() with SDL_SetWindowModal() instead
* SDL_SetWindowBrightness() - use a shader or other in-game effect.
* SDL_GetWindowBrightness() - use a shader or other in-game effect.
* SDL_SetWindowGammaRamp() - use a shader or other in-game effect.
* SDL_GetWindowGammaRamp() - use a shader or other in-game effect.
The SDL_Window id type is named SDL_WindowID

42
external/SDL/docs/README-platforms.md vendored
View File

@@ -1,8 +1,40 @@
Platforms
=========
# Platforms
We maintain the list of supported platforms on our wiki now, and how to
build and install SDL for those platforms:
## Supported Platforms
https://wiki.libsdl.org/Installation
- [Android](README-android.md)
- [Emscripten](README-emscripten.md)
- [FreeBSD](README-bsd.md)
- [Haiku OS](README-haiku.md)
- [iOS](README-ios.md)
- [Linux](README-linux.md)
- [macOS](README-macos.md)
- [NetBSD](README-bsd.md)
- [Nintendo Switch](README-switch.md)
- [Nintendo 3DS](README-3ds.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)
- [RISC OS](README-riscos.md)
- [SteamOS](README-steamos.md)
- [tvOS](README-ios.md)
- [Windows](README-windows.md)
- [Windows GDK](README-gdk.md)
- [Xbox](README-gdk.md)
## 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.
- Google Stadia
- NaCL
- Nokia N-Gage
- OS/2
- QNX
- WinPhone
- WinRT/UWP

3
external/SDL/docs/README-ps4.md vendored Normal file
View File

@@ -0,0 +1,3 @@
# Sony PlayStation 4
SDL3 runs on the PS4! 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 PlayStation development with Sony. Please contact Ryan (icculus at icculus dot org) for details.

3
external/SDL/docs/README-ps5.md vendored Normal file
View File

@@ -0,0 +1,3 @@
# Sony PlayStation 5
SDL3 runs on the PS5! 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 PlayStation development with Sony. Please contact Ryan (icculus at icculus dot org) for details.

6
external/SDL/docs/README-psp.md vendored
View File

@@ -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
@@ -29,7 +29,7 @@ cmake --install build
## Compiling a HelloWorld
[PSP Hello World](https://psp-dev.org/doku.php?id=tutorial:hello_world)
[PSP Hello World](https://pspdev.github.io/basic_programs.html#hello-world)
## To Do
- PSP Screen Keyboard

188
external/SDL/docs/README-raspberrypi.md vendored
View File

@@ -1,188 +0,0 @@
Raspberry Pi
============
Requirements:
Raspberry Pi OS (other Linux distros may work as well).
In modern times, the Raspberry Pi works mostly like any other Linux device:
for video, you can use X11, Wayland, or KMSDRM. For audio, you can use ALSA,
PulseAudio, or PipeWire, etc. OpenGL, OpenGL ES, and Vulkan are known to work.
There is a video backend in SDL called "rpi" that uses a deprecated Broadcom
interface (named "dispmanx") to draw directly to the console without X11.
Newer Raspberry Pi OS releases don't support this (and work fine with our
"kmsdrm" backend for the same purposes, a standard Linux interface). Don't
panic if you can't use this backend, or CMake says it can't find libraries it
needs for this.
SDL has, in past times, worked on the original Raspberry Pi and the RPi 2, but
these devices are no longer targets we actively test; if they broke, please
report bugs or send patches!
The Raspberry Pi 3 and later (in 32-bit and 64-bit mode) are still known to
work well at the time of this writing. The Raspberry Pi Zero and Zero 2 are
also known to work well.
## Documentation Out Of Date
The rest of this document is likely out of date; a lot has changed in recent
years in both SDL and the Raspberry Pi universe, and this document has not
been updated to reflect those details. Take the rest of this information with
a grain of salt!
NEON
----
If your Pi has NEON support, make sure you add -mfpu=neon to your CFLAGS so
that SDL will select some otherwise-disabled highly-optimized code. The
original Pi and Pi Zero units don't have NEON; everything from the Pi2/PiZero2
and later do.
Cross compiling from x86 Linux
------------------------------
To cross compile SDL for Raspbian from your desktop machine, you'll need a
Raspbian system root and the cross compilation tools. We'll assume these tools
will be placed in /opt/rpi-tools
sudo git clone --depth 1 https://github.com/raspberrypi/tools /opt/rpi-tools
You'll also need a Raspbian binary image.
Get it from: http://downloads.raspberrypi.org/raspbian_latest
After unzipping, you'll get file with a name like: "<date>-wheezy-raspbian.img"
Let's assume the sysroot will be built in /opt/rpi-sysroot.
export SYSROOT=/opt/rpi-sysroot
sudo kpartx -a -v <path_to_raspbian_image>.img
sudo mount -o loop /dev/mapper/loop0p2 /mnt
sudo cp -r /mnt $SYSROOT
sudo apt-get install qemu binfmt-support qemu-user-static
sudo cp /usr/bin/qemu-arm-static $SYSROOT/usr/bin
sudo mount --bind /dev $SYSROOT/dev
sudo mount --bind /proc $SYSROOT/proc
sudo mount --bind /sys $SYSROOT/sys
Now, before chrooting into the ARM sysroot, you'll need to apply a workaround,
edit $SYSROOT/etc/ld.so.preload and comment out all lines in it.
sudo chroot $SYSROOT
apt-get install libudev-dev libasound2-dev libdbus-1-dev libraspberrypi0 libraspberrypi-bin libraspberrypi-dev libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxss-dev
exit
sudo umount $SYSROOT/dev
sudo umount $SYSROOT/proc
sudo umount $SYSROOT/sys
sudo umount /mnt
There's one more fix required, as the libdl.so symlink uses an absolute path
which doesn't quite work in our setup.
sudo rm -rf $SYSROOT/usr/lib/arm-linux-gnueabihf/libdl.so
sudo ln -s ../../../lib/arm-linux-gnueabihf/libdl.so.2 $SYSROOT/usr/lib/arm-linux-gnueabihf/libdl.so
The final step is compiling SDL itself.
export CC="/opt/rpi-tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf-gcc --sysroot=$SYSROOT -I$SYSROOT/opt/vc/include -I$SYSROOT/usr/include -I$SYSROOT/opt/vc/include/interface/vcos/pthreads -I$SYSROOT/opt/vc/include/interface/vmcs_host/linux"
cd <SDL SOURCE>
mkdir -p build;cd build
LDFLAGS="-L$SYSROOT/opt/vc/lib" ../configure --with-sysroot=$SYSROOT --host=arm-raspberry-linux-gnueabihf --prefix=$PWD/rpi-sdl3-installed --disable-pulseaudio --disable-esd
make
make install
To be able to deploy this to /usr/local in the Raspbian system you need to fix up a few paths:
perl -w -pi -e "s#$PWD/rpi-sdl3-installed#/usr/local#g;" ./rpi-sdl3-installed/lib/libSDL3.la ./rpi-sdl3-installed/lib/pkgconfig/sdl3.pc
Apps don't work or poor video/audio performance
-----------------------------------------------
If you get sound problems, buffer underruns, etc, run "sudo rpi-update" to
update the RPi's firmware. Note that doing so will fix these problems, but it
will also render the CMA - Dynamic Memory Split functionality useless.
Also, by default the Raspbian distro configures the GPU RAM at 64MB, this is too
low in general, specially if a 1080p TV is hooked up.
See here how to configure this setting: http://elinux.org/RPiconfig
Using a fixed gpu_mem=128 is the best option (specially if you updated the
firmware, using CMA probably won't work, at least it's the current case).
No input
--------
Make sure you belong to the "input" group.
sudo usermod -aG input `whoami`
No HDMI Audio
-------------
If you notice that ALSA works but there's no audio over HDMI, try adding:
hdmi_drive=2
to your config.txt file and reboot.
Reference: http://www.raspberrypi.org/phpBB3/viewtopic.php?t=5062
Text Input API support
----------------------
The Text Input API is supported, with translation of scan codes done via the
kernel symbol tables. For this to work, SDL needs access to a valid console.
If you notice there's no SDL_EVENT_TEXT_INPUT message being emitted, double check that
your app has read access to one of the following:
* /proc/self/fd/0
* /dev/tty
* /dev/tty[0...6]
* /dev/vc/0
* /dev/console
This is usually not a problem if you run from the physical terminal (as opposed
to running from a pseudo terminal, such as via SSH). If running from a PTS, a
quick workaround is to run your app as root or add yourself to the tty group,
then re-login to the system.
sudo usermod -aG tty `whoami`
The keyboard layout used by SDL is the same as the one the kernel uses.
To configure the layout on Raspbian:
sudo dpkg-reconfigure keyboard-configuration
To configure the locale, which controls which keys are interpreted as letters,
this determining the CAPS LOCK behavior:
sudo dpkg-reconfigure locales
OpenGL problems
---------------
If you have desktop OpenGL headers installed at build time in your RPi or cross
compilation environment, support for it will be built in. However, the chipset
does not actually have support for it, which causes issues in certain SDL apps
since the presence of OpenGL support supersedes the ES/ES2 variants.
The workaround is to disable OpenGL at configuration time:
./configure --disable-video-opengl
Or if the application uses the Render functions, you can use the SDL_RENDER_DRIVER
environment variable:
export SDL_RENDER_DRIVER=opengles2
Notes
-----
* When launching apps remotely (via SSH), SDL can prevent local keystrokes from
leaking into the console only if it has root privileges. Launching apps locally
does not suffer from this issue.

10
external/SDL/docs/README-steamos.md vendored Normal file
View File

@@ -0,0 +1,10 @@
# SteamOS
SteamOS is literally a Linux system, and uses the same binaries you distribute to generic Linux Steam users, so generally speaking, all the other [Linux advice](README-linux.md) applies.
If you are shipping a Linux game on Steam, or explicitly targeting SteamOS, the system is guaranteed to provide SDL. The Steam Client will set up the dynamic loader path so that a known-good copy of SDL is available to any program that needs it before launching a game. Steam provides all major versions of SDL to date, in this manner, for both x86 and amd64, in addition to several add-on libraries like `SDL_image` and `SDL_mixer`. When shipping a Linux game on Steam, do not ship a build of SDL with your game. Link against SDL as normal, and expect it to be available on the player's system. This allows Valve to make fixes and improvements to their SDL and those fixes to flow on to your game.
We are obsessive about SDL3 having a backwards-compatible ABI. Whether you build your game using the Steam Runtime SDK or just about any other copy of SDL, it _should_ work with the one that ships with Steam.
In fact, it's not a bad idea to just copy the SDL build out of the Steam Runtime if you plan to ship a Linux game for non-Steam platforms, too, since you know it's definitely well-built.

3
external/SDL/docs/README-switch.md vendored Normal file
View File

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

68
external/SDL/docs/README-versions.md vendored
View File

@@ -1,60 +1,48 @@
# Versioning
## Since 2.23.0
## Since 3.2.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.
* If the minor version (second part) and the patch version (third part) is
divisible by 2 (for example 3.2.6, 3.4.0), 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).
indicates bugfix releases. Bugfix releases may add small changes
to the ABI, so newer patch versions are backwards-compatible but
not fully forwards-compatible. For example, programs built against
SDL 3.2.0 should work fine with SDL 3.2.8, but programs built against
SDL 3.2.8 may not work with 3.2.0.
* 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.
* The minor version increases when significant changes are made that
require longer development or testing time, e.g. major new functionality,
or revamping support for a platform. Newer minor versions are
backwards-compatible, but not fully forwards-compatible. For example,
programs built against SDL 3.2.x should work fine with SDL 3.4.x,
but programs built against SDL 3.4.x may not work with 3.2.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.
* If the minor version (second part) or patch version (third part) is not
divisible by 2 (for example 3.2.9, 3.3.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.
* The patchlevel or micro version (third part) increases with each prerelease.
* Prereleases are backwards-compatible with older stable branches.
For example, 2.25.x will be backwards-compatible with 2.24.x.
For example, programs built against SDL 3.2.x should work fine with
SDL 3.3.x, but programs built against SDL 3.3.x may not work with 3.2.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.
* Prereleases are not guaranteed to be backwards-compatible with each other.
For example, new API or ABI added in 3.3.0 might be removed or changed in
3.3.1. 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.
* Only use a prerelease if you can guarantee that you will promptly upgrade
to the stable release that follows it. For example, do not use 3.3.x
unless you will be able to upgrade to 3.4.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.
should 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.

113
external/SDL/docs/README-visualc.md vendored
View File

@@ -1,113 +0,0 @@
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/SDL3.dll` or `./VisualC/Win32/Release/SDL3.dll`
- `./VisualC/Win32/Debug/SDL3.lib` or `./VisualC/Win32/Release/SDL3.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:
- `SDL3.dll`
Add the following file to your project (It is not necessary to copy it to your project directory):
- `SDL3.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 SDL
Here's a sample SDL snippet to verify everything is setup in your IDE:
```c
#include <SDL3/SDL.h>
#include <SDL3/SDL_main.h> // only include this one in the source file with main()!
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("Hello SDL", WIDTH, HEIGHT, 0);
renderer = SDL_CreateRenderer(window, NULL);
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 italic) was added by [James Turk](mailto:james@conceptofzero.net)

8
external/SDL/docs/README-vita.md vendored
View File

@@ -10,10 +10,10 @@ Credit to
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
```sh
cmake -S. -Bbuild -DCMAKE_TOOLCHAIN_FILE=${VITASDK}/share/vita.toolchain.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build
```

4
external/SDL/docs/README-wayland.md vendored
View File

@@ -59,6 +59,10 @@ 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`.
### 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.
## Using custom Wayland windowing protocols with SDL windows
Under normal operation, an `SDL_Window` corresponds to an XDG toplevel window, which provides a standard desktop window.

4
external/SDL/docs/README-windows.md vendored
View File

@@ -18,7 +18,9 @@ Details are here: https://github.com/libsdl-org/SDL/issues/5186
## MinGW-w64 compiler support
SDL can be built with MinGW-w64 and CMake. First, you need to install and set up the MSYS2 environment, which provides the MinGW-w64 toolchain. Install MSYS2, typically to `C:\msys64`, and follow the instructions on the MSYS2 wiki to use the MinGW-w64 shell to update all components in the MSYS2 environment. This generally amounts to running `pacman -Syuu` from the mingw64 shell, but refer to MSYS2's documentation for more details. Once the MSYS2 environment has been updated, install the x86_64 MinGW toolchain from the mingw64 shell with the command `pacman -S mingw-w64-x86_64-toolchain`. (You can additionally install `mingw-w64-i686-toolchain` if you intend to build 32-bit binaries as well. The remainder of this section assumes you only want to build 64-bit binaries.)
SDL can be built with MinGW-w64 and CMake. Minimum tested MinGW-w64 version is 8.0.3.
On a Windows host, you first need to install and set up the MSYS2 environment, which provides the MinGW-w64 toolchain. Install MSYS2, typically to `C:\msys64`, and follow the instructions on the MSYS2 wiki to use the MinGW-w64 shell to update all components in the MSYS2 environment. This generally amounts to running `pacman -Syuu` from the mingw64 shell, but refer to MSYS2's documentation for more details. Once the MSYS2 environment has been updated, install the x86_64 MinGW toolchain from the mingw64 shell with the command `pacman -S mingw-w64-x86_64-toolchain`. (You can additionally install `mingw-w64-i686-toolchain` if you intend to build 32-bit binaries as well. The remainder of this section assumes you only want to build 64-bit binaries.)
To build and install SDL, you can use PowerShell or any CMake-compatible IDE. First, install CMake, Ninja, and Git. These tools can be installed using any number of tools, such as the MSYS2's `pacman`, `winget`, `Chocolatey`, or by manually downloading and running the installers. Clone SDL to an appropriate location with `git` and run the following commands from the root of the cloned repository:

32
external/SDL/docs/README.md vendored
View File

@@ -7,8 +7,7 @@ to provide low level access to audio, keyboard, mouse, joystick, and graphics
hardware. 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, macOS, Linux, iOS, and Android.
Support for other platforms may be found in the source code.
SDL officially supports Windows, macOS, Linux, iOS, Android, Xbox, PlayStation 4/5, Nintendo Switch, and many other platforms.
SDL is written in C, works natively with C++, and there are bindings
available for several other languages, including C# and Python.
@@ -19,36 +18,19 @@ in the file "LICENSE.txt".
Information on building SDL with CMake is available in [README-cmake.md](README-cmake.md)
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.
the "include" subdirectory and the programs in the "examples" subdirectory.
The header files and test programs are well commented and always up to date.
Information on reporting bugs and contributing is available in [README-contributing.md](README-contributing.md)
More documentation and FAQs are available online at [the wiki](http://wiki.libsdl.org/)
More documentation and FAQs are available online at the [wiki](http://wiki.libsdl.org/)
- [High DPI Support](README-highdpi.md)
- [main()](README-main-functions.md)
- [Porting information](README-porting.md)
- [Migrating from SDL 2.0](README-migration.md)
- [Supported Platforms](README-platforms.md)
- [main()](README-main-functions.md)
- [High DPI Support](README-highdpi.md)
- [Touch](README-touch.md)
- [Versions](README-versions.md)
- [Visual Studio](README-visualc.md)
- [Android](README-android.md)
- [Emscripten](README-emscripten.md)
- [iOS](README-ios.md)
- [KMSDRM support on BSD](README-kmsbsd.md)
- [Linux](README-linux.md)
- [macOS](README-macos.md)
- [Nintendo 3DS](README-n3ds.md)
- [PS2](README-ps2.md)
- [PSP](README-psp.md)
- [PSVita](README-vita.md)
- [Raspberry Pi](README-raspberrypi.md)
- [RISC OS](README-riscos.md)
- [Windows GDK](README-gdk.md)
- [Windows](README-windows.md)
- [Supported platforms](README-platforms.md)
- [Porting information](README-porting.md)
If you need help with the library, or just want to discuss SDL related
issues, you can join the [SDL Discourse](https://discourse.libsdl.org/),

68
external/SDL/docs/hello.c vendored Normal file
View File

@@ -0,0 +1,68 @@
/*
Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely.
*/
#define SDL_MAIN_USE_CALLBACKS 1 /* use the callbacks instead of main() */
#include <SDL3/SDL.h>
#include <SDL3/SDL_main.h>
static SDL_Window *window = NULL;
static SDL_Renderer *renderer = NULL;
/* This function runs once at startup. */
SDL_AppResult SDL_AppInit(void **appstate, int argc, char *argv[])
{
/* Create the window */
if (!SDL_CreateWindowAndRenderer("Hello World", 800, 600, SDL_WINDOW_FULLSCREEN, &window, &renderer)) {
SDL_Log("Couldn't create window and renderer: %s", SDL_GetError());
return SDL_APP_FAILURE;
}
return SDL_APP_CONTINUE;
}
/* This function runs when a new event (mouse input, keypresses, etc) occurs. */
SDL_AppResult SDL_AppEvent(void *appstate, SDL_Event *event)
{
if (event->type == SDL_EVENT_KEY_DOWN ||
event->type == SDL_EVENT_QUIT) {
return SDL_APP_SUCCESS; /* end the program, reporting success to the OS. */
}
return SDL_APP_CONTINUE;
}
/* This function runs once per frame, and is the heart of the program. */
SDL_AppResult SDL_AppIterate(void *appstate)
{
const char *message = "Hello World!";
int w = 0, h = 0;
float x, y;
const float scale = 4.0f;
/* Center the message and scale it up */
SDL_GetRenderOutputSize(renderer, &w, &h);
SDL_SetRenderScale(renderer, scale, scale);
x = ((w / scale) - SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE * SDL_strlen(message)) / 2;
y = ((h / scale) - SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE) / 2;
/* Draw the message */
SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);
SDL_RenderClear(renderer);
SDL_SetRenderDrawColor(renderer, 255, 255, 255, 255);
SDL_RenderDebugText(renderer, x, y, message);
SDL_RenderPresent(renderer);
return SDL_APP_CONTINUE;
}
/* This function runs once at shutdown. */
void SDL_AppQuit(void *appstate, SDL_AppResult result)
{
}

2
external/SDL/docs/release_checklist.md vendored
View File

@@ -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`