188 lines
4.9 KiB
Markdown
188 lines
4.9 KiB
Markdown
|
# 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)
|