# Extra2D

Build Status C++17 OpenGL ES 3.2 SDL2 GLFW Nintendo Switch

轻量级跨平台 2D 游戏引擎
高性能、模块化、支持 Nintendo Switch

[构建指南](#构建指南) | [快速开始](#快速开始) | [示例程序](#示例程序) | [模块系统](./docs/module_system.md)
--- ## 简介 **Extra2D** 是一个轻量级跨平台 2D 游戏引擎，采用现代 C++17 架构，支持 Windows、Linux、macOS 和 Nintendo Switch 平台。 ### 核心特性 - **跨平台支持**：Windows、Linux、macOS、Nintendo Switch - **模块化架构**：模块系统 + 服务系统，灵活可扩展 - **多后端渲染**：OpenGL / Vulkan 支持，易于扩展新后端 - **资源抽象层**：统一的 Buffer、Pipeline、Framebuffer 接口 - **高性能批处理**：独立 Batch 层，TrigLookup 优化，支持 10000 精灵/批次 - **场景图系统**：树形节点结构，支持变换继承 - **输入系统**：键盘、鼠标、手柄、触摸，事件驱动 - **渲染系统**：OpenGL ES 3.2，支持自定义着色器 - **视口适配**：多种适配模式，自动响应窗口大小变化 - **显存管理**：VRAM 预算追踪，内存泄漏防护 - **音频系统**：高质量音频播放（规划中） - **UI 系统**：完整的 UI 控件支持（规划中） --- ## 架构概览 ```mermaid flowchart TB subgraph Application["Application (应用层)"] direction TB APP[Application] end subgraph Core["Core Layer (核心层)"] direction LR MR[ModuleRegistry
模块注册表] SL[ServiceLocator
服务定位器] end subgraph Modules["Modules (模块系统)"] direction TB WINDOW["Window Module
窗口管理 P0"] RENDER["Render Module
渲染系统 P10"] INPUT["Input Module
输入处理 P20"] end subgraph Services["Services (服务系统)"] direction TB EVENT[EventService
事件分发] TIMER[TimerService
计时器] SCENE_SVC[SceneService
场景管理] CAMERA[CameraService
相机系统] end subgraph Scene["Scene System (场景系统)"] direction TB SCENE[Scene
场景] NODE[Node
节点] SHAPE[ShapeNode
形状节点] SPRITE[Sprite
精灵] end subgraph Graphics["Graphics (图形系统)"] direction TB RESOURCES[Resources
资源抽象层] BACKEND[RenderBackend
渲染后端] BATCH[Batch Layer
批处理层] GL[OpenGL Backend
OpenGL 后端] VK[Vulkan Backend
Vulkan 后端] SHADER[ShaderManager
着色器管理] TEXTURE[TexturePool
纹理池] MEMORY[Memory
显存管理] end subgraph Platform["Platform (平台层)"] direction TB subgraph WindowBackends["窗口后端"] SDL2[SDL2 Backend
SDL2 后端] GLFW[GLFW Backend
GLFW 后端] end INPUT_SYS[Input System
输入系统] end APP --> MR APP --> SL MR --> Modules SL --> Services SCENE_SVC --> SCENE SCENE --> NODE NODE --> SHAPE NODE --> SPRITE RENDER --> BACKEND BACKEND --> BATCH BATCH --> GL BATCH --> VK GL --> RESOURCES GL --> SHADER GL --> TEXTURE GL --> MEMORY WINDOW --> SDL2 WINDOW --> GLFW INPUT --> INPUT_SYS INPUT_SYS --> SDL2 INPUT_SYS --> GLFW ``` ### 模块系统 | 模块 | 职责 | 优先级 | |-----|------|-------| | Window | 窗口管理 | 0 | | Render | 渲染系统 | 10 | | Input | 输入处理 | 20 | ### 服务系统 | 服务 | 职责 | 优先级 | |-----|------|-------| | EventService | 事件分发 | 100 | | TimerService | 计时器 | 200 | | SceneService | 场景管理 | 300 | | CameraService | 相机系统 | 400 | --- ## 渲染系统架构 ### 多后端支持 Extra2D 采用分层架构支持多渲染后端： ``` ┌─────────────────────────────────────┐ │ Application (游戏逻辑) │ ├─────────────────────────────────────┤ │ Renderer (渲染命令) │ ├─────────────────────────────────────┤ │ Resources (resources/) │ ← 资源抽象层（后端无关） │ - Buffer 接口 │ │ - Pipeline 接口 │ │ - Framebuffer 接口 │ │ - Shader 接口 │ │ - FontAtlas 接口 │ ├─────────────────────────────────────┤ │ Batch Layer (batch/) │ ← 后端无关的批处理 │ - 顶点缓存管理 │ │ - 批次策略 (10000 精灵/批次) │ │ - TrigLookup 三角函数查表 │ │ - 批量绘制接口 │ ├─────────────────────────────────────┤ │ Backend Layer (backends/) │ ← 具体 GPU 实现 │ - OpenGL / Vulkan / Metal / D3D │ │ - GLBuffer / GLPipeline / GLFramebuffer │ - GPU 提交 │ └─────────────────────────────────────┘ ``` ### 资源抽象层 统一的资源接口，支持多后端实现： | 接口 | 功能 | OpenGL 实现 | |-----|------|------------| | Buffer | 顶点/索引/统一缓冲 | GLBuffer | | Pipeline | 渲染状态管理 | GLPipeline | | Framebuffer | 离屏渲染目标 | GLFramebuffer | | Shader | 着色器程序 | GLShader | | FontAtlas | 字体图集 | GLFontAtlas | ### 显存管理 ```cpp // VRAM 预算管理（Switch 默认 400MB） VRAMMgr::get().setVRAMBudget(400 * 1024 * 1024); // 自动追踪显存使用 // - GLTexture 自动追踪纹理显存 // - GLBuffer 自动追踪缓冲区显存 // 打印显存统计 VRAMMgr::get().printStats(); ``` ### 着色器系统 支持多后端的 JSON 元数据着色器系统： ```json { "name": "sprite", "backends": { "opengl": { "vertex": "backends/opengl/builtin/sprite.vert", "fragment": "backends/opengl/builtin/sprite.frag" }, "vulkan": { "vertex": "backends/vulkan/builtin/sprite.vert.spv", "fragment": "backends/vulkan/builtin/sprite.frag.spv" } } } ``` ### 性能优化 | 优化技术 | 说明 | 性能提升 | |---------|------|---------| | **TrigLookup** | 三角函数查表，避免每帧 sin/cos 计算 | 旋转计算 5-10x | | **大批次容量** | 10000 精灵/批次，减少 draw call | Draw call 减少 10x | | **批量绘制** | `drawBatch()` 一次性处理多个精灵 | CPU 开销减少 20-30% | | **静态索引** | 预生成索引缓冲区，避免运行时分配 | 内存分配开销消除 | | **着色器缓存** | 二进制着色器缓存，加速启动 | 启动时间减少 | | **状态缓存** | GLPipeline 缓存状态，避免冗余 GL 调用 | 状态切换开销减少 | | **Orphaning** | 动态缓冲区 orphaning 策略 | GPU 同步开销减少 | --- ## 构建指南 ### 环境要求 | 组件 | 要求 | |:----:|:-----| | 编译器 | GCC 9+ / Clang 10+ / MSVC 2019+ | | C++ 标准 | C++17 | | 构建工具 | xmake 2.5+ | | 目标平台 | Windows / Linux / macOS / Nintendo Switch | ### 安装 xmake ```powershell # Windows (PowerShell) Invoke-Expression (Invoke-WebRequest 'https://xmake.io/psget.text' -UseBasicParsing).Content ``` ```bash # macOS brew install xmake # Linux sudo add-apt-repository ppa:xmake-io/xmake sudo apt update sudo apt install xmake ``` ### 构建项目 #### 基础构建（使用 SDL2 后端，默认） ```bash # 配置项目 xmake f -p mingw -a x86_64 -m release -y # 构建 xmake build # 运行示例 xmake run demo_basic ``` #### 使用 GLFW 后端 ```bash # 配置项目（指定 GLFW 后端） xmake f -p mingw -a x86_64 -m release --window_backend=glfw -y # 构建 xmake build # 运行示例 xmake run demo_basic ``` #### 切换窗口后端 ```bash # 切换到 GLFW 后端 xmake f --window_backend=glfw -y # 切换回 SDL2 后端 xmake f --window_backend=sdl2 -y # 清理重新配置 xmake f -c -y ``` #### 切换渲染后端 ```bash # 切换到 Vulkan 后端 xmake f --render_backend=vulkan -y # 切换回 OpenGL 后端（默认） xmake f --render_backend=opengl -y # 清理重新配置 xmake f -c -y ``` ### Nintendo Switch 构建 ```bash # 设置 devkitPro 环境 export DEVKITPRO=/opt/devkitpro # 配置并构建 xmake f -p switch -m release -y xmake build ``` --- ## 快速开始 ### 创建应用 ```cpp #include using namespace extra2d; int main() { // 配置应用 AppConfig config = AppConfig::createDefault(); config.appName = "My Game"; config.appVersion = "1.0.0"; // 初始化 Application& app = Application::get(); if (!app.init(config)) { return -1; } // 创建场景 auto scene = Scene::create(); scene->setBackgroundColor(Color(0.1f, 0.1f, 0.15f, 1.0f)); scene->setViewportSize(app.window().width(), app.window().height()); // 配置视口适配 auto cameraService = app.camera(); if (cameraService) { ViewportConfig vpConfig; vpConfig.logicWidth = app.window().width(); vpConfig.logicHeight = app.window().height(); vpConfig.mode = ViewportMode::AspectRatio; cameraService->setViewportConfig(vpConfig); } // 运行场景 app.enterScene(scene); app.run(); // 清理 app.shutdown(); return 0; } ``` ### 场景图示例 ```cpp // 创建节点层级 auto root = makeShared(); root->setPos(width / 2, height / 2); scene->addChild(root); // 添加形状节点 auto rect = ShapeNode::createFilledRect( Rect(-50, -50, 100, 100), Color(1.0f, 0.4f, 0.4f, 1.0f) ); root->addChild(rect); // 变换继承 auto child = makeShared(); child->setPos(100, 0); child->setRotation(45); // 旋转 45 度 child->setScale(0.5f); // 缩放 0.5 root->addChild(child); ``` ### 输入事件 ```cpp auto eventService = app.events(); // 键盘事件 eventService->addListener(EventType::KeyPressed, [](Event& e) { auto& key = std::get(e.data); if (key.keyCode == static_cast(Key::Escape)) { Application::get().quit(); } }); // 鼠标事件 eventService->addListener(EventType::MouseButtonPressed, [](Event& e) { auto& mouse = std::get(e.data); // 处理鼠标点击 }); // 手柄事件 eventService->addListener(EventType::GamepadButtonPressed, [](Event& e) { auto& gamepad = std::get(e.data); // 处理手柄输入 }); ``` --- ## 示例程序 | 示例 | 说明 | |-----|------| | `demo_basic` | 基础示例：场景图、输入事件、视口适配 | | `demo_text_rendering` | 文字渲染示例：使用 GLFontAtlas 渲染文字 | 运行示例： ```bash xmake run demo_basic ``` --- ## 技术栈 | 技术 | 用途 | 版本 | |:----:|:-----|:----:| | OpenGL ES | 2D 图形渲染 | 3.2 | | SDL2 | 窗口和输入管理（可选） | 2.0+ | | GLFW | 窗口和输入管理（可选） | 3.4+ | | GLM | 数学库 | 0.9.9+ | | nlohmann_json | JSON 解析 | 3.x | | glad | OpenGL 加载器 | 最新版 | | stb_image | 图像加载 | 最新版 | | stb_truetype | 字体渲染 | 最新版 | | xmake | 构建系统 | 2.5+ | --- ## 文档 - [模块系统文档](./docs/module_system.md) - 模块系统、服务系统、场景图、视口适配 --- ## 目录结构 ``` Extra2D/ ├── Extra2D/ │ ├── include/ │ │ ├── KHR/ # KHR 平台头文件 │ │ ├── extra2d/ # 引擎公共头文件 │ │ │ ├── app/ # 应用程序 │ │ │ ├── audio/ # 音频配置 │ │ │ ├── config/ # 配置系统 │ │ │ ├── core/ # 核心类型 │ │ │ ├── event/ # 事件系统 │ │ │ ├── graphics/ # 图形渲染 │ │ │ │ ├── backends/ # 渲染后端 │ │ │ │ │ ├── opengl/ # OpenGL 实现 │ │ │ │ │ │ ├── gl_context.h # OpenGL 上下文 │ │ │ │ │ │ ├── gl_buffer.h # 缓冲区实现 │ │ │ │ │ │ ├── gl_pipeline.h # 管线状态 │ │ │ │ │ │ ├── gl_framebuffer.h # 帧缓冲 │ │ │ │ │ │ ├── gl_renderer.h # 渲染器 │ │ │ │ │ │ ├── gl_texture.h # 纹理 │ │ │ │ │ │ ├── gl_shader.h # 着色器 │ │ │ │ │ │ ├── gl_sprite_batch.h # 精灵批处理 │ │ │ │ │ │ └── gl_font_atlas.h # 字体图集 │ │ │ │ │ └── vulkan/ # Vulkan 实现 │ │ │ │ ├── batch/ # 批处理层（后端无关） │ │ │ │ │ ├── sprite_batch.h │ │ │ │ │ └── shape_batch.h │ │ │ │ ├── resources/ # 资源抽象层（新增） │ │ │ │ │ ├── buffer.h # 缓冲区接口 │ │ │ │ │ ├── pipeline.h # 管线接口 │ │ │ │ │ ├── framebuffer.h # 帧缓冲接口 │ │ │ │ │ ├── shader.h # 着色器接口 │ │ │ │ │ └── font_atlas.h # 字体接口 │ │ │ │ ├── core/ # 渲染核心 │ │ │ │ ├── camera/ # 相机和视口 │ │ │ │ ├── shader/ # Shader 系统 │ │ │ │ ├── texture/ # 纹理系统 │ │ │ │ └── memory/ # GPU 内存管理 │ │ │ │ ├── gpu_context.h # GPU 上下文状态 │ │ │ │ └── vram_manager.h # 显存管理器 │ │ │ ├── platform/ # 平台抽象 │ │ │ ├── scene/ # 场景系统 │ │ │ ├── services/ # 服务接口 │ │ │ └── utils/ # 工具库 │ │ ├── glad/ # OpenGL 加载器 │ │ └── stb/ # STB 单文件库 │ ├── shaders/ # 着色器文件 │ │ ├── backends/ # 后端特定着色器 │ │ │ └── opengl/ # OpenGL 着色器 │ │ └── shared/ # 共享着色器元数据 │ └── src/ # 源文件 │ ├── app/ # 应用实现 │ ├── config/ # 配置实现 │ ├── core/ # 核心实现 │ ├── event/ # 事件实现 │ ├── glad/ # GLAD 实现 │ ├── graphics/ # 图形实现 │ │ ├── backends/ # 渲染后端实现 │ │ │ ├── opengl/ # OpenGL 实现 │ │ │ │ ├── gl_context.cpp │ │ │ │ ├── gl_buffer.cpp │ │ │ │ ├── gl_pipeline.cpp │ │ │ │ ├── gl_framebuffer.cpp │ │ │ │ ├── gl_renderer.cpp │ │ │ │ ├── gl_texture.cpp │ │ │ │ ├── gl_shader.cpp │ │ │ │ ├── gl_sprite_batch.cpp │ │ │ │ └── gl_font_atlas.cpp │ │ │ └── vulkan/ # Vulkan 实现 │ │ ├── batch/ # 批处理层实现 │ │ ├── resources/ # 资源抽象层（接口定义） │ │ ├── core/ # 渲染核心 │ │ ├── camera/ # 相机和视口 │ │ ├── shader/ # Shader 系统 │ │ ├── texture/ # 纹理系统 │ │ └── memory/ # GPU 内存管理 │ │ ├── gpu_context.cpp │ │ └── vram_manager.cpp │ ├── platform/ # 平台实现 │ │ └── backends/ # 后端实现 │ │ ├── sdl2/ # SDL2 后端 │ │ └── glfw/ # GLFW 后端 │ ├── scene/ # 场景实现 │ ├── services/ # 服务实现 │ └── utils/ # 工具实现 ├── docs/ # 文档 ├── examples/ # 示例程序 │ └── basic/ # 基础示例 └── xmake/ # 构建配置 └── toolchains/ # 工具链配置 ``` --- ## 平台支持 | 平台 | 窗口后端 | 图形 API | 状态 | |-----|---------|---------|------| | Windows | SDL2 / GLFW | OpenGL ES 3.2 / Vulkan | ✅ 支持 | | Linux | SDL2 / GLFW | OpenGL ES 3.2 / Vulkan | ✅ 支持 | | macOS | SDL2 / GLFW | OpenGL ES 3.2 / Vulkan | ✅ 支持 | | Nintendo Switch | SDL2 / GLFW | OpenGL ES 3.2 | ✅ 支持 | --- ## 贡献 欢迎提交 Issue 和 Pull Request！ --- ## 许可证 Extra2D 使用 [MIT](LICENSE) 许可证。 --- ## 联系方式 - GitHub Issues: https://github.com/ChestnutYueyue/extra2d/issues