From c479595bf55c33b4a60704f38ab5c0f571c713e4 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Thu, 26 Mar 2026 16:03:15 +0800 Subject: [PATCH] docs: split readme and agent entry guide --- AGENT.md | 187 +++++++++++++++ README.md | 686 ++++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 744 insertions(+), 129 deletions(-) create mode 100644 AGENT.md diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 00000000..d8761eb1 --- /dev/null +++ b/AGENT.md @@ -0,0 +1,187 @@ +# 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) diff --git a/README.md b/README.md index 9a1f9c74..151b82a2 100644 --- a/README.md +++ b/README.md @@ -1,186 +1,614 @@ # XCEngine -XCEngine 是一个模块化的 C++ 游戏引擎工程，当前以 RHI 抽象层为核心推进渲染能力建设。 -目前代码库已经具备可用的 D3D12 / OpenGL 双后端 RHI 基线，并配有单元测试与跨后端集成测试，已经可以作为后续基础渲染管线开发的支撑层继续向上推进。 +基于 DirectX 12 的模块化游戏引擎，支持体积渲染、跨平台渲染后端和核心模块单元测试。 -## 当前状态 +当前工程状态、RHI 近期收敛结果、推荐构建与测试入口，请优先参考 [AGENT.md](AGENT.md)。 -- 构建系统基于 CMake，测试系统基于 Google Test / CTest。 -- RHI 抽象层当前重点支持 `D3D12` 和 `OpenGL` 两套后端。 -- RHI 抽象层已完成一轮针对 `pipeline layout`、`descriptor set`、`set-aware binding`、`shader`、`compute/UAV` 路径的系统性收敛。 -- 抽象层集成测试目前覆盖 `minimal`、`triangle`、`quad`、`sphere` 四个场景。 -- 每个 RHI 抽象层集成测试场景只维护一张基准图 `GT.ppm`，D3D12 与 OpenGL 生成图都与同一张 GT 图进行比对。 -- 以当前状态，RHI 已经适合作为“先开做基础渲染管线，再由上层反向驱动继续完善”的工程基线。 +## 项目概述 -## RHI 设计原则 +XCEngine 是一个正在开发中的模块化 C++ 游戏引擎，采用 RHI（Render Hardware Interface）抽象层设计，支持 DirectX 12 和 OpenGL 4.6+ 多种渲染 API。项目采用模块化设计，包含核心库、示例程序和单元测试。 -RHI 模块遵循 [`docs/plan/end/RHI模块设计与实现/RHI模块总览.md`](docs/plan/end/RHI模块设计与实现/RHI模块总览.md) 中的核心理念： +## 技术栈 -- 求同存异：优先抽取后端共性，避免把上层绑死在单一图形 API 上。 -- 分层抽象：上层功能系统 -> 渲染管线 -> RHI -> 后端 API。 -- 特性降级：后端能力不一致时，优先通过能力检测与合理降级维持统一接口。 -- 谨慎逃逸：只有在抽象层无法表达时，才考虑后端特化，而不是让上层直接依赖原生 API。 +- **渲染 API**: DirectX 12, OpenGL 4.6+ +- **语言**: C++17 +- **构建系统**: CMake 3.15+ +- **测试框架**: Google Test +- **UI**: ImGui（用于编辑器） -当前更强调的一条实践约束是： - -- 如果抽象层测试为了“能跑过”而不得不依赖后端私有接口，优先修 RHI 本身，而不是给测试开后门。 - -## 近期 RHI 整理结果 - -最近一轮 RHI 清理与重构，已经把以下关键问题收敛到统一行为： - -- `pipeline layout` 负责拥有并管理 descriptor set 元数据，而不是把布局信息分散在各处。 -- D3D12 / OpenGL 两个后端的 descriptor 绑定都已经是 `set-aware` 的，并正确处理 `firstSet`。 -- OpenGL 路径下，来自内存源码的 GLSL 编译不再依赖意外的 `NUL` 终止。 -- OpenGL 单 shader 编译路径现在会正确记录 `ShaderType`，计算着色器不再被错误标记为 `Vertex`。 -- OpenGL 的 compute/UAV 绑定路径已经有真实 dispatch + 回读验证，不再只是状态级别的伪验证。 -- 抽象层集成测试的 GT 管理已经统一为“每场景一张 GT，双后端都与同一 GT 比对”。 - -这意味着当前 RHI 的重点不再是“补最基础可用性”，而是“在做渲染管线的过程中继续按真实需求向前演进”。 - -## 仓库结构 +## 项目结构 ```text XCEngine/ -├─ engine/ # 引擎静态库，包含 Core / RHI / Resources / Scene 等模块 -├─ editor/ # 编辑器程序 -├─ tests/ # 单元测试与集成测试 -├─ mvs/ # 示例与实验性程序 -├─ docs/ # 设计文档与 API 文档 -└─ CMakeLists.txt +├── 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/ +│ │ ├── Core/ +│ │ │ ├── Asset/ # Core/Asset 实现 +│ │ │ └── IO/ # Core/IO 实现 +│ │ ├── Debug/ +│ │ ├── Math/ +│ │ ├── Memory/ +│ │ ├── Threading/ +│ │ ├── Platform/ +│ │ │ └── Windows/ +│ │ ├── Input/ +│ │ ├── Resources/ +│ │ │ ├── Texture/ +│ │ │ ├── Mesh/ +│ │ │ ├── Shader/ +│ │ │ ├── Material/ +│ │ │ └── AudioClip/ +│ │ ├── 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/ +│ │ ├── Material/ +│ │ ├── 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 配置文件 ``` -和当前渲染工作最相关的目录： - -- `engine/include/XCEngine/RHI/` -- `engine/src/RHI/` -- `tests/RHI/unit/` -- `tests/RHI/integration/` -- `tests/TEST_SPEC.md` - -## 环境要求 - -推荐开发环境： - -- Windows 10/11 -- Visual Studio 2019 或更新版本 -- CMake 3.15+ -- Python 3 - - RHI 抽象层集成测试会调用 `compare_ppm.py` 做 GT 图比对 -- 可用的 D3D12 和/或 OpenGL 驱动环境 - ## 快速开始 -### 1. 配置 +### 前置要求 -如果使用 Visual Studio 生成器： +- Windows 10/11 +- Visual Studio 2019 或更高版本 +- CMake 3.15+ + +### 构建项目 ```bash -cmake -S . -B build -A x64 +# 创建构建目录 +mkdir build && cd build + +# 配置 CMake +cmake .. -A x64 + +# 编译 +cmake --build . --config Debug ``` -如果使用 Ninja 等单配置生成器： +### 运行测试 ```bash -cmake -S . -B build +cd build/tests +ctest -C Debug --output-on-failure ``` -### 2. 构建 +或直接运行测试可执行文件： ```bash -cmake --build build --config Debug +build/tests/containers/Debug/xcengine_containers_tests.exe +build/tests/memory/Debug/xcengine_memory_tests.exe +build/tests/threading/Debug/xcengine_threading_tests.exe ``` -如果只想增量构建当前最关键的 RHI 测试目标： +## 核心模块说明 -```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 -``` +### Audio（音频系统） -## 测试 +- **AudioSystem**: 音频系统主类，管理所有音频设备 +- **AudioMixer**: 音频混音器，多通道混合与效果处理 +- **HRTF**: 头部相关传输函数，支持空间音频定位 +- **FFTFilter**: 快速傅里叶变换滤波器 +- **Reverbation**: 混响效果 +- **Equalizer**: 音频均衡器 +- **WindowsAudioBackend**: Windows WASAPI 音频后端实现 +- **AudioSourceComponent**: 音频源组件（用于游戏对象） +- **AudioListenerComponent**: 音频监听器组件（用于游戏对象） -### 运行全部测试 +### Components（游戏组件系统） -```bash -ctest --test-dir build -C Debug --output-on-failure -``` +- **Component**: 组件基类，提供生命周期管理 +- **GameObject**: 游戏对象，支持层级结构 +- **TransformComponent**: 变换组件，管理位置、旋转、缩放 +- **AudioSourceComponent**: 音频源组件 +- **AudioListenerComponent**: 音频监听器组件 -### 查看已注册测试 +### Containers（容器） -```bash -ctest --test-dir build -N -C Debug -``` +- **String**: 动态字符串类，支持常用字符串操作 +- **Array**: 模板动态数组，自动内存管理 +- **HashMap**: 模板哈希表，支持自定义键类型 -### 运行 RHI 抽象层单元测试 +### Core（核心基础） -```bash -build\tests\RHI\unit\Debug\rhi_unit_tests.exe -``` +- **Types**: 基础类型别名（int8、uint32 等） +- **RefCounted**: 引用计数基类，支持多线程安全释放 +- **SmartPtr**: 智能指针实现（Ref、UniqueRef） +- **Event**: 事件系统，支持订阅/发布模式 +- **FileWriter**: 文件写入工具 +- **Layer/LayerStack**: 层级与层级栈管理 -### 运行 RHI 抽象层集成测试 +### Platform（平台抽象层） -以 `quad` 为例： +跨平台抽象接口，支持 Windows、Linux、Android、macOS： -```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 -``` +- **IPlatform**: 平台接口 +- **IWindow**: 窗口接口 +- **IFileSystem**: 文件系统接口 +- **IClock**: 时钟接口 +- **IDynamicLibrary**: 动态库加载接口 +- **IDisplayEnumerator**: 显示设备枚举接口 +- **Window**: 窗口实现类 -截图输出约定： +### Input（输入模块） -- `quad_d3d12.ppm` -- `quad_opengl.ppm` -- `GT.ppm` +- **InputManager**: 输入管理器 +- **InputModule**: 输入模块基类 +- **InputEvent**: 输入事件定义 +- **InputAxis**: 输入轴配置 -两个后端都会与同目录下同一张 `GT.ppm` 比对。 +### Debug（调试与日志） -## RHI 测试体系 +- **Logger**: 分级日志系统（Info、Warning、Error） +- **ConsoleLogSink**: 控制台日志输出 +- **FileLogSink**: 文件日志输出 +- **Profiler**: 性能分析工具 +- **RenderDocCapture**: RenderDoc 帧捕获集成，支持 D3D12/OpenGL GPU 调试 -当前 RHI 测试分为四层： +### Memory（内存管理） -| 层级 | 目录 | 目标 | -| --- | --- | --- | -| 抽象层单元测试 | `tests/RHI/unit/` | 验证公共 RHI 接口在双后端上的一致性 | -| 抽象层集成测试 | `tests/RHI/integration/` | 用同一套 RHI 抽象代码驱动 D3D12 / OpenGL 完成真实渲染 | -| D3D12 后端测试 | `tests/RHI/D3D12/` | 验证 D3D12 封装自身行为 | -| OpenGL 后端测试 | `tests/RHI/OpenGL/` | 验证 OpenGL 封装自身行为 | +- **IAllocator**: 内存分配器接口 +- **LinearAllocator**: 线性分配器，适合帧分配 +- **PoolAllocator**: 内存池分配器，适合固定大小对象 +- **ProxyAllocator**: 代理分配器，跟踪内存使用统计 +- **MemoryManager**: 全局内存管理器 -当前已存在的关键 RHI 测试目标： +### Threading（线程） -- `rhi_unit_tests` -- `rhi_integration_minimal` -- `rhi_integration_triangle` -- `rhi_integration_quad` -- `rhi_integration_sphere` -- `rhi_d3d12_tests` -- `rhi_opengl_tests` +- **Thread**: 线程封装类 +- **Mutex**: 互斥锁 +- **SpinLock**: 自旋锁，适合短临界区 +- **ReadWriteLock**: 读写锁 +- **TaskSystem**: 多线程任务系统 +- **Task/TaskGroup**: 任务和任务组管理 -更多测试组织与命名规范见 [`tests/TEST_SPEC.md`](tests/TEST_SPEC.md)。 +### Math（数学库） -## 文档入口 +- **Vector2/3/4**: 向量运算 +- **Matrix3/4**: 矩阵运算 +- **Quaternion**: 四元数 +- **Transform**: 变换（位姿） +- **Color**: 颜色 +- **Rect**: 矩形 +- **Sphere/Box/Plane**: 基本几何体 +- **Ray**: 射线 +- **AABB/Bounds**: 包围体 +- **Frustum**: 视锥体 -- RHI 总览与设计原则： - [`docs/plan/end/RHI模块设计与实现/RHI模块总览.md`](docs/plan/end/RHI模块设计与实现/RHI模块总览.md) -- 测试规范： - [`tests/TEST_SPEC.md`](tests/TEST_SPEC.md) -- API 文档： - `docs/api/` +### Resources（资源管理） -## 当前开发建议 +XCEngine 资源系统采用分层架构： -如果你的目标是继续推进引擎渲染能力，建议直接在当前 RHI 之上开始做基础渲染管线，而不是继续闭门补抽象层“理论完整性”。 +#### Core/Asset（资源系统核心） -推荐策略： +- **IResource**: 资源接口基类 +- **ResourceTypes**: 资源类型定义（GUID、状态等） +- **ResourceHandle**: 资源句柄，安全引用资源 +- **ResourceManager**: 全局资源管理器，资源加载/卸载 +- **ResourceCache**: 资源缓存，支持引用计数 +- **AsyncLoader**: 异步资源加载器 +- **ResourceDependencyGraph**: 资源依赖图管理 -- 先做最小可运行的基础渲染管线 -- 始终只依赖公共 RHI 抽象接口 -- 一旦上层逼出真实缺口，回到 RHI 修根因 -- 每次修 RHI 时同步补单测和集成测试 -- 始终把“双后端功能不破坏”放在第一优先级 +#### 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)。 ## 许可证