docs: 更新 API 文档 - 多模块修复和完善

- audio: 更新 audio-system 方法文档 - components: 新增 audio-listener/audio-source 组件方法文档，新增 remove-component 方法 - core: 更新 filewriter, types 文档 - math: 更新 box 方法文档 - memory: 更新 proxy-allocator 文档 - resources: 更新 loader 和 texture 文档 - rhi: 更新 opengl 设备、shader、swap-chain 文档 - threading: 更新 mutex 和 task-system 文档
2026-03-26 01:58:45 +08:00
parent 445876752c
commit 8df04c120f
81 changed files with 1747 additions and 170 deletions
--- a/docs/api/rhi/device/device.md
+++ b/docs/api/rhi/device/device.md
@@ -25,7 +25,7 @@
 | [`CreateSwapChain`](create-swap-chain.md) | 创建交换链 |
 | [`CreateCommandList`](create-command-list.md) | 创建命令列表 |
 | [`CreateCommandQueue`](create-command-queue.md) | 创建命令队列 |
-| [`CompileShader`](compile-shader.md) | 编译着色器 |
+| [`CreateShader`](create-shader.md) | 创建着色器 |
 | [`CreatePipelineState`](create-pipeline-state.md) | 创建管线状态 |
 | [`CreateFence`](create-fence.md) | 创建栅栏 |
 | [`CreateSampler`](create-sampler.md) | 创建采样器 |
--- a/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md
+++ b/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md
@@ -31,8 +31,6 @@
 | [`GetFramebuffer`](get-framebuffer.md) | 获取帧缓冲 |
 | [`GetTexture`](get-texture.md) | 获取纹理 |
 | [`GetMipLevel`](get-mip-level.md) | 获取 Mip 级别 |
-| [`GetWidth`](get-size.md) | 获取宽度 |
-| [`GetHeight`](get-size.md) | 获取高度 |
 | [`BindFramebuffer`](bind-framebuffer.md) | 绑定帧缓冲 |
 | [`UnbindFramebuffer`](unbind-framebuffer.md) | 解绑帧缓冲 |

--- a/docs/api/rhi/opengl/device/device.md
+++ b/docs/api/rhi/opengl/device/device.md
@@ -4,26 +4,20 @@

 **继承自**: `RHIDevice`

-**描述**: OpenGL 设备的实现，基于 GLFW 和 Glad 提供 OpenGL 图形渲染能力。支持创建窗口、管理渲染资源、编译着色器等核心 RHI 功能。
+**描述**: OpenGL 设备的实现，基于 Windows 原生窗口（HWND）和 Glad 提供 OpenGL 图形渲染能力。

 ## 概述

-`OpenGLDevice` 是 XCEngine RHI 模块的 OpenGL 后端实现，通过 GLFW 管理窗口上下文，使用 Glad 加载 OpenGL 函数。它继承自抽象接口 `RHIDevice`，提供与具体图形 API 无关的统一接口。
+`OpenGLDevice` 是 XCEngine RHI 模块的 OpenGL 后端实现，通过 Windows HWND 管理窗口上下文，使用 Glad 加载 OpenGL 函数。它继承自抽象接口 `RHIDevice`，提供与具体图形 API 无关的统一接口。

 ### 主要功能

- 基于 GLFW 的窗口管理和事件处理
+- 基于 Windows HWND 的窗口管理和事件处理
 - OpenGL 3.3 Core Profile 上下文初始化
 - 使用 Glad 动态加载 OpenGL 函数
 - 设备能力查询和信息收集
 - 渲染资源创建（缓冲区、纹理、着色器等）

-### 版本要求
-
- OpenGL 3.3 Core Profile
- GLFW 3.0+
- Glad OpenGL 3.3+
-
 ## 公共方法

 | 方法 | 描述 |
@@ -32,22 +26,15 @@
 | [`~OpenGLDevice`](destructor.md) | 析构函数 |
 | [`Initialize`](initialize.md) | 初始化设备 |
 | [`Shutdown`](shutdown.md) | 关闭设备 |
-| [`CreateRenderWindow`](create-render-window.md) | 创建渲染窗口 |
 | [`InitializeWithExistingWindow`](initialize-with-existing-window.md) | 使用现有窗口初始化 |
