XCEngine/README.md

XCEngine

XCEngine 是一个模块化的 C++ 游戏引擎工程，当前以 RHI 抽象层为核心推进渲染能力建设。
目前代码库已经具备可用的 D3D12 / OpenGL 双后端 RHI 基线，并配有单元测试与跨后端集成测试，已经可以作为后续基础渲染管线开发的支撑层继续向上推进。

当前状态

• 构建系统基于 CMake，测试系统基于 Google Test / CTest。
• RHI 抽象层当前重点支持 D3D12 和 OpenGL 两套后端。
• RHI 抽象层已完成一轮针对 pipeline layout、descriptor set、set-aware binding、shader、compute/UAV 路径的系统性收敛。
• 抽象层集成测试目前覆盖 minimal、triangle、quad、sphere 四个场景。
• 每个 RHI 抽象层集成测试场景只维护一张基准图 GT.ppm，D3D12 与 OpenGL 生成图都与同一张 GT 图进行比对。
• 以当前状态，RHI 已经适合作为“先开做基础渲染管线，再由上层反向驱动继续完善”的工程基线。

RHI 设计原则

RHI 模块遵循 docs/plan/end/RHI模块设计与实现/RHI模块总览.md 中的核心理念：

• 求同存异：优先抽取后端共性，避免把上层绑死在单一图形 API 上。
• 分层抽象：上层功能系统 -> 渲染管线 -> RHI -> 后端 API。
• 特性降级：后端能力不一致时，优先通过能力检测与合理降级维持统一接口。
• 谨慎逃逸：只有在抽象层无法表达时，才考虑后端特化，而不是让上层直接依赖原生 API。

当前更强调的一条实践约束是：

• 如果抽象层测试为了“能跑过”而不得不依赖后端私有接口，优先修 RHI 本身，而不是给测试开后门。

近期 RHI 整理结果

最近一轮 RHI 清理与重构，已经把以下关键问题收敛到统一行为：

• pipeline layout 负责拥有并管理 descriptor set 元数据，而不是把布局信息分散在各处。
• D3D12 / OpenGL 两个后端的 descriptor 绑定都已经是 set-aware 的，并正确处理 firstSet。
• OpenGL 路径下，来自内存源码的 GLSL 编译不再依赖意外的 NUL 终止。
• OpenGL 单 shader 编译路径现在会正确记录 ShaderType，计算着色器不再被错误标记为 Vertex。
• OpenGL 的 compute/UAV 绑定路径已经有真实 dispatch + 回读验证，不再只是状态级别的伪验证。
• 抽象层集成测试的 GT 管理已经统一为“每场景一张 GT，双后端都与同一 GT 比对”。

这意味着当前 RHI 的重点不再是“补最基础可用性”，而是“在做渲染管线的过程中继续按真实需求向前演进”。

仓库结构

XCEngine/
├─ engine/                  # 引擎静态库，包含 Core / RHI / Resources / Scene 等模块
├─ editor/                  # 编辑器程序
├─ tests/                   # 单元测试与集成测试
├─ mvs/                     # 示例与实验性程序
├─ docs/                    # 设计文档与 API 文档
└─ CMakeLists.txt

和当前渲染工作最相关的目录：

• engine/include/XCEngine/RHI/
• engine/src/RHI/
• tests/RHI/unit/
• tests/RHI/integration/
• tests/TEST_SPEC.md

环境要求

推荐开发环境：

• Windows 10/11
• Visual Studio 2019 或更新版本
• CMake 3.15+
• Python 3
  • RHI 抽象层集成测试会调用 compare_ppm.py 做 GT 图比对
• 可用的 D3D12 和/或 OpenGL 驱动环境

快速开始

1. 配置

如果使用 Visual Studio 生成器：

cmake -S . -B build -A x64

如果使用 Ninja 等单配置生成器：

cmake -S . -B build

2. 构建

cmake --build build --config Debug

如果只想增量构建当前最关键的 RHI 测试目标：

cmake --build build --config Debug --target rhi_unit_tests
cmake --build build --config Debug --target rhi_integration_minimal
cmake --build build --config Debug --target rhi_integration_triangle
cmake --build build --config Debug --target rhi_integration_quad
cmake --build build --config Debug --target rhi_integration_sphere

测试

运行全部测试

ctest --test-dir build -C Debug --output-on-failure

查看已注册测试

ctest --test-dir build -N -C Debug

运行 RHI 抽象层单元测试

build\tests\RHI\unit\Debug\rhi_unit_tests.exe

运行 RHI 抽象层集成测试

以 quad 为例：

build\tests\RHI\integration\quad\Debug\rhi_integration_quad.exe --gtest_filter=D3D12/QuadTest.RenderQuad/0
build\tests\RHI\integration\quad\Debug\rhi_integration_quad.exe --gtest_filter=OpenGL/QuadTest.RenderQuad/0

截图输出约定：

• quad_d3d12.ppm
• quad_opengl.ppm
• GT.ppm

两个后端都会与同目录下同一张 GT.ppm 比对。

RHI 测试体系

当前 RHI 测试分为四层：

层级	目录	目标
抽象层单元测试	tests/RHI/unit/	验证公共 RHI 接口在双后端上的一致性
抽象层集成测试	tests/RHI/integration/	用同一套 RHI 抽象代码驱动 D3D12 / OpenGL 完成真实渲染
D3D12 后端测试	tests/RHI/D3D12/	验证 D3D12 封装自身行为
OpenGL 后端测试	tests/RHI/OpenGL/	验证 OpenGL 封装自身行为

当前已存在的关键 RHI 测试目标：

• rhi_unit_tests
• rhi_integration_minimal
• rhi_integration_triangle
• rhi_integration_quad
• rhi_integration_sphere
• rhi_d3d12_tests
• rhi_opengl_tests

更多测试组织与命名规范见 tests/TEST_SPEC.md。

文档入口

• RHI 总览与设计原则： docs/plan/end/RHI模块设计与实现/RHI模块总览.md
• 测试规范： tests/TEST_SPEC.md
• API 文档： docs/api/

当前开发建议

如果你的目标是继续推进引擎渲染能力，建议直接在当前 RHI 之上开始做基础渲染管线，而不是继续闭门补抽象层“理论完整性”。

推荐策略：

• 先做最小可运行的基础渲染管线
• 始终只依赖公共 RHI 抽象接口
• 一旦上层逼出真实缺口，回到 RHI 修根因
• 每次修 RHI 时同步补单测和集成测试
• 始终把“双后端功能不破坏”放在第一优先级

许可证

MIT License