XCEngine/AGENT.md

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模块总览

工程实践约束：

• 抽象层测试只能依赖公共 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

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. 推荐构建命令

配置：

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。

推荐顺序：

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

工作方式：

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

9. 文档入口

• 项目介绍与目录总览：
  • README.md
• RHI 核心设计文档：
  • RHI模块总览
• 测试规范：
  • TEST_SPEC.md