简易直媒体层 (SDL) sdl12-compat

https://www.libsdl.org/

这是简易直媒体层（Simple DirectMedia Layer），一个通用API，提供跨平台的底层访问功能，包括音频、键盘、鼠标、游戏手柄、通过OpenGL实现的3D硬件加速以及2D帧缓冲。

本代码是一个兼容层；它为基于SDL 1.2编写的程序提供了二进制和源代码兼容的API，但在底层实际使用的是SDL 2.0。如果您正在编写新代码，请直接以SDL 2.0为目标，不要使用此兼容层。

如果您确实需要使用真正的SDL 1.2（“SDL 1.2经典版”），请访问源代码库https://github.com/libsdl-org/SDL-1.2，该库偶尔会修复错误但不会正式发布。但我们强烈建议您不要这样做。

使用方法：

• 构建库。这需要访问SDL2的头文件（v2.0.7或更高版本）、CMake以及您选择的构建工具。构建完成后，您将获得一个可直接替换的库，可用于任何依赖SDL 1.2的现有二进制文件。您可以将此库覆盖现有的1.2版本，或通过LD_LIBRARY_PATH等方式使其优先于系统版本。在运行时，sdl12-compat需要能够找到SDL2的副本（v2.0.7或更高版本——Windows需要v2.0.12或更高版本），因此必要时请将其与库一起包含。

• 如果您想从源代码构建SDL 1.2程序，我们提供了兼容头文件，以便sdl12-compat可以在所有方面完全替代SDL 1.2。这些头文件仅包含源代码兼容所需的最基本内容，没有大量文档或高级功能。新头文件同样遵循zlib许可证。请注意，sdl12-compat本身不使用这些头文件，因此如果您只需要库，则不需要它们。

构建库：

以下是快速入门指南；如果您熟悉CMake的使用，这里没有什么特别之处。

您需要使用CMake来构建sdl12-compat。可从cmake.org下载或通过包管理器安装（例如在Ubuntu上使用sudo apt-get install cmake）。

由于平台和构建工具的细节各异，请参考CMake文档获取完整详情。

构建sdl12-compat需要SDL 2.0.x的副本，因为我们需要SDL2的头文件。您可以从源代码构建或通过包管理器安装。Windows和Mac用户可以从SDL下载页面获取预编译的二进制文件；请确保下载的是“开发库”而非“运行时二进制文件”。

Linux用户可能需要从其Linux发行版中安装一些包。在Ubuntu上，您可能需要执行：

sudo apt-get install build-essential cmake libsdl2-2.0-0 libsdl2-dev libgl-dev

现在只需将 CMake 指向 sdl12-compat 的目录即可。以下是一个命令行示例：

cd sdl12-compat
cmake -Bbuild -DCMAKE_BUILD_TYPE=Release .
cmake --build build

在 Windows 或 macOS 系统上，您可能更倾向于使用 CMake 的图形界面，但操作原理相同：指定 sdl12-compat 所在的目录，点击"Configure"按钮，选择您惯用的编译器，接着点击"Generate"即可生成项目文件。此时点击"Open Project"即可启动开发环境，随后您可以通过 Visual Studio、Xcode 等工具按需进行构建。

若使用 CMake 时遇到需要指定 SDL2 头文件路径的情况（注意：sdl12-compat 在构建时仅需 SDL2 的头文件而非库文件，即使提示缺少库文件警告也可忽略），可通过命令行添加 -DSDL2_INCLUDE_DIR=/path/to/SDL2/include 参数，或在 CMake 图形界面中找到对应选项进行配置，再次点击"Configure"后执行"Generate"。

构建完成后，您将获得一个可替换现有 SDL 1.2 版本的动态链接库。该过程同时会构建原始 SDL 1.2 测试程序，便于验证库文件功能是否正常。

Linux 环境下为旧版 CPU 架构构建说明：

考虑到许多年前使用 SDL 1.2 的二进制文件往往针对与当前系统不同的 CPU 架构（例如 32 位 x86），若您需要在 x86-64 Linux 设备上构建 32 位 x86 库以实现对老游戏的兼容，应安装适用于您发行版的基础 32 位开发库。以 Ubuntu 为例，需执行以下操作：

sudo apt-get install gcc-multilib libsdl2-dev:i386

