From 35a361465a2fdbd689c3798b731fe62ddd63ec19 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 22 Nov 2022 15:35:12 -0500
Subject: [PATCH] Added some text files from sdl12-compat, edited for
sdl2-compat.
---
BUGS.md | 20 +++
COMPATIBILITY.md | 9 ++
HOW_TO_TEST_GAMES.md | 176 ++++++++++++++++++++++++
LICENSE.txt | 18 +++
README.md | 311 +++++++++++++++++++++++++++++++++++++++++++
5 files changed, 534 insertions(+)
create mode 100644 BUGS.md
create mode 100644 COMPATIBILITY.md
create mode 100644 HOW_TO_TEST_GAMES.md
create mode 100644 LICENSE.txt
create mode 100644 README.md
diff --git a/BUGS.md b/BUGS.md
new file mode 100644
index 0000000..fea7d57
--- /dev/null
+++ b/BUGS.md
@@ -0,0 +1,20 @@
+
+# Reporting bugs
+
+Bugs are now managed in sdl2-compat's GitHub Issues tracker:
+
+https://github.com/libsdl-org/sdl2-compat/issues
+
+You may report bugs there, and search to see if a given issue has already
+been reported, discussed, and maybe even fixed.
+
+
+# Discussion with other humans
+
+You may also find help at the SDL forums:
+
+https://discourse.libsdl.org/
+
+Bug reports are welcome here, but we really appreciate if you use the bug
+tracker, as bugs discussed on the forums may be forgotten or missed.
+
diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md
new file mode 100644
index 0000000..2a50c42
--- /dev/null
+++ b/COMPATIBILITY.md
@@ -0,0 +1,9 @@
+# Compatibility notes
+
+This is a list of quirks and known-issues for specific games, with possible
+workarounds.
+
+## Nothing yet.
+
+Come back later and there might be more notes here.
+
diff --git a/HOW_TO_TEST_GAMES.md b/HOW_TO_TEST_GAMES.md
new file mode 100644
index 0000000..15d31cb
--- /dev/null
+++ b/HOW_TO_TEST_GAMES.md
@@ -0,0 +1,176 @@
+# Testing games with sdl2-compat
+
+sdl2-compat is here to make sure older games not only work well, but work
+_correctly_, and for that, we need an army of testers.
+
+Here's how to test games with sdl2-compat.
+
+
+## The general idea
+
+- Build [SDL3](https://github.com/libsdl-org/SDL) or find a prebuilt binary.
+- Build sdl2-compat (documentation is in README.md)
+- Find a game to test.
+- Make sure a game uses sdl2-compat instead of classic SDL2.
+- See if game works or blows up, report back.
+
+
+## Find a game to test
+
+Unlike SDL 1.2, where we didn't build the compatibility layer until almost
+a decade in and most major projects had already migrated, there are _tons_
+of SDL2 games at the time of this writing; almost any Linux game on Steam
+in 2022 is using SDL2, not to mention almost any game that is in a Linux
+distribution's package manager, etc.
+
+As such, while we kept a spreadsheet for known SDL 1.2 titles, we don't
+have an authoritative source of them for SDL2, but they're everywhere
+you look!
+
+
+## Make sure the game works with real SDL2 first!
+
+You'd be surprised how quickly games can bitrot! If it doesn't work with
+real SDL2 anymore, it's not a bug if sdl12-compat doesn't work either.
+
+
+## Force it to use sdl2-compat instead.
+
+Either overwrite the copy of SDL2 that the game uses with sdl2-compat,
+or (on Linux) export LD_LIBRARY_PATH to point to your copy, so the system will
+favor it when loading libraries.
+
+SDL2 has something called the "Dynamic API" which is some magic inside of
+SDL2 itself: you can override the build of SDL2 in use, even if SDL2 is
+statically linked to the app!
+
+Just export the environment variable SDL_DYNAMIC_API with the path of your
+sdl2-compat library, and it will use sdl2-compat! No LD_LIBRARY_PATH
+needed!
+
+
+## Watch out for setuid/setgid binaries!
+
+On Linux, if you're testing a binary that's setgid to a "games" group (which
+we ran into several times with Debian packages), or setuid root or whatever,
+then the system will ignore the LD_LIBRARY_PATH variable, as a security
+measure. SDL_DYNAMIC_API is not affected by this.
+
+The reason some games are packaged like this is usually because they want to
+write to a high score list in a global, shared directory. Often times the
+games will just carry on if they fail to do so.
+
+There are several ways to bypass this:
+
+- Use SDL_DYNAMIC_API instead.
+- On some distros, you can run `ld.so` directly:
+ ```bash
+ LD_LIBRARY_PATH=/where/i/can/find/sdl2-compat ld.so /usr/games/mygame
+ ```
+- You can remove the setgid bit:
+ ```bash
+ # (it's `u-s` for the setuid bit)
+ sudo chmod g-s /usr/games/mygame
+ ```
+- You can install sdl2-compat system-wide, so the game uses that
+ instead of SDL2 by default.
+- If you don't have root access at all, you can try to copy the game
+ somewhere else or install a personal copy, or build from source code,
+ but these are drastic measures.
+
+Definitely read the next section ("Am I actually running sdl2-compat?") in
+these scenarios to make sure you ended up with the right library!
+
+## Am I actually running sdl2-compat?
+
+The easiest way to know is to set some environment variables:
+
+```bash
+export SDL2COMPAT_DEBUG_LOGGING=1
+```
+
+If this is set, when loading sdl2-compat, it'll write something like this
+to stderr (on Linux and Mac, at least)...
+
+```
+INFO: sdl2-compat, built on Sep 2 2022 at 11:27:37, talking to SDL3 3.2.0
+```
+
+
+## Steam
+
+If testing a Steam game, you'll want to launch the game outside of the Steam
+Client, so that Steam doesn't overwrite files you replaced and so you can
+easily control environment variables.
+
+Since you'll be using the Steam Runtime, you don't have to find your own copy
+of SDL3, as Steam provides it (!!! FIXME: note to the future: SDL3 is still
+in development at the time of this writing, so Steam doesn't provide it _yet_).
+
+On Linux, Steam stores games in ~/.local/share/Steam/steamapps/common, each
+in its own usually-well-named subdirectory.
+
+You'll want to add a file named "steam_appid.txt" to the same directory as
+the binary, which will encourage Steamworks to _not_ terminate the process
+and have the Steam Client relaunch it. This file should just have the appid
+for the game in question, which you can find from the store page.
+
+For example, the store page for Braid is:
+
+https://store.steampowered.com/app/26800/Braid/
+
+See that `26800`? That's the appid.
+
+```bash
+echo 26800 > steam_appid.txt
+```
+
+For Linux, you can make sure that, from the command line, the game still
+runs with the Steam Runtime and has the Steam Overlay by launching it with a
+little script:
+
+- [steamapp32](https://raw.githubusercontent.com/icculus/twisty-little-utilities/main/steamapp32) for x86 binaries.
+- [steamapp64](https://raw.githubusercontent.com/icculus/twisty-little-utilities/main/steamapp64) for x86-64 binaries.
+
+(And make sure you have a 32-bit or 64-bit build of sdl2-compat!)
+
+And then make sure you force it to use _your_ sdl2-compat instead of the
+system/Steam Runtime build:
+
+```bash
+export LD_LIBRARY_PATH=/where/i/installed/sdl12-compat
+```
+
+Putting this all together, you might run [Portal](https://store.steampowered.com/app/400/)
+like this:
+
+```bash
+cd ~/.local/share/Steam/steamapps/common/Portal
+export LD_LIBRARY_PATH=/where/i/installed/sdl2-compat
+export SDL2COMPAT_DEBUG_LOGGING=1
+echo 400 > steam_appid.txt
+steamapp64 ./portal
+```
+
+
+## Windows
+
+Generally, Windows games just ship with an SDL2.dll, and you just need to
+overwrite it with an sdl2-compat build, then run as usual.
+
+
+## macOS, etc.
+
+(write me.)
+
+Most of the Linux advice applies, but you might have to replace the SDL2
+in a framework.
+
+
+## Questions?
+
+If something isn't clear, make a note [here](https://github.com/libsdl-org/sdl2-compat/issues/new)
+and we'll update this document.
+
+Thanks!
+
diff --git a/LICENSE.txt b/LICENSE.txt
new file mode 100644
index 0000000..7854bee
--- /dev/null
+++ b/LICENSE.txt
@@ -0,0 +1,18 @@
+Copyright (C) 2022 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, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+ claim that you wrote the original software. If you use this software
+ in a product, an acknowledgment in the product documentation would be
+ appreciated but is not required.
+2. Altered source versions must be plainly marked as such, and must not be
+ misrepresented as being the original software.
+3. This notice may not be removed or altered from any source distribution.
+
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6048ce0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,311 @@
+# Simple DirectMedia Layer (SDL) sdl2-compat
+
+https://www.libsdl.org/
+
+This is the Simple DirectMedia Layer, a general API that provides low
+level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL,
+and 2D framebuffer across multiple platforms.
+
+This code is a compatibility layer; it provides a binary and source
+compatible API for programs written against SDL2, but it uses SDL3
+behind the scenes. If you are writing new code, please target SDL3
+directly and do not use this layer.
+
+If you absolutely must have the real SDL2 ("SDL 2 Classic"), please use
+the `SDL2` branch at https://github.com/libsdl-org/SDL, which occasionally
+gets bug fixes (and eventually, no new formal releases). But we strongly
+encourage you not to do that.
+
+# How to use:
+
+- Build the library. This will need access to SDL3's headers,
+[CMake](https://cmake.org/) and the build tools of your choice. Once built, you
+will have a drop-in replacement that can be used with any existing binary
+that relies on SDL2. You can copy this library over the existing SDL2 build,
+or force it to take priority over a system copy with LD_LIBRARY_PATH, etc.
+At runtime, sdl2-compat needs to be able to find a copy of SDL3, so plan to
+include it with the library if necessary.
+
+- If you want to build an SDL2 program from source code, we have included
+compatibility headers, so that sdl2-compat can completely replace SDL2
+at all points. These headers are just the bare minimum needed for source-level
+compatibility and don't have a lot of documentation or fanciness at all. The
+new headers are also under the zlib license. Note that sdl2-compat itself
+does not use these headers, so if you just want the library, you don't need
+them.
+
+# Building the library:
+
+These are quick-start instructions; there isn't anything out of the ordinary
+here if you're used to using CMake.
+
+You'll need to use CMake to build sdl12-compat. Download at
+[cmake.org](https://cmake.org/) or install from your package manager
+(`sudo apt-get install cmake` on Ubuntu, etc).
+
+Please refer to the [CMake documentation](https://cmake.org/documentation/)
+for complete details, as platform and build tool details vary.
+
+You'll need a copy of SDL3 to build sdl12-compat, because we need the
+SDL3 headers. You can build this from source or install from a package
+manager. Windows and Mac users can download prebuilt binaries from
+[SDL's download page](https://libsdl.org/download-3.0.php); make sure you
+get the "development libraries" and not "runtime binaries" there.
+
+Linux users might need some packages from their Linux distribution. On Ubuntu,
+you might need to do (!!! FIXME: this won't work until SDL3 is further in
+development!) ...
+
+```bash
+sudo apt-get install build-essential cmake libsdl3-3.0-0 libsdl3-dev libgl-dev
+```
+
+Now just point CMake at sdl2-compat's directory. Here's a command-line
+example:
+
+```bash
+cd sdl2-compat
+cmake -Bbuild -DCMAKE_BUILD_TYPE=Release .
+cmake --build build
+```
+
+On Windows or macOS, you might prefer to use CMake's GUI, but it's the same
+idea: give it the directory where sdl12-compat is located, click "Configure,"
+choose your favorite compiler, then click "Generate." Now you have project
+files! Click "Open Project" to launch your development environment. Then you
+can build however you like with Visual Studio, Xcode, etc.
+
+If necessary, you might have to fill in the location of the SDL3 headers
+when using CMake. sdl2-compat does not need SDL3's library to _build_,
+just its headers (although it may complain about the missing library,
+you can ignore that). From the command line, add
+`-DSDL3_INCLUDE_DIR=/path/to/SDL3/include`, or find this in the CMake
+GUI and set it appropriately, click "Configure" again, and then "Generate."
+
+When the build is complete, you'll have a shared library you can drop in
+as a replacement for an existing SDL2 build. This will also build
+the original SDL2 test apps, so you can verify the library is working.
+
+
+# Building for older CPU architectures on Linux:
+
+There are a lot of binaries from many years ago that used SDL2, which is
+to say they are for CPU architectures that are likely not your current
+system's.
+
+If you want to build a 32-bit x86 library on an x86-64 Linux machine, for
+compatibility with older games, you should install some basic 32-bit
+development libraries for your distribution. On Ubuntu, this would be:
+
+(!!! FIXME: this won't work until SDL3 is further in
+development!)
+
+```bash
+sudo apt-get install gcc-multilib libsdl3-dev:i386
+```
+
+...and then add `-m32` to your build options:
+
+
+```bash
+cd sdl2-compat
+cmake -Bbuild32 -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_FLAGS=-m32
+cmake --build build32
+```
+
+
+# Building for older CPU architectures on macOS:
+
+macOS users can try adding `-DCMAKE_OSX_ARCHITECTURES='arm64;x86_64'` instead
+of `-DCMAKE_C_FLAGS=-m32` to make a Universal Binary for both 64-bit Intel and
+Apple Silicon machines. If you have an older (or much older!) version of Xcode,
+you can try to build with "i386" or maybe even "powerpc" for 32-bit Intel or
+PowerPC systems, but Xcode (and macOS itself) has not supported either of
+these for quite some time, and you will likely struggle to get SDL2 to compile
+here in small ways, as well...but with some effort, it's maybe _possible_ to
+run SDL2 and sdl12-compat on Apple's abandoned architectures.
+
+
+# Building for older CPU architectures on Windows:
+
+Windows users just select a 32-bit version of Visual Studio when running
+CMake, when it asks you what compiler to target in the CMake GUI.
+
+
+# Configuration options:
+
+sdl12-compat has a number of configuration options which can be used to work
+around issues with individual applications, or to better fit your system or
+preferences.
+
+These options are all specified as environment variables, and can be set by
+running your application with them set on the command-line, for example:
+```
+SDL12COMPAT_HIGHDPI=1 SDL12COMPAT_OPENGL_SCALING=0 %command%
+```
+will run `%command%` with high-dpi monitor support enabled, but OpenGL
+scaling support disabled.
+
+(While these environment variables are checked at various times throughout
+the lifetime of the app, sdl12-compat expects these to be set before the
+process starts and not change during the life of the process, and any
+places where changing it later might affect operation is purely accidental
+and might change. That is to say: don't write an SDL 1.2-based app with
+plans to tweak these values on the fly!)
+
+The available options are:
+
+- SDL12COMPAT_DEBUG_LOGGING: (checked at startup)
+ If enabled, print debugging messages to stderr. These messages are
+ mostly useful to developers, or when trying to track down a specific
+ bug.
+
+- SDL12COMPAT_FAKE_CDROM_PATH: (checked during SDL_Init)
+ A path to a directory containing MP3 files (named trackXX.mp3, where
+ XX is a two-digit track number) to be used by applications which play
+ CD audio. Using an absolute path is recommended: relative paths are
+ not guaranteed to work correctly.
+
+- SDL12COMPAT_OPENGL_SCALING: (checked during SDL_Init)
+ Enables scaling of OpenGL applications to the current desktop resolution.
+ If disabled, applications can change the real screen resolution. This
+ option is enabled by default, but not all applications are compatible
+ with it: try changing this if you can only see a black screen.
+
+- SDL12COMPAT_FIX_BORDERLESS_FS_WIN: (checked during SDL_SetVideoMode)
+ Enables turning borderless windows at the desktop resolution into actual
+ fullscreen windows (so they'll go into a separate space on macOS and
+ properly hide dock windows on other desktop environments, etc).
+ If disabled, applications may not get the full display to theirselves as
+ they expect. This option is enabled by default, but this option is here
+ so it can be manually disabled, in case this causes some negative result
+ we haven't anticipated.
+
+- SDL12COMPAT_SCALE_METHOD: (checked during SDL_Init)
+ Choose the scaling method used when applications render at a non-native
+ resolution. The options are `nearest`, for nearest-neighbour sampling
+ (more pixelated) and `linear` for bilinear sampling (blurrier).
+
+- SDL12COMPAT_HIGHDPI: (checked during SDL_SetVideoMode)
+ Advertise the application as supporting high-DPI displays. Enabling
+ this will usually result in sharper graphics, but on some applications
+ text and other elements may become very small.
+
+- SDL12COMPAT_SYNC_TO_VBLANK: (checked during SDL_SetVideoMode)
+ Force the application to sync (or not sync) to the vertical blanking
+ interval (VSync). When enabled, this will cap the application's
+ framerate to the screen's refresh rate (and may resolve issues with
+ screen tearing).
+
+- SDL12COMPAT_USE_KEYBOARD_LAYOUT: (checked during SDL_Init)
+ Make all keyboard input take the current keyboard layout into account.
+ This may need to be disabled for applications which provide their own
+ keyboard layout support, or if the position of the keys on the keyboard
+ is more important than the character they produce. Note that text input
+ (in most applications) will take the keyboard layout into account
+ regardless of this option.
+
+- SDL12COMPAT_USE_GAME_CONTROLLERS: (checked during SDL_Init)
+ Use SDL2's higher-level Game Controller API to expose joysticks instead of
+ its lower-level joystick API. The benefit of this is that you can exert
+ more control over arbitrary hardware (deadzones, button mapping, device
+ name, etc), and button and axes layouts are consistent (what is physically
+ located where an Xbox360's "A" button is will always be SDL 1.2 joystick
+ button 0, "B" will be 1, etc). The downside is it might not expose all of
+ a given piece of hardware's functionality, or simply not make sense in
+ general...if you need to use a flight stick, for example, you should not
+ use this hint. If there is no known game controller mapping for a joystick,
+ and this hint is in use, it will not be listed as an availble device.
+
+- SDL12COMPAT_WINDOW_SCALING: (checked during SDL_SetVideoMode)
+ When creating non-fullscreen, non-resizable windows, use this variable to
+ size the window differently. If, for example, you have a 4K monitor and the
+ game is running in a window the size of a postage stamp, you might set this
+ to 2 to double the size of the window. Fractional values work, so "1.5"
+ might be a more-pleasing value on your hardware. You can even shrink the
+ window with values less than 1.0! When scaling a window like this,
+ sdl12-compat will use all the usual scaling options
+ (SDL12COMPAT_OPENGL_SCALING, SDL12COMPAT_SCALE_METHOD, etc). If sdl12-compat
+ can't scale the contents of the window for various technical reasons, it
+ will create the window at the originally-requested size. If this variable
+ isn't specified, it defaults to 1.0 (no scaling).
+
+- SDL12COMPAT_MAX_VIDMODE: (checked during SDL_Init)
+ This is a string in the form of `WxH`, where `W` is the maximum width
+ and `H` is the maximum height (for example: `640x480`). The list of valid
+ resolutions that will be reported by SDL_ListModes and SDL_VideoModeOK will
+ not include any dimensions that are wider or taller than these sizes. A size
+ of zero will be ignored, so for `0x480` a resolution of 1920x480 would be
+ accepted). If not specified, or set to `0x0`, no resolution clamping is done.
+ This is for old software-rendered games that might always choose the largest
+ resolution offered, but never conceived of 4K displays. In these cases, it
+ might be better for them to use a smaller resolution and let sdl12-compat
+ scale their output up with the GPU.
+
+- SDL_MOUSE_RELATIVE_SCALING: (checked during SDL_SetVideoMode)
+ If enabled, relative mouse motion is scaled when the application is
+ running at a non-native resolution. This may be required with some
+ applications which use their own mouse cursors. See also:
+ https://wiki.libsdl.org/SDL_HINT_MOUSE_RELATIVE_SCALING
+
+- SDL12COMPAT_ALLOW_THREADED_DRAWS: (checked during SDL_Init)
+ Enabled by default.
+ If disabled, calls to `SDL_UpdateRects()` from non-main threads are
+ converted into requests for the main thread to carry out the update later.
+ The thread that called `SDL_SetVideoMode()` is treated as the main thread.
+
+- SDL12COMPAT_ALLOW_THREADED_PUMPS: (checked during SDL_Init)
+ Enabled by default.
+ If disabled, calls to `SDL_PumpEvents()` from non-main threads are
+ completely ignored.
+ The thread that called `SDL_SetVideoMode()` is treated as the main thread.
+
+- SDL12COMPAT_ALLOW_SYSWM: (checked during SDL_Init)
+ Enabled by default.
+ If disabled, SDL_SYSWMEVENT events will not be delivered to the app, and
+ SDL_GetWMInfo() will fail; this is useful if you have a program that
+ tries to access X11 directly through SDL's interfaces, but can survive
+ without it, becoming compatible with, for example, Wayland, or perhaps
+ just avoiding a bug in target-specific code. Note that sdl12-compat already
+ disallows SysWM things unless SDL2 is using its "windows" or "x11" video
+ backends, because SDL 1.2 didn't have wide support for its SysWM APIs
+ outside of Windows and X11 anyhow.
+
+
+# Compatibility issues with OpenGL scaling
+
+The OpenGL scaling feature of sdl12-compat allows applications which wish to
+run at a non-native screen resolution to do so without changing the system
+resolution. It does this by redirecting OpenGL rendering calls to a "fake"
+backbuffer which is scaled when rendering.
+
+This works well for simple applications, but for more complicated applications
+which use Frame Buffer Objects, sdl12-compat needs to intercept and redirect
+some OpenGL calls. Applications which access these functions without going
+though SDL (even if via a library) may not successfully render anything, or
+may render incorrectly if OpenGL scaling is enabled.
+
+In these cases, you can disable OpenGL scaling by setting the environment
+variable:
+```
+SDL12COMPAT_OPENGL_SCALING=0
+```
+
+# Compatibility issues with applications directly accessing underlying APIs
+
+Some applications combine the use of SDL with direct access to the underlying
+OS or window system. When running these applications on the same OS and SDL
+video driver (e.g. a program written for X11 on Linux is run on X11 on Linux),
+sdl12-compat is usually compatible.
+
+However, if you wish to run an application on a different video driver, the
+application will be unable to access the underlying API it is expecting, and
+may fail. This often occurs trying to run applications written for X11 under
+Wayland, and particularly affects a number of popular OpenGL extension loaders.
+
+In this case, the best workaround is to run under a compatibility layer like
+XWayland, and set the SDL_VIDEODRIVER environment variable to the driver the
+program is expecting:
+```
+SDL_VIDEODRIVER=x11
+```