# 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