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

docs: update RHI API docs

Browse Source
This commit is contained in:
ssdfasd
2026-03-20 02:35:45 +08:00
parent ea756c0177
commit 070b444f8f
501 changed files with 13493 additions and 2022 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
docs/api/rhi/opengl/device/compile-shader.md Normal file
View File

@@ -0,0 +1,73 @@
# OpenGLDevice::CompileShader
```cpp
RHIShader* CompileShader(const ShaderCompileDesc& desc) override
```
编译着色器程序。
## 详细描述
从文件加载并编译着色器代码。
### 支持的着色器类型
通过 `profile` 参数指定：
- `"vs"` / `"vert"` - 顶点着色器
- `"fs"` / `"frag"` - 片段着色器
- `"gs"` - 几何着色器
- `"cs"` / `"compute"` - 计算着色器
- `"ts"` / `"tess"` - 曲面细分着色器
### 着色器编译流程
1. 从文件读取着色器源码
2. 根据 `profile` 选择着色器类型
3. 编译着色器源码
4. 链接程序（如果需要）
## 参数
- `desc` - 着色器编译描述符
### ShaderCompileDesc 字段
| 字段 | 描述 |
|------|------|
| `fileName` | 着色器文件路径（宽字符） |
| `entryPoint` | 入口点名称（默认 "main"） |
| `profile` | 着色器配置文件（如 "vs", "fs"） |
## 返回值
`RHIShader*` - 创建的着色器指针，编译失败返回包含错误的着色器对象
## 注意事项
- `fileName` 使用宽字符 (`std::wstring`)
- `entryPoint` 和 `profile` 从宽字符转换为窄字符
- 如果 `fileName` 为空，不执行编译但仍返回着色器对象
- 返回的着色器对象归调用者所有，需自行管理生命周期
## 示例
```cpp
ShaderCompileDesc vsDesc;
vsDesc.fileName = L"shaders/triangle.vert";
vsDesc.entryPoint = L"main";
vsDesc.profile = L"vs";
RHIShader* vertexShader = device.CompileShader(vsDesc);
ShaderCompileDesc fsDesc;
fsDesc.fileName = L"shaders/triangle.frag";
fsDesc.entryPoint = L"main";
fsDesc.profile = L"fs";
RHIShader* fragmentShader = device.CompileShader(fsDesc);
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [OpenGLShader](../opengl-shader.md) - OpenGL 着色器实现

29
docs/api/rhi/opengl/device/constructor.md Normal file
View File

@@ -0,0 +1,29 @@
# OpenGLDevice::OpenGLDevice
```cpp
OpenGLDevice()
```
默认构造函数，创建一个未初始化的 `OpenGLDevice` 实例。
## 详细描述
构造函数创建 `OpenGLDevice` 对象并初始化内部状态：
- `m_window` 设为 `nullptr`
- `m_initialized` 设为 `false`
- `m_ownsWindow` 设为 `false`
设备在使用前必须调用 `Initialize()` 或 `InitializeWithExistingWindow()` 进行初始化。
## 示例
```cpp
OpenGLDevice* device = new OpenGLDevice();
// 后续需要调用 Initialize() 进行初始化
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [Initialize](initialize.md) - 初始化设备
- [InitializeWithExistingWindow](initialize-with-existing-window.md) - 使用现有窗口初始化

67
docs/api/rhi/opengl/device/create-buffer.md Normal file
View File

