feat: add Graphics module with D3D12 backend and documentation

Graphics Module: - Add platform abstraction layer (GraphicsPlatformInterface) - Add unified renderer entry point (Renderer) - Add D3D12 backend implementation (D3D12Core, D3D12Interface) - Add TestRenderer for multi-window rendering tests Documentation: - Add Graphics渲染架构分析.md - Add D3D12学习Wiki.md - Add changelogs directory with per-commit documentation - Add 20260326-dx12-initial.md for initial framework - Add 20260326-d3d12-foundation.md for Graphics module Fixes: - Resolve header include issues and type redefinition errors
2026-03-26 16:53:09 +08:00
parent 6ca6970e34
commit b7eebc11b2
18 changed files with 937 additions and 2 deletions
--- a/docs/wiki/D3D12学习Wiki.md
+++ b/docs/wiki/D3D12学习Wiki.md
@@ -0,0 +1,230 @@
+# Direct3D 12 学习 Wiki
+
+## 概述
+
+本文档是项目中 Direct3D 12 学习的基础知识汇总，帮助理解 D3D12 的核心概念和项目中的实现方式。
+
+## 1. D3D12 核心概念
+
+### 1.1 什么是 Direct3D 12？
+
+Direct3D 12 是微软推出的底层图形 API，相比 D3D11，它提供了：
+
+- **更底层的硬件控制**：开发者可以更精细地控制 GPU
+- **更低的 CPU 开销**：减少驱动程序的 CPU 时间
+- **更好的多线程支持**：支持多线程命令录制
+- **显式的资源管理**：开发者完全控制资源生命周期
+
+### 1.2 核心组件
+
+| 组件 | 说明 |
+|------|------|
+| **Device（设备）** | 代表物理 GPU 的逻辑抽象，用于创建所有 D3D12 对象 |
+| **Command Queue（命令队列）** | GPU 执行命令的队列 |
+| **Command List（命令列表）** | 记录 GPU 命令的容器 |
+| **Swap Chain（交换链）** | 管理后台缓冲区和前台显示 |
+| **Descriptor Heap（描述符堆）** | 存储资源描述符（视图）的内存池 |
+| **Root Signature（根签名）** | 定义着色器如何访问资源 |
+
+## 2. DXGI（DirectX Graphics Infrastructure）
+
+### 2.1 DXGI 的作用
+
+DXGI 是 DirectX 与图形硬件之间的抽象层，负责：
+
+- 枚举显示适配器
+- 管理显示输出
+- 创建交换链
+- 处理全屏/窗口切换
+
+### 2.2 关键接口
+
+```cpp
+IDXGIFactory6    // DXGI 工厂，创建其他 DXGI 对象
+IDXGIAdapter4    // 代表物理 GPU 适配器
+IDXGIOutput      // 代表显示器输出
+IDXGISwapChain   // 交换链接口
+```
+
+### 2.3 项目中的使用
+
+在 [D3D12CommonHeader.h](file:///d:/AllWX/AllC/FeatureExtractDemo/Engine/Graphics/Direct3D12/D3D12CommonHeader.h) 中引入了 `dxgi_6.h`：
+
+```cpp
+#include <dxgi_6.h>  // DXGI 6.0，支持枚举 GPU、查询显示模式
+```
+
+## 3. D3D12 初始化流程
+
+### 3.1 标准初始化步骤
+
+```
+1. 创建 DXGI Factory
+       ↓
+2. 枚举并选择适配器（GPU）
+       ↓
+3. 创建 D3D12 Device
+       ↓
+4. 创建命令队列
+       ↓
+5. 创建交换链
+       ↓
+6. 创建描述符堆
+       ↓
+7. 创建命令分配器和命令列表
+       ↓
+8. 创建同步对象（Fence）
+```
+
+### 3.2 项目当前状态
+
+[D3D12Core.cpp](file:///d:/AllWX/AllC/FeatureExtractDemo/Engine/Graphics/Direct3D12/D3D12Core.cpp) 目前是框架代码：
+
+```cpp
+namespace {
+    ID3D12Device8* main_device;  // 已声明主设备
+}
+
+bool initialize() {
+    // TODO: 实现适配器选择和设备创建
+    return true;
+}
+```
+
+## 4. COM 对象管理
+
+### 4.1 什么是 COM？
+
+COM（Component Object Model）是微软的组件对象模型，D3D12 对象都是 COM 对象。
+
+### 4.2 智能指针
+
+项目使用 WRL 库的 `ComPtr` 管理 COM 对象生命周期：
+
+```cpp
+#include <wrl.h>  // 提供 Microsoft::WRL::ComPtr
+
+// 使用示例
+Microsoft::WRL::ComPtr<ID3D12Device8> device;
+```
+
+### 4.3 ComPtr 的优势
+
+- **自动引用计数**：无需手动 AddRef/Release
+- **异常安全**：即使发生异常也能正确释放
+- **代码简洁**：减少内存管理代码
+
+## 5. 平台抽象设计
+
+### 5.1 设计理念
+
+项目采用**平台抽象层**设计，将图形 API 的差异封装在统一接口后：
+
+```
+┌────────────────────────────────────┐
+│         上层渲染代码                │
+│   graphics::initialize(platform)   │
+└──────────────┬─────────────────────┘
+               │
+               ▼
+┌────────────────────────────────────┐
+│      platform_interface            │
+│   - initialize()                   │
+│   - shutdown()                     │
+└──────────────┬─────────────────────┘
+               │
+    ┌──────────┼──────────┐
+    ▼          ▼          ▼
+┌───────┐  ┌───────┐  ┌───────┐
+│ D3D12 │  │Vulkan │  │OpenGL │
+└───────┘  └───────┘  └───────┘
+```
+
+### 5.2 接口绑定机制
+
+```cpp
+// D3D12Interface.cpp
+void get_platform_interface(platform_interface& pi) {
+    pi.initialize = core::initialize;
+    pi.shutdown = core::shutdown;
+}
+```
+
+这种设计允许：
+- 编译时或运行时切换图形后端
+- 各后端独立开发和测试
+- 上层代码与具体 API 解耦
+
+## 6. 渲染表面与窗口
+
+### 6.1 render_surface 结构
+
+```cpp
+struct render_surface {
+    platform::window window{};  // 平台窗口
+    surface surface{};          // 渲染表面
+};
+```
+
+### 6.2 多窗口支持
+
+TestRenderer 测试展示了多窗口渲染：
+
+```cpp
+graphics::render_surface _surfaces[4];  // 支持 4 个窗口
+
+// 创建多个渲染表面
+for (u32 i{0}; i < _countof(_surfaces); ++i) {
+    create_render_surface(_surfaces[i], info[i]);
+}
+```
+
+### 6.3 全屏切换
+
+通过 `WM_SYSCHAR` 消息处理 Alt+Enter：
+
+```cpp
+if (wparam == VK_RETURN && (HIWORD(lparam) & KF_ALTDOWN)) {
+    win.set_fullscreen(!win.is_fullscreen());
+}
+```
+
+## 7. 后续学习路径
+
+### 7.1 基础阶段
+
+- [ ] 完成设备创建和适配器枚举
+- [ ] 创建命令队列和命令列表
+- [ ] 实现交换链和后台缓冲区
+- [ ] 渲染第一个三角形
+
+### 7.2 进阶阶段
+
+- [ ] 描述符堆管理
+- [ ] 根签名和管线状态对象
+- [ ] 资源屏障和同步
+- [ ] 常量缓冲区和着色器资源
+
+### 7.3 高级阶段
+
+- [ ] 多线程渲染
+- [ ] 资源绑定策略
+- [ ] 动态资源管理
+- [ ] 性能优化
+
+## 8. 参考资源
+
+### 8.1 官方文档
+
+- [Microsoft D3D12 文档](https://docs.microsoft.com/en-us/windows/win32/direct3d12/direct3d-12-graphics)
+- [DXGI 文档](https://docs.microsoft.com/en-us/windows/win32/direct3ddxgi/dx-graphics-dxgi)
+
+### 8.2 推荐书籍
+
+- 《Introduction to 3D Game Programming with DirectX 12》
+- 《Real-Time 3D Rendering with DirectX and HLSL》
+
+### 8.3 项目相关文档
+
+- [Graphics渲染架构分析](./Graphics渲染架构分析.md)
+- [项目约定规范](./项目约定规范.md)