Add OpenGL backend project and third phase plan

2026-03-16 13:18:53 +08:00
parent 554c48448b
commit 2b3ac27243
3237 changed files with 623781 additions and 0 deletions
--- a/docs/plan/第三阶段计划.md
+++ b/docs/plan/第三阶段计划.md
@@ -0,0 +1,335 @@
+# 第三阶段计划：OpenGL 后端实现
+
+> **目标**：实现 OpenGL 后端，完成 RHI 跨平台渲染抽象
+> **阶段**：第三阶段
+> **前置依赖**：第二阶段 RHI 抽象层与 D3D12 后端
+
+---
+
+## 3.1 阶段目标
+
+在已有 RHI 抽象层和 D3D12 后端的基础上，实现 OpenGL 后端：
+- 复用现有抽象接口
+- 对接 OpenGL (GLFW + GLAD)
+- 支持最小渲染系统验证
+
+---
+
+## 3.2 目录结构
+
+```
+engine/include/XCEngine/RHI/OpenGL/
+├── OpenGLCommon.h              # OpenGL 公共定义与辅助函数
+├── OpenGLEnum.h                # RHI 枚举 → OpenGL 枚举转换层
+├── OpenGLDevice.h              # 设备初始化
+├── OpenGLDevice.cpp
+├── OpenGLSwapChain.h           # 交换链（GLFW 窗口）
+├── OpenGLSwapChain.cpp
+├── OpenGLCommandList.h         # 命令列表封装
+├── OpenGLCommandList.cpp
+├── OpenGLBuffer.h              # VBO/IBO/UBO 管理
+├── OpenGLBuffer.cpp
+├── OpenGLTexture.h             # 纹理管理
+├── OpenGLTexture.cpp
+├── OpenGLShader.h              # GLSL 着色器
+├── OpenGLShader.cpp
+├── OpenGLPipelineState.h       # VAO + Program + State
+├── OpenGLPipelineState.cpp
+├── OpenGLRenderTarget.h        # FBO + RTV
+├── OpenGLRenderTarget.cpp
+├── OpenGLDepthStencil.h        # 深度模板
+├── OpenGLDepthStencil.cpp
+├── OpenGLDescriptorHeap.h      # Texture Unit 模拟
+├── OpenGLDescriptorHeap.cpp
+├── OpenGLFence.h               # 同步
+├── OpenGLFence.cpp
+├── OpenGLQueryHeap.h           # 查询堆
+├── OpenGLQueryHeap.cpp
+├── OpenGLRootSignature.h       # 简化实现
+├── OpenGLRootSignature.cpp
+├── OpenGLSampler.h            # 采样器
+├── OpenGLSampler.cpp
+├── OpenGLResourceView.h        # 视图基类
+├── OpenGLResourceView.cpp
+└── OpenGLRenderTargetView.h    # 渲染目标视图
+    ├── OpenGLRenderTargetView.cpp
+    ├── OpenGLDepthStencilView.h
+    ├── OpenGLDepthStencilView.cpp
+    ├── OpenGLShaderResourceView.h
+    ├── OpenGLShaderResourceView.cpp
+    ├── OpenGLUnorderedAccessView.h
+    ├── OpenGLUnorderedAccessView.cpp
+    ├── OpenGLConstantBufferView.h
+    └── OpenGLConstantBufferView.cpp
+```
+
+---
+
+## 3.3 任务拆分
+
+### 3.3.1 基础准备
+
+**任务 3.1：OpenGLEnum.h - 枚举转换层**
+
+实现 RHI 枚举到 OpenGL 枚举的转换：
+- `Format` → `GLenum`
+- `PrimitiveTopology` → `GLenum`
+- `BlendOp` / `BlendFactor` → `GLenum`
+- `ComparisonFunc` → `GLenum`
+- `ResourceStates` → `GLenum` (简化)
+- `ShaderType` → `GLenum`
+
+**任务 3.2：OpenGLCommon.h - 公共定义**
+
+- OpenGL 初始化辅助函数
+- 格式支持检测
+- 错误检查宏
+- GLAD 加载器封装
+
+---
+
+### 3.3.2 核心组件实现
+
+**任务 3.3：OpenGLDevice - 设备实现**
+
+实现 `OpenGLDevice` 类：
+- GLFW 窗口创建
+- GLAD 初始化
+- OpenGL 上下文配置
+- 设备信息查询
+
+```cpp
+class OpenGLDevice : public IRHIDevice {
+public:
+    bool Initialize(void* windowHandle, bool enableDebug = false);
+    GLFWwindow* GetWindow() const { return m_window; }
+    
+    // IRHIDevice 实现...
+    
+private:
+    GLFWwindow* m_window;
+    HGLRC m_glContext;
+};
+```
+
+**任务 3.4：OpenGLSwapChain - 交换链实现**
+
+实现 `OpenGLSwapChain` 类：
+- GLFW 窗口管理
+- 双缓冲切换
+- 帧缓冲 resize 处理
+
+**任务 3.5：OpenGLShader - 着色器实现**
+
+实现 `OpenGLShader` 类：
+- GLSL 源码加载
+- `glShaderSource` + `glCompileShader`
+- 编译错误获取
+- 反射数据提取（可选）
+
+**任务 3.6：OpenGLBuffer - 缓冲区实现**
+
+实现 `OpenGLBuffer` 类：
+- VBO 创建与管理
+- IBO 索引缓冲
+- UBO uniform 缓冲
+- Buffer mapping
+
+**任务 3.7：OpenGLTexture - 纹理实现**
+
+实现 `OpenGLTexture` 类：
+- 2D 纹理创建
+- 纹理参数设置
+- Mipmap 生成
+- 纹理绑定
+
+**任务 3.8：OpenGLPipelineState - 管线状态实现**
+
+实现 `OpenGLPipelineState` 类：
+- VAO 管理
+- Shader Program 链接
+- 状态缓存（blend, depth, rasterizer）
+- 输入布局映射
+
+**任务 3.9：OpenGLCommandList - 命令列表实现**
+
+实现 `OpenGLCommandList` 类：
+- 状态缓存与批量提交
+- `glDrawArrays` / `glDrawElements` 封装
+- 视口裁剪设置
+- 渲染目标绑定
+
+**任务 3.10：OpenGLFence - 同步实现**
+
+实现 `OpenGLFence` 类：
+- `glFenceSync` 封装
+- CPU 等待实现
+
+**任务 3.11：OpenGLDescriptorHeap - 描述符堆实现**
+
+实现 `OpenGLDescriptorHeap` 类：
+- Texture Unit 数组管理
+- 简化版描述符绑定
+
+---
+
+### 3.3.3 视图实现
+
+**任务 3.12：OpenGLRenderTargetView - 渲染目标视图**
+
+- Framebuffer 对象管理
+- 颜色附件绑定
+
+**任务 3.13：OpenGLDepthStencilView - 深度模板视图**
+
+- Depth/stencil buffer 管理
+- FBO 深度附件
+
+**任务 3.14：OpenGLShaderResourceView - 着色器资源视图**
+
+- 纹理视图绑定到 Texture Unit
+
+**任务 3.15：OpenGLUnorderedAccessView - 无序访问视图**
+
+- SSBO 管理
+
+**任务 3.16：OpenGLConstantBufferView - 常量缓冲区视图**
+
+- UBO 绑定
+
+---
+
+## 3.4 D3D12 与 OpenGL 关键差异
+
+| D3D12 组件 | OpenGL 对应 | 差异说明 |
+|------------|-------------|----------|
+| `ID3D12Device` | `OpenGLDevice` | GLFW + GLAD 初始化 |
+| `ID3D12CommandQueue` | 简化 | OpenGL 无需显式命令队列 |
+| `ID3D12CommandList` | `OpenGLCommandList` | 封装立即模式渲染 |
+| `ID3D12DescriptorHeap` | `OpenGLDescriptorHeap` | 使用 Texture Unit 模拟 |
+| `ID3D12PipelineState` | `OpenGLPipelineState` | VAO + Program + State |
+| `ID3D12RootSignature` | 简化 | 使用 uniform binding |
+| `ID3D12Fence` | `OpenGLFence` | glFenceSync |
+| `ID3D12SwapChain` | `OpenGLSwapChain` | GLFW 窗口管理 |
+| `ID3D12Buffer` | `OpenGLBuffer` | VBO/IBO/UBO |
+| `ID3D12Texture` | `OpenGLTexture` | GL 纹理对象 |
+| `ID3D12Shader` | `OpenGLShader` | GLSL 编译 |
+| `ID3D12QueryHeap` | `OpenGLQueryHeap` | GL 查询对象 |
+
+---
+
+## 3.5 实现顺序
+
+```
+阶段 3.1: 基础准备 (1天)
+    ├── 3.1.1 OpenGLEnum.h (枚举转换)
+    └── 3.1.2 OpenGLCommon.h (公共定义)
+
+阶段 3.2: 核心组件 (4天)
+    ├── 3.2.1 OpenGLDevice
+    ├── 3.2.2 OpenGLSwapChain
+    ├── 3.2.3 OpenGLShader
+    ├── 3.2.4 OpenGLBuffer
+    ├── 3.2.5 OpenGLTexture
+    ├── 3.2.6 OpenGLPipelineState
+    └── 3.2.7 OpenGLCommandList
+
+阶段 3.3: 辅助组件 (2天)
+    ├── 3.3.1 OpenGLFence
+    ├── 3.3.2 OpenGLDescriptorHeap
+    ├── 3.3.3 OpenGLQueryHeap
+    ├── 3.3.4 OpenGLSampler
+    └── 3.3.5 OpenGLRootSignature
+
+阶段 3.4: 视图实现 (1天)
+    ├── 3.4.1 OpenGLRenderTargetView
+    ├── 3.4.2 OpenGLDepthStencilView
+    ├── 3.4.3 OpenGLShaderResourceView
+    ├── 3.4.4 OpenGLUnorderedAccessView
+    └── 3.4.5 OpenGLConstantBufferView
+
+阶段 3.5: 集成测试 (1天)
+    ├── 窗口创建与渲染循环
+    ├── 简单模型渲染测试
+    └── 与 mvs/OpenGL 功能对比验证
+```
+
+---
+
+## 3.6 关键技术点
+
+### 3.6.1 状态管理
+
+OpenGL 是状态机模式：
+- 在 `OpenGLCommandList` 中缓存当前状态
+- 绘制前检查状态变化，仅调用变化的 GL 函数
+- 避免冗余状态设置
+
+### 3.6.2 资源绑定
+
+D3D12: Descriptor Heap + Root Signature  
+OpenGL: Texture Unit + Uniform Location
+
+```cpp
+// OpenGL 方式
+glActiveTexture(GL_TEXTURE0 + slot);
+glBindTexture(GL_TEXTURE_2D, textureID);
+glUniform1i(location, slot);
+```
+
+### 3.6.3 着色器编译
+
+```cpp
+// GLSL 编译
+GLuint vertexShader = glCreateShader(GL_VERTEX_SHADER);
+glShaderSource(vertexShader, 1, &vertexSource, nullptr);
+glCompileShader(vertexShader);
+
+GLuint program = glCreateProgram();
+glAttachShader(program, vertexShader);
+glAttachShader(program, fragmentShader);
+glLinkProgram(program);
+```
+
+### 3.6.4 VAO 管理
+
+```cpp
+// Vertex Array Object
+GLuint vao;
+glGenVertexArrays(1, &vao);
+glBindVertexArray(vao);
+glEnableVertexAttribArray(0);
+glVertexAttribPointer(0, 3, GL_FLOAT, GL_FALSE, sizeof(Vertex), (void*)0);
+```
+
+### 3.6.5 帧缓冲
+
+```cpp
+// Framebuffer Object
+GLuint fbo;
+glGenFramebuffers(1, &fbo);
+glBindFramebuffer(GL_FRAMEBUFFER, fbo);
+glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, textureID, 0);
+glFramebufferTexture2D(GL_FRAMEBUFFER, GL_DEPTH_ATTACHMENT, GL_TEXTURE_2D, depthID, 0);
+```
+
+---
+
+## 3.7 验收标准
+
+1. **编译通过**：所有头文件和实现文件能够无错误编译
+2. **接口完整**：所有 RHI 抽象接口都有 OpenGL 实现
+3. **功能验证**：
+   - 能够创建 GLFW 窗口并初始化 OpenGL 上下文
+   - 能够渲染简单的几何体
+   - 能够加载和显示纹理
+   - 能够呈现到屏幕
+4. **功能对比**：与现有 mvs/OpenGL 功能一致
+
+---
+
+## 3.8 后续阶段依赖
+
+- 第四阶段：渲染管线（RenderPipeline）需要 RHI 多后端支持
+- 材质系统需要统一的 Shader 接口
+- 跨平台渲染验证需要 OpenGL 后端