xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9a7a6102b55ba7694a3e1401bb443e0fa34832b9
XCEngine/docs/plan/第二阶段计划.md

14 KiB
Raw Blame History

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 命令正常、资源释放正确

执行命令

# 编译引擎
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 体系在第三阶段实现，届时将整合渲染组件
Reference in New Issue View Git Blame Copy Permalink