4.9 KiB
4.9 KiB
XCEngine Agent Guide
这个文件面向进入当前工作区的开发者 / Codex / Agent，目标是快速建立对当前工程状态的正确认知，避免重新踩已经处理过的 RHI 问题。
1. 当前工程焦点
当前工程已经不再处于“先把 RHI 补到能跑起来”的阶段，而是处于：
- RHI 抽象层已经可用
- 可以开始继续向上做基础渲染管线
- 上层实现过程中继续反向驱动 RHI 精化
当前最重要的原则不是“继续堆抽象”，而是：
- 先保证功能正确
- 保证 D3D12 / OpenGL 双后端不被破坏
- 每修一个真实问题，都补对应测试
2. RHI 当前状态
RHI 当前重点支持：
D3D12OpenGL
近期已经完成的关键收敛：
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 接口
- 如果为了让抽象层测试通过而不得不 include 后端私有头文件，优先修 RHI 本身
- 功能不破坏永远高于“为了抽象而抽象”
4. 当前测试体系
RHI 测试分四层：
tests/RHI/unit/- 抽象层单元测试
tests/RHI/integration/- 抽象层集成测试
tests/RHI/D3D12/- D3D12 后端专项测试
tests/RHI/OpenGL/- OpenGL 后端专项测试
当前关键测试目标：
rhi_unit_testsrhi_integration_minimalrhi_integration_trianglerhi_integration_quadrhi_integration_sphererhi_d3d12_testsrhi_opengl_tests
测试规范总文档：
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.ppmquad_opengl.ppm
- 抽象层集成测试必须只用公共 RHI 接口
- 新场景如果暴露的是 RHI 根因，要先修 RHI，再修测试
特别注意：
sphere这类场景承担了firstSet != 0的验证职责- 不能为了让测试过而绕开 set/binding 语义
6. 推荐构建命令
配置：
cmake -S . -B build -A x64
常用增量构建：
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 -N -C Debug
全量跑测试：
ctest --test-dir build -C Debug --output-on-failure
7. 常用验证命令
RHI 单测：
build\tests\RHI\unit\Debug\rhi_unit_tests.exe
抽象层集成测试示例：
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
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。
推荐顺序：
- 最小相机常量 / 每物体常量
- 基础 opaque pass
- render target / depth target 管理
- 最小材质系统
- 新的场景级集成测试
工作方式：
- 上层只能依赖 RHI 抽象
- 一旦暴露 RHI 根因，及时回到底层修复
- 每个阶段完成后立刻验证并提交
9. 文档入口
- 项目介绍与目录总览：
- RHI 核心设计文档：
- 测试规范：