From b0427b70911e7bdbe5bf93f9a1663375336ea2c9 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Sun, 29 Mar 2026 01:55:36 +0800 Subject: [PATCH] docs: refresh repository entry guides --- AGENT.md | 322 ++++++++++++------- README.md | 918 ++++++++++++++++++++---------------------------------- 2 files changed, 551 insertions(+), 689 deletions(-) diff --git a/AGENT.md b/AGENT.md index d8761eb1..11be9597 100644 --- a/AGENT.md +++ b/AGENT.md @@ -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//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) diff --git a/README.md b/README.md index 151b82a2..2b1f71a1 100644 --- a/README.md +++ b/README.md @@ -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/（具体资源类型） - -- **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 +当前仓库根目录未看到单独的顶层许可证文件；涉及第三方库时请分别遵循对应依赖目录中的许可证说明。