XCEngine/docs/used/第三阶段计划.md

第三阶段计划：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 上下文配置
• 设备信息查询

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

// OpenGL 方式
glActiveTexture(GL_TEXTURE0 + slot);
glBindTexture(GL_TEXTURE_2D, textureID);
glUniform1i(location, slot);

3.6.3 着色器编译

// 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 管理

// 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 帧缓冲

// 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 后端