@@ -0,0 +1,67 @@
# OpenGLDevice::CreateBuffer
```cpp
RHIBuffer* CreateBuffer(const BufferDesc& desc) override
```
创建 OpenGL 缓冲区对象。
## 详细描述
根据 `BufferDesc` 创建一个 OpenGL 缓冲区对象。缓冲区类型映射：
| BufferDesc.bufferType | OpenGLBufferType |
|----------------------|------------------|
| 0 (默认) | Vertex (顶点缓冲区) |
| 1 | Index (索引缓冲区) |
| 2 | Uniform (常量缓冲区/Uniform Buffer) |
### 缓冲区类型
- **Vertex Buffer**: 存储顶点属性数据（位置、法线、UV 等）
- **Index Buffer**: 存储顶点索引，用于索引绘制
- **Uniform Buffer**: 存储着色器 uniforms 数据
## 参数
- `desc` - 缓冲区描述符
### BufferDesc 字段
| 字段 | 描述 |
|------|------|
| `bufferType` | 缓冲区类型 (0=顶点, 1=索引, 2=Uniform) |
| `size` | 缓冲区大小（字节） |
## 返回值
`RHIBuffer*` - 创建的缓冲区指针，失败返回 `nullptr`
## 注意事项
- 当前实现创建的缓冲区初始数据为 `nullptr`（空缓冲区）
- 缓冲区创建后可使用 `OpenGLBuffer` 的接口进行数据更新
- 返回的缓冲区对象归调用者所有，需自行管理生命周期
## 示例
```cpp
// 创建顶点缓冲区
BufferDesc vertexDesc;
vertexDesc.bufferType = 0; // Vertex
vertexDesc.size = sizeof(Vertex) * vertexCount;
RHIBuffer* vertexBuffer = device.CreateBuffer(vertexDesc);
// 创建索引缓冲区
BufferDesc indexDesc;
indexDesc.bufferType = 1; // Index
indexDesc.size = sizeof(uint32_t) * indexCount;
RHIBuffer* indexBuffer = device.CreateBuffer(indexDesc);
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [OpenGLBuffer](../opengl-buffer.md) - OpenGL 缓冲区实现

49
docs/api/rhi/opengl/device/create-command-list.md Normal file
View File

@@ -0,0 +1,49 @@
# OpenGLDevice::CreateCommandList
```cpp
RHICommandList* CreateCommandList(const CommandListDesc& desc) override
```
创建 OpenGL 命令列表对象。
## 详细描述
创建用于记录 GPU 命令的命令列表对象。
### OpenGL 实现
当前实现创建基本的 `OpenGLCommandList`，支持：
- 命令录制
- 命令重放
## 参数
- `desc` - 命令列表描述符
## 返回值
`RHICommandList*` - 创建的命令列表指针
## 注意事项
- 返回的命令列表对象归调用者所有，需自行管理生命周期
- 命令列表使用前可能需要额外初始化步骤
## 示例
```cpp
CommandListDesc cmdDesc;
RHICommandList* cmdList = device.CreateCommandList(cmdDesc);
// 录制命令
cmdList->Begin();
cmdList->Draw(...);
cmdList->End();
// 提交命令
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [OpenGLCommandList](../opengl-command-list.md) - OpenGL 命令列表实现

45
docs/api/rhi/opengl/device/create-command-queue.md Normal file
View File

@@ -0,0 +1,45 @@
# OpenGLDevice::CreateCommandQueue
```cpp
RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc) override
```
创建 OpenGL 命令队列对象。
## 详细描述
创建用于管理命令列表提交的命令队列。
### OpenGL 实现
当前实现创建 `OpenGLCommandQueue`，用于：
- 命令列表提交
- 命令同步
## 参数
- `desc` - 命令队列描述符
## 返回值
`RHICommandQueue*` - 创建的命令队列指针
## 注意事项
- 返回的命令队列对象归调用者所有，需自行管理生命周期
- OpenGL 本身没有显式的命令队列概念，此为抽象接口实现
## 示例
```cpp
CommandQueueDesc queueDesc;
RHICommandQueue* queue = device.CreateCommandQueue(queueDesc);
// 提交命令列表到队列
queue->ExecuteCommandList(cmdList);
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [OpenGLCommandQueue](../opengl-command-queue.md) - OpenGL 命令队列实现

56
docs/api/rhi/opengl/device/create-fence.md Normal file
View File

@@ -0,0 +1,56 @@
# OpenGLDevice::CreateFence
```cpp
RHIFence* CreateFence(const FenceDesc& desc) override
```
创建同步栅栏对象。
## 详细描述
创建用于 GPU/CPU 同步的栅栏对象。
### FenceDesc 字段
| 字段 | 描述 |
|------|------|
| `initialValue` | 初始值（0=未 signaled, >0=signaled） |
### 行为
- `initialValue > 0`: 创建时栅栏处于 signaled 状态
- `initialValue == 0`: 创建时栅栏处于未 signaled 状态
## 参数
- `desc` - 栅栏描述符
## 返回值
`RHIFence*` - 创建的栅栏指针
## 注意事项
- 返回的栅栏对象归调用者所有，需自行管理生命周期
- 栅栏用于同步 GPU 命令执行和 CPU 代码执行
## 示例
```cpp
FenceDesc fenceDesc;
fenceDesc.initialValue = 0;
RHIFence* fence = device.CreateFence(fenceDesc);
// 等待栅栏
while (!fence->IsSignaled()) {
// 等待或做其他工作
}
// GPU 命令完成，栅栏 signaled
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [OpenGLFence](../opengl-fence.md) - OpenGL 栅栏实现

