From 6a0dfb150d656c0741c3ec7c378a8fb41d7c6f6d Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Fri, 13 Mar 2026 21:24:02 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E7=AC=AC=E4=BA=8C?= =?UTF-8?q?=E9=98=B6=E6=AE=B5=E8=AE=A1=E5=88=92=20-=20RHI=E6=8A=BD?= =?UTF-8?q?=E8=B1=A1=E5=B1=82=E5=B0=81=E8=A3=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/plan/第二阶段计划.md | 351 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 351 insertions(+) create mode 100644 docs/plan/第二阶段计划.md diff --git a/docs/plan/第二阶段计划.md b/docs/plan/第二阶段计划.md new file mode 100644 index 00000000..5e833359 --- /dev/null +++ b/docs/plan/第二阶段计划.md @@ -0,0 +1,351 @@ +# XCEngine 渲染引擎 - 第二阶段计划 + +> **目标**: 构建 RHI 抽象层，将 HelloEarth 的 D3D12 最小可行系统封装为引擎基础设施 +> **版本**: 1.0 +> **日期**: 2026-03-13 +> **前置依赖**: 第一阶段（数学库、Core基础类型、线程系统、内存管理、容器库、日志系统） + +--- + +## 阶段背景 + +本阶段基于以下代码基础进行构建： + +1. **HelloEarth 最小可行渲染系统** (`mvs/HelloEarth/`) + - 已实现完整的 D3D12 渲染流程 + - 包含窗口创建、设备初始化、Shader 加载、网格渲染、纹理绑定 + - 可直接运行并渲染地球模型 + +2. **XCEngine 架构设计书** (`docs/XCEngine渲染引擎架构设计.md`) + - 定义了 RHI 抽象层接口规范 + - 定义了渲染资源封装接口 + - 定义了渲染管线基础架构 + +--- + +## 阶段目标 + +将 HelloEarth 中散落的 D3D12 代码重构为引擎的 RHI 抽象层，建立可复用的渲染基础设施，为第三阶段的 Component/GameObject 体系提供渲染支撑。 + +--- + +## 模块规划 + +### 2.1 RHI 公共定义 (RHIDefines) + +| 项目 | 内容 | +|------|------| +| **优先级** | P0 | +| **预计工作量** | 1天 | +| **包含内容** | 枚举定义 (`Format`, `ShaderStage`, `ResourceState`, `PrimitiveTopology` 等)、公共结构体 (`Viewport`, `Rect`)、DXGI/D3D12 类型映射 | +| **参考来源** | `docs/XCEngine渲染引擎架构设计.md` 4.1 节 | + +### 2.2 RHI 接口层 + +| 项目 | 内容 | +|------|------| +| **优先级** | P0 | +| **预计工作量** | 2天 | +| **包含接口** | `IRHIDevice`, `ICommandList`, `ICommandAllocator`, `ICommandQueue`, `IFence`, `ISwapChain`, `IDescriptorHeap`, `IRootSignature`, `IPipelineState` | +| **功能要求** | 跨平台抽象接口定义，不包含平台特定实现 | +| **补充说明** | 必须包含 `SetPrimitiveTopology()` 图元类型设置接口 | +| **参考来源** | `docs/XCEngine渲染引擎架构设计.md` 4.1 节 RHI 接口定义 | + +### 2.3 D3D12 后端实现 + +| 项目 | 内容 | +|------|------| +| **优先级** | P0 | +| **预计工作量** | 4天 | +| **包含内容** | `D3D12Device` 实现 `IRHIDevice` 接口、`D3D12CommandList`、`D3D12CommandAllocator`、`D3D12Fence`、`D3D12SwapChain`、`D3D12DescriptorHeap`、`D3D12RootSignature`、`D3D12PipelineState` | +| **迁移参考** | `mvs/HelloEarth/BattleFireDirect.h/cpp` 中的全局函数封装为类接口 | +| **依赖** | RHI 接口层 | + +**迁移映射表**： + +| HelloEarth 原有实现 | 新架构 RHI 接口 | +|---------------------|-----------------| +| `InitD3D12()` | `D3D12Device::Initialize()` | +| `GetD3DDevice()` | `IRHIDevice::GetNativeDevice()` | +| `GetCommandList()` | `ICommandList` | +| `GetCommandAllocator()` | `ICommandAllocator` | +| `InitRootSignature()` | `D3D12RootSignature` | +| `CreatePSO()` | `D3D12PipelineState` | +| `SwapD3D12Buffers()` | `ISwapChain::Present()` | +| `CreateBufferObject()` | `IVertexBuffer` / `IIndexBuffer` | +| `CreateConstantBufferObject()` | `IConstantBuffer` | +| `CreateTexture2D()` | `ITexture2D` | + +### 2.4 渲染资源封装 + +| 项目 | 内容 | +|------|------| +| **优先级** | P0 | +| **预计工作量** | 2天 | +| **包含内容** | `VertexBuffer`, `IndexBuffer`, `ConstantBuffer`, `Texture2D`, `Sampler` | +| **功能要求** | 封装 RHI 资源创建/更新/绑定逻辑 | +| **参考来源** | `docs/XCEngine渲染引擎架构设计.md` 4.0 节渲染资源类型定义 | +| **迁移参考** | `mvs/HelloEarth/main.cpp` 中的 VB/IB/CB/Texture 创建逻辑 | + +### 2.5 RenderTarget / DepthStencil 管理 + +| 项目 | 内容 | +|------|------| +| **优先级** | P0 | +| **预计工作量** | 1天 | +| **包含内容** | `RenderTarget`, `DepthStencil`, 交换链缓冲管理、Resource Barrier 状态转换、SRV/RTV/DSV 创建 | +| **功能要求** | 渲染目标创建、深度模板缓冲管理、状态转换 (Present ↔ RenderTarget)、视图创建 | +| **补充说明** | 必须包含纹理完整创建流程：SRV 创建 + Copy 过程 + Barrier 转换；ClearRenderTarget/ClearDepthStencil 命令 | +| **迁移参考** | `mvs/HelloEarth/BattleFireDirect.cpp` 中的 `gDSRT`, `gColorRTs` 管理逻辑、`InitResourceBarrier()` 函数、`CreateTexture2D()` 中的 SRV 创建和资源复制逻辑 | + +### 2.6 Shader / PSO 管理 + +| 项目 | 内容 | +|------|------| +| **优先级** | P1 | +| **预计工作量** | 2天 | +| **包含内容** | `Shader` 加载编译、`PipelineState` 缓存管理、`InputLayout` 顶点布局定义、`BlendState`/`DepthStencilState`/`RasterizerState` 渲染状态 | +| **功能要求** | HLSL 文件加载、编译、PSO 创建与缓存、顶点布局定义 | +| **补充说明** | 必须定义渲染状态结构：BlendState (混合模式)、DepthStencilState (深度测试)、RasterizerState (光栅化) | +| **迁移参考** | `mvs/HelloEarth/main.cpp` 中 `CreateShaderFromFile()` 和 `CreatePSO()` 逻辑，PSO 中的硬编码状态 | + +### 2.7 渲染上下文 (RenderContext) + +| 项目 | 内容 | +|------|------| +| **优先级** | P1 | +| **预计工作量** | 2天 | +| **包含内容** | 渲染上下文管理、SwapChain 渲染循环封装、Viewport/Scissor 设置、Clear 命令 | +| **功能要求** | 帧开始/结束、渲染目标切换、视口裁剪设置、背景清除、Present | +| **补充说明** | 必须包含 ClearRenderTargetView 和 ClearDepthStencilView 命令 | +| **迁移参考** | `mvs/HelloEarth/main.cpp` 中渲染循环逻辑、`BeginRenderToSwapChain()` / `EndRenderToSwapChain()` 中的 Clear 调用 | + +### 2.8 静态网格组件 (StaticMeshComponent) + +| 项目 | 内容 | +|------|------| +| **优先级** | P1 | +| **预计工作量** | 1天 | +| **包含内容** | 网格加载 (.lhsm 格式)、顶点/索引缓冲绑定、渲染调用 | +| **功能要求** | 模型文件加载、顶点数据上传、DrawCall 封装 | +| **迁移参考** | `mvs/HelloEarth/StaticMeshComponent.h/cpp` | + +### 2.9 CMake 构建配置 + +| 项目 | 内容 | +|------|------| +| **优先级** | P1 | +| **预计工作量** | 1天 | +| **包含内容** | RHI/D3D12 子目录 CMakeLists.txt、引擎库配置更新 | +| **功能要求** | 添加 D3D12 后端到构建系统、链接 DirectX 库 | + +### 2.10 Demo 整合验证 + +| 项目 | 内容 | +|------|------| +| **优先级** | P1 | +| **预计工作量** | 1天 | +| **包含内容** | 使用新 RHI 架构重写 HelloEarth Demo | +| **验证目标** | 渲染效果与原 HelloEarth 一致，验证 RHI 层功能完整 | + +--- + +## 目录结构 + +``` +engine/include/XCEngine/ +├── RHI/ +│ ├── RHIDefines.h # 公共枚举定义 +│ ├── IRHIDevice.h # 抽象设备接口 +│ ├── ICommandList.h # 命令列表接口 +│ ├── ICommandAllocator.h # 命令分配器接口 +│ ├── ICommandQueue.h # 命令队列接口 +│ ├── IFence.h # 同步围栏接口 +│ ├── ISwapChain.h # 交换链接口 +│ ├── IDescriptorHeap.h # 描述符堆接口 +│ ├── IRootSignature.h # 根签名接口 +│ ├── IPipelineState.h # PSO 接口 +│ ├── IRenderTargetView.h # RTV 接口 +│ ├── IDepthStencilView.h # DSV 接口 +│ ├── IShaderResourceView.h # SRV 接口 +│ └── RHISystem.h # RHI 系统入口 +│ +├── Rendering/ +│ ├── Buffer.h # 缓冲区基类 +│ ├── VertexBuffer.h # 顶点缓冲区 +│ ├── IndexBuffer.h # 索引缓冲区 +│ ├── ConstantBuffer.h # 常量缓冲区 +│ ├── Texture.h # 纹理 +│ ├── RenderTarget.h # 渲染目标 +│ ├── DepthStencil.h # 深度模板缓冲 +│ ├── Shader.h # Shader 抽象 +│ ├── Sampler.h # 采样器 +│ ├── InputLayout.h # 顶点输入布局 +│ ├── RenderState.h # 渲染状态 (Blend/Depth/Rasterizer) +│ ├── StaticMeshComponent.h # 静态网格组件 +│ └── RenderContext.h # 渲染上下文 +│ +engine/src/ +├── RHI/ +│ ├── CMakeLists.txt # RHI 构建配置 +│ └── D3D12/ +│ ├── CMakeLists.txt # D3D12 构建配置 +│ ├── D3D12Device.cpp +│ ├── D3D12CommandList.cpp +│ ├── D3D12CommandAllocator.cpp +│ ├── D3D12CommandQueue.cpp +│ ├── D3D12Fence.cpp +│ ├── D3D12SwapChain.cpp +│ ├── D3D12DescriptorHeap.cpp +│ ├── D3D12RootSignature.cpp +│ ├── D3D12PipelineState.cpp +│ ├── D3D12Resource.cpp +│ └── D3D12Texture.cpp +│ +└── Rendering/ + ├── CMakeLists.txt # Rendering 构建配置 + ├── Buffer.cpp + ├── Texture.cpp + ├── RenderTarget.cpp + ├── Shader.cpp + ├── RenderState.cpp + ├── StaticMeshComponent.cpp + └── RenderContext.cpp +``` + +--- + +## 时间安排 + +| 天数 | 内容 | +|------|------| +| 第1天 | RHI 公共定义 | +| 第2-3天 | RHI 接口层定义 | +| 第4-7天 | D3D12 后端实现 | +| 第8-9天 | 渲染资源封装 (VB/IB/CB/Texture) | +| 第10天 | RenderTarget/DepthStencil 管理 | +| 第11-12天 | Shader / PSO 管理 + InputLayout | +| 第13-14天 | 渲染上下文 (RenderContext) | +| 第15天 | StaticMeshComponent 迁移 | +| 第16天 | CMake 构建配置 | +| 第17-18天 | Demo 整合验证 + 调试修复 | + +> 注：总计约 18 个工作日，可根据实际情况调整 + +--- + +## 依赖关系 + +``` +第一阶段 (已完成) + │ + ├──▶ RHI 公共定义 (无依赖) + │ │ + │ ├──▶ RHI 接口层 (依赖 RHI 公共定义) + │ │ + │ └──▶ D3D12 后端 (依赖 RHI 接口层, 复用 HelloEarth 实现) + │ + ├──▶ 渲染资源封装 (依赖 RHI 接口层, 复用 HelloEarth 资源创建逻辑) + │ │ + │ └──▶ RenderTarget/DepthStencil (依赖 RHI 接口层) + │ + ├──▶ Shader/PSO 管理 (依赖 RHI 接口层, 复用 HelloEarth 编译逻辑) + │ + ├──▶ 渲染上下文 (依赖 RHI 接口层, 渲染资源, 复用 HelloEarth 渲染循环) + │ + ├──▶ StaticMeshComponent (依赖 RHI 接口层, 渲染资源) + │ + └──▶ CMake 构建配置 (依赖引擎构建系统) +``` + +--- + +## 验收标准 + +- [ ] RHI 接口编译通过 +- [ ] D3D12 后端完整实现 RHI 接口 +- [ ] 可创建 VertexBuffer/IndexBuffer/ConstantBuffer/Texture2D +- [ ] RenderTarget/DepthStencil 创建与管理正常 +- [ ] Resource Barrier 状态转换正常 +- [ ] Shader 加载编译正常工作 +- [ ] PipelineState 创建与管理正常 +- [ ] InputLayout 顶点布局定义正确 +- [ ] 渲染状态 (Blend/Depth/Rasterizer) 定义正确 +- [ ] PrimitiveTopology 图元类型设置正常 +- [ ] 纹理 SRV/RTV/DSV 视图创建正常 +- [ ] ClearRenderTarget/ClearDepthStencil 清除命令正常 +- [ ] Viewport/Scissor 设置正常 +- [ ] 渲染上下文帧循环正常 +- [ ] StaticMeshComponent 网格加载与渲染正常 +- [ ] CMake 构建配置完整 +- [ ] 新架构 Demo 运行效果与原 HelloEarth 一致 +- [ ] 窗口/渲染/退出流程无崩溃 + +--- + +## 测试方案 + +### 测试用例设计 + +| 模块 | 测试类别 | 测试用例示例 | +|------|---------|-------------| +| **RHI** | 设备初始化 | D3D12 设备创建成功、获取适配器信息 | +| **RHI** | 命令列表 | Reset/Close/Begin 流程正常、PrimitiveTopology 设置 | +| **RHI** | 同步 | Fence Signal/Wait 正常工作 | +| **RHI** | 交换链 | Present/Resize 正常工作 | +| **Resources** | 缓冲区 | VB/IB 创建、数据更新、绑定正确 | +| **Resources** | 纹理 | 2D 纹理创建、Mipmap 生成、SRV 绑定、资源状态转换 | +| **Resources** | 视图 | RTV/DSV 创建正确 | +| **Shader** | 编译 | VS/PS/GS 编译成功、错误信息正确 | +| **Pipeline** | PSO | 图形 PSO 创建成功、渲染状态配置正确 | +| **Pipeline** | 渲染状态 | Blend/Depth/Rasterizer 状态正确应用 | +| **RenderContext** | 渲染循环 | 帧循环正常、Clear 命令正常、资源释放正确 | + +### 执行命令 + +```bash +# 编译引擎 +cmake --build build --target XCEngine + +# 编译 Demo +cmake --build build --target HelloEarth + +# 运行 Demo +./build/bin/HelloEarth.exe +``` + +--- + +## 迁移对照表 + +以下表格详细说明 HelloEarth 原有实现到新架构的映射关系： + +| 功能 | HelloEarth 实现 | 新架构实现 | 接口位置 | +|------|----------------|-----------|----------| +| 初始化 D3D12 | `InitD3D12(hwnd, width, height)` | `device->Initialize(windowHandle, desc)` | `IRHIDevice` | +| 获取 D3D12 设备 | `GetD3DDevice()` | `device->GetNativeDevice()` | `IRHIDevice` | +| 命令分配器 | `GetCommandAllocator()` | `device->CreateCommandAllocator()` | `IRHIDevice` | +| 命令列表 | `GetCommandList()` | `device->CreateCommandList()` | `IRHIDevice` | +| 创建根签名 | `InitRootSignature()` | `device->CreateRootSignature()` | `IRHIDevice` | +| 创建 PSO | `CreatePSO(rs, vs, ps, gs)` | `device->CreatePipelineState()` | `IRHIDevice` | +| 创建顶点缓冲 | `CreateBufferObject()` | `device->CreateVertexBuffer()` | `IRHIDevice` | +| 创建常量缓冲 | `CreateConstantBufferObject()` | `device->CreateConstantBuffer()` | `IRHIDevice` | +| 创建纹理 | `CreateTexture2D()` | `device->CreateTexture2D()` | `IRHIDevice` | +| 纹理 SRV 创建 | `CreateShaderResourceView()` | `texture->CreateSRV()` | `ITexture` | +| 资源状态转换 | `InitResourceBarrier()` | `ICommandList::ResourceBarrier()` | `ICommandList` | +| 设置图元类型 | `IASetPrimitiveTopology()` | `ICommandList::SetPrimitiveTopology()` | `ICommandList` | +| 清除渲染目标 | `ClearRenderTargetView()` | `ICommandList::ClearRenderTargetView()` | `ICommandList` | +| 清除深度模板 | `ClearDepthStencilView()` | `ICommandList::ClearDepthStencilView()` | `ICommandList` | +| 渲染到交换链 | `BeginRenderToSwapChain()` | `context->BeginFrame()` | `RenderContext` | +| 结束渲染 | `EndRenderToSwapChain()` | `context->EndFrame()` | `RenderContext` | +| 呈现 | `SwapD3D12Buffers()` | `swapChain->Present()` | `ISwapChain` | +| 等待 GPU | `WaitForCompletionOfCommandList()` | `fence->Wait()` | `IFence` | +| 网格渲染 | `StaticMeshComponent::Render()` | `StaticMeshComponent::Render()` | `StaticMeshComponent` | + +--- + +## 备注 + +1. **DirectX Math**: 本阶段继续使用 `DirectX::XMMatrix` 等数学库，待第三阶段替换为 XCEngine Math +2. **HelloEarth 复用**: HelloEarth 的 Shader 文件 (`Res/Shader/*.hlsl`)、模型文件 (`Res/Model/*.lhsm`)、纹理文件 (`Res/Image/*`) 均可直接复用 +3. **后续阶段**: Component/GameObject 体系在第三阶段实现，届时将整合渲染组件