-| [`GetWindow`](get-window.md) | 获取 GLFW 窗口指针 |
-| [`GetDC`](get-dc.md) | 获取 Windows 设备上下文 |
-| [`GetContext`](get-context.md) | 获取 OpenGL 渲染上下文 |
-| [`GetDeviceInfoImpl`](get-device-info-impl.md) | 获取设备信息实现 |
-| [`SwapBuffers`](swap-buffers.md) | 交换前后缓冲区 |
-| [`PollEvents`](poll-events.md) | 处理窗口事件 |
-| [`SetShouldClose`](set-should-close.md) | 设置关闭标志 |
-| [`ShouldClose`](should-close.md) | 检查是否应关闭 |
+| [`MakeContextCurrent`](make-context-current.md) | 使 OpenGL 上下文为当前上下文 |
+| [`GetNativeContext`](get-native-context.md) | 获取 OpenGL 渲染上下文句柄 |
 | [`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) | 编译着色器 |
+| [`CreateShader`](create-shader.md) | 创建着色器 |
 | [`CreatePipelineState`](create-pipeline-state.md) | 创建管线状态 |
 | [`CreateFence`](create-fence.md) | 创建栅栏 |
 | [`CreateSampler`](create-sampler.md) | 创建采样器 |
@@ -76,25 +63,17 @@ if (!device.Initialize(desc)) {
 }

 // 渲染循环
-while (!device.ShouldClose()) {
-    device.PollEvents();
-    
-    // 渲染逻辑
-    renderScene();
-    
-    device.SwapBuffers();
-}
+// (OpenGL 采用立即模式，渲染逻辑在主循环中执行)

 // 清理
 device.Shutdown();
 ```

-### 使用已有 GLFW 窗口
+### 使用已有 Windows 窗口

 ```cpp
-GLFWwindow* existingWindow = glfwCreateWindow(1280, 720, "My Window", nullptr, nullptr);
-
 OpenGLDevice device;
+HWND existingWindow = /* 获取 Windows 窗口句柄 */;
 if (device.InitializeWithExistingWindow(existingWindow)) {
    // 使用已有窗口继续渲染
 }
--- a/docs/api/rhi/opengl/pipeline-state/pipeline-state.md
+++ b/docs/api/rhi/opengl/pipeline-state/pipeline-state.md
@@ -20,7 +20,6 @@
 | [`SetRasterizerState`](set-rasterizer-state.md) | 设置光栅化状态 |
 | [`SetViewport`](set-viewport.md) | 设置视口 |
 | [`SetScissor`](set-scissor.md) | 设置裁剪 |
-| [`SetLogicalOperation`](set-logical-operation.md) | 设置逻辑操作 |
 | [`Apply`](apply.md) | 应用管线状态 |
 | [`ApplyDepthStencil`](apply-depth-stencil.md) | 应用深度模板状态 |
 | [`ApplyBlend`](apply-blend.md) | 应用混合状态 |
--- a/docs/api/rhi/opengl/shader/shader.md
+++ b/docs/api/rhi/opengl/shader/shader.md
@@ -24,23 +24,6 @@
 | [`Bind`](../../shader/bind.md) | 绑定着色器 |
 | [`Unbind`](../../shader/unbind.md) | 解绑着色器 |

-### Uniform 设置方法
-
-| 方法 | 描述 |
-|------|------|
-| [`SetInt`](../../shader/set-int.md) | 设置整数 uniform |
-| [`SetIntArray`](set-int-array.md) | 设置整数数组 uniform |
-| [`SetFloat`](../../shader/set-float.md) | 设置浮点数 uniform |
-| [`SetFloatArray`](set-float-array.md) | 设置浮点数数组 uniform |
-| [`SetVec3`](../../shader/set-vec3.md) | 设置 vec3 uniform (xyz分量) |
-| [`SetVec3`](set-vec3-array.md) | 设置 vec3 uniform (数组) |
-| [`SetVec4`](../../shader/set-vec4.md) | 设置 vec4 uniform (xyzw分量) |
-| [`SetVec4`](set-vec4-array.md) | 设置 vec4 uniform (数组) |
-| [`SetMat2`](set-mat2.md) | 设置 mat2 uniform |
-| [`SetMat3`](set-mat3.md) | 设置 mat3 uniform |
-| [`SetMat4`](../../shader/set-mat4.md) | 设置 mat4 uniform |
-| [`SetMat4Array`](set-mat4-array.md) | 设置 mat4 数组 uniform |
-
 ### 查询方法

 | 方法 | 描述 |
--- a/docs/api/rhi/opengl/swap-chain/swap-chain.md
+++ b/docs/api/rhi/opengl/swap-chain/swap-chain.md
@@ -24,26 +24,14 @@
 | [`OpenGLSwapChain`](constructor.md) | 构造函数 |
 | [`~OpenGLSwapChain`](destructor.md) | 析构函数 |
 | [`Initialize`](initialize.md) | 初始化交换链 |
-| [`Initialize(mode)`](initialize-mode.md) | 使用模式初始化 |
 | [`Shutdown`](shutdown.md) | 关闭交换链 |
 | [`Present`](present.md) | 呈现画面 |
 | [`SwapBuffers`](swap-buffers.md) | 交换缓冲 |
 | [`Resize`](resize.md) | 调整交换链大小 |
-| [`SetVSync`](set-vsync.md) | 设置垂直同步 |
-| [`IsVSync`](is-vsync.md) | 检查是否垂直同步 |
-| [`SetFullscreen`](set-fullscreen.md) | 设置全屏模式 |
-| [`IsFullscreen`](is-fullscreen.md) | 检查是否全屏 |
-| [`ShouldClose`](should-close.md) | 检查是否应关闭 |
-| [`SetShouldClose`](set-should-close.md) | 设置关闭标志 |
-| [`PollEvents`](poll-events.md) | 处理窗口事件 |
 | [`GetCurrentBackBufferIndex`](get-current-back-buffer-index.md) | 获取当前后台缓冲区索引 |
 | [`GetCurrentBackBuffer`](get-current-back-buffer.md) | 获取当前后台缓冲区 |
 | [`GetWidth`](get-width.md) | 获取宽度 |
 | [`GetHeight`](get-height.md) | 获取高度 |
-| [`GetFramebufferWidth`](get-framebuffer-width.md) | 获取帧缓冲宽度 |
-| [`GetFramebufferHeight`](get-framebuffer-height.md) | 获取帧缓冲高度 |
-| [`SetFramebufferSize`](set-framebuffer-size.md) | 设置帧缓冲大小 |
-| [`GetWindow`](get-window.md) | 获取窗口 |
 | [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 |

 ## 使用示例
@@ -53,16 +41,15 @@

 // 创建并初始化
 XCEngine::RHI::OpenGLSwapChain swapChain;
-GLFWwindow* window = /* 获取 GLFW 窗口 */;
-swapChain.Initialize(window, true);
+OpenGLDevice* device = /* 获取 OpenGLDevice */;
+HWND window = /* 获取窗口句柄 */;
+swapChain.Initialize(device, window, 1280, 720);

 // 游戏循环
-while (!swapChain.ShouldClose()) {
-    swapChain.PollEvents();
-    
+while (true) {
    // 渲染逻辑
    Render();
-    
+
    swapChain.Present(1, 0);
 }

--- a/docs/api/rhi/shader/shader.md
+++ b/docs/api/rhi/shader/shader.md
@@ -10,31 +10,22 @@

 ## 概述

-`RHIShader` 是 XCEngine RHI 模块中的抽象着色器接口类，定义了 GPU 着色器程序的标准 API。该类是所有具体着色器实现（如 D3D12Shader、VulkanShader 等）的基类，提供了统一的着色器编译、绑定和参数设置接口。
+`RHIShader` 是 XCEngine RHI 模块中的抽象着色器接口类，定义了 GPU 着色器程序的标准 API。该类是所有具体着色器实现（如 D3D12Shader、OpenGLShader 等）的基类，提供了统一的着色器编译和元数据查询接口。

 设计目的：
 - 提供跨平台的着色器抽象
- 统一着色器资源管理和绑定流程
+- 统一着色器编译和资源管理
 - 简化渲染管线中着色器的使用

 ## 公共方法

 | 方法 | 描述 |
 |------|------|
-| [`RHIShader`](constructor.md) | 默认构造函数 |
-| [`~RHIShader`](destructor.md) | 虚析构函数 |
 | [`CompileFromFile`](compile-from-file.md) | 从文件编译着色器 |
 | [`Compile`](compile.md) | 从内存数据编译着色器 |
 | [`GetType`](get-type.md) | 获取着色器类型 |
 | [`IsValid`](is-valid.md) | 检查着色器是否有效 |
-| [`Bind`](bind.md) | 绑定着色器到渲染管线 |
-| [`Unbind`](unbind.md) | 解绑着色器 |
 | [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 |
-| [`SetInt`](set-int.md) | 设置整数 uniform |
-| [`SetFloat`](set-float.md) | 设置浮点数 uniform |
-| [`SetVec3`](set-vec3.md) | 设置三维向量 uniform |
-| [`SetVec4`](set-vec4.md) | 设置四维向量 uniform |
-| [`SetMat4`](set-mat4.md) | 设置 4x4 矩阵 uniform |
 | [`Shutdown`](shutdown.md) | 释放着色器资源 |

 ## 公共属性
@@ -67,22 +58,14 @@

 using namespace XCEngine::RHI;

-// 通过 RHIDevice 编译着色器
+// 通过 RHIDevice 创建并编译着色器
 ShaderCompileDesc vsDesc;
 vsDesc.fileName = L"shaders/vertex.cso";
 vsDesc.entryPoint = "VSMain";
 vsDesc.profile = "vs_5_0";
-RHIShader* vertexShader = device->CompileShader(vsDesc);
+RHIShader* vertexShader = device->CreateShader(vsDesc);
 if (vertexShader && vertexShader->IsValid()) {
-    vertexShader->Bind();
-    
-    // 设置 uniform 参数
-    float modelMatrix[16] = { /* 4x4 模型矩阵数据 */ };
-    vertexShader->SetMat4("u_modelMatrix", modelMatrix);
-    
    // 渲染...
-    
-    vertexShader->Unbind();
 }

 if (vertexShader) {
--- a/docs/api/rhi/swap-chain/swap-chain.md
+++ b/docs/api/rhi/swap-chain/swap-chain.md
@@ -14,7 +14,6 @@

 主要职责：
 - 管理前后台缓冲区切换
- 处理窗口全屏/窗口化模式切换
 - 协调垂直同步呈现
 - 提供原生 API 句柄供高级用法

@@ -22,33 +21,24 @@

 | 方法 | 描述 |
 |------|------|
-| [`RHISwapChain`](constructor.md) | 默认构造函数 |
 | [`~RHISwapChain`](destructor.md) | 虚析构函数 |
 | [`Shutdown`](shutdown.md) | 关闭并释放资源 |
 | [`GetCurrentBackBufferIndex`](get-current-back-buffer-index.md) | 获取当前后台缓冲区索引 |
 | [`GetCurrentBackBuffer`](get-current-back-buffer.md) | 获取当前后台缓冲区 |
 | [`Present`](present.md) | 呈现画面 |
 | [`Resize`](resize.md) | 调整交换链大小 |
-| [`SetFullscreen`](set-fullscreen.md) | 设置全屏模式 |
-| [`IsFullscreen`](is-fullscreen.md) | 检查是否全屏 |
-| [`ShouldClose`](should-close.md) | 检查是否应关闭 |
-| [`SetShouldClose`](set-should-close.md) | 设置关闭标志 |
-| [`PollEvents`](poll-events.md) | 处理窗口事件 |
 | [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 |

 ## 使用示例

 ```cpp
-while (!swapChain->ShouldClose()) {
-    swapChain->PollEvents();
-    RHITexture* backBuffer = swapChain->GetCurrentBackBuffer();
-    commandList->Reset();
-    commandList->SetRenderTargets(1, &backBuffer, nullptr);
-    commandList->ClearRenderTarget(backBuffer, clearColor);
-    commandList->Close();
-    commandQueue->ExecuteCommandLists(1, (void**)&commandList);
-    swapChain->Present(1, 0);
-}
+RHITexture* backBuffer = swapChain->GetCurrentBackBuffer();
+commandList->Reset();
+commandList->SetRenderTargets(1, &backBuffer, nullptr);
+commandList->ClearRenderTarget(backBuffer, clearColor);
+commandList->Close();
+commandQueue->ExecuteCommandLists(1, (void**)&commandList);
+swapChain->Present(1, 0);
 ```

 ## 相关文档