...然后在构建选项中添加 -m32：

cd sdl12-compat
cmake -Bbuild32 -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_FLAGS=-m32
cmake --build build32

为 macOS 旧版 CPU 架构构建：

macOS 用户可尝试添加 -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' 参数替代 -DCMAKE_C_FLAGS=-m32，以生成同时支持 64 位 Intel 和 Apple Silicon 芯片的通用二进制文件。若您使用的是较旧（或非常老旧！）版本的 Xcode，可尝试使用 "i386" 甚至 "powerpc" 架构为 32 位 Intel 或 PowerPC 系统构建——但需注意 Xcode（及 macOS 系统本身）早已停止对这些架构的支持，且您可能会在 SDL2 编译过程中遇到各种小问题...不过通过足够努力，或许仍能_勉强_让 SDL2 和 sdl12-compat 在苹果已弃用的架构上运行。

为 Windows 旧版 CPU 架构构建：

Windows 用户只需在 CMake 图形界面中选择 32 位版本的 Visual Studio 编译器即可（当 CMake 询问目标编译器时）。

配置选项：

sdl12-compat 提供多项配置选项，可用于解决特定应用程序的兼容性问题，或使软件更适配您的系统环境及使用偏好。

所有选项均通过环境变量指定，您可以在命令行启动应用程序时设置这些变量，例如：

SDL12COMPAT_HIGHDPI=1 SDL12COMPAT_OPENGL_SCALING=0 %command%

将以支持高DPI显示器的模式运行 %command%，但禁用OpenGL缩放支持。

（注意：这些环境变量会在应用程序生命周期中多次被检测，但sdl12-compat要求这些变量在进程启动前设置且运行期间保持不变。任何运行时修改可能产生的影响均属偶然行为，未来可能发生变化。换言之：请不要开发基于SDL 1.2且计划动态调整这些值的应用程序！）

可用选项包括：

• SDL12COMPAT_DEBUG_LOGGING:（启动时检测） 启用后，将调试信息输出至stderr。这些信息主要对开发者有用，或用于追踪特定错误。

• SDL12COMPAT_FAKE_CDROM_PATH:（SDL_Init期间检测） 指定包含MP3文件（命名格式为trackXX.mp3，XX为两位数音轨编号）的目录路径，供播放CD音频的应用程序使用。建议使用绝对路径：相对路径的正确性无法保证。

• SDL12COMPAT_OPENGL_SCALING:（SDL_Init期间检测） 启用OpenGL应用程序缩放至当前桌面分辨率。禁用时，应用程序可更改实际屏幕分辨率。默认启用，但并非所有应用程序都兼容：若出现黑屏问题可尝试调整此选项。

• SDL12COMPAT_FIX_BORDERLESS_FS_WIN:（SDL_SetVideoMode期间检测） 将桌面分辨率的无边框窗口转为真正全屏窗口（在macOS中会进入独立空间，在其他桌面环境中能正确隐藏停靠窗口等）。禁用时，应用程序可能无法获得预期的完整显示区域。默认启用，但若出现未预见的负面效果可手动禁用。

• SDL12COMPAT_SCALE_METHOD:（SDL_Init期间检测） 选择非原生分辨率渲染时的缩放方法。可选nearest（最近邻采样，更像素化）或linear（双线性采样，更模糊）。

• SDL12COMPAT_HIGHDPI:（SDL_SetVideoMode期间检测） 声明应用程序支持高DPI显示器。启用后通常能获得更锐利的图像，但某些应用程序的文本等元素可能变得过小。

• SDL12COMPAT_SYNC_TO_VBLANK:（SDL_SetVideoMode期间检测） 强制应用程序启用/禁用垂直同步（VSync）。启用时将帧率限制为屏幕刷新率（可能解决画面撕裂问题）。

• SDL12COMPAT_USE_KEYBOARD_LAYOUT:（SDL_Init期间检测） 使所有键盘输入考虑当前键盘布局。对于自带键盘布局支持的应用程序，或需优先考虑物理键位而非生成字符时，可能需要禁用。注意：文本输入（多数情况下）不受此选项影响。

