======================
sdl2-compat for Debian
======================

sdl2-compat is a compatible reimplementation of the SDL 2 interface
using SDL 3. It has now replaced "classic" SDL2, similar to what was
previously done in other OS distributions like Arch and Fedora.

sdl2-compat can be combined with sdl12-compat (the `libsdl1.2debian`
package) to run SDL 1.2 games on SDL 3, but if possible please port those
games to SDL 2 or SDL 3 instead.

Installation and use
====================

sdl2-compat has now taken over the libsdl2-2.0-0 package name from
"classic" SDL 2 and will be installed by default as a dependency of
SDL 2 games.

Please do not depend on the transitional packages libsdl2-compat or
libsdl2-compat-shim, which will be removed later.

If a game exhibits regressions with sdl2-compat, it can be forced to
use "classic" SDL 2 by installing the libsdl2-classic package, and then
using a command like:

    $ SDL_DYNAMIC_API='/usr/$LIB/sdl2-classic/libSDL2-2.0.so.0' \
      openarena

If there are regressions with sdl2-compat which can be worked around by
using "classic" SDL 2, please report that as a bug in the sdl2-compat
source package: see "Testing and reporting bugs", below.

Checking which SDL you are using
--------------------------------

If the environment variable SDL2COMPAT_DEBUG_LOGGING is set to 1,
like this:

    $ SDL_DYNAMIC_API='/usr/$LIB/sdl2-classic/libSDL2-2.0.so.0' \
      openarena

    $ SDL2COMPAT_DEBUG_LOGGING=1 \
      SDL_DYNAMIC_API='/usr/$LIB/sdl2-classic/libSDL2-2.0.so.0' \
      openarena

then you should see output like this for sdl2-compat:

    sdl2-compat 2.32.57, built on Sep 10 2025 at 12:31:43, talking to SDL3 3.3.0
    sdl2-compat: This app appears to be named: ioquake3
    SDL_DYNAMIC_API: Not overridden

or like this for "classic" SDL 2:

    sdl2-compat 2.32.57, built on Sep 10 2025 at 12:31:43, talking to SDL3 3.3.0
    sdl2-compat: This app appears to be named: ioquake3
    SDL_DYNAMIC_API: Library replaced by SDL 2.32.10 (SDL-release-2.32.10-0-g5d2495703 (Debian 2.32.10+dfsg-3))

Wayland
=======

On Wayland, some SDL 2 games don't work correctly with the native Wayland
video driver, which became the default in SDL 3.

Please report this to the game's developer or packager as a bug. If a game
only supports X11 and does not support native Wayland, an easy way that a game
developer can signal this to SDL is with code similar to this near the
beginning of main(), before calling SDL_Init():

    #ifdef SDL_VIDEO_DRIVER_X11
    SDL_SetHintWithPriority(SDL_HINT_VIDEODRIVER, "x11", SDL_HINT_OVERRIDE);
    #endif

As a workaround for this bug you can set environment variable
SDL_VIDEODRIVER=x11, which forces all SDL 2 games to use X11 (possibly
via Xwayland).

sdl2-compat has a table of "quirks" for games and apps that cannot
easily be fixed, which can be applied automatically based on the name of
the executable. One of the most common quirks is to do the equivalent of
`SDL_VIDEODRIVER=x11` automatically.
If a game that cannot easily be fixed (for example a proprietary game)
needs this workaround, please report this as a bug in sdl2-compat:

* upstream: https://github.com/libsdl-org/sdl2-compat/issues/new
* and/or in Debian: as bugs in `src:sdl2-compat`

so that the game can be added to the table of quirks.

Testing and reporting bugs
==========================

Please report bugs for any regressions when compared with "classic" SDL2:

* upstream: https://github.com/libsdl-org/sdl2-compat/issues/new
* and/or in Debian: as bugs in `src:sdl2-compat`, or as bugs in the game
    with an "affects" on `src:sdl2-compat` if it appears to be a game bug

Please provide details of the game version, the sdl2-compat version,
and the SDL3 version. SDL2COMPAT_DEBUG_LOGGING=1 will tell you everything
except the game version.

If you are using a Wayland environment, please specify which one.
"Wayland" is not enough information: we'll need something more like
"GNOME Shell 48.4" or "sway 1.11".

If a game doesn't work in native Wayland, please try it with
`SDL_VIDEODRIVER=x11` as a workaround, and mention in your bug report
whether that workaround helped or not.

There will often be a newer version of SDL3 and/or sdl2-compat available
in experimental, which might have additional bug fixes. If you can,
trying that version is also helpful. Versions in experimental are often
upstream snapshots that have only been lightly tested, so there might be
regressions - please report those too!

See `HOW_TO_TEST_GAMES.md` in the source package for more details.

Compiling games
===============

sdl2-compat has now taken over the libsdl2-dev package name from
"classic" SDL 2 and will be installed by default as a build-dependency of
SDL 2 games.

Please do not build-depend on the transitional package libsdl2-compat-dev,
which will be removed later.