第70章 SDL2

课程目录第70章 SDL2

70、SDL2：集成SDL2多媒体库

说到多媒体开发，SDL2 绝对是个绕不开的库。我最早接触它是在做一个小游戏的时候，当时想找个跨平台的图形库，OpenGL 太底层，Qt 又太重。SDL2 刚好卡在中间——它给你一个窗口、一个画布、一套输入事件处理，剩下的你自己发挥。说白了，它就是个「多媒体瑞士军刀」。

这一讲，我们就聊聊怎么在 CMake 里把 SDL2 集成进来。嗯，这里要注意，SDL2 的集成方式有好几种，我挑最实用的讲。

SDL2 是什么？

SDL（Simple DirectMedia Layer）是一个跨平台的多媒体库。它封装了底层的图形、音频、输入设备操作。你写一份代码，能在 Windows、Linux、macOS 甚至 Android 上跑起来。

我个人习惯把它分成几个核心模块：

模块	功能
SDL2	核心库：窗口、事件、线程、定时器
SDL2_image	图片加载：PNG、JPG、BMP 等
SDL2_ttf	字体渲染：TrueType 字体
SDL2_mixer	音频播放：WAV、MP3、OGG 等
SDL2_net	网络通信（用得少，但需要时很管用）

你在项目里不一定全用上。我做过一个简单的 2D 游戏，只用到了 SDL2 和 SDL2_image。音频直接用 SDL2_mixer 加载了几首背景音乐。嗯，够用了。

CMake 集成 SDL2 的三种方式

集成 SDL2 的方式，说白了就三种。我按推荐程度排个序：

用 find_package 找系统安装的 SDL2 —— 最标准，适合 Linux 用户
用 FetchContent 自动下载 —— 最省心，适合跨平台项目
手动指定路径 —— 最灵活，适合特殊环境

我个人最推荐第二种。为什么？因为你在 Windows 上开发，同事在 macOS 上，CI 跑在 Linux 上。用 FetchContent 能保证大家拿到的 SDL2 版本完全一致。我曾经被「我本地能编译，你那边怎么不行」这种问题坑过好几次，后来统一用 FetchContent 就再没出过事。

方式一：find_package（系统安装）

如果你的开发机上已经装了 SDL2，那直接用 find_package 最省事。CMake 官方提供了 FindSDL2.cmake 模块，但说实话，不同版本的 CMake 支持程度不一样。我建议你显式指定路径：

find_package(SDL2 REQUIRED)
find_package(SDL2_image REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE SDL2::SDL2 SDL2_image::SDL2_image)

这里有个坑：SDL2 的 CMake 目标名是 SDL2::SDL2，不是 SDL2。我刚开始用的时候写成了 SDL2::SDL2main，结果链接报错。后来查文档才发现，SDL2main 是另一个库，用来帮你自动生成 main 函数的入口。一般你不需要它。

注意： 如果你在 Windows 上用 vcpkg 安装了 SDL2，记得在 CMake 配置时加上 -DCMAKE_TOOLCHAIN_FILE 参数。否则 find_package 找不到。

方式二：FetchContent（自动下载）

这是我现在最常用的方式。你想想看，项目 clone 下来，直接 cmake .. 就能编译，不用装任何依赖。多爽。

include(FetchContent)

FetchContent_Declare(
  SDL2
  GIT_REPOSITORY https://github.com/libsdl-org/SDL.git
  GIT_TAG release-2.28.5
)

FetchContent_Declare(
  SDL2_image
  GIT_REPOSITORY https://github.com/libsdl-org/SDL_image.git
  GIT_TAG release-2.6.3
)

FetchContent_MakeAvailable(SDL2 SDL2_image)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE SDL2::SDL2 SDL2_image::SDL2_image)

这里有个小技巧：GIT_TAG 最好指定具体的 release 版本，不要用 main 或 master。我遇到过两次，上游更新了代码，结果我的项目突然编译不过。锁定版本号，稳如老狗。

提示： 如果你网络不好，可以先把 SDL2 源码下载到本地，然后用 FetchContent 的 SOURCE_DIR 参数指定本地路径。这样既保留了自动集成的便利性，又避免了网络问题。

方式三：手动指定路径

这种方式适合你手头有预编译的 SDL2 库，或者公司内部有私有仓库。说白了就是「我自己告诉你库在哪」。

set(SDL2_INCLUDE_DIR "C:/libs/SDL2-2.28.5/include")
set(SDL2_LIBRARY "C:/libs/SDL2-2.28.5/lib/x64/SDL2.lib")

