# XCEngine Agent Guide

这个文件面向进入当前工作区的开发者 / Codex / Agent，目标是快速建立对当前工程状态的正确认知，避免重新踩已经处理过的 RHI 问题。

## 1. 当前工程焦点

当前工程已经不再处于“先把 RHI 补到能跑起来”的阶段，而是处于：

- RHI 抽象层已经可用
- 可以开始继续向上做基础渲染管线
- 上层实现过程中继续反向驱动 RHI 精化

当前最重要的原则不是“继续堆抽象”，而是：

- 先保证功能正确
- 保证 D3D12 / OpenGL 双后端不被破坏
- 每修一个真实问题，都补对应测试

## 2. RHI 当前状态

RHI 当前重点支持：

- `D3D12`
- `OpenGL`

近期已经完成的关键收敛：

- `pipeline layout` 负责拥有并管理 descriptor set 元数据
- D3D12 / OpenGL 两个后端的 descriptor 绑定都已经 `set-aware`
- `firstSet` 路径已经被系统性修过并补测
- OpenGL shader 从内存源码创建时，不再依赖偶然的 NUL 终止
- OpenGL 单 shader 编译路径现在会正确记录 `ShaderType`
- OpenGL 的 compute/UAV 绑定已经有真实 dispatch + 回读验证
- RHI 抽象层集成测试统一采用“一场景一张 `GT.ppm`，双后端都与同一 GT 比对”

结论：

- 现在可以直接开始做基础渲染管线
- 但不要假设 RHI 已经“绝对最终完成”
- 后续上层实现很可能继续暴露新的真实缺口，这是正常状态

## 3. 设计原则

RHI 模块始终遵循：

- 求同存异
- 分层抽象
- 特性降级
- 谨慎逃逸

核心设计文档：

- [RHI模块总览](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)

工程实践约束：

- 抽象层测试只能依赖公共 RHI 接口
- 如果为了让抽象层测试通过而不得不 include 后端私有头文件，优先修 RHI 本身
- 功能不破坏永远高于“为了抽象而抽象”

## 4. 当前测试体系

RHI 测试分四层：

- `tests/RHI/unit/`
  - 抽象层单元测试
- `tests/RHI/integration/`
  - 抽象层集成测试
- `tests/RHI/D3D12/`
  - D3D12 后端专项测试
- `tests/RHI/OpenGL/`
  - OpenGL 后端专项测试

当前关键测试目标：

- `rhi_unit_tests`
- `rhi_integration_minimal`
- `rhi_integration_triangle`
- `rhi_integration_quad`
- `rhi_integration_sphere`
- `rhi_d3d12_tests`
- `rhi_opengl_tests`

测试规范总文档：

- [TEST_SPEC.md](tests/TEST_SPEC.md)

## 5. RHI 抽象层集成测试约束

当前抽象层集成测试目录：

- `tests/RHI/integration/minimal/`
- `tests/RHI/integration/triangle/`
- `tests/RHI/integration/quad/`
- `tests/RHI/integration/sphere/`

必须遵守：

- 每个场景目录只维护一张 `GT.ppm`
- D3D12 与 OpenGL 都与同一张 `GT.ppm` 比对
- 截图文件可以按后端区分，例如：
  - `quad_d3d12.ppm`
  - `quad_opengl.ppm`
- 抽象层集成测试必须只用公共 RHI 接口
- 新场景如果暴露的是 RHI 根因，要先修 RHI，再修测试

特别注意：

- `sphere` 这类场景承担了 `firstSet != 0` 的验证职责
- 不能为了让测试过而绕开 set/binding 语义

## 6. 推荐构建命令

配置：

```bash
cmake -S . -B build -A x64
```

常用增量构建：

```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 -N -C Debug
```

全量跑测试：

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

## 7. 常用验证命令

RHI 单测：

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

抽象层集成测试示例：

```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
```

```bash
build\tests\RHI\integration\sphere\Debug\rhi_integration_sphere.exe --gtest_filter=D3D12/SphereTest.RenderSphere/0
build\tests\RHI\integration\sphere\Debug\rhi_integration_sphere.exe --gtest_filter=OpenGL/SphereTest.RenderSphere/0
```

## 8. 后续推荐方向

当前最合理的后续工作是直接做基础渲染管线，而不是继续封闭式打磨 RHI。

推荐顺序：

1. 最小相机常量 / 每物体常量
2. 基础 opaque pass
3. render target / depth target 管理
4. 最小材质系统
5. 新的场景级集成测试

工作方式：

- 上层只能依赖 RHI 抽象
- 一旦暴露 RHI 根因，及时回到底层修复
- 每个阶段完成后立刻验证并提交

## 9. 文档入口

- 项目介绍与目录总览：
  - [README.md](README.md)
- RHI 核心设计文档：
  - [RHI模块总览](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
- 测试规范：
  - [TEST_SPEC.md](tests/TEST_SPEC.md)