TorqueGameEngines/Torque3D
1
0
Fork 0
mirror of https://github.com/TorqueGameEngines/Torque3D.git synced 2026-07-12 07:04:36 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

update sdl to 2.26.5

Browse source
This commit is contained in:
AzaezelX 2023-05-27 10:16:20 -05:00
parent 0d981b62cf
commit 0e44e165bd
1260 changed files with 290370 additions and 124892 deletions
Download patch file Download diff file Expand all files Collapse all files

97
Engine/lib/sdl/docs/CONTRIBUTING.md Normal file
View file

@ -0,0 +1,97 @@
# Contributing to SDL
We appreciate your interest in contributing to SDL, this document will describe how to report bugs, contribute code or ideas or edit documentation.
**Table Of Contents**
- [Filing a GitHub issue](#filing-a-github-issue)
- [Reporting a bug](#reporting-a-bug)
- [Suggesting enhancements](#suggesting-enhancements)
- [Contributing code](#contributing-code)
- [Forking the project](#forking-the-project)
- [Following the style guide](#following-the-style-guide)
- [Running the tests](#running-the-tests)
- [Opening a pull request](#opening-a-pull-request)
- [Contributing to the documentation](#contributing-to-the-documentation)
- [Editing a function documentation](#editing-a-function-documentation)
- [Editing the wiki](#editing-the-wiki)
## Filing a GitHub issue
### Reporting a bug
If you think you have found a bug and would like to report it, here are the steps you should take:
- Before opening a new issue, ensure your bug has not already been reported on the [GitHub Issues page](https://github.com/libsdl-org/SDL/issues).
- On the issue tracker, click on [New Issue](https://github.com/libsdl-org/SDL/issues/new).
- Include details about your environment, such as your Operating System and SDL version.
- If possible, provide a small example that reproduces your bug.
### Suggesting enhancements
If you want to suggest changes for the project, here are the steps you should take:
- Check if the suggestion has already been made on:
- the [issue tracker](https://github.com/libsdl-org/SDL/issues);
- the [discourse forum](https://discourse.libsdl.org/);
- or if a [pull request](https://github.com/libsdl-org/SDL/pulls) already exists.
- On the issue tracker, click on [New Issue](https://github.com/libsdl-org/SDL/issues/new).
- Describe what change you would like to happen.
## Contributing code
This section will cover how the process of forking the project, making a change and opening a pull request.
### Forking the project
The first step consists in making a fork of the project, this is only necessary for the first contribution.
Head over to https://github.com/libsdl-org/SDL and click on the `Fork` button in the top right corner of your screen, you may leave the fields unchanged and click `Create Fork`.
You will be redirected to your fork of the repository, click the green `Code` button and copy the git clone link.
If you had already forked the repository, you may update it from the web page using the `Fetch upstream` button.
### Following the style guide
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.
For your commit message to be properly displayed on GitHub, it should contain:
- A short description of the commit of 50 characters or less on the first line.
- If necessary, add a blank line followed by a long description, each line should be 72 characters or less.
For example:
```
Fix crash in SDL_FooBar.
This addresses the issue #123456 by making sure Foo was successful
before calling Bar.
```
### Running the tests
Tests allow you to verify if your changes did not break any behaviour, here are the steps to follow:
- Before pushing, run the `testautomation` suite on your machine, there should be no more failing tests after your change than before.
- After pushing to your fork, Continuous Integration (GitHub Actions) will ensure compilation and tests still pass on other systems.
### Opening a pull request
- Head over to your fork's GitHub page.
- Click on the `Contribute` button and `Open Pull Request`.
- Fill out the pull request template.
- If any changes are requested, you can add new commits to your fork and they will be automatically added to the pull request.
## Contributing to the documentation
### Editing a function documentation
The wiki documentation for API functions is synchronised from the headers' doxygen comments. As such, all modifications to syntax; function parameters; return value; version; related functions should be done in the header directly.
### Editing the wiki
Other changes to the wiki should done directly from https://wiki.libsdl.org/

2
Engine/lib/sdl/docs/README-android.md
View file

@ -13,7 +13,7 @@ supported, but you can use the "android-project-ant" directory as a template.
Requirements
================================================================================
Android SDK (version 26 or later)
Android SDK (version 31 or later)
https://developer.android.com/sdk/index.html
Android NDK r15c or later

135
Engine/lib/sdl/docs/README-cmake.md
View file

@ -1,40 +1,102 @@
CMake
================================================================================
# CMake
(www.cmake.org)
SDL's build system was traditionally based on autotools. Over time, this
approach has suffered from several issues across the different supported
platforms.
To solve these problems, a new build system based on CMake is under development.
It works in parallel to the legacy system, so users can experiment with it
without complication.
While still experimental, the build system should be usable on the following
platforms:
To solve these problems, a new build system based on CMake was introduced.
It is developed in parallel to the legacy autotools build system, so users
can experiment with it without complication.
The CMake build system is supported on the following platforms:
* FreeBSD
* Linux
* VS.NET 2010
* Microsoft Visual C
* MinGW and Msys
* macOS, iOS, and tvOS, with support for XCode
* Android
* Emscripten
* RiscOS
* Playstation Vita
## Building SDL
================================================================================
Usage
================================================================================
Assuming the source for SDL is located at `~/sdl`
```sh
cd ~
mkdir build
cd build
cmake ~/sdl
cmake --build .
```
Assuming the source for SDL is located at ~/sdl
This will build the static and dynamic versions of SDL in the `~/build` directory.
Installation can be done using:
cd ~
mkdir build
cd build
cmake ../sdl
```sh
cmake --install . # '--install' requires CMake 3.15, or newer
```
This will build the static and dynamic versions of SDL in the ~/build directory.
## 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 vendored SDL library: this is SDL copied or symlinked in a subfolder.
================================================================================
Usage, iOS/tvOS
================================================================================
The following CMake script supports both, depending on the value of `MYGAME_VENDORED`.
```cmake
cmake_minimum_required(VERSION 3.0)
project(mygame)
# Create an option to switch between a system sdl library and a vendored sdl library
option(MYGAME_VENDORED "Use vendored libraries" OFF)
if(MYGAME_VENDORED)
add_subdirectory(vendored/sdl EXCLUDE_FROM_ALL)
else()
# 1. Look for a SDL2 package, 2. look for the SDL2 component and 3. fail if none can be found
find_package(SDL2 REQUIRED CONFIG REQUIRED COMPONENTS SDL2)
# 1. Look for a SDL2 package, 2. Look for the SDL2maincomponent and 3. DO NOT fail when SDL2main is not available
find_package(SDL2 REQUIRED CONFIG COMPONENTS SDL2main)
endif()
# Create your game executable target as usual
add_executable(mygame WIN32 mygame.c)
# SDL2::SDL2main may or may not be available. It is e.g. required by Windows GUI applications
if(TARGET SDL2::SDL2main)
# It has an implicit dependency on SDL2 functions, so it MUST be added before SDL2::SDL2 (or SDL2::SDL2-static)
target_link_libraries(mygame PRIVATE SDL2::SDL2main)
endif()
# Link to the actual SDL2 library. SDL2::SDL2 is the shared SDL library, SDL2::SDL2-static is the static SDL libarary.
target_link_libraries(mygame PRIVATE SDL2::SDL2)
```
### A system SDL library
For CMake to find SDL, it must be installed in [a default location CMake is looking for](https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure).
The following components are available, to be used as an argument of `find_package`.
| Component name | Description |
|----------------|--------------------------------------------------------------------------------------------|
| SDL2 | The SDL2 shared library, available through the `SDL2::SDL2` target [^SDL_TARGET_EXCEPTION] |
| SDL2-static | The SDL2 static library, available through the `SDL2::SDL2-static` target |
| SDL2main | The SDL2main static library, available through the `SDL2::SDL2main` target |
| SDL2test | The SDL2test static library, available through the `SDL2::SDL2test` target |
### Using a vendored SDL
This only requires a copy of SDL in a subdirectory.
## CMake configuration options for platforms
### iOS/tvOS
CMake 3.14+ natively includes support for iOS and tvOS. SDL binaries may be built
using Xcode or Make, possibly among other build-systems.
@ -53,32 +115,49 @@ To use, set the following CMake variables when running CMake's configuration sta
- `CMAKE_OSX_ARCHITECTURES=<semicolon-separated list of CPU architectures>` (example: "arm64;armv7s;x86_64")
### Examples (for iOS/tvOS):
#### Examples
- for iOS-Simulator, using the latest, installed SDK:
`cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=x86_64`
```bash
cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=x86_64
```
- for iOS-Device, using the latest, installed SDK, 64-bit only
`cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_ARCHITECTURES=arm64`
```bash
cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_ARCHITECTURES=arm64
```
- for iOS-Device, using the latest, installed SDK, mixed 32/64 bit
`cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_ARCHITECTURES="arm64;armv7s"`
```cmake
cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_ARCHITECTURES="arm64;armv7s"
```
- for iOS-Device, using a specific SDK revision (iOS 12.4, in this example):
`cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos12.4 -DCMAKE_OSX_ARCHITECTURES=arm64`
```cmake
cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos12.4 -DCMAKE_OSX_ARCHITECTURES=arm64
```
- for iOS-Simulator, using the latest, installed SDK, and building SDL test apps (as .app bundles):
`cmake ~/sdl -DSDL_TEST=1 -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=x86_64`
```cmake
cmake ~/sdl -DSDL_TESTS=1 -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=x86_64
```
- for tvOS-Simulator, using the latest, installed SDK:
`cmake ~/sdl -DCMAKE_SYSTEM_NAME=tvOS -DCMAKE_OSX_SYSROOT=appletvsimulator -DCMAKE_OSX_ARCHITECTURES=x86_64`
```cmake
cmake ~/sdl -DCMAKE_SYSTEM_NAME=tvOS -DCMAKE_OSX_SYSROOT=appletvsimulator -DCMAKE_OSX_ARCHITECTURES=x86_64
```
- for tvOS-Device, using the latest, installed SDK:
`cmake ~/sdl -DCMAKE_SYSTEM_NAME=tvOS -DCMAKE_OSX_SYSROOT=appletvos -DCMAKE_OSX_ARCHITECTURES=arm64`
```cmake
cmake ~/sdl -DCMAKE_SYSTEM_NAME=tvOS -DCMAKE_OSX_SYSROOT=appletvos -DCMAKE_OSX_ARCHITECTURES=arm64`
```
[^SDL_TARGET_EXCEPTION]: `SDL2::SDL2` can be an ALIAS to a static `SDL2::SDL2-static` target for multiple reasons.

45
Engine/lib/sdl/docs/README-emscripten.md
View file

@ -1,5 +1,46 @@
Emscripten
================================================================================
# Emscripten
(This documentation is not very robust; we will update and expand this later.)
## A quick note about audio
Modern web browsers will not permit web pages to produce sound before the
user has interacted with them; this is 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.
To solve this, most browsers will refuse to let a web app use the audio
subsystem at all before the user has interacted with (clicked on) the page
in a meaningful way. SDL-based apps also have to deal with this problem; if
the user hasn't interacted with the page, SDL_OpenAudioDevice will fail.
There are two reasonable ways to deal with this: 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 play at start, the user can
reasonably opt-in to listening, and you never get access denied to the audio
device.
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.
Please see the discussion at https://github.com/libsdl-org/SDL/issues/6385
for some Javascript code to steal for this approach.
## Building SDL/emscripten
SDL currently requires at least Emscripten 2.0.32 to build. Newer versions
are likely to work, as well.
Build:

155
Engine/lib/sdl/docs/README-gdk.md Normal file
View file

@ -0,0 +1,155 @@
GDK
=====
This port allows SDL applications to run via Microsoft's Game Development Kit (GDK).
Windows (GDK) and Xbox One/Xbox Series (GDKX) are supported. Although most of the Xbox code is included in the public SDL source code, NDA access is required for a small number of source files. If you have access to GDKX, these required Xbox files are posted on the GDK forums [here](https://forums.xboxlive.com/questions/130003/).
Requirements
------------
* Microsoft Visual Studio 2022 (in theory, it should also work in 2017 or 2019, but this has not been tested)
* Microsoft GDK June 2022 or newer (public release [here](https://github.com/microsoft/GDK/releases/tag/June_2022))
* To publish a package or successfully authenticate a user, you will need to create an app id/configure services in Partner Center. However, for local testing purposes (without authenticating on Xbox Live), the identifiers used by the GDK test programs in the included solution will work.
Windows GDK Status
------
The Windows GDK port supports the full set of Win32 APIs, renderers, controllers, input devices, etc., as the normal Windows x64 build of SDL.
* Additionally, the GDK port adds the following:
* Compile-time platform detection for SDL programs. The `__GDK__` is `#define`d on every GDK platform, and the `__WINGDK__` is `#define`d on Windows GDK, specifically. (This distinction exists because other GDK platforms support a smaller subset of functionality. This allows you to mark code for "any" GDK separate from Windows GDK.)
* GDK-specific setup:
* Initializing/uninitializing the game runtime, and initializing Xbox Live services
* Creating a global task queue and setting it as the default for the process. When running any async operations, passing in `NULL` as the task queue will make the task get added to the global task queue.
* An implementation on `WinMain` that performs the above GDK setup (you should link against SDL2main.lib, as in Windows x64). If you are unable to do this, you can instead manually call `SDL_GDKRunApp` from your entry point, passing in your `SDL_main` function and `NULL` as the parameters.
* Global task queue callbacks are dispatched during `SDL_PumpEvents` (which is also called internally if using `SDL_PollEvent`).
* You can get the handle of the global task queue through `SDL_GDKGetTaskQueue`, if needed. When done with the queue, be sure to use `XTaskQueueCloseHandle` to decrement the reference count (otherwise it will cause a resource leak).
* What doesn't work:
* Compilation with anything other than through the included Visual C++ solution file
## VisualC-GDK Solution
The included `VisualC-GDK/SDL.sln` solution includes the following targets for the Gaming.Desktop.x64 configuration:
* SDL2 (DLL) - This is the typical SDL2.dll, but for Gaming.Desktop.x64.
* SDL2main (lib) - This contains a drop-in implementation of `WinMain` that is used as the entry point for GDK programs.
* tests/testgamecontroller - Standard SDL test program demonstrating controller functionality.
* tests/testgdk - GDK-specific test program that demonstrates using the global task queue to login a user into Xbox Live.
*NOTE*: As of the June 2022 GDK, you cannot test user logins without a valid Title ID and MSAAppId. You will need to manually change the identifiers in the `MicrosoftGame.config` to your valid IDs from Partner Center if you wish to test this.
* tests/testsprite2 - Standard SDL test program demonstrating sprite drawing functionality.
If you set one of the test programs as a startup project, you can run it directly from Visual Studio.
Windows GDK Setup, Detailed Steps
---------------------
These steps assume you already have a game using SDL that runs on Windows x64 along with a corresponding Visual Studio solution file for the x64 version. If you don't have this, it's easiest to use one of the test program vcxproj files in the `VisualC-GDK` directory as a starting point, though you will still need to do most of the steps below.
### 1. Add a Gaming.Desktop.x64 Configuration ###
In your game's existing Visual Studio Solution, go to Build > Configuration Manager. From the "Active solution platform" drop-down select "New...". From the drop-down list, select Gaming.Desktop.x64 and copy the settings from the x64 configuration.
### 2. Build SDL2 and SDL2main for GDK ###
Open `VisualC-GDK/SDL.sln` in Visual Studio, you need to build the SDL2 and SDL2main targets for the Gaming.Desktop.x64 platform (Release is recommended). You will need to copy/keep track of the `SDL2.dll`, `XCurl.dll` (which is output by Gaming.Desktop.x64), `SDL2.lib`, and `SDL2main.lib` output files for your game project.
*Alternatively*, you could setup your solution file to instead reference the SDL2/SDL2main project file targets from the SDL source, and add those projects as a dependency. This would mean that SDL2 and SDL2main would both be built when your game is built.
### 3. Configuring Project Settings ###
While the Gaming.Desktop.x64 configuration sets most of the required settings, there are some additional items to configure for your game project under the Gaming.Desktop.x64 Configuration:
* Under C/C++ > General > Additional Include Directories, make sure the `SDL/include` path is referenced
* Under Linker > General > Additional Library Directories, make sure to reference the path where the newly-built SDL2.lib and SDL2main.lib are
* Under Linker > Input > Additional Dependencies, you need the following:
* `SDL2.lib`
* `SDL2main.lib` (unless not using)
* `xgameruntime.lib`
* `../Microsoft.Xbox.Services.141.GDK.C.Thunks.lib`
* Note that in general, the GDK libraries depend on the MSVC C/C++ runtime, so there is no way to remove this dependency from a GDK program that links against GDK.
### 4. Setting up SDL_main ###
Rather than using your own implementation of `WinMain`, it's recommended that you instead `#include "SDL_main.h"` and declare a standard main function. If you are unable to do this, you can instead manually call `SDL_GDKRunApp` from your entry point, passing in your `SDL_main` function and `NULL` as the parameters.
### 5. Required DLLs ###
The game will not launch in the debugger unless required DLLs are included in the directory that contains the game's .exe file. You need to make sure that the following files are copied into the directory:
* Your SDL2.dll
* "$(Console_GRDKExtLibRoot)Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release\Microsoft.Xbox.Services.141.GDK.C.Thunks.dll"
* XCurl.dll
You can either copy these in a post-build step, or you can add the dlls into the project and set its Configuration Properties > General > Item type to "Copy file," which will also copy them into the output directory.
### 6. Setting up MicrosoftGame.config ###
You can copy `VisualC-GDK/tests/testgdk/MicrosoftGame.config` and use that as a starting point in your project. Minimally, you will want to change the Executable Name attribute, the DefaultDisplayName, and the Description.
This file must be copied into the same directory as the game's .exe file. As with the DLLs, you can either use a post-build step or the "Copy file" item type.
For basic testing, you do not need to change anything else in `MicrosoftGame.config`. However, if you want to test any Xbox Live services (such as logging in users) _or_ publish a package, you will need to setup a Game app on Partner Center.
Then, you need to set the following values to the values from Partner Center:
* Identity tag - Name and Publisher attributes
* TitleId
* MSAAppId
### 7. Adding Required Logos
Several logo PNG files are required to be able to launch the game, even from the debugger. You can use the sample logos provided in `VisualC-GDK/logos`. As with the other files, they must be copied into the same directory as the game's .exe file.
### 8. Copying any Data Files ###
When debugging GDK games, there is no way to specify a working directory. Therefore, any required game data must also be copied into the output directory, likely in a post-build step.
### 9. Build and Run from Visual Studio ###
At this point, you should be able to build and run your game from the Visual Studio Debugger. If you get any linker errors, make sure you double-check that you referenced all the required libs.
If you are testing Xbox Live functionality, it's likely you will need to change to the Sandbox for your title. To do this:
1. Run "Desktop VS 2022 Gaming Command Prompt" from the Start Menu
2. Switch the sandbox name with:
`XblPCSandbox SANDBOX.#`
3. (To switch back to the retail sandbox):
`XblPCSandbox RETAIL`
### 10. Packaging and Installing Locally
You can use one of the test program's `PackageLayout.xml` as a starting point. Minimally, you will need to change the exe to the correct name and also reference any required game data. As with the other data files, it's easiest if you have this copy to the output directory, although it's not a requirement as you can specify relative paths to files.
To create the package:
1. Run "Desktop VS 2022 Gaming Command Prompt" from the Start Menu
2. `cd` to the directory containing the `PackageLayout.xml` with the correct paths (if you use the local path as in the sample package layout, this would be from your .exe output directory)
3. `mkdir Package` to create an output directory
4. To package the file into the `Package` directory, use:
`makepkg pack /f PackageLayout.xml /lt /d . /nogameos /pc /pd Package`
5. To install the package, use:
`wdapp install PACKAGENAME.msixvc`
6. Once the package is installed, you can run it from the start menu.
7. As with when running from Visual Studio, if you need to test any Xbox Live functionality you must switch to the correct sandbox.
Troubleshooting
---------------
#### Xbox Live Login does not work
As of June 2022 GDK, you must have a valid Title Id and MSAAppId in order to test Xbox Live functionality such as user login. Make sure these are set correctly in the `MicrosoftGame.config`. This means that even testgdk will not let you login without setting these properties to valid values.
Furthermore, confirm that your PC is set to the correct sandbox.
#### "The current user has already installed an unpackaged version of this app. A packaged version cannot replace this." error when installing
Prior to June 2022 GDK, running from the Visual Studio debugger would still locally register the app (and it would appear on the start menu). To fix this, you have to uninstall it (it's simplest to right click on it from the start menu to uninstall it).

38
Engine/lib/sdl/docs/README-ios.md
View file

@ -1,10 +1,10 @@
iOS
======
Building the Simple DirectMedia Layer for iOS 5.1+
Building the Simple DirectMedia Layer for iOS 9.0+
==============================================================================
Requirements: Mac OS X 10.8 or later and the iOS 7+ SDK.
Requirements: Mac OS X 10.9 or later and the iOS 9.0 or newer SDK.
Instructions:
@ -191,6 +191,38 @@ 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 SDL2.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 SDL2.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. This means that iOS apps which used the statically-linked libSDL2.lib and now link with the xcframwork will need to define their own main() to call SDL_UIKitRunApp(), like this:
#ifndef SDL_MAIN_HANDLED
#ifdef main
#undef main
#endif
int
main(int argc, char *argv[])
{
return SDL_UIKitRunApp(argc, argv, SDL_main);
}
#endif /* !SDL_MAIN_HANDLED */
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
==============================================================================
@ -261,7 +293,7 @@ e.g.
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 6.1
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
In order to do that you need to download an older version of Xcode:
https://developer.apple.com/download/more/?name=Xcode

17
Engine/lib/sdl/docs/README-linux.md
View file

@ -12,15 +12,16 @@ default configuration parameters.
Build Dependencies
--------------------------------------------------------------------------------
Ubuntu 20.04, all available features enabled:
Ubuntu 18.04, all available features enabled:
sudo apt-get install build-essential git make cmake autoconf automake \
libtool pkg-config libasound2-dev libpulse-dev libaudio-dev libjack-dev \
libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxfixes-dev libxi-dev \
libxss-dev libgl1-mesa-dev libdbus-1-dev \
libudev-dev libgles2-mesa-dev libegl1-mesa-dev libibus-1.0-dev \
fcitx-libs-dev libsamplerate0-dev libsndio-dev libwayland-dev \
libxkbcommon-dev libdrm-dev libgbm-dev
sudo apt-get install build-essential git make autoconf automake libtool \
pkg-config cmake ninja-build gnome-desktop-testing libasound2-dev libpulse-dev \
libaudio-dev libjack-dev libsndio-dev libsamplerate0-dev libx11-dev libxext-dev \
libxrandr-dev libxcursor-dev libxfixes-dev libxi-dev libxss-dev libwayland-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
Ubuntu 22.04+ can also add `libpipewire-0.3-dev libdecor-0-dev` to that command line.
Fedora 35, all available features enabled:

6
Engine/lib/sdl/docs/README-macos.md
View file

@ -43,13 +43,13 @@ make
sudo make install
```
This script builds SDL with 10.7 ABI compatibility on 64-bit Intel and 11.0
This script builds SDL with 10.9 ABI compatibility on 64-bit Intel and 11.0
ABI compatibility on ARM64 architectures. For best compatibility you
should compile your application the same way.
Please note that building SDL requires at least Xcode 4.6 and the 10.7 SDK.
Please note that building SDL requires at least Xcode 6 and the 10.9 SDK.
PowerPC support for macOS has been officially dropped as of SDL 2.0.2.
32-bit Intel and macOS 10.6 runtime support has been officially dropped as
32-bit Intel and macOS 10.8 runtime support has been officially dropped as
of SDL 2.24.0.
To use the library once it's built, you essential have two possibilities:

27
Engine/lib/sdl/docs/README-n3ds.md Normal file
View file

@ -0,0 +1,27 @@
# Nintendo 3DS
SDL port for the Nintendo 3DS [Homebrew toolchain](https://devkitpro.org/) contributed by:
- [Pierre Wendling](https://github.com/FtZPetruska)
Credits to:
- The awesome people who ported SDL to other homebrew platforms.
- The Devkitpro team for making all the tools necessary to achieve this.
## Building
To build for the Nintendo 3DS, make sure you have devkitARM and cmake installed and run:
```bash
cmake -S. -Bbuild -DCMAKE_TOOLCHAIN_FILE="$DEVKITPRO/cmake/3DS.cmake" -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build
```
## Notes
- Currently only software rendering is supported.
- SDL2main should be used to ensure ROMFS is enabled.
- By default, the extra L2 cache and higher clock speeds of the New 2/3DS lineup are enabled. If you wish to turn it off, use `osSetSpeedupEnable(false)` in your main function.
- `SDL_GetBasePath` returns the romfs root instead of the executable's directory.

51
Engine/lib/sdl/docs/README-ps2.md Normal file
View file

@ -0,0 +1,51 @@
PS2
======
SDL2 port for the Sony Playstation 2 contributed by:
- Francisco Javier Trujillo Mata
Credit to
- The guys that ported SDL to PSP & Vita because I'm taking them as reference.
- David G. F. for helping me with several issues and tests.
## Building
To build SDL2 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
cmake --build build
cmake --install build
```
## Hints
The PS2 port has a special Hint for having a dynamic VSYNC. The Hint is `SDL_HINT_PS2_DYNAMIC_VSYNC`.
If you enabled the dynamic vsync having as well `SDL_RENDERER_PRESENTVSYNC` enabled, then if the app is not able to run at 60 FPS, automatically the `vsync` will be disabled having a better performance, instead of droping FPS to 30.
## 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 conection with your computer.
So to avoid the reset of the IOP CPU, you need to call to the macro `SDL_PS2_SKIP_IOP_RESET();`.
It could be something similar as:
```c
.....
SDL_PS2_SKIP_IOP_RESET();
int main(int argc, char *argv[])
{
.....
```
For a release binary is recommendable to reset the IOP always.
Remember to do a clean compilation everytime you enable or disable the `SDL_PS2_SKIP_IOP_RESET` otherwise the change won't be reflected.
## Getting PS2 Dev
[Installing PS2 Dev](https://github.com/ps2dev/ps2dev)
## Running on PCSX2 Emulator
[PCSX2](https://github.com/PCSX2/pcsx2)
[More PCSX2 information](https://pcsx2.net/)
## To Do
- PS2 Screen Keyboard
- Dialogs
- Others

47
Engine/lib/sdl/docs/README-winrt.md
View file

@ -5,47 +5,21 @@ This port allows SDL applications to run on Microsoft's platforms that require
use of "Windows Runtime", aka. "WinRT", APIs. Microsoft may, in some cases,
refer to them as either "Windows Store", or for Windows 10, "UWP" apps.
Some of the operating systems that include WinRT, are:
* Windows 10, via its Universal Windows Platform (UWP) APIs
* Windows 8.x
* Windows RT 8.x (aka. Windows 8.x for ARM processors)
* Windows Phone 8.x
In the past, SDL has supported Windows RT 8.x, Windows Phone, etc, but in
modern times this port is focused on UWP apps, which run on Windows 10,
and modern Xbox consoles.
Requirements
------------
* Microsoft Visual C++ (aka Visual Studio), either 2017, 2015, 2013, or 2012
* Microsoft Visual C++ (aka Visual Studio) 2019.
- Free, "Community" or "Express" editions may be used, so long as they
include support for either "Windows Store" or "Windows Phone" apps.
include support for either "Windows Store" or "Windows Phone" apps.
"Express" versions marked as supporting "Windows Desktop" development
typically do not include support for creating WinRT apps, to note.
(The "Community" editions of Visual C++ do, however, support both
desktop/Win32 and WinRT development).
- Visual Studio 2017 can be used, however it is recommended that you install
the Visual C++ 2015 build tools. These build tools can be installed
using VS 2017's installer. Be sure to also install the workload for
"Universal Windows Platform development", its optional component, the
"C++ Universal Windows Platform tools", and for UWP / Windows 10
development, the "Windows 10 SDK (10.0.10240.0)". Please note that
targeting UWP / Windows 10 apps from development machine(s) running
earlier versions of Windows, such as Windows 7, is not always supported
by Visual Studio, and you may get error(s) when attempting to do so.
- Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
or Windows Phone. 8.0-targeted apps will run on devices running 8.1
editions of Windows, however they will not be able to take advantage of
8.1-specific features.
- Visual C++ 2013 cannot create app projects that target Windows 8.0.
Visual C++ 2013 Update 4, can create app projects for Windows Phone 8.0,
Windows Phone 8.1, and Windows 8.1, but not Windows 8.0. An optional
Visual Studio add-in, "Tools for Maintaining Store apps for Windows 8",
allows Visual C++ 2013 to load and build Windows 8.0 projects that were
created with Visual C++ 2012, so long as Visual C++ 2012 is installed
on the same machine. More details on targeting different versions of
Windows can found at the following web pages:
- [Develop apps by using Visual Studio 2013](http://msdn.microsoft.com/en-us/library/windows/apps/br211384.aspx)
- [To add the Tools for Maintaining Store apps for Windows 8](http://msdn.microsoft.com/en-us/library/windows/apps/dn263114.aspx#AddMaintenanceTools)
* A valid Microsoft account - This requirement is not imposed by SDL, but
rather by Microsoft's Visual C++ toolchain. This is required to launch or
debug apps.
@ -57,7 +31,7 @@ Status
Here is a rough list of what works, and what doesn't:
* What works:
* compilation via Visual C++ 2012 through 2015
* compilation via Visual C++ 2019.
* compile-time platform detection for SDL programs. The C/C++ #define,
`__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
* GPU-accelerated 2D rendering, via SDL_Renderer.
@ -234,13 +208,8 @@ To set this up for SDL/WinRT, you'll need to run through the following steps:
"Solution Explorer")
2. right click on your app's solution.
3. navigate to "Add", then to "Existing Project..."
4. find SDL/WinRT's Visual C++ project file and open it. Different project
files exist for different WinRT platforms. All of them are in SDL's
source distribution, in the following directories:
* `VisualC-WinRT/UWP_VS2015/` - for Windows 10 / UWP apps
* `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
* `VisualC-WinRT/WinRT80_VS2012/` - for Windows 8.0 apps
* `VisualC-WinRT/WinRT81_VS2013/` - for Windows 8.1 apps
4. find SDL/WinRT's Visual C++ project file and open it, in the `VisualC-WinRT`
directory.
5. once the project has been added, right-click on your app's project and
select, "References..."
6. click on the button titled, "Add New Reference..."

12
Engine/lib/sdl/docs/README.md
View file

@ -1,12 +1,6 @@
Simple DirectMedia Layer {#mainpage}
========================
# Simple DirectMedia Layer
(SDL)
Version 2.0
---
http://www.libsdl.org/
https://www.libsdl.org/
Simple DirectMedia Layer is a cross-platform development library designed
to provide low level access to audio, keyboard, mouse, joystick, and graphics
@ -34,6 +28,7 @@ More documentation and FAQs are available online at [the wiki](http://wiki.libsd
- [DirectFB](README-directfb.md)
- [DynAPI](README-dynapi.md)
- [Emscripten](README-emscripten.md)
- [GDK](README-gdk.md)
- [Gesture](README-gesture.md)
- [Git](README-git.md)
- [iOS](README-ios.md)
@ -45,6 +40,7 @@ More documentation and FAQs are available online at [the wiki](http://wiki.libsd
- [Supported Platforms](README-platforms.md)
- [Porting information](README-porting.md)
- [PSP](README-psp.md)
- [PS2](README-ps2.md)
- [Raspberry Pi](README-raspberrypi.md)
- [Touch](README-touch.md)
- [Versions](README-versions.md)

72
Engine/lib/sdl/docs/release_checklist.md
View file

@ -1,36 +1,23 @@
# Release checklist
When changing the version, run `build-scripts/update-version.sh X Y Z`,
where `X Y Z` are the major version, minor version, and patch level. So
`2 28 1` means "change the version to 2.28.1". This script does much of the
mechanical work.
## New feature release
* Update `WhatsNew.txt`
* Bump version number to 2.EVEN.0 in all these locations:
* Bump version number to 2.EVEN.0:
* `configure.ac`, `CMakeLists.txt`: `SDL_*_VERSION`
* `Xcode/SDL/Info-Framework.plist`: `CFBundleShortVersionString`,
`CFBundleVersion`
* `Makefile.os2`: `VERSION`
* `build-scripts/winrtbuild.ps1`: `$SDLVersion`
* `include/SDL_version.h`: `SDL_*_VERSION`, `SDL_PATCHLEVEL`
* `src/main/windows/version.rc`: `FILEVERSION`, `PRODUCTVERSION`,
`FileVersion`, `ProductVersion`
* Bump ABI version information
* `CMakeLists.txt`, `Xcode/SDL/SDL.xcodeproj/project.pbxproj`:
`DYLIB_CURRENT_VERSION`, `DYLIB_COMPATIBILITY_VERSION`
* set first number in `DYLIB_CURRENT_VERSION` to
(100 * *minor*) + 1
* set second number in `DYLIB_CURRENT_VERSION` to 0
* if backwards compatibility has been broken,
increase `DYLIB_COMPATIBILITY_VERSION` (?)
* Run test/versioning.sh to verify that everything is consistent
* Regenerate `configure`
* `./build-scripts/update-version.sh 2 EVEN 0`
* Do the release
* Update the website file include/header.inc.php to reflect the new version
## New bugfix release
* Check that no new API/ABI was added
@ -39,53 +26,24 @@
* Bump version number from 2.Y.Z to 2.Y.(Z+1) (Y is even)
* Same places as listed above
* Bump ABI version information
* `CMakeLists.txt`, `Xcode/SDL/SDL.xcodeproj/project.pbxproj`:
`DYLIB_CURRENT_VERSION`, `DYLIB_COMPATIBILITY_VERSION`
* set second number in `DYLIB_CURRENT_VERSION` to *patchlevel*
* Run test/versioning.sh to verify that everything is consistent
* Regenerate `configure`
* `./build-scripts/update-version.sh 2 Y Z+1`
* Do the release
* Update the website file include/header.inc.php to reflect the new version
## After a feature release
* Create a branch like `release-2.24.x`
* Bump version number to 2.ODD.0 for next development branch
* Same places as listed above
* Bump ABI version information
* Same places as listed above
* Assume that the next feature release will contain new API/ABI
* Run test/versioning.sh to verify that everything is consistent
* `./build-scripts/update-version.sh 2 ODD 0`
## New development prerelease
* Bump version number from 2.Y.Z to 2.Y.(Z+1) (Y is odd)
* Same places as listed above
* Bump ABI version information
* `CMakeLists.txt`, `Xcode/SDL/SDL.xcodeproj/project.pbxproj`:
`DYLIB_CURRENT_VERSION`, `DYLIB_COMPATIBILITY_VERSION`
* set first number in `DYLIB_CURRENT_VERSION` to
(100 * *minor*) + *patchlevel* + 1
* set second number in `DYLIB_CURRENT_VERSION` to 0
* if backwards compatibility has been broken,
increase `DYLIB_COMPATIBILITY_VERSION` (?)
* Run test/versioning.sh to verify that everything is consistent
* Regenerate `configure`
* `./build-scripts/update-version.sh 2 Y Z+1`
* Do the release