add_executable(my_app main.cpp)
target_include_directories(my_app PRIVATE ${SDL2_INCLUDE_DIR})
target_link_libraries(my_app PRIVATE ${SDL2_LIBRARY})

嗯，这种方式我不太推荐。因为路径写死了，换台机器就得改。除非你项目里所有开发者都用同一个构建环境，否则还是用前两种方式吧。

核心知识体系

我把 SDL2 集成的核心逻辑画了张图，方便你理解整体流程：

一个完整的例子

光说不练假把式。我给你一个完整的 CMakeLists.txt，它用 FetchContent 集成了 SDL2 和 SDL2_image，然后创建了一个窗口并显示一张图片。

cmake_minimum_required(VERSION 3.20)
project(SDL2Demo)

include(FetchContent)

# 拉取 SDL2
FetchContent_Declare(
  SDL2
  GIT_REPOSITORY https://github.com/libsdl-org/SDL.git
  GIT_TAG release-2.28.5
)

# 拉取 SDL2_image
FetchContent_Declare(
  SDL2_image
  GIT_REPOSITORY https://github.com/libsdl-org/SDL_image.git
  GIT_TAG release-2.6.3
)

FetchContent_MakeAvailable(SDL2 SDL2_image)

add_executable(sdl2_demo main.cpp)
target_link_libraries(sdl2_demo PRIVATE SDL2::SDL2 SDL2_image::SDL2_image)

对应的 main.cpp 长这样：

#include <SDL2/SDL.h>
#include <SDL2/SDL_image.h>
#include <iostream>

int main(int argc, char* argv[]) {
    // 初始化 SDL2
    if (SDL_Init(SDL_INIT_VIDEO) < 0) {
        std::cerr << "SDL_Init failed: " << SDL_GetError() << std::endl;
        return -1;
    }

    // 创建窗口
    SDL_Window* window = SDL_CreateWindow(
        "SDL2 Demo",
        SDL_WINDOWPOS_CENTERED,
        SDL_WINDOWPOS_CENTERED,
        800, 600,
        SDL_WINDOW_SHOWN
    );

    if (!window) {
        std::cerr << "Window creation failed: " << SDL_GetError() << std::endl;
        SDL_Quit();
        return -1;
    }

    // 事件循环
    SDL_Event event;
    bool running = true;
    while (running) {
        while (SDL_PollEvent(&event)) {
            if (event.type == SDL_QUIT) {
                running = false;
            }
        }
    }

    SDL_DestroyWindow(window);
    SDL_Quit();
    return 0;
}

  重要提醒： SDL2 的 main 函数签名必须是 int main(int argc, char* argv[])。如果你写成 int main()，在某些平台上会链接失败。这是因为 SDL2 内部会替换 main 函数入口。嗯，这个坑我踩过，印象很深。

避坑指南

集成 SDL2 的过程中，有几个常见问题。我挨个说一下：

找不到 SDL2.h —— 检查你的 include 路径。如果用 FetchContent，CMake 会自动处理。如果用 find_package，确认 SDL2 确实装在了系统路径里。
链接报错：undefined reference to SDL_main —— 这个我遇到过。原因是 SDL2 把 main 宏定义成了 SDL_main。解决方案：在 main 函数前加上 #undef main，或者直接用 SDL2 提供的 SDL_main 宏。
Windows 上控制台一闪而过 —— 这是因为 SDL2 默认链接了 SDL2main.lib，它会自动隐藏控制台。如果你想要控制台窗口，链接时不要加 SDL2main。
macOS 上找不到 OpenGL 相关符号 —— SDL2 在 macOS 上依赖 OpenGL 框架。你需要在 CMake 里加上 find_package(OpenGL REQUIRED) 和 target_link_libraries(... OpenGL::GL)。

总结

SDL2 的集成其实不复杂。你只要记住：用 FetchContent 最省心，锁定版本号最安全，按需选择模块最轻量。我个人的项目模板里，SDL2 和 SDL2_image 是标配，SDL2_ttf 和 SDL2_mixer 看需求再加。这样既保证了功能完整，又不会让编译时间太长。

好了，这一讲就到这里。你可以在自己的项目里试试看，跑通一个窗口，然后慢慢加图片、加音频。SDL2 的世界，比你想象的要简单。

📚 课程目录

70、SDL2：集成SDL2多媒体库

SDL2 是什么？

CMake 集成 SDL2 的三种方式

方式一：find_package（系统安装）

方式二：FetchContent（自动下载）

方式三：手动指定路径

核心知识体系

一个完整的例子

避坑指南

总结