{"id":28412336,"url":"https://github.com/libsdl-org/sdl2-compat","last_synced_at":"2026-03-09T13:05:12.719Z","repository":{"id":63862454,"uuid":"569413483","full_name":"libsdl-org/sdl2-compat","owner":"libsdl-org","description":"An SDL2 compatibility layer that uses SDL3 behind the scenes.","archived":false,"fork":false,"pushed_at":"2026-02-20T16:37:32.000Z","size":6036,"stargazers_count":179,"open_issues_count":13,"forks_count":47,"subscribers_count":12,"default_branch":"main","last_synced_at":"2026-02-20T21:07:13.831Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"zlib","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/libsdl-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-11-22T19:15:31.000Z","updated_at":"2026-02-20T16:37:37.000Z","dependencies_parsed_at":"2023-10-11T11:00:12.747Z","dependency_job_id":"6fdce75e-bb29-42ad-a521-f5d9092e13cb","html_url":"https://github.com/libsdl-org/sdl2-compat","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/libsdl-org/sdl2-compat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libsdl-org%2Fsdl2-compat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libsdl-org%2Fsdl2-compat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libsdl-org%2Fsdl2-compat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libsdl-org%2Fsdl2-compat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/libsdl-org","download_url":"https://codeload.github.com/libsdl-org/sdl2-compat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libsdl-org%2Fsdl2-compat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30297111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T11:12:22.024Z","status":"ssl_error","status_checked_at":"2026-03-09T11:10:54.577Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-02T20:46:38.103Z","updated_at":"2026-03-09T13:05:12.707Z","avatar_url":"https://github.com/libsdl-org.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simple DirectMedia Layer (SDL) sdl2-compat\n\nhttps://www.libsdl.org/\n\nThis is the Simple DirectMedia Layer, a general API that provides low\nlevel access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL,\nand 2D framebuffer across multiple platforms.\n\nThis code is a compatibility layer; it provides a binary and source\ncompatible API for programs written against SDL2, but it uses SDL3\nbehind the scenes. If you are writing new code, please target SDL3\ndirectly and do not use this layer.\n\nIf you absolutely must have the real SDL2 (\"SDL 2 Classic\"), please use\nthe `SDL2` branch at https://github.com/libsdl-org/SDL, which occasionally\ngets bug fixes (and eventually, no new formal releases). But we strongly\nencourage you not to do that.\n\n# How to use:\n\n- Build the library. This will need access to SDL3's headers,\n[CMake](https://cmake.org/) and the build tools of your choice. Once built, you\nwill have a drop-in replacement that can be used with any existing binary\nthat relies on SDL2. You can copy this library over the existing SDL2 build,\nor force it to take priority over a system copy with LD_LIBRARY_PATH, etc.\nAt runtime, sdl2-compat needs to be able to find a copy of SDL3, so plan to\ninclude it with the library if necessary.\n\n- If you want to build an SDL2 program from source code, we have included\ncompatibility headers, so that sdl2-compat can completely replace SDL2\nat all points. Note that sdl2-compat itself does not use these headers,\nso if you just want the library, you don't need them.\n\n# Building the library:\n\nThese are quick-start instructions; there isn't anything out of the ordinary\nhere if you're used to using CMake. \n\nYou'll need to use CMake to build sdl2-compat. Download at\n[cmake.org](https://cmake.org/) or install from your package manager\n(`sudo apt-get install cmake` on Ubuntu, etc).\n\nPlease refer to the [CMake documentation](https://cmake.org/documentation/)\nfor complete details, as platform and build tool details vary.\n\nYou'll need a copy of SDL3 to build sdl2-compat, because we need the\nSDL3 headers. You can build this from source or install from a package\nmanager. Windows and Mac users can download prebuilt binaries from\n[SDL's download page](https://libsdl.org/download-3.0.php); make sure you\nget the \"development libraries\" and not \"runtime binaries\" there.\n\nLinux users might need some packages from their Linux distribution. On Ubuntu,\nyou might need to do (!!! FIXME: this won't work until SDL3 is further in\ndevelopment!) ...\n\n```bash\nsudo apt-get install build-essential cmake libsdl3-dev libgl-dev\n```\n\nNow just point CMake at sdl2-compat's directory. Here's a command-line\nexample:\n\n```bash\ncd sdl2-compat\ncmake -Bbuild -DCMAKE_BUILD_TYPE=Release .\ncmake --build build\n```\n\nOn Windows or macOS, you might prefer to use CMake's GUI, but it's the same\nidea: give it the directory where sdl2-compat is located, click \"Configure,\"\nchoose your favorite compiler, then click \"Generate.\" Now you have project\nfiles! Click \"Open Project\" to launch your development environment. Then you\ncan build however you like with Visual Studio, Xcode, etc.\n\nIf necessary, you might have to fill in the location of the SDL3 headers\nwhen using CMake. sdl2-compat does not need SDL3's library to _build_,\njust its headers (although it may complain about the missing library,\nyou can ignore that). From the command line, add\n`-DSDL3_INCLUDE_DIRS=/path/to/SDL3/include`, or find this in the CMake\nGUI and set it appropriately, click \"Configure\" again, and then \"Generate.\"\n\nWhen the build is complete, you'll have a shared library you can drop in\nas a replacement for an existing SDL2 build. This will also build\nthe original SDL2 test apps, so you can verify the library is working.\n\n\n# Building for older CPU architectures on Linux:\n\nThere are a lot of binaries from many years ago that used SDL2, which is\nto say they are for CPU architectures that are likely not your current\nsystem's.\n\nIf you want to build a 32-bit x86 library on an x86-64 Linux machine, for\ncompatibility with older games, you should install some basic 32-bit\ndevelopment libraries for your distribution. On Ubuntu, this would be:\n\n(!!! FIXME: this won't work until SDL3 is further in\ndevelopment!) \n\n```bash\nsudo apt-get install gcc-multilib libsdl3-dev:i386\n```\n\n...and then add `-m32` to your build options:\n\n\n```bash\ncd sdl2-compat\ncmake -Bbuild32 -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_FLAGS=-m32\ncmake --build build32\n```\n\n\n# Building for older CPU architectures on macOS:\n\nmacOS users can try adding `-DCMAKE_OSX_ARCHITECTURES='arm64;x86_64'` instead\nof `-DCMAKE_C_FLAGS=-m32` to make a Universal Binary for both 64-bit Intel and\nApple Silicon machines.\n\n\n# Building for older CPU architectures on Windows:\n\nWindows users just select a 32-bit version of Visual Studio when running\nCMake, when it asks you what compiler to target in the CMake GUI.\n\n\n# Configuration options:\n\nsdl2-compat has a number of configuration options which can be used to work\naround issues with individual applications, or to better fit your system or\npreferences.\n\nThese options are all specified as environment variables, and can be set by\nrunning your application with them set on the command-line, for example:\n```\nSDL2COMPAT_DEBUG_LOGGING=1 SDL2COMPAT_ALLOW_SYSWM=0 %command%\n```\nwill run `%command%` with high-dpi monitor support enabled, but OpenGL\nscaling support disabled.\n\n(While these environment variables are checked at various times throughout\nthe lifetime of the app, sdl2-compat expects these to be set before the\nprocess starts and not change during the life of the process, and any\nplaces where changing it later might affect operation is purely accidental\nand might change. That is to say: don't write an SDL2-based app with\nplans to tweak these values on the fly!)\n\nThe available options are:\n\n- SDL2COMPAT_DEBUG_LOGGING: (checked at startup)\n  If enabled, print debugging messages to stderr.  These messages are\n  mostly useful to developers, or when trying to track down a specific\n  bug.\n\n- SDL2COMPAT_ALLOW_SYSWM: (checked during SDL_Init)\n  Enabled by default.\n  If disabled, SDL_SYSWMEVENT events will not be delivered to the app, and\n  SDL_GetWMInfo() will fail; this is useful if you have a program that\n  tries to access X11 directly through SDL's interfaces, but can survive\n  without it, becoming compatible with, for example, Wayland, or perhaps\n  just avoiding a bug in target-specific code.\n\n\n# Compatibility issues with applications directly accessing underlying APIs\n\nSome applications combine the use of SDL with direct access to the underlying\nOS or window system. When running these applications on the same OS and SDL\nvideo driver (e.g. a program written for X11 on Linux is run on X11 on Linux),\nsdl2-compat is usually compatible.\n\nHowever, if you wish to run an application on a different video driver, the\napplication will be unable to access the underlying API it is expecting, and\nmay fail. This often occurs trying to run applications written for X11 under\nWayland, and particularly affects a number of popular OpenGL extension loaders.\n\nIn this case, the best workaround is to run under a compatibility layer like\nXWayland, and set the SDL_VIDEODRIVER environment variable to the driver the\nprogram is expecting:\n```\nSDL_VIDEODRIVER=x11\n```\n\nPlease report this to the game developer as a bug.\nGame developers who know that their game engine requires X11 on Linux can\narrange for this to happen by including code similar to this at the\nbeginning of `main()`:\n```\n#ifdef SDL_VIDEO_DRIVER_X11\nSDL_SetHintWithPriority(SDL_HINT_VIDEODRIVER, \"x11\", SDL_HINT_OVERRIDE);\n#endif\n```\n\nThis is backward-compatible with \"classic\" SDL 2 version 2.0.12 or later.\nIf older versions need to be supported,\nset the `SDL_VIDEODRIVER` environment variable instead.\n\nFor unmaintained games where applying this code change is not feasible,\neither a wrapper script can set the `SDL_VIDEODRIVER` environment variable,\nor the game can be added to the `quirks` array in sdl2-compat.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibsdl-org%2Fsdl2-compat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flibsdl-org%2Fsdl2-compat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibsdl-org%2Fsdl2-compat/lists"}