• SDL12COMPAT_USE_GAME_CONTROLLERS:（SDL_Init期间检测） 使用SDL2的高级游戏控制器API替代底层摇杆API。优势是可对硬件进行更多控制（死区、按键映射、设备名称等），且按键/轴布局统一（如Xbox360的"A"键始终对应SDL 1.2摇杆按钮0）。缺点是可能无法暴露硬件的全部功能，或不适用于飞行摇杆等设备。若摇杆无已知控制器映射且启用此选项，该设备将不可见。

• SDL12COMPAT_WINDOW_SCALING:（SDL_SetVideoMode期间检测） 为非全屏/不可调整大小的窗口设置缩放系数。例如在4K显示器上窗口过小时，可设为2进行双倍放大。支持小数（如"1.5"），甚至可设为小于1.0的值缩小窗口。缩放时会应用所有常规缩放选项（SDL12COMPAT_OPENGL_SCALING等）。若因技术原因无法缩放，则按原始尺寸创建窗口。默认值1.0表示无缩放。

• SDL12COMPAT_MAX_VIDMODE:（SDL_Init期间检测） 格式为WxH的字符串（如640x480），限制SDL_ListModes和SDL_VideoModeOK返回的分辨率范围。零值表示不限制对应维度（如0x480允许1920x480）。适用于总选择最大分辨率但未考虑4K显示的旧软件渲染游戏，可让其使用较小分辨率后由GPU放大输出。

• SDL_MOUSE_RELATIVE_SCALING:（SDL_SetVideoMode期间检测） 启用时，非原生分辨率下会缩放相对鼠标移动。某些使用自定义鼠标指针的应用程序可能需要此功能。详见：https://wiki.libsdl.org/SDL_HINT_MOUSE_RELATIVE_SCALING

• SDL12COMPAT_ALLOW_THREADED_DRAWS:（SDL_Init期间检测） 默认启用。禁用时，非主线程的SDL_UpdateRects()调用会转为由主线程延迟执行的请求。调用SDL_SetVideoMode()的线程视为主线程。

• SDL12COMPAT_ALLOW_THREADED_PUMPS:（SDL_Init期间检测） 默认启用。禁用时，非主线程的SDL_PumpEvents()调用会被完全忽略。调用SDL_SetVideoMode()的线程视为主线程。

• SDL12COMPAT_ALLOW_SYSWM:（SDL_Init期间检测） 默认启用。禁用时，不向应用程序传递SDL_SYSWMEVENT事件且SDL_GetWMInfo()会失败。适用于通过SDL接口直接访问X11但能兼容Wayland等环境的程序。注意：sdl12-compat已限制SysWM功能仅限SDL2使用"windows"或"x11"视频后端时可用，因SDL 1.2的SysWM API原本就仅广泛支持Windows和X11。

OpenGL 缩放兼容性问题

sdl12-compat 的 OpenGL 缩放功能允许应用程序在不改变系统分辨率的情况下，以非原生屏幕分辨率运行。该功能通过将 OpenGL 渲染调用重定向到一个"虚拟"后备缓冲区实现，渲染时会对该缓冲区进行缩放处理。

对于简单应用而言，这一机制运行良好。但对于使用帧缓冲对象（Frame Buffer Objects）的复杂应用，sdl12-compat 需要拦截并重定向部分 OpenGL 调用。若应用程序绕过 SDL（即使通过第三方库）直接访问这些函数，在启用 OpenGL 缩放时可能导致渲染失败或出现异常渲染。

遇到此类情况时，您可通过设置以下环境变量禁用 OpenGL 缩放功能：

SDL12COMPAT_OPENGL_SCALING=0

应用程序直接调用底层 API 的兼容性问题

部分应用程序在调用 SDL 的同时，会直接访问底层操作系统或窗口系统。当这些应用程序在相同的操作系统和 SDL 视频驱动下运行时（例如为 Linux X11 编写的程序在 Linux X11 环境下运行），sdl12-compat 通常能保持兼容。

但若要在不同的视频驱动环境下运行应用程序，程序将无法访问其预期的底层 API，可能导致运行失败。这种情况常见于尝试在 Wayland 下运行专为 X11 编写的应用程序，尤其会影响多个主流的 OpenGL 扩展加载器。

针对这种情况，最佳的解决方案是通过 XWayland 等兼容层运行程序，并通过设置 SDL_VIDEODRIVER 环境变量来指定程序期望使用的驱动程序：

SDL_VIDEODRIVER=x11