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

refactor: 移除HelloEarth示例，统一使用D3D12最小可行系统

Browse Source
This commit is contained in:
ssdfasd
2026-03-15 00:43:54 +08:00
parent 9a7a6102b5
commit d8882ab93f
17 changed files with 0 additions and 8722 deletions
Download Patch File Download Diff File Expand all files Collapse all files

351
docs/plan/第二阶段计划.md
View File

@@ -1,351 +0,0 @@
# 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 体系在第三阶段实现，届时将整合渲染组件