53
docs/api/rhi/opengl/device/create-pipeline-state.md Normal file
View File

@@ -0,0 +1,53 @@
# OpenGLDevice::CreatePipelineState
```cpp
RHIPipelineState* CreatePipelineState(const PipelineStateDesc& desc) override
```
创建图形管线状态对象。
## 详细描述
创建封装完整渲染管线状态的 `RHIPipelineState` 对象。
### 管线组件
- 顶点/片段着色器
- 顶点格式
- 光栅化状态
- 混合状态
- 深度/模板状态
- 渲染目标格式
## 参数
- `desc` - 管线状态描述符
## 返回值
`RHIPipelineState*` - 创建的管线状态指针
## 注意事项
- 返回的管线状态对象归调用者所有，需自行管理生命周期
- 管线状态创建后可通过 `RHIPipelineState` 接口配置
## 示例
```cpp
PipelineStateDesc psoDesc;
psoDesc.vertexShader = vertexShader;
psoDesc.fragmentShader = fragmentShader;
psoDesc.vertexFormat = vertexFormat;
// ... 设置其他管线状态
RHIPipelineState* pso = device.CreatePipelineState(psoDesc);
// 绑定管线状态
pso->Bind();
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [OpenGLPipelineState](../opengl-pipeline-state.md) - OpenGL 管线状态实现

65
docs/api/rhi/opengl/device/create-sampler.md Normal file
View File

@@ -0,0 +1,65 @@
# OpenGLDevice::CreateSampler
```cpp
RHISampler* CreateSampler(const SamplerDesc& desc) override
```
创建纹理采样器对象。
## 详细描述
创建配置纹理采样参数的状态对象。
### 默认采样参数
当前实现使用默认采样参数（`OpenGLSamplerDesc` 零初始化）：
| 参数 | 默认值 |
|------|--------|
| 过滤模式 | 线性 |
| 地址模式 | Clamp |
| 各向异性 | 关闭 |
## 参数
- `desc` - 采样器描述符
### SamplerDesc 字段
| 字段 | 描述 |
|------|------|
| `minFilter` | 缩小过滤模式 |
| `magFilter` | 放大过滤模式 |
| `addressU/V/W` | UVW 坐标寻址模式 |
| `maxAnisotropy` | 最大各向异性级别 |
## 返回值
`RHISampler*` - 创建的采样器指针
## 注意事项
- 返回的采样器对象归调用者所有，需自行管理生命周期
- 当前实现忽略输入的 `desc`，使用默认参数
- 采样器需要绑定到纹理单元才能使用
## 示例
```cpp
SamplerDesc samplerDesc;
samplerDesc.minFilter = FilterMode::Linear;
samplerDesc.magFilter = FilterMode::Linear;
samplerDesc.addressU = AddressMode::Clamp;
samplerDesc.addressV = AddressMode::Clamp;
samplerDesc.maxAnisotropy = 16;
RHISampler* sampler = device.CreateSampler(samplerDesc);
// 绑定到纹理单元
sampler->Bind(0);
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [OpenGLSampler](../opengl-sampler.md) - OpenGL 采样器实现

61
docs/api/rhi/opengl/device/create-swap-chain.md Normal file
View File

