xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refresh repository entry guides

Browse Source
This commit is contained in:
ssdfasd
2026-03-29 01:55:36 +08:00
parent 6683e3c299
commit b0427b7091
2 changed files with 551 additions and 689 deletions
Download Patch File Download Diff File Expand all files Collapse all files

322
AGENT.md
View File

@@ -1,187 +1,291 @@
# XCEngine Agent Guide
这个文件面向进入当前工作区的开发者 / Codex / Agent，目标是快速建立对当前工程状态的正确认知，避免重新踩已经处理过的 RHI 问题。
这个文件面向进入当前仓库的开发者 / Codex / Agent。目标不是介绍项目，而是快速建立对“当前工程状态、真实约束、推荐入口与协作方式”的统一认知。
## 1. 当前工程焦点
项目介绍与目录总览看 [README.md](README.md)；设计原则与当前测试规则以本文为准。
当前工程已经不再处于“先把 RHI 补到能跑起来”的阶段，而是处于：
## 1. 先看什么
- RHI 抽象层已经可用
- 可以开始继续向上做基础渲染管线
- 上层实现过程中继续反向驱动 RHI 精化
进入仓库后，优先读这几份文档：
当前最重要的原则不是“继续堆抽象”，而是：
1. [AGENT.md](AGENT.md)
2. [README.md](README.md)
3. [docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
4. [docs/plan/Renderer模块设计与实现.md](docs/plan/Renderer模块设计与实现.md)
5. [tests/TEST_SPEC.md](tests/TEST_SPEC.md)
- 先保证功能正确
- 保证 D3D12 / OpenGL 双后端不被破坏
- 每修一个真实问题，都补对应测试
其中：
## 2. RHI 当前状态
- `RHI模块总览.md` 是 RHI 设计原则基线
- `Renderer模块设计与实现.md` 是当前渲染层演进方向
- `TEST_SPEC.md` 是测试组织、GT 图规则和 CMake/CTest 入口基线
RHI 当前重点支持：
## 2. 当前工程状态
### 2.1 引擎整体
当前仓库已经不再处于“先把底层跑起来”的阶段，而是处于：
- `RHI` 已具备可维护的三后端基线
- `Rendering` 已形成正式模块，不再只是零散 sample 代码
- `Editor` 已能通过引擎渲染链路驱动 viewport
- `Scripting` 已具备 Mono 托管程序集构建和基础运行时测试
当前主线工作不应继续封闭式堆 RHI，而应在不破坏测试基线的前提下，继续推进渲染、编辑器和脚本三者的对接。
### 2.2 RHI
当前正式支持的后端：
- `D3D12`
- `OpenGL`
- `Vulkan`
近期已经完成的关键收敛：
当前 RHI 的基本判断：
- `pipeline layout` 负责拥有并管理 descriptor set 元数据
- D3D12 / OpenGL 两个后端的 descriptor 绑定都已经 `set-aware`
- `firstSet` 路径已经被系统性修过并补测
- OpenGL shader 从内存源码创建时，不再依赖偶然的 NUL 终止
- OpenGL 单 shader 编译路径现在会正确记录 `ShaderType`
- OpenGL 的 compute/UAV 绑定已经有真实 dispatch + 回读验证
- RHI 抽象层集成测试统一采用“一场景一张 `GT.ppm`，双后端都与同一 GT 比对”
- 抽象层已经可用
- 后端差异路径已经被一轮轮集成测试逼出了很多真实问题并修过
- 但它仍然不是“完全封顶”的模块
结论：
看到上层新问题时，不要本能地用“测试特判 / 测试绕过 / include 私有头”来糊过去；优先判断是不是 RHI 根因。
- 现在可以直接开始做基础渲染管线
- 但不要假设 RHI 已经“绝对最终完成”
- 后续上层实现很可能继续暴露新的真实缺口，这是正常状态
### 2.3 Rendering
## 3. 设计原则
当前 `engine/include/XCEngine/Rendering/` 与 `engine/src/Rendering/` 已经落地：
RHI 模块始终遵循：
- `RenderSceneExtractor`
- `RenderResourceCache`
- `RenderSurface`
- `CameraRenderer`
- `SceneRenderer`
- `BuiltinForwardPipeline`
- `RenderMaterialUtility`
- 求同存异
- 分层抽象
- 特性降级
- 谨慎逃逸
这意味着：
核心设计文档：
- 当前已经存在正式的场景渲染运行时
- 不要再把真实渲染逻辑塞回 `mvs/` 样例里长期存活
- 新渲染功能优先落在 `Rendering` 模块与配套测试中
- [RHI模块总览](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
### 2.4 Editor
工程实践约束：
当前 editor 的关键事实：
- 抽象层测试只能依赖公共 RHI 接口
- 如果为了让抽象层测试通过而不得不 include 后端私有头文件，优先修 RHI 本身
- 功能不破坏永远高于“为了抽象而抽象”
- 它仍然是 `D3D12` 宿主应用
- Scene/Game viewport 已通过离屏纹理接入引擎 `SceneRenderer`
- `editor/src/Viewport/ViewportHostService.h` 当前直接依赖 `RHI::D3D12Device`
- Scene view 相机控制已经有独立控制器与单测
## 4. 当前测试体系
因此当前要注意：
RHI 测试分四层：
- 引擎渲染逻辑应继续收敛在 `engine/Rendering`
- editor 只是宿主，不应复制一套独立 renderer
- editor 侧若要继续做 viewport 能力，应尽量围绕 `RenderSurface` 和引擎场景渲染入口扩展
### 2.5 Scripting
当前脚本链路：
- `managed/XCEngine.ScriptCore/`：托管 API
- `managed/GameScripts/`：托管测试 / 示例脚本
- `engine/include/XCEngine/Scripting/` 与 `engine/src/Scripting/`：原生运行时桥接
当前脚本构建依赖：
- .NET SDK
- `参考/Fermion/Fermion/external/mono` 下的 Mono 依赖
如果环境不完整，可以通过 `-DXCENGINE_ENABLE_MONO_SCRIPTING=OFF` 暂时关闭。
## 3. 当前测试基线
### 3.1 测试树
当前主要测试模块：
- `tests/Core/`
- `tests/Memory/`
- `tests/Threading/`
- `tests/Debug/`
- `tests/Components/`
- `tests/Scene/`
- `tests/Scripting/`
- `tests/Rendering/`
- `tests/RHI/`
- `tests/Resources/`
- `tests/Input/`
- `tests/Editor/`
### 3.2 RHI 测试分层
`tests/RHI/` 当前分为五块：
- `tests/RHI/unit/`
- 抽象层单元测试
- `tests/RHI/integration/`
- 抽象层集成测试
- `tests/RHI/D3D12/`
- D3D12 后端专项测试
- `tests/RHI/OpenGL/`
- OpenGL 后端专项测试
- `tests/RHI/Vulkan/`
当前关键测试目标：
边界规则：
- `rhi_unit_tests`
- `rhi_integration_minimal`
- `rhi_integration_triangle`
- `rhi_integration_quad`
- `rhi_integration_sphere`
- `rhi_d3d12_tests`
- `rhi_opengl_tests`
- `tests/RHI/unit/` 和 `tests/RHI/integration/` 只能依赖公共 RHI 抽象
- 后端私有 API / 原生句柄 / 后端特有断言，只能进对应后端目录
- 如果抽象层测试必须 include 后端头才能过，优先修 RHI
测试规范总文档：
### 3.3 RHI 抽象层集成测试
- [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/`
- `minimal`
- `triangle`
- `quad`
- `sphere`
- `backpack`
必须遵守：
- 每个场景目录只维护一张 `GT.ppm`
- D3D12 与 OpenGL 都与同一张 `GT.ppm` 比对
- 截图文件可以按后端区分，例如：
- `quad_d3d12.ppm`
- `quad_opengl.ppm`
- 抽象层集成测试必须只用公共 RHI 接口
- 新场景如果暴露的是 RHI 根因，要先修 RHI，再修测试
1. 每个场景目录只维护一张 `GT.ppm`
2. `D3D12 / OpenGL / Vulkan` 都与同一张 `GT.ppm` 做比对
3. 运行输出可以按后端区分命名，但 GT 不能拆成多份
4. 场景测试代码只能使用公共 RHI 接口
特别注意：
### 3.4 Rendering 测试
- `sphere` 这类场景承担了 `firstSet != 0` 的验证职责
- 不能为了让测试过而绕开 set/binding 语义
当前 `tests/Rendering/` 已经存在：
## 6. 推荐构建命令
- `unit/`
- `integration/backpack_scene`
- `integration/textured_quad_scene`
- `integration/transparent_material_scene`
- `integration/cull_material_scene`
- `integration/depth_sort_scene`
- `integration/material_state_scene`
- `integration/offscreen_scene`
配置：
结论：
- 新渲染功能不需要再从零搭测试体系
- 直接往现有 `tests/Rendering` 扩展即可
## 4. 已知关键约束
### 4.1 始终遵循 RHI 设计文档
涉及 RHI 抽象、后端收敛、接口新增时，始终以：
- [docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
作为原则基线，而不是局部方便优先。
### 4.2 功能正确优先于抽象表面整洁
允许为了功能正确做必要重构，但不允许：
- 测试特判掩盖真实后端缺陷
- 为了不改底层而污染抽象层测试
- 为了“少动代码”保留明显错误的对象边界
### 4.3 backpack 资源导入行为必须统一
这是当前仓库里已经踩过的真实坑。
规则：
- editor / runtime / rendering tests / rhi abstraction tests 的 backpack 导入行为必须保持一致
- 不要只在某个测试路径里额外加 `MeshImportFlags::FlipUVs`
- 否则很容易出现 editor 显示正确、测试里 UV 错乱的假分叉
### 4.4 editor 是宿主，不是第二套渲染器
如果 editor viewport 有问题，优先判断：
- 是 `Rendering` 模块问题
- 是 `RenderSurface` / RHI 输出问题
- 还是 editor 宿主接线问题
不要把问题简单归因为“editor 特殊”，然后在 editor 里复制一份独立渲染逻辑。
## 5. 推荐构建入口
### 5.1 配置
```bash
cmake -S . -B build -A x64
```
常用增量构建：
如果缺 Mono：
```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
cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
```
查看测试：
### 5.2 常用构建 target
```bash
ctest --test-dir build -N -C Debug
cmake --build build --config Debug --target XCEngine
cmake --build build --config Debug --target XCVolumeRendererUI2
cmake --build build --config Debug --target xcengine_managed_assemblies
cmake --build build --config Debug --target rhi_all_tests
cmake --build build --config Debug --target rendering_unit_tests
cmake --build build --config Debug --target editor_tests
cmake --build build --config Debug --target scripting_tests
```
全量跑测试：
补充：
- 编辑器 target 名称是 `XCVolumeRendererUI2`
- 输出文件名是 `editor/bin/<Config>/XCEngine.exe`
## 6. 推荐验证入口
### 6.1 全量
```bash
ctest --test-dir build -C Debug --output-on-failure
```
## 7. 常用验证命令
RHI 单测：
### 6.2 RHI
```bash
build\tests\RHI\unit\Debug\rhi_unit_tests.exe
cmake --build build --config Debug --target rhi_abstraction_tests
cmake --build build --config Debug --target rhi_backend_tests
```
抽象层集成测试示例：
### 6.3 Rendering
```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
cmake --build build --config Debug --target rendering_unit_tests
cmake --build build --config Debug --target rendering_integration_backpack_scene
```
### 6.4 Editor / Scripting
```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
cmake --build build --config Debug --target editor_tests
cmake --build build --config Debug --target scripting_tests
```
## 8. 后续推荐方向
## 7. 当前最合理的工作方式
当前最合理的后续工作是直接做基础渲染管线，而不是继续封闭式打磨 RHI。
适用于当前仓库的协作方式：
推荐顺序：
1. 先在现有模块边界里定位问题，不要绕开体系补 sample 代码
2. 改动后立即补或更新测试
3. 先跑和改动最相关的测试，再决定是否扩大全量验证
4. 每个阶段完成后尽快提交，保持工作区清晰
1. 最小相机常量 / 每物体常量
2. 基础 opaque pass
3. render target / depth target 管理
4. 最小材质系统
5. 新的场景级集成测试
特别是涉及：
工作方式：
- `RHI`
- `Rendering`
- `Editor viewport`
- `Scripting runtime`
- 上层只能依赖 RHI 抽象
- 一旦暴露 RHI 根因，及时回到底层修复
- 每个阶段完成后立刻验证并提交
这些模块时，必须避免“表面修好了，但测试基线退化”的情况。
## 9. 文档入口
## 8. 文档入口
- 项目介绍与目录总览：
- [README.md](README.md)
- RHI 核心设计文档：
- [RHI模块总览](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
- 测试规范：
- [TEST_SPEC.md](tests/TEST_SPEC.md)
- 项目概览与目录树：[README.md](README.md)
- RHI 设计基线：[docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
- Renderer 设计文档：[docs/plan/Renderer模块设计与实现.md](docs/plan/Renderer模块设计与实现.md)
- 测试规范：[tests/TEST_SPEC.md](tests/TEST_SPEC.md)

918
README.md
View File

@@ -1,615 +1,373 @@
# XCEngine
基于 DirectX 12 的模块化游戏引擎，支持体积渲染、跨平台渲染后端和核心模块单元测试。
XCEngine 是一个正在持续开发中的模块化 C++ 游戏引擎。当前仓库已经形成了较完整的底座：
当前工程状态、RHI 近期收敛结果、推荐构建与测试入口，请优先参考 [AGENT.md](AGENT.md)。
- `RHI` 抽象层已稳定覆盖 `D3D12 / OpenGL / Vulkan`
- `Rendering` 模块已经落地最小可用的场景渲染链路
- `editor/` 已接入基于引擎渲染链路的 Scene/Game viewport
- `managed/` 已具备基于 Mono 的 C# 运行时与托管程序集构建链路
- `tests/` 已形成按模块分层的单元测试与集成测试体系
## 项目概述
如果你是第一次进入当前仓库，先看 [AGENT.md](AGENT.md)。它更偏向“当前工程状态、协作约束与推荐入口”。
XCEngine 是一个正在开发中的模块化 C++ 游戏引擎，采用 RHI（Render Hardware Interface）抽象层设计，支持 DirectX 12 和 OpenGL 4.6+ 多种渲染 API。项目采用模块化设计，包含核心库、示例程序和单元测试。
## 当前状态
## 技术栈
- 核心引擎库位于 `engine/`，包含 Audio、Components、Core、Debug、Input、Memory、Platform、Rendering、Resources、RHI、Scene、Scripting、Threading。
- RHI 当前正式支持 `D3D12 / OpenGL / Vulkan` 三后端，且抽象层与后端层测试都已经落地。
- Rendering 当前已具备 `RenderSceneExtractor`、`RenderResourceCache`、`SceneRenderer`、`CameraRenderer`、`BuiltinForwardPipeline`。
- Editor 当前是 `D3D12` 宿主应用，但场景绘制已通过引擎 `Rendering + RHI` 链路输出到离屏纹理，再接入 ImGui 面板。
- Managed scripting 当前通过 `managed/XCEngine.ScriptCore` 与 `managed/GameScripts` 构建托管程序集；默认启用 Mono 运行时集成。
- 默认示例工程位于 `project/`，已包含基础场景、背包模型与脚本资产目录。
- **渲染 API**: DirectX 12, OpenGL 4.6+
- **语言**: C++17
- **构建系统**: CMake 3.15+
- **测试框架**: Google Test
- **UI**: ImGui（用于编辑器）
## 环境要求
## 项目结构
建议在 Windows 上构建当前仓库。
- Windows 10/11
- Visual Studio 2022 / MSVC v143
- CMake 3.15+
- .NET SDK
- Vulkan SDK
- Git LFS
如果启用默认脚本构建，还需要：
- `参考/Fermion/Fermion/external/mono` 下可用的 Mono 头文件、静态库与 `mscorlib.dll`
如果本地暂时没有 Mono 依赖，可以在配置时关闭脚本构建：
```bash
cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
```
如果你需要 `mvs/3DGS-Unity/room.ply` 这类大文件样例，请确保已经执行过 Git LFS 拉取。
## 构建
### 1. 配置
```bash
cmake -S . -B build -A x64
```
### 2. 全量编译
```bash
cmake --build build --config Debug
```
### 3. 常用增量 target
```bash
cmake --build build --config Debug --target XCEngine
cmake --build build --config Debug --target XCVolumeRendererUI2
cmake --build build --config Debug --target xcengine_managed_assemblies
cmake --build build --config Debug --target rhi_all_tests
cmake --build build --config Debug --target rendering_unit_tests
cmake --build build --config Debug --target editor_tests
cmake --build build --config Debug --target scripting_tests
```
说明：
- 编辑器 CMake target 名称仍然是历史遗留的 `XCVolumeRendererUI2`，但输出文件名是 `XCEngine.exe`
- 顶层 CMake 当前会纳入 `engine/`、`editor/`、`managed/`、`mvs/RenderDoc/` 与 `tests/`
## 测试
推荐始终通过 CMake / CTest 驱动测试。
### 列出测试
```bash
ctest --test-dir build -N -C Debug
```
### 运行全部测试
```bash
ctest --test-dir build -C Debug --output-on-failure
```
### 常用测试 target
```bash
cmake --build build --config Debug --target rhi_abstraction_tests
cmake --build build --config Debug --target rhi_backend_tests
cmake --build build --config Debug --target rendering_unit_tests
cmake --build build --config Debug --target editor_tests
cmake --build build --config Debug --target scripting_tests
```
更完整的测试规则见 [tests/TEST_SPEC.md](tests/TEST_SPEC.md)。
## 目录结构
下面的目录树用于表达当前仓库的实际入口结构与模块边界。
```text
XCEngine/
├── engine/ # 核心引擎库
│ ├── include/XCEngine/
│ │ ├── Audio/ # 音频系统
│ │ │ ├── AudioSystem.h # 音频系统主类
│ │ │ ├── AudioTypes.h # 音频类型定义
│ │ │ ├── AudioConfig.h # 音频配置
│ │ │ ├── AudioMixer.h # 音频混音器
│ │ │ ├── HRTF.h # HRTF 空间音频
│ │ │ ├── FFTFilter.h # FFT 滤波器
│ │ │ ├── Reverbation.h # 混响效果
│ │ │ ├── Equalizer.h # 均衡器
│ │ │ ├── IAudioEffect.h # 音频效果接口
│ │ │ ├── IAudioBackend.h # 音频后端接口
│ │ │ └── WindowsAudioBackend.h # Windows 音频后端
│ │ ├── Components/ # 游戏组件系统
│ │ │ ├── Component.h # 组件基类
│ │ │ ├── GameObject.h # 游戏对象
│ │ │ ├── TransformComponent.h # 变换组件
│ │ │ ├── AudioSourceComponent.h # 音频源组件
│ │ │ └── AudioListenerComponent.h # 音频监听器组件
│ │ ├── Core/ # 核心基础模块
│ │ │ ├── Asset/ # 资源系统核心
│ │ │ │ ├── IResource.h # 资源接口
│ │ │ │ ├── ResourceTypes.h # 资源类型定义
│ │ │ │ ├── ResourceHandle.h # 资源句柄
│ │ │ │ ├── ResourceManager.h # 资源管理器
│ │ │ │ ├── ResourceCache.h # 资源缓存
│ │ │ │ ├── AsyncLoader.h # 异步加载器
│ │ │ │ ├── ResourceDependencyGraph.h # 依赖图
│ │ │ │ └── ImportSettings.h # 导入设置基类
│ │ │ ├── IO/ # IO 系统
│ │ │ │ ├── IResourceLoader.h # 资源加载器接口
│ │ │ │ ├── ResourceFileSystem.h # 资源文件系统
│ │ │ │ ├── ResourcePath.h # 资源路径
│ │ │ │ ├── FileArchive.h # 文件归档
│ │ │ │ └── ResourcePackage.h # 资源包
│ │ │ ├── Containers/ # 容器模块
│ │ │ │ ├── Array.h # 动态数组
│ │ │ │ ├── String.h # 字符串类
│ │ │ │ ├── HashMap.h # 哈希表
│ │ │ │ └── Containers.h # 模块统一头文件
│ │ │ ├── Math/ # 数学库
│ │ │ │ ├── Vector2.h # 二维向量
│ │ │ │ ├── Vector3.h # 三维向量
│ │ │ │ ├── Vector4.h # 四维向量
│ │ │ │ ├── Matrix3.h # 3x3 矩阵
│ │ │ │ ├── Matrix4.h # 4x4 矩阵
│ │ │ │ ├── Quaternion.h # 四元数
│ │ │ │ ├── Transform.h # 变换
│ │ │ │ ├── Color.h # 颜色
│ │ │ │ ├── Rect.h # 矩形
│ │ │ │ ├── Sphere.h # 球体
│ │ │ │ ├── Box.h # 盒子
│ │ │ │ ├── Plane.h # 平面
│ │ │ │ ├── Ray.h # 射线
│ │ │ │ ├── AABB.h # 轴对齐包围盒
│ │ │ │ ├── Bounds.h # 包围体
│ │ │ │ ├── Frustum.h # 视锥体
│ │ │ │ └── Math.h # 数学库统一头文件
│ │ │ ├── Layer.h # 层级
│ │ │ ├── LayerStack.h # 层级栈
│ │ │ ├── Types.h # 基础类型别名
│ │ │ ├── RefCounted.h # 引用计数基类
│ │ │ ├── SmartPtr.h # 智能指针
│ │ │ ├── Event.h # 事件系统
│ │ │ └── FileWriter.h # 文件写入
│ │ ├── Debug/ # 调试与日志模块
│ │ │ ├── Logger.h # 日志系统
│ │ │ ├── LogLevel.h # 日志级别
│ │ │ ├── LogCategory.h # 日志分类
│ │ │ ├── LogEntry.h # 日志条目
│ │ │ ├── ConsoleLogSink.h # 控制台输出
│ │ │ ├── FileLogSink.h # 文件输出
│ │ │ ├── ILogSink.h # 日志槽接口
│ │ │ ├── Debug.h # 调试宏
│ │ │ └── Profiler.h # 性能分析
│ │ ├── Memory/ # 内存管理模块
│ │ │ ├── Allocator.h # 分配器接口
│ │ │ ├── LinearAllocator.h # 线性分配器
│ │ │ ├── PoolAllocator.h # 内存池分配器
│ │ │ ├── ProxyAllocator.h # 代理分配器
│ │ │ └── MemoryManager.h # 全局内存管理器
│ │ ├── Threading/ # 线程模块
│ │ │ ├── Thread.h # 线程类
│ │ │ ├── Mutex.h # 互斥锁
│ │ │ ├── SpinLock.h # 自旋锁
│ │ │ ├── ReadWriteLock.h # 读写锁
│ │ │ ├── Task.h # 任务基类
│ │ │ ├── LambdaTask.h # Lambda 任务
│ │ │ ├── TaskGroup.h # 任务组
│ │ │ ├── TaskSystem.h # 任务系统
│ │ │ ├── TaskSystemConfig.h # 任务系统配置
│ │ │ └── Threading.h # 线程模块统一头文件
│ │ ├── Platform/ # 平台抽象层
│ │ │ ├── PlatformTypes.h # 平台类型
│ │ │ ├── IPlatform.h # 平台接口
│ │ │ ├── IWindow.h # 窗口接口
│ │ │ ├── IFileSystem.h # 文件系统接口
│ │ │ ├── IClock.h # 时钟接口
│ │ │ ├── IDynamicLibrary.h # 动态库接口
│ │ │ ├── IDisplayEnumerator.h # 显示枚举接口
│ │ │ ├── GameTime.h # 游戏时间
│ │ │ ├── Window.h # 窗口类
│ │ │ ├── Windows/ # Windows 平台实现
│ │ │ │ ├── WindowsWindow.h
│ │ │ │ └── WindowsInputModule.h
│ │ │ ├── Linux/ # Linux 平台实现
│ │ │ ├── Android/ # Android 平台实现
│ │ │ └── macOS/ # macOS 平台实现
│ │ ├── Input/ # 输入模块
│ │ │ ├── InputTypes.h # 输入类型
│ │ │ ├── InputEvent.h # 输入事件
│ │ │ ├── InputAxis.h # 输入轴
│ │ │ ├── InputModule.h # 输入模块基类
│ │ │ └── InputManager.h # 输入管理器
│ │ ├── Resources/ # 资源管理模块 (按类型分目录)
│ │ │ ├── Texture/ # 纹理资源
│ │ │ │ ├── Texture.h
│ │ │ │ ├── TextureLoader.h
│ │ │ │ └── TextureImportSettings.h
│ │ │ ├── Mesh/ # 网格资源
│ │ │ │ ├── Mesh.h
│ │ │ │ ├── MeshLoader.h
│ │ │ │ └── MeshImportSettings.h
│ │ │ ├── Shader/ # 着色器资源
│ │ │ │ ├── Shader.h
│ │ │ │ └── ShaderLoader.h
│ │ │ ├── Material/ # 材质资源
│ │ │ │ ├── Material.h
│ │ │ │ └── MaterialLoader.h
│ │ │ ├── AudioClip/ # 音频资源
│ │ │ │ ├── AudioClip.h
│ │ │ │ └── AudioLoader.h
│ │ │ └── Resources.h # 资源模块统一头文件
│ │ ├── Scene/ # 场景管理模块
│ │ │ ├── Scene.h # 场景类
│ │ │ └── SceneManager.h # 场景管理器
│ │ └── RHI/ # 渲染硬件接口抽象层
│ │ ├── RHITypes.h # RHI 类型定义
│ │ ├── RHIEnums.h # RHI 枚举
│ │ ├── RHICapabilities.h # 硬件能力查询
│ │ ├── RHIFactory.h # 设备工厂
│ │ ├── RHIDevice.h # 渲染设备抽象
│ │ ├── RHICommandQueue.h # 命令队列抽象
│ │ ├── RHICommandList.h # 命令列表抽象
│ │ ├── RHIBuffer.h # 缓冲区抽象
│ │ ├── RHITexture.h # 纹理抽象
│ │ ├── RHIShader.h # 着色器抽象
│ │ ├── RHISampler.h # 采样器抽象
│ │ ├── RHIFence.h # 同步栅栏抽象
│ │ ├── RHISwapChain.h # 交换链抽象
│ │ ├── RHIPipelineState.h # 管线状态抽象
│ │ ├── RHIPipelineLayout.h # 管线布局抽象
│ │ ├── RHIDescriptorPool.h # 描述符池抽象
│ │ ├── RHIDescriptorSet.h # 描述符集抽象
│ │ ├── RHIRenderPass.h # 渲染通道抽象
│ │ ├── RHIFramebuffer.h # 帧缓冲抽象
│ │ ├── RHIResource.h # 资源基类
│ │ ├── RHIResourceView.h # 资源视图抽象
│ │ ├── OpenGL/ # OpenGL 后端实现
│ │ │ ├── OpenGLDevice.h
│ │ │ ├── OpenGLCommandQueue.h
│ │ │ ├── OpenGLCommandList.h
│ │ │ ├── OpenGLSwapChain.h
│ │ │ ├── OpenGLPipelineState.h
│ │ │ ├── OpenGLBuffer.h
│ │ │ ├── OpenGLTexture.h
│ │ │ ├── OpenGLShader.h
│ │ │ ├── OpenGLSampler.h
│ │ │ ├── OpenGLFence.h
│ │ │ ├── OpenGLVertexArray.h
│ │ │ ├── OpenGLRenderTargetView.h
│ │ │ ├── OpenGLDepthStencilView.h
│ │ │ ├── OpenGLFramebuffer.h
│ │ │ ├── OpenGLRenderPass.h
│ │ │ ├── OpenGLResourceView.h
│ │ │ ├── OpenGLDescriptorPool.h
│ │ │ ├── OpenGLDescriptorSet.h
│ │ │ ├── OpenGLTextureUnitAllocator.h
│ │ │ ├── OpenGLUniformBufferManager.h
│ │ │ └── OpenGLScreenshot.h
│ │ └── D3D12/ # DirectX 12 后端实现
│ │ ├── D3D12Device.h
│ │ ├── D3D12CommandQueue.h
│ │ ├── D3D12CommandAllocator.h
│ │ ├── D3D12CommandList.h
│ │ ├── D3D12SwapChain.h
│ │ ├── D3D12PipelineState.h
│ │ ├── D3D12Buffer.h
│ │ ├── D3D12Texture.h
│ │ ├── D3D12Shader.h
│ │ ├── D3D12Sampler.h
│ │ ├── D3D12Fence.h
│ │ ├── D3D12DescriptorHeap.h
│ │ ├── D3D12DescriptorSet.h
│ │ ├── D3D12RootSignature.h
│ │ ├── D3D12PipelineLayout.h
│ │ ├── D3D12RenderTargetView.h
│ │ ├── D3D12DepthStencilView.h
│ │ ├── D3D12ShaderResourceView.h
│ │ ├── D3D12UnorderedAccessView.h
│ │ ├── D3D12ConstantBufferView.h
│ │ ├── D3D12ResourceView.h
│ │ ├── D3D12QueryHeap.h
│ │ ├── D3D12RenderPass.h
│ │ ├── D3D12Framebuffer.h
│ │ ├── D3D12Screenshot.h
│ │ ├── D3D12Types.h
│ │ ├── D3D12Enums.h
│ │ └── D3D12Common.h
│ ├── src/ # 实现文件
│ │ ├── Audio/
│ │ ├── Containers/
├── .gitattributes
├── .gitignore
├── AGENT.md
├── CMakeLists.txt
├── README.md
├── build/ # 本地构建输出
├── docs/
│ ├── api/ # API 文档
│ ├── issues/ # 跟踪中的设计 / 实现问题
│ ├── plan/ # 设计文档、阶段规划、归档方案
│ │ ├── Renderer模块设计与实现.md
│ │ └── end/
│ │ └── RHI模块设计与实现/
│ │ └── RHI模块总览.md
│ ├── used/
│ ├── api-skill.md
│ ├── blueprint-skill.md
│ └── blueprint.md
├── editor/
│ ├── CMakeLists.txt
│ ├── README.md
│ ├── resources/
│ │ └── Icons/
│ ├── src/
│ │ ├── Actions/
│ │ ├── Commands/
│ │ ├── ComponentEditors/
│ │ ├── Core/
│ │ │ ├── Asset/ # Core/Asset 实现
│ │ │ └── IO/ # Core/IO 实现
│ │ ├── Layers/
│ │ ├── Layout/
│ │ ├── Managers/
│ │ ├── panels/
│ │ ├── Platform/
│ │ ├── UI/
│ │ ├── Utils/
│ │ ├── Viewport/
│ │ ├── Application.cpp
│ │ ├── Application.h
│ │ ├── EditorApp.rc
│ │ ├── Theme.cpp
│ │ ├── Theme.h
│ │ └── main.cpp
│ └── bin/ # 编辑器输出目录，输出名为 XCEngine.exe
├── engine/
│ ├── CMakeLists.txt
│ ├── include/
│ │ └── XCEngine/
│ │ ├── Audio/
│ │ ├── Components/
│ │ ├── Core/
│ │ │ ├── Asset/
│ │ │ ├── Containers/
│ │ │ ├── IO/
│ │ │ └── Math/
│ │ ├── Debug/
│ │ ├── Input/
│ │ ├── Memory/
│ │ ├── Platform/
│ │ │ └── Windows/
│ │ ├── Rendering/
│ │ │ ├── Pipelines/
│ │ │ ├── CameraRenderRequest.h
│ │ │ ├── CameraRenderer.h
│ │ │ ├── RenderCameraData.h
│ │ │ ├── RenderContext.h
│ │ │ ├── RenderMaterialUtility.h
│ │ │ ├── RenderPipeline.h
│ │ │ ├── RenderPipelineAsset.h
│ │ │ ├── RenderResourceCache.h
│ │ │ ├── RenderSceneExtractor.h
│ │ │ ├── RenderSurface.h
│ │ │ ├── SceneRenderer.h
│ │ │ └── VisibleRenderObject.h
│ │ ├── Resources/
│ │ │ ├── AudioClip/
│ │ │ ├── Material/
│ │ │ ├── Mesh/
│ │ │ ├── Shader/
│ │ │ └── Texture/
│ │ ├── RHI/
│ │ │ ├── D3D12/
│ │ │ ├── OpenGL/
│ │ │ ├── Vulkan/
│ │ │ ├── RHIBuffer.h
│ │ │ ├── RHICapabilities.h
│ │ │ ├── RHICommandList.h
│ │ │ ├── RHICommandQueue.h
│ │ │ ├── RHIDescriptorPool.h
│ │ │ ├── RHIDescriptorSet.h
│ │ │ ├── RHIDevice.h
│ │ │ ├── RHIEnums.h
│ │ │ ├── RHIFactory.h
│ │ │ ├── RHIFence.h
│ │ │ ├── RHIFramebuffer.h
│ │ │ ├── RHIPipelineLayout.h
│ │ │ ├── RHIPipelineState.h
│ │ │ ├── RHIRenderPass.h
│ │ │ ├── RHIResource.h
│ │ │ ├── RHIResourceView.h
│ │ │ ├── RHISampler.h
│ │ │ ├── RHIScreenshot.h
│ │ │ ├── RHIShader.h
│ │ │ ├── RHISwapChain.h
│ │ │ ├── RHITexture.h
│ │ │ └── RHITypes.h
│ │ ├── Scene/
│ │ ├── Scripting/
│ │ │ └── Mono/
│ │ └── Threading/
│ ├── src/
│ │ ├── Audio/
│ │ ├── Components/
│ │ ├── Core/
│ │ │ ├── Asset/
│ │ │ ├── Containers/
│ │ │ ├── IO/
│ │ │ └── Math/
│ │ ├── Debug/
│ │ ├── Math/
│ │ ├── Input/
│ │ ├── Memory/
│ │ ├── Threading/
│ │ ├── Platform/
│ │ │ └── Windows/
│ │ ├── Input/
│ │ ├── Rendering/
│ │ │ └── Pipelines/
│ │ ├── Resources/
│ │ │ ├── Texture/
│ │ │ ├── AudioClip/
│ │ │ ├── Material/
│ │ │ ├── Mesh/
│ │ │ ├── Shader/
│ │ │ ├── Material/
│ │ │ └── AudioClip/
│ │ │ └── Texture/
│ │ ├── RHI/
│ │ │ ├── D3D12/
│ │ │ ├── OpenGL/
│ │ │ └── Vulkan/
│ │ ├── Scene/
│ │ └── RHI/
│ │ ├── D3D12/
│ │ ├── OpenGL/
│ │ └── RHIFactory.cpp
│ └── third_party/ # 第三方库
│ ├── kissfft/ # FFT 库
│ ├── stb/ # 图像处理库 (stb_image, stb_image_write)
│ ├── GLAD/ # OpenGL 加载器
│ └── renderdoc/ # RenderDoc 调试库
│
├── editor/ # 编辑器 UI 应用程序
│ ├── src/ # 编辑器源代码
│ │ ├── Application.cpp/h # 编辑器应用入口
│ │ ├── main.cpp # 主函数
│ │ ├── Core/ # 编辑器核心
│ │ ├── Layers/ # 编辑器层级
│ │ ├── Managers/ # 管理器
│ │ ├── panels/ # 编辑器面板
│ │ └── UI/ # UI 控件
│ ├── bin/ # 资源文件和可执行文件
│ └── build/ # 构建目录
│
├── tests/ # 单元测试
│ ├── math/ # 数学库测试
│ ├── containers/ # 容器测试
│ ├── memory/ # 内存管理测试
│ ├── threading/ # 线程模块测试
│ ├── debug/ # 调试模块测试
│ ├── core/ # 核心模块测试
│ │ ├── Asset/ # Core/Asset 模块测试
│ │ └── IO/ # Core/IO 模块测试
│ ├── Components/ # 组件测试
│ ├── Scene/ # 场景测试
│ ├── Resources/ # 资源管理测试
│ │ ├── Texture/
│ │ ├── Mesh/
│ │ ├── Scripting/
│ │ │ └── Mono/
│ │ └── Threading/
│ ├── third_party/
│ │ ├── assimp/
│ │ ├── GLAD/
│ │ ├── kissfft/
│ │ ├── renderdoc/
│ │ └── stb/
│ └── tools/
│ └── renderdoc_parser/
├── managed/
│ ├── CMakeLists.txt
│ ├── GameScripts/ # 示例 / 验证脚本程序集源码
│ └── XCEngine.ScriptCore/ # 引擎托管 API
├── mvs/
│ ├── 3DGS-Unity/ # Unity 侧 3DGS 参考与资源
│ ├── D3D12/
│ ├── Music fluctuations/
│ ├── OpenGL/
│ ├── RenderDoc/
│ ├── Res/
│ ├── ui/
│ └── VolumeRenderer/
├── project/
│ ├── .xceditor/
│ │ └── imgui_layout.ini
│ ├── Assets/
│ │ ├── Materials/
│ │ ├── Models/
│ │ │ └── backpack/
│ │ ├── Scenes/
│ │ │ └── Main.xc
│ │ └── Scripts/
│ └── Project.xcproject
├── tests/
│ ├── CMakeLists.txt
│ ├── TEST_SPEC.md
│ ├── Components/
│ ├── Core/
│ │ ├── Asset/
│ │ ├── Containers/
│ │ ├── IO/
│ │ └── Math/
│ ├── Debug/
│ ├── Editor/
│ ├── Fixtures/
│ ├── Input/
│ ├── Memory/
│ ├── Rendering/
│ │ ├── integration/
│ │ │ ├── backpack_scene/
│ │ │ ├── cull_material_scene/
│ │ │ ├── depth_sort_scene/
│ │ │ ├── material_state_scene/
│ │ │ ├── offscreen_scene/
│ │ │ ├── textured_quad_scene/
│ │ │ └── transparent_material_scene/
│ │ └── unit/
│ ├── Resources/
│ │ ├── AudioClip/
│ │ ├── Material/
│ │ ├── Mesh/
│ │ ├── Shader/
│ │ └── AudioClip/
│ ├── Input/ # 输入模块测试
│ └── RHI/ # RHI 抽象层测试
│ ├── unit/ # RHI 抽象层单元测试
│ ├── D3D12/ # D3D12 后端测试
│ │ ├── unit/
│ │ └── integration/
│ ├── OpenGL/ # OpenGL 后端测试
│ │ ├── unit/
│ │ └── integration/
│ └── integration/ # RHI 抽象层集成测试
│ ├── fixtures/
│ ├── minimal/
│ ├── triangle/
│ ├── quad/
│ └── sphere/
│
├── mvs/ # 示例程序
│ ├── D3D12/ # DirectX 12 渲染示例
│ ├── OpenGL/ # OpenGL 渲染示例
│ ├── Music fluctuations/ # 音频可视化示例
│ ├── VolumeRenderer/ # 体积渲染器（NanoVDB）
│ ├── RenderDoc/ # RenderDoc 集成示例
│ ├── ui/ # 编辑器 UI 示例
│ └── Res/ # 示例资源文件
│
├── docs/ # 文档
│ ├── api/ # API 文档
│ │ ├── audio/ # 音频系统 API
│ │ ├── components/ # 组件系统 API
│ │ ├── containers/ # 容器 API
│ │ ├── core/ # 核心 API
│ │ ├── d3d12/ # D3D12 API
│ │ ├── debug/ # 调试 API
│ │ ├── math/ # 数学库 API
│ │ ├── memory/ # 内存管理 API
│ │ ├── resources/ # 资源管理 API
│ │ └── main.md # API 文档总索引
│ ├── plan/ # 开发计划与架构设计
│ └── api-skill.md # API 技能文档
│
├── 参考/ # 参考资料
│ └── Fermion/ # 参考项目
│
├── build/ # 构建目录
│
└── imgui.ini # ImGui 配置文件
│ │ └── Texture/
│ ├── RHI/
│ │ ├── CMakeLists.txt
│ │ ├── D3D12/
│ │ │ ├── integration/
│ │ │ └── unit/
│ │ ├── OpenGL/
│ │ │ ├── integration/
│ │ │ └── unit/
│ │ ├── Vulkan/
│ │ │ ├── integration/
│ │ │ ├── unit/
│ │ │ └── TEST_SPEC.md
│ │ ├── integration/
│ │ │ ├── backpack/
│ │ │ ├── fixtures/
│ │ │ ├── minimal/
│ │ │ ├── quad/
│ │ │ ├── sphere/
│ │ │ ├── triangle/
│ │ │ ├── compare_ppm.py
│ │ │ ├── README.md
│ │ │ └── run_integration_test.py
│ │ └── unit/
│ ├── Scene/
│ ├── Scripting/
│ └── Threading/
├── 参考/
│ └── TransformGizmo/
└── .vscode/
```
## 快速开始
## 模块概览
### 前置要求
### Engine
- Windows 10/11
- Visual Studio 2019 或更高版本
- CMake 3.15+
- `RHI`：统一图形 API 抽象，当前三后端并行维护
- `Rendering`：位于 Scene/Resources 与 RHI 之间，负责把场景提取成真实 draw path
- `Resources`：Mesh / Texture / Material / Shader / AudioClip 导入与加载
- `Scene + Components`：游戏对象、相机、灯光、网格与脚本组件
- `Scripting`：原生脚本运行时与 Mono 托管桥接
### 构建项目
### Editor
```bash
# 创建构建目录
mkdir build && cd build
- 当前是 D3D12 桌面宿主应用
- Scene/Game viewport 已走引擎离屏渲染链路
- 包含 Actions、Commands、Panels、Viewport、Managers 等编辑器子系统
# 配置 CMake
cmake .. -A x64
### Tests
# 编译
cmake --build . --config Debug
```
- `tests/RHI/`：RHI 抽象层与三后端测试
- `tests/Rendering/`：渲染链路单元与场景级集成测试
- `tests/Scripting/`：脚本运行时与托管程序集集成测试
- `tests/Editor/`：编辑器动作路由与 Scene viewport 相机控制测试
### 运行测试
## 关键文档入口
```bash
cd build/tests
ctest -C Debug --output-on-failure
```
或直接运行测试可执行文件：
```bash
build/tests/containers/Debug/xcengine_containers_tests.exe
build/tests/memory/Debug/xcengine_memory_tests.exe
build/tests/threading/Debug/xcengine_threading_tests.exe
```
## 核心模块说明
### Audio（音频系统）
- **AudioSystem**: 音频系统主类，管理所有音频设备
- **AudioMixer**: 音频混音器，多通道混合与效果处理
- **HRTF**: 头部相关传输函数，支持空间音频定位
- **FFTFilter**: 快速傅里叶变换滤波器
- **Reverbation**: 混响效果
- **Equalizer**: 音频均衡器
- **WindowsAudioBackend**: Windows WASAPI 音频后端实现
- **AudioSourceComponent**: 音频源组件（用于游戏对象）
- **AudioListenerComponent**: 音频监听器组件（用于游戏对象）
### Components（游戏组件系统）
- **Component**: 组件基类，提供生命周期管理
- **GameObject**: 游戏对象，支持层级结构
- **TransformComponent**: 变换组件，管理位置、旋转、缩放
- **AudioSourceComponent**: 音频源组件
- **AudioListenerComponent**: 音频监听器组件
### Containers（容器）
- **String**: 动态字符串类，支持常用字符串操作
- **Array**: 模板动态数组，自动内存管理
- **HashMap**: 模板哈希表，支持自定义键类型
### Core（核心基础）
- **Types**: 基础类型别名（int8、uint32 等）
- **RefCounted**: 引用计数基类，支持多线程安全释放
- **SmartPtr**: 智能指针实现（Ref、UniqueRef）
- **Event**: 事件系统，支持订阅/发布模式
- **FileWriter**: 文件写入工具
- **Layer/LayerStack**: 层级与层级栈管理
### Platform（平台抽象层）
跨平台抽象接口，支持 Windows、Linux、Android、macOS：
- **IPlatform**: 平台接口
- **IWindow**: 窗口接口
- **IFileSystem**: 文件系统接口
- **IClock**: 时钟接口
- **IDynamicLibrary**: 动态库加载接口
- **IDisplayEnumerator**: 显示设备枚举接口
- **Window**: 窗口实现类
### Input（输入模块）
- **InputManager**: 输入管理器
- **InputModule**: 输入模块基类
- **InputEvent**: 输入事件定义
- **InputAxis**: 输入轴配置
### Debug（调试与日志）
- **Logger**: 分级日志系统（Info、Warning、Error）
- **ConsoleLogSink**: 控制台日志输出
- **FileLogSink**: 文件日志输出
- **Profiler**: 性能分析工具
- **RenderDocCapture**: RenderDoc 帧捕获集成，支持 D3D12/OpenGL GPU 调试
### Memory（内存管理）
- **IAllocator**: 内存分配器接口
- **LinearAllocator**: 线性分配器，适合帧分配
- **PoolAllocator**: 内存池分配器，适合固定大小对象
- **ProxyAllocator**: 代理分配器，跟踪内存使用统计
- **MemoryManager**: 全局内存管理器
### Threading（线程）
- **Thread**: 线程封装类
- **Mutex**: 互斥锁
- **SpinLock**: 自旋锁，适合短临界区
- **ReadWriteLock**: 读写锁
- **TaskSystem**: 多线程任务系统
- **Task/TaskGroup**: 任务和任务组管理
### Math（数学库）
- **Vector2/3/4**: 向量运算
- **Matrix3/4**: 矩阵运算
- **Quaternion**: 四元数
- **Transform**: 变换（位姿）
- **Color**: 颜色
- **Rect**: 矩形
- **Sphere/Box/Plane**: 基本几何体
- **Ray**: 射线
- **AABB/Bounds**: 包围体
- **Frustum**: 视锥体
### Resources（资源管理）
XCEngine 资源系统采用分层架构：
#### Core/Asset（资源系统核心）
- **IResource**: 资源接口基类
- **ResourceTypes**: 资源类型定义（GUID、状态等）
- **ResourceHandle**: 资源句柄，安全引用资源
- **ResourceManager**: 全局资源管理器，资源加载/卸载
- **ResourceCache**: 资源缓存，支持引用计数
- **AsyncLoader**: 异步资源加载器
- **ResourceDependencyGraph**: 资源依赖图管理
#### Core/IO（资源 IO 系统）
- **IResourceLoader**: 资源加载器接口
- **ResourceFileSystem**: 资源文件系统
- **ResourcePath**: 资源路径解析
- **FileArchive**: 文件归档支持
- **ResourcePackage**: 资源包批量管理
#### Resources/<Type>（具体资源类型）
- **Texture**: 纹理资源（Texture.h、TextureLoader.h、TextureImportSettings.h）
- **Mesh**: 网格资源（Mesh.h、MeshLoader.h、MeshImportSettings.h）
- **Shader**: 着色器资源（Shader.h、ShaderLoader.h）
- **Material**: 材质资源（Material.h、MaterialLoader.h）
- **AudioClip**: 音频资源（AudioClip.h、AudioLoader.h）
### Scene（场景管理）
- **Scene**: 场景类，管理场景内的所有游戏对象
- **SceneManager**: 场景管理器，处理场景切换
### RHI（渲染硬件接口）
XCEngine 采用 RHI（Render Hardware Interface）抽象层设计，支持多渲染后端。
#### 设计原则
- **求同存异**: 提取各 API 共同特性，统一抽象接口
- **分层抽象**: 核心抽象层 → 后端实现层 → 平台适配层
- **特性降级**: 后端不支持的特性优雅降级
- **底层逃逸**: 后端特有方法通过重载暴露
#### 抽象接口
- **RHIDevice**: 渲染设备抽象
- **RHICommandQueue**: 命令队列抽象
- **RHICommandList**: 命令列表抽象
- **RHISwapChain**: 交换链抽象
- **RHIPipelineState**: 渲染管线状态抽象
- **RHIPipelineLayout**: 管线布局抽象
- **RHIBuffer/RHITexture**: 资源抽象
- **RHIShader**: 着色器抽象
- **RHISampler**: 采样器抽象
- **RHIFence**: 同步栅栏抽象
- **RHIDescriptorPool**: 描述符池抽象
- **RHIDescriptorSet**: 描述符集抽象
- **RHIRenderPass**: 渲染通道抽象
- **RHIFramebuffer**: 帧缓冲抽象
- **RHIResourceView**: 资源视图抽象
#### 后端实现
- **OpenGL 后端**: OpenGL 4.6+ 支持
- **D3D12 后端**: DirectX 12 支持
当前更偏向“工程协作”和“当前状态”的入口说明见 [AGENT.md](AGENT.md)。
## 测试覆盖
| 模块 | 测试用例数 |
|------|-----------|
| Math | ~4 |
| Containers | ~3 |
| Memory | ~3 |
| Threading | ~3 |
| Debug | ~3 |
| Core | ~10 |
| Components | ~3 |
| Scene | ~2 |
| Resources | ~12 |
| Input | ~2 |
| RHI/unit | ~10 |
| RHI/D3D12 | ~18 (unit + integration) |
| RHI/OpenGL | ~16 (unit + integration) |
## mvs 示例程序
mvs（Multiple Version Samples）展示游戏引擎的各类功能。所有示例均基于 RHI 抽象层开发，可无缝切换 DirectX 12 或 OpenGL 后端。
### D3D12 / OpenGL
跨平台渲染示例，展示如何：
- 初始化 RHI 渲染环境（支持 D3D12/OpenGL）
- 加载和渲染静态网格
- 纹理映射
- 常量缓冲区更新
### RenderDoc
D3D12 + RenderDoc 集成示例，展示如何使用 RenderDoc API 进行 GPU 帧捕获和调试：
- 动态加载 renderdoc.dll
- 帧捕获 API（BeginCapture/EndCapture/TriggerCapture）
- 捕获文件路径和注释设置
> 注意：renderdoc.dll 需单独放置于 `engine/third_party/renderdoc/renderdoc.dll`
### VolumeRenderer
XCEngine 的体积渲染模块，基于 NanoVDB 实现云、烟雾等体积数据的实时渲染：
- NanoVDB 格式体积数据加载
- 光线步进（Ray Marching）渲染
- HDDA 空间跳跃加速
- 体积阴影（Volumetric Shadow）
- 动态光照参数调节
### Music fluctuations
音频可视化示例，基于 FFT 实时分析音频频谱：
- 音频播放与 FFT 分析
- 频谱可视化渲染
- 音频与视觉效果同步
### Editor UI
Unity 风格的编辑器 UI，基于 ImGui 实现：
- 场景层级面板
- 属性检查器
- 游戏视图与场景视图
- 项目资源浏览器
- 控制台日志面板
## 文档
API 文档位于 `docs/api/` 目录，包含各模块的完整 API 参考。
详细设计文档请参考 `docs/plan/` 目录。
当前工程协作入口见 [AGENT.md](AGENT.md)。
- 当前工程协作入口：[AGENT.md](AGENT.md)
- RHI 核心设计文档：[docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
- Renderer 规划与实现说明：[docs/plan/Renderer模块设计与实现.md](docs/plan/Renderer模块设计与实现.md)
- 测试规范：[tests/TEST_SPEC.md](tests/TEST_SPEC.md)
## 许可证
MIT License
当前仓库根目录未看到单独的顶层许可证文件；涉及第三方库时请分别遵循对应依赖目录中的许可证说明。