188 lines
6.3 KiB
Markdown
188 lines
6.3 KiB
Markdown
# 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`](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 的重点不再是“补最基础可用性”，而是“在做渲染管线的过程中继续按真实需求向前演进”。
|
||
|
||
## 仓库结构
|
||
|
||
```text
|
||
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 生成器：
|
||
|
||
```bash
|
||
cmake -S . -B build -A x64
|
||
```
|
||
|
||
如果使用 Ninja 等单配置生成器：
|
||
|
||
```bash
|
||
cmake -S . -B build
|
||
```
|
||
|
||
### 2. 构建
|
||
|
||
```bash
|
||
cmake --build build --config Debug
|
||
```
|
||
|
||
如果只想增量构建当前最关键的 RHI 测试目标：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
## 测试
|
||
|
||
### 运行全部测试
|
||
|
||
```bash
|
||
ctest --test-dir build -C Debug --output-on-failure
|
||
```
|
||
|
||
### 查看已注册测试
|
||
|
||
```bash
|
||
ctest --test-dir build -N -C Debug
|
||
```
|
||
|
||
### 运行 RHI 抽象层单元测试
|
||
|
||
```bash
|
||
build\tests\RHI\unit\Debug\rhi_unit_tests.exe
|
||
```
|
||
|
||
### 运行 RHI 抽象层集成测试
|
||
|
||
以 `quad` 为例：
|
||
|
||
```bash
|
||
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`](tests/TEST_SPEC.md)。
|
||
|
||
## 文档入口
|
||
|
||
- RHI 总览与设计原则：
|
||
[`docs/plan/end/RHI模块设计与实现/RHI模块总览.md`](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
|
||
- 测试规范：
|
||
[`tests/TEST_SPEC.md`](tests/TEST_SPEC.md)
|
||
- API 文档：
|
||
`docs/api/`
|
||
|
||
## 当前开发建议
|
||
|
||
如果你的目标是继续推进引擎渲染能力，建议直接在当前 RHI 之上开始做基础渲染管线，而不是继续闭门补抽象层“理论完整性”。
|
||
|
||
推荐策略：
|
||
|
||
- 先做最小可运行的基础渲染管线
|
||
- 始终只依赖公共 RHI 抽象接口
|
||
- 一旦上层逼出真实缺口，回到 RHI 修根因
|
||
- 每次修 RHI 时同步补单测和集成测试
|
||
- 始终把“双后端功能不破坏”放在第一优先级
|
||
|
||
## 许可证
|
||
|
||
MIT License
|