@@ -0,0 +1,61 @@
# OpenGLDevice::CreateSwapChain
```cpp
RHISwapChain* CreateSwapChain(const SwapChainDesc& desc) override
```
创建 OpenGL 交换链对象。
## 详细描述
创建与设备窗口关联的交换链，用于管理前后缓冲区的交换。
### 交换链行为
- 使用窗口的当前尺寸初始化交换链
- 通过 `SwapBuffers()` 执行缓冲区交换
- 交换链与 GLFW 窗口 (`m_window`) 关联
## 参数
- `desc` - 交换链描述符
### SwapChainDesc 字段
| 字段 | 描述 |
|------|------|
| `width` | 缓冲区宽度 |
| `height` | 缓冲区高度 |
## 返回值
`RHISwapChain*` - 创建的交换链指针
## 注意事项
- 如果 `m_window` 为 `nullptr`，交换链创建失败
- 返回的交换链对象归调用者所有，需自行管理生命周期
- 交换链尺寸应与窗口尺寸匹配
## 示例
```cpp
SwapChainDesc swapDesc;
swapDesc.width = 1280;
swapDesc.height = 720;
RHISwapChain* swapChain = device.CreateSwapChain(swapDesc);
// 在渲染循环中使用
while (!device.ShouldClose()) {
device.PollEvents();
renderScene();
device.SwapBuffers();
}
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [OpenGLSwapChain](../opengl-swap-chain.md) - OpenGL 交换链实现
- [SwapBuffers](swap-buffers.md) - 交换缓冲区

81
docs/api/rhi/opengl/device/create-texture.md Normal file
View File

@@ -0,0 +1,81 @@
# OpenGLDevice::CreateTexture
```cpp
RHITexture* CreateTexture(const TextureDesc& desc) override
```
创建 OpenGL 纹理对象。
## 详细描述
根据 `TextureDesc` 创建一个 OpenGL 纹理对象。纹理类型映射：
| TextureDesc.textureType | OpenGLTextureType |
|------------------------|-------------------|
| 0 | Texture1D |
| 1 (默认) | Texture2D |
| 2 | Texture3D |
| 3 | TextureCube |
### 纹理格式
当前实现固定使用 `RGBA8` (RGBA, 8 bits per channel) 格式。
### 纹理参数
| 参数 | 值 |
|------|-----|
| 格式 | RGBA8 |
| Mipmap | 根据 `desc.mipLevels` |
| 类型 | GL_UNSIGNED_BYTE |
## 参数
- `desc` - 纹理描述符
### TextureDesc 字段
| 字段 | 描述 |
|------|------|
| `textureType` | 纹理类型 (0=1D, 1=2D, 2=3D, 3=Cube) |
| `width` | 纹理宽度 |
| `height` | 纹理高度 |
| `depth` | 纹理深度（用于 3D 纹理） |
| `mipLevels` | Mipmap 级别数量 |
## 返回值
`RHITexture*` - 创建的纹理指针
## 注意事项
- 当前实现创建的纹理初始数据为 `nullptr`（空纹理）
- 返回的纹理对象归调用者所有，需自行管理生命周期
- 1D 纹理使用 `height=1`，3D 纹理使用 `depth` 参数
## 示例
```cpp
// 创建 2D 纹理
TextureDesc tex2dDesc;
tex2dDesc.textureType = 1; // Texture2D
tex2dDesc.width = 1024;
tex2dDesc.height = 1024;
tex2dDesc.mipLevels = 1;
RHITexture* tex2d = device.CreateTexture(tex2dDesc);
// 创建立方体纹理
TextureDesc texCubeDesc;
texCubeDesc.textureType = 3; // TextureCube
texCubeDesc.width = 512;
texCubeDesc.height = 512;
texCubeDesc.mipLevels = 1;
RHITexture* texCube = device.CreateTexture(texCubeDesc);
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [OpenGLTexture](../opengl-texture.md) - OpenGL 纹理实现

33
docs/api/rhi/opengl/device/destructor.md Normal file
View File

@@ -0,0 +1,33 @@
# OpenGLDevice::~OpenGLDevice
```cpp
~OpenGLDevice() override
```
析构函数，销毁 `OpenGLDevice` 实例。
## 详细描述
析构函数调用 `Shutdown()` 清理资源：
- 如果设备拥有窗口 (`m_ownsWindow == true`)，则销毁 GLFW 窗口
- 重置所有内部状态
## 注意事项
- 建议在销毁前显式调用 `Shutdown()` 以确保资源正确释放
- 析构函数是虚函数，支持多态删除
## 示例
```cpp
{
OpenGLDevice device;
device.Initialize(desc);
// ... 使用设备
} // 析构时自动调用 Shutdown()
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [Shutdown](shutdown.md) - 关闭设备

103
docs/api/rhi/opengl/device/device.md
View File

@@ -2,34 +2,101 @@
**命名空间**: `XCEngine::RHI`
**描述**: OpenGL 设备的实现，继承自 `RHIDevice`。
**继承自**: `RHIDevice`
**描述**: OpenGL 设备的实现，基于 GLFW 和 Glad 提供 OpenGL 图形渲染能力。支持创建窗口、管理渲染资源、编译着色器等核心 RHI 功能。
## 概述
`OpenGLDevice` 是 XCEngine RHI 模块的 OpenGL 后端实现，通过 GLFW 管理窗口上下文，使用 Glad 加载 OpenGL 函数。它继承自抽象接口 `RHIDevice`，提供与具体图形 API 无关的统一接口。
### 主要功能
- 基于 GLFW 的窗口管理和事件处理
- OpenGL 3.3 Core Profile 上下文初始化
- 使用 Glad 动态加载 OpenGL 函数
- 设备能力查询和信息收集
- 渲染资源创建（缓冲区、纹理、着色器等）
### 版本要求
- OpenGL 3.3 Core Profile
- GLFW 3.0+
- Glad OpenGL 3.3+
## 公共方法
| 方法 | 描述 |
|------|------|
| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化设备 |
| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭设备 |
| [`OpenGLDevice`](constructor.md) | 构造函数 |
| [`~OpenGLDevice`](destructor.md) | 析构函数 |
| [`Initialize`](initialize.md) | 初始化设备 |
| [`Shutdown`](shutdown.md) | 关闭设备 |
| [`CreateRenderWindow`](create-render-window.md) | 创建渲染窗口 |
| [`InitializeWithExistingWindow`](initialize-with-existing-window.md) | 使用现有窗口初始化 |
| [`GetWindow`](get-window.md) | 获取窗口 |
| [`SwapBuffers`](swap-buffers.md) | 交换缓冲 |
| [`GetWindow`](get-window.md) | 获取 GLFW 窗口指针 |
| [`GetDeviceInfoImpl`](get-device-info-impl.md) | 获取设备信息实现 |
| [`SwapBuffers`](swap-buffers.md) | 交换前后缓冲区 |
| [`PollEvents`](poll-events.md) | 处理窗口事件 |
| [`SetShouldClose`](set-should-close.md) | 设置关闭标志 |
| [`ShouldClose`](should-close.md) | 检查是否应关闭 |
| [`CreateBuffer`](../../device/create-buffer.md) | 创建缓冲区 |
| [`CreateTexture`](../../device/create-texture.md) | 创建纹理 |
| [`CreateSwapChain`](../../device/create-swap-chain.md) | 创建交换链 |
| [`CreateCommandList`](../../device/create-command-list.md) | 创建命令列表 |
| [`CreateCommandQueue`](../../device/create-command-queue.md) | 创建命令队列 |
| [`CompileShader`](../../device/compile-shader.md) | 编译着色器 |
| [`CreatePipelineState`](../../device/create-pipeline-state.md) | 创建管线状态 |
| [`CreateFence`](../../device/create-fence.md) | 创建栅栏 |
| [`CreateSampler`](../../device/create-sampler.md) | 创建采样器 |
| [`GetCapabilities`](../../device/get-capabilities.md) | 获取设备能力 |
| [`GetDeviceInfo`](../../device/get-device-info.md) | 获取设备信息 |
| [`GetNativeDevice`](../../device/get-native-device.md) | 获取原生设备 |
| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 |
| [`CreateBuffer`](create-buffer.md) | 创建缓冲区 |
| [`CreateTexture`](create-texture.md) | 创建纹理 |
| [`CreateSwapChain`](create-swap-chain.md) | 创建交换链 |
| [`CreateCommandList`](create-command-list.md) | 创建命令列表 |
| [`CreateCommandQueue`](create-command-queue.md) | 创建命令队列 |
| [`CompileShader`](compile-shader.md) | 编译着色器 |
| [`CreatePipelineState`](create-pipeline-state.md) | 创建管线状态 |
| [`CreateFence`](create-fence.md) | 创建栅栏 |
| [`CreateSampler`](create-sampler.md) | 创建采样器 |
| [`GetCapabilities`](get-capabilities.md) | 获取设备能力 |
| [`GetDeviceInfo`](get-device-info.md) | 获取设备信息 |
| [`GetNativeDevice`](get-native-device.md) | 获取原生设备 |
| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 |
## 使用示例
```cpp
#include "XCEngine/RHI/OpenGL/OpenGLDevice.h"
using namespace XCEngine::RHI;
// 创建并初始化 OpenGL 设备
OpenGLDevice device;
RHIDeviceDesc desc;
desc.width = 1280;
desc.height = 720;
desc.appName = L"XCEngine App";
desc.enableDebugLayer = true;
if (!device.Initialize(desc)) {
return false;
}
// 渲染循环
while (!device.ShouldClose()) {
device.PollEvents();
// 渲染逻辑
renderScene();
device.SwapBuffers();
}
// 清理
device.Shutdown();
```
### 使用已有 GLFW 窗口
```cpp
GLFWwindow* existingWindow = glfwCreateWindow(1280, 720, "My Window", nullptr, nullptr);
OpenGLDevice device;
if (device.InitializeWithExistingWindow(existingWindow)) {
// 使用已有窗口继续渲染
}
```
## 相关文档

57
docs/api/rhi/opengl/device/get-capabilities.md Normal file
View File

@@ -0,0 +1,57 @@
# OpenGLDevice::GetCapabilities
```cpp
const RHICapabilities& GetCapabilities() const override
```
获取 OpenGL 设备能力。
## 详细描述
返回设备的硬件能力和特性支持信息。能力信息在 `InitializeWithExistingWindow()` 期间通过查询 OpenGL 获得。
### 查询的能力项
| 能力字段 | 描述 | OpenGL 查询 |
|----------|------|-------------|
| `majorVersion` | OpenGL 主版本 | GL_MAJOR_VERSION |
| `minorVersion` | OpenGL 次版本 | GL_MINOR_VERSION |
| `bSupportsGeometryShaders` | 几何着色器支持 | 始终 true |
| `bSupportsComputeShaders` | 计算着色器支持 | GL_VERSION >= 4.3 |
| `bSupportsTessellation` | 曲面细分支持 | GL_VERSION >= 4.1 |
| `bSupportsExplicitMultiThreading` | 多线程支持 | 始终 false |
| `maxTexture2DSize` | 2D 纹理最大尺寸 | GL_MAX_TEXTURE_SIZE |
| `maxTextureCubeSize` | 立方体贴图最大尺寸 | GL_MAX_CUBE_MAP_TEXTURE_SIZE |
| `maxRenderTargets` | 最大渲染目标数 | GL_MAX_DRAW_BUFFERS |
| `maxColorAttachments` | 最大颜色附件数 | GL_MAX_DRAW_BUFFERS |
| `maxViewports` | 最大视口数 | GL_MAX_VIEWPORTS |
| `maxAnisotropy` | 最大各向异性级别 | GL_MAX_TEXTURE_MAX_ANISOTROPY |
| `maxVertexAttribs` | 最大顶点属性数 | GL_MAX_VERTEX_ATTRIBS |
## 返回值
`const RHICapabilities&` - 设备能力结构的常量引用
## 复杂度
O(1) - 返回内部缓存的能力信息
## 示例
```cpp
const RHICapabilities& caps = device.GetCapabilities();
std::cout << "OpenGL Version: " << caps.majorVersion << "." << caps.minorVersion << std::endl;
std::cout << "Max Texture Size: " << caps.maxTexture2DSize << std::endl;
std::cout << "Max Render Targets: " << caps.maxRenderTargets << std::endl;
if (caps.bSupportsComputeShaders) {
std::cout << "Compute shaders supported" << std::endl;
}
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [RHICapabilities](../../capabilities/capabilities.md) - 能力结构定义
- [GetDeviceInfo](get-device-info.md) - 获取设备信息

39
docs/api/rhi/opengl/device/get-device-info-impl.md Normal file
View File

@@ -0,0 +1,39 @@
# OpenGLDevice::GetDeviceInfoImpl
```cpp
const RHIDeviceInfo& GetDeviceInfoImpl() const
```
获取设备信息的内部实现。
## 详细描述
返回存储在设备中的 `RHIDeviceInfo` 结构，包含 OpenGL 设备的具体信息：
- **vendor**: GPU 厂商名称
- **renderer**: GPU 渲染器名称
- **version**: OpenGL 驱动版本
- **majorVersion**: OpenGL 主版本号
- **minorVersion**: OpenGL 次版本号
此方法直接返回内部缓存的设备信息，无需额外查询。
## 返回值
`const RHIDeviceInfo&` - 设备信息结构的常量引用
## 复杂度
O(1)
## 示例
```cpp
const RHIDeviceInfo& info = device.GetDeviceInfoImpl();
std::wcout << L"GPU: " << info.renderer << std::endl;
std::wcout << L"OpenGL Version: " << info.majorVersion << L"." << info.minorVersion << std::endl;
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [GetDeviceInfo](get-device-info.md) - 获取设备信息（公共接口）

53
docs/api/rhi/opengl/device/get-device-info.md Normal file
View File

@@ -0,0 +1,53 @@
# OpenGLDevice::GetDeviceInfo
```cpp
const RHIDeviceInfo& GetDeviceInfo() const override
```
获取 OpenGL 设备信息。
## 详细描述
返回设备的标识和版本信息。设备信息在 `InitializeWithExistingWindow()` 期间通过 `glGetString()` 和 `glGetIntegerv()` 查询获得。
### 设备信息内容
| 信息字段 | 描述 | OpenGL 来源 |
|----------|------|-------------|
| `vendor` | GPU 厂商 | GL_VENDOR |
| `renderer` | GPU 渲染器名称 | GL_RENDERER |
| `version` | OpenGL 版本字符串 | GL_VERSION |
| `majorVersion` | OpenGL 主版本号 | GL_MAJOR_VERSION |
| `minorVersion` | OpenGL 次版本号 | GL_MINOR_VERSION |
### 厂商示例
- **NVIDIA**: "NVIDIA Corporation"
- **AMD**: "AMD" 或 "Advanced Micro Devices, Inc."
- **Intel**: "Intel" 或 "Intel Corporation"
## 返回值
`const RHIDeviceInfo&` - 设备信息结构的常量引用
## 复杂度
O(1) - 返回内部缓存的设备信息
## 示例
```cpp
const RHIDeviceInfo& info = device.GetDeviceInfo();
std::wcout << L"Vendor: " << info.vendor << std::endl;
std::wcout << L"Renderer: " << info.renderer << std::endl;
std::wcout << L"Version: " << info.version << std::endl;
std::cout << "GL Version: " << info.majorVersion << "." << info.minorVersion << std::endl;
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [RHIDeviceInfo](../../types/device-info.md) - 设备信息结构定义
- [GetCapabilities](get-capabilities.md) - 获取设备能力
- [GetDeviceInfoImpl](get-device-info-impl.md) - 获取设备信息实现

35
docs/api/rhi/opengl/device/get-native-device.md Normal file
View File

@@ -0,0 +1,35 @@
# OpenGLDevice::GetNativeDevice
```cpp
void* GetNativeDevice() override
```
获取原生图形设备指针。
## 详细描述
返回原生图形 API 的设备指针。OpenGL 是一种状态机模型，没有传统意义上的"设备"对象，因此此方法返回 `nullptr`。
## 返回值
`void*` - 始终返回 `nullptr`（OpenGL 无原生设备对象）
## 注意事项
- OpenGL 使用隐式状态机模式，不需要显式的设备对象
- 如需获取 OpenGL 上下文相关信息，使用 `GetCapabilities()` 或 `GetDeviceInfo()`
- 如需获取窗口句柄，使用 `GetWindow()` 方法
## 示例
```cpp
void* native = device.GetNativeDevice();
// 注意：当前实现返回 nullptr
// OpenGL 为状态机，无需设备对象
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [GetWindow](get-window.md) - 获取 GLFW 窗口
- [GetCapabilities](get-capabilities.md) - 获取设备能力

26
docs/api/rhi/opengl/device/get-native-handle.md Normal file
View File

@@ -0,0 +1,26 @@
# OpenGLDevice::GetNativeHandle
```cpp
void* GetNativeHandle() const
```
获取原生窗口或渲染上下文句柄。
**返回：** `void*` - 原生句柄（当前实现返回 `nullptr`）
**复杂度：** O(1)
**注意：** 此方法当前实现返回 `nullptr`。使用 `GetWindow()` 获取 GLFW 窗口指针。
**示例：**
```cpp
void* handle = device.GetNativeHandle();
// 注意：当前实现返回 nullptr
GLFWwindow* window = device.GetWindow(); // 使用此方法获取窗口
```
## 相关文档
- [OpenGLDevice](device.md) - 返回类总览
- [GetWindow](get-window.md) - 获取 GLFW 窗口指针

64
docs/api/rhi/opengl/device/initialize.md Normal file
View File

@@ -0,0 +1,64 @@
# OpenGLDevice::Initialize
```cpp
bool Initialize(const RHIDeviceDesc& desc) override
```
初始化 OpenGL 设备。
## 详细描述
根据 `RHIDeviceDesc` 初始化 OpenGL 设备。初始化过程包括：
1. **检查是否已初始化**: 如果已初始化，直接返回 `true`
2. **窗口处理**:
- 如果 `desc.windowHandle` 提供现有窗口，调用 `InitializeWithExistingWindow()`
- 否则调用 `CreateRenderWindow()` 创建新窗口
3. **GLFW 初始化**: 确保 GLFW 库已初始化
4. **OpenGL 上下文**: 创建 OpenGL 3.3 Core Profile 上下文
5. **Glad 加载**: 使用 Glad 动态加载 OpenGL 函数
6. **设备信息收集**: 获取 GPU 厂商、渲染器、版本等信息
7. **能力查询**: 查询并存储 OpenGL 设备能力
### RHIDeviceDesc 字段说明
| 字段 | 描述 |
|------|------|
| `width` | 窗口宽度（当创建新窗口时） |
| `height` | 窗口高度（当创建新窗口时） |
| `appName` | 应用程序名称（用于窗口标题） |
| `enableDebugLayer` | 是否启用调试上下文 |
| `windowHandle` | 现有 GLFW 窗口句柄（可选） |
## 参数
- `desc` - 设备描述符，包含初始化参数
## 返回值
`bool` - 初始化成功返回 `true`，失败返回 `false`
## 示例
```cpp
OpenGLDevice device;
RHIDeviceDesc desc;
desc.width = 1920;
desc.height = 1080;
desc.appName = L"My OpenGL App";
desc.enableDebugLayer = true;
if (!device.Initialize(desc)) {
// 处理初始化失败
return;
}
// 设备已就绪，可以开始渲染
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [CreateRenderWindow](create-render-window.md) - 创建渲染窗口
- [InitializeWithExistingWindow](initialize-with-existing-window.md) - 使用现有窗口初始化
- [Shutdown](shutdown.md) - 关闭设备

49
docs/api/rhi/opengl/device/shutdown.md Normal file
View File

@@ -0,0 +1,49 @@
# OpenGLDevice::Shutdown
```cpp
void Shutdown() override
```
关闭 OpenGL 设备并释放相关资源。
## 详细描述
关闭 OpenGL 设备并执行清理操作：
1. **窗口销毁**: 如果设备拥有窗口 (`m_ownsWindow == true`)，调用 `glfwDestroyWindow()` 销毁 GLFW 窗口
2. **状态重置**:
- `m_window` 设为 `nullptr`
- `m_initialized` 设为 `false`
- `m_ownsWindow` 设为 `false`
### 窗口所有权
设备可能通过两种方式获得窗口：
- **自有窗口**: 通过 `CreateRenderWindow()` 创建，设备负责销毁
- **外部窗口**: 通过 `InitializeWithExistingWindow()` 传入，设备不负责销毁
## 注意事项
- 多次调用 `Shutdown()` 是安全的
- 销毁窗口后，与该窗口关联的 OpenGL 上下文将无效
- 建议在程序结束前显式调用 `Shutdown()`
## 示例
```cpp
{
OpenGLDevice device;
device.Initialize(desc);
// ... 使用设备进行渲染
device.Shutdown(); // 显式关闭
}
// 或等待析构函数自动调用
```
## 相关文档
- [OpenGLDevice](device.md) - 类总览
- [Initialize](initialize.md) - 初始化设备
- [CreateRenderWindow](create-render-window.md) - 创建渲染窗口