diff --git a/docs/api/rhi/buffer/buffer.md b/docs/api/rhi/buffer/buffer.md index 1e774eff..a870866a 100644 --- a/docs/api/rhi/buffer/buffer.md +++ b/docs/api/rhi/buffer/buffer.md @@ -4,6 +4,8 @@ **类型**: `class` (abstract) +**头文件**: `XCEngine/RHI/RHIBuffer.h` + **描述**: GPU 缓冲区资源抽象接口，用于管理顶点缓冲、索引缓冲、常量缓冲等 GPU 内存资源。 ## 概述 diff --git a/docs/api/rhi/buffer/get-buffer-type.md b/docs/api/rhi/buffer/get-buffer-type.md index df2d53ff..863c3a81 100644 --- a/docs/api/rhi/buffer/get-buffer-type.md +++ b/docs/api/rhi/buffer/get-buffer-type.md @@ -4,12 +4,25 @@ virtual BufferType GetBufferType() const = 0; ``` -获取缓冲区类型。 +获取缓冲区的类型，用于区分顶点缓冲、索引缓冲、常量缓冲等。 -**返回：** 缓冲区类型枚举值 +**返回：** `BufferType` 枚举值 + +**线程安全：** ✅ **复杂度：** O(1) +**示例：** + +```cpp +BufferType type = buffer->GetBufferType(); +if (type == BufferType::Vertex) { + printf("This is a vertex buffer\n"); +} else if (type == BufferType::Index) { + printf("This is an index buffer\n"); +} +``` + ## 相关文档 - [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/get-name.md b/docs/api/rhi/buffer/get-name.md index 749f53fc..98f2eead 100644 --- a/docs/api/rhi/buffer/get-name.md +++ b/docs/api/rhi/buffer/get-name.md @@ -4,12 +4,21 @@ virtual const std::string& GetName() const = 0; ``` -获取缓冲区名称（用于调试）。 +获取缓冲区名称（用于调试和诊断）。名称通常在图形调试器（如 RenderDoc、PIX）中显示。 -**返回：** 缓冲区名称 +**返回：** 缓冲区名称字符串 + +**线程安全：** ✅ **复杂度：** O(1) +**示例：** + +```cpp +const std::string& name = buffer->GetName(); +printf("Buffer name: %s\n", name.c_str()); +``` + ## 相关文档 - [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/get-native-handle.md b/docs/api/rhi/buffer/get-native-handle.md index dabc40f9..e96eb90f 100644 --- a/docs/api/rhi/buffer/get-native-handle.md +++ b/docs/api/rhi/buffer/get-native-handle.md @@ -4,14 +4,26 @@ virtual void* GetNativeHandle() = 0; ``` -获取原生 API 句柄。 +获取底层图形 API 的原生资源句柄，用于平台特定操作或调试。 -**返回：** +**返回：** - D3D12: `ID3D12Resource*` -- OpenGL: `GLuint` 指针 +- Vulkan: `VkBuffer` +- OpenGL: `GLuint` + +**线程安全：** ✅ **复杂度：** O(1) +**示例：** + +```cpp +void* handle = buffer->GetNativeHandle(); +#ifdef _WIN32 + ID3D12Resource* d3d12Resource = static_cast(handle); +#endif +``` + ## 相关文档 - [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/get-size.md b/docs/api/rhi/buffer/get-size.md index 1e09922d..2a413ed4 100644 --- a/docs/api/rhi/buffer/get-size.md +++ b/docs/api/rhi/buffer/get-size.md @@ -4,12 +4,21 @@ virtual uint64_t GetSize() const = 0; ``` -获取缓冲区大小（字节）。 +获取缓冲区总大小（字节）。 -**返回：** 缓冲区大小 +**返回：** 缓冲区大小（字节） + +**线程安全：** ✅ **复杂度：** O(1) +**示例：** + +```cpp +uint64_t size = buffer->GetSize(); +printf("Buffer size: %llu bytes\n", (unsigned long long)size); +``` + ## 相关文档 - [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/get-state.md b/docs/api/rhi/buffer/get-state.md index c5818c83..f46e9993 100644 --- a/docs/api/rhi/buffer/get-state.md +++ b/docs/api/rhi/buffer/get-state.md @@ -4,12 +4,23 @@ virtual ResourceStates GetState() const = 0; ``` -获取当前资源状态。 +获取缓冲区当前所处的资源状态。资源状态决定缓冲区可以用于哪些 GPU 操作。 -**返回：** 资源状态枚举值 +**返回：** `ResourceStates` 枚举值 + +**线程安全：** ✅ **复杂度：** O(1) +**示例：** + +```cpp +ResourceStates state = buffer->GetState(); +if (state == ResourceStates::VertexAndConstantBuffer) { + printf("Buffer is ready for vertex binding\n"); +} +``` + ## 相关文档 - [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/get-stride.md b/docs/api/rhi/buffer/get-stride.md index 82b29828..88c59ca0 100644 --- a/docs/api/rhi/buffer/get-stride.md +++ b/docs/api/rhi/buffer/get-stride.md @@ -4,12 +4,21 @@ virtual uint32_t GetStride() const = 0; ``` -获取单个元素的字节大小。 +获取单个元素的字节大小（步长）。对于顶点缓冲是单个顶点的字节大小，对于索引缓冲是单个索引的字节大小。 **返回：** 元素步长（字节） +**线程安全：** ✅ + **复杂度：** O(1) +**示例：** + +```cpp +uint32_t stride = buffer->GetStride(); +printf("Element stride: %u bytes\n", stride); +``` + ## 相关文档 - [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/map.md b/docs/api/rhi/buffer/map.md index 70ef5a7d..8e3c59dc 100644 --- a/docs/api/rhi/buffer/map.md +++ b/docs/api/rhi/buffer/map.md @@ -4,9 +4,11 @@ virtual void* Map() = 0; ``` -映射缓冲区内存到 CPU 可访问空间。 +将缓冲区 GPU 内存映射到 CPU 可访问的虚拟地址空间。映射后可直接使用 memcpy 等 CPU 内存操作函数写入数据。 -**返回：** 指向缓冲区数据的指针 +**返回：** 指向缓冲区数据的指针，映射失败返回 `nullptr` + +**线程安全：** ❌ **复杂度：** O(1) diff --git a/docs/api/rhi/buffer/set-buffer-type.md b/docs/api/rhi/buffer/set-buffer-type.md index 2541eb61..ebd56a54 100644 --- a/docs/api/rhi/buffer/set-buffer-type.md +++ b/docs/api/rhi/buffer/set-buffer-type.md @@ -4,13 +4,21 @@ virtual void SetBufferType(BufferType type) = 0; ``` -设置缓冲区类型。 +设置缓冲区的类型。应在缓冲区创建后立即设置，确保后续绑定到渲染管线时使用正确的类型。 **参数：** -- `type` - 新的缓冲区类型 +- `type` - 缓冲区类型（`Vertex`、`Index`、`Constant` 等） + +**线程安全：** ❌ **复杂度：** O(1) +**示例：** + +```cpp +buffer->SetBufferType(BufferType::Vertex); +``` + ## 相关文档 - [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/set-stride.md b/docs/api/rhi/buffer/set-stride.md index fea09316..0175fe08 100644 --- a/docs/api/rhi/buffer/set-stride.md +++ b/docs/api/rhi/buffer/set-stride.md @@ -4,13 +4,21 @@ virtual void SetStride(uint32_t stride) = 0; ``` -设置元素字节大小。 +设置单个元素的字节大小（步长）。 **参数：** -- `stride` - 新的步长值 +- `stride` - 新的步长值（字节） + +**线程安全：** ❌ **复杂度：** O(1) +**示例：** + +```cpp +buffer->SetStride(sizeof(Vertex)); +``` + ## 相关文档 - [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/shutdown.md b/docs/api/rhi/buffer/shutdown.md index 568391e5..0ec29257 100644 --- a/docs/api/rhi/buffer/shutdown.md +++ b/docs/api/rhi/buffer/shutdown.md @@ -4,10 +4,20 @@ virtual void Shutdown() = 0; ``` -释放缓冲区资源。 +关闭并释放缓冲区资源。调用后缓冲区不再可用，所有已绑定的命令列表中的引用将失效。 + +**线程安全：** ❌ **复杂度：** O(1) +**示例：** + +```cpp +buffer->Shutdown(); +// buffer is now invalid +delete buffer; +``` + ## 相关文档 - [RHIBuffer 总览](buffer.md) - 返回类总览 diff --git a/docs/api/rhi/buffer/unmap.md b/docs/api/rhi/buffer/unmap.md index 51b5bf9a..0cbcab49 100644 --- a/docs/api/rhi/buffer/unmap.md +++ b/docs/api/rhi/buffer/unmap.md @@ -4,15 +4,17 @@ virtual void Unmap() = 0; ``` -取消内存映射。 +取消缓冲区内存映射，使 GPU 可以继续访问该内存。在调用 `Map()` 后必须调用此方法。 + +**线程安全：** ❌ **复杂度：** O(1) **示例：** ```cpp -buffer->Map(); -memcpy(mappedData, sourceData, size); +void* data = buffer->Map(); +memcpy(data, sourceData, size); buffer->Unmap(); ``` diff --git a/docs/api/rhi/capabilities/capabilities.md b/docs/api/rhi/capabilities/capabilities.md index 4f67c35b..a8e309c7 100644 --- a/docs/api/rhi/capabilities/capabilities.md +++ b/docs/api/rhi/capabilities/capabilities.md @@ -4,61 +4,65 @@ **类型**: `struct` +**头文件**: `XCEngine/RHI/RHICapabilities.h` + **描述**: GPU 设备能力结构体，描述了当前图形设备支持的各种功能和限制。 -## 公共成员 +## 概述 -### 特性支持 +`RHICapabilities` 是一个纯数据结构的 struct，用于在运行时查询当前 GPU 设备的能力和限制。开发者可以通过 `RHIDevice::GetCapabilities()` 获取设备能力信息，据此决定是否启用特定图形特性（如光线追踪、网格着色器等），或在进行资源创建时确保不超过设备支持的范围。 -| 成员 | 类型 | 描述 | -|------|------|------| -| `bSupportsRayTracing` | `bool` | 支持光线追踪 | -| `bSupportsMeshShaders` | `bool` | 支持 Mesh 着色器 | -| `bSupportsExplicitMultiThreading` | `bool` | 支持显式多线程 | -| `bSupportsGeometryShaders` | `bool` | 支持几何着色器 | -| `bSupportsTessellation` | `bool` | 支持曲面细分 | -| `bSupportsComputeShaders` | `bool` | 支持计算着色器 | -| `bSupportsDepthBoundsTest` | `bool` | 支持深度范围测试 | -| `bSupportsAlphaToCoverage` | `bool` | 支持 Alpha 到覆盖 | -| `bSupportsIndependentBlend` | `bool` | 支持独立混合 | -| `bSupportsLogicOps` | `bool` | 支持逻辑操作 | -| `bSupportsMultiViewport` | `bool` | 支持多视口 | -| `bSupportsConservativeRasterization` | `bool` | 支持保守光栅化 | -| `bSupportsProgrammableSamplePositions` | `bool` | 支持可编程采样位置 | +## 结构体成员 + +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `bSupportsRayTracing` | `bool` | 支持光线追踪 | - | +| `bSupportsMeshShaders` | `bool` | 支持 Mesh 着色器 | - | +| `bSupportsExplicitMultiThreading` | `bool` | 支持显式多线程 | - | +| `bSupportsGeometryShaders` | `bool` | 支持几何着色器 | - | +| `bSupportsTessellation` | `bool` | 支持曲面细分 | - | +| `bSupportsComputeShaders` | `bool` | 支持计算着色器 | - | +| `bSupportsDepthBoundsTest` | `bool` | 支持深度范围测试 | - | +| `bSupportsAlphaToCoverage` | `bool` | 支持 Alpha 到覆盖 | - | +| `bSupportsIndependentBlend` | `bool` | 支持独立混合 | - | +| `bSupportsLogicOps` | `bool` | 支持逻辑操作 | - | +| `bSupportsMultiViewport` | `bool` | 支持多视口 | - | +| `bSupportsConservativeRasterization` | `bool` | 支持保守光栅化 | - | +| `bSupportsProgrammableSamplePositions` | `bool` | 支持可编程采样位置 | - | ### 资源限制 -| 成员 | 类型 | 描述 | -|------|------|------| -| `maxTexture2DSize` | `uint32_t` | 最大 2D 纹理尺寸 | -| `maxTexture3DSize` | `uint32_t` | 最大 3D 纹理尺寸 | -| `maxTextureCubeSize` | `uint32_t` | 最大立方体贴图尺寸 | -| `maxRenderTargets` | `uint32_t` | 最大渲染目标数量 | -| `maxViewports` | `uint32_t` | 最大视口数量 | -| `maxVertexAttribs` | `uint32_t` | 最大顶点属性数量 | -| `maxConstantBufferSize` | `uint32_t` | 最大常量缓冲大小 | -| `maxAnisotropy` | `uint32_t` | 最大各向异性级别 | -| `maxColorAttachments` | `uint32_t` | 最大颜色附件数量 | +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `maxTexture2DSize` | `uint32_t` | 最大 2D 纹理尺寸 | - | +| `maxTexture3DSize` | `uint32_t` | 最大 3D 纹理尺寸 | - | +| `maxTextureCubeSize` | `uint32_t` | 最大立方体贴图尺寸 | - | +| `maxRenderTargets` | `uint32_t` | 最大渲染目标数量 | - | +| `maxViewports` | `uint32_t` | 最大视口数量 | - | +| `maxVertexAttribs` | `uint32_t` | 最大顶点属性数量 | - | +| `maxConstantBufferSize` | `uint32_t` | 最大常量缓冲大小 | - | +| `maxAnisotropy` | `uint32_t` | 最大各向异性级别 | - | +| `maxColorAttachments` | `uint32_t` | 最大颜色附件数量 | - | ### 线宽和点大小 -| 成员 | 类型 | 描述 | -|------|------|------| -| `minSmoothedLineWidth` | `float` | 最小平滑线宽 | -| `maxSmoothedLineWidth` | `float` | 最大平滑线宽 | -| `minPointSize` | `float` | 最小点大小 | -| `maxPointSize` | `float` | 最大点大小 | -| `maxPointSizeAA` | `float` | 抗锯齿最大点大小 | -| `maxLineWidth` | `float` | 最大线宽 | -| `maxLineWidthAA` | `float` | 抗锯齿最大线宽 | +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `minSmoothedLineWidth` | `float` | 最小平滑线宽 | - | +| `maxSmoothedLineWidth` | `float` | 最大平滑线宽 | - | +| `minPointSize` | `float` | 最小点大小 | - | +| `maxPointSize` | `float` | 最大点大小 | - | +| `maxPointSizeAA` | `float` | 抗锯齿最大点大小 | - | +| `maxLineWidth` | `float` | 最大线宽 | - | +| `maxLineWidthAA` | `float` | 抗锯齿最大线宽 | - | ### 版本信息 -| 成员 | 类型 | 描述 | -|------|------|------| -| `majorVersion` | `int` | 主版本号 | -| `minorVersion` | `int` | 次版本号 | -| `shaderModel` | `std::string` | 着色器模型版本 | +| 成员 | 类型 | 描述 | 默认值 | +|------|------|------|--------| +| `majorVersion` | `int` | 主版本号 | - | +| `minorVersion` | `int` | 次版本号 | - | +| `shaderModel` | `std::string` | 着色器模型版本 | - | ## 使用示例 @@ -78,5 +82,5 @@ uint32_t textureSize = std::min(requestedSize, caps.maxTexture2DSize); ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHI 模块](../rhi.md) - RHI 模块总览 - [RHIDevice](../device/device.md) - 设备对象 diff --git a/docs/api/rhi/command-list/clear-depth-stencil.md b/docs/api/rhi/command-list/clear-depth-stencil.md index e9e34928..5fa9055d 100644 --- a/docs/api/rhi/command-list/clear-depth-stencil.md +++ b/docs/api/rhi/command-list/clear-depth-stencil.md @@ -4,12 +4,20 @@ virtual void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil) = 0; ``` -清除深度模板缓冲区。 +清除深度模板视图。可同时清除深度值和模板值。 **参数：** -- `depthStencil` - 深度模板缓冲区指针 -- `depth` - 深度值 -- `stencil` - 模板值 +- `depthStencil` - 深度模板视图指针 +- `depth` - 清除深度值（通常为 1.0） +- `stencil` - 清除模板值（范围 0-255） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -20,3 +28,5 @@ cmdList->ClearDepthStencil(depthStencil, 1.0f, 0); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [Clear](clear.md) - 清除多个渲染目标 +- [SetRenderTargets](set-render-targets.md) - 设置渲染目标 \ No newline at end of file diff --git a/docs/api/rhi/command-list/clear-render-target.md b/docs/api/rhi/command-list/clear-render-target.md index 2534b1d0..979cec6e 100644 --- a/docs/api/rhi/command-list/clear-render-target.md +++ b/docs/api/rhi/command-list/clear-render-target.md @@ -4,11 +4,19 @@ virtual void ClearRenderTarget(void* renderTarget, const float color[4]) = 0; ``` -清除渲染目标。 +清除指定的渲染目标视图。用给定的颜色值填充整个渲染目标。 **参数：** -- `renderTarget` - 渲染目标指针 -- `color` - 清除颜色 [r, g, b, a] +- `renderTarget` - 渲染目标视图指针 +- `color` - 4 元素浮点数数组，表示 RGBA 清除颜色（范围 0.0-1.0） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -20,3 +28,5 @@ cmdList->ClearRenderTarget(renderTarget, color); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [Clear](clear.md) - 清除多个渲染目标 +- [SetRenderTargets](set-render-targets.md) - 设置渲染目标 \ No newline at end of file diff --git a/docs/api/rhi/command-list/clear.md b/docs/api/rhi/command-list/clear.md index f8307fce..229f28f2 100644 --- a/docs/api/rhi/command-list/clear.md +++ b/docs/api/rhi/command-list/clear.md @@ -4,17 +4,31 @@ virtual void Clear(float r, float g, float b, float a, uint32_t buffers) = 0; ``` -清除渲染目标。 +清除多个渲染目标。可同时清除颜色、深度和模板缓冲区。 **参数：** -- `r` - 红色分量 -- `g` - 绿色分量 -- `b` - 蓝色分量 -- `a` - Alpha 分量 -- `buffers` - 要清除的缓冲区标志 +- `r` - 清除颜色红色分量（范围 0.0-1.0） +- `g` - 清除颜色绿色分量（范围 0.0-1.0） +- `b` - 清除颜色蓝色分量（范围 0.0-1.0） +- `a` - 清除颜色 Alpha 分量（范围 0.0-1.0） +- `buffers` - 要清除的缓冲区标志位（ClearFlags 枚举组合） -**复杂度：** O(1) +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(n) + +**示例：** + +```cpp +cmdList->Clear(0.0f, 0.0f, 0.0f, 1.0f, 0x1); // 清除颜色缓冲 +``` ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [ClearRenderTarget](clear-render-target.md) - 清除渲染目标 +- [ClearDepthStencil](clear-depth-stencil.md) - 清除深度模板 \ No newline at end of file diff --git a/docs/api/rhi/command-list/close.md b/docs/api/rhi/command-list/close.md index ea2ee6ea..1ee4390f 100644 --- a/docs/api/rhi/command-list/close.md +++ b/docs/api/rhi/command-list/close.md @@ -4,10 +4,26 @@ virtual void Close() = 0; ``` -关闭命令列表以执行。 +关闭命令列表以执行。调用此方法后，命令列表中的命令无法再被修改，可以提交给图形设备执行。 + +**参数：** 无 + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ **复杂度：** O(1) +**示例：** + +```cpp +commandList->Close(); +``` + ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [Reset](reset.md) - 重置命令列表 +- [Shutdown](shutdown.md) - 关闭命令列表 \ No newline at end of file diff --git a/docs/api/rhi/command-list/command-list.md b/docs/api/rhi/command-list/command-list.md index 8196d893..93de90a9 100644 --- a/docs/api/rhi/command-list/command-list.md +++ b/docs/api/rhi/command-list/command-list.md @@ -4,12 +4,26 @@ **类型**: `class` (abstract) -**描述**: GPU 命令列表抽象接口，用于录制和执行 GPU 命令。 +**头文件**: `XCEngine/RHI/RHICommandList.h` + +**描述**: GPU 命令列表抽象接口，用于录制和执行 GPU 渲染命令 + +## 概述 + +`RHICommandList` 是渲染硬件接口（RHI）层提供的抽象命令列表类，用于录制 GPU 命令并提交执行。该类是纯虚接口，具体实现由各图形 API（D3D12、Vulkan 等）提供。 + +主要功能包括： +- 状态设置（管线、视口、裁剪、渲染目标等） +- 资源绑定（顶点缓冲、索引缓冲等） +- 绘制调用（Draw、DrawIndexed） +- 资源操作（复制、转换状态） +- 计算着色器分发 ## 公共方法 | 方法 | 描述 | |------|------| +| [`Shutdown`](shutdown.md) | 关闭命令列表并释放资源 | | [`Reset`](reset.md) | 重置命令列表 | | [`Close`](close.md) | 关闭命令列表 | | [`TransitionBarrier`](transition-barrier.md) | 资源状态转换 | @@ -21,7 +35,7 @@ | [`SetScissorRects`](set-scissor-rects.md) | 设置多个裁剪矩形 | | [`SetRenderTargets`](set-render-targets.md) | 设置渲染目标 | | [`SetDepthStencilState`](set-depth-stencil-state.md) | 设置深度模板状态 | -| [`SetStencilRef`](set-stencil-ref.md) | 设置模板引用值 | +| [`SetStencilRef`](set-stencil-ref.md) | 设置模板参考值 | | [`SetBlendState`](set-blend-state.md) | 设置混合状态 | | [`SetBlendFactor`](set-blend-factor.md) | 设置混合因子 | | [`SetVertexBuffer`](set-vertex-buffer.md) | 设置顶点缓冲 | @@ -34,7 +48,6 @@ | [`ClearDepthStencil`](clear-depth-stencil.md) | 清除深度模板 | | [`CopyResource`](copy-resource.md) | 复制资源 | | [`Dispatch`](dispatch.md) | 分发计算任务 | -| [`Shutdown`](shutdown.md) | 关闭并释放资源 | ## 使用示例 @@ -51,5 +64,5 @@ commandQueue->ExecuteCommandLists(1, (void**)&commandList); ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 -- [RHICommandQueue](../command-queue/command-queue.md) - 命令队列 +- [RHI 模块总览](../rhi.md) - RHI 模块总览 +- [RHICommandQueue](../command-queue/command-queue.md) - 命令队列 \ No newline at end of file diff --git a/docs/api/rhi/command-list/copy-resource.md b/docs/api/rhi/command-list/copy-resource.md index e1aa6446..96c5eea2 100644 --- a/docs/api/rhi/command-list/copy-resource.md +++ b/docs/api/rhi/command-list/copy-resource.md @@ -4,11 +4,19 @@ virtual void CopyResource(void* dst, void* src) = 0; ``` -复制资源。 +复制整个资源的内容。源资源和目标资源必须类型相同且大小相等。 **参数：** -- `dst` - 目标资源 -- `src` - 源资源 +- `dst` - 目标资源指针 +- `src` - 源资源指针 + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(n)，n 为资源大小 **示例：** @@ -19,3 +27,4 @@ cmdList->CopyResource(dstTexture, srcTexture); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [TransitionBarrier](transition-barrier.md) - 设置资源状态转换 \ No newline at end of file diff --git a/docs/api/rhi/command-list/dispatch.md b/docs/api/rhi/command-list/dispatch.md index c1b24b53..9a0ee696 100644 --- a/docs/api/rhi/command-list/dispatch.md +++ b/docs/api/rhi/command-list/dispatch.md @@ -4,13 +4,21 @@ virtual void Dispatch(uint32_t x, uint32_t y, uint32_t z) = 0; ``` -分发计算着色器。 +分发计算着色器线程组。用于执行计算着色器（Compute Shader），将工作分配到三维线程网格中。 **参数：** - `x` - X 方向线程组数量 - `y` - Y 方向线程组数量 - `z` - Z 方向线程组数量 +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(x * y * z) + **示例：** ```cpp @@ -20,3 +28,5 @@ cmdList->Dispatch(8, 8, 1); // 分发 8x8x1 线程组 ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [SetPipelineState](set-pipeline-state.md) - 设置管线状态 +- [Draw](draw.md) - 绘制 \ No newline at end of file diff --git a/docs/api/rhi/command-list/draw-indexed.md b/docs/api/rhi/command-list/draw-indexed.md index 1d7e5fa0..151ab67e 100644 --- a/docs/api/rhi/command-list/draw-indexed.md +++ b/docs/api/rhi/command-list/draw-indexed.md @@ -4,14 +4,22 @@ virtual void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0) = 0; ``` -绘制索引图元。 +执行索引绘制调用。通过索引缓冲区从顶点缓冲区中选择顶点绘制图元，允许顶点复用。 **参数：** - `indexCount` - 索引数量 -- `instanceCount` - 实例数量（默认1） -- `startIndex` - 起始索引 -- `baseVertex` - 基础顶点索引 -- `startInstance` - 起始实例索引 +- `instanceCount` - 实例数量（默认 1） +- `startIndex` - 起始索引偏移（默认 0） +- `baseVertex` - 基础顶点偏移（默认 0） +- `startInstance` - 起始实例偏移（默认 0） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(indexCount * instanceCount) **示例：** @@ -22,3 +30,5 @@ cmdList->DrawIndexed(36); // 绘制36个索引 ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [Draw](draw.md) - 绘制 +- [SetIndexBuffer](set-index-buffer.md) - 设置索引缓冲 \ No newline at end of file diff --git a/docs/api/rhi/command-list/draw.md b/docs/api/rhi/command-list/draw.md index 70914f1d..a5a07013 100644 --- a/docs/api/rhi/command-list/draw.md +++ b/docs/api/rhi/command-list/draw.md @@ -4,13 +4,21 @@ virtual void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0) = 0; ``` -绘制调用。 +执行非索引绘制调用。从顶点缓冲区按顺序读取顶点数据绘制图元。 **参数：** - `vertexCount` - 顶点数量 -- `instanceCount` - 实例数量（默认1） -- `startVertex` - 起始顶点索引 -- `startInstance` - 起始实例索引 +- `instanceCount` - 实例数量（默认 1） +- `startVertex` - 起始顶点偏移（默认 0） +- `startInstance` - 起始实例偏移（默认 0） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(vertexCount * instanceCount) **示例：** @@ -21,3 +29,5 @@ cmdList->Draw(36); // 绘制36个顶点 ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [DrawIndexed](draw-indexed.md) - 索引绘制 +- [SetVertexBuffer](set-vertex-buffer.md) - 设置顶点缓冲 \ No newline at end of file diff --git a/docs/api/rhi/command-list/methods.md b/docs/api/rhi/command-list/methods.md deleted file mode 100644 index ed6e704c..00000000 --- a/docs/api/rhi/command-list/methods.md +++ /dev/null @@ -1,201 +0,0 @@ -# RHICommandList 方法 - -## Reset - -```cpp -virtual void Reset() = 0; -``` - -重置命令列表，开始新的录制。 - -## Close - -```cpp -virtual void Close() = 0; -``` - -关闭命令列表，结束录制。 - -## TransitionBarrier - -```cpp -virtual void TransitionBarrier(void* resource, ResourceStates stateBefore, ResourceStates stateAfter) = 0; -``` - -资源状态转换屏障。 - -## SetPipelineState - -```cpp -virtual void SetPipelineState(void* pso) = 0; -``` - -设置管线状态对象。 - -## SetPrimitiveTopology - -```cpp -virtual void SetPrimitiveTopology(PrimitiveTopology topology) = 0; -``` - -设置图元拓扑。 - -## SetViewport - -```cpp -virtual void SetViewport(const Viewport& viewport) = 0; -``` - -设置视口。 - -## SetViewports - -```cpp -virtual void SetViewports(uint32_t count, const Viewport* viewports) = 0; -``` - -设置多个视口。 - -## SetScissorRect - -```cpp -virtual void SetScissorRect(const Rect& rect) = 0; -``` - -设置裁剪矩形。 - -## SetScissorRects - -```cpp -virtual void SetScissorRects(uint32_t count, const Rect* rects) = 0; -``` - -设置多个裁剪矩形。 - -## SetRenderTargets - -```cpp -virtual void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil = nullptr) = 0; -``` - -设置渲染目标。 - -## SetDepthStencilState - -```cpp -virtual void SetDepthStencilState(const DepthStencilState& state) = 0; -``` - -设置深度模板状态。 - -## SetStencilRef - -```cpp -virtual void SetStencilRef(uint8_t ref) = 0; -``` - -设置模板参考值。 - -## SetBlendState - -```cpp -virtual void SetBlendState(const BlendState& state) = 0; -``` - -设置混合状态。 - -## SetBlendFactor - -```cpp -virtual void SetBlendFactor(const float factor[4]) = 0; -``` - -设置混合因子。 - -## SetVertexBuffer - -```cpp -virtual void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride) = 0; -``` - -设置顶点缓冲。 - -## SetVertexBuffers - -```cpp -virtual void SetVertexBuffers(uint32_t startSlot, uint32_t count, const uint64_t* buffers, const uint64_t* offsets, const uint32_t* strides) = 0; -``` - -设置多个顶点缓冲。 - -## SetIndexBuffer - -```cpp -virtual void SetIndexBuffer(void* buffer, uint64_t offset, Format format) = 0; -``` - -设置索引缓冲。 - -## Draw - -```cpp -virtual void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0) = 0; -``` - -绘制调用。 - -## DrawIndexed - -```cpp -virtual void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0) = 0; -``` - -索引绘制调用。 - -## Clear - -```cpp -virtual void Clear(float r, float g, float b, float a, uint32_t buffers) = 0; -``` - -清除缓冲。 - -## ClearRenderTarget - -```cpp -virtual void ClearRenderTarget(void* renderTarget, const float color[4]) = 0; -``` - -清除渲染目标。 - -## ClearDepthStencil - -```cpp -virtual void ClearDepthStencil(void* depthStencil, float depth, uint8_t stencil) = 0; -``` - -清除深度模板。 - -## CopyResource - -```cpp -virtual void CopyResource(void* dst, void* src) = 0; -``` - -复制资源。 - -## Dispatch - -```cpp -virtual void Dispatch(uint32_t x, uint32_t y, uint32_t z) = 0; -``` - -分发计算着色器。 - -## Shutdown - -```cpp -virtual void Shutdown() = 0; -``` - -释放命令列表资源。 diff --git a/docs/api/rhi/command-list/reset.md b/docs/api/rhi/command-list/reset.md index ed0ea740..294913d4 100644 --- a/docs/api/rhi/command-list/reset.md +++ b/docs/api/rhi/command-list/reset.md @@ -4,10 +4,26 @@ virtual void Reset() = 0; ``` -重置命令列表以重新录制。 +重置命令列表以重新录制。调用此方法后，可以重新开始向命令列表添加命令。 + +**参数：** 无 + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ **复杂度：** O(1) +**示例：** + +```cpp +commandList->Reset(); +``` + ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [Close](close.md) - 关闭命令列表 +- [Shutdown](shutdown.md) - 关闭命令列表 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-blend-factor.md b/docs/api/rhi/command-list/set-blend-factor.md index a075922e..63ffc266 100644 --- a/docs/api/rhi/command-list/set-blend-factor.md +++ b/docs/api/rhi/command-list/set-blend-factor.md @@ -4,10 +4,18 @@ virtual void SetBlendFactor(const float factor[4]) = 0; ``` -设置混合因子。 +设置混合因子数组。当混合函数使用可编程混合因子时，使用此方法设置 RGBA 四个通道的混合因子。 **参数：** -- `factor` - 混合因子数组 [r, g, b, a] +- `factor` - 4 元素浮点数数组，表示 RGBA 混合因子（范围 0.0-1.0） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -19,3 +27,4 @@ cmdList->SetBlendFactor(factor); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [SetBlendState](set-blend-state.md) - 设置混合状态 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-blend-state.md b/docs/api/rhi/command-list/set-blend-state.md index 2ec1ae30..fd71b413 100644 --- a/docs/api/rhi/command-list/set-blend-state.md +++ b/docs/api/rhi/command-list/set-blend-state.md @@ -4,10 +4,18 @@ virtual void SetBlendState(const BlendState& state) = 0; ``` -设置混合状态。 +设置颜色混合状态。控制源颜色和目标颜色如何混合，影响最终输出像素的颜色值。 **参数：** -- `state` - 混合状态结构体 +- `state` - 混合状态结构体（包含 alphaToCoverageEnable、independentBlendEnable、renderTargets[] 等） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -15,9 +23,15 @@ virtual void SetBlendState(const BlendState& state) = 0; BlendState blendState; blendState.alphaToCoverageEnable = false; blendState.independentBlendEnable = false; +blendState.renderTargets[0].blendEnable = true; +blendState.renderTargets[0].srcBlend = BlendFactor::SrcAlpha; +blendState.renderTargets[0].dstBlend = BlendFactor::InvSrcAlpha; +blendState.renderTargets[0].blendOp = BlendOp::Add; cmdList->SetBlendState(blendState); ``` ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [SetBlendFactor](set-blend-factor.md) - 设置混合因子 +- [SetPipelineState](set-pipeline-state.md) - 设置管线状态 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-depth-stencil-state.md b/docs/api/rhi/command-list/set-depth-stencil-state.md index 1bf38d7b..dd228f83 100644 --- a/docs/api/rhi/command-list/set-depth-stencil-state.md +++ b/docs/api/rhi/command-list/set-depth-stencil-state.md @@ -4,10 +4,18 @@ virtual void SetDepthStencilState(const DepthStencilState& state) = 0; ``` -设置深度模板状态。 +设置深度测试和模板测试的状态配置。控制像素是否根据深度值和模板值被丢弃。 **参数：** -- `state` - 深度模板状态结构体 +- `state` - 深度模板状态结构体（包含 depthEnable、depthWriteMask、depthFunc、stencilEnable 等） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -16,9 +24,12 @@ DepthStencilState dsState; dsState.depthEnable = true; dsState.depthWriteMask = true; dsState.depthFunc = ComparisonFunc::Less; +dsState.stencilEnable = false; cmdList->SetDepthStencilState(dsState); ``` ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [SetStencilRef](set-stencil-ref.md) - 设置模板参考值 +- [SetPipelineState](set-pipeline-state.md) - 设置管线状态 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-index-buffer.md b/docs/api/rhi/command-list/set-index-buffer.md index 3698cc9a..746118ed 100644 --- a/docs/api/rhi/command-list/set-index-buffer.md +++ b/docs/api/rhi/command-list/set-index-buffer.md @@ -4,12 +4,20 @@ virtual void SetIndexBuffer(void* buffer, uint64_t offset, Format format) = 0; ``` -设置索引缓冲区。 +绑定索引缓冲区。索引缓冲区存储顶点索引，用于 `DrawIndexed` 调用，从顶点缓冲区中选择顶点组成图元。 **参数：** - `buffer` - 索引缓冲区指针 -- `offset` - 数据偏移量 -- `format` - 索引格式（R16_UINT 或 R32_UINT） +- `offset` - 缓冲区内的起始偏移量（字节） +- `format` - 索引格式（Format::R16_UINT 或 Format::R32_UINT） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -20,3 +28,5 @@ cmdList->SetIndexBuffer(indexBuffer, 0, Format::R16_UINT); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [DrawIndexed](draw-indexed.md) - 索引绘制 +- [SetVertexBuffer](set-vertex-buffer.md) - 设置顶点缓冲 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-pipeline-state.md b/docs/api/rhi/command-list/set-pipeline-state.md index 98ac03e1..67486e91 100644 --- a/docs/api/rhi/command-list/set-pipeline-state.md +++ b/docs/api/rhi/command-list/set-pipeline-state.md @@ -4,11 +4,19 @@ virtual void SetPipelineState(void* pso) = 0; ``` -设置渲染管线状态对象。 +设置渲染管线状态对象。管线状态包含着色器、混合模式、深度模板设置等所有影响渲染的固定功能配置。 **参数：** - `pso` - 管线状态对象指针 +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) + **示例：** ```cpp @@ -18,3 +26,5 @@ cmdList->SetPipelineState(pipelineState); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [SetPrimitiveTopology](set-primitive-topology.md) - 设置图元拓扑 +- [SetDepthStencilState](set-depth-stencil-state.md) - 设置深度模板状态 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-primitive-topology.md b/docs/api/rhi/command-list/set-primitive-topology.md index 4efd502b..7d8c5749 100644 --- a/docs/api/rhi/command-list/set-primitive-topology.md +++ b/docs/api/rhi/command-list/set-primitive-topology.md @@ -4,10 +4,18 @@ virtual void SetPrimitiveTopology(PrimitiveTopology topology) = 0; ``` -设置图元拓扑类型。 +设置图元拓扑类型。拓扑类型决定了顶点如何被解释为几何图元，如点列表、线段列表、三角形列表等。 **参数：** -- `topology` - 图元拓扑类型（点、线、三角形等） +- `topology` - 图元拓扑类型（枚举值：PointList、LineList、TriangleList 等） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -18,3 +26,5 @@ cmdList->SetPrimitiveTopology(PrimitiveTopology::TriangleList); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [Draw](draw.md) - 绘制 +- [DrawIndexed](draw-indexed.md) - 索引绘制 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-render-targets.md b/docs/api/rhi/command-list/set-render-targets.md index 3e826cd6..826db5b7 100644 --- a/docs/api/rhi/command-list/set-render-targets.md +++ b/docs/api/rhi/command-list/set-render-targets.md @@ -4,12 +4,20 @@ virtual void SetRenderTargets(uint32_t count, void** renderTargets, void* depthStencil = nullptr) = 0; ``` -设置渲染目标和深度模板缓冲区。 +设置渲染目标和深度模板缓冲区。指定着色器将输出到的颜色缓冲区和深度模板缓冲区。 **参数：** -- `count` - 渲染目标数量 -- `renderTargets` - 渲染目标数组 -- `depthStencil` - 深度模板缓冲区（可选） +- `count` - 渲染目标数量（最多 8 个） +- `renderTargets` - 渲染目标数组指针 +- `depthStencil` - 深度模板缓冲区指针（可选，默认为 nullptr） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -21,3 +29,5 @@ cmdList->SetRenderTargets(1, targets, depthStencil); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [ClearRenderTarget](clear-render-target.md) - 清除渲染目标 +- [ClearDepthStencil](clear-depth-stencil.md) - 清除深度模板 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-scissor-rect.md b/docs/api/rhi/command-list/set-scissor-rect.md index 5cc7a751..973b06f0 100644 --- a/docs/api/rhi/command-list/set-scissor-rect.md +++ b/docs/api/rhi/command-list/set-scissor-rect.md @@ -4,10 +4,18 @@ virtual void SetScissorRect(const Rect& rect) = 0; ``` -设置裁剪矩形。 +设置裁剪矩形。超出该矩形区域的像素将被丢弃。此操作用于实现遮罩、屏幕空间裁剪等效果。 **参数：** -- `rect` - 裁剪矩形结构体 +- `rect` - 裁剪矩形结构体（包含 left、top、right、bottom，单位为像素） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -23,3 +31,5 @@ cmdList->SetScissorRect(rect); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [SetScissorRects](set-scissor-rects.md) - 设置多个裁剪矩形 +- [SetViewport](set-viewport.md) - 设置视口 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-scissor-rects.md b/docs/api/rhi/command-list/set-scissor-rects.md index fa857b9c..3d2dad33 100644 --- a/docs/api/rhi/command-list/set-scissor-rects.md +++ b/docs/api/rhi/command-list/set-scissor-rects.md @@ -4,12 +4,20 @@ virtual void SetScissorRects(uint32_t count, const Rect* rects) = 0; ``` -设置多个裁剪矩形。 +批量设置多个裁剪矩形。与 `SetViewports` 类似，用于多重渲染场景，每个视口对应一个裁剪矩形。 **参数：** -- `count` - 裁剪矩形数量 +- `count` - 裁剪矩形数量（最大 16） - `rects` - 裁剪矩形数组指针 +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(n)，n 为矩形数量 + **示例：** ```cpp @@ -22,3 +30,5 @@ cmdList->SetScissorRects(2, rects); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [SetScissorRect](set-scissor-rect.md) - 设置单个裁剪矩形 +- [SetViewports](set-viewports.md) - 设置多个视口 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-stencil-ref.md b/docs/api/rhi/command-list/set-stencil-ref.md index eb1f4d05..d09d78d4 100644 --- a/docs/api/rhi/command-list/set-stencil-ref.md +++ b/docs/api/rhi/command-list/set-stencil-ref.md @@ -4,10 +4,18 @@ virtual void SetStencilRef(uint8_t ref) = 0; ``` -设置模板参考值。 +设置模板测试的参考值。模板测试将每个像素的模板值与此参考值进行比较，决定像素是否被写入。 **参数：** -- `ref` - 模板参考值 +- `ref` - 模板参考值（范围 0-255） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -18,3 +26,4 @@ cmdList->SetStencilRef(0xFF); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [SetDepthStencilState](set-depth-stencil-state.md) - 设置深度模板状态 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-vertex-buffer.md b/docs/api/rhi/command-list/set-vertex-buffer.md index 0b13f64a..84273a21 100644 --- a/docs/api/rhi/command-list/set-vertex-buffer.md +++ b/docs/api/rhi/command-list/set-vertex-buffer.md @@ -4,13 +4,21 @@ virtual void SetVertexBuffer(uint32_t slot, void* buffer, uint64_t offset, uint32_t stride) = 0; ``` -设置顶点缓冲区。 +绑定单个顶点缓冲区到指定的槽位。顶点缓冲区包含绘制所需的顶点数据。 **参数：** -- `slot` - 顶点缓冲区槽位 +- `slot` - 顶点缓冲区槽位索引（范围 0-15） - `buffer` - 顶点缓冲区指针 -- `offset` - 数据偏移量 -- `stride` - 顶点步长 +- `offset` - 缓冲区内的起始偏移量（字节） +- `stride` - 每个顶点的字节大小 + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -21,3 +29,5 @@ cmdList->SetVertexBuffer(0, vertexBuffer, 0, sizeof(Vertex)); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [SetVertexBuffers](set-vertex-buffers.md) - 设置多个顶点缓冲 +- [SetIndexBuffer](set-index-buffer.md) - 设置索引缓冲 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-vertex-buffers.md b/docs/api/rhi/command-list/set-vertex-buffers.md index 23bfd83b..ec8a7d14 100644 --- a/docs/api/rhi/command-list/set-vertex-buffers.md +++ b/docs/api/rhi/command-list/set-vertex-buffers.md @@ -4,14 +4,22 @@ virtual void SetVertexBuffers(uint32_t startSlot, uint32_t count, const uint64_t* buffers, const uint64_t* offsets, const uint32_t* strides) = 0; ``` -设置多个顶点缓冲区。 +批量绑定多个顶点缓冲区到连续的槽位。用于需要多个顶点流的高级渲染场景。 **参数：** -- `startSlot` - 起始槽位 -- `count` - 缓冲区数量 -- `buffers` - 缓冲区指针数组 -- `offsets` - 偏移量数组 -- `strides` - 步长数组 +- `startSlot` - 起始槽位索引（范围 0-15） +- `count` - 顶点缓冲区数量 +- `buffers` - 顶点缓冲区指针数组 +- `offsets` - 偏移量数组（字节） +- `strides` - 步长数组（每个顶点的字节大小） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(n)，n 为缓冲区数量 **示例：** @@ -25,3 +33,4 @@ cmdList->SetVertexBuffers(0, 2, buffers, offsets, strides); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [SetVertexBuffer](set-vertex-buffer.md) - 设置单个顶点缓冲 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-viewport.md b/docs/api/rhi/command-list/set-viewport.md index 53cff939..73c8e2bf 100644 --- a/docs/api/rhi/command-list/set-viewport.md +++ b/docs/api/rhi/command-list/set-viewport.md @@ -4,10 +4,18 @@ virtual void SetViewport(const Viewport& viewport) = 0; ``` -设置视口。 +设置渲染区域视口。视口定义了渲染输出到目标区域的映射变换。 **参数：** -- `viewport` - 视口结构体 +- `viewport` - 视口结构体（包含 topLeftX、topLeftY、width、height、minDepth、maxDepth） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -25,3 +33,5 @@ cmdList->SetViewport(vp); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [SetViewports](set-viewports.md) - 设置多个视口 +- [SetScissorRect](set-scissor-rect.md) - 设置裁剪矩形 \ No newline at end of file diff --git a/docs/api/rhi/command-list/set-viewports.md b/docs/api/rhi/command-list/set-viewports.md index 13640fb1..c9547858 100644 --- a/docs/api/rhi/command-list/set-viewports.md +++ b/docs/api/rhi/command-list/set-viewports.md @@ -4,12 +4,20 @@ virtual void SetViewports(uint32_t count, const Viewport* viewports) = 0; ``` -设置多个视口。 +批量设置多个渲染视口。用于需要多重渲染（Multi-Rendering）的场景，如立体渲染或分屏渲染。 **参数：** -- `count` - 视口数量 +- `count` - 视口数量（最大 16） - `viewports` - 视口数组指针 +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(n)，n 为视口数量 + **示例：** ```cpp @@ -22,3 +30,5 @@ cmdList->SetViewports(2, viewports); ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [SetViewport](set-viewport.md) - 设置单个视口 +- [SetScissorRects](set-scissor-rects.md) - 设置多个裁剪矩形 \ No newline at end of file diff --git a/docs/api/rhi/command-list/shutdown.md b/docs/api/rhi/command-list/shutdown.md index 477a6fc9..67f9cc02 100644 --- a/docs/api/rhi/command-list/shutdown.md +++ b/docs/api/rhi/command-list/shutdown.md @@ -4,10 +4,26 @@ virtual void Shutdown() = 0; ``` -关闭命令列表，释放所有相关资源。 +关闭命令列表，释放所有相关资源。此方法将命令列表置于不可用状态。 -**复杂度：** O(n) - 取决于管理的命令数量 +**参数：** 无 + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +commandList->Shutdown(); +``` ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [Reset](reset.md) - 重置命令列表 +- [Close](close.md) - 关闭命令列表 \ No newline at end of file diff --git a/docs/api/rhi/command-list/transition-barrier.md b/docs/api/rhi/command-list/transition-barrier.md index 2c0a7efd..a4652723 100644 --- a/docs/api/rhi/command-list/transition-barrier.md +++ b/docs/api/rhi/command-list/transition-barrier.md @@ -4,12 +4,20 @@ virtual void TransitionBarrier(void* resource, ResourceStates stateBefore, ResourceStates stateAfter) = 0; ``` -设置资源状态转换屏障，确保 GPU 资源在状态转换前完成所有操作。 +设置资源状态转换屏障，确保 GPU 资源在状态转换前完成所有操作。资源在 GPU 不同的使用方式之间切换时需要通过此方法进行状态转换。 **参数：** - `resource` - 目标资源指针 -- `stateBefore` - 转换前的资源状态 -- `stateAfter` - 转换后的资源状态 +- `stateBefore` - 转换前的资源状态（枚举值） +- `stateAfter` - 转换后的资源状态（枚举值） + +**返回：** `void` + +**异常：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** @@ -21,3 +29,5 @@ cmdList->TransitionBarrier(texture, ResourceStates::RenderTarget, ResourceStates ## 相关文档 - [RHICommandList 总览](command-list.md) - 返回类总览 +- [CopyResource](copy-resource.md) - 复制资源 +- [SetRenderTargets](set-render-targets.md) - 设置渲染目标 \ No newline at end of file diff --git a/docs/api/rhi/command-queue/command-queue.md b/docs/api/rhi/command-queue/command-queue.md index bb29210b..44a7c1cf 100644 --- a/docs/api/rhi/command-queue/command-queue.md +++ b/docs/api/rhi/command-queue/command-queue.md @@ -2,49 +2,73 @@ **命名空间**: `XCEngine::RHI` -**类型**: `class` (abstract) +**类型**: `class` (抽象基类) + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` **描述**: GPU 命令队列抽象接口，负责提交和执行命令列表，以及 GPU/CPU 同步。 +## 概述 + +`RHICommandQueue` 是 RHI（Render Hardware Interface）系统中的核心抽象接口之一，封装了底层图形 API（D3D12/Vulkan/Metal 等）的命令队列功能。 + +主要职责： +- **命令提交**：将准备好的命令列表提交到 GPU 执行 +- **GPU/CPU 同步**：通过栅栏（Fence）机制协调 CPU 和 GPU 的执行顺序 +- **队列类型管理**：区分直接队列、计算队列和复制队列 + +使用场景： +- 渲染循环中提交绘制命令 +- 资源在 GPU 和 CPU 之间传输时的同步 +- 多线程渲染时的命令生成和提交 + ## 公共方法 | 方法 | 描述 | |------|------| | [`Shutdown`](shutdown.md) | 关闭并释放资源 | | [`ExecuteCommandLists`](execute-command-lists.md) | 执行命令列表 | -| [`Signal`](signal.md) | 信号栅栏 | -| [`Wait`](../../threading/task-group/wait.md) | 等待栅栏 | -| [`GetCompletedValue`](get-completed-value.md) | 获取完成值 | -| [`WaitForIdle`](wait-for-idle.md) | 等待空闲 | +| [`Signal`](signal.md) | 向栅栏发送信号 | +| [`Wait`](wait.md) | 等待栅栏达到指定值 | +| [`GetCompletedValue`](get-completed-value.md) | 获取栅栏已完成的值 | +| [`WaitForIdle`](wait-for-idle.md) | 等待队列所有操作完成 | | [`GetType`](get-type.md) | 获取队列类型 | | [`GetTimestampFrequency`](get-timestamp-frequency.md) | 获取时间戳频率 | | [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | -## 命令队列类型 (CommandQueueType) - -| 枚举值 | 描述 | -|--------|------| -| `Direct` | 直接队列，用于图形和计算命令 | -| `Compute` | 计算队列，专门用于计算着色器 | -| `Copy` | 复制队列，专门用于资源复制 | - ## 使用示例 ```cpp -CommandQueueDesc queueDesc; -queueDesc.queueType = (uint32_t)CommandQueueType::Direct; -RHICommandQueue* commandQueue = device->CreateCommandQueue(queueDesc); +#include "RHICommandQueue.h" +#include "RHIDevice.h" +#include "RHIFence.h" +#include "RHICommandList.h" -FenceDesc fenceDesc; -RHIFence* fence = device->CreateFence(fenceDesc); +void RenderLoop(RHIDevice* device, RHICommandQueue* cmdQueue) { + CommandQueueDesc queueDesc; + queueDesc.queueType = (uint32_t)CommandQueueType::Direct; + RHICommandQueue* commandQueue = device->CreateCommandQueue(queueDesc); -commandQueue->ExecuteCommandLists(1, (void**)&commandList); -commandQueue->Signal(fence, 1); -fence->Wait(1); + FenceDesc fenceDesc; + RHIFence* fence = device->CreateFence(fenceDesc); + + RHICommandList* commandList = device->CreateCommandList(); + commandList->Begin(); + commandList->DrawInstanced(vertices, vertexCount, 0); + commandList->End(); + + void* lists[1] = { commandList }; + commandQueue->ExecuteCommandLists(1, lists); + commandQueue->Signal(fence, 1); + fence->Wait(1); + + commandQueue->WaitForIdle(); + commandQueue->Shutdown(); +} ``` ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHI 模块](../rhi.md) - RHI 模块总览 - [RHICommandList](../command-list/command-list.md) - 命令列表 - [RHIFence](../fence/fence.md) - 同步栅栏 diff --git a/docs/api/rhi/command-queue/execute-command-lists.md b/docs/api/rhi/command-queue/execute-command-lists.md index 631b5a29..ded82a2a 100644 --- a/docs/api/rhi/command-queue/execute-command-lists.md +++ b/docs/api/rhi/command-queue/execute-command-lists.md @@ -4,19 +4,36 @@ virtual void ExecuteCommandLists(uint32_t count, void** lists) = 0; ``` -执行命令列表。 +将一个或多个命令列表提交到 GPU 执行。命令列表会在 GPU 上异步执行，具体执行时机取决于底层图形 API 的调度策略。 **参数：** -- `count` - 命令列表数量 -- `lists` - 命令列表指针数组 +- `count` - 命令列表数量，指定 `lists` 数组中的有效元素个数 +- `lists` - 命令列表指针数组，每个元素必须是一个已完成的 `RHICommandList` 对象 + +**返回：** 无 + +**线程安全：** ❌ 非线程安全，应在渲染线程中调用 + +**复杂度：** O(n) - n 为命令列表中的命令数量 **示例：** ```cpp -void* lists[1] = {cmdList}; -cmdQueue->ExecuteCommandLists(1, lists); +#include "RHICommandQueue.h" +#include "RHICommandList.h" + +void SubmitDrawCommands(RHICommandQueue* cmdQueue, RHICommandList* cmdList) { + RHICommandList* lists[1] = { cmdList }; + cmdList->Begin(); + cmdList->SetPipelineState(pipelineState); + cmdList->SetVertexBuffer(vertexBuffer); + cmdList->DrawInstanced(vertices, vertexCount, 0); + cmdList->End(); + cmdQueue->ExecuteCommandLists(1, (void**)lists); +} ``` ## 相关文档 - [RHICommandQueue 总览](command-queue.md) - 返回类总览 +- [RHICommandList](../command-list/command-list.md) - 命令列表 diff --git a/docs/api/rhi/command-queue/get-completed-value.md b/docs/api/rhi/command-queue/get-completed-value.md index bdf98aaf..29680e13 100644 --- a/docs/api/rhi/command-queue/get-completed-value.md +++ b/docs/api/rhi/command-queue/get-completed-value.md @@ -4,16 +4,31 @@ virtual uint64_t GetCompletedValue() = 0; ``` -获取栅栏已完成值。 +查询栅栏的当前完成值。返回值表示栅栏已被 GPU 完成的最新信号值。如果返回的值小于等待的值，则表示 GPU 尚未完成到该点的所有操作。 -**返回：** 已完成的信号值 +**参数：** 无 + +**返回：** 栅栏已完成的最大信号值（uint64_t） + +**线程安全：** ✅ 线程安全，可以从任意线程调用 + +**复杂度：** O(1) **示例：** ```cpp -uint64_t value = cmdQueue->GetCompletedValue(); +#include "RHICommandQueue.h" +#include "RHIFence.h" + +void CheckFenceStatus(RHICommandQueue* cmdQueue, RHIFence* fence) { + uint64_t completed = cmdQueue->GetCompletedValue(); + if (completed >= fence->GetCurrentValue()) { + } +} ``` ## 相关文档 - [RHICommandQueue 总览](command-queue.md) - 返回类总览 +- [Signal](signal.md) - 信号栅栏 +- [Wait](wait.md) - 等待栅栏 diff --git a/docs/api/rhi/command-queue/get-native-handle.md b/docs/api/rhi/command-queue/get-native-handle.md index 35e15a57..d599685c 100644 --- a/docs/api/rhi/command-queue/get-native-handle.md +++ b/docs/api/rhi/command-queue/get-native-handle.md @@ -4,12 +4,27 @@ virtual void* GetNativeHandle() = 0; ``` -获取原生 API 句柄。 +获取底层图形 API 的原生命令队列句柄。返回类型为 `void*`，具体类型取决于使用的图形 API（D3D12 ID3D12CommandQueue*、Vulkan VkQueue 等）。 -**返回：** 原生命令队列句柄 +**参数：** 无 + +**返回：** 原生命令队列句柄（void*），可用于平台特定的互操作操作 + +**线程安全：** ✅ 线程安全，可以从任意线程调用 **复杂度：** O(1) +**示例：** + +```cpp +#include "RHICommandQueue.h" + +void* GetNativeQueue(RHICommandQueue* cmdQueue) { + void* handle = cmdQueue->GetNativeHandle(); + return handle; +} +``` + ## 相关文档 - [RHICommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/command-queue/get-timestamp-frequency.md b/docs/api/rhi/command-queue/get-timestamp-frequency.md index 4622fbc3..b613d064 100644 --- a/docs/api/rhi/command-queue/get-timestamp-frequency.md +++ b/docs/api/rhi/command-queue/get-timestamp-frequency.md @@ -4,14 +4,25 @@ virtual uint64_t GetTimestampFrequency() const = 0; ``` -获取时间戳频率。 +获取命令队列的时间戳频率，即每秒计时计数次数。该频率用于解析时间戳查询结果，计算 GPU 操作的耗时。 -**返回：** 时间戳频率（每秒计数） +**参数：** 无 + +**返回：** 时间戳频率（每秒计数次数，uint64_t） + +**线程安全：** ✅ 线程安全，可以从任意线程调用 + +**复杂度：** O(1) **示例：** ```cpp -uint64_t freq = cmdQueue->GetTimestampFrequency(); +#include "RHICommandQueue.h" + +void CalculateGPUTime(RHICommandQueue* cmdQueue, uint64_t start, uint64_t end) { + uint64_t frequency = cmdQueue->GetTimestampFrequency(); + double elapsedSeconds = static_cast(end - start) / static_cast(frequency); +} ``` ## 相关文档 diff --git a/docs/api/rhi/command-queue/get-type.md b/docs/api/rhi/command-queue/get-type.md index 76e5a5d9..245b21e2 100644 --- a/docs/api/rhi/command-queue/get-type.md +++ b/docs/api/rhi/command-queue/get-type.md @@ -4,12 +4,36 @@ virtual CommandQueueType GetType() const = 0; ``` -获取命令队列类型。 +获取命令队列的类型。命令队列类型决定了它能执行的操作类型。 -**返回：** 命令队列类型枚举值 +**参数：** 无 + +**返回：** `CommandQueueType` 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Direct` | 直接队列，用于图形和计算命令 | +| `Compute` | 计算队列，专门用于计算着色器 | +| `Copy` | 复制队列，专门用于资源复制 | + +**线程安全：** ✅ 线程安全，可以从任意线程调用 **复杂度：** O(1) +**示例：** + +```cpp +#include "RHICommandQueue.h" + +void CheckQueueType(RHICommandQueue* cmdQueue) { + CommandQueueType type = cmdQueue->GetType(); + if (type == CommandQueueType::Direct) { + } else if (type == CommandQueueType::Compute) { + } else if (type == CommandQueueType::Copy) { + } +} +``` + ## 相关文档 - [RHICommandQueue 总览](command-queue.md) - 返回类总览 diff --git a/docs/api/rhi/command-queue/methods.md b/docs/api/rhi/command-queue/methods.md deleted file mode 100644 index b44ea12c..00000000 --- a/docs/api/rhi/command-queue/methods.md +++ /dev/null @@ -1,73 +0,0 @@ -# RHICommandQueue 方法 - -## Shutdown - -```cpp -virtual void Shutdown() = 0; -``` - -关闭命令队列。 - -## ExecuteCommandLists - -```cpp -virtual void ExecuteCommandLists(uint32_t count, void** lists) = 0; -``` - -执行命令列表。 - -## Signal - -```cpp -virtual void Signal(RHIFence* fence, uint64_t value) = 0; -``` - -信号通知栅栏。 - -## Wait - -```cpp -virtual void Wait(RHIFence* fence, uint64_t value) = 0; -``` - -等待栅栏。 - -## GetCompletedValue - -```cpp -virtual uint64_t GetCompletedValue() = 0; -``` - -获取已完成的值。 - -## WaitForIdle - -```cpp -virtual void WaitForIdle() = 0; -``` - -等待队列空闲。 - -## GetType - -```cpp -virtual CommandQueueType GetType() const = 0; -``` - -获取队列类型。 - -## GetTimestampFrequency - -```cpp -virtual uint64_t GetTimestampFrequency() const = 0; -``` - -获取时间戳频率。 - -## GetNativeHandle - -```cpp -virtual void* GetNativeHandle() = 0; -``` - -获取原生 API 句柄。 diff --git a/docs/api/rhi/command-queue/shutdown.md b/docs/api/rhi/command-queue/shutdown.md index 580b1def..efea4521 100644 --- a/docs/api/rhi/command-queue/shutdown.md +++ b/docs/api/rhi/command-queue/shutdown.md @@ -4,9 +4,27 @@ virtual void Shutdown() = 0; ``` -关闭命令队列，释放所有相关资源。 +关闭命令队列，释放所有相关资源。调用此方法后，命令队列将不再可用，必须重新创建才能继续使用。 -**复杂度：** O(n) - 取决于管理的命令列表数量 +**参数：** 无 + +**返回：** 无 + +**线程安全：** ❌ 非线程安全，应在确保没有其他线程访问该队列时调用 + +**复杂度：** O(n) - 取决于管理的命令列表数量和待处理的 GPU 操作 + +**示例：** + +```cpp +#include "RHICommandQueue.h" +#include "RHIDevice.h" + +void CleanupQueue(RHICommandQueue* cmdQueue, RHIDevice* device) { + cmdQueue->WaitForIdle(); + cmdQueue->Shutdown(); +} +``` ## 相关文档 diff --git a/docs/api/rhi/command-queue/signal.md b/docs/api/rhi/command-queue/signal.md index c9bcd539..eeab53b5 100644 --- a/docs/api/rhi/command-queue/signal.md +++ b/docs/api/rhi/command-queue/signal.md @@ -4,18 +4,33 @@ virtual void Signal(RHIFence* fence, uint64_t value) = 0; ``` -向栅栏发送信号。 +向指定的栅栏发送信号，将栅栏的当前值设置为 `value`。当 GPU 执行到此信号操作时，栅栏值会被更新。该方法用于 GPU 到 CPU 同步。 **参数：** -- `fence` - 目标栅栏 -- `value` - 信号值 +- `fence` - 目标栅栏对象，不能为 `nullptr` +- `value` - 信号值，一个 64 位无符号整数 + +**返回：** 无 + +**线程安全：** ❌ 非线程安全，应在渲染线程中调用 + +**复杂度：** O(1) **示例：** ```cpp -cmdQueue->Signal(fence, 1); +#include "RHICommandQueue.h" +#include "RHIFence.h" + +void GPUToCPUSync(RHICommandQueue* cmdQueue, RHIFence* fence) { + cmdQueue->ExecuteCommandLists(1, (void**)&cmdList); + cmdQueue->Signal(fence, 1); + fence->Wait(1); +} ``` ## 相关文档 - [RHICommandQueue 总览](command-queue.md) - 返回类总览 +- [Wait](wait.md) - 等待栅栏 +- [RHIFence](../fence/fence.md) - 同步栅栏 diff --git a/docs/api/rhi/command-queue/wait-for-idle.md b/docs/api/rhi/command-queue/wait-for-idle.md index 80a50fc3..6b98de6d 100644 --- a/docs/api/rhi/command-queue/wait-for-idle.md +++ b/docs/api/rhi/command-queue/wait-for-idle.md @@ -4,14 +4,28 @@ virtual void WaitForIdle() = 0; ``` -等待命令队列完成所有操作。 +等待命令队列完成所有已提交的操作。这是确保 GPU 执行完所有待处理命令的最简单方法，适用于需要完全同步的场景（如资源销毁前）。 + +**参数：** 无 + +**返回：** 无 + +**线程安全：** ❌ 非线程安全，应在渲染线程中调用 + +**复杂度：** O(n) - 取决于待处理命令的数量 **示例：** ```cpp -cmdQueue->WaitForIdle(); +#include "RHICommandQueue.h" + +void EnsureGPUIdle(RHICommandQueue* cmdQueue) { + cmdQueue->ExecuteCommandLists(1, (void**)&cmdList); + cmdQueue->WaitForIdle(); +} ``` ## 相关文档 - [RHICommandQueue 总览](command-queue.md) - 返回类总览 +- [Wait](wait.md) - 等待栅栏 diff --git a/docs/api/rhi/command-queue/wait.md b/docs/api/rhi/command-queue/wait.md new file mode 100644 index 00000000..ecb84044 --- /dev/null +++ b/docs/api/rhi/command-queue/wait.md @@ -0,0 +1,36 @@ +# RHICommandQueue::Wait + +```cpp +virtual void Wait(RHIFence* fence, uint64_t value) = 0; +``` + +等待指定栅栏达到或超过 `value` 值。在栅栏值未达到指定值之前，命令队列的所有后续操作都不会开始执行。该方法用于 CPU 到 GPU 同步。 + +**参数：** +- `fence` - 目标栅栏对象，不能为 `nullptr` +- `value` - 等待的信号值，一个 64 位无符号整数 + +**返回：** 无 + +**线程安全：** ❌ 非线程安全，应在渲染线程中调用 + +**复杂度：** O(1) - 实际操作取决于底层同步机制 + +**示例：** + +```cpp +#include "RHICommandQueue.h" +#include "RHIFence.h" + +void CPUTO GPUSync(RHICommandQueue* cmdQueue, RHIFence* fence) { + cmdQueue->Signal(fence, 1); + cmdQueue->Wait(fence, 1); +} +``` + +## 相关文档 + +- [RHICommandQueue 总览](command-queue.md) - 返回类总览 +- [Signal](signal.md) - 信号栅栏 +- [GetCompletedValue](get-completed-value.md) - 获取完成值 +- [RHIFence](../fence/fence.md) - 同步栅栏 diff --git a/docs/api/rhi/d3d12/buffer/buffer.md b/docs/api/rhi/d3d12/buffer/buffer.md index 90f3506a..31d4bfae 100644 --- a/docs/api/rhi/d3d12/buffer/buffer.md +++ b/docs/api/rhi/d3d12/buffer/buffer.md @@ -2,36 +2,79 @@ **命名空间**: `XCEngine::RHI` +**类型**: `class` (继承自 `RHIBuffer`) + **描述**: DirectX 12 缓冲区的 D3D12 实现，继承自 `RHIBuffer`。 +## 概述 + +`D3D12Buffer` 是 RHI 缓冲区接口的 DirectX 12 后端实现。该类封装了 `ID3D12Resource` 对象，提供缓冲区的创建、初始化、数据更新和状态管理功能。支持顶点缓冲区、索引缓冲区、常量缓冲区等多种缓冲区类型。 + ## 公共方法 +### D3D12 特有方法 + | 方法 | 描述 | |------|------| | [`Initialize`](initialize.md) | 初始化缓冲区 | | [`InitializeFromExisting`](initialize-from-existing.md) | 从现有资源初始化 | | [`InitializeWithData`](initialize-with-data.md) | 初始化并写入数据 | -| [`Shutdown`](shutdown.md) | 关闭缓冲区 | | [`UpdateData`](update-data.md) | 更新数据 | -| [`Map`](map.md) | 映射缓冲区 | -| [`Unmap`](unmap.md) | 取消映射 | -| [`SetData`](set-data.md) | 设置数据 | | [`GetResource`](get-resource.md) | 获取 D3D12 资源 | | [`GetDesc`](get-desc.md) | 获取描述符 | | [`GetGPUVirtualAddress`](get-gpu-virtual-address.md) | 获取 GPU 虚拟地址 | | [`GetGPUAddress`](get-gpu-address.md) | 获取 GPU 地址 | -| [`GetSize`](get-size.md) | 获取缓冲区大小 | -| [`GetState`](get-state.md) | 获取资源状态 | + +### 继承自 RHIBuffer 的方法 + +| 方法 | 描述 | +|------|------| +| [`Shutdown`](../../buffer/shutdown.md) | 关闭缓冲区 | +| [`Map`](../../buffer/map.md) | 映射缓冲区 | +| [`Unmap`](../../buffer/unmap.md) | 取消映射 | +| [`SetData`](../../buffer/set-data.md) | 设置数据 | +| [`GetSize`](../../buffer/get-size.md) | 获取缓冲区大小 | +| [`GetState`](../../buffer/get-state.md) | 获取资源状态 | | [`SetState`](../../buffer/set-state.md) | 设置资源状态 | -| [`GetName`](get-name.md) | 获取资源名称 | +| [`GetName`](../../buffer/get-name.md) | 获取资源名称 | | [`SetName`](../../buffer/set-name.md) | 设置资源名称 | -| [`GetStride`](get-stride.md) | 获取步长 | +| [`GetStride`](../../buffer/get-stride.md) | 获取步长 | | [`SetStride`](../../buffer/set-stride.md) | 设置步长 | -| [`GetBufferType`](get-buffer-type.md) | 获取缓冲区类型 | +| [`GetBufferType`](../../buffer/get-buffer-type.md) | 获取缓冲区类型 | | [`SetBufferType`](../../buffer/set-buffer-type.md) | 设置缓冲区类型 | -| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | +| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | + +## 使用示例 + +```cpp +// 创建顶点缓冲区 +D3D12Buffer vertexBuffer; +vertexBuffer.Initialize( + device, + sizeof(Vertex) * vertexCount, + D3D12_RESOURCE_STATE_VERTEX_AND_CONSTANT_BUFFER, + D3D12_HEAP_TYPE_DEFAULT); +vertexBuffer.SetName(L"VertexBuffer"); +vertexBuffer.SetBufferType(BufferType::Vertex); +vertexBuffer.SetStride(sizeof(Vertex)); + +// 创建索引缓冲区（带初始数据） +D3D12Buffer indexBuffer; +uint16_t indices[] = { 0, 1, 2, 1, 3, 2 }; +indexBuffer.InitializeWithData( + device, + commandList, + indices, + sizeof(indices), + D3D12_RESOURCE_STATE_INDEX_BUFFER); + +// 使用 UPLOAD 堆更新数据 +D3D12Buffer uploadBuffer; +uploadBuffer.Initialize(device, uploadSize, D3D12_RESOURCE_STATE_GENERIC_READ, D3D12_HEAP_TYPE_UPLOAD); +uploadBuffer.UpdateData(newData, dataSize); +``` ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../../d3d12/d3d12.md) - [RHIBuffer](../../buffer/buffer.md) - 抽象缓冲区接口 diff --git a/docs/api/rhi/d3d12/buffer/get-buffer-type.md b/docs/api/rhi/d3d12/buffer/get-buffer-type.md deleted file mode 100644 index 44698e04..00000000 --- a/docs/api/rhi/d3d12/buffer/get-buffer-type.md +++ /dev/null @@ -1,16 +0,0 @@ -# D3D12Buffer::GetBufferType / SetBufferType - -## 函数签名 - -```cpp -BufferType GetBufferType() const override -void SetBufferType(BufferType type) override -``` - -## 中文描述 - -获取和设置缓冲区类型（Vertex / Index / Constant 等）。 - -## 复杂度 - -O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-name.md b/docs/api/rhi/d3d12/buffer/get-name.md deleted file mode 100644 index 4d3d8739..00000000 --- a/docs/api/rhi/d3d12/buffer/get-name.md +++ /dev/null @@ -1,16 +0,0 @@ -# D3D12Buffer::GetName / SetName - -## 函数签名 - -```cpp -const std::string& GetName() const override -void SetName(const std::string& name) override -``` - -## 中文描述 - -获取和设置对象名称（用于调试）。 - -## 复杂度 - -O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-native-handle.md b/docs/api/rhi/d3d12/buffer/get-native-handle.md deleted file mode 100644 index bf64fcd2..00000000 --- a/docs/api/rhi/d3d12/buffer/get-native-handle.md +++ /dev/null @@ -1,19 +0,0 @@ -# D3D12Buffer::GetNativeHandle - -## 函数签名 - -```cpp -void* GetNativeHandle() override -``` - -## 中文描述 - -返回原生句柄，即 `ID3D12Resource*`。 - -## 返回值 - -`void*` - 原生句柄 - -## 复杂度 - -O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-size.md b/docs/api/rhi/d3d12/buffer/get-size.md deleted file mode 100644 index 9a1e8bcb..00000000 --- a/docs/api/rhi/d3d12/buffer/get-size.md +++ /dev/null @@ -1,19 +0,0 @@ -# D3D12Buffer::GetSize - -## 函数签名 - -```cpp -uint64_t GetSize() const override -``` - -## 中文描述 - -获取缓冲区大小（字节）。 - -## 返回值 - -`uint64_t` - 缓冲区大小 - -## 复杂度 - -O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-state.md b/docs/api/rhi/d3d12/buffer/get-state.md deleted file mode 100644 index f1b2e93e..00000000 --- a/docs/api/rhi/d3d12/buffer/get-state.md +++ /dev/null @@ -1,16 +0,0 @@ -# D3D12Buffer::GetState / SetState - -## 函数签名 - -```cpp -ResourceStates GetState() const -void SetState(ResourceStates state) -``` - -## 中文描述 - -获取和设置当前资源状态。用于状态跟踪和屏障生成。 - -## 复杂度 - -O(1) diff --git a/docs/api/rhi/d3d12/buffer/get-stride.md b/docs/api/rhi/d3d12/buffer/get-stride.md deleted file mode 100644 index b29afae1..00000000 --- a/docs/api/rhi/d3d12/buffer/get-stride.md +++ /dev/null @@ -1,16 +0,0 @@ -# D3D12Buffer::GetStride / SetStride - -## 函数签名 - -```cpp -uint32_t GetStride() const override -void SetStride(uint32_t stride) override -``` - -## 中文描述 - -获取和设置顶点缓冲区步长（字节）。 - -## 复杂度 - -O(1) diff --git a/docs/api/rhi/d3d12/buffer/initialize-with-data.md b/docs/api/rhi/d3d12/buffer/initialize-with-data.md index 41047bc6..2260a75c 100644 --- a/docs/api/rhi/d3d12/buffer/initialize-with-data.md +++ b/docs/api/rhi/d3d12/buffer/initialize-with-data.md @@ -33,9 +33,9 @@ O(n) - 取决于数据大小，内部创建临时上传堆 ```cpp uint16_t indices[] = { 0, 1, 2, 1, 3, 2 }; D3D12Buffer indexBuffer; -D3D12Buffer::InitializeWithData( - device->GetDevice(), - cmdList->GetCommandList(), +indexBuffer.InitializeWithData( + device, + commandList, indices, sizeof(indices), D3D12_RESOURCE_STATE_INDEX_BUFFER); diff --git a/docs/api/rhi/d3d12/buffer/map.md b/docs/api/rhi/d3d12/buffer/map.md deleted file mode 100644 index fbe02910..00000000 --- a/docs/api/rhi/d3d12/buffer/map.md +++ /dev/null @@ -1,27 +0,0 @@ -# D3D12Buffer::Map - -## 函数签名 - -```cpp -void* Map() override -``` - -## 中文描述 - -将缓冲区内存映射到 CPU 可访问地址。仅对 UPLOAD 或 READBACK 堆有效。 - -## 返回值 - -`void*` - 映射的内存指针 - -## 复杂度 - -O(1) - -## 示例 - -```cpp -void* mapped = uploadBuffer.Map(); -memcpy(mapped, vertexData, sizeof(vertexData)); -buffer.Unmap(); -``` diff --git a/docs/api/rhi/d3d12/buffer/set-data.md b/docs/api/rhi/d3d12/buffer/set-data.md deleted file mode 100644 index e3f6376a..00000000 --- a/docs/api/rhi/d3d12/buffer/set-data.md +++ /dev/null @@ -1,23 +0,0 @@ -# D3D12Buffer::SetData - -## 函数签名 - -```cpp -void SetData(const void* data, size_t size, size_t offset = 0) override -``` - -## 中文描述 - -设置缓冲区数据。通过 Map/Unmap 实现。 - -## 参数 - -| 参数 | 类型 | 描述 | -|------|------|------| -| `data` | `const void*` | 数据指针 | -| `size` | `size_t` | 数据大小 | -| `offset` | `size_t` | 缓冲区内的偏移量 | - -## 复杂度 - -O(n) diff --git a/docs/api/rhi/d3d12/buffer/shutdown.md b/docs/api/rhi/d3d12/buffer/shutdown.md deleted file mode 100644 index 9c3c4797..00000000 --- a/docs/api/rhi/d3d12/buffer/shutdown.md +++ /dev/null @@ -1,15 +0,0 @@ -# D3D12Buffer::Shutdown - -## 函数签名 - -```cpp -void Shutdown() override -``` - -## 中文描述 - -释放 D3D12 缓冲区资源，将成员变量置为空。 - -## 复杂度 - -O(1) diff --git a/docs/api/rhi/d3d12/buffer/unmap.md b/docs/api/rhi/d3d12/buffer/unmap.md deleted file mode 100644 index 2ee8db6f..00000000 --- a/docs/api/rhi/d3d12/buffer/unmap.md +++ /dev/null @@ -1,15 +0,0 @@ -# D3D12Buffer::Unmap - -## 函数签名 - -```cpp -void Unmap() override -``` - -## 中文描述 - -解除缓冲区内存映射。 - -## 复杂度 - -O(1) diff --git a/docs/api/rhi/d3d12/buffer/update-data.md b/docs/api/rhi/d3d12/buffer/update-data.md index ab757c1f..e2d3d711 100644 --- a/docs/api/rhi/d3d12/buffer/update-data.md +++ b/docs/api/rhi/d3d12/buffer/update-data.md @@ -17,6 +17,10 @@ void UpdateData(const void* data, uint64_t size) | `data` | `const void*` | 新数据指针 | | `size` | `uint64_t` | 数据大小 | +## 返回值 + +无 + ## 复杂度 O(n) diff --git a/docs/api/rhi/d3d12/command-allocator/command-allocator.md b/docs/api/rhi/d3d12/command-allocator/command-allocator.md index 7a7dfa98..a350e87a 100644 --- a/docs/api/rhi/d3d12/command-allocator/command-allocator.md +++ b/docs/api/rhi/d3d12/command-allocator/command-allocator.md @@ -2,18 +2,49 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 命令分配器的 D3D12 实现。 +**类型**: `class` (standalone, does not inherit from base) + +**描述**: DirectX 12 命令分配器的 D3D12 实现，用于管理 GPU 命令分配内存。 + +## 构造函数 + +| 方法 | 描述 | +|------|------| +| [`D3D12CommandAllocator`](constructor.md) | 默认构造函数 | ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化命令分配器 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭命令分配器 | -| [`Reset`](../../command-list/reset.md) | 重置命令分配器 | +| [`Initialize`](initialize.md) | 初始化命令分配器 | +| [`Shutdown`](shutdown.md) | 关闭命令分配器 | +| [`Reset`](reset.md) | 重置命令分配器 | | [`IsReady`](is-ready.md) | 检查是否就绪 | | [`GetCommandAllocator`](get-command-allocator.md) | 获取 D3D12 命令分配器 | +## 析构函数 + +| 方法 | 描述 | +|------|------| +| [`~D3D12CommandAllocator`](destructor.md) | 析构函数，自动调用 Shutdown | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::RHI; + +D3D12CommandAllocator allocator; +if (allocator.Initialize(device, CommandQueueType::Direct)) { + allocator.Reset(); + if (allocator.IsReady()) { + ID3D12CommandAllocator* native = allocator.GetCommandAllocator(); + } + allocator.Shutdown(); +} +``` + ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../../d3d12/d3d12.md) diff --git a/docs/api/rhi/d3d12/command-allocator/constructor.md b/docs/api/rhi/d3d12/command-allocator/constructor.md new file mode 100644 index 00000000..a2df205e --- /dev/null +++ b/docs/api/rhi/d3d12/command-allocator/constructor.md @@ -0,0 +1,20 @@ +# D3D12CommandAllocator::D3D12CommandAllocator + +```cpp +D3D12CommandAllocator(); +``` + +默认构造函数，创建一个未初始化的命令分配器实例。创建后需要调用 [`Initialize`](initialize.md) 进行初始化。 + +## 示例 + +```cpp +D3D12CommandAllocator allocator; +// 此时 allocator 未初始化，需要调用 Initialize +allocator.Initialize(device); +``` + +## 相关文档 + +- [D3D12CommandAllocator 总览](command-allocator.md) - 返回类总览 +- [D3D12CommandAllocator::Initialize](initialize.md) - 初始化分配器 diff --git a/docs/api/rhi/d3d12/command-allocator/destructor.md b/docs/api/rhi/d3d12/command-allocator/destructor.md new file mode 100644 index 00000000..c33734f4 --- /dev/null +++ b/docs/api/rhi/d3d12/command-allocator/destructor.md @@ -0,0 +1,22 @@ +# D3D12CommandAllocator::~D3D12CommandAllocator + +```cpp +~D3D12CommandAllocator(); +``` + +析构函数，自动调用 [`Shutdown`](shutdown.md) 释放底层 D3D12 资源。 + +## 示例 + +```cpp +{ + D3D12CommandAllocator allocator; + allocator.Initialize(device); + // 使用分配器 +} // 离开作用域时析构函数自动调用 Shutdown +``` + +## 相关文档 + +- [D3D12CommandAllocator 总览](command-allocator.md) - 返回类总览 +- [D3D12CommandAllocator::Shutdown](shutdown.md) - 关闭分配器 diff --git a/docs/api/rhi/d3d12/command-allocator/get-command-allocator.md b/docs/api/rhi/d3d12/command-allocator/get-command-allocator.md index da32a507..65183418 100644 --- a/docs/api/rhi/d3d12/command-allocator/get-command-allocator.md +++ b/docs/api/rhi/d3d12/command-allocator/get-command-allocator.md @@ -6,6 +6,16 @@ ID3D12CommandAllocator* GetCommandAllocator() const { return m_commandAllocator. 获取底层的 D3D12 命令分配器接口。 +## 示例 + +```cpp +D3D12CommandAllocator allocator; +if (allocator.Initialize(device)) { + ID3D12CommandAllocator* native = allocator.GetCommandAllocator(); + // 使用原生 D3D12 接口 +} +``` + **返回：** `ID3D12CommandAllocator*` **复杂度：** O(1) diff --git a/docs/api/rhi/d3d12/command-allocator/initialize.md b/docs/api/rhi/d3d12/command-allocator/initialize.md new file mode 100644 index 00000000..3044f096 --- /dev/null +++ b/docs/api/rhi/d3d12/command-allocator/initialize.md @@ -0,0 +1,37 @@ +# D3D12CommandAllocator::Initialize + +```cpp +bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct); +``` + +初始化 D3D12 命令分配器，创建指定类型的命令分配器。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `type` | `CommandQueueType` | 命令队列类型，默认值为 `Direct` | + +## 返回值 + +`bool` - 初始化是否成功 + +## 示例 + +```cpp +D3D12CommandAllocator allocator; +if (allocator.Initialize(device, CommandQueueType::Direct)) { + // 分配器初始化成功 +} +``` + +## 复杂度 + +O(1) + +## 相关文档 + +- [D3D12CommandAllocator 总览](command-allocator.md) - 返回类总览 +- [D3D12CommandAllocator::Reset](reset.md) - 重置分配器 +- [D3D12CommandAllocator::Shutdown](shutdown.md) - 关闭分配器 diff --git a/docs/api/rhi/d3d12/command-allocator/is-ready.md b/docs/api/rhi/d3d12/command-allocator/is-ready.md index c70acb1d..87f191e8 100644 --- a/docs/api/rhi/d3d12/command-allocator/is-ready.md +++ b/docs/api/rhi/d3d12/command-allocator/is-ready.md @@ -6,6 +6,17 @@ bool IsReady() const; 检查命令分配器是否准备就绪。 +## 示例 + +```cpp +D3D12CommandAllocator allocator; +if (allocator.Initialize(device)) { + if (allocator.IsReady()) { + // 分配器就绪可以使用 + } +} +``` + **返回：** 分配器是否准备就绪 **复杂度：** O(1) diff --git a/docs/api/rhi/d3d12/command-allocator/reset.md b/docs/api/rhi/d3d12/command-allocator/reset.md new file mode 100644 index 00000000..7d4bfe8f --- /dev/null +++ b/docs/api/rhi/d3d12/command-allocator/reset.md @@ -0,0 +1,25 @@ +# D3D12CommandAllocator::Reset + +```cpp +void Reset(); +``` + +重置命令分配器，将分配器重置为初始状态，使其可以重新使用。此方法必须在 GPU 完成所有使用该分配器的命令后才能调用。 + +## 示例 + +```cpp +D3D12CommandAllocator allocator; +if (allocator.Initialize(device)) { + allocator.Reset(); // 重置以重新使用 +} +``` + +## 复杂度 + +O(1) + +## 相关文档 + +- [D3D12CommandAllocator 总览](command-allocator.md) - 返回类总览 +- [D3D12CommandAllocator::Initialize](initialize.md) - 初始化分配器 diff --git a/docs/api/rhi/d3d12/command-allocator/shutdown.md b/docs/api/rhi/d3d12/command-allocator/shutdown.md new file mode 100644 index 00000000..9607e26a --- /dev/null +++ b/docs/api/rhi/d3d12/command-allocator/shutdown.md @@ -0,0 +1,27 @@ +# D3D12CommandAllocator::Shutdown + +```cpp +void Shutdown(); +``` + +关闭 D3D12 命令分配器，释放底层 D3D12 资源。此方法通常不需要显式调用，析构函数会自动执行。 + +## 示例 + +```cpp +D3D12CommandAllocator allocator; +if (allocator.Initialize(device)) { + // 使用分配器 + allocator.Shutdown(); // 显式关闭 +} +// 或者依靠析构函数自动关闭 +``` + +## 复杂度 + +O(1) + +## 相关文档 + +- [D3D12CommandAllocator 总览](command-allocator.md) - 返回类总览 +- [D3D12CommandAllocator::Initialize](initialize.md) - 初始化分配器 diff --git a/docs/api/rhi/d3d12/command-list/begin-query.md b/docs/api/rhi/d3d12/command-list/begin-query.md index 8fb4f0b6..9bc50813 100644 --- a/docs/api/rhi/d3d12/command-list/begin-query.md +++ b/docs/api/rhi/d3d12/command-list/begin-query.md @@ -13,6 +13,15 @@ void BeginQuery(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t index); **复杂度：** O(1) +**示例：** + +```cpp +ID3D12QueryHeap* queryHeap = /* 获取查询堆 */; +cmdList.BeginQuery(queryHeap, QueryType::Timestamp, 0); +``` + ## 相关文档 - [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [EndQuery](end-query.md) - 结束查询 +- [ResolveQueryData](resolve-query-data.md) - 解析查询数据 diff --git a/docs/api/rhi/d3d12/command-list/clear.md b/docs/api/rhi/d3d12/command-list/clear.md new file mode 100644 index 00000000..25971b1c --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/clear.md @@ -0,0 +1,21 @@ +# D3D12CommandList::Clear + +```cpp +void Clear(float r, float g, float b, float a, uint32_t buffers) override; +``` + +清除渲染目标和/或深度模板缓冲区。 + +**参数：** +- `r` - 清除颜色（红色通道） +- `g` - 清除颜色（绿色通道） +- `b` - 清除颜色（蓝色通道） +- `a` - 清除颜色（Alpha通道） +- `buffers` - 要清除的缓冲区标志 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [RHICommandList::Clear](../../command-list/command-list.md) - 基类方法 diff --git a/docs/api/rhi/d3d12/command-list/close.md b/docs/api/rhi/d3d12/command-list/close.md new file mode 100644 index 00000000..baa00789 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/close.md @@ -0,0 +1,14 @@ +# D3D12CommandList::Close + +```cpp +void Close() override; +``` + +关闭命令列表，停止录制。 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [RHICommandList::Close](../../command-list/command-list.md) - 基类方法 diff --git a/docs/api/rhi/d3d12/command-list/command-list.md b/docs/api/rhi/d3d12/command-list/command-list.md index 714fd926..e08d7c09 100644 --- a/docs/api/rhi/d3d12/command-list/command-list.md +++ b/docs/api/rhi/d3d12/command-list/command-list.md @@ -2,18 +2,33 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 命令列表的 D3D12 实现，继承自 `RHICommandList`。 +**继承自**: [`RHICommandList`](../../command-list/command-list.md) + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 概述 + +`D3D12CommandList` 是 DirectX 12 命令列表的 RHI 实现，封装了 `ID3D12GraphicsCommandList` 接口。该类负责记录 GPU 命令，包括绘制调用、资源状态转换、渲染目标设置等。 + +### 主要功能 + +- **命令录制**: 支持图形和计算命令的录制 +- **资源状态管理**: 维护资源状态映射表，跟踪资源转换 +- **描述符管理**: 管理 GPU 描述符堆和描述符表 +- **状态设置**: 设置管线状态、根签名、视口、裁剪矩形等 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭命令列表 | -| [`Reset`](../../command-list/reset.md) | 重置命令列表 | -| [`Close`](../../command-list/close.md) | 关闭命令列表 | +| [`D3D12CommandList`](../../../threading/lambdatask/constructor.md) | 构造函数 | +| [`~D3D12CommandList`](../../../threading/readwritelock/destructor.md) | 析构函数 | +| [`Initialize`](initialize.md) | 初始化命令列表 | +| [`Shutdown`](shutdown.md) | 关闭命令列表 | +| [`Reset`](reset.md) | 重置命令列表 | +| [`Close`](close.md) | 关闭命令列表 | | [`GetCommandList`](get-command-list.md) | 获取 D3D12 命令列表 | | [`TransitionBarrier`](transition-barrier.md) | 资源状态转换 | -| [`TransitionBarrierInternal`](transition-barrier-internal.md) | 内部资源状态转换 | | [`UAVBarrier`](uav-barrier.md) | UAV 屏障 | | [`AliasBarrier`](alias-barrier.md) | 别名屏障 | | [`SetPipelineState`](set-pipeline-state.md) | 设置管线状态 | @@ -24,8 +39,6 @@ | [`SetScissorRect`](set-scissor-rect.md) | 设置裁剪矩形 | | [`SetScissorRects`](set-scissor-rects.md) | 设置多个裁剪矩形 | | [`SetRenderTargets`](set-render-targets.md) | 设置渲染目标 | -| [`SetRenderTargetsInternal`](set-render-targets-internal.md) | 内部渲染目标设置 | -| [`SetRenderTargetsHandle`](set-render-targets-handle.md) | 句柄渲染目标设置 | | [`SetVertexBuffer`](set-vertex-buffer.md) | 设置顶点缓冲 | | [`SetVertexBuffers`](set-vertex-buffers.md) | 设置多个顶点缓冲 | | [`SetIndexBuffer`](set-index-buffer.md) | 设置索引缓冲 | @@ -44,7 +57,7 @@ | [`DrawIndexed`](draw-indexed.md) | 索引绘制 | | [`DrawInstancedIndirect`](draw-instanced-indirect.md) | 实例化间接绘制 | | [`DrawIndexedInstancedIndirect`](draw-indexed-instanced-indirect.md) | 索引实例化间接绘制 | -| [`Clear`](../../command-list/clear.md) | 清除 | +| [`Clear`](clear.md) | 清除 | | [`ClearRenderTarget`](clear-render-target.md) | 清除渲染目标 | | [`ClearDepthStencil`](clear-depth-stencil.md) | 清除深度模板 | | [`CopyResource`](copy-resource.md) | 复制资源 | @@ -59,7 +72,45 @@ | [`GetResourceState`](get-resource-state.md) | 获取资源状态 | | [`TrackResource`](track-resource.md) | 跟踪资源 | +## 使用示例 + +```cpp +#include "XCEngine/RHI/D3D12/D3D12CommandList.h" +#include "XCEngine/RHI/D3D12/D3D12Device.h" + +using namespace XCEngine::RHI; + +// 创建命令列表 +D3D12CommandList cmdList; +ID3D12Device* device = /* 获取设备 */; + +// 初始化 +if (!cmdList.Initialize(device, CommandQueueType::Direct)) { + return false; +} + +// 重置并开始录制 +cmdList.Reset(); + +// 设置渲染状态 +cmdList.SetPipelineState(pipelineState); +cmdList.SetRootSignature(rootSignature); +cmdList.SetPrimitiveTopology(PrimitiveTopology::TriangleList); +cmdList.SetViewport(viewport); +cmdList.SetRenderTargets(1, renderTargets, depthStencil); + +// 绑定资源 +cmdList.SetVertexBuffer(0, vertexBuffer, 0, sizeof(Vertex)); +cmdList.SetIndexBuffer(indexBuffer, 0, Format::R32_UINT); + +// 绘制 +cmdList.DrawIndexed(indexCount, 1, 0, 0, 0); + +// 关闭命令列表 +cmdList.Close(); +``` + ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../d3d12.md) - [RHICommandList](../../command-list/command-list.md) - 抽象命令列表接口 diff --git a/docs/api/rhi/d3d12/command-list/copy-buffer.md b/docs/api/rhi/d3d12/command-list/copy-buffer.md index 49fddf4f..bbe09a04 100644 --- a/docs/api/rhi/d3d12/command-list/copy-buffer.md +++ b/docs/api/rhi/d3d12/command-list/copy-buffer.md @@ -13,8 +13,18 @@ void CopyBuffer(ID3D12Resource* dst, uint64_t dstOffset, ID3D12Resource* src, ui - `srcOffset` - 源偏移 - `size` - 复制大小 -**复杂度：** O(n) +**复杂度：** O(n)，n 为复制数据量 + +**示例：** + +```cpp +ID3D12Resource* srcBuffer = /* 源缓冲区 */; +ID3D12Resource* dstBuffer = /* 目标缓冲区 */; +cmdList.CopyBuffer(dstBuffer, 0, srcBuffer, 0, 1024); +``` ## 相关文档 - [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [CopyResource](copy-resource.md) - 复制整个资源 +- [CopyTexture](copy-texture.md) - 复制纹理数据 diff --git a/docs/api/rhi/d3d12/command-list/copy-resource.md b/docs/api/rhi/d3d12/command-list/copy-resource.md index 1ebadd90..bb6dafe4 100644 --- a/docs/api/rhi/d3d12/command-list/copy-resource.md +++ b/docs/api/rhi/d3d12/command-list/copy-resource.md @@ -10,8 +10,18 @@ void CopyResource(void* dst, void* src) override; - `dst` - 目标资源指针 - `src` - 源资源指针 -**复杂度：** O(n) +**复杂度：** O(n)，n 为资源大小 + +**示例：** + +```cpp +ID3D12Resource* dst = /* 目标资源 */; +ID3D12Resource* src = /* 源资源 */; +cmdList.CopyResource(dst, src); +``` ## 相关文档 - [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [CopyBuffer](copy-buffer.md) - 复制缓冲区数据 +- [CopyTexture](copy-texture.md) - 复制纹理数据 diff --git a/docs/api/rhi/d3d12/command-list/copy-texture.md b/docs/api/rhi/d3d12/command-list/copy-texture.md index cb7ea684..e3415813 100644 --- a/docs/api/rhi/d3d12/command-list/copy-texture.md +++ b/docs/api/rhi/d3d12/command-list/copy-texture.md @@ -12,8 +12,26 @@ void CopyTexture(ID3D12Resource* dst, const D3D12_TEXTURE_COPY_LOCATION& dstLoca - `src` - 源纹理 - `srcLocation` - 源位置 -**复杂度：** O(n) +**复杂度：** O(n)，n 为复制数据量 + +**示例：** + +```cpp +D3D12_TEXTURE_COPY_LOCATION dstLoc = {}; +dstLoc.pResource = dstTexture; +dstLoc.Type = D3D12_TEXTURE_COPY_TYPE_SUBRESOURCE_INDEX; +dstLoc.SubresourceIndex = 0; + +D3D12_TEXTURE_COPY_LOCATION srcLoc = {}; +srcLoc.pResource = srcTexture; +srcLoc.Type = D3D12_TEXTURE_COPY_TYPE_SUBRESOURCE_INDEX; +srcLoc.SubresourceIndex = 0; + +cmdList.CopyTexture(dst, dstLoc, src, srcLoc); +``` ## 相关文档 - [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [CopyResource](copy-resource.md) - 复制整个资源 +- [CopyBuffer](copy-buffer.md) - 复制缓冲区数据 diff --git a/docs/api/rhi/d3d12/command-list/dispatch-indirect.md b/docs/api/rhi/d3d12/command-list/dispatch-indirect.md index ab5cf179..fca32953 100644 --- a/docs/api/rhi/d3d12/command-list/dispatch-indirect.md +++ b/docs/api/rhi/d3d12/command-list/dispatch-indirect.md @@ -4,7 +4,7 @@ void DispatchIndirect(void* argBuffer, uint64_t alignedByteOffset); ``` -间接分发计算命令。 +间接分发计算命令，使用存储在缓冲区中的参数执行 `Dispatch` 操作。 **参数：** - `argBuffer` - 参数缓冲区 @@ -12,6 +12,14 @@ void DispatchIndirect(void* argBuffer, uint64_t alignedByteOffset); **复杂度：** O(1) +**示例：** + +```cpp +ID3D12Resource* argBuffer = /* 包含 DispatchIndirect 参数的缓冲区 */; +cmdList.DispatchIndirect(argBuffer, 0); +``` + ## 相关文档 - [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [Dispatch](dispatch.md) - 直接分发计算任务 diff --git a/docs/api/rhi/d3d12/command-list/end-query.md b/docs/api/rhi/d3d12/command-list/end-query.md index f8bde2a2..c2ea899b 100644 --- a/docs/api/rhi/d3d12/command-list/end-query.md +++ b/docs/api/rhi/d3d12/command-list/end-query.md @@ -13,6 +13,15 @@ void EndQuery(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t index); **复杂度：** O(1) +**示例：** + +```cpp +ID3D12QueryHeap* queryHeap = /* 获取查询堆 */; +cmdList.EndQuery(queryHeap, QueryType::Timestamp, 0); +``` + ## 相关文档 - [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [BeginQuery](begin-query.md) - 开始查询 +- [ResolveQueryData](resolve-query-data.md) - 解析查询数据 diff --git a/docs/api/rhi/d3d12/command-list/execute-bundle.md b/docs/api/rhi/d3d12/command-list/execute-bundle.md index 0ddd68fa..1db2dea6 100644 --- a/docs/api/rhi/d3d12/command-list/execute-bundle.md +++ b/docs/api/rhi/d3d12/command-list/execute-bundle.md @@ -11,6 +11,13 @@ void ExecuteBundle(ID3D12GraphicsCommandList* bundle); **复杂度：** O(1) +**示例：** + +```cpp +ID3D12GraphicsCommandList* bundle = /* 获取 Bundle */; +cmdList.ExecuteBundle(bundle); +``` + ## 相关文档 - [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/get-resource-state.md b/docs/api/rhi/d3d12/command-list/get-resource-state.md index 81f3d2a6..bfe88822 100644 --- a/docs/api/rhi/d3d12/command-list/get-resource-state.md +++ b/docs/api/rhi/d3d12/command-list/get-resource-state.md @@ -9,10 +9,22 @@ ResourceStates GetResourceState(ID3D12Resource* resource) const; **参数：** - `resource` - D3D12 资源指针 -**返回：** 资源当前状态 +**返回值：** 资源当前状态，如果资源未被跟踪则返回 `ResourceStates::Common` **复杂度：** O(1) +**示例：** + +```cpp +ID3D12Resource* resource = /* 获取资源 */; +ResourceStates state = cmdList.GetResourceState(resource); +if (state == ResourceStates::RenderTarget) { + // 资源当前为渲染目标状态 +} +``` + ## 相关文档 - [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [TrackResource](track-resource.md) - 跟踪资源 +- [TransitionBarrier](transition-barrier.md) - 资源状态转换 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/command-list/initialize.md b/docs/api/rhi/d3d12/command-list/initialize.md new file mode 100644 index 00000000..1de48480 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/initialize.md @@ -0,0 +1,40 @@ +# D3D12CommandList::Initialize + +```cpp +bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct, ID3D12CommandAllocator* allocator = nullptr); +``` + +初始化 D3D12 命令列表，创建 `ID3D12GraphicsCommandList` 实例。 + +**参数：** +- `device` - D3D12 设备指针 +- `type` - 命令队列类型，默认为 `CommandQueueType::Direct` +- `allocator` - 命令分配器指针，如果为 `nullptr`，则由方法内部创建 + +**返回值：** +- `bool` - 初始化成功返回 `true`，失败返回 `false` + +**复杂度：** O(1) + +**示例：** + +```cpp +D3D12CommandList cmdList; +ID3D12Device* device = /* 获取设备 */; + +if (!cmdList.Initialize(device)) { + // 处理初始化失败 + return; +} + +// 使用命令列表... +cmdList.Reset(); +// ... 录制命令 +cmdList.Close(); +``` + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [Shutdown](shutdown.md) - 关闭命令列表 +- [Close](close.md) - 关闭命令列表 diff --git a/docs/api/rhi/d3d12/command-list/reset.md b/docs/api/rhi/d3d12/command-list/reset.md new file mode 100644 index 00000000..adc13abb --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/reset.md @@ -0,0 +1,14 @@ +# D3D12CommandList::Reset + +```cpp +void Reset() override; +``` + +重置命令列表，准备录制新命令。 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [RHICommandList::Reset](../../command-list/command-list.md) - 基类方法 diff --git a/docs/api/rhi/d3d12/command-list/resolve-query-data.md b/docs/api/rhi/d3d12/command-list/resolve-query-data.md index df1e241d..4f7c19ab 100644 --- a/docs/api/rhi/d3d12/command-list/resolve-query-data.md +++ b/docs/api/rhi/d3d12/command-list/resolve-query-data.md @@ -14,8 +14,18 @@ void ResolveQueryData(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t start - `resultBuffer` - 结果缓冲区 - `resultOffset` - 结果偏移 -**复杂度：** O(n) +**复杂度：** O(n)，n 为查询数量 + +**示例：** + +```cpp +ID3D12QueryHeap* queryHeap = /* 获取查询堆 */; +ID3D12Resource* resultBuffer = /* 结果缓冲区 */; +cmdList.ResolveQueryData(queryHeap, QueryType::Timestamp, 0, 1, resultBuffer, 0); +``` ## 相关文档 - [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [BeginQuery](begin-query.md) - 开始查询 +- [EndQuery](end-query.md) - 结束查询 diff --git a/docs/api/rhi/d3d12/command-list/set-depth-bias.md b/docs/api/rhi/d3d12/command-list/set-depth-bias.md index 55dd006c..8410d38f 100644 --- a/docs/api/rhi/d3d12/command-list/set-depth-bias.md +++ b/docs/api/rhi/d3d12/command-list/set-depth-bias.md @@ -13,6 +13,16 @@ void SetDepthBias(float depthBias, float slopeScaledDepthBias, float depthBiasCl **复杂度：** O(1) +**注意：** 当前实现为空，深度偏移通过管线状态对象设置。 + +**示例：** + +```cpp +// 深度偏移参数通常在 PSO 中设置 +// 此方法当前为空实现 +cmdList.SetDepthBias(0.0f, 0.0f, 0.0f); +``` + ## 相关文档 - [D3D12CommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/command-list/shutdown.md b/docs/api/rhi/d3d12/command-list/shutdown.md new file mode 100644 index 00000000..6d904af1 --- /dev/null +++ b/docs/api/rhi/d3d12/command-list/shutdown.md @@ -0,0 +1,14 @@ +# D3D12CommandList::Shutdown + +```cpp +void Shutdown() override; +``` + +关闭命令列表并释放相关资源。 + +**复杂度：** O(n) - 遍历释放所有跟踪的资源 + +## 相关文档 + +- [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [RHICommandList::Shutdown](../../command-list/command-list.md) - 基类方法 diff --git a/docs/api/rhi/d3d12/command-list/track-resource.md b/docs/api/rhi/d3d12/command-list/track-resource.md index b9502045..266b7e2a 100644 --- a/docs/api/rhi/d3d12/command-list/track-resource.md +++ b/docs/api/rhi/d3d12/command-list/track-resource.md @@ -11,6 +11,15 @@ void TrackResource(ID3D12Resource* resource); **复杂度：** O(1) +**示例：** + +```cpp +ID3D12Resource* resource = /* 获取资源 */; +cmdList.TrackResource(resource); +``` + ## 相关文档 - [D3D12CommandList 总览](command-list.md) - 返回类总览 +- [GetResourceState](get-resource-state.md) - 获取资源状态 +- [TransitionBarrier](transition-barrier.md) - 资源状态转换 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/command-queue/command-queue.md b/docs/api/rhi/d3d12/command-queue/command-queue.md index c717e41b..b5dffb2d 100644 --- a/docs/api/rhi/d3d12/command-queue/command-queue.md +++ b/docs/api/rhi/d3d12/command-queue/command-queue.md @@ -2,25 +2,48 @@ **命名空间**: `XCEngine::RHI` +**类型**: `class` + +**继承**: `RHICommandQueue` + **描述**: DirectX 12 命令队列的 D3D12 实现，继承自 `RHICommandQueue`。 ## 公共方法 -| 方法 | 描述 | -|------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化命令队列 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭命令队列 | -| [`ExecuteCommandLists`](execute-command-lists.md) | 执行命令列表 | -| [`Signal`](signal.md) | 信号栅栏 | -| [`Wait`](../../../threading/task-group/wait.md) | 等待栅栏 | -| [`GetCompletedValue`](get-completed-value.md) | 获取完成值 | -| [`WaitForIdle`](wait-for-idle.md) | 等待空闲 | -| [`GetType`](../../command-queue/get-type.md) | 获取队列类型 | -| [`GetTimestampFrequency`](get-timestamp-frequency.md) | 获取时间戳频率 | -| [`GetCommandQueue`](get-command-queue.md) | 获取 D3D12 命令队列 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| 方法 | 描述 | 类型 | +|------|------|------| +| [`Initialize`](initialize.md) | 初始化命令队列 | D3D12 特有 | +| [`Shutdown`](shutdown.md) | 关闭命令队列 | Override | +| [`ExecuteCommandLists`](execute-command-lists.md) | 执行命令列表 | Override | +| [`Signal`](signal.md) | 信号栅栏（RHIFence 重载） | Override | +| [`Signal(ID3D12Fence*)`](signal-native.md) | 信号栅栏（Native D3D12Fence） | D3D12 特有 | +| [`Wait`](wait.md) | 等待栅栏达到指定值 | Override | +| [`Wait(ID3D12Fence*)`](wait-native.md) | 等待栅栏（Native D3D12Fence） | D3D12 特有 | +| [`GetCompletedValue`](get-completed-value.md) | 获取完成值 | Override | +| [`WaitForIdle`](wait-for-idle.md) | 等待空闲 | Override | +| [`GetType`](get-type.md) | 获取队列类型 | Override | +| [`GetTimestampFrequency`](get-timestamp-frequency.md) | 获取时间戳频率 | Override | +| [`GetCommandQueue`](get-command-queue.md) | 获取 D3D12 命令队列 | D3D12 特有 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | Override | + +## 使用示例 + +```cpp +ID3D12Device* device; // 初始化好的 D3D12 设备 +D3D12CommandQueue commandQueue; + +if (commandQueue.Initialize(device, CommandQueueType::Direct)) { + // 使用命令队列 + commandQueue.ExecuteCommandLists(count, lists); + + // 等待完成 + commandQueue.WaitForIdle(); +} +``` ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../d3d12.md) - [RHICommandQueue](../../command-queue/command-queue.md) - 抽象命令队列接口 +- [D3D12CommandList](../command-list/command-list.md) +- [D3D12Fence](../fence/fence.md) diff --git a/docs/api/rhi/d3d12/command-queue/execute-command-lists.md b/docs/api/rhi/d3d12/command-queue/execute-command-lists.md index ca08fc31..640dfa0f 100644 --- a/docs/api/rhi/d3d12/command-queue/execute-command-lists.md +++ b/docs/api/rhi/d3d12/command-queue/execute-command-lists.md @@ -4,14 +4,31 @@ void ExecuteCommandLists(uint32_t count, void** lists) override; ``` -执行命令列表。 +将指定数量的命令列表提交到命令队列执行。所有命令列表将在 GPU 上按提交顺序串行执行。 **参数：** -- `count` - 命令列表数量 -- `lists` - 命令列表指针数组 +- `count` - 命令列表数量，为正整数 +- `lists` - 命令列表指针数组，每个元素类型为 `ID3D12CommandList*` -**复杂度：** O(n) +**返回：** 无 + +**线程安全：** 可从任意线程调用，建议从单线程提交以保证顺序 + +**复杂度：** O(1) 提交，O(n) GPU 执行（n 为命令数量） + +**注意：** 此方法会阻塞调用线程直到命令列表提交完成，GPU 实际执行是异步的。 + +## 示例 + +```cpp +ID3D12CommandList* lists[2]; +lists[0] = commandList1->GetCommandList(); +lists[1] = commandList2->GetCommandList(); + +commandQueue.ExecuteCommandLists(2, reinterpret_cast(lists)); +``` ## 相关文档 - [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 +- [D3D12CommandList](../command-list/command-list.md) diff --git a/docs/api/rhi/d3d12/command-queue/get-completed-value.md b/docs/api/rhi/d3d12/command-queue/get-completed-value.md index f649b7da..3958f398 100644 --- a/docs/api/rhi/d3d12/command-queue/get-completed-value.md +++ b/docs/api/rhi/d3d12/command-queue/get-completed-value.md @@ -4,12 +4,16 @@ uint64_t GetCompletedValue() override; ``` -获取已完成值。 +获取命令队列关联的栅栏的当前完成值。 -**返回：** 栅栏已完成的值 +**返回：** 栅栏的已完成值 **复杂度：** O(1) +**注意：** 当前实现始终返回 0，表示此方法为未完成功能。使用前请确认功能状态。 + ## 相关文档 - [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 +- [Signal](signal.md) - 向栅栏发送信号 +- [D3D12Fence](../fence/fence.md) diff --git a/docs/api/rhi/d3d12/command-queue/get-native-handle.md b/docs/api/rhi/d3d12/command-queue/get-native-handle.md new file mode 100644 index 00000000..58b5c135 --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/get-native-handle.md @@ -0,0 +1,18 @@ +# D3D12CommandQueue::GetNativeHandle + +```cpp +void* GetNativeHandle() override { return m_commandQueue.Get(); } +``` + +获取命令队列的原生句柄，用于与底层 D3D12 API 交互。 + +**返回：** `void*` 类型的原生指针，实际类型为 `ID3D12CommandQueue*` + +**复杂度：** O(1) + +**注意：** 返回的指针在命令队列销毁后将变为无效。请勿在命令队列销毁后继续使用。 + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 +- [GetCommandQueue](get-command-queue.md) - 获取类型安全的 D3D12 命令队列指针 diff --git a/docs/api/rhi/d3d12/command-queue/get-type.md b/docs/api/rhi/d3d12/command-queue/get-type.md new file mode 100644 index 00000000..bc93af38 --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/get-type.md @@ -0,0 +1,21 @@ +# D3D12CommandQueue::GetType + +```cpp +CommandQueueType GetType() const override { return m_type; } +``` + +获取命令队列的类型。 + +**返回：** `CommandQueueType` 枚举值，表示命令队列类型 + +- `Direct` - 直接命令队列，用于图形和计算操作 +- `Compute` - 计算命令队列，用于纯计算操作 +- `Copy` - 复制命令队列，用于数据传输操作 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 +- [Initialize](initialize.md) - 初始化命令队列 +- [CommandQueueType](../../common/enums.md#commandqueuetype) - 队列类型枚举说明 diff --git a/docs/api/rhi/d3d12/command-queue/initialize.md b/docs/api/rhi/d3d12/command-queue/initialize.md new file mode 100644 index 00000000..3bee6541 --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/initialize.md @@ -0,0 +1,31 @@ +# D3D12CommandQueue::Initialize + +```cpp +bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct); +``` + +初始化 D3D12 命令队列，创建底层 `ID3D12CommandQueue` 对象。 + +**参数：** +- `device` - D3D12 设备指针 +- `type` - 命令队列类型，默认为 `Direct` + +**返回：** 初始化成功返回 `true`，失败返回 `false` + +**复杂度：** O(1) + +## 示例 + +```cpp +ID3D12Device* device; // 已初始化的 D3D12 设备 +D3D12CommandQueue commandQueue; + +if (commandQueue.Initialize(device, CommandQueueType::Direct)) { + // 命令队列初始化成功 +} +``` + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 +- [Shutdown](../../command-queue/shutdown.md) - 关闭命令队列 diff --git a/docs/api/rhi/d3d12/command-queue/shutdown.md b/docs/api/rhi/d3d12/command-queue/shutdown.md new file mode 100644 index 00000000..781f40c4 --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/shutdown.md @@ -0,0 +1,31 @@ +# D3D12CommandQueue::Shutdown + +```cpp +void Shutdown() override; +``` + +关闭命令队列并释放底层 D3D12 资源。调用此方法后，命令队列将变为无效状态。 + +**返回：** 无 + +**注意：** +- 此方法由析构函数自动调用 +- 调用前应确保没有正在执行命令 +- 释放底层的 `ID3D12CommandQueue` 接口 + +## 示例 + +```cpp +D3D12CommandQueue commandQueue; +commandQueue.Initialize(device, CommandQueueType::Direct); + +// 使用命令队列... + +// 关闭并释放资源 +commandQueue.Shutdown(); +``` + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 +- [Initialize](initialize.md) - 初始化命令队列 diff --git a/docs/api/rhi/d3d12/command-queue/signal-native.md b/docs/api/rhi/d3d12/command-queue/signal-native.md new file mode 100644 index 00000000..09444630 --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/signal-native.md @@ -0,0 +1,25 @@ +# D3D12CommandQueue::Signal (Native) + +```cpp +void Signal(ID3D12Fence* fence, uint64_t value); +``` + +向 D3D12 原生栅栏发送信号。 + +**参数：** +- `fence` - D3D12 原生栅栏指针 +- `value` - 信号值 + +**复杂度：** O(1) + +## 示例 + +```cpp +ID3D12Fence* nativeFence; // D3D12 原生栅栏 +commandQueue.Signal(nativeFence, 1); +``` + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 +- [Signal(RHIFence*)](../../command-queue/signal.md) - RHIFence 重载版本 diff --git a/docs/api/rhi/d3d12/command-queue/signal.md b/docs/api/rhi/d3d12/command-queue/signal.md index b1ec2650..11ecc479 100644 --- a/docs/api/rhi/d3d12/command-queue/signal.md +++ b/docs/api/rhi/d3d12/command-queue/signal.md @@ -4,14 +4,31 @@ void Signal(RHIFence* fence, uint64_t value) override; ``` -发送信号。 +向指定栅栏发送信号，将栅栏的完成值设置为给定值。该方法用于同步 GPU 和 CPU 操作。 **参数：** -- `fence` - 栅栏指针 -- `value` - 信号值 +- `fence` - 目标栅栏指针，不能为 `nullptr` +- `value` - 信号值，一个正整数 + +**返回：** 无 **复杂度：** O(1) +**使用场景：** +- 标记命令队列中所有已提交命令完成的时间点 +- 用于 GPU-CPU 同步 +- 与 `Wait` 方法配合实现 GPU 流水线同步 + +## 示例 + +```cpp +D3D12Fence* fence; // 已初始化的栅栏 +commandQueue.Signal(fence, 1); +// CPU 可以继续其他工作，GPU 执行完成后 fence 的值变为 1 +``` + ## 相关文档 - [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 +- [Wait](wait-for-idle.md) - 等待命令队列完成 +- [D3D12Fence](../fence/fence.md) diff --git a/docs/api/rhi/d3d12/command-queue/wait-for-idle.md b/docs/api/rhi/d3d12/command-queue/wait-for-idle.md index 71c0f4ba..47e274da 100644 --- a/docs/api/rhi/d3d12/command-queue/wait-for-idle.md +++ b/docs/api/rhi/d3d12/command-queue/wait-for-idle.md @@ -4,10 +4,33 @@ void WaitForIdle() override; ``` -等待空闲。 +阻塞当前线程，直到命令队列中所有已提交的命令全部执行完成。该方法会强制 GPU 等待所有待处理命令完成后才返回。 -**复杂度：** O(n) +**返回：** 无 + +**复杂度：** O(n)，其中 n 为待处理命令的数量 + +**使用场景：** +- 帧同步：确保一帧的所有渲染命令完成后再进行下一步操作 +- 资源管理：确保 GPU 不再使用某个资源后再释放 +- 调试：等待特定命令完成以便进行 GPU 调试 + +**注意：** 这是一个阻塞调用，会暂停 CPU 线程直到 GPU 完成所有命令。频繁调用可能影响性能。 + +## 示例 + +```cpp +// 提交渲染命令 +commandQueue.ExecuteCommandLists(count, lists); + +// 等待所有命令完成 +commandQueue.WaitForIdle(); + +// 此时可以安全地释放命令列表使用的资源 +``` ## 相关文档 - [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 +- [Signal](signal.md) - 向栅栏发送信号 +- [Wait](signal.md) - 等待栅栏达到指定值 diff --git a/docs/api/rhi/d3d12/command-queue/wait-native.md b/docs/api/rhi/d3d12/command-queue/wait-native.md new file mode 100644 index 00000000..476eb302 --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/wait-native.md @@ -0,0 +1,25 @@ +# D3D12CommandQueue::Wait (Native) + +```cpp +void Wait(ID3D12Fence* fence, uint64_t value); +``` + +等待 D3D12 原生栅栏达到指定值。 + +**参数：** +- `fence` - D3D12 原生栅栏指针 +- `value` - 等待的信号值 + +**复杂度：** O(1) + +## 示例 + +```cpp +ID3D12Fence* nativeFence; // D3D12 原生栅栏 +commandQueue.Wait(nativeFence, 1); +``` + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 +- [Wait(RHIFence*)](../../command-queue/wait.md) - RHIFence 重载版本 diff --git a/docs/api/rhi/d3d12/command-queue/wait.md b/docs/api/rhi/d3d12/command-queue/wait.md new file mode 100644 index 00000000..5c2a0661 --- /dev/null +++ b/docs/api/rhi/d3d12/command-queue/wait.md @@ -0,0 +1,37 @@ +# D3D12CommandQueue::Wait + +```cpp +void Wait(RHIFence* fence, uint64_t value) override; +``` + +阻塞命令队列，直到指定栅栏的完成值达到指定值。该方法用于 GPU 内部的同步操作。 + +**参数：** +- `fence` - 目标栅栏指针，不能为 `nullptr` +- `value` - 等待的信号值 + +**返回：** 无 + +**复杂度：** O(1) + +**使用场景：** +- 等待另一个命令队列的操作完成 +- 实现 GPU 流水线各阶段之间的同步 +- 多 GPU 节点间的同步 + +**注意：** 如果栅栏的当前值已经大于或等于指定值，则此方法立即返回。 + +## 示例 + +```cpp +D3D12Fence* fence; // 已发送信号的栅栏 +// 等待 fence 的值达到 1 +commandQueue.Wait(fence, 1); +``` + +## 相关文档 + +- [D3D12CommandQueue 总览](command-queue.md) - 返回类总览 +- [Signal](signal.md) - 向栅栏发送信号 +- [Wait(ID3D12Fence*)](wait-native.md) - Native D3D12Fence 版本 +- [D3D12Fence](../fence/fence.md) diff --git a/docs/api/rhi/d3d12/common/check-format-support.md b/docs/api/rhi/d3d12/common/check-format-support.md new file mode 100644 index 00000000..51be1f89 --- /dev/null +++ b/docs/api/rhi/d3d12/common/check-format-support.md @@ -0,0 +1,37 @@ +# D3D12Common::CheckFormatSupport + +```cpp +inline bool CheckFormatSupport( + ID3D12Device* device, + DXGI_FORMAT format, + D3D12_FORMAT_SUPPORT1 support1, + D3D12_FORMAT_SUPPORT2 support2 = D3D12_FORMAT_SUPPORT2_NONE +) +``` + +检查设备是否支持指定格式的特定功能。 + +**参数：** +- `device` - D3D12 设备指针 +- `format` - 要检查的 DXGI 格式 +- `support1` - 主格式支持标志（`D3D12_FORMAT_SUPPORT1`） +- `support2` - 扩展格式支持标志（`D3D12_FORMAT_SUPPORT2`），默认为 `D3D12_FORMAT_SUPPORT2_NONE` + +**返回：** 如果格式支持指定功能返回 `true`，否则返回 `false` + +**线程安全：** ✅（只读查询） + +**示例：** + +```cpp +ID3D12Device* device = ...; +if (CheckFormatSupport(device, DXGI_FORMAT_BC1_UNORM, D3D12_FORMAT_SUPPORT1_TEXTURE2D)) { + // 支持 BC1 压缩格式 +} +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [IsRenderTargetFormatSupported](is-render-target-format-supported.md) +- [IsTextureFormatSupported](is-texture-format-supported.md) diff --git a/docs/api/rhi/d3d12/common/common.md b/docs/api/rhi/d3d12/common/common.md index 0c94b9bf..e22700d6 100644 --- a/docs/api/rhi/d3d12/common/common.md +++ b/docs/api/rhi/d3d12/common/common.md @@ -2,7 +2,21 @@ **命名空间**: `XCEngine::RHI` -**描述**: D3D12 通用辅助函数集合，提供描述符大小、屏障创建、格式支持检查等功能。**所有函数均为 inline 函数**。 +**类型**: `inline 函数集合` (header-only) + +**描述**: D3D12 通用辅助函数集合，提供描述符大小查询、资源屏障创建、格式支持检查、视图创建等功能。所有函数均为 `inline` 函数，封装自 DirectX 12 原生 API。 + +## 概述 + +D3D12Common 是 D3D12 后端的工具函数模块，封装了 DirectX 12 常用的辅助功能，包括： + +- **描述符大小查询**: 封装 `ID3D12Device::GetDescriptorHandleIncrementSize`，提供各类描述符的增量大小 +- **资源屏障创建**: 封装 `D3D12_RESOURCE_BARRIER` 的三种类型（Transition、UAV、Aliasing） +- **格式支持检查**: 封装 `ID3D12Device::CheckFeatureSupport`，检查格式是否支持特定用途 +- **视图创建**: 封装 D3D12_VERTEX_BUFFER_VIEW、D3D12_INDEX_BUFFER_VIEW、D3D12_VIEWPORT 等创建 +- **描述符句柄运算**: 提供描述符句柄的偏移计算 + +这些函数均为无状态的纯函数，设计用于简化 D3D12 常见操作的代码编写。 ## 函数列表 @@ -10,58 +24,88 @@ | 函数 | 描述 | |------|------| -| `GetDescriptorHandleIncrementSize` | 获取描述符增量大小 | -| `GetRTVDescriptorSize` | 获取 RTV 描述符大小 | -| `GetDSVDescriptorSize` | 获取 DSV 描述符大小 | -| `GetCBV_SRV_UAVDescriptorSize` | 获取 CBV/SRV/UAV 描述符大小 | -| `GetSamplerDescriptorSize` | 获取 Sampler 描述符大小 | +| [`GetDescriptorHandleIncrementSize`](get-descriptor-handle-increment-size.md) | 获取指定描述符堆类型的增量大小 | +| [`GetRTVDescriptorSize`](get-rtv-descriptor-size.md) | 获取 RTV 描述符大小 | +| [`GetDSVDescriptorSize`](get-dsv-descriptor-size.md) | 获取 DSV 描述符大小 | +| [`GetCBV_SRV_UAVDescriptorSize`](get-cbv-srv-uav-descriptor-size.md) | 获取 CBV/SRV/UAV 描述符大小 | +| [`GetSamplerDescriptorSize`](get-sampler-descriptor-size.md) | 获取 Sampler 描述符大小 | ### 屏障创建 | 函数 | 描述 | |------|------| -| `CreateTransitionBarrier` | 创建资源状态转换屏障 | -| `CreateUAVBarrier` | 创建 UAV 屏障 | -| `CreateAliasingBarrier` | 创建别名化屏障 | +| [`CreateTransitionBarrier`](create-transition-barrier.md) | 创建资源状态转换屏障 | +| [`CreateUAVBarrier`](create-uav-barrier.md) | 创建 UAV 屏障 | +| [`CreateAliasingBarrier`](create-aliasing-barrier.md) | 创建别名化屏障 | ### 格式支持 | 函数 | 描述 | |------|------| -| `CheckFormatSupport` | 检查格式支持 | -| `IsRenderTargetFormatSupported` | 检查是否支持作为渲染目标 | -| `IsDepthStencilFormatSupported` | 检查是否支持作为深度模板 | -| `IsShaderResourceFormatSupported` | 检查 shader 是否可读取 | -| `IsTextureFormatSupported` | 检查是否支持作为纹理 | +| [`CheckFormatSupport`](check-format-support.md) | 检查格式是否支持指定功能 | +| [`IsRenderTargetFormatSupported`](is-render-target-format-supported.md) | 检查是否支持作为渲染目标 | +| [`IsDepthStencilFormatSupported`](is-depth-stencil-format-supported.md) | 检查是否支持作为深度模板 | +| [`IsShaderResourceFormatSupported`](is-shader-resource-format-supported.md) | 检查是否支持作为着色器资源 | +| [`IsTextureFormatSupported`](is-texture-format-supported.md) | 检查是否支持作为纹理 | ### 清除值创建 | 函数 | 描述 | |------|------| -| `CreateRenderTargetClearValue` | 创建渲染目标清除值 | -| `CreateDepthStencilClearValue` | 创建深度模板清除值 | +| [`CreateRenderTargetClearValue`](create-render-target-clear-value.md) | 创建渲染目标清除值 | +| [`CreateDepthStencilClearValue`](create-depth-stencil-clear-value.md) | 创建深度模板清除值 | ### 视口和裁剪矩形 | 函数 | 描述 | |------|------| -| `CreateViewport` | 创建视口 | -| `CreateScissorRect` | 创建裁剪矩形 | +| [`CreateViewport`](create-viewport.md) | 创建视口结构 | +| [`CreateScissorRect`](create-scissor-rect.md) | 创建裁剪矩形 | ### 缓冲区视图 | 函数 | 描述 | |------|------| -| `CreateVertexBufferView` | 创建顶点缓冲区视图 | -| `CreateIndexBufferView` | 创建索引缓冲区视图 | +| [`CreateVertexBufferView`](create-vertex-buffer-view.md) | 创建顶点缓冲区视图 | +| [`CreateIndexBufferView`](create-index-buffer-view.md) | 创建索引缓冲区视图 | ### 描述符句柄运算 | 函数 | 描述 | |------|------| -| `GetCPUDescriptorHandle` | 计算偏移后的 CPU 描述符句柄 | -| `GetGPUDescriptorHandle` | 计算偏移后的 GPU 描述符句柄 | +| [`GetCPUDescriptorHandle`](get-cpu-descriptor-handle.md) | 计算偏移后的 CPU 描述符句柄 | +| [`GetGPUDescriptorHandle`](get-gpu-descriptor-handle.md) | 计算偏移后的 GPU 描述符句柄 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::RHI; + +// 获取描述符大小 +ID3D12Device* device = ...; +UINT rtvSize = GetRTVDescriptorSize(device); + +// 创建资源屏障 +D3D12_RESOURCE_BARRIER barrier = CreateTransitionBarrier( + resource, + D3D12_RESOURCE_STATE_RENDER_TARGET, + D3D12_RESOURCE_STATE_COMMON +); + +// 检查格式支持 +if (IsTextureFormatSupported(device, DXGI_FORMAT_BC1_UNORM)) { + // 使用压缩纹理 +} + +// 创建视口 +D3D12_VIEWPORT viewport = CreateViewport(1280.0f, 720.0f); +``` ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端概览](../d3d12.md) - D3D12 模块总览 +- [RHI 模块总览](../../rhi.md) - RHI 抽象层 +- [D3D12Device](../device/device.md) - D3D12 设备 +- [D3D12DescriptorHeap](../descriptor-heap/descriptor-heap.md) - 描述符堆 diff --git a/docs/api/rhi/d3d12/common/create-aliasing-barrier.md b/docs/api/rhi/d3d12/common/create-aliasing-barrier.md new file mode 100644 index 00000000..f5e8b133 --- /dev/null +++ b/docs/api/rhi/d3d12/common/create-aliasing-barrier.md @@ -0,0 +1,32 @@ +# D3D12Common::CreateAliasingBarrier + +```cpp +inline D3D12_RESOURCE_BARRIER CreateAliasingBarrier( + ID3D12Resource* beforeResource = nullptr, + ID3D12Resource* afterResource = nullptr +) +``` + +创建资源别名化屏障，用于不同资源之间的切换。 + +**参数：** +- `beforeResource` - 别名前的资源，默认为 `nullptr` +- `afterResource` - 别名后的资源，默认为 `nullptr` + +**返回：** 配置好的 `D3D12_RESOURCE_BARRIER` 结构 + +**线程安全：** ✅（纯函数） + +**示例：** + +```cpp +ID3D12Resource* resourceA = ...; +ID3D12Resource* resourceB = ...; +D3D12_RESOURCE_BARRIER barrier = CreateAliasingBarrier(resourceA, resourceB); +cmdList->ResourceBarrier(1, &barrier); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [CreateTransitionBarrier](create-transition-barrier.md) diff --git a/docs/api/rhi/d3d12/common/create-depth-stencil-clear-value.md b/docs/api/rhi/d3d12/common/create-depth-stencil-clear-value.md new file mode 100644 index 00000000..c0c62a48 --- /dev/null +++ b/docs/api/rhi/d3d12/common/create-depth-stencil-clear-value.md @@ -0,0 +1,35 @@ +# D3D12Common::CreateDepthStencilClearValue + +```cpp +inline D3D12_CLEAR_VALUE CreateDepthStencilClearValue( + DXGI_FORMAT format, + float depth = 1.0f, + uint8_t stencil = 0 +) +``` + +创建深度模板缓冲区的清除值。 + +**参数：** +- `format` - 深度模板格式 +- `depth` - 深度值，默认为 1.0f +- `stencil` - 模板值，默认为 0 + +**返回：** 配置好的 `D3D12_CLEAR_VALUE` 结构 + +**线程安全：** ✅（纯函数） + +**示例：** + +```cpp +D3D12_CLEAR_VALUE clearValue = CreateDepthStencilClearValue( + DXGI_FORMAT_D24_UNORM_S8_UINT, + 1.0f, + 0 +); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [CreateRenderTargetClearValue](create-render-target-clear-value.md) diff --git a/docs/api/rhi/d3d12/common/create-index-buffer-view.md b/docs/api/rhi/d3d12/common/create-index-buffer-view.md new file mode 100644 index 00000000..2ff39b2b --- /dev/null +++ b/docs/api/rhi/d3d12/common/create-index-buffer-view.md @@ -0,0 +1,37 @@ +# D3D12Common::CreateIndexBufferView + +```cpp +inline D3D12_INDEX_BUFFER_VIEW CreateIndexBufferView( + D3D12_GPU_VIRTUAL_ADDRESS bufferLocation, + UINT sizeInBytes, + DXGI_FORMAT format +) +``` + +创建索引缓冲区视图。 + +**参数：** +- `bufferLocation` - 索引缓冲区 GPU 虚拟地址 +- `sizeInBytes` - 缓冲区大小（字节） +- `format` - 索引格式（DXGI_FORMAT_R16_UINT 或 DXGI_FORMAT_R32_UINT） + +**返回：** 配置好的 `D3D12_INDEX_BUFFER_VIEW` 结构 + +**线程安全：** ✅（纯函数） + +**示例：** + +```cpp +ID3D12Resource* indexBuffer = ...; +D3D12_INDEX_BUFFER_VIEW ibView = CreateIndexBufferView( + indexBuffer->GetGPUVirtualAddress(), + indexBufferSize, + DXGI_FORMAT_R16_UINT +); +cmdList->IASetIndexBuffer(&ibView); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [CreateVertexBufferView](create-vertex-buffer-view.md) diff --git a/docs/api/rhi/d3d12/common/create-render-target-clear-value.md b/docs/api/rhi/d3d12/common/create-render-target-clear-value.md new file mode 100644 index 00000000..a6c77f89 --- /dev/null +++ b/docs/api/rhi/d3d12/common/create-render-target-clear-value.md @@ -0,0 +1,38 @@ +# D3D12Common::CreateRenderTargetClearValue + +```cpp +inline D3D12_CLEAR_VALUE CreateRenderTargetClearValue( + DXGI_FORMAT format, + float r = 0.0f, + float g = 0.0f, + float b = 0.0f, + float a = 1.0f +) +``` + +创建渲染目标的清除值（清除颜色）。 + +**参数：** +- `format` - 渲染目标格式 +- `r` - 红色分量，默认为 0.0f +- `g` - 绿色分量，默认为 0.0f +- `b` - 蓝色分量，默认为 0.0f +- `a` - Alpha 分量，默认为 1.0f + +**返回：** 配置好的 `D3D12_CLEAR_VALUE` 结构 + +**线程安全：** ✅（纯函数） + +**示例：** + +```cpp +D3D12_CLEAR_VALUE clearValue = CreateRenderTargetClearValue( + DXGI_FORMAT_R8G8B8A8_UNORM, + 0.0f, 0.0f, 0.0f, 1.0f +); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [CreateDepthStencilClearValue](create-depth-stencil-clear-value.md) diff --git a/docs/api/rhi/d3d12/common/create-scissor-rect.md b/docs/api/rhi/d3d12/common/create-scissor-rect.md new file mode 100644 index 00000000..9ba637a7 --- /dev/null +++ b/docs/api/rhi/d3d12/common/create-scissor-rect.md @@ -0,0 +1,29 @@ +# D3D12Common::CreateScissorRect + +```cpp +inline D3D12_RECT CreateScissorRect(int left, int top, int right, int bottom) +``` + +创建裁剪矩形（剪刀矩形）。 + +**参数：** +- `left` - 矩形左边界 +- `top` - 矩形上边界 +- `right` - 矩形右边界 +- `bottom` - 矩形下边界 + +**返回：** 配置好的 `D3D12_RECT` 结构 + +**线程安全：** ✅（纯函数） + +**示例：** + +```cpp +D3D12_RECT scissorRect = CreateScissorRect(0, 0, 1280, 720); +cmdList->RSSetScissorRects(1, &scissorRect); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [CreateViewport](create-viewport.md) diff --git a/docs/api/rhi/d3d12/common/create-transition-barrier.md b/docs/api/rhi/d3d12/common/create-transition-barrier.md new file mode 100644 index 00000000..65190070 --- /dev/null +++ b/docs/api/rhi/d3d12/common/create-transition-barrier.md @@ -0,0 +1,39 @@ +# D3D12Common::CreateTransitionBarrier + +```cpp +inline D3D12_RESOURCE_BARRIER CreateTransitionBarrier( + ID3D12Resource* resource, + D3D12_RESOURCE_STATES stateBefore, + D3D12_RESOURCE_STATES stateAfter, + UINT subresource = D3D12_RESOURCE_BARRIER_ALL_SUBRESOURCES +) +``` + +创建资源状态转换屏障，用于同步资源状态转换。 + +**参数：** +- `resource` - 目标资源指针 +- `stateBefore` - 转换前的资源状态 +- `stateAfter` - 转换后的资源状态 +- `subresource` - 子资源索引，默认为所有子资源 + +**返回：** 配置好的 `D3D12_RESOURCE_BARRIER` 结构 + +**线程安全：** ✅（纯函数） + +**示例：** + +```cpp +ID3D12Resource* texture = ...; +D3D12_RESOURCE_BARRIER barrier = CreateTransitionBarrier( + texture, + D3D12_RESOURCE_STATE_RENDER_TARGET, + D3D12_RESOURCE_STATE_COMMON +); +cmdList->ResourceBarrier(1, &barrier); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [D3D12CommandList](../command-list/command-list.md) diff --git a/docs/api/rhi/d3d12/common/create-uav-barrier.md b/docs/api/rhi/d3d12/common/create-uav-barrier.md new file mode 100644 index 00000000..0fc33515 --- /dev/null +++ b/docs/api/rhi/d3d12/common/create-uav-barrier.md @@ -0,0 +1,27 @@ +# D3D12Common::CreateUAVBarrier + +```cpp +inline D3D12_RESOURCE_BARRIER CreateUAVBarrier(ID3D12Resource* resource = nullptr) +``` + +创建无序访问视图（UAV）屏障，用于同步 UAV 访问。 + +**参数：** +- `resource` - UAV 资源指针，默认为 `nullptr`（全局 UAV 屏障） + +**返回：** 配置好的 `D3D12_RESOURCE_BARRIER` 结构 + +**线程安全：** ✅（纯函数） + +**示例：** + +```cpp +ID3D12Resource* uavResource = ...; +D3D12_RESOURCE_BARRIER barrier = CreateUAVBarrier(uavResource); +cmdList->ResourceBarrier(1, &barrier); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [CreateTransitionBarrier](create-transition-barrier.md) diff --git a/docs/api/rhi/d3d12/common/create-vertex-buffer-view.md b/docs/api/rhi/d3d12/common/create-vertex-buffer-view.md new file mode 100644 index 00000000..aa89488e --- /dev/null +++ b/docs/api/rhi/d3d12/common/create-vertex-buffer-view.md @@ -0,0 +1,37 @@ +# D3D12Common::CreateVertexBufferView + +```cpp +inline D3D12_VERTEX_BUFFER_VIEW CreateVertexBufferView( + D3D12_GPU_VIRTUAL_ADDRESS bufferLocation, + UINT sizeInBytes, + UINT strideInBytes +) +``` + +创建顶点缓冲区视图。 + +**参数：** +- `bufferLocation` - 顶点缓冲区 GPU 虚拟地址 +- `sizeInBytes` - 缓冲区大小（字节） +- `strideInBytes` - 单个顶点的大小（字节） + +**返回：** 配置好的 `D3D12_VERTEX_BUFFER_VIEW` 结构 + +**线程安全：** ✅（纯函数） + +**示例：** + +```cpp +ID3D12Resource* vertexBuffer = ...; +D3D12_VERTEX_BUFFER_VIEW vbView = CreateVertexBufferView( + vertexBuffer->GetGPUVirtualAddress(), + vertexBufferSize, + sizeof(Vertex) +); +cmdList->IASetVertexBuffers(0, 1, &vbView); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [CreateIndexBufferView](create-index-buffer-view.md) diff --git a/docs/api/rhi/d3d12/common/create-viewport.md b/docs/api/rhi/d3d12/common/create-viewport.md new file mode 100644 index 00000000..c5a9a06b --- /dev/null +++ b/docs/api/rhi/d3d12/common/create-viewport.md @@ -0,0 +1,38 @@ +# D3D12Common::CreateViewport + +```cpp +inline D3D12_VIEWPORT CreateViewport( + float width, + float height, + float topLeftX = 0.0f, + float topLeftY = 0.0f, + float minDepth = 0.0f, + float maxDepth = 1.0f +) +``` + +创建 D3D12 视口结构。 + +**参数：** +- `width` - 视口宽度（像素） +- `height` - 视口高度（像素） +- `topLeftX` - 视口左上角 X 坐标，默认为 0 +- `topLeftY` - 视口左上角 Y 坐标，默认为 0 +- `minDepth` - 最小深度值，默认为 0 +- `maxDepth` - 最大深度值，默认为 1 + +**返回：** 配置好的 `D3D12_VIEWPORT` 结构 + +**线程安全：** ✅（纯函数） + +**示例：** + +```cpp +D3D12_VIEWPORT viewport = CreateViewport(1280.0f, 720.0f, 0.0f, 0.0f, 0.0f, 1.0f); +cmdList->RSSetViewports(1, &viewport); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [CreateScissorRect](create-scissor-rect.md) diff --git a/docs/api/rhi/d3d12/common/get-cbv-srv-uav-descriptor-size.md b/docs/api/rhi/d3d12/common/get-cbv-srv-uav-descriptor-size.md new file mode 100644 index 00000000..e33b3947 --- /dev/null +++ b/docs/api/rhi/d3d12/common/get-cbv-srv-uav-descriptor-size.md @@ -0,0 +1,26 @@ +# D3D12Common::GetCBV_SRV_UAVDescriptorSize + +```cpp +inline UINT GetCBV_SRV_UAVDescriptorSize(ID3D12Device* device) +``` + +获取常量缓冲区视图（CBV）、着色器资源视图（SRV）和无序访问视图（UAV）的描述符大小。 + +**参数：** +- `device` - D3D12 设备指针 + +**返回：** CBV/SRV/UAV 描述符大小（字节） + +**线程安全：** ✅（只读操作） + +**示例：** + +```cpp +ID3D12Device* device = ...; +UINT descriptorSize = GetCBV_SRV_UAVDescriptorSize(device); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [GetSamplerDescriptorSize](get-sampler-descriptor-size.md) diff --git a/docs/api/rhi/d3d12/common/get-cpu-descriptor-handle.md b/docs/api/rhi/d3d12/common/get-cpu-descriptor-handle.md new file mode 100644 index 00000000..641035a8 --- /dev/null +++ b/docs/api/rhi/d3d12/common/get-cpu-descriptor-handle.md @@ -0,0 +1,35 @@ +# D3D12Common::GetCPUDescriptorHandle + +```cpp +inline D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle( + D3D12_CPU_DESCRIPTOR_HANDLE baseHandle, + UINT offsetInDescriptors, + UINT descriptorSize +) +``` + +计算偏移后的 CPU 描述符句柄。 + +**参数：** +- `baseHandle` - 基础描述符句柄 +- `offsetInDescriptors` - 描述符偏移数量 +- `descriptorSize` - 单个描述符大小（字节） + +**返回：** 偏移后的 CPU 描述符句柄 + +**线程安全：** ✅（纯函数） + +**示例：** + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE rtvHandle = GetCPUDescriptorHandle( + heapStartHandle, + 2, // 第3个描述符 + rtvDescriptorSize +); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [GetGPUDescriptorHandle](get-gpu-descriptor-handle.md) diff --git a/docs/api/rhi/d3d12/common/get-descriptor-handle-increment-size.md b/docs/api/rhi/d3d12/common/get-descriptor-handle-increment-size.md new file mode 100644 index 00000000..b62ba827 --- /dev/null +++ b/docs/api/rhi/d3d12/common/get-descriptor-handle-increment-size.md @@ -0,0 +1,28 @@ +# D3D12Common::GetDescriptorHandleIncrementSize + +```cpp +inline UINT GetDescriptorHandleIncrementSize(ID3D12Device* device, D3D12_DESCRIPTOR_HEAP_TYPE heapType) +``` + +获取指定描述符堆类型的描述符增量大小（增量偏移值）。 + +**参数：** +- `device` - D3D12 设备指针 +- `heapType` - 描述符堆类型（`D3D12_DESCRIPTOR_HEAP_TYPE`） + +**返回：** 指定类型的描述符增量大小（字节） + +**线程安全：** ✅（只读操作） + +**示例：** + +```cpp +ID3D12Device* device = ...; +UINT rtvIncSize = GetDescriptorHandleIncrementSize(device, D3D12_DESCRIPTOR_HEAP_TYPE_RTV); +UINT srvIncSize = GetDescriptorHandleIncrementSize(device, D3D12_DESCRIPTOR_HEAP_TYPE_CBV_SRV_UAV); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [D3D12DescriptorHeap](../descriptor-heap/descriptor-heap.md) diff --git a/docs/api/rhi/d3d12/common/get-dsv-descriptor-size.md b/docs/api/rhi/d3d12/common/get-dsv-descriptor-size.md new file mode 100644 index 00000000..ec1f74ac --- /dev/null +++ b/docs/api/rhi/d3d12/common/get-dsv-descriptor-size.md @@ -0,0 +1,26 @@ +# D3D12Common::GetDSVDescriptorSize + +```cpp +inline UINT GetDSVDescriptorSize(ID3D12Device* device) +``` + +获取深度模板视图（DSV）的描述符大小。 + +**参数：** +- `device` - D3D12 设备指针 + +**返回：** DSV 描述符大小（字节） + +**线程安全：** ✅（只读操作） + +**示例：** + +```cpp +ID3D12Device* device = ...; +UINT dsvSize = GetDSVDescriptorSize(device); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [GetRTVDescriptorSize](get-rtv-descriptor-size.md) diff --git a/docs/api/rhi/d3d12/common/get-gpu-descriptor-handle.md b/docs/api/rhi/d3d12/common/get-gpu-descriptor-handle.md new file mode 100644 index 00000000..379367bf --- /dev/null +++ b/docs/api/rhi/d3d12/common/get-gpu-descriptor-handle.md @@ -0,0 +1,35 @@ +# D3D12Common::GetGPUDescriptorHandle + +```cpp +inline D3D12_GPU_DESCRIPTOR_HANDLE GetGPUDescriptorHandle( + D3D12_GPU_DESCRIPTOR_HANDLE baseHandle, + UINT offsetInDescriptors, + UINT descriptorSize +) +``` + +计算偏移后的 GPU 描述符句柄。 + +**参数：** +- `baseHandle` - 基础描述符句柄 +- `offsetInDescriptors` - 描述符偏移数量 +- `descriptorSize` - 单个描述符大小（字节） + +**返回：** 偏移后的 GPU 描述符句柄 + +**线程安全：** ✅（纯函数） + +**示例：** + +```cpp +D3D12_GPU_DESCRIPTOR_HANDLE srvHandle = GetGPUDescriptorHandle( + heapStartHandle, + 5, // 第6个描述符 + srvDescriptorSize +); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [GetCPUDescriptorHandle](get-cpu-descriptor-handle.md) diff --git a/docs/api/rhi/d3d12/common/get-rtv-descriptor-size.md b/docs/api/rhi/d3d12/common/get-rtv-descriptor-size.md new file mode 100644 index 00000000..2e41dd5d --- /dev/null +++ b/docs/api/rhi/d3d12/common/get-rtv-descriptor-size.md @@ -0,0 +1,27 @@ +# D3D12Common::GetRTVDescriptorSize + +```cpp +inline UINT GetRTVDescriptorSize(ID3D12Device* device) +``` + +获取渲染目标视图（RTV）的描述符大小。 + +**参数：** +- `device` - D3D12 设备指针 + +**返回：** RTV 描述符大小（字节） + +**线程安全：** ✅（只读操作） + +**示例：** + +```cpp +ID3D12Device* device = ...; +UINT rtvSize = GetRTVDescriptorSize(device); +D3D12_CPU_DESCRIPTOR_HANDLE rtvHandle = GetCPUDescriptorHandle(baseHandle, 0, rtvSize); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [D3D12RenderTargetView](../render-target-view/render-target-view.md) diff --git a/docs/api/rhi/d3d12/common/get-sampler-descriptor-size.md b/docs/api/rhi/d3d12/common/get-sampler-descriptor-size.md new file mode 100644 index 00000000..c2e94f3f --- /dev/null +++ b/docs/api/rhi/d3d12/common/get-sampler-descriptor-size.md @@ -0,0 +1,26 @@ +# D3D12Common::GetSamplerDescriptorSize + +```cpp +inline UINT GetSamplerDescriptorSize(ID3D12Device* device) +``` + +获取采样器（Sampler）的描述符大小。 + +**参数：** +- `device` - D3D12 设备指针 + +**返回：** Sampler 描述符大小（字节） + +**线程安全：** ✅（只读操作） + +**示例：** + +```cpp +ID3D12Device* device = ...; +UINT samplerSize = GetSamplerDescriptorSize(device); +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [GetCBV_SRV_UAVDescriptorSize](get-cbv-srv-uav-descriptor-size.md) diff --git a/docs/api/rhi/d3d12/common/is-depth-stencil-format-supported.md b/docs/api/rhi/d3d12/common/is-depth-stencil-format-supported.md new file mode 100644 index 00000000..59e6b682 --- /dev/null +++ b/docs/api/rhi/d3d12/common/is-depth-stencil-format-supported.md @@ -0,0 +1,29 @@ +# D3D12Common::IsDepthStencilFormatSupported + +```cpp +inline bool IsDepthStencilFormatSupported(ID3D12Device* device, DXGI_FORMAT format) +``` + +检查指定格式是否支持作为深度模板缓冲区。 + +**参数：** +- `device` - D3D12 设备指针 +- `format` - 要检查的 DXGI 格式 + +**返回：** 如果格式支持作为深度模板返回 `true` + +**线程安全：** ✅（只读查询） + +**示例：** + +```cpp +ID3D12Device* device = ...; +if (IsDepthStencilFormatSupported(device, DXGI_FORMAT_D24_UNORM_S8_UINT)) { + // 可以使用该格式作为深度模板 +} +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [CheckFormatSupport](check-format-support.md) diff --git a/docs/api/rhi/d3d12/common/is-render-target-format-supported.md b/docs/api/rhi/d3d12/common/is-render-target-format-supported.md new file mode 100644 index 00000000..6587b63a --- /dev/null +++ b/docs/api/rhi/d3d12/common/is-render-target-format-supported.md @@ -0,0 +1,29 @@ +# D3D12Common::IsRenderTargetFormatSupported + +```cpp +inline bool IsRenderTargetFormatSupported(ID3D12Device* device, DXGI_FORMAT format) +``` + +检查指定格式是否支持作为渲染目标。 + +**参数：** +- `device` - D3D12 设备指针 +- `format` - 要检查的 DXGI 格式 + +**返回：** 如果格式支持作为渲染目标返回 `true` + +**线程安全：** ✅（只读查询） + +**示例：** + +```cpp +ID3D12Device* device = ...; +if (IsRenderTargetFormatSupported(device, DXGI_FORMAT_R8G8B8A8_UNORM)) { + // 可以使用该格式作为渲染目标 +} +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [CheckFormatSupport](check-format-support.md) diff --git a/docs/api/rhi/d3d12/common/is-shader-resource-format-supported.md b/docs/api/rhi/d3d12/common/is-shader-resource-format-supported.md new file mode 100644 index 00000000..b2123e72 --- /dev/null +++ b/docs/api/rhi/d3d12/common/is-shader-resource-format-supported.md @@ -0,0 +1,29 @@ +# D3D12Common::IsShaderResourceFormatSupported + +```cpp +inline bool IsShaderResourceFormatSupported(ID3D12Device* device, DXGI_FORMAT format) +``` + +检查指定格式是否支持作为着色器资源。 + +**参数：** +- `device` - D3D12 设备指针 +- `format` - 要检查的 DXGI 格式 + +**返回：** 如果格式支持作为着色器资源返回 `true` + +**线程安全：** ✅（只读查询） + +**示例：** + +```cpp +ID3D12Device* device = ...; +if (IsShaderResourceFormatSupported(device, DXGI_FORMAT_R32G32B32_FLOAT)) { + // 可以在着色器中读取该格式 +} +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [CheckFormatSupport](check-format-support.md) diff --git a/docs/api/rhi/d3d12/common/is-texture-format-supported.md b/docs/api/rhi/d3d12/common/is-texture-format-supported.md new file mode 100644 index 00000000..384fe366 --- /dev/null +++ b/docs/api/rhi/d3d12/common/is-texture-format-supported.md @@ -0,0 +1,29 @@ +# D3D12Common::IsTextureFormatSupported + +```cpp +inline bool IsTextureFormatSupported(ID3D12Device* device, DXGI_FORMAT format) +``` + +检查指定格式是否支持作为纹理。 + +**参数：** +- `device` - D3D12 设备指针 +- `format` - 要检查的 DXGI 格式 + +**返回：** 如果格式支持作为纹理返回 `true` + +**线程安全：** ✅（只读查询） + +**示例：** + +```cpp +ID3D12Device* device = ...; +if (IsTextureFormatSupported(device, DXGI_FORMAT_BC1_UNORM)) { + // 可以创建该格式的纹理 +} +``` + +## 相关文档 + +- [D3D12Common 总览](common.md) +- [CheckFormatSupport](check-format-support.md) diff --git a/docs/api/rhi/d3d12/constant-buffer-view/constant-buffer-view.md b/docs/api/rhi/d3d12/constant-buffer-view/constant-buffer-view.md index f59eb66b..814c65b1 100644 --- a/docs/api/rhi/d3d12/constant-buffer-view/constant-buffer-view.md +++ b/docs/api/rhi/d3d12/constant-buffer-view/constant-buffer-view.md @@ -2,16 +2,36 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 常量缓冲区视图的 D3D12 实现。 +**类型**: 类 + +**描述**: DirectX 12 常量缓冲区视图的 D3D12 实现，提供与 D3D12 API 的直接交互接口。 + +**概述**: `D3D12ConstantBufferView` 是对 D3D12 常量缓冲区视图（Constant Buffer View）的封装类。它管理一个 CPU 可见的描述符句柄，用于在渲染命令中绑定常量缓冲区。内部持有对 D3D12 资源的引用，资源生命周期由外部管理。 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化常量缓冲区视图 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭常量缓冲区视图 | +| [`D3D12ConstantBufferView`](constructor.md) | 构造函数 | +| [`~D3D12ConstantBufferView`](destructor.md) | 析构函数 | +| [`Initialize`](initialize.md) | 初始化常量缓冲区视图 | +| [`Shutdown`](shutdown.md) | 关闭常量缓冲区视图 | | [`GetCPUDescriptorHandle`](get-cpu-descriptor-handle.md) | 获取 CPU 描述符句柄 | +## 使用示例 + +```cpp +ID3D12Device* device; +ID3D12Resource* buffer; + +XCEngine::RHI::D3D12ConstantBufferView cbv; +cbv.Initialize(device, buffer); + +// 使用 cbv.GetCPUDescriptorHandle() 绑定到命令列表 + +cbv.Shutdown(); +``` + ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../d3d12.md) diff --git a/docs/api/rhi/d3d12/constant-buffer-view/constructor.md b/docs/api/rhi/d3d12/constant-buffer-view/constructor.md new file mode 100644 index 00000000..9157f4da --- /dev/null +++ b/docs/api/rhi/d3d12/constant-buffer-view/constructor.md @@ -0,0 +1,16 @@ +# D3D12ConstantBufferView::D3D12ConstantBufferView + +```cpp +D3D12ConstantBufferView(); +``` + +构造一个空的 D3D12ConstantBufferView 实例。 + +## 复杂度 + +O(1) + +## 相关文档 + +- [D3D12ConstantBufferView 总览](constant-buffer-view.md) +- [~D3D12ConstantBufferView](destructor.md) diff --git a/docs/api/rhi/d3d12/constant-buffer-view/destructor.md b/docs/api/rhi/d3d12/constant-buffer-view/destructor.md new file mode 100644 index 00000000..d1a319df --- /dev/null +++ b/docs/api/rhi/d3d12/constant-buffer-view/destructor.md @@ -0,0 +1,16 @@ +# D3D12ConstantBufferView::~D3D12ConstantBufferView + +```cpp +~D3D12ConstantBufferView(); +``` + +析构函数，自动调用 Shutdown 清理资源。 + +## 复杂度 + +O(1) + +## 相关文档 + +- [D3D12ConstantBufferView 总览](constant-buffer-view.md) +- [D3D12ConstantBufferView](constructor.md) diff --git a/docs/api/rhi/d3d12/constant-buffer-view/get-cpu-descriptor-handle.md b/docs/api/rhi/d3d12/constant-buffer-view/get-cpu-descriptor-handle.md index c4202e6e..f1c0c65d 100644 --- a/docs/api/rhi/d3d12/constant-buffer-view/get-cpu-descriptor-handle.md +++ b/docs/api/rhi/d3d12/constant-buffer-view/get-cpu-descriptor-handle.md @@ -1,15 +1,21 @@ # D3D12ConstantBufferView::GetCPUDescriptorHandle ```cpp -D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const { return m_handle; } +D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const; ``` -获取 CPU 描述符句柄。 +获取 CPU 描述符句柄，用于绑定到命令列表。 -**返回：** CPU 描述符句柄 +## 返回值 -**复杂度：** O(1) +| 类型 | 描述 | +|------|------| +| `D3D12_CPU_DESCRIPTOR_HANDLE` | CPU 侧描述符句柄，可用于设置命令列表 | + +## 复杂度 + +O(1) ## 相关文档 -- [D3D12ConstantBufferView 总览](constant-buffer-view.md) - 返回类总览 +- [D3D12ConstantBufferView 总览](constant-buffer-view.md) diff --git a/docs/api/rhi/d3d12/constant-buffer-view/initialize.md b/docs/api/rhi/d3d12/constant-buffer-view/initialize.md new file mode 100644 index 00000000..656e680f --- /dev/null +++ b/docs/api/rhi/d3d12/constant-buffer-view/initialize.md @@ -0,0 +1,26 @@ +# D3D12ConstantBufferView::Initialize + +```cpp +void Initialize(ID3D12Device* device, ID3D12Resource* buffer, const D3D12_CONSTANT_BUFFER_VIEW_DESC* desc = nullptr); +``` + +初始化常量缓冲区视图。 + +当 `desc` 参数为 `nullptr` 时，方法会自动根据 `buffer` 的属性创建视图描述：设置 `BufferLocation` 为缓冲区的 GPU 虚拟地址，`SizeInBytes` 为缓冲区的宽度。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `buffer` | `ID3D12Resource*` | D3D12 资源指针，必须是常量缓冲区 | +| `desc` | `const D3D12_CONSTANT_BUFFER_VIEW_DESC*` | 可选的视图描述，如果为 `nullptr` 则自动创建 | + +## 复杂度 + +O(1) + +## 相关文档 + +- [D3D12ConstantBufferView 总览](constant-buffer-view.md) +- [Shutdown](shutdown.md) diff --git a/docs/api/rhi/d3d12/constant-buffer-view/shutdown.md b/docs/api/rhi/d3d12/constant-buffer-view/shutdown.md new file mode 100644 index 00000000..d1c02b22 --- /dev/null +++ b/docs/api/rhi/d3d12/constant-buffer-view/shutdown.md @@ -0,0 +1,16 @@ +# D3D12ConstantBufferView::Shutdown + +```cpp +void Shutdown(); +``` + +关闭常量缓冲区视图，重置内部状态。此方法仅重置描述符句柄和资源指针，**不会**释放底层 D3D12 资源，资源生命周期由外部管理。 + +## 复杂度 + +O(1) + +## 相关文档 + +- [D3D12ConstantBufferView 总览](constant-buffer-view.md) +- [Initialize](initialize.md) diff --git a/docs/api/rhi/d3d12/depth-stencil-view/create-desc.md b/docs/api/rhi/d3d12/depth-stencil-view/create-desc.md index 5f36d14e..cae4c0a9 100644 --- a/docs/api/rhi/d3d12/depth-stencil-view/create-desc.md +++ b/docs/api/rhi/d3d12/depth-stencil-view/create-desc.md @@ -7,13 +7,21 @@ static D3D12_DEPTH_STENCIL_VIEW_DESC CreateDesc(Format format, D3D12_DSV_DIMENSI 创建深度模板视图描述（静态方法）。 **参数：** -- `format` - 格式 -- `dimension` - 视图维度 +- `format` - 深度模板格式（如 `Format::D32_FLOAT`） +- `dimension` - 视图维度，默认为 `D3D12_DSV_DIMENSION_TEXTURE2D` **返回：** D3D12 深度模板视图描述 **复杂度：** O(1) +## 示例 + +```cpp +auto desc = D3D12DepthStencilView::CreateDesc(Format::D32_FLOAT, D3D12_DSV_DIMENSION_TEXTURE2D); +dsv.Initialize(device, depthBuffer, &desc); +``` + ## 相关文档 -- [D3D12DepthStencilView 总览](depth-stencil-view.md) - 返回类总览 +- [D3D12DepthStencilView 总览](depth-stencil-view.md) - 类总览 +- [Initialize](initialize.md) - 初始化方法 diff --git a/docs/api/rhi/d3d12/depth-stencil-view/depth-stencil-view.md b/docs/api/rhi/d3d12/depth-stencil-view/depth-stencil-view.md index e528ab16..649cce9c 100644 --- a/docs/api/rhi/d3d12/depth-stencil-view/depth-stencil-view.md +++ b/docs/api/rhi/d3d12/depth-stencil-view/depth-stencil-view.md @@ -2,18 +2,43 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 深度模板视图的 D3D12 实现。 +**类型**: `class` + +**描述**: DirectX 12 深度模板视图的 D3D12 实现，用于渲染管线中的深度/模板测试。 + +## 概述 + +`D3D12DepthStencilView` 是 RHI 深度模板视图接口的 D3D12 特定实现。该类封装了 D3D12 深度模板视图（DSV）的创建和管理，提供两种初始化方式：自动分配描述符句柄或使用预分配的描述符句柄。深度模板视图是渲染管线中用于深度测试和模板测试的关键资源。 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化深度模板视图 | -| [`InitializeAt`](initialize-at.md) | 在指定位置初始化 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭深度模板视图 | +| [`D3D12DepthStencilView()`](initialize.md) | 构造函数 | +| [`~D3D12DepthStencilView()`](initialize.md) | 析构函数 | +| [`Initialize`](initialize.md) | 初始化深度模板视图 | +| [`InitializeAt`](initialize-at.md) | 在指定位置初始化深度模板视图 | +| [`Shutdown`](shutdown.md) | 关闭深度模板视图 | | [`GetCPUDescriptorHandle`](get-cpu-descriptor-handle.md) | 获取 CPU 描述符句柄 | -| [`CreateDesc`](create-desc.md) | 创建描述符（静态） | +| [`CreateDesc`](create-desc.md) | 创建描述符（静态方法） | + +## 使用示例 + +```cpp +ID3D12Device* device; // 已初始化的 D3D12 设备 +ID3D12Resource* depthBuffer; // 深度缓冲资源 + +D3D12DepthStencilView dsv; +dsv.Initialize(device, depthBuffer, nullptr); + +D3D12_CPU_DESCRIPTOR_HANDLE handle = dsv.GetCPUDescriptorHandle(); +// 使用 handle 进行渲染操作 + +dsv.Shutdown(); +``` ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端概览](../d3d12.md) - D3D12 后端模块总览 +- [D3D12DescriptorHeap](../descriptor-heap/descriptor-heap.md) - 描述符堆管理 +- [D3D12RenderTargetView](../render-target-view/render-target-view.md) - 渲染目标视图 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/depth-stencil-view/get-cpu-descriptor-handle.md b/docs/api/rhi/d3d12/depth-stencil-view/get-cpu-descriptor-handle.md index a956320a..6e656204 100644 --- a/docs/api/rhi/d3d12/depth-stencil-view/get-cpu-descriptor-handle.md +++ b/docs/api/rhi/d3d12/depth-stencil-view/get-cpu-descriptor-handle.md @@ -1,15 +1,29 @@ # D3D12DepthStencilView::GetCPUDescriptorHandle ```cpp -D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const { return m_handle; } +D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const; ``` -获取 CPU 描述符句柄。 +获取深度模板视图的 CPU 描述符句柄，用于绑定到渲染管线。 **返回：** CPU 描述符句柄 **复杂度：** O(1) +## 说明 + +返回的描述符句柄用于将深度模板视图绑定到渲染管线的 OM（输出合并）阶段。此方法是 const 的，因为描述符句柄本身不修改对象状态。 + +## 示例 + +```cpp +D3D12DepthStencilView dsv; +dsv.Initialize(device, depthBuffer, nullptr); + +D3D12_CPU_DESCRIPTOR_HANDLE handle = dsv.GetCPUDescriptorHandle(); +// 使用 handle 绑定到 OM 阶段 +``` + ## 相关文档 - [D3D12DepthStencilView 总览](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/depth-stencil-view/initialize-at.md b/docs/api/rhi/d3d12/depth-stencil-view/initialize-at.md index 0ed47b9a..7b0b06b9 100644 --- a/docs/api/rhi/d3d12/depth-stencil-view/initialize-at.md +++ b/docs/api/rhi/d3d12/depth-stencil-view/initialize-at.md @@ -4,16 +4,30 @@ void InitializeAt(ID3D12Device* device, ID3D12Resource* resource, D3D12_CPU_DESCRIPTOR_HANDLE handle, const D3D12_DEPTH_STENCIL_VIEW_DESC* desc = nullptr); ``` -在指定位置初始化深度模板视图。 +在指定位置初始化深度模板视图，允许使用预分配的描述符句柄。 **参数：** -- `device` - D3D12 设备 -- `resource` - D3D12 资源 -- `handle` - CPU 描述符句柄 -- `desc` - 深度模板视图描述 +- `device` - D3D12 设备指针 +- `resource` - D3D12 资源指针（深度缓冲纹理） +- `handle` - 预分配的 CPU 描述符句柄位置 +- `desc` - 深度模板视图描述符，可选，默认为 nullptr + +**返回：** 无 **复杂度：** O(1) +## 说明 + +此方法与 `Initialize` 的区别在于使用预分配的描述符句柄位置，适用于描述符堆管理场景。当需要将深度模板视图绑定到特定的描述符位置时使用此方法。 + +## 示例 + +```cpp +D3D12DepthStencilView dsv; +D3D12_CPU_DESCRIPTOR_HANDLE handle = GetPreallocatedHandle(); // 预分配的句柄 +dsv.InitializeAt(device, depthBuffer, handle, nullptr); +``` + ## 相关文档 - [D3D12DepthStencilView 总览](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/d3d12/depth-stencil-view/initialize.md b/docs/api/rhi/d3d12/depth-stencil-view/initialize.md new file mode 100644 index 00000000..203f5c00 --- /dev/null +++ b/docs/api/rhi/d3d12/depth-stencil-view/initialize.md @@ -0,0 +1,36 @@ +# D3D12DepthStencilView::Initialize + +```cpp +void Initialize(ID3D12Device* device, ID3D12Resource* resource, const D3D12_DEPTH_STENCIL_VIEW_DESC* desc = nullptr); +``` + +初始化深度模板视图，使用设备自动分配描述符句柄。 + +**参数：** +- `device` - D3D12 设备指针 +- `resource` - D3D12 资源指针（深度缓冲纹理） +- `desc` - 深度模板视图描述符，可选，默认为 nullptr + +**返回：** 无 + +**复杂度：** O(1) + +## 说明 + +此方法使用 `ID3D12Device::CreateDepthStencilView` 创建深度模板视图，描述符句柄由设备自动分配。适用于创建独立的深度模板视图。 + +## 示例 + +```cpp +D3D12DepthStencilView dsv; +dsv.Initialize(device, depthBuffer, nullptr); + +// 获取描述符句柄用于渲染 +D3D12_CPU_DESCRIPTOR_HANDLE handle = dsv.GetCPUDescriptorHandle(); +``` + +## 相关文档 + +- [D3D12DepthStencilView 总览](depth-stencil-view.md) - 类总览 +- [InitializeAt](initialize-at.md) - 在指定位置初始化 +- [D3D12Device](../../device/device.md) - D3D12 设备 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/depth-stencil-view/shutdown.md b/docs/api/rhi/d3d12/depth-stencil-view/shutdown.md new file mode 100644 index 00000000..dd51f88a --- /dev/null +++ b/docs/api/rhi/d3d12/depth-stencil-view/shutdown.md @@ -0,0 +1,31 @@ +# D3D12DepthStencilView::Shutdown + +```cpp +void Shutdown(); +``` + +关闭深度模板视图，释放关联的资源引用。 + +**返回：** 无 + +**复杂度：** O(1) + +## 说明 + +此方法重置内部描述符句柄和资源指针，但不会释放描述符堆本身。调用后，视图对象处于未初始化状态，可以重新调用 `Initialize` 或 `InitializeAt` 进行初始化。 + +## 示例 + +```cpp +D3D12DepthStencilView dsv; +dsv.Initialize(device, depthBuffer, nullptr); + +// 使用视图... +dsv.Shutdown(); +``` + +## 相关文档 + +- [D3D12DepthStencilView 总览](depth-stencil-view.md) - 类总览 +- [Initialize](initialize.md) - 初始化视图 +- [InitializeAt](initialize-at.md) - 在指定位置初始化 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/descriptor-heap/constructor.md b/docs/api/rhi/d3d12/descriptor-heap/constructor.md new file mode 100644 index 00000000..2cf55542 --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/constructor.md @@ -0,0 +1,18 @@ +# D3D12DescriptorHeap::D3D12DescriptorHeap + +```cpp +D3D12DescriptorHeap(); +``` + +默认构造函数。创建空的描述符堆对象，所有成员变量初始化为默认值： +- `m_type` 初始化为 `CBV_SRV_UAV` +- `m_numDescriptors` 初始化为 0 +- `m_descriptorSize` 初始化为 0 +- `m_shaderVisible` 初始化为 false + +构造的对象需要调用 `Initialize` 方法进行实际初始化。 + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 +- [Initialize](initialize-from-desc.md) - 初始化方法 diff --git a/docs/api/rhi/d3d12/descriptor-heap/descriptor-heap.md b/docs/api/rhi/d3d12/descriptor-heap/descriptor-heap.md index d17ea0f5..ffadc812 100644 --- a/docs/api/rhi/d3d12/descriptor-heap/descriptor-heap.md +++ b/docs/api/rhi/d3d12/descriptor-heap/descriptor-heap.md @@ -2,26 +2,61 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 描述符堆的 D3D12 实现，继承自 `RHIDescriptorPool`。 +**继承自**: [`RHIDescriptorPool`](../../descriptor-pool/descriptor-pool.md) + +**描述**: DirectX 12 描述符堆的 D3D12 实现，继承自 `RHIDescriptorPool`。描述符堆是 D3D12 中用于存储描述符（CBV/SRV/UAV/Sampler）的内存块，支持 CPU 可访问和 GPU 可访问两种模式。 + +**概述**: + +`D3D12DescriptorHeap` 封装了 D3D12 的描述符堆资源，提供描述符的分配、句柄计算和资源管理功能。描述符堆类型包括： +- `CBV_SRV_UAV` - 常量缓冲区、Shader资源和无序访问视图 +- `SAMPLER` - 采样器 + +描述符堆可以标记为 `shaderVisible`，使其可被 GPU shader 访问。仅当需要绑定到命令列表时才应使用 shader visible 堆。 ## 公共方法 | 方法 | 描述 | |------|------| +| [`D3D12DescriptorHeap`](constructor.md) | 构造函数 | | [`Initialize`](initialize-from-desc.md) | 从描述符初始化 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭描述符堆 | +| [`Initialize(ID3D12Device*,...)`](initialize-device.md) | 直接初始化 | +| [`Shutdown`](shutdown.md) | 关闭描述符堆 | | [`GetDescriptorHeap`](get-descriptor-heap.md) | 获取 D3D12 描述符堆 | | [`GetCPUDescriptorHandle`](get-cpu-descriptor-handle.md) | 获取 CPU 描述符句柄 | | [`GetGPUDescriptorHandle`](get-gpu-descriptor-handle.md) | 获取 GPU 描述符句柄 | | [`GetDescriptorCount`](get-descriptor-count.md) | 获取描述符数量 | -| [`GetType`](../../command-queue/get-type.md) | 获取描述符类型 | +| [`GetType`](get-type.md) | 获取描述符类型 | | [`GetDescriptorSize`](get-descriptor-size.md) | 获取描述符大小 | | [`GetCPUDescriptorHandleForHeapStart`](get-cpu-descriptor-handle-for-heap-start.md) | 获取堆起始 CPU 句柄 | | [`GetGPUDescriptorHandleForHeapStart`](get-gpu-descriptor-handle-for-heap-start.md) | 获取堆起始 GPU 句柄 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | | [`CreateDesc`](create-desc.md) | 创建描述符（静态） | +## 使用示例 + +```cpp +#include "XCEngine/RHI/D3D12/D3D12DescriptorHeap.h" + +using namespace XCEngine::RHI; + +// 创建设备 +ID3D12Device* device = ...; + +// 创建 CBV/SRV/UAV 描述符堆 +D3D12DescriptorHeap heap; +heap.Initialize(device, DescriptorHeapType::CBV_SRV_UAV, 256, true); + +// 获取描述符句柄 +CPUDescriptorHandle cpuHandle = heap.GetCPUDescriptorHandle(0); +GPUDescriptorHandle gpuHandle = heap.GetGPUDescriptorHandle(0); + +// 关闭 +heap.Shutdown(); +``` + ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../d3d12.md) - [RHIDescriptorPool](../../descriptor-pool/descriptor-pool.md) - 抽象描述符池接口 +- [D3D12Enum](d3d12-enum.md) - D3D12 类型枚举映射 diff --git a/docs/api/rhi/d3d12/descriptor-heap/get-cpu-descriptor-handle-for-heap-start.md b/docs/api/rhi/d3d12/descriptor-heap/get-cpu-descriptor-handle-for-heap-start.md index 74caa4da..e1b1e719 100644 --- a/docs/api/rhi/d3d12/descriptor-heap/get-cpu-descriptor-handle-for-heap-start.md +++ b/docs/api/rhi/d3d12/descriptor-heap/get-cpu-descriptor-handle-for-heap-start.md @@ -4,12 +4,14 @@ D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandleForHeapStart() const; ``` -获取堆起始处的 CPU 描述符句柄。 +获取描述符堆起始位置的 CPU 描述符句柄。此句柄指向堆中第一个描述符，可作为遍历和偏移计算的基准。 -**返回：** CPU 描述符句柄 +**返回：** `D3D12_CPU_DESCRIPTOR_HANDLE` 结构体，包含堆起始 CPU 指针 **复杂度：** O(1) ## 相关文档 - [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 +- [GetCPUDescriptorHandle](get-cpu-descriptor-handle.md) - 获取指定索引的 CPU 句柄 +- [GetGPUDescriptorHandleForHeapStart](get-gpu-descriptor-handle-for-heap-start.md) - GPU 版本 diff --git a/docs/api/rhi/d3d12/descriptor-heap/get-gpu-descriptor-handle-for-heap-start.md b/docs/api/rhi/d3d12/descriptor-heap/get-gpu-descriptor-handle-for-heap-start.md index bc33191b..7bb31452 100644 --- a/docs/api/rhi/d3d12/descriptor-heap/get-gpu-descriptor-handle-for-heap-start.md +++ b/docs/api/rhi/d3d12/descriptor-heap/get-gpu-descriptor-handle-for-heap-start.md @@ -4,12 +4,14 @@ D3D12_GPU_DESCRIPTOR_HANDLE GetGPUDescriptorHandleForHeapStart() const; ``` -获取堆起始处的 GPU 描述符句柄。 +获取描述符堆起始位置的 GPU 描述符句柄。此句柄指向堆中第一个描述符，可作为遍历和偏移计算的基准。仅当堆创建时 `shaderVisible` 为 `true` 时返回的句柄才有效。 -**返回：** GPU 描述符句柄 +**返回：** `D3D12_GPU_DESCRIPTOR_HANDLE` 结构体，包含堆起始 GPU 指针 **复杂度：** O(1) ## 相关文档 - [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 +- [GetGPUDescriptorHandle](get-gpu-descriptor-handle.md) - 获取指定索引的 GPU 句柄 +- [GetCPUDescriptorHandleForHeapStart](get-cpu-descriptor-handle-for-heap-start.md) - CPU 版本 diff --git a/docs/api/rhi/d3d12/descriptor-heap/get-native-handle.md b/docs/api/rhi/d3d12/descriptor-heap/get-native-handle.md new file mode 100644 index 00000000..0301be53 --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/get-native-handle.md @@ -0,0 +1,17 @@ +# D3D12DescriptorHeap::GetNativeHandle + +```cpp +void* GetNativeHandle() override; +``` + +获取底层 D3D12 描述符堆原生句柄。返回 `ID3D12DescriptorHeap*` 的 `void*` 形式，用于泛型接口获取原生资源。 + +**返回：** `void*` 指向 `ID3D12DescriptorHeap` 的指针 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 +- [RHIDescriptorPool::GetNativeHandle](../../descriptor-pool/get-native-handle.md) - 基类方法 +- [GetDescriptorHeap](get-descriptor-heap.md) - 类型安全的获取方法 diff --git a/docs/api/rhi/d3d12/descriptor-heap/get-type.md b/docs/api/rhi/d3d12/descriptor-heap/get-type.md new file mode 100644 index 00000000..ae681bb9 --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/get-type.md @@ -0,0 +1,16 @@ +# D3D12DescriptorHeap::GetType + +```cpp +DescriptorHeapType GetType() const override; +``` + +获取描述符堆类型。 + +**返回：** 描述符堆类型枚举值 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 +- [RHIDescriptorPool::GetType](../../descriptor-pool/get-type.md) - 基类方法 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/descriptor-heap/initialize-device.md b/docs/api/rhi/d3d12/descriptor-heap/initialize-device.md new file mode 100644 index 00000000..bdda6d83 --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/initialize-device.md @@ -0,0 +1,40 @@ +# D3D12DescriptorHeap::Initialize + +```cpp +bool Initialize(ID3D12Device* device, DescriptorHeapType type, uint32_t numDescriptors, bool shaderVisible = false); +``` + +直接使用 D3D12 设备创描述符堆。这是主要初始化方法，会创建底层的 `ID3D12DescriptorHeap` COM 对象。 + +**参数：** +- `device` - D3D12 设备指针，不得为 `nullptr` +- `type` - 描述符堆类型，决定堆中存储的描述符种类 +- `numDescriptors` - 描述符数量，必须大于 0 +- `shaderVisible` - 是否创建为 shader visible 模式。shader visible 的堆可绑定到命令列表供 shader 访问，但会增加 GPU 访问开销 + +**返回：** 是否初始化成功。失败时返回 `false`，可能原因包括： +- 设备指针无效 +- 描述符数量为 0 +- D3D12 API 创建堆失败 + +**复杂度：** O(1) + +## 示例 + +```cpp +ID3D12Device* device = ...; + +// 创建不可见的 CPU 描述符堆 +D3D12DescriptorHeap cpuHeap; +cpuHeap.Initialize(device, DescriptorHeapType::CBV_SRV_UAV, 64, false); + +// 创建 GPU 可见的描述符堆 +D3D12DescriptorHeap gpuHeap; +gpuHeap.Initialize(device, DescriptorHeapType::CBV_SRV_UAV, 256, true); +``` + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 +- [Initialize(const DescriptorPoolDesc&)](initialize-from-desc.md) - 描述符重载 +- [CreateDesc](create-desc.md) - 创建描述符结构体 diff --git a/docs/api/rhi/d3d12/descriptor-heap/initialize-from-desc.md b/docs/api/rhi/d3d12/descriptor-heap/initialize-from-desc.md index 762c2610..420e52c8 100644 --- a/docs/api/rhi/d3d12/descriptor-heap/initialize-from-desc.md +++ b/docs/api/rhi/d3d12/descriptor-heap/initialize-from-desc.md @@ -4,15 +4,31 @@ bool Initialize(const DescriptorPoolDesc& desc) override; ``` -从描述符初始化。 +从描述符池描述结构体初始化描述符堆。该方法是 `RHIDescriptorPool` 基类接口的实现，内部调用 `Initialize(ID3D12Device*, ...)` 重载。 **参数：** -- `desc` - 描述符池描述 +- `desc` - 描述符池描述，包含设备指针、堆类型、描述符数量和 shader visible 标志 -**返回：** 是否初始化成功 +**返回：** 是否初始化成功。失败时返回 `false`，可能由于 D3D12 API 调用失败导致。 -**复杂度：** O(n) +**复杂度：** O(1) + +## 示例 + +```cpp +DescriptorPoolDesc desc = {}; +desc.device = device; +desc.type = DescriptorHeapType::CBV_SRV_UAV; +desc.descriptorCount = 256; +desc.shaderVisible = true; + +D3D12DescriptorHeap heap; +if (!heap.Initialize(desc)) { + // 处理初始化失败 +} +``` ## 相关文档 - [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 +- [Initialize(ID3D12Device*,...)](initialize-device.md) - 直接初始化重载 diff --git a/docs/api/rhi/d3d12/descriptor-heap/shutdown.md b/docs/api/rhi/d3d12/descriptor-heap/shutdown.md new file mode 100644 index 00000000..d4626740 --- /dev/null +++ b/docs/api/rhi/d3d12/descriptor-heap/shutdown.md @@ -0,0 +1,14 @@ +# D3D12DescriptorHeap::Shutdown + +```cpp +void Shutdown() override; +``` + +关闭描述符堆，释放底层 D3D12 描述符堆资源。 + +**复杂度：** O(1) + +## 相关文档 + +- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览 +- [RHIDescriptorPool::Shutdown](../../descriptor-pool/shutdown.md) - 基类方法 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/device/compile-shader.md b/docs/api/rhi/d3d12/device/compile-shader.md new file mode 100644 index 00000000..d6d79ca1 --- /dev/null +++ b/docs/api/rhi/d3d12/device/compile-shader.md @@ -0,0 +1,31 @@ +# D3D12Device::CompileShader + +```cpp +RHIShader* CompileShader(const ShaderCompileDesc& desc) override; +``` + +编译 D3D12 着色器。 + +**参数：** +- `desc` - 着色器编译描述符，包含文件名、入口点、Profile 等 + +**返回：** 新创建的着色器指针，失败返回 `nullptr` + +**复杂度：** 取决于着色器复杂度 + +**示例：** + +```cpp +ShaderCompileDesc shaderDesc; +shaderDesc.fileName = L"shaders/vertex.hlsl"; +shaderDesc.entryPoint = "VSMain"; +shaderDesc.profile = "vs_5_0"; + +RHIShader* shader = device->CompileShader(shaderDesc); +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::CompileShader](../../device/compile-shader.md) - 基类方法 +- [D3D12Shader](../../shader/shader.md) - D3D12 着色器实现 diff --git a/docs/api/rhi/d3d12/device/create-buffer.md b/docs/api/rhi/d3d12/device/create-buffer.md new file mode 100644 index 00000000..e6bc5410 --- /dev/null +++ b/docs/api/rhi/d3d12/device/create-buffer.md @@ -0,0 +1,32 @@ +# D3D12Device::CreateBuffer + +```cpp +RHIBuffer* CreateBuffer(const BufferDesc& desc) override; +``` + +创建 D3D12 缓冲区资源。 + +**参数：** +- `desc` - 缓冲区描述符，包含大小、类型、标志等 + +**返回：** 新创建的缓冲区指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +BufferDesc bufferDesc; +bufferDesc.size = sizeof(Vertex) * vertexCount; +bufferDesc.stride = sizeof(Vertex); +bufferDesc.bufferType = (uint32_t)BufferType::Vertex; +bufferDesc.flags = 0; + +RHIBuffer* vertexBuffer = device->CreateBuffer(bufferDesc); +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::CreateBuffer](../../device/create-buffer.md) - 基类方法 +- [D3D12Buffer](../../buffer/buffer.md) - D3D12 缓冲区实现 diff --git a/docs/api/rhi/d3d12/device/create-command-list.md b/docs/api/rhi/d3d12/device/create-command-list.md new file mode 100644 index 00000000..e81984bd --- /dev/null +++ b/docs/api/rhi/d3d12/device/create-command-list.md @@ -0,0 +1,19 @@ +# D3D12Device::CreateCommandList + +```cpp +RHICommandList* CreateCommandList(const CommandListDesc& desc) override; +``` + +创建 D3D12 命令列表。 + +**参数：** +- `desc` - 命令列表描述符 + +**返回：** 新创建的命令列表指针 + +**注意：** 当前实现返回 `nullptr` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::CreateCommandList](../../device/create-command-list.md) - 基类方法 diff --git a/docs/api/rhi/d3d12/device/create-command-queue.md b/docs/api/rhi/d3d12/device/create-command-queue.md new file mode 100644 index 00000000..88ede436 --- /dev/null +++ b/docs/api/rhi/d3d12/device/create-command-queue.md @@ -0,0 +1,19 @@ +# D3D12Device::CreateCommandQueue + +```cpp +RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc) override; +``` + +创建 D3D12 命令队列。 + +**参数：** +- `desc` - 命令队列描述符 + +**返回：** 新创建的命令队列指针 + +**注意：** 当前实现返回 `nullptr` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::CreateCommandQueue](../../device/create-command-queue.md) - 基类方法 diff --git a/docs/api/rhi/d3d12/device/create-fence.md b/docs/api/rhi/d3d12/device/create-fence.md new file mode 100644 index 00000000..307c27bf --- /dev/null +++ b/docs/api/rhi/d3d12/device/create-fence.md @@ -0,0 +1,27 @@ +# D3D12Device::CreateFence + +```cpp +RHIFence* CreateFence(const FenceDesc& desc) override; +``` + +创建 D3D12 栅栏。 + +**参数：** +- `desc` - 栅栏描述符，包含初始值等 + +**返回：** 新创建的栅栏指针，失败返回 `nullptr` + +**示例：** + +```cpp +FenceDesc fenceDesc; +fenceDesc.initialValue = 0; + +RHIFence* fence = device->CreateFence(fenceDesc); +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::CreateFence](../../device/create-fence.md) - 基类方法 +- [D3D12Fence](../../fence/fence.md) - D3D12 栅栏实现 diff --git a/docs/api/rhi/d3d12/device/create-pipeline-state.md b/docs/api/rhi/d3d12/device/create-pipeline-state.md new file mode 100644 index 00000000..42be1f01 --- /dev/null +++ b/docs/api/rhi/d3d12/device/create-pipeline-state.md @@ -0,0 +1,19 @@ +# D3D12Device::CreatePipelineState + +```cpp +RHIPipelineState* CreatePipelineState(const PipelineStateDesc& desc) override; +``` + +创建 D3D12 管线状态对象。 + +**参数：** +- `desc` - 管线状态描述符 + +**返回：** 新创建的管线状态指针 + +**注意：** 当前实现返回 `nullptr` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::CreatePipelineState](../../device/create-pipeline-state.md) - 基类方法 diff --git a/docs/api/rhi/d3d12/device/create-sampler.md b/docs/api/rhi/d3d12/device/create-sampler.md new file mode 100644 index 00000000..b1942fef --- /dev/null +++ b/docs/api/rhi/d3d12/device/create-sampler.md @@ -0,0 +1,30 @@ +# D3D12Device::CreateSampler + +```cpp +RHISampler* CreateSampler(const SamplerDesc& desc) override; +``` + +创建 D3D12 采样器。 + +**参数：** +- `desc` - 采样器描述符，包含过滤模式、地址模式等 + +**返回：** 新创建的采样器指针，失败返回 `nullptr` + +**示例：** + +```cpp +SamplerDesc samplerDesc; +samplerDesc.filter = (uint32_t)D3D12_FILTER_MIN_MAG_MIP_LINEAR; +samplerDesc.addressU = (uint32_t)D3D12_TEXTURE_ADDRESS_MODE_WRAP; +samplerDesc.addressV = (uint32_t)D3D12_TEXTURE_ADDRESS_MODE_WRAP; +samplerDesc.addressW = (uint32_t)D3D12_TEXTURE_ADDRESS_MODE_WRAP; + +RHISampler* sampler = device->CreateSampler(samplerDesc); +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::CreateSampler](../../device/create-sampler.md) - 基类方法 +- [D3D12Sampler](../../sampler/sampler.md) - D3D12 采样器实现 diff --git a/docs/api/rhi/d3d12/device/create-swap-chain.md b/docs/api/rhi/d3d12/device/create-swap-chain.md new file mode 100644 index 00000000..71a50b87 --- /dev/null +++ b/docs/api/rhi/d3d12/device/create-swap-chain.md @@ -0,0 +1,19 @@ +# D3D12Device::CreateSwapChain + +```cpp +RHISwapChain* CreateSwapChain(const SwapChainDesc& desc) override; +``` + +创建 D3D12 交换链。 + +**参数：** +- `desc` - 交换链描述符 + +**返回：** 新创建的交换链指针 + +**注意：** 当前实现返回 `nullptr` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::CreateSwapChain](../../device/create-swap-chain.md) - 基类方法 diff --git a/docs/api/rhi/d3d12/device/create-texture.md b/docs/api/rhi/d3d12/device/create-texture.md new file mode 100644 index 00000000..5847a5ad --- /dev/null +++ b/docs/api/rhi/d3d12/device/create-texture.md @@ -0,0 +1,36 @@ +# D3D12Device::CreateTexture + +```cpp +RHITexture* CreateTexture(const TextureDesc& desc) override; +``` + +创建 D3D12 纹理资源。 + +**参数：** +- `desc` - 纹理描述符，包含维度、格式、分辨率等 + +**返回：** 新创建的纹理指针，失败返回 `nullptr` + +**复杂度：** O(1) + +**示例：** + +```cpp +TextureDesc texDesc; +texDesc.textureType = (uint32_t)D3D12_RESOURCE_DIMENSION_TEXTURE2D; +texDesc.width = 1920; +texDesc.height = 1080; +texDesc.depth = 1; +texDesc.mipLevels = 1; +texDesc.format = (uint32_t)DXGI_FORMAT_R8G8B8A8_UNORM; +texDesc.sampleCount = 1; +texDesc.sampleQuality = 0; + +RHITexture* texture = device->CreateTexture(texDesc); +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::CreateTexture](../../device/create-texture.md) - 基类方法 +- [D3D12Texture](../../texture/texture.md) - D3D12 纹理实现 diff --git a/docs/api/rhi/d3d12/device/device.md b/docs/api/rhi/d3d12/device/device.md index ac1b59c7..eba57ed0 100644 --- a/docs/api/rhi/d3d12/device/device.md +++ b/docs/api/rhi/d3d12/device/device.md @@ -2,34 +2,55 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 设备实现，继承自 `RHIDevice`。 +**继承自**: `RHIDevice` + +**描述**: DirectX 12 设备实现，用于管理 D3D12 图形适配器、创建资源和管理命令队列。 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化设备 | -| [`Shutdown`](../../../threading/task-system/shutdown.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) | 获取原生设备 | +| [`Initialize`](initialize.md) | 初始化 D3D12 设备 | +| [`Shutdown`](shutdown.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) | 获取原生句柄 | | [`GetDevice`](get-device.md) | 获取 D3D12 设备 | | [`GetFactory`](get-factory.md) | 获取 D3D12 工厂 | | [`GetAdapterInfo`](get-adapter-info.md) | 获取适配器信息 | | [`EnumerateAdapters`](enumerate-adapters.md) | 枚举适配器 | | [`GetDescriptorHandleIncrementSize`](get-descriptor-handle-increment-size.md) | 获取描述符增量大小 | | [`CheckFeatureSupport`](check-feature-support.md) | 检查特性支持 | +| [`SetDeviceRemoved`](set-device-removed.md) | 设置设备已移除 | +| [`IsDeviceRemoved`](is-device-removed.md) | 查询设备是否已移除 | + +## 使用示例 + +```cpp +RHIDeviceDesc desc; +desc.adapterIndex = 0; +desc.enableDebugLayer = true; + +D3D12Device* device = new D3D12Device(); +if (device->Initialize(desc)) { + ID3D12Device* nativeDevice = device->GetDevice(); + // 使用设备... + device->Shutdown(); +} +delete device; +``` ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../d3d12.md) - [RHIDevice](../../device/device.md) - 抽象设备接口 diff --git a/docs/api/rhi/d3d12/device/get-capabilities.md b/docs/api/rhi/d3d12/device/get-capabilities.md new file mode 100644 index 00000000..bef438b7 --- /dev/null +++ b/docs/api/rhi/d3d12/device/get-capabilities.md @@ -0,0 +1,15 @@ +# D3D12Device::GetCapabilities + +```cpp +const RHICapabilities& GetCapabilities() const override; +``` + +获取 D3D12 设备能力。 + +**返回：** 设备能力引用 + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::GetCapabilities](../../device/get-capabilities.md) - 基类方法 +- [RHICapabilities](../../capabilities/capabilities.md) - 能力结构体 diff --git a/docs/api/rhi/d3d12/device/get-device-info.md b/docs/api/rhi/d3d12/device/get-device-info.md new file mode 100644 index 00000000..6880cc7e --- /dev/null +++ b/docs/api/rhi/d3d12/device/get-device-info.md @@ -0,0 +1,14 @@ +# D3D12Device::GetDeviceInfo + +```cpp +const RHIDeviceInfo& GetDeviceInfo() const override; +``` + +获取 D3D12 设备信息。 + +**返回：** 设备信息引用 + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::GetDeviceInfo](../../device/get-device-info.md) - 基类方法 diff --git a/docs/api/rhi/d3d12/device/get-native-device.md b/docs/api/rhi/d3d12/device/get-native-device.md new file mode 100644 index 00000000..19f292dc --- /dev/null +++ b/docs/api/rhi/d3d12/device/get-native-device.md @@ -0,0 +1,21 @@ +# D3D12Device::GetNativeDevice + +```cpp +void* GetNativeDevice() override; +``` + +获取原生 D3D12 设备指针。 + +**返回：** `ID3D12Device*` 指针 + +**示例：** + +```cpp +ID3D12Device* nativeDevice = static_cast(device->GetNativeDevice()); +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::GetNativeDevice](../../device/get-native-device.md) - 基类方法 +- [GetNativeHandle](get-native-handle.md) - 获取原生句柄 diff --git a/docs/api/rhi/d3d12/device/get-native-handle.md b/docs/api/rhi/d3d12/device/get-native-handle.md new file mode 100644 index 00000000..8f412a73 --- /dev/null +++ b/docs/api/rhi/d3d12/device/get-native-handle.md @@ -0,0 +1,16 @@ +# D3D12Device::GetNativeHandle + +```cpp +void* GetNativeHandle() const; +``` + +获取原生 D3D12 设备句柄。 + +**返回：** `ID3D12Device*` 指针 + +**注意：** 此方法返回与 `GetNativeDevice()` 相同的指针 + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [GetNativeDevice](get-native-device.md) - 获取原生设备 diff --git a/docs/api/rhi/d3d12/device/initialize.md b/docs/api/rhi/d3d12/device/initialize.md new file mode 100644 index 00000000..6d6227b9 --- /dev/null +++ b/docs/api/rhi/d3d12/device/initialize.md @@ -0,0 +1,35 @@ +# D3D12Device::Initialize + +```cpp +bool Initialize(const RHIDeviceDesc& desc) override; +``` + +初始化 D3D12 设备，建立与图形适配器的连接。 + +**参数：** +- `desc` - 设备描述符，包含适配器索引、调试选项等配置 + +**返回：** 成功返回 `true`，失败返回 `false` + +**复杂度：** O(1) + +**示例：** + +```cpp +RHIDeviceDesc desc; +desc.adapterIndex = 0; +desc.enableDebugLayer = true; + +D3D12Device* device = new D3D12Device(); +if (device->Initialize(desc)) { + ID3D12Device* nativeDevice = device->GetDevice(); +} else { + delete device; +} +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::Initialize](../../device/initialize.md) - 基类方法 +- [RHIDeviceDesc](../../types/types.md) - 设备描述结构体 diff --git a/docs/api/rhi/d3d12/device/is-device-removed.md b/docs/api/rhi/d3d12/device/is-device-removed.md new file mode 100644 index 00000000..f0629484 --- /dev/null +++ b/docs/api/rhi/d3d12/device/is-device-removed.md @@ -0,0 +1,14 @@ +# D3D12Device::IsDeviceRemoved + +```cpp +bool IsDeviceRemoved() const; +``` + +查询设备是否已移除。 + +**返回：** 设备已移除返回 `true`，否则返回 `false` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [SetDeviceRemoved](set-device-removed.md) - 设置设备已移除标记 diff --git a/docs/api/rhi/d3d12/device/methods.md b/docs/api/rhi/d3d12/device/methods.md deleted file mode 100644 index fd1ef2a5..00000000 --- a/docs/api/rhi/d3d12/device/methods.md +++ /dev/null @@ -1,165 +0,0 @@ -# D3D12Device 方法 - -## 继承方法 - -### Initialize - -```cpp -bool Initialize(const RHIDeviceDesc& desc) override; -``` - -初始化 D3D12 设备。 - -### Shutdown - -```cpp -void Shutdown() override; -``` - -关闭设备。 - -### CreateBuffer - -```cpp -RHIBuffer* CreateBuffer(const BufferDesc& desc) override; -``` - -创建 D3D12 缓冲区。 - -### CreateTexture - -```cpp -RHITexture* CreateTexture(const TextureDesc& desc) override; -``` - -创建 D3D12 纹理。 - -### CreateSwapChain - -```cpp -RHISwapChain* CreateSwapChain(const SwapChainDesc& desc) override; -``` - -创建 D3D12 交换链。 - -### CreateCommandList - -```cpp -RHICommandList* CreateCommandList(const CommandListDesc& desc) override; -``` - -创建 D3D12 命令列表。 - -### CreateCommandQueue - -```cpp -RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc) override; -``` - -创建 D3D12 命令队列。 - -### CompileShader - -```cpp -RHIShader* CompileShader(const ShaderCompileDesc& desc) override; -``` - -编译 D3D12 着色器。 - -### CreatePipelineState - -```cpp -RHIPipelineState* CreatePipelineState(const PipelineStateDesc& desc) override; -``` - -创建 D3D12 管线状态对象。 - -### CreateFence - -```cpp -RHIFence* CreateFence(const FenceDesc& desc) override; -``` - -创建 D3D12 栅栏。 - -### CreateSampler - -```cpp -RHISampler* CreateSampler(const SamplerDesc& desc) override; -``` - -创建 D3D12 采样器。 - -### GetCapabilities - -```cpp -const RHICapabilities& GetCapabilities() const override; -``` - -获取设备能力。 - -### GetDeviceInfo - -```cpp -const RHIDeviceInfo& GetDeviceInfo() const override; -``` - -获取设备信息。 - -### GetNativeDevice - -```cpp -void* GetNativeDevice() override; -``` - -获取原生 D3D12 设备指针。 - -## D3D12 特有方法 - -### GetDevice - -```cpp -ID3D12Device* GetDevice() const; -``` - -获取 `ID3D12Device` 接口。 - -### GetFactory - -```cpp -IDXGIFactory4* GetFactory() const; -``` - -获取 `IDXGIFactory4` 接口。 - -### GetAdapterInfo - -```cpp -const AdapterInfo& GetAdapterInfo() const; -``` - -获取适配器信息。 - -### EnumerateAdapters - -```cpp -std::vector EnumerateAdapters(); -``` - -枚举所有适配器。 - -### GetDescriptorHandleIncrementSize - -```cpp -UINT GetDescriptorHandleIncrementSize(DescriptorHeapType type) const; -``` - -获取描述符句柄增量大小。 - -### CheckFeatureSupport - -```cpp -bool CheckFeatureSupport(D3D12_FEATURE feature, void* featureSupportData, uint32_t featureSupportDataSize); -``` - -检查功能支持。 diff --git a/docs/api/rhi/d3d12/device/set-device-removed.md b/docs/api/rhi/d3d12/device/set-device-removed.md new file mode 100644 index 00000000..cf88c41c --- /dev/null +++ b/docs/api/rhi/d3d12/device/set-device-removed.md @@ -0,0 +1,12 @@ +# D3D12Device::SetDeviceRemoved + +```cpp +void SetDeviceRemoved(); +``` + +标记设备已移除。 + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [IsDeviceRemoved](is-device-removed.md) - 查询设备是否已移除 diff --git a/docs/api/rhi/d3d12/device/shutdown.md b/docs/api/rhi/d3d12/device/shutdown.md new file mode 100644 index 00000000..64affeeb --- /dev/null +++ b/docs/api/rhi/d3d12/device/shutdown.md @@ -0,0 +1,21 @@ +# D3D12Device::Shutdown + +```cpp +void Shutdown() override; +``` + +关闭 D3D12 设备，释放所有相关资源。 + +**复杂度：** O(n) - 取决于管理的资源数量 + +**示例：** + +```cpp +device->Shutdown(); +delete device; +``` + +## 相关文档 + +- [D3D12Device 总览](device.md) - 返回类总览 +- [RHIDevice::Shutdown](../../device/shutdown.md) - 基类方法 diff --git a/docs/api/rhi/d3d12/enums/enums.md b/docs/api/rhi/d3d12/enums/enums.md index b43015c0..cd9c8c41 100644 --- a/docs/api/rhi/d3d12/enums/enums.md +++ b/docs/api/rhi/d3d12/enums/enums.md @@ -2,36 +2,77 @@ **命名空间**: `XCEngine::RHI` +**类型**: `namespace` (枚举转换函数集合) + **描述**: D3D12 枚举值转换函数集合，提供 RHI 抽象枚举到 D3D12 原生枚举的转换。**所有函数均为 inline 函数**。 -## 转换函数列表 +## 概述 -| 函数 | 描述 | -|------|------| -| `ToD3D12(FillMode)` | 填充模式转换 | -| `ToD3D12(CullMode)` | 剔除模式转换 | -| `ToD3D12(ComparisonFunc)` | 比较函数转换 | -| `ToD3D12(StencilOp)` | 模板操作转换 | -| `ToD3D12(BlendOp)` | 混合操作转换 | -| `ToD3D12(BlendFactor)` | 混合因子转换 | -| `ToD3D12(LogicOp)` | 逻辑操作转换 | -| `ToD3D12(FilterMode)` | 过滤器模式转换 | -| `ToD3D12(TextureAddressMode)` | 纹理寻址模式转换 | -| `ToD3D12(BorderColor)` | 边框颜色转换 | -| `ToD3D12(ShaderVisibility)` | Shader 可见性转换 | -| `ToD3D12(Format)` | 格式转换 | -| `ToDXGI(Format)` | DXGI 格式转换 | -| `ToD3D12(ResourceStates)` | 资源状态转换 | -| `ToD3D12(HeapType)` | 堆类型转换 | -| `ToD3D12(PrimitiveTopology)` | 图元拓扑类型转换 | -| `ToD3D12Topology` | 图元拓扑详细转换 | -| `ToD3D12(DescriptorHeapType)` | 描述符堆类型转换 | -| `ToD3D12(QueryType)` | 查询类型转换 | -| `ToD3D12(RootParameterType)` | 根参数类型转换 | -| `ToD3D12(TextureType)` | 纹理类型维度转换 | -| `ToD3D12(CommandQueueType)` | 命令列表类型转换 | +`D3D12Enum.h` 提供了 RHI 抽象层枚举类型到 DirectX 12 原生枚举类型的转换函数。这些函数是 D3D12 后端实现的核心组成部分，使得上层的 RHI 抽象枚举能够正确转换为对应的 D3D12 枚举值。设计遵循 DirectX 12 规范，涵盖填充模式、剔除模式、混合操作、纹理寻址、图元拓扑等核心渲染参数。 + +## 转换函数详细列表 + +| 函数 | 源类型 | 目标类型 | 描述 | +|------|--------|----------|------| +| `ToD3D12(FillMode)` | `FillMode` | `D3D12_FILL_MODE` | 填充模式转换 (Wireframe/Solid) | +| `ToD3D12(CullMode)` | `CullMode` | `D3D12_CULL_MODE` | 剔除模式转换 (None/Front/Back) | +| `ToD3D12(ComparisonFunc)` | `ComparisonFunc` | `D3D12_COMPARISON_FUNC` | 比较函数转换 (Never/Less/Equal/LessEqual/Greater/NotEqual/GreaterEqual/Always) | +| `ToD3D12(StencilOp)` | `StencilOp` | `D3D12_STENCIL_OP` | 模板操作转换 (Keep/Zero/Replace/IncrSat/DecrSat/Invert/Incr/Decr) | +| `ToD3D12(BlendOp)` | `BlendOp` | `D3D12_BLEND_OP` | 混合操作转换 (Add/Subtract/ReverseSubtract/Min/Max) | +| `ToD3D12(BlendFactor)` | `BlendFactor` | `D3D12_BLEND` | 混合因子转换 (Zero/One/SrcColor/InvSrcColor/SrcAlpha/InvSrcAlpha/SrcAlphaSat/BlendFactor/InvBlendFactor) | +| `ToD3D12(LogicOp)` | `LogicOp` | `D3D12_LOGIC_OP` | 逻辑操作转换 (Clear/Set/Copy/CopyInverted/Noop/Invert/And/Nand/Or/Nor/Xor/Equiv/AndReverse/AndInverted/OrReverse/OrInverted) | +| `ToD3D12(FilterMode)` | `FilterMode` | `D3D12_FILTER` | 过滤器模式转换 (Point/Linear/Anisotropic/ComparisonPoint/ComparisonLinear/ComparisonAnisotropic) | +| `ToD3D12(TextureAddressMode)` | `TextureAddressMode` | `D3D12_TEXTURE_ADDRESS_MODE` | 纹理寻址模式转换 (Wrap/Mirror/Clamp/Border/MirrorOnce) | +| `ToD3D12(BorderColor)` | `BorderColor` | `D3D12_STATIC_BORDER_COLOR` | 边框颜色转换 (TransparentBlack/OpaqueBlack/OpaqueWhite) | +| `ToD3D12(ShaderVisibility)` | `ShaderVisibility` | `D3D12_SHADER_VISIBILITY` | Shader 可见性转换 (All/Vertex/Hull/Domain/Geometry/Pixel/Amplification/Mesh) | +| `ToD3D12(Format)` | `Format` | `DXGI_FORMAT` | 格式转换 (Unknown/R8_UNorm/R8G8_UNorm/R8G8B8A8_UNorm/R16G16B16A16_Float/R32G32B32A32_Float/R16_Float/R32_Float/D16_UNorm/D24_UNorm_S8_UInt/D32_Float/BC1-7_UNorm/BC6H_UF16/R32G32B32A32_UInt/R32_UInt) | +| `ToDXGI(Format)` | `Format` | `DXGI_FORMAT` | DXGI 格式转换（内部调用 `ToD3D12(Format)`） | +| `ToD3D12(ResourceStates)` | `ResourceStates` | `D3D12_RESOURCE_STATES` | 资源状态转换 (Common/VertexAndConstantBuffer/IndexBuffer/RenderTarget/UnorderedAccess/DepthWrite/DepthRead/NonPixelShaderResource/PixelShaderResource/CopySrc/CopyDst/Present/GenericRead) | +| `ToD3D12(HeapType)` | `HeapType` | `D3D12_HEAP_TYPE` | 堆类型转换 (Default/Upload/Readback) | +| `ToD3D12(PrimitiveTopology)` | `PrimitiveTopology` | `D3D12_PRIMITIVE_TOPOLOGY_TYPE` | 图元拓扑类型转换 (PointList/Line*/Triangle*/PatchList) | +| `ToD3D12Topology(PrimitiveTopology)` | `PrimitiveTopology` | `D3D12_PRIMITIVE_TOPOLOGY` | 图元拓扑详细转换（包含控制点信息） | +| `ToD3D12(DescriptorHeapType)` | `DescriptorHeapType` | `D3D12_DESCRIPTOR_HEAP_TYPE` | 描述符堆类型转换 (CBV_SRV_UAV/Sampler/RTV/DSV) | +| `ToD3D12(QueryType)` | `QueryType` | `D3D12_QUERY_TYPE` | 查询类型转换 (Occlusion/Timestamp/PipelineStatistics) | +| `ToD3D12(RootParameterType)` | `RootParameterType` | `D3D12_ROOT_PARAMETER_TYPE` | 根参数类型转换 (DescriptorTable/Constants/CBV/SRV/UAV) | +| `ToD3D12(TextureType)` | `TextureType` | `D3D12_RESOURCE_DIMENSION` | 纹理类型维度转换 (Texture1D/Texture2D*/Texture3D) | +| `ToD3D12(CommandQueueType)` | `CommandQueueType` | `D3D12_COMMAND_LIST_TYPE` | 命令列表类型转换 (Direct/Compute/Copy) | + +## 使用示例 + +### 渲染状态设置 + +```cpp +#include + +void SetupRenderState(XCEngine::RHI::FillMode fill, XCEngine::RHI::CullMode cull) { + D3D12_FILL_MODE d3dFill = XCEngine::RHI::ToD3D12(fill); + D3D12_CULL_MODE d3dCull = XCEngine::RHI::ToD3D12(cull); +} +``` + +### 纹理采样器配置 + +```cpp +#include + +void ConfigureSampler(XCEngine::RHI::FilterMode filterMode, XCEngine::RHI::TextureAddressMode addressMode) { + D3D12_FILTER filter = XCEngine::RHI::ToD3D12(filterMode); + D3D12_TEXTURE_ADDRESS_MODE address = XCEngine::RHI::ToD3D12(addressMode); +} +``` + +### 资源状态转换 + +```cpp +#include + +void TransitionResource(XCEngine::RHI::ResourceStates state) { + D3D12_RESOURCE_STATES d3dState = XCEngine::RHI::ToD3D12(state); +} +``` ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端概览](../d3d12.md) - [D3D12Types](../../types/types.md) - 类型转换 +- [RHI 枚举定义](../../../threading/task-system-config/README.md) - RHI 抽象层枚举定义 diff --git a/docs/api/rhi/d3d12/fence/fence.md b/docs/api/rhi/d3d12/fence/fence.md index 7b75051e..dbeb3eb6 100644 --- a/docs/api/rhi/d3d12/fence/fence.md +++ b/docs/api/rhi/d3d12/fence/fence.md @@ -2,23 +2,38 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 栅栏同步对象的 D3D12 实现，继承自 `RHIFence`。 +**继承自**: `RHIFence` + +**描述**: DirectX 12 栅栏同步对象，用于 GPU/CPU 同步和跨队列同步。 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化栅栏 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭栅栏 | +| [`Initialize`](initialize.md) | 初始化栅栏 | +| [`Shutdown`](shutdown.md) | 关闭并释放资源 | | [`Signal`](signal.md) | 信号栅栏 | -| [`Wait`](../../../threading/task-group/wait.md) | 等待栅栏 | +| [`Wait`](wait.md) | 等待栅栏 | | [`GetCompletedValue`](get-completed-value.md) | 获取完成值 | | [`IsSignaled`](is-signaled.md) | 检查是否已信号 | | [`GetEventHandle`](get-event-handle.md) | 获取事件句柄 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | | [`GetFence`](get-fence.md) | 获取 D3D12 栅栏 | +## 使用示例 + +```cpp +ID3D12Device* device = /* 获取 D3D12 设备 */; +D3D12Fence fence; +if (!fence.Initialize(device, 0)) { + return false; +} + +commandQueue->Signal(&fence, 1); +fence.Wait(1); +``` + ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) -- [RHIFence](../../fence/fence.md) - 抽象栅栏接口 +- [D3D12 后端总览](../d3d12.md) - D3D12 后端总览 +- [RHIFence](../../fence/fence.md) - 抽象栅栏接口 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/fence/get-event-handle.md b/docs/api/rhi/d3d12/fence/get-event-handle.md index cc889439..34f47c87 100644 --- a/docs/api/rhi/d3d12/fence/get-event-handle.md +++ b/docs/api/rhi/d3d12/fence/get-event-handle.md @@ -28,4 +28,4 @@ WaitForSingleObject(eventHandle, INFINITE); ## 相关文档 - [D3D12Fence](fence.md) - 类总览 -- [D3D12Fence::Wait](../../../threading/task-group/wait.md) - 等待栅栏 +- [D3D12Fence::Wait](wait.md) - 等待栅栏 diff --git a/docs/api/rhi/d3d12/fence/get-fence.md b/docs/api/rhi/d3d12/fence/get-fence.md index 4084d487..ba7633a3 100644 --- a/docs/api/rhi/d3d12/fence/get-fence.md +++ b/docs/api/rhi/d3d12/fence/get-fence.md @@ -27,4 +27,4 @@ ID3D12Fence* fence = d3d12Fence->GetFence(); ## 相关文档 - [D3D12Fence](fence.md) - 类总览 -- [D3D12Fence::GetNativeHandle](../../buffer/get-native-handle.md) - 获取原生句柄 +- [D3D12Fence::GetNativeHandle](get-native-handle.md) - 获取原生句柄 diff --git a/docs/api/rhi/d3d12/fence/get-native-handle.md b/docs/api/rhi/d3d12/fence/get-native-handle.md new file mode 100644 index 00000000..46998606 --- /dev/null +++ b/docs/api/rhi/d3d12/fence/get-native-handle.md @@ -0,0 +1,30 @@ +# D3D12Fence::GetNativeHandle + +## 函数签名 + +```cpp +void* GetNativeHandle() override +``` + +## 中文描述 + +获取底层 D3D12 栅栏指针。 + +## 返回值 + +`void*` - 底层 `ID3D12Fence*` 指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +ID3D12Fence* nativeFence = static_cast(d3d12Fence->GetNativeHandle()); +``` + +## 相关文档 + +- [D3D12Fence](fence.md) - 类总览 +- [D3D12Fence::GetFence](get-fence.md) - 获取 D3D12 栅栏接口 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/fence/index.md b/docs/api/rhi/d3d12/fence/index.md new file mode 100644 index 00000000..40d32cdb --- /dev/null +++ b/docs/api/rhi/d3d12/fence/index.md @@ -0,0 +1,75 @@ +# D3D12Fence + +## 命名空间 + +`XCEngine::RHI` + +## 类型 + +类 (Class) + +## 描述 + +D3D12Fence 是 DirectX 12 栅栏同步原语的实现类，继承自 RHIFence。该类封装了 ID3D12Fence 对象和 Win32 事件句柄，提供 GPU 与 CPU 之间的同步机制。 + +## 概述 + +D3D12Fence 通过 DirectX 12 的栅栏机制实现 GPU 命令队列的同步。每个栅栏关联一个 64 位递增数值，当 GPU 到达指定栅栏点时会更新该值，CPU 端可以等待栅栏达到目标值后继续执行。 + +## 公共方法表格 + +| 方法 | 签名 | 描述 | +|------|------|------| +| Initialize | `bool Initialize(ID3D12Device* device, uint64_t initialValue = 0)` | 初始化 D3D12Fence 对象 | +| Shutdown | `void Shutdown() override` | 释放栅栏相关资源 | +| Signal | `void Signal() override` | 使用默认值 1 触发栅栏 | +| Signal | `void Signal(uint64_t value) override` | 使用指定值触发栅栏 | +| Wait | `void Wait(uint64_t value) override` | 等待栅栏达到指定值 | +| GetCompletedValue | `uint64_t GetCompletedValue() const override` | 获取栅栏当前完成值 | +| IsSignaled | `bool IsSignaled() const override` | 检查栅栏是否已触发 | +| GetEventHandle | `void* GetEventHandle()` | 获取 Win32 事件句柄 | +| GetNativeHandle | `void* GetNativeHandle() override` | 获取底层 D3D12Fence 指针 | +| GetFence | `ID3D12Fence* GetFence() const` | 获取 ID3D12Fence 接口 | + +## 使用示例 + +```cpp +#include "XCEngine/RHI/D3D12/D3D12Fence.h" +#include + +// 创建设备后初始化栅栏 +ID3D12Device* device = ...; +D3D12Fence fence; +if (!fence.Initialize(device)) { + return false; +} + +// 在 GPU 命令完成后触发栅栏 +fence.Signal(1); + +// 在 CPU 端等待栅栏 +fence.Wait(1); + +// 检查栅栏状态 +if (fence.IsSignaled()) { + // 栅栏已触发，可以继续执行 +} + +// 获取底层 D3D12Fence 进行高级操作 +ID3D12Fence* nativeFence = fence.GetFence(); + +// 销毁前关闭 +fence.Shutdown(); +``` + +## 相关文档 + +- [Initialize](methods/initialize.md) +- [Shutdown](methods/shutdown.md) +- [Signal](methods/signal.md) +- [Wait](methods/wait.md) +- [GetCompletedValue](methods/get-completed-value.md) +- [IsSignaled](methods/is-signaled.md) +- [GetEventHandle](methods/get-event-handle.md) +- [GetNativeHandle](methods/get-native-handle.md) +- [GetFence](methods/get-fence.md) diff --git a/docs/api/rhi/d3d12/fence/initialize.md b/docs/api/rhi/d3d12/fence/initialize.md new file mode 100644 index 00000000..8e9b25d5 --- /dev/null +++ b/docs/api/rhi/d3d12/fence/initialize.md @@ -0,0 +1,43 @@ +# D3D12Fence::Initialize + +## 函数签名 + +```cpp +bool Initialize(ID3D12Device* device, uint64_t initialValue = 0) +``` + +## 中文描述 + +创建 D3D12 栅栏对象并初始化同步事件。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `initialValue` | `uint64_t` | 栅栏初始值，默认为 0 | + +## 返回值 + +`bool` - 初始化成功返回 `true`，失败返回 `false` + +## 复杂度 + +O(1) + +## 示例 + +```cpp +ID3D12Device* device = /* 获取 D3D12 设备 */; +D3D12Fence fence; +if (!fence.Initialize(device, 0)) { + // 初始化失败 + return false; +} +``` + +## 相关文档 + +- [D3D12Fence](fence.md) - 类总览 +- [D3D12Fence::Shutdown](shutdown.md) - 关闭栅栏 +- [D3D12Fence::Signal](signal.md) - 信号栅栏 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/fence/is-signaled.md b/docs/api/rhi/d3d12/fence/is-signaled.md index b6c622db..e7b4e2b2 100644 --- a/docs/api/rhi/d3d12/fence/is-signaled.md +++ b/docs/api/rhi/d3d12/fence/is-signaled.md @@ -30,4 +30,4 @@ if (d3d12Fence->IsSignaled()) { - [D3D12Fence](fence.md) - 类总览 - [D3D12Fence::GetCompletedValue](get-completed-value.md) - 获取完成值 -- [D3D12Fence::Wait](../../../threading/task-group/wait.md) - 等待栅栏 +- [D3D12Fence::Wait](wait.md) - 等待栅栏 diff --git a/docs/api/rhi/d3d12/fence/shutdown.md b/docs/api/rhi/d3d12/fence/shutdown.md new file mode 100644 index 00000000..c011ea8f --- /dev/null +++ b/docs/api/rhi/d3d12/fence/shutdown.md @@ -0,0 +1,37 @@ +# D3D12Fence::Shutdown + +## 函数签名 + +```cpp +void Shutdown() override +``` + +## 中文描述 + +关闭栅栏并释放关联的 Win32 事件句柄。 + +## 参数 + +无 + +## 返回值 + +无 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12Fence fence; +fence.Initialize(device, 0); +// 使用栅栏... +fence.Shutdown(); +``` + +## 相关文档 + +- [D3D12Fence](fence.md) - 类总览 +- [D3D12Fence::Initialize](initialize.md) - 初始化栅栏 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/fence/signal.md b/docs/api/rhi/d3d12/fence/signal.md index 6344e27a..694e4e4d 100644 --- a/docs/api/rhi/d3d12/fence/signal.md +++ b/docs/api/rhi/d3d12/fence/signal.md @@ -42,5 +42,5 @@ d3d12Fence->Signal(1); ## 相关文档 - [D3D12Fence](fence.md) - 类总览 -- [D3D12Fence::Wait](../../../threading/task-group/wait.md) - 等待栅栏 +- [D3D12Fence::Wait](wait.md) - 等待栅栏 - [D3D12Fence::GetCompletedValue](get-completed-value.md) - 获取完成值 diff --git a/docs/api/rhi/d3d12/fence/wait.md b/docs/api/rhi/d3d12/fence/wait.md new file mode 100644 index 00000000..9911f972 --- /dev/null +++ b/docs/api/rhi/d3d12/fence/wait.md @@ -0,0 +1,37 @@ +# D3D12Fence::Wait + +## 函数签名 + +```cpp +void Wait(uint64_t value) override +``` + +## 中文描述 + +阻塞等待直到栅栏值达到指定值。利用 Win32 事件进行高效等待。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `value` | `uint64_t` | 要等待的栅栏值 | + +## 返回值 + +无 + +## 复杂度 + +O(1) 到 O(n)，n 为等待时间 + +## 示例 + +```cpp +fence.Wait(1); // 等待栅栏值达到 1 +``` + +## 相关文档 + +- [D3D12Fence](fence.md) - 类总览 +- [D3D12Fence::Signal](signal.md) - 信号栅栏 +- [D3D12Fence::GetCompletedValue](get-completed-value.md) - 获取完成值 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/pipeline-state/bind.md b/docs/api/rhi/d3d12/pipeline-state/bind.md new file mode 100644 index 00000000..cd7761b8 --- /dev/null +++ b/docs/api/rhi/d3d12/pipeline-state/bind.md @@ -0,0 +1,36 @@ +# D3D12PipelineState::Bind + +## 函数签名 + +```cpp +void Bind() override +``` + +## 中文描述 + +绑定管线状态到渲染上下文。此方法从 `RHIPipelineState` 基类继承并重写。当前实现为空。 + +## 参数 + +无 + +## 返回值 + +无 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12PipelineState pipelineState; +// ... 初始化 pipelineState +pipelineState.Bind(); +``` + +## 相关文档 + +- [D3D12PipelineState](pipeline-state.md) - 类总览 +- [RHIPipelineState](../../pipeline-state/pipeline-state.md) - 抽象管线状态接口 diff --git a/docs/api/rhi/d3d12/pipeline-state/get-native-handle.md b/docs/api/rhi/d3d12/pipeline-state/get-native-handle.md new file mode 100644 index 00000000..003064a4 --- /dev/null +++ b/docs/api/rhi/d3d12/pipeline-state/get-native-handle.md @@ -0,0 +1,37 @@ +# D3D12PipelineState::GetNativeHandle + +## 函数签名 + +```cpp +void* GetNativeHandle() override +``` + +## 中文描述 + +获取管线状态的原生句柄。此方法返回底层 `ID3D12PipelineState` 接口指针，用于与原生 D3D12 API 交互。此方法从 `RHIPipelineState` 基类继承并重写。 + +## 参数 + +无 + +## 返回值 + +`void*` - 底层 `ID3D12PipelineState*` 指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12PipelineState pipelineState; +// ... 初始化 pipelineState +ID3D12PipelineState* nativePSO = static_cast(pipelineState.GetNativeHandle()); +``` + +## 相关文档 + +- [D3D12PipelineState](pipeline-state.md) - 类总览 +- [D3D12PipelineState::GetPipelineState](get-pipeline-state.md) - 获取 D3D12 管线状态对象 +- [RHIPipelineState](../../pipeline-state/pipeline-state.md) - 抽象管线状态接口 diff --git a/docs/api/rhi/d3d12/pipeline-state/get-type.md b/docs/api/rhi/d3d12/pipeline-state/get-type.md new file mode 100644 index 00000000..971d3d31 --- /dev/null +++ b/docs/api/rhi/d3d12/pipeline-state/get-type.md @@ -0,0 +1,35 @@ +# D3D12PipelineState::GetType + +## 函数签名 + +```cpp +PipelineType GetType() const override +``` + +## 中文描述 + +获取管线类型。返回 `PipelineType::Graphics` 表示图形管线。此方法从 `RHIPipelineState` 基类继承并重写。 + +## 参数 + +无 + +## 返回值 + +`PipelineType` - 管线类型，始终返回 `PipelineType::Graphics` + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12PipelineState pipelineState; +PipelineType type = pipelineState.GetType(); // 返回 PipelineType::Graphics +``` + +## 相关文档 + +- [D3D12PipelineState](pipeline-state.md) - 类总览 +- [RHIPipelineState](../../pipeline-state/pipeline-state.md) - 抽象管线状态接口 diff --git a/docs/api/rhi/d3d12/pipeline-state/initialize.md b/docs/api/rhi/d3d12/pipeline-state/initialize.md new file mode 100644 index 00000000..40b423f3 --- /dev/null +++ b/docs/api/rhi/d3d12/pipeline-state/initialize.md @@ -0,0 +1,48 @@ +# D3D12PipelineState::Initialize + +## 函数签名 + +```cpp +bool Initialize(ID3D12Device* device, const D3D12_GRAPHICS_PIPELINE_STATE_DESC& desc) +``` + +## 中文描述 + +初始化 D3D12 图形管线状态对象。根据提供的管线状态描述符创建 DirectX 12 管线状态对象。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `desc` | `D3D12_GRAPHICS_PIPELINE_STATE_DESC` | 图形管线状态描述符 | + +## 返回值 + +`bool` - 初始化成功返回 `true`，失败返回 `false` + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12_GRAPHICS_PIPELINE_STATE_DESC psoDesc = D3D12PipelineState::CreateDesc( + rootSignature, + vsBytecode, + psBytecode, + gsBytecode, + inputElementCount, + inputElements); + +D3D12PipelineState pipelineState; +if (!pipelineState.Initialize(device, psoDesc)) { + // 处理初始化失败 +} +``` + +## 相关文档 + +- [D3D12PipelineState](pipeline-state.md) - 类总览 +- [D3D12PipelineState::CreateDesc](create-desc.md) - 创建管线描述符 diff --git a/docs/api/rhi/d3d12/pipeline-state/pipeline-state.md b/docs/api/rhi/d3d12/pipeline-state/pipeline-state.md index e2e2442b..10655c66 100644 --- a/docs/api/rhi/d3d12/pipeline-state/pipeline-state.md +++ b/docs/api/rhi/d3d12/pipeline-state/pipeline-state.md @@ -2,23 +2,25 @@ **命名空间**: `XCEngine::RHI` +**继承自**: `RHIPipelineState` + **描述**: DirectX 12 管线状态对象的 D3D12 实现，继承自 `RHIPipelineState`。 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化管线状态 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭管线状态 | +| [`Initialize`](initialize.md) | 初始化管线状态 | +| [`Shutdown`](shutdown.md) | 关闭管线状态 | | [`GetPipelineState`](get-pipeline-state.md) | 获取 D3D12 管线状态对象 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | -| [`GetType`](../../command-queue/get-type.md) | 获取管线类型 | -| [`Bind`](../../shader/bind.md) | 绑定管线状态 | -| [`Unbind`](../../shader/unbind.md) | 解绑管线状态 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | +| [`GetType`](get-type.md) | 获取管线类型 | +| [`Bind`](bind.md) | 绑定管线状态 | +| [`Unbind`](unbind.md) | 解绑管线状态 | | [`CreateDesc`](create-desc.md) | 创建管线状态描述符（静态） | | [`CreateInputElement`](create-input-element.md) | 创建输入元素描述符（静态） | ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../d3d12.md) - [RHIPipelineState](../../pipeline-state/pipeline-state.md) - 抽象管线状态接口 diff --git a/docs/api/rhi/d3d12/pipeline-state/shutdown.md b/docs/api/rhi/d3d12/pipeline-state/shutdown.md new file mode 100644 index 00000000..b1af5351 --- /dev/null +++ b/docs/api/rhi/d3d12/pipeline-state/shutdown.md @@ -0,0 +1,36 @@ +# D3D12PipelineState::Shutdown + +## 函数签名 + +```cpp +void Shutdown() override +``` + +## 中文描述 + +关闭管线状态对象，释放底层 D3D12 管线状态资源。此方法从 `RHIPipelineState` 基类继承并重写。 + +## 参数 + +无 + +## 返回值 + +无 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12PipelineState pipelineState; +// ... 使用 pipelineState +pipelineState.Shutdown(); +``` + +## 相关文档 + +- [D3D12PipelineState](pipeline-state.md) - 类总览 +- [RHIPipelineState](../../pipeline-state/pipeline-state.md) - 抽象管线状态接口 diff --git a/docs/api/rhi/d3d12/pipeline-state/unbind.md b/docs/api/rhi/d3d12/pipeline-state/unbind.md new file mode 100644 index 00000000..58392971 --- /dev/null +++ b/docs/api/rhi/d3d12/pipeline-state/unbind.md @@ -0,0 +1,36 @@ +# D3D12PipelineState::Unbind + +## 函数签名 + +```cpp +void Unbind() override +``` + +## 中文描述 + +解绑管线状态从渲染上下文。此方法从 `RHIPipelineState` 基类继承并重写。当前实现为空。 + +## 参数 + +无 + +## 返回值 + +无 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12PipelineState pipelineState; +// ... 使用 pipelineState +pipelineState.Unbind(); +``` + +## 相关文档 + +- [D3D12PipelineState](pipeline-state.md) - 类总览 +- [RHIPipelineState](../../pipeline-state/pipeline-state.md) - 抽象管线状态接口 diff --git a/docs/api/rhi/d3d12/query-heap/get-count.md b/docs/api/rhi/d3d12/query-heap/get-count.md index c730e8b1..7f92f09a 100644 --- a/docs/api/rhi/d3d12/query-heap/get-count.md +++ b/docs/api/rhi/d3d12/query-heap/get-count.md @@ -27,3 +27,4 @@ uint32_t count = d3d12QueryHeap->GetCount(); ## 相关文档 - [D3D12QueryHeap](query-heap.md) - 类总览 +- [GetType](get-type.md) diff --git a/docs/api/rhi/d3d12/query-heap/get-native-handle.md b/docs/api/rhi/d3d12/query-heap/get-native-handle.md new file mode 100644 index 00000000..d45d75e0 --- /dev/null +++ b/docs/api/rhi/d3d12/query-heap/get-native-handle.md @@ -0,0 +1,33 @@ +# D3D12QueryHeap::GetNativeHandle + +## 函数签名 + +```cpp +void* GetNativeHandle() const +``` + +## 中文描述 + +获取原生句柄，用于跨 RHI 模块互操作。返回的指针类型为 `ID3D12QueryHeap*`。 + +## 参数 + +无 + +## 返回值 + +`void*` - 指向 `ID3D12QueryHeap` 的指针 + +## 示例 + +```cpp +D3D12QueryHeap queryHeap; +queryHeap.Initialize(device, QueryType::Timestamp, 1024); + +void* handle = queryHeap.GetNativeHandle(); +ID3D12QueryHeap* nativeHeap = static_cast(handle); +``` + +## 相关文档 + +- [GetQueryHeap](get-query-heap.md) diff --git a/docs/api/rhi/d3d12/query-heap/get-query-heap.md b/docs/api/rhi/d3d12/query-heap/get-query-heap.md index 3e37c4ed..bf1aa17d 100644 --- a/docs/api/rhi/d3d12/query-heap/get-query-heap.md +++ b/docs/api/rhi/d3d12/query-heap/get-query-heap.md @@ -27,3 +27,4 @@ ID3D12QueryHeap* queryHeap = d3d12QueryHeap->GetQueryHeap(); ## 相关文档 - [D3D12QueryHeap](query-heap.md) - 类总览 +- [GetNativeHandle](get-native-handle.md) diff --git a/docs/api/rhi/d3d12/query-heap/get-type.md b/docs/api/rhi/d3d12/query-heap/get-type.md new file mode 100644 index 00000000..f9be64e8 --- /dev/null +++ b/docs/api/rhi/d3d12/query-heap/get-type.md @@ -0,0 +1,36 @@ +# D3D12QueryHeap::GetType + +## 函数签名 + +```cpp +QueryType GetType() const +``` + +## 中文描述 + +获取查询堆的类型。 + +## 参数 + +无 + +## 返回值 + +`QueryType` - 查询类型（Timestamp、Occlusion 或 PipelineStatistics） + +## 示例 + +```cpp +D3D12QueryHeap queryHeap; +queryHeap.Initialize(device, QueryType::Occlusion, 256); + +QueryType type = queryHeap.GetType(); +if (type == QueryType::Occlusion) { + // 处理遮挡查询 +} +``` + +## 相关文档 + +- [D3D12QueryHeap](query-heap.md) +- [GetCount](get-count.md) diff --git a/docs/api/rhi/d3d12/query-heap/initialize.md b/docs/api/rhi/d3d12/query-heap/initialize.md new file mode 100644 index 00000000..73f7cb9e --- /dev/null +++ b/docs/api/rhi/d3d12/query-heap/initialize.md @@ -0,0 +1,42 @@ +# D3D12QueryHeap::Initialize + +## 函数签名 + +```cpp +bool Initialize(ID3D12Device* device, QueryType type, uint32_t count) +``` + +## 中文描述 + +创建 D3D12 查询堆资源。根据指定的查询类型分配相应类型的 GPU 查询堆。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `type` | `QueryType` | 查询类型：Timestamp（时间戳）、Occlusion（遮挡）、PipelineStatistics（管线统计） | +| `count` | `uint32_t` | 查询数量 | + +## 返回值 + +`bool` - 初始化是否成功 + +## 示例 + +```cpp +D3D12QueryHeap timestampHeap; +if (timestampHeap.Initialize(device, QueryType::Timestamp, 1024)) { + // 时间戳查询堆创建成功 +} + +D3D12QueryHeap occlusionHeap; +if (occlusionHeap.Initialize(device, QueryType::Occlusion, 256)) { + // 遮挡查询堆创建成功 +} +``` + +## 相关文档 + +- [D3D12QueryHeap](query-heap.md) +- [Shutdown](shutdown.md) diff --git a/docs/api/rhi/d3d12/query-heap/query-heap.md b/docs/api/rhi/d3d12/query-heap/query-heap.md index 06062b60..2b985ebc 100644 --- a/docs/api/rhi/d3d12/query-heap/query-heap.md +++ b/docs/api/rhi/d3d12/query-heap/query-heap.md @@ -2,19 +2,37 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 查询堆的 D3D12 实现。 +**类型**: `class` + +**描述**: DirectX 12 查询堆的 D3D12 实现，用于管理 GPU 查询操作。 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化查询堆 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭查询堆 | +| [`Initialize`](initialize.md) | 初始化查询堆 | +| [`Shutdown`](shutdown.md) | 关闭查询堆 | | [`GetQueryHeap`](get-query-heap.md) | 获取 D3D12 查询堆 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | -| [`GetType`](../../command-queue/get-type.md) | 获取查询类型 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | +| [`GetType`](get-type.md) | 获取查询类型 | | [`GetCount`](get-count.md) | 获取查询数量 | +## 使用示例 + +```cpp +#include "XCEngine/RHI/D3D12/D3D12QueryHeap.h" + +D3D12QueryHeap queryHeap; +if (queryHeap.Initialize(device, QueryType::Timestamp, 1024)) { + // 使用查询堆 + ID3D12QueryHeap* heap = queryHeap.GetQueryHeap(); + QueryType type = queryHeap.GetType(); + uint32_t count = queryHeap.GetCount(); + + queryHeap.Shutdown(); +} +``` + ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../d3d12.md) diff --git a/docs/api/rhi/d3d12/query-heap/shutdown.md b/docs/api/rhi/d3d12/query-heap/shutdown.md new file mode 100644 index 00000000..aa40deba --- /dev/null +++ b/docs/api/rhi/d3d12/query-heap/shutdown.md @@ -0,0 +1,35 @@ +# D3D12QueryHeap::Shutdown + +## 函数签名 + +```cpp +void Shutdown() +``` + +## 中文描述 + +关闭查询堆，释放所有关联的 GPU 资源。将重置内部状态为默认值。 + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +```cpp +D3D12QueryHeap queryHeap; +queryHeap.Initialize(device, QueryType::Timestamp, 1024); + +// 使用查询堆... + +queryHeap.Shutdown(); // 释放资源 +``` + +## 相关文档 + +- [D3D12QueryHeap](query-heap.md) +- [Initialize](initialize.md) diff --git a/docs/api/rhi/d3d12/render-target-view/constructor.md b/docs/api/rhi/d3d12/render-target-view/constructor.md new file mode 100644 index 00000000..b84ae8bf --- /dev/null +++ b/docs/api/rhi/d3d12/render-target-view/constructor.md @@ -0,0 +1,27 @@ +# D3D12RenderTargetView::D3D12RenderTargetView + +## 函数签名 + +```cpp +D3D12RenderTargetView() +``` + +## 描述 + +默认构造函数。创建空的渲染目标视图实例，成员变量初始化为零值和空指针。 + +## 返回值 + +无 + +## 示例 + +```cpp +D3D12RenderTargetView rtv; // 创建空实例 +``` + +## 相关文档 + +- [D3D12RenderTargetView](render-target-view.md) - 类总览 +- [D3D12RenderTargetView::Initialize](initialize.md) - 初始化方法 +- [D3D12RenderTargetView::~D3D12RenderTargetView](destructor.md) - 析构函数 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/render-target-view/create-desc.md b/docs/api/rhi/d3d12/render-target-view/create-desc.md index fc0675ce..12fd6055 100644 --- a/docs/api/rhi/d3d12/render-target-view/create-desc.md +++ b/docs/api/rhi/d3d12/render-target-view/create-desc.md @@ -6,20 +6,20 @@ static D3D12_RENDER_TARGET_VIEW_DESC CreateDesc(Format format, D3D12_RTV_DIMENSION dimension = D3D12_RTV_DIMENSION_TEXTURE2D) ``` -## 中文描述 +## 描述 -创建渲染目标视图描述符。 +创建渲染目标视图描述符的便捷静态方法。将引擎格式枚举转换为 D3D12 格式，并设置视图维度。 ## 参数 | 参数 | 类型 | 描述 | |------|------|------| -| `format` | `Format` | 资源格式 | -| `dimension` | `D3D12_RTV_DIMENSION` | 视图维度（默认 TEXTURE2D） | +| `format` | `Format` | 资源格式（参见 `RHIEnums.h` 中的 Format 枚举） | +| `dimension` | `D3D12_RTV_DIMENSION` | 视图维度（默认 `D3D12_RTV_DIMENSION_TEXTURE2D`） | ## 返回值 -`D3D12_RENDER_TARGET_VIEW_DESC` - 渲染目标视图描述符 +`D3D12_RENDER_TARGET_VIEW_DESC` - 渲染目标视图描述符结构体 ## 复杂度 @@ -28,9 +28,12 @@ O(1) ## 示例 ```cpp +// 创建典型纹理2D渲染目标描述符 D3D12_RENDER_TARGET_VIEW_DESC desc = D3D12RenderTargetView::CreateDesc(Format::R8G8B8A8_UNorm); ``` ## 相关文档 - [D3D12RenderTargetView](render-target-view.md) - 类总览 +- [D3D12_RENDER_TARGET_VIEW_DESC](https://docs.microsoft.com/en-us/windows/win32/api/d3d12/ns-d3d12-d3d12_render_target_view_desc) +- [Format 枚举](../enums.md#Format) \ No newline at end of file diff --git a/docs/api/rhi/d3d12/render-target-view/destructor.md b/docs/api/rhi/d3d12/render-target-view/destructor.md new file mode 100644 index 00000000..d5e6672e --- /dev/null +++ b/docs/api/rhi/d3d12/render-target-view/destructor.md @@ -0,0 +1,34 @@ +# D3D12RenderTargetView::~D3D12RenderTargetView + +## 函数签名 + +```cpp +~D3D12RenderTargetView() +``` + +## 描述 + +析构函数。自动调用 `Shutdown()` 释放内部资源。 + +## 返回值 + +无 + +## 注意事项 + +此析构函数不直接释放 D3D12 资源，仅清理类内部状态。实际资源释放由描述符堆管理。 + +## 示例 + +```cpp +{ + D3D12RenderTargetView rtv; + rtv.Initialize(device, resource, &desc); + // 使用 rtv... +} // rtv 析构时自动调用 Shutdown() +``` + +## 相关文档 + +- [D3D12RenderTargetView](render-target-view.md) - 类总览 +- [D3D12RenderTargetView::Shutdown](shutdown.md) - 关闭方法 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/render-target-view/get-cpu-descriptor-handle.md b/docs/api/rhi/d3d12/render-target-view/get-cpu-descriptor-handle.md index b68c7f5f..d0a4a9a4 100644 --- a/docs/api/rhi/d3d12/render-target-view/get-cpu-descriptor-handle.md +++ b/docs/api/rhi/d3d12/render-target-view/get-cpu-descriptor-handle.md @@ -6,9 +6,9 @@ D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const ``` -## 中文描述 +## 描述 -获取渲染目标视图的 CPU 描述符句柄。 +获取渲染目标视图的 CPU 描述符句柄。返回的句柄用于绑定 RTV 到渲染管线命令列表。 ## 返回值 @@ -21,9 +21,11 @@ O(1) ## 示例 ```cpp -D3D12_CPU_DESCRIPTOR_HANDLE handle = rtv->GetCPUDescriptorHandle(); +D3D12_CPU_DESCRIPTOR_HANDLE handle = rtv.GetCPUDescriptorHandle(); +commandList->OMSetRenderTargets(1, &handle, FALSE, nullptr); ``` ## 相关文档 - [D3D12RenderTargetView](render-target-view.md) - 类总览 +- [OMSetRenderTargets (D3D12)](https://docs.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-id3d12graphicscommandlist-omsetrendertargets) \ No newline at end of file diff --git a/docs/api/rhi/d3d12/render-target-view/initialize-at.md b/docs/api/rhi/d3d12/render-target-view/initialize-at.md index 76318609..a7ce4f49 100644 --- a/docs/api/rhi/d3d12/render-target-view/initialize-at.md +++ b/docs/api/rhi/d3d12/render-target-view/initialize-at.md @@ -6,18 +6,18 @@ void InitializeAt(ID3D12Device* device, ID3D12Resource* resource, D3D12_CPU_DESCRIPTOR_HANDLE handle, const D3D12_RENDER_TARGET_VIEW_DESC* desc = nullptr) ``` -## 中文描述 +## 描述 -在指定描述符句柄位置初始化渲染目标视图，用于外部描述符堆管理场景。 +在指定描述符句柄位置初始化渲染目标视图，用于外部描述符堆管理场景。此方法允许将 RTV 创建在预分配的描述符位置，便于批量管理描述符。 ## 参数 | 参数 | 类型 | 描述 | |------|------|------| | `device` | `ID3D12Device*` | D3D12 设备指针 | -| `resource` | `ID3D12Resource*` | 资源指针 | -| `handle` | `D3D12_CPU_DESCRIPTOR_HANDLE` | 预分配的描述符句柄 | -| `desc` | `D3D12_RENDER_TARGET_VIEW_DESC*` | 视图描述符（可选） | +| `resource` | `ID3D12Resource*` | 渲染目标资源指针 | +| `handle` | `D3D12_CPU_DESCRIPTOR_HANDLE` | 预分配的描述符句柄位置 | +| `desc` | `D3D12_RENDER_TARGET_VIEW_DESC*` | 视图描述符（可选，传入 nullptr 使用资源默认格式） | ## 返回值 @@ -30,11 +30,13 @@ O(1) ## 示例 ```cpp +// 从描述符堆获取句柄 D3D12_CPU_DESCRIPTOR_HANDLE handle = descriptorHeap->GetCPUDescriptorHandleForHeapStart(); -rtv->InitializeAt(device, resource, handle); +rtv.InitializeAt(device, resource, handle); ``` ## 相关文档 - [D3D12RenderTargetView](render-target-view.md) - 类总览 -- [D3D12RenderTargetView::Initialize](../../../threading/task-system/initialize.md) - 标准初始化 +- [D3D12RenderTargetView::Initialize](initialize.md) - 标准初始化 +- [D3D12DescriptorHeap](../descriptor-heap/descriptor-heap.md) - 描述符堆管理 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/render-target-view/initialize.md b/docs/api/rhi/d3d12/render-target-view/initialize.md new file mode 100644 index 00000000..1906f20e --- /dev/null +++ b/docs/api/rhi/d3d12/render-target-view/initialize.md @@ -0,0 +1,35 @@ +# D3D12RenderTargetView::Initialize + +## 函数签名 + +```cpp +void Initialize(ID3D12Device* device, ID3D12Resource* resource, const D3D12_RENDER_TARGET_VIEW_DESC* desc = nullptr) +``` + +## 描述 + +初始化渲染目标视图。内部自动分配描述符句柄。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `resource` | `ID3D12Resource*` | 渲染目标资源指针 | +| `desc` | `D3D12_RENDER_TARGET_VIEW_DESC*` | 视图描述符（可选） | + +## 返回值 + +无 + +## 示例 + +```cpp +D3D12RenderTargetView rtv; +rtv.Initialize(device, resource, &desc); +``` + +## 相关文档 + +- [D3D12RenderTargetView](render-target-view.md) - 类总览 +- [D3D12RenderTargetView::InitializeAt](initialize-at.md) - 在指定位置初始化 diff --git a/docs/api/rhi/d3d12/render-target-view/render-target-view.md b/docs/api/rhi/d3d12/render-target-view/render-target-view.md index 16e7ac91..cd303466 100644 --- a/docs/api/rhi/d3d12/render-target-view/render-target-view.md +++ b/docs/api/rhi/d3d12/render-target-view/render-target-view.md @@ -2,18 +2,35 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 渲染目标视图的 D3D12 实现。 +**描述**: DirectX 12 渲染目标视图的 D3D12 实现，用于在渲染管线中作为渲染目标使用。 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化渲染目标视图 | +| [`D3D12RenderTargetView`](constructor.md) | 构造函数 | +| [`~D3D12RenderTargetView`](destructor.md) | 析构函数 | +| [`Initialize`](initialize.md) | 初始化渲染目标视图 | | [`InitializeAt`](initialize-at.md) | 在指定位置初始化 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭渲染目标视图 | +| [`Shutdown`](shutdown.md) | 关闭渲染目标视图 | | [`GetCPUDescriptorHandle`](get-cpu-descriptor-handle.md) | 获取 CPU 描述符句柄 | | [`CreateDesc`](create-desc.md) | 创建描述符（静态） | +## 使用示例 + +```cpp +// 创建 RTV +D3D12RenderTargetView rtv; +rtv.Initialize(device, resource, &desc); + +// 使用 +device->CreateRenderTargetView(resource, &desc, rtv.GetCPUDescriptorHandle()); + +// 清理 +rtv.Shutdown(); +``` + ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../d3d12.md) +- [D3D12DescriptorHeap](../descriptor-heap/descriptor-heap.md) \ No newline at end of file diff --git a/docs/api/rhi/d3d12/render-target-view/shutdown.md b/docs/api/rhi/d3d12/render-target-view/shutdown.md new file mode 100644 index 00000000..459fe041 --- /dev/null +++ b/docs/api/rhi/d3d12/render-target-view/shutdown.md @@ -0,0 +1,26 @@ +# D3D12RenderTargetView::Shutdown + +## 函数签名 + +```cpp +void Shutdown() +``` + +## 描述 + +关闭渲染目标视图，释放内部资源。 + +## 返回值 + +无 + +## 示例 + +```cpp +rtv.Shutdown(); +``` + +## 相关文档 + +- [D3D12RenderTargetView](render-target-view.md) - 类总览 +- [D3D12RenderTargetView::Initialize](initialize.md) - 初始化 diff --git a/docs/api/rhi/d3d12/root-signature/get-native-handle.md b/docs/api/rhi/d3d12/root-signature/get-native-handle.md new file mode 100644 index 00000000..bff5f43f --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/get-native-handle.md @@ -0,0 +1,31 @@ +# D3D12RootSignature::GetNativeHandle + +## 函数签名 + +```cpp +void* GetNativeHandle() const +``` + +## 中文描述 + +获取底层 `ID3D12RootSignature` 接口指针的原生句柄。 + +## 返回值 + +`void*` - 指向 `ID3D12RootSignature` 接口的指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +void* handle = rootSignature->GetNativeHandle(); +ID3D12RootSignature* rs = static_cast(handle); +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 +- [D3D12RootSignature::GetRootSignature](get-root-signature.md) - 获取 D3D12 根签名接口 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/root-signature/initialize.md b/docs/api/rhi/d3d12/root-signature/initialize.md new file mode 100644 index 00000000..c7f61cbb --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/initialize.md @@ -0,0 +1,48 @@ +# D3D12RootSignature::Initialize + +## 函数签名 + +```cpp +bool Initialize(ID3D12Device* device, const D3D12_ROOT_SIGNATURE_DESC& desc) +``` + +## 中文描述 + +初始化 D3D12 根签名对象，使用提供的描述符序列化并创建根签名。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `desc` | `const D3D12_ROOT_SIGNATURE_DESC&` | 根签名描述符 | + +## 返回值 + +`bool` - 初始化成功返回 `true`，失败返回 `false` + +## 复杂度 + +O(n)，n 为参数和采样器数量 + +## 示例 + +```cpp +D3D12RootSignature rootSig; + +D3D12_ROOT_SIGNATURE_DESC desc = D3D12RootSignature::CreateDesc( + parameters.data(), + parameters.size(), + samplers.data(), + samplers.size()); + +if (rootSig.Initialize(device, desc)) { + // 根签名创建成功 +} +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 +- [D3D12RootSignature::Shutdown](shutdown.md) - 关闭根签名 +- [D3D12RootSignature::CreateDesc](create-desc.md) - 创建描述符 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/root-signature/root-signature.md b/docs/api/rhi/d3d12/root-signature/root-signature.md index ec578f60..43c41449 100644 --- a/docs/api/rhi/d3d12/root-signature/root-signature.md +++ b/docs/api/rhi/d3d12/root-signature/root-signature.md @@ -2,16 +2,18 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 根签名的 D3D12 实现。**不继承 RHI 抽象接口**，是 D3D12 特有的封装类。 +**类型**: `class` (D3D12-specific, does not inherit from RHI) + +**描述**: DirectX 12 根签名的 D3D12 实现，提供根签名序列化、参数创建等功能。 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化根签名 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭根签名 | +| [`Initialize`](initialize.md) | 初始化根签名 | +| [`Shutdown`](shutdown.md) | 关闭根签名 | | [`GetRootSignature`](get-root-signature.md) | 获取 D3D12 根签名 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | | [`GetParameterCount`](get-parameter-count.md) | 获取参数数量 | | [`CreateDesc`](create-desc.md) | 创建根签名描述符（静态） | | [`CreateCBV`](create-cbv.md) | 创建常量缓冲区视图（静态） | @@ -23,6 +25,23 @@ | [`CreateSamplerDesc`](create-sampler-desc.md) | 创建采样器描述符（静态） | | [`CreateDescriptorRange`](create-descriptor-range.md) | 创建描述符范围（静态） | +## 使用示例 + +```cpp +D3D12RootSignature rootSig; + +D3D12_ROOT_PARAMETER params[2] = {}; +params[0] = D3D12RootSignature::CreateCBV(0); +params[1] = D3D12RootSignature::CreateSRV(0); + +D3D12_ROOT_SIGNATURE_DESC desc = D3D12RootSignature::CreateDesc(params, 2); + +if (rootSig.Initialize(device, desc)) { + ID3D12RootSignature* rs = rootSig.GetRootSignature(); + rootSig.Shutdown(); +} +``` + ## 相关文档 - [D3D12 后端总览](../../opengl/overview.md) diff --git a/docs/api/rhi/d3d12/root-signature/shutdown.md b/docs/api/rhi/d3d12/root-signature/shutdown.md new file mode 100644 index 00000000..93384246 --- /dev/null +++ b/docs/api/rhi/d3d12/root-signature/shutdown.md @@ -0,0 +1,30 @@ +# D3D12RootSignature::Shutdown + +## 函数签名 + +```cpp +void Shutdown() +``` + +## 中文描述 + +关闭并释放 D3D12 根签名资源。 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12RootSignature rootSig; +if (rootSig.Initialize(device, desc)) { + // 使用根签名 + rootSig.Shutdown(); +} +``` + +## 相关文档 + +- [D3D12RootSignature](root-signature.md) - 类总览 +- [D3D12RootSignature::Initialize](initialize.md) - 初始化根签名 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/sampler/bind.md b/docs/api/rhi/d3d12/sampler/bind.md new file mode 100644 index 00000000..3994800c --- /dev/null +++ b/docs/api/rhi/d3d12/sampler/bind.md @@ -0,0 +1,26 @@ +# D3D12Sampler::Bind + +## 函数签名 + +```cpp +void Bind(unsigned int unit) override +``` + +## 描述 + +绑定采样器到指定的纹理单元。此方法继承自 `RHISampler` 接口。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `unit` | `unsigned int` | 纹理单元索引 | + +## 返回值 + +无 + +## 相关文档 + +- [D3D12Sampler](sampler.md) - 类总览 +- [RHISampler](../../sampler/sampler.md) - 抽象采样器接口 diff --git a/docs/api/rhi/d3d12/sampler/get-desc.md b/docs/api/rhi/d3d12/sampler/get-desc.md new file mode 100644 index 00000000..4937fc30 --- /dev/null +++ b/docs/api/rhi/d3d12/sampler/get-desc.md @@ -0,0 +1,42 @@ +# D3D12Sampler::GetDesc + +## 函数签名 + +```cpp +D3D12_SAMPLER_DESC GetDesc() const +``` + +## 描述 + +获取 D3D12 采样器的描述符结构。该描述符包含了采样器的所有配置信息，包括过滤模式、寻址模式和细节级别等。 + +## 返回值 + +`D3D12_SAMPLER_DESC` - 采样器描述符的副本，包含以下配置： + +| 字段 | 描述 | +|------|------| +| `Filter` | 过滤模式（线性、点采样、各向异性等） | +| `AddressU/V/W` | UVW 三个方向的寻址模式 | +| `MipLODBias` | Mip 级别偏移 | +| `MaxAnisotropy` | 最大各向异性级别 | +| `ComparisonFunc` | 比较函数 | +| `BorderColor` | 边界颜色 | +| `MinLOD/MaxLOD` | Mip 级别范围 | + +## 示例 + +```cpp +D3D12Sampler sampler; +// ... 初始化 sampler ... +D3D12_SAMPLER_DESC desc = sampler.GetDesc(); + +if (desc.Filter == D3D12_FILTER_MIN_MAG_MIP_LINEAR) { + // 使用线性过滤 +} +``` + +## 相关文档 + +- [D3D12Sampler::Initialize](initialize.md) - 初始化采样器 +- [D3D12Sampler](sampler.md) - 类总览 diff --git a/docs/api/rhi/d3d12/sampler/get-native-handle.md b/docs/api/rhi/d3d12/sampler/get-native-handle.md new file mode 100644 index 00000000..610ea7b9 --- /dev/null +++ b/docs/api/rhi/d3d12/sampler/get-native-handle.md @@ -0,0 +1,24 @@ +# D3D12Sampler::GetNativeHandle + +## 函数签名 + +```cpp +void* GetNativeHandle() override +``` + +## 描述 + +获取 D3D12 采样器的原生句柄。此方法继承自 `RHISampler` 接口。 + +## 参数 + +无 + +## 返回值 + +`void*` - 原生句柄指针。当前实现返回 `nullptr`。 + +## 相关文档 + +- [D3D12Sampler](sampler.md) - 类总览 +- [RHISampler](../../sampler/sampler.md) - 抽象采样器接口 diff --git a/docs/api/rhi/d3d12/sampler/index.md b/docs/api/rhi/d3d12/sampler/index.md new file mode 100644 index 00000000..8c617f8b --- /dev/null +++ b/docs/api/rhi/d3d12/sampler/index.md @@ -0,0 +1,71 @@ +# D3D12Sampler 类 + +## 命名空间 +`XCEngine::RHI` + +## 类型 +类 (Class)，继承自 `RHISampler` + +## 描述 +D3D12 采样器实现类，用于配置纹理采样状态。封装 D3D12 采样器描述符，支持过滤模式、寻址模式等采样参数配置。 + +## 概述 +`D3D12Sampler` 是 RHI 抽象层在 DirectX 12 后端的采样器实现。该类管理 D3D12 采样器状态，与 `RHISampler` 基类配合提供跨平台统一的采样器接口。 + +**当前实现状态**: 本类为存根实现，`Initialize()` 仅存储描述符，未创建实际 D3D12 采样器对象。 + +## 公共方法表格 + +| 方法 | 签名 | 描述 | +|------|------|------| +| `D3D12Sampler` | `D3D12Sampler()` | 构造函数，初始化描述符为零 | +| `~D3D12Sampler` | `~D3D12Sampler()` | 析构函数，调用 `Shutdown()` | +| `Initialize` | `bool Initialize(ID3D12Device* device, const D3D12_SAMPLER_DESC& desc)` | 初始化采样器 | +| `Shutdown` | `void Shutdown()` | 关闭采样器，重置描述符 | +| `GetDesc` | `D3D12_SAMPLER_DESC GetDesc() const` | 获取采样器描述符副本 | +| `GetNativeHandle` | `void* GetNativeHandle()` | 获取原生句柄（暂未实现） | +| `GetID` | `unsigned int GetID()` | 获取采样器 ID（暂未实现） | +| `Bind` | `void Bind(unsigned int unit)` | 绑定到纹理单元（暂未实现） | +| `Unbind` | `void Unbind(unsigned int unit)` | 从纹理单元解绑（暂未实现） | + +## 头文件 +```cpp +#include "XCEngine/RHI/D3D12/D3D12Sampler.h" +``` + +## 使用示例 +```cpp +#include "XCEngine/RHI/D3D12/D3D12Sampler.h" + +using namespace XCEngine::RHI; + +// 创建设备指针 (假设已创建) +ID3D12Device* device = ...; + +// 配置采样器描述符 +D3D12_SAMPLER_DESC samplerDesc = {}; +samplerDesc.Filter = D3D12_FILTER_MIN_MAG_MIP_LINEAR; +samplerDesc.AddressU = D3D12_TEXTURE_ADDRESS_MODE_WRAP; +samplerDesc.AddressV = D3D12_TEXTURE_ADDRESS_MODE_WRAP; +samplerDesc.AddressW = D3D12_TEXTURE_ADDRESS_MODE_WRAP; +samplerDesc.MaxAnisotropy = 16; +samplerDesc.ComparisonFunc = D3D12_COMPARISON_FUNC_LESS; +samplerDesc.BorderColor[0] = 0.0f; +samplerDesc.BorderColor[1] = 0.0f; +samplerDesc.BorderColor[2] = 0.0f; +samplerDesc.BorderColor[3] = 1.0f; + +// 创建并初始化采样器 +D3D12Sampler* sampler = new D3D12Sampler(); +if (sampler->Initialize(device, samplerDesc)) { + D3D12_SAMPLER_DESC desc = sampler->GetDesc(); + // 使用采样器... + sampler->Shutdown(); +} +delete sampler; +``` + +## 相关文档 + +- [RHISampler 基类](../RHISampler.md) +- [D3D12 枚举映射](./D3D12Enum.md) diff --git a/docs/api/rhi/d3d12/sampler/initialize.md b/docs/api/rhi/d3d12/sampler/initialize.md new file mode 100644 index 00000000..4b42c945 --- /dev/null +++ b/docs/api/rhi/d3d12/sampler/initialize.md @@ -0,0 +1,52 @@ +# D3D12Sampler::Initialize + +## 函数签名 + +```cpp +bool Initialize(ID3D12Device* device, const D3D12_SAMPLER_DESC& desc) +``` + +## 描述 + +初始化 D3D12 采样器对象。根据提供的采样器描述符创建并配置 D3D12 采样器状态。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针，用于创建采样器资源 | +| `desc` | `const D3D12_SAMPLER_DESC&` | 采样器描述符，包含过滤模式、寻址模式等配置 | + +## 返回值 + +`bool` - 初始化成功返回 `true`，否则返回 `false` + +## 示例 + +```cpp +D3D12Sampler sampler; +D3D12_SAMPLER_DESC desc = {}; +desc.Filter = D3D12_FILTER_MIN_MAG_MIP_LINEAR; +desc.AddressU = D3D12_TEXTURE_ADDRESS_MODE_WRAP; +desc.AddressV = D3D12_TEXTURE_ADDRESS_MODE_WRAP; +desc.AddressW = D3D12_TEXTURE_ADDRESS_MODE_WRAP; +desc.MipLODBias = 0.0f; +desc.MaxAnisotropy = 16; +desc.ComparisonFunc = D3D12_COMPARISON_FUNC_NEVER; +desc.BorderColor[0] = 0.0f; +desc.BorderColor[1] = 0.0f; +desc.BorderColor[2] = 0.0f; +desc.BorderColor[3] = 0.0f; +desc.MinLOD = 0.0f; +desc.MaxLOD = D3D12_FLOAT32_MAX; + +if (sampler.Initialize(device, desc)) { + // 采样器初始化成功 +} +``` + +## 相关文档 + +- [D3D12Sampler::Shutdown](shutdown.md) - 关闭采样器 +- [D3D12Sampler::GetDesc](get-desc.md) - 获取采样器描述符 +- [D3D12Sampler](sampler.md) - 类总览 diff --git a/docs/api/rhi/d3d12/sampler/sampler.md b/docs/api/rhi/d3d12/sampler/sampler.md index fab87f1d..b7650da4 100644 --- a/docs/api/rhi/d3d12/sampler/sampler.md +++ b/docs/api/rhi/d3d12/sampler/sampler.md @@ -2,21 +2,50 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 采样器的 D3D12 实现，继承自 `RHISampler`。 +**类型**: `class` + +**继承**: `RHISampler` + +**描述**: DirectX 12 采样器的 D3D12 实现，提供对 D3D12 采样器资源的封装和管理。 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化采样器 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭采样器 | -| [`GetDesc`](../buffer/get-desc.md) | 获取采样器描述符 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| [`Initialize`](initialize.md) | 初始化采样器 | +| [`GetDesc`](get-desc.md) | 获取采样器描述符 | | [`GetID`](get-id.md) | 获取采样器 ID | -| [`Bind`](../../shader/bind.md) | 绑定采样器 | -| [`Unbind`](../../shader/unbind.md) | 解绑采样器 | + +## 继承方法 + +以下方法继承自 `RHISampler`： + +| 方法 | 描述 | +|------|------| +| [`Shutdown`](shutdown.md) | 关闭采样器 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | +| [`Bind`](bind.md) | 绑定采样器到纹理单元 | +| [`Unbind`](unbind.md) | 解绑采样器 | + +## 使用示例 + +```cpp +D3D12Sampler sampler; +D3D12_SAMPLER_DESC desc = {}; +desc.Filter = D3D12_FILTER_MIN_MAG_MIP_LINEAR; +desc.AddressU = D3D12_TEXTURE_ADDRESS_MODE_WRAP; +desc.AddressV = D3D12_TEXTURE_ADDRESS_MODE_WRAP; +desc.AddressW = D3D12_TEXTURE_ADDRESS_MODE_WRAP; + +if (sampler.Initialize(device, desc)) { + sampler.Bind(0); + // 使用采样器... + sampler.Unbind(0); + sampler.Shutdown(); +} +``` ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../d3d12.md) - D3D12 模块总览 - [RHISampler](../../sampler/sampler.md) - 抽象采样器接口 diff --git a/docs/api/rhi/d3d12/sampler/shutdown.md b/docs/api/rhi/d3d12/sampler/shutdown.md new file mode 100644 index 00000000..323dcb34 --- /dev/null +++ b/docs/api/rhi/d3d12/sampler/shutdown.md @@ -0,0 +1,24 @@ +# D3D12Sampler::Shutdown + +## 函数签名 + +```cpp +void Shutdown() override +``` + +## 描述 + +关闭 D3D12 采样器并释放相关资源。此方法继承自 `RHISampler` 接口。 + +## 参数 + +无 + +## 返回值 + +无 + +## 相关文档 + +- [D3D12Sampler](sampler.md) - 类总览 +- [RHISampler](../../sampler/sampler.md) - 抽象采样器接口 diff --git a/docs/api/rhi/d3d12/sampler/unbind.md b/docs/api/rhi/d3d12/sampler/unbind.md new file mode 100644 index 00000000..94ffc8e0 --- /dev/null +++ b/docs/api/rhi/d3d12/sampler/unbind.md @@ -0,0 +1,26 @@ +# D3D12Sampler::Unbind + +## 函数签名 + +```cpp +void Unbind(unsigned int unit) override +``` + +## 描述 + +从指定的纹理单元解绑采样器。此方法继承自 `RHISampler` 接口。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `unit` | `unsigned int` | 纹理单元索引 | + +## 返回值 + +无 + +## 相关文档 + +- [D3D12Sampler](sampler.md) - 类总览 +- [RHISampler](../../sampler/sampler.md) - 抽象采样器接口 diff --git a/docs/api/rhi/d3d12/shader-resource-view/constructor.md b/docs/api/rhi/d3d12/shader-resource-view/constructor.md new file mode 100644 index 00000000..d09dd91b --- /dev/null +++ b/docs/api/rhi/d3d12/shader-resource-view/constructor.md @@ -0,0 +1,24 @@ +# D3D12ShaderResourceView::D3D12ShaderResourceView + +## 函数签名 + +```cpp +D3D12ShaderResourceView() +``` + +## 描述 + +构造一个空的 `D3D12ShaderResourceView` 实例。描述符句柄初始化为零，资源指针为 `nullptr`。 + +## 参数 + +无 + +## 返回值 + +无 + +## 相关文档 + +- [D3D12ShaderResourceView](shader-resource-view.md) - 类总览 +- [D3D12ShaderResourceView::~D3D12ShaderResourceView](destructor.md) - 析构函数 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/shader-resource-view/create-desc.md b/docs/api/rhi/d3d12/shader-resource-view/create-desc.md index 019e4273..ae19c442 100644 --- a/docs/api/rhi/d3d12/shader-resource-view/create-desc.md +++ b/docs/api/rhi/d3d12/shader-resource-view/create-desc.md @@ -32,6 +32,13 @@ O(1) D3D12_SHADER_RESOURCE_VIEW_DESC desc = D3D12ShaderResourceView::CreateDesc(Format::R8G8B8A8_UNorm); ``` +## 示例 + +```cpp +// 创建 2D 纹理 SRV 描述符 +D3D12_SHADER_RESOURCE_VIEW_DESC desc = D3D12ShaderResourceView::CreateDesc(Format::R8G8B8A8_UNorm, D3D12_SRV_DIMENSION_TEXTURE2D, 4); +``` + ## 相关文档 - [D3D12ShaderResourceView](shader-resource-view.md) - 类总览 diff --git a/docs/api/rhi/d3d12/shader-resource-view/destructor.md b/docs/api/rhi/d3d12/shader-resource-view/destructor.md new file mode 100644 index 00000000..bf03a75b --- /dev/null +++ b/docs/api/rhi/d3d12/shader-resource-view/destructor.md @@ -0,0 +1,24 @@ +# D3D12ShaderResourceView::~D3D12ShaderResourceView + +## 函数签名 + +```cpp +~D3D12ShaderResourceView() +``` + +## 描述 + +析构函数，调用 `Shutdown()` 释放资源。 + +## 参数 + +无 + +## 返回值 + +无 + +## 相关文档 + +- [D3D12ShaderResourceView](shader-resource-view.md) - 类总览 +- [D3D12ShaderResourceView::Shutdown](shutdown.md) - 关闭视图 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/shader-resource-view/get-cpu-descriptor-handle.md b/docs/api/rhi/d3d12/shader-resource-view/get-cpu-descriptor-handle.md index 6b07bb54..d105d0f6 100644 --- a/docs/api/rhi/d3d12/shader-resource-view/get-cpu-descriptor-handle.md +++ b/docs/api/rhi/d3d12/shader-resource-view/get-cpu-descriptor-handle.md @@ -24,6 +24,14 @@ O(1) D3D12_CPU_DESCRIPTOR_HANDLE handle = srv->GetCPUDescriptorHandle(); ``` +## 示例 + +```cpp +D3D12_CPU_DESCRIPTOR_HANDLE handle = srv->GetCPUDescriptorHandle(); +// 用于绑定到命令列表 +commandList->SetGraphicsRootDescriptorTable(0, handle); +``` + ## 相关文档 - [D3D12ShaderResourceView](shader-resource-view.md) - 类总览 diff --git a/docs/api/rhi/d3d12/shader-resource-view/initialize.md b/docs/api/rhi/d3d12/shader-resource-view/initialize.md new file mode 100644 index 00000000..5464d8d2 --- /dev/null +++ b/docs/api/rhi/d3d12/shader-resource-view/initialize.md @@ -0,0 +1,41 @@ +# D3D12ShaderResourceView::Initialize + +## 函数签名 + +```cpp +void Initialize(ID3D12Device* device, ID3D12Resource* resource, const D3D12_SHADER_RESOURCE_VIEW_DESC* desc = nullptr) +``` + +## 描述 + +初始化 D3D12 着色器资源视图。根据提供的资源创建 D3D12 着色器资源视图。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针，用于创建视图 | +| `resource` | `ID3D12Resource*` | D3D12 资源指针 | +| `desc` | `const D3D12_SHADER_RESOURCE_VIEW_DESC*` | 着色器资源视图描述符（可选，默认 nullptr） | + +## 返回值 + +无 + +## 示例 + +```cpp +// 创建 SRV，使用默认描述符 +D3D12ShaderResourceView srv; +srv.Initialize(device, texture, nullptr); + +// 创建 SRV，使用自定义描述符 +D3D12_SHADER_RESOURCE_VIEW_DESC desc = D3D12ShaderResourceView::CreateDesc(Format::R8G8B8A8_UNorm); +srv.Initialize(device, texture, &desc); +``` + +## 相关文档 + +- [D3D12ShaderResourceView::InitializeAt](initialize-at.md) - 在指定位置初始化 +- [D3D12ShaderResourceView::Shutdown](shutdown.md) - 关闭视图 +- [D3D12ShaderResourceView](shader-resource-view.md) - 类总览 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/shader-resource-view/shader-resource-view.md b/docs/api/rhi/d3d12/shader-resource-view/shader-resource-view.md index fe40f876..7d8278c6 100644 --- a/docs/api/rhi/d3d12/shader-resource-view/shader-resource-view.md +++ b/docs/api/rhi/d3d12/shader-resource-view/shader-resource-view.md @@ -2,18 +2,47 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 着色器资源视图的 D3D12 实现。 +**描述**: DirectX 12 着色器资源视图（Shader Resource View, SRV）的 D3D12 实现。SRV 允许着色器访问纹理、缓冲区等资源。 + +## 概述 + +`D3D12ShaderResourceView` 封装了 D3D12 的 `CreateShaderResourceView` 操作，提供两种初始化方式： +- `Initialize`: 自动分配描述符句柄 +- `InitializeAt`: 在预分配的描述符位置创建视图 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化着色器资源视图 | +| [`D3D12ShaderResourceView()`](constructor.md) | 构造函数 | +| [`~D3D12ShaderResourceView()`](destructor.md) | 析构函数 | +| [`Initialize`](initialize.md) | 初始化着色器资源视图 | | [`InitializeAt`](initialize-at.md) | 在指定位置初始化 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭着色器资源视图 | +| [`Shutdown`](shutdown.md) | 关闭着色器资源视图 | | [`GetCPUDescriptorHandle`](get-cpu-descriptor-handle.md) | 获取 CPU 描述符句柄 | | [`CreateDesc`](create-desc.md) | 创建描述符（静态） | +## 使用示例 + +```cpp +// 创建设备和资源 +ID3D12Device* device; +ID3D12Resource* texture; +// ... 初始化设备资源 ... + +// 创建 SRV +D3D12ShaderResourceView* srv = new D3D12ShaderResourceView(); +srv->Initialize(device, texture, nullptr); + +// 获取描述符句柄用于绑定 +D3D12_CPU_DESCRIPTOR_HANDLE handle = srv->GetCPUDescriptorHandle(); + +// 清理 +srv->Shutdown(); +delete srv; +``` + ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端概览](../d3d12.md) +- [OpenGL 后端](../../opengl/overview.md) diff --git a/docs/api/rhi/d3d12/shader-resource-view/shutdown.md b/docs/api/rhi/d3d12/shader-resource-view/shutdown.md new file mode 100644 index 00000000..2c77ad1c --- /dev/null +++ b/docs/api/rhi/d3d12/shader-resource-view/shutdown.md @@ -0,0 +1,30 @@ +# D3D12ShaderResourceView::Shutdown + +## 函数签名 + +```cpp +void Shutdown() +``` + +## 描述 + +关闭 D3D12 着色器资源视图并释放相关资源。 + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +```cpp +srv.Shutdown(); +``` + +## 相关文档 + +- [D3D12ShaderResourceView::Initialize](initialize.md) - 初始化视图 +- [D3D12ShaderResourceView](shader-resource-view.md) - 类总览 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/shader/set-float.md b/docs/api/rhi/d3d12/shader/set-float.md new file mode 100644 index 00000000..cf41a6cf --- /dev/null +++ b/docs/api/rhi/d3d12/shader/set-float.md @@ -0,0 +1,36 @@ +# D3D12Shader::SetFloat + +## 函数签名 + +```cpp +void SetFloat(const char* name, float value) override +``` + +## 中文描述 + +设置着色器中的浮点型 uniform 变量。当前实现为空（stub）。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `name` | `const char*` | 变量名称 | +| `value` | `float` | 变量值 | + +## 返回值 + +无 + +## 示例 + +```cpp +shader->SetFloat("scale", 2.0f); +``` + +## 相关文档 + +- [D3D12Shader](shader.md) - 类总览 +- [SetInt](set-int.md) - 设置整型 uniform +- [SetVec3](set-vec3.md) - 设置 Vec3 uniform +- [SetVec4](set-vec4.md) - 设置 Vec4 uniform +- [SetMat4](set-mat4.md) - 设置矩阵 uniform diff --git a/docs/api/rhi/d3d12/shader/set-int.md b/docs/api/rhi/d3d12/shader/set-int.md new file mode 100644 index 00000000..6795a504 --- /dev/null +++ b/docs/api/rhi/d3d12/shader/set-int.md @@ -0,0 +1,36 @@ +# D3D12Shader::SetInt + +## 函数签名 + +```cpp +void SetInt(const char* name, int value) override +``` + +## 中文描述 + +设置着色器中的整型 uniform 变量。当前实现为空（stub）。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `name` | `const char*` | 变量名称 | +| `value` | `int` | 变量值 | + +## 返回值 + +无 + +## 示例 + +```cpp +shader->SetInt("useLighting", 1); +``` + +## 相关文档 + +- [D3D12Shader](shader.md) - 类总览 +- [SetFloat](set-float.md) - 设置浮点型 uniform +- [SetVec3](set-vec3.md) - 设置 Vec3 uniform +- [SetVec4](set-vec4.md) - 设置 Vec4 uniform +- [SetMat4](set-mat4.md) - 设置矩阵 uniform diff --git a/docs/api/rhi/d3d12/shader/set-mat4.md b/docs/api/rhi/d3d12/shader/set-mat4.md new file mode 100644 index 00000000..81936245 --- /dev/null +++ b/docs/api/rhi/d3d12/shader/set-mat4.md @@ -0,0 +1,37 @@ +# D3D12Shader::SetMat4 + +## 函数签名 + +```cpp +void SetMat4(const char* name, const float* value) override +``` + +## 中文描述 + +设置着色器中的 4x4 矩阵 uniform 变量。当前实现为空（stub）。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `name` | `const char*` | 变量名称 | +| `value` | `const float*` | 矩阵数据指针（16 个 float 元素，按列主序存储） | + +## 返回值 + +无 + +## 示例 + +```cpp +float matrixData[16] = { /* 4x4 矩阵数据 */ }; +shader->SetMat4("transform", matrixData); +``` + +## 相关文档 + +- [D3D12Shader](shader.md) - 类总览 +- [SetInt](set-int.md) - 设置整型 uniform +- [SetFloat](set-float.md) - 设置浮点型 uniform +- [SetVec3](set-vec3.md) - 设置 Vec3 uniform +- [SetVec4](set-vec4.md) - 设置 Vec4 uniform diff --git a/docs/api/rhi/d3d12/shader/set-uniforms.md b/docs/api/rhi/d3d12/shader/set-uniforms.md deleted file mode 100644 index bf04a346..00000000 --- a/docs/api/rhi/d3d12/shader/set-uniforms.md +++ /dev/null @@ -1,46 +0,0 @@ -# D3D12Shader::SetUniforms - -## 函数签名 - -```cpp -void SetInt(const char* name, int value) override -void SetFloat(const char* name, float value) override -void SetVec3(const char* name, float x, float y, float z) override -void SetVec4(const char* name, float x, float y, float z, float w) override -void SetMat4(const char* name, const float* value) override -``` - -## 中文描述 - -设置着色器 uniform 变量。当前实现为空（stub）。 - -## 参数 - -| 参数 | 类型 | 描述 | -|------|------|------| -| `name` | `const char*` | 变量名称 | -| `value` | 各种类型 | 变量值 | -| `x, y, z, w` | `float` | 向量分量 | -| `value` | `const float*` | 矩阵数据指针 | - -## 返回值 - -无 - -## 复杂度 - -O(1) - -## 示例 - -```cpp -shader->SetInt("useLighting", 1); -shader->SetFloat("scale", 2.0f); -shader->SetVec3("lightPos", 1.0f, 2.0f, 3.0f); -shader->SetVec4("color", 1.0f, 0.0f, 0.0f, 1.0f); -shader->SetMat4("transform", matrixData); -``` - -## 相关文档 - -- [D3D12Shader](shader.md) - 类总览 diff --git a/docs/api/rhi/d3d12/shader/set-vec3.md b/docs/api/rhi/d3d12/shader/set-vec3.md new file mode 100644 index 00000000..0f227fff --- /dev/null +++ b/docs/api/rhi/d3d12/shader/set-vec3.md @@ -0,0 +1,38 @@ +# D3D12Shader::SetVec3 + +## 函数签名 + +```cpp +void SetVec3(const char* name, float x, float y, float z) override +``` + +## 中文描述 + +设置着色器中的三维向量 uniform 变量。当前实现为空（stub）。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `name` | `const char*` | 变量名称 | +| `x` | `float` | 向量 X 分量 | +| `y` | `float` | 向量 Y 分量 | +| `z` | `float` | 向量 Z 分量 | + +## 返回值 + +无 + +## 示例 + +```cpp +shader->SetVec3("lightPos", 1.0f, 2.0f, 3.0f); +``` + +## 相关文档 + +- [D3D12Shader](shader.md) - 类总览 +- [SetInt](set-int.md) - 设置整型 uniform +- [SetFloat](set-float.md) - 设置浮点型 uniform +- [SetVec4](set-vec4.md) - 设置 Vec4 uniform +- [SetMat4](set-mat4.md) - 设置矩阵 uniform diff --git a/docs/api/rhi/d3d12/shader/set-vec4.md b/docs/api/rhi/d3d12/shader/set-vec4.md new file mode 100644 index 00000000..a9ce89e3 --- /dev/null +++ b/docs/api/rhi/d3d12/shader/set-vec4.md @@ -0,0 +1,39 @@ +# D3D12Shader::SetVec4 + +## 函数签名 + +```cpp +void SetVec4(const char* name, float x, float y, float z, float w) override +``` + +## 中文描述 + +设置着色器中的四维向量 uniform 变量。当前实现为空（stub）。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `name` | `const char*` | 变量名称 | +| `x` | `float` | 向量 X 分量 | +| `y` | `float` | 向量 Y 分量 | +| `z` | `float` | 向量 Z 分量 | +| `w` | `float` | 向量 W 分量 | + +## 返回值 + +无 + +## 示例 + +```cpp +shader->SetVec4("color", 1.0f, 0.0f, 0.0f, 1.0f); +``` + +## 相关文档 + +- [D3D12Shader](shader.md) - 类总览 +- [SetInt](set-int.md) - 设置整型 uniform +- [SetFloat](set-float.md) - 设置浮点型 uniform +- [SetVec3](set-vec3.md) - 设置 Vec3 uniform +- [SetMat4](set-mat4.md) - 设置矩阵 uniform diff --git a/docs/api/rhi/d3d12/shader/shader.md b/docs/api/rhi/d3d12/shader/shader.md index 0acf341b..dfe21fe0 100644 --- a/docs/api/rhi/d3d12/shader/shader.md +++ b/docs/api/rhi/d3d12/shader/shader.md @@ -2,6 +2,8 @@ **命名空间**: `XCEngine::RHI` +**类型**: 类 (继承自 `RHIShader`) + **描述**: DirectX 12 着色器的 D3D12 实现，继承自 `RHIShader`。 ## 公共方法 @@ -10,19 +12,35 @@ |------|------| | [`CompileFromFile`](../../shader/compile-from-file.md) | 从文件编译着色器 | | [`Compile`](../../shader/compile.md) | 从源码编译着色器 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭着色器 | +| [`Shutdown`](../../shader/shutdown.md) | 关闭着色器 | | [`GetD3D12Bytecode`](get-d3d12-bytecode.md) | 获取 D3D12 字节码 | | [`GetBytecode`](get-bytecode.md) | 获取字节码 | | [`GetBytecodeSize`](get-bytecode-size.md) | 获取字节码大小 | -| [`GetType`](../../command-queue/get-type.md) | 获取着色器类型 | +| [`GetType`](../../shader/get-type.md) | 获取着色器类型 | | [`GetInputLayout`](get-input-layout.md) | 获取输入布局 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| [`GetNativeHandle`](../../shader/get-native-handle.md) | 获取原生句柄 | | [`IsValid`](../../shader/is-valid.md) | 检查是否有效 | | [`Bind`](../../shader/bind.md) | 绑定着色器 | | [`Unbind`](../../shader/unbind.md) | 解绑着色器 | -| [`SetUniforms`](set-uniforms.md) | 设置 uniform 变量 | +| [`SetInt`](set-int.md) | 设置整型 uniform | +| [`SetFloat`](set-float.md) | 设置浮点型 uniform | +| [`SetVec3`](set-vec3.md) | 设置 Vec3 uniform | +| [`SetVec4`](set-vec4.md) | 设置 Vec4 uniform | +| [`SetMat4`](set-mat4.md) | 设置矩阵 uniform | + +## 使用示例 + +```cpp +#include "XCEngine/RHI/D3D12/D3D12Shader.h" + +auto shader = std::make_unique(); +if (shader->CompileFromFile(L"shaders/vertex.hlsl", "VSMain", "vs_6_0")) { + D3D12_SHADER_BYTECODE bytecode = shader->GetD3D12Bytecode(); + // 使用字节码创建 PSO... +} +``` ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../d3d12.md) - [RHIShader](../../shader/shader.md) - 抽象着色器接口 diff --git a/docs/api/rhi/d3d12/swap-chain/constructor.md b/docs/api/rhi/d3d12/swap-chain/constructor.md new file mode 100644 index 00000000..4e3d43d7 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/constructor.md @@ -0,0 +1,26 @@ +# D3D12SwapChain::D3D12SwapChain + +## 函数签名 + +```cpp +D3D12SwapChain() +``` + +## 中文描述 + +D3D12SwapChain 类的构造函数，创建一个空的交换链实例。 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12SwapChain* swapChain = new D3D12SwapChain(); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 +- [~D3D12SwapChain](destructor.md) - 析构函数 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/swap-chain/destructor.md b/docs/api/rhi/d3d12/swap-chain/destructor.md new file mode 100644 index 00000000..c8f9a27e --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/destructor.md @@ -0,0 +1,21 @@ +# D3D12SwapChain::~D3D12SwapChain + +## 函数签名 + +```cpp +~D3D12SwapChain() override +``` + +## 中文描述 + +D3D12SwapChain 类的析构函数，调用 `Shutdown()` 释放资源。 + +## 复杂度 + +O(n) - 取决于管理的缓冲区数量 + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 +- [D3D12SwapChain](constructor.md) - 构造函数 +- [Shutdown](../../swap-chain/shutdown.md) - 关闭交换链 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/swap-chain/get-native-handle.md b/docs/api/rhi/d3d12/swap-chain/get-native-handle.md new file mode 100644 index 00000000..de3f9066 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/get-native-handle.md @@ -0,0 +1,35 @@ +# D3D12SwapChain::GetNativeHandle + +## 函数签名 + +```cpp +void* GetNativeHandle() override +``` + +## 中文描述 + +获取交换链的原生 DXGI 指针。此方法返回底层 `IDXGISwapChain3` 接口的指针，可用于与原生 D3D12 代码互操作。 + +## 参数 + +无 + +## 返回值 + +`void*` - 指向 `IDXGISwapChain3` 接口的指针 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +void* nativeHandle = swapChain->GetNativeHandle(); +IDXGISwapChain3* swapChain3 = reinterpret_cast(nativeHandle); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 +- [GetSwapChain](get-swap-chain.md) - 获取 D3D12 交换链接口 diff --git a/docs/api/rhi/d3d12/swap-chain/initialize-from-factory.md b/docs/api/rhi/d3d12/swap-chain/initialize-from-factory.md new file mode 100644 index 00000000..4879a4cb --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/initialize-from-factory.md @@ -0,0 +1,42 @@ +# D3D12SwapChain::Initialize (from factory) + +## 函数签名 + +```cpp +bool Initialize(IDXGIFactory4* factory, ID3D12CommandQueue* commandQueue, HWND windowHandle, uint32_t width, uint32_t height, uint32_t bufferCount = 2) +``` + +## 中文描述 + +从 DXGI 工厂创建新的交换链。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `factory` | `IDXGIFactory4*` | DXGI 工厂指针 | +| `commandQueue` | `ID3D12CommandQueue*` | 命令队列指针 | +| `windowHandle` | `HWND` | 窗口句柄 | +| `width` | `uint32_t` | 宽度 | +| `height` | `uint32_t` | 高度 | +| `bufferCount` | `uint32_t` | 缓冲区数量（默认 2） | + +## 返回值 + +`bool` - 初始化是否成功 + +## 复杂度 + +O(n) - 取决于缓冲区数量和大小 + +## 示例 + +```cpp +D3D12SwapChain swapChain; +swapChain->Initialize(factory, commandQueue, hwnd, 1920, 1080, 2); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 +- [Initialize (from swapchain)](initialize-from-swapchain.md) - 从已有交换链初始化 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/swap-chain/initialize-from-swapchain.md b/docs/api/rhi/d3d12/swap-chain/initialize-from-swapchain.md index 3e9d1116..a57535b5 100644 --- a/docs/api/rhi/d3d12/swap-chain/initialize-from-swapchain.md +++ b/docs/api/rhi/d3d12/swap-chain/initialize-from-swapchain.md @@ -1,25 +1,22 @@ -# D3D12SwapChain::Initialize +# D3D12SwapChain::Initialize (from swapchain) ## 函数签名 ```cpp -bool Initialize(IDXGIFactory4* factory, ID3D12CommandQueue* commandQueue, HWND windowHandle, uint32_t width, uint32_t height, uint32_t bufferCount = 2) +bool Initialize(IDXGISwapChain* swapChain, uint32_t width, uint32_t height) ``` ## 中文描述 -从工厂创建新的交换链。 +从已有的 DXGI 交换链对象初始化 D3D12SwapChain。 ## 参数 | 参数 | 类型 | 描述 | |------|------|------| -| `factory` | `IDXGIFactory4*` | DXGI 工厂指针 | -| `commandQueue` | `ID3D12CommandQueue*` | 命令队列指针 | -| `windowHandle` | `HWND` | 窗口句柄 | -| `width` | `uint32_t` | 宽度 | -| `height` | `uint32_t` | 高度 | -| `bufferCount` | `uint32_t` | 缓冲区数量（默认 2） | +| `swapChain` | `IDXGISwapChain*` | 已存在的 DXGI 交换链指针 | +| `width` | `uint32_t` | 交换链宽度 | +| `height` | `uint32_t` | 交换链高度 | ## 返回值 @@ -27,14 +24,16 @@ bool Initialize(IDXGIFactory4* factory, ID3D12CommandQueue* commandQueue, HWND w ## 复杂度 -O(n) - 取决于缓冲区数量和大小 +O(n) - 取决于缓冲区数量 ## 示例 ```cpp -swapChain->Initialize(factory, commandQueue, hwnd, 1920, 1080, 2); +D3D12SwapChain swapChain; +swapChain->Initialize(existingSwapChain, 1920, 1080); ``` ## 相关文档 - [D3D12SwapChain](swap-chain.md) - 类总览 +- [Initialize (from factory)](initialize-from-factory.md) - 从工厂创建新交换链 \ No newline at end of file diff --git a/docs/api/rhi/d3d12/swap-chain/resize.md b/docs/api/rhi/d3d12/swap-chain/resize.md new file mode 100644 index 00000000..6f068661 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/resize.md @@ -0,0 +1,42 @@ +# D3D12SwapChain::Resize + +## 函数签名 + +```cpp +void Resize(uint32_t width, uint32_t height) override +``` + +## 中文描述 + +调整交换链的缓冲区尺寸。此方法调用 DXGI 交换链的 `ResizeBuffers`，更新内部存储的宽度和高度。 + +注意：调用此方法后，之前获取的后台缓冲区指针可能失效，需要重新调用 `GetBackBuffer` 获取。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `width` | `uint32_t` | 新的宽度 | +| `height` | `uint32_t` | 新的高度 | + +## 返回值 + +无 + +## 复杂度 + +O(n) - 取决于缓冲区数量和大小 + +## 示例 + +```cpp +// 窗口大小改变时调整交换链 +void OnWindowResize(uint32_t newWidth, uint32_t newHeight) { + swapChain.Resize(newWidth, newHeight); +} +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 +- [GetBackBuffer](get-back-buffer.md) - 获取后台缓冲区 diff --git a/docs/api/rhi/d3d12/swap-chain/shutdown.md b/docs/api/rhi/d3d12/swap-chain/shutdown.md new file mode 100644 index 00000000..81882862 --- /dev/null +++ b/docs/api/rhi/d3d12/swap-chain/shutdown.md @@ -0,0 +1,40 @@ +# D3D12SwapChain::Shutdown + +## 函数签名 + +```cpp +void Shutdown() override +``` + +## 中文描述 + +关闭交换链并释放所有相关资源。此方法会重置交换链 COM 指针，释放后台缓冲区。 + +调用此方法后，交换链实例可重新调用 `Initialize` 进行初始化。 + +## 参数 + +无 + +## 返回值 + +无 + +## 复杂度 + +O(n) - 取决于缓冲区数量 + +## 示例 + +```cpp +D3D12SwapChain swapChain; +swapChain.Initialize(factory, commandQueue, hwnd, 1920, 1080); + +// 使用完毕后关闭 +swapChain.Shutdown(); +``` + +## 相关文档 + +- [D3D12SwapChain](swap-chain.md) - 类总览 +- [Initialize (from factory)](initialize-from-factory.md) - 创建交换链 diff --git a/docs/api/rhi/d3d12/swap-chain/swap-chain.md b/docs/api/rhi/d3d12/swap-chain/swap-chain.md index 6d742855..9809a32e 100644 --- a/docs/api/rhi/d3d12/swap-chain/swap-chain.md +++ b/docs/api/rhi/d3d12/swap-chain/swap-chain.md @@ -2,28 +2,60 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 交换链的 D3D12 实现，继承自 `RHISwapChain`。 +**继承自**: `RHISwapChain` + +## 概述 + +`D3D12SwapChain` 是 DirectX 12 交换链的 D3D12 实现，继承自 `RHISwapChain`。该类负责管理 DXGI 交换链的创建、呈现、分辨率调整等操作，是 D3D12 RHI 后端的核心组件之一。 + +交换链维护多个后台缓冲区用于双缓冲或三缓冲渲染，通过 `Present` 方法将已完成渲染的缓冲区呈现到屏幕。 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](initialize-from-swapchain.md) | 从交换链初始化 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭交换链 | +| [`D3D12SwapChain`](constructor.md) | 构造函数 | +| [`~D3D12SwapChain`](destructor.md) | 析构函数 | +| [`Initialize (from factory)`](initialize-from-factory.md) | 从工厂创建新交换链 | +| [`Initialize (from swapchain)`](initialize-from-swapchain.md) | 从已有交换链初始化 | +| [`Shutdown`](shutdown.md) | 关闭交换链 | | [`GetCurrentBackBufferIndex`](get-current-back-buffer-index.md) | 获取当前后台缓冲区索引 | | [`GetCurrentBackBuffer`](get-current-back-buffer.md) | 获取当前后台缓冲区 | | [`GetBackBuffer`](get-back-buffer.md) | 获取后台缓冲区 | | [`Present`](present.md) | 呈现画面 | -| [`Resize`](../../swap-chain/resize.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`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | | [`GetSwapChain`](get-swap-chain.md) | 获取 D3D12 交换链 | +## 使用示例 + +```cpp +// 创建交换链 +D3D12SwapChain swapChain; +swapChain.Initialize(factory, commandQueue, hwnd, 1920, 1080, 2); + +// 渲染循环 +while (!swapChain.ShouldClose()) { + swapChain.PollEvents(); + + // 获取当前后台缓冲区进行渲染 + D3D12Texture* backBuffer = swapChain.GetCurrentBackBuffer(); + + // ... 渲染操作 ... + + // 呈现 + swapChain.Present(1, 0); +} + +// 关闭 +swapChain.Shutdown(); +``` + ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) -- [RHISwapChain](../../swap-chain/swap-chain.md) - 抽象交换链接口 +- [D3D12 后端总览](../d3d12.md) diff --git a/docs/api/rhi/d3d12/texture/ctor.md b/docs/api/rhi/d3d12/texture/ctor.md new file mode 100644 index 00000000..95b18fe0 --- /dev/null +++ b/docs/api/rhi/d3d12/texture/ctor.md @@ -0,0 +1,42 @@ +# D3D12Texture::D3D12Texture + +## 函数签名 + +```cpp +D3D12Texture(); +``` + +## 中文描述 + +默认构造函数，创建一个空的 D3D12Texture 对象。需要调用 `Initialize` 或其他初始化方法才能使用。 + +## 参数 + +无 + +## 返回值 + +无 + +## 线程安全 + +非线程安全，对象构造时无需同步。 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +D3D12Texture texture; +// 需要调用 Initialize 等方法进行初始化 +texture.Initialize(device, desc); +``` + +## 相关文档 + +- [D3D12Texture](texture.md) - 类总览 +- [Initialize](initialize.md) - 初始化纹理 +- [InitializeFromData](initialize-from-data.md) - 从数据初始化 +- [InitializeDepthStencil](initialize-depth-stencil.md) - 初始化深度模板纹理 diff --git a/docs/api/rhi/d3d12/texture/dtor.md b/docs/api/rhi/d3d12/texture/dtor.md new file mode 100644 index 00000000..cce36b2a --- /dev/null +++ b/docs/api/rhi/d3d12/texture/dtor.md @@ -0,0 +1,42 @@ +# D3D12Texture::~D3D12Texture + +## 函数签名 + +```cpp +~D3D12Texture() override; +``` + +## 中文描述 + +析构函数，调用 `Shutdown` 释放资源并销毁 D3D12 资源对象。 + +## 参数 + +无 + +## 返回值 + +无 + +## 线程安全 + +非线程安全，请在所有 GPU 操作完成后销毁对象。 + +## 复杂度 + +O(n) - 取决于资源释放时间 + +## 示例 + +```cpp +{ + D3D12Texture texture; + texture.Initialize(device, desc); + // ... 使用 texture ... +} // 超出作用域时自动调用析构函数，释放资源 +``` + +## 相关文档 + +- [D3D12Texture](texture.md) - 类总览 +- [Shutdown](../../../threading/task-system/shutdown.md) - 关闭纹理 diff --git a/docs/api/rhi/d3d12/texture/get-size.md b/docs/api/rhi/d3d12/texture/get-size.md new file mode 100644 index 00000000..d4717770 --- /dev/null +++ b/docs/api/rhi/d3d12/texture/get-size.md @@ -0,0 +1,32 @@ +# D3D12Texture::GetSize + +## 函数签名 + +```cpp +size_t GetSize() const +``` + +## 中文描述 + +计算并返回纹理的总大小（字节）。计算方式为 `宽度 × 高度 × 深度或数组大小`。 + +## 返回值 + +`size_t` - 纹理大小（字节） + +## 复杂度 + +O(1) + +## 示例 + +```cpp +size_t size = texture->GetSize(); +printf("Texture size: %zu bytes\n", size); +``` + +## 相关文档 + +- [D3D12Texture](texture.md) - 类总览 +- [GetWidth](../../texture/get-width.md) - 获取纹理宽度 +- [GetHeight](../../texture/get-height.md) - 获取纹理高度 diff --git a/docs/api/rhi/d3d12/texture/initialize-from-existing.md b/docs/api/rhi/d3d12/texture/initialize-from-existing.md new file mode 100644 index 00000000..9b812f94 --- /dev/null +++ b/docs/api/rhi/d3d12/texture/initialize-from-existing.md @@ -0,0 +1,50 @@ +# D3D12Texture::InitializeFromExisting + +## 函数签名 + +```cpp +bool InitializeFromExisting(ID3D12Resource* resource); +``` + +## 中文描述 + +从已存在的 D3D12 纹理资源初始化纹理包装类，不分配新资源。此方法用于包装外部创建的纹理资源，例如从文件系统加载的纹理或与其他 API 共享的资源。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `resource` | `ID3D12Resource*` | 已存在的 D3D12 纹理资源指针，不能为 nullptr | + +## 返回值 + +`bool` - 初始化是否成功。如果 `resource` 为 nullptr，返回 false。 + +## 线程安全 + +非线程安全，请确保在单线程环境中调用。 + +## 复杂度 + +O(1) + +## 示例 + +```cpp +ComPtr externalResource; +// 外部创建或获取的 D3D12 资源 +device->CreateReservedResource(&desc, initialState, nullptr, IID_PPV_ARGS(&externalResource)); + +D3D12Texture texture; +if (texture.InitializeFromExisting(externalResource.Get())) { + // 成功包装外部资源 + // 注意：外部资源的管理责任保持不变 +} +``` + +## 相关文档 + +- [D3D12Texture](texture.md) - 类总览 +- [Initialize](initialize.md) - 创建新纹理 +- [InitializeFromData](initialize-from-data.md) - 从数据初始化 +- [InitializeDepthStencil](initialize-depth-stencil.md) - 初始化深度模板纹理 diff --git a/docs/api/rhi/d3d12/texture/initialize.md b/docs/api/rhi/d3d12/texture/initialize.md new file mode 100644 index 00000000..d01a963c --- /dev/null +++ b/docs/api/rhi/d3d12/texture/initialize.md @@ -0,0 +1,49 @@ +# D3D12Texture::Initialize + +## 函数签名 + +```cpp +bool Initialize(ID3D12Device* device, const D3D12_RESOURCE_DESC& desc, D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON) +``` + +## 中文描述 + +分配并初始化一个 D3D12 纹理资源。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `desc` | `const D3D12_RESOURCE_DESC&` | 纹理资源描述符 | +| `initialState` | `D3D12_RESOURCE_STATES` | 初始资源状态（默认 D3D12_RESOURCE_STATE_COMMON） | + +## 返回值 + +`bool` - 初始化是否成功 + +## 复杂度 + +O(n) - 取决于纹理大小 + +## 示例 + +```cpp +D3D12_RESOURCE_DESC desc = {}; +desc.Dimension = D3D12_RESOURCE_DIMENSION_TEXTURE2D; +desc.Width = 1920; +desc.Height = 1080; +desc.Format = DXGI_FORMAT_R8G8B8A8_UNORM; +desc.Flags = D3D12_RESOURCE_FLAG_NONE; + +D3D12Texture texture; +if (texture.Initialize(device, desc)) { + // 纹理初始化成功 +} +``` + +## 相关文档 + +- [D3D12Texture](texture.md) - 类总览 +- [InitializeFromData](initialize-from-data.md) - 从数据初始化 +- [InitializeDepthStencil](initialize-depth-stencil.md) - 初始化深度模板纹理 diff --git a/docs/api/rhi/d3d12/texture/texture.md b/docs/api/rhi/d3d12/texture/texture.md index fe55dfaf..b68a7d8d 100644 --- a/docs/api/rhi/d3d12/texture/texture.md +++ b/docs/api/rhi/d3d12/texture/texture.md @@ -8,10 +8,13 @@ | 方法 | 描述 | |------|------| -| [`InitializeFromExisting`](../buffer/initialize-from-existing.md) | 从现有资源初始化 | +| [`D3D12Texture`](ctor.md) | 默认构造函数 | +| [`~D3D12Texture`](dtor.md) | 析构函数 | +| [`Initialize`](initialize.md) | 初始化纹理 | +| [`InitializeFromExisting`](initialize-from-existing.md) | 从现有资源初始化 | | [`InitializeFromData`](initialize-from-data.md) | 从数据初始化纹理 | | [`InitializeDepthStencil`](initialize-depth-stencil.md) | 初始化深度模板纹理 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭纹理 | +| [`Shutdown`](../../texture/shutdown.md) | 关闭纹理 | | [`GetResource`](../buffer/get-resource.md) | 获取 D3D12 资源 | | [`GetDesc`](../buffer/get-desc.md) | 获取纹理描述符 | | [`GetWidth`](../../texture/get-width.md) | 获取纹理宽度 | @@ -20,16 +23,16 @@ | [`GetMipLevels`](../../texture/get-mip-levels.md) | 获取 Mip 级别 | | [`GetArraySize`](get-array-size.md) | 获取数组大小 | | [`GetGPUAddress`](../buffer/get-gpu-address.md) | 获取 GPU 地址 | -| [`GetSize`](../../buffer/get-size.md) | 获取纹理大小 | -| [`GetName`](../../buffer/get-name.md) | 获取纹理名称 | -| [`SetName`](../../buffer/set-name.md) | 设置纹理名称 | +| [`GetSize`](get-size.md) | 获取纹理大小 | +| [`GetName`](../../texture/get-name.md) | 获取纹理名称 | +| [`SetName`](../../texture/set-name.md) | 设置纹理名称 | | [`GetFormat`](../../texture/get-format.md) | 获取纹理格式 | | [`GetTextureType`](../../texture/get-texture-type.md) | 获取纹理类型 | -| [`GetState`](../../buffer/get-state.md) | 获取资源状态 | -| [`SetState`](../../buffer/set-state.md) | 设置资源状态 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| [`GetState`](../../texture/get-state.md) | 获取资源状态 | +| [`SetState`](../../texture/set-state.md) | 设置资源状态 | +| [`GetNativeHandle`](../../texture/get-native-handle.md) | 获取原生句柄 | ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端概览](../d3d12.md) - [RHITexture](../../texture/texture.md) - 抽象纹理接口 diff --git a/docs/api/rhi/d3d12/types/types.md b/docs/api/rhi/d3d12/types/types.md index d4a60a2f..26d4d396 100644 --- a/docs/api/rhi/d3d12/types/types.md +++ b/docs/api/rhi/d3d12/types/types.md @@ -20,5 +20,5 @@ ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) -- [D3D12Enum](../../enums/enums.md) - 枚举值转换 +- [D3D12 后端总览](../d3d12.md) +- [D3D12Enums](../enums/enums.md) - 枚举值转换 diff --git a/docs/api/rhi/d3d12/unordered-access-view/constructor.md b/docs/api/rhi/d3d12/unordered-access-view/constructor.md new file mode 100644 index 00000000..7904f18c --- /dev/null +++ b/docs/api/rhi/d3d12/unordered-access-view/constructor.md @@ -0,0 +1,22 @@ +# D3D12UnorderedAccessView::D3D12UnorderedAccessView + +## 函数签名 + +```cpp +D3D12UnorderedAccessView(); +``` + +## 中文描述 + +构造一个空的 `D3D12UnorderedAccessView` 对象。 + +## 示例 + +```cpp +D3D12UnorderedAccessView uav; +``` + +## 相关文档 + +- [D3D12UnorderedAccessView](unordered-access-view.md) - 类总览 +- [Initialize](initialize.md) - 初始化方法 diff --git a/docs/api/rhi/d3d12/unordered-access-view/destructor.md b/docs/api/rhi/d3d12/unordered-access-view/destructor.md new file mode 100644 index 00000000..92571ea6 --- /dev/null +++ b/docs/api/rhi/d3d12/unordered-access-view/destructor.md @@ -0,0 +1,16 @@ +# D3D12UnorderedAccessView::~D3D12UnorderedAccessView + +## 函数签名 + +```cpp +~D3D12UnorderedAccessView(); +``` + +## 中文描述 + +销毁 `D3D12UnorderedAccessView` 对象，自动调用 `Shutdown`。 + +## 相关文档 + +- [D3D12UnorderedAccessView](unordered-access-view.md) - 类总览 +- [Shutdown](shutdown.md) - 关闭方法 diff --git a/docs/api/rhi/d3d12/unordered-access-view/get-cpu-descriptor-handle.md b/docs/api/rhi/d3d12/unordered-access-view/get-cpu-descriptor-handle.md index 105b13da..84603588 100644 --- a/docs/api/rhi/d3d12/unordered-access-view/get-cpu-descriptor-handle.md +++ b/docs/api/rhi/d3d12/unordered-access-view/get-cpu-descriptor-handle.md @@ -21,7 +21,9 @@ O(1) ## 示例 ```cpp -D3D12_CPU_DESCRIPTOR_HANDLE handle = uav->GetCPUDescriptorHandle(); +D3D12UnorderedAccessView uav; +uav.Initialize(device, resource); +D3D12_CPU_DESCRIPTOR_HANDLE handle = uav.GetCPUDescriptorHandle(); ``` ## 相关文档 diff --git a/docs/api/rhi/d3d12/unordered-access-view/index.md b/docs/api/rhi/d3d12/unordered-access-view/index.md new file mode 100644 index 00000000..fcc6c468 --- /dev/null +++ b/docs/api/rhi/d3d12/unordered-access-view/index.md @@ -0,0 +1,60 @@ +# D3D12UnorderedAccessView + +## 命名空间 + +`XCEngine::RHI` + +## 类型 + +类 (Class) + +## 描述 + +D3D12 无序访问视图 (Unordered Access View, UAV) 封装类，用于在 D3D12 渲染管线中提供对资源的无序读/写访问能力。UAV 允许着色器对资源进行非同步访问，适用于并行计算和延迟渲染等场景。 + +## 概述 + +`D3D12UnorderedAccessView` 封装了 D3D12 UAV 的创建和生命周期管理。UAV 是一种可以同时被 GPU 读取和写入的资源视图，常见用途包括： + +- 计算着色器 (Compute Shader) 的数据存储 +- 延迟渲染中的光照参数存储 +- 粒子系统的位置/速度数据 +- 纹理流式传输缓冲 + +## 公共方法表格 + +| 方法 | 签名 | 描述 | +|------|------|------| +| `Initialize` | `void Initialize(ID3D12Device* device, ID3D12Resource* resource, const D3D12_UNORDERED_ACCESS_VIEW_DESC* desc = nullptr)` | 初始化 UAV，创建 D3D12 无序访问视图 | +| `Shutdown` | `void Shutdown()` | 释放 UAV 相关资源 | +| `GetCPUDescriptorHandle` | `D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const` | 获取 CPU 端的描述符句柄 | + +## 使用示例 + +```cpp +#include "XCEngine/RHI/D3D12/D3D12UnorderedAccessView.h" +#include "XCEngine/RHI/D3D12/D3D12Device.h" + +// 创建设备和资源后... +D3D12Device* device = ...; +ID3D12Resource* bufferResource = ...; + +// 创建无序访问视图 +XCEngine::RHI::D3D12UnorderedAccessView uav; +uav.Initialize(device->GetDevice(), bufferResource, nullptr); + +// 在命令列表中设置 UAV +commandList->SetComputeRootUnorderedAccessView( + parameterIndex, + uav.GetCPUDescriptorHandle() +); + +// 使用完毕后清理 +uav.Shutdown(); +``` + +## 相关文档 + +- [D3D12ShaderResourceView](../shader-resource-view/) +- [D3D12RenderTargetView](../render-target-view/) +- [D3D12ConstantBufferView](../constant-buffer-view/) diff --git a/docs/api/rhi/d3d12/unordered-access-view/initialize.md b/docs/api/rhi/d3d12/unordered-access-view/initialize.md new file mode 100644 index 00000000..c551ab92 --- /dev/null +++ b/docs/api/rhi/d3d12/unordered-access-view/initialize.md @@ -0,0 +1,39 @@ +# D3D12UnorderedAccessView::Initialize + +## 函数签名 + +```cpp +void Initialize( + ID3D12Device* device, + ID3D12Resource* resource, + const D3D12_UNORDERED_ACCESS_VIEW_DESC* desc = nullptr +); +``` + +## 中文描述 + +初始化无序访问视图。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `device` | `ID3D12Device*` | D3D12 设备指针 | +| `resource` | `ID3D12Resource*` | D3D12 资源指针 | +| `desc` | `const D3D12_UNORDERED_ACCESS_VIEW_DESC*` | UAV 描述符，可选 | + +## 返回值 + +无 + +## 示例 + +```cpp +D3D12UnorderedAccessView uav; +uav.Initialize(device, resource, &uavDesc); +``` + +## 相关文档 + +- [D3D12UnorderedAccessView](unordered-access-view.md) - 类总览 +- [Shutdown](shutdown.md) - 关闭方法 diff --git a/docs/api/rhi/d3d12/unordered-access-view/shutdown.md b/docs/api/rhi/d3d12/unordered-access-view/shutdown.md new file mode 100644 index 00000000..eaff5746 --- /dev/null +++ b/docs/api/rhi/d3d12/unordered-access-view/shutdown.md @@ -0,0 +1,28 @@ +# D3D12UnorderedAccessView::Shutdown + +## 函数签名 + +```cpp +void Shutdown(); +``` + +## 中文描述 + +关闭无序访问视图，释放相关资源。 + +## 返回值 + +无 + +## 示例 + +```cpp +D3D12UnorderedAccessView uav; +uav.Initialize(device, resource); +uav.Shutdown(); +``` + +## 相关文档 + +- [D3D12UnorderedAccessView](unordered-access-view.md) - 类总览 +- [Initialize](initialize.md) - 初始化方法 diff --git a/docs/api/rhi/d3d12/unordered-access-view/unordered-access-view.md b/docs/api/rhi/d3d12/unordered-access-view/unordered-access-view.md index 05ec467c..26c6e5d7 100644 --- a/docs/api/rhi/d3d12/unordered-access-view/unordered-access-view.md +++ b/docs/api/rhi/d3d12/unordered-access-view/unordered-access-view.md @@ -2,14 +2,20 @@ **命名空间**: `XCEngine::RHI` -**描述**: DirectX 12 无序访问视图的 D3D12 实现。 +**描述**: DirectX 12 无序访问视图 (Unordered Access View, UAV) 的 D3D12 实现封装类。UAV 允许着色器对资源进行非同步的读写访问，主要用于计算着色器和延迟渲染场景。 + +此类管理 D3D12 UAV 的创建和生命周期，封装了 `ID3D12Resource` 和 CPU 描述符句柄。 ## 公共方法 -| 方法 | 描述 | -|------|------| -| [`GetCPUDescriptorHandle`](get-cpu-descriptor-handle.md) | 获取 CPU 描述符句柄 | +| 方法 | 签名 | 描述 | +|------|------|------| +| [`D3D12UnorderedAccessView`](constructor.md) | `D3D12UnorderedAccessView()` | 默认构造函数 | +| [`~D3D12UnorderedAccessView`](destructor.md) | `~D3D12UnorderedAccessView()` | 析构函数 | +| [`Initialize`](initialize.md) | `void Initialize(ID3D12Device* device, ID3D12Resource* resource, const D3D12_UNORDERED_ACCESS_VIEW_DESC* desc = nullptr)` | 初始化 UAV | +| [`Shutdown`](shutdown.md) | `void Shutdown()` | 释放 UAV 资源 | +| [`GetCPUDescriptorHandle`](get-cpu-descriptor-handle.md) | `D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandle() const` | 获取 CPU 描述符句柄 | ## 相关文档 -- [D3D12 后端总览](../../opengl/overview.md) +- [D3D12 后端总览](../d3d12.md) diff --git a/docs/api/rhi/descriptor-pool/descriptor-pool.md b/docs/api/rhi/descriptor-pool/descriptor-pool.md index cc9ce688..7f73061c 100644 --- a/docs/api/rhi/descriptor-pool/descriptor-pool.md +++ b/docs/api/rhi/descriptor-pool/descriptor-pool.md @@ -4,19 +4,49 @@ **类型**: `class` (abstract) +**头文件**: `XCEngine/RHI/RHIDescriptorPool.h` + **描述**: GPU 描述符堆池抽象接口，用于管理 GPU 描述符的分配和回收。 +## 概述 + +`RHIDescriptorPool` 是 RHI 模块中的抽象类，提供 GPU 描述符堆的统一接口。描述符堆用于存储 GPU 资源视图（如常量缓冲区视图、着色器资源视图、采样器等）。该类管理描述符的分配和回收，支持着色器可见性配置。 + ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../threading/task-system/initialize.md) | 初始化描述符池 | -| [`Shutdown`](../../threading/task-system/shutdown.md) | 关闭并释放资源 | -| [`GetNativeHandle`](../buffer/get-native-handle.md) | 获取原生句柄 | +| [`~RHIDescriptorPool`](destructor.md) | 虚析构函数 | +| [`Initialize`](initialize.md) | 初始化描述符池 | +| [`Shutdown`](shutdown.md) | 关闭并释放资源 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | | [`GetDescriptorCount`](get-descriptor-count.md) | 获取描述符数量 | -| [`GetType`](../command-queue/get-type.md) | 获取描述符类型 | +| [`GetType`](get-type.md) | 获取描述符类型 | + +## 使用示例 + +```cpp +// 创建描述符池 +DescriptorPoolDesc desc; +desc.device = device; +desc.type = DescriptorHeapType::CBV_SRV_UAV; +desc.descriptorCount = 256; +desc.shaderVisible = true; + +RHIDescriptorPool* pool = yourFactory->CreateDescriptorPool(); +if (pool->Initialize(desc)) { + // 获取描述符数量 + uint32_t count = pool->GetDescriptorCount(); + + // 获取原生句柄 + void* handle = pool->GetNativeHandle(); + + // 使用完后关闭 + pool->Shutdown(); +} +delete pool; +``` ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 -- [RHIDevice](../device/device.md) - 创建设备 +- [RHI 模块总览](../rhi.md) - RHI 模块总览 diff --git a/docs/api/rhi/descriptor-pool/destructor.md b/docs/api/rhi/descriptor-pool/destructor.md new file mode 100644 index 00000000..afe49a1c --- /dev/null +++ b/docs/api/rhi/descriptor-pool/destructor.md @@ -0,0 +1,33 @@ +# RHIDescriptorPool::~RHIDescriptorPool + +```cpp +virtual ~RHIDescriptorPool() = default; +``` + +虚析构函数，确保派生类对象能被正确销毁。 + +## 详细描述 + +析构函数是虚函数，允许通过基类指针正确删除派生类对象。在销毁描述符池前，应确保已经调用 [`Shutdown`](shutdown.md) 释放资源。 + +## 参数列表 + +无参数。 + +## 返回值 + +无返回值。 + +## 示例代码 + +```cpp +// 通过基类指针销毁派生类对象 +RHIDescriptorPool* pool = factory->CreateDescriptorPool(); +// ... 使用 pool +delete pool; // 正确调用析构函数 +``` + +## 相关文档 + +- [RHIDescriptorPool 总览](descriptor-pool.md) - 返回类总览 +- [Shutdown](shutdown.md) - 关闭描述符池 diff --git a/docs/api/rhi/descriptor-pool/get-descriptor-count.md b/docs/api/rhi/descriptor-pool/get-descriptor-count.md index 2505223d..98e40393 100644 --- a/docs/api/rhi/descriptor-pool/get-descriptor-count.md +++ b/docs/api/rhi/descriptor-pool/get-descriptor-count.md @@ -6,9 +6,15 @@ virtual uint32_t GetDescriptorCount() const = 0; 获取描述符数量。 -**返回：** 描述符池中的描述符数量 +## 参数列表 -**示例：** +无参数。 + +## 返回值 + +`uint32_t` - 描述符池中的描述符数量 + +## 示例代码 ```cpp uint32_t count = descriptorPool->GetDescriptorCount(); @@ -17,3 +23,6 @@ uint32_t count = descriptorPool->GetDescriptorCount(); ## 相关文档 - [RHIDescriptorPool 总览](descriptor-pool.md) - 返回类总览 +- [Initialize](initialize.md) - 初始化描述符池 +- [Shutdown](shutdown.md) - 关闭描述符池 +- [GetType](get-type.md) - 获取描述符类型 diff --git a/docs/api/rhi/descriptor-pool/get-native-handle.md b/docs/api/rhi/descriptor-pool/get-native-handle.md new file mode 100644 index 00000000..50a5b849 --- /dev/null +++ b/docs/api/rhi/descriptor-pool/get-native-handle.md @@ -0,0 +1,34 @@ +# RHIDescriptorPool::GetNativeHandle + +获取描述符池的原生 API 句柄。 + +## 方法签名 + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +## 详细描述 + +返回描述符池在底层图形 API（DirectX 12/Vulkan）中的原生句柄。用于与原生 API 进行交互。 + +## 参数列表 + +无参数。 + +## 返回值 + +`void*` - 原生 API 句柄指针。DirectX 12 下为 `ID3D12DescriptorHeap*`，Vulkan 下为 `VkDescriptorPool` + +## 示例代码 + +```cpp +void* handle = descriptorPool->GetNativeHandle(); +// 使用原生句柄进行 API 特定操作 +``` + +## 相关文档 + +- [RHIDescriptorPool 总览](descriptor-pool.md) - 返回类总览 +- [GetDescriptorCount](get-descriptor-count.md) - 获取描述符数量 +- [GetType](get-type.md) - 获取描述符类型 diff --git a/docs/api/rhi/descriptor-pool/get-type.md b/docs/api/rhi/descriptor-pool/get-type.md new file mode 100644 index 00000000..1452e166 --- /dev/null +++ b/docs/api/rhi/descriptor-pool/get-type.md @@ -0,0 +1,36 @@ +# RHIDescriptorPool::GetType + +获取描述符堆类型。 + +## 方法签名 + +```cpp +virtual DescriptorHeapType GetType() const = 0; +``` + +## 详细描述 + +返回描述符池所管理的描述符堆类型。类型决定了这个池可以分配哪些类型的描述符。 + +## 参数列表 + +无参数。 + +## 返回值 + +`DescriptorHeapType` - 描述符堆类型枚举值 + +## 示例代码 + +```cpp +DescriptorHeapType type = descriptorPool->GetType(); +if (type == DescriptorHeapType::CBV_SRV_UAV) { + // 处理 CBV/SRV/UAV 描述符 +} +``` + +## 相关文档 + +- [RHIDescriptorPool 总览](descriptor-pool.md) - 返回类总览 +- [GetNativeHandle](get-native-handle.md) - 获取原生句柄 +- [GetDescriptorCount](get-descriptor-count.md) - 获取描述符数量 diff --git a/docs/api/rhi/descriptor-pool/initialize.md b/docs/api/rhi/descriptor-pool/initialize.md new file mode 100644 index 00000000..faaea991 --- /dev/null +++ b/docs/api/rhi/descriptor-pool/initialize.md @@ -0,0 +1,45 @@ +# RHIDescriptorPool::Initialize + +初始化描述符池。 + +## 方法签名 + +```cpp +virtual bool Initialize(const DescriptorPoolDesc& desc) = 0; +``` + +## 详细描述 + +使用指定的描述符池描述初始化描述符池。分配 GPU 描述符堆资源，使其可以分配描述符。 + +## 参数列表 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `desc` | `const DescriptorPoolDesc&` | 描述符池配置，包含设备指针、堆类型、描述符数量和着色器可见性 | + +## 返回值 + +`bool` - 初始化成功返回 `true`，失败返回 `false` + +## 示例代码 + +```cpp +DescriptorPoolDesc desc; +desc.device = device; +desc.type = DescriptorHeapType::CBV_SRV_UAV; +desc.descriptorCount = 256; +desc.shaderVisible = true; + +if (descriptorPool->Initialize(desc)) { + // 初始化成功 +} else { + // 初始化失败 +} +``` + +## 相关文档 + +- [RHIDescriptorPool 总览](descriptor-pool.md) - 返回类总览 +- [Shutdown](shutdown.md) - 关闭描述符池 +- [GetDescriptorCount](get-descriptor-count.md) - 获取描述符数量 diff --git a/docs/api/rhi/descriptor-pool/methods.md b/docs/api/rhi/descriptor-pool/methods.md deleted file mode 100644 index dcda05db..00000000 --- a/docs/api/rhi/descriptor-pool/methods.md +++ /dev/null @@ -1,41 +0,0 @@ -# RHIDescriptorPool 方法 - -## Initialize - -```cpp -virtual bool Initialize(const DescriptorPoolDesc& desc) = 0; -``` - -初始化描述符池。 - -## Shutdown - -```cpp -virtual void Shutdown() = 0; -``` - -释放描述符池资源。 - -## GetNativeHandle - -```cpp -virtual void* GetNativeHandle() = 0; -``` - -获取原生 API 句柄。 - -## GetDescriptorCount - -```cpp -virtual uint32_t GetDescriptorCount() const = 0; -``` - -获取描述符数量。 - -## GetType - -```cpp -virtual DescriptorHeapType GetType() const = 0; -``` - -获取堆类型。 diff --git a/docs/api/rhi/descriptor-pool/shutdown.md b/docs/api/rhi/descriptor-pool/shutdown.md new file mode 100644 index 00000000..a98a359b --- /dev/null +++ b/docs/api/rhi/descriptor-pool/shutdown.md @@ -0,0 +1,33 @@ +# RHIDescriptorPool::Shutdown + +关闭描述符池并释放所有相关资源。 + +## 方法签名 + +```cpp +virtual void Shutdown() = 0; +``` + +## 详细描述 + +关闭描述符池，释放所有已分配的 GPU 描述符堆资源。此操作不可撤销。 + +## 参数列表 + +无参数。 + +## 返回值 + +无返回值。 + +## 示例代码 + +```cpp +descriptorPool->Shutdown(); +``` + +## 相关文档 + +- [RHIDescriptorPool 总览](descriptor-pool.md) - 返回类总览 +- [Initialize](initialize.md) - 初始化描述符池 +- [GetDescriptorCount](get-descriptor-count.md) - 获取描述符数量 diff --git a/docs/api/rhi/device/create-swap-chain.md b/docs/api/rhi/device/create-swap-chain.md index 63c9663a..2fe7b602 100644 --- a/docs/api/rhi/device/create-swap-chain.md +++ b/docs/api/rhi/device/create-swap-chain.md @@ -9,7 +9,7 @@ virtual RHISwapChain* CreateSwapChain(const SwapChainDesc& desc) = 0; **参数：** - `desc` - 交换链描述符，包含尺寸、缓冲数量、格式等 -**返回：** 新创建的交换链指针，失败返回 `nullptr` +**返回：** 新创建的交换链指针，失败返回 `nullptr`，OpenGL 后端始终返回有效对象 **复杂度：** O(1) diff --git a/docs/api/rhi/device/device.md b/docs/api/rhi/device/device.md index cbe249db..37cd9715 100644 --- a/docs/api/rhi/device/device.md +++ b/docs/api/rhi/device/device.md @@ -4,6 +4,8 @@ **类型**: `class` (abstract) +**头文件**: `XCEngine/RHI/RHIDevice.h` + **描述**: RHI 渲染设备抽象接口，代表一个图形设备实例。 ## 概述 @@ -51,7 +53,7 @@ if (device->Initialize(desc)) { } const RHI::RHIDeviceInfo& info = device->GetDeviceInfo(); - printf("GPU: %ls\n", info.description.c_str()); + printf("GPU: %ls\n", info.renderer.c_str()); // 创建资源 RHI::BufferDesc bufferDesc; diff --git a/docs/api/rhi/device/get-device-info.md b/docs/api/rhi/device/get-device-info.md index 94b67d23..d1fa8540 100644 --- a/docs/api/rhi/device/get-device-info.md +++ b/docs/api/rhi/device/get-device-info.md @@ -15,7 +15,7 @@ virtual const RHIDeviceInfo& GetDeviceInfo() const = 0; ```cpp const RHIDeviceInfo& info = device->GetDeviceInfo(); -printf("GPU: %ls\n", info.description.c_str()); +printf("GPU: %ls\n", info.renderer.c_str()); printf("Vendor: %ls\n", info.vendor.c_str()); printf("Driver: %ls\n", info.version.c_str()); printf("VRAM: %llu MB\n", info.dedicatedVideoMemory / 1024 / 1024); diff --git a/docs/api/rhi/enums/blend-factor.md b/docs/api/rhi/enums/blend-factor.md new file mode 100644 index 00000000..391d9f14 --- /dev/null +++ b/docs/api/rhi/enums/blend-factor.md @@ -0,0 +1,53 @@ +# BlendFactor + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 混合因子枚举，定义颜色混合的权重因子 + +## 概述 + +BlendFactor 枚举定义了混合运算中使用的各种因子，用于控制源颜色和目标颜色的混合权重。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Zero` | 0 | +| `One` | 1 | +| `SrcColor` | 源颜色 | +| `InvSrcColor` | 1 - 源颜色 | +| `SrcAlpha` | 源 alpha 值 | +| `InvSrcAlpha` | 1 - 源 alpha 值 | +| `DstAlpha` | 目标 alpha 值 | +| `InvDstAlpha` | 1 - 目标 alpha 值 | +| `DstColor` | 目标颜色 | +| `InvDstColor` | 1 - 目标颜色 | +| `SrcAlphaSat` | 饱和的源 alpha 值 | +| `BlendFactor` | 自定义混合因子 | +| `InvBlendFactor` | 1 - 自定义混合因子 | +| `Src1Color` | 第二个源的 RGB | +| `InvSrc1Color` | 1 - 第二个源的 RGB | +| `Src1Alpha` | 第二个源的 alpha | +| `InvSrc1Alpha` | 1 - 第二个源的 alpha | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + BlendFactor srcFactor = BlendFactor::SrcAlpha; + BlendFactor dstFactor = BlendFactor::InvSrcAlpha; + + if (srcFactor == BlendFactor::One) { + // 完全使用源颜色 + } +} +``` + +## 相关文档 + +- [BlendOp](blend-op.md) - 混合操作枚举 +- [ColorWriteMask](color-write-mask.md) - 颜色写入掩码枚举 diff --git a/docs/api/rhi/enums/blend-op.md b/docs/api/rhi/enums/blend-op.md new file mode 100644 index 00000000..a4c62a8c --- /dev/null +++ b/docs/api/rhi/enums/blend-op.md @@ -0,0 +1,40 @@ +# BlendOp + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 混合操作枚举，定义颜色混合的运算方式 + +## 概述 + +BlendOp 枚举定义了源颜色和目标颜色之间的混合运算方式，用于实现各种透明和混合效果。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Add` | 加法混合（Src + Dst） | +| `Subtract` | 减法混合（Src - Dst） | +| `ReverseSubtract` | 反向减法混合（Dst - Src） | +| `Min` | 取最小值 | +| `Max` | 取最大值 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + BlendOp blendOp = BlendOp::Add; + + if (blendOp == BlendOp::Subtract) { + // 使用减法混合 + } +} +``` + +## 相关文档 + +- [BlendFactor](blend-factor.md) - 混合因子枚举 +- [LogicOp](logic-op.md) - 逻辑操作枚举 diff --git a/docs/api/rhi/enums/border-color.md b/docs/api/rhi/enums/border-color.md new file mode 100644 index 00000000..f480b3ae --- /dev/null +++ b/docs/api/rhi/enums/border-color.md @@ -0,0 +1,38 @@ +# BorderColor + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 边界颜色枚举，定义纹理采样边界颜色 + +## 概述 + +BorderColor 枚举定义了当 TextureAddressMode 为 Border 模式时使用的边界颜色。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `TransparentBlack` | 透明黑色 (0,0,0,0) | +| `OpaqueBlack` | 不透明黑色 (0,0,0,1) | +| `OpaqueWhite` | 不透明白色 (1,1,1,1) | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + BorderColor borderColor = BorderColor::TransparentBlack; + + if (borderColor == BorderColor::OpaqueWhite) { + // 使用白色边界 + } +} +``` + +## 相关文档 + +- [TextureAddressMode](texture-address-mode.md) - 纹理寻址模式枚举 +- [FilterMode](filter-mode.md) - 过滤模式枚举 diff --git a/docs/api/rhi/enums/buffer-type.md b/docs/api/rhi/enums/buffer-type.md new file mode 100644 index 00000000..5c2f0f28 --- /dev/null +++ b/docs/api/rhi/enums/buffer-type.md @@ -0,0 +1,42 @@ +# BufferType + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 缓冲区类型枚举，定义 GPU 缓冲区的用途类型 + +## 概述 + +BufferType 枚举定义了引擎中使用的各种 GPU 缓冲区类型，每种类型对应不同的用途和访问模式。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Vertex` | 顶点缓冲区 | +| `Index` | 索引缓冲区 | +| `Constant` | 常量缓冲区（CBV） | +| `ReadBack` | 回读缓冲区 | +| `Indirect` | 间接执行缓冲区 | +| `RaytracingAccelerationStructure` | 光线追踪加速结构 | +| `ShaderBindingTable` | 着色器绑定表 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + BufferType bufferType = BufferType::Vertex; + + if (bufferType == BufferType::Constant) { + // 常量缓冲区处理 + } +} +``` + +## 相关文档 + +- [TextureType](texture-type.md) - 纹理类型枚举 +- [DescriptorType](descriptor-type.md) - 描述符类型枚举 diff --git a/docs/api/rhi/enums/color-write-mask.md b/docs/api/rhi/enums/color-write-mask.md new file mode 100644 index 00000000..5a7ea7f2 --- /dev/null +++ b/docs/api/rhi/enums/color-write-mask.md @@ -0,0 +1,41 @@ +# ColorWriteMask + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 颜色写入掩码枚举，控制颜色通道的写入 + +## 概述 + +ColorWriteMask 枚举定义了哪些颜色通道可以被写入渲染目标，支持位运算组合。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Red = 1` | 红色通道 | +| `Green = 2` | 绿色通道 | +| `Blue = 4` | 蓝色通道 | +| `Alpha = 8` | Alpha 通道 | +| `All = 15` | 所有通道（Red\|Green\|Blue\|Alpha） | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + ColorWriteMask mask = ColorWriteMask::All; + ColorWriteMask rgbOnly = ColorWriteMask::Red | ColorWriteMask::Green | ColorWriteMask::Blue; + + if (mask == ColorWriteMask::All) { + // 写入所有通道 + } +} +``` + +## 相关文档 + +- [BlendFactor](blend-factor.md) - 混合因子枚举 +- [LogicOp](logic-op.md) - 逻辑操作枚举 diff --git a/docs/api/rhi/enums/command-queue-type.md b/docs/api/rhi/enums/command-queue-type.md new file mode 100644 index 00000000..3e03861c --- /dev/null +++ b/docs/api/rhi/enums/command-queue-type.md @@ -0,0 +1,38 @@ +# CommandQueueType + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 命令队列类型枚举，定义 GPU 命令队列的类型 + +## 概述 + +CommandQueueType 枚举定义了不同类型的 GPU 命令队列，用于提交渲染和计算命令。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Direct` | 直接命令队列（图形命令） | +| `Compute` | 计算命令队列 | +| `Copy` | 复制命令队列 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + CommandQueueType queueType = CommandQueueType::Direct; + + if (queueType == CommandQueueType::Compute) { + // 计算命令队列 + } +} +``` + +## 相关文档 + +- [PipelineType](pipeline-type.md) - 管线类型枚举 +- [CommandQueueType](command-queue-type.md) - 命令队列类型枚举 diff --git a/docs/api/rhi/enums/comparison-func.md b/docs/api/rhi/enums/comparison-func.md new file mode 100644 index 00000000..11110677 --- /dev/null +++ b/docs/api/rhi/enums/comparison-func.md @@ -0,0 +1,43 @@ +# ComparisonFunc + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 比较函数枚举，定义深度和模板测试的比较方式 + +## 概述 + +ComparisonFunc 枚举用于深度测试和模板测试中的比较操作，决定何时通过测试。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Never` | 永不通过 | +| `Less` | 小于比较 | +| `Equal` | 等于比较 | +| `LessEqual` | 小于等于比较 | +| `Greater` | 大于比较 | +| `NotEqual` | 不等于比较 | +| `GreaterEqual` | 大于等于比较 | +| `Always` | 永远通过 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + ComparisonFunc depthFunc = ComparisonFunc::Less; + + if (depthFunc == ComparisonFunc::Equal) { + // 等于深度时通过 + } +} +``` + +## 相关文档 + +- [StencilOp](stencil-op.md) - 模板操作枚举 +- [FilterMode](filter-mode.md) - 采样过滤模式枚举 diff --git a/docs/api/rhi/enums/cull-mode.md b/docs/api/rhi/enums/cull-mode.md new file mode 100644 index 00000000..9a208d9c --- /dev/null +++ b/docs/api/rhi/enums/cull-mode.md @@ -0,0 +1,38 @@ +# CullMode + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 背面剔除模式枚举，控制图元的剔除方式 + +## 概述 + +CullMode 枚举用于控制 GPU 渲染时的背面剔除模式，决定哪些几何图元被丢弃以优化渲染性能。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `None` | 不进行剔除，显示所有图元 | +| `Front` | 剔除正面图元 | +| `Back` | 剔除背面图元（默认值） | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + CullMode cullMode = CullMode::Back; + + if (cullMode == CullMode::None) { + // 不进行剔除 + } +} +``` + +## 相关文档 + +- [FillMode](fill-mode.md) - 填充模式枚举 +- [ShaderType](shader-type.md) - 着色器类型枚举 diff --git a/docs/api/rhi/enums/descriptor-heap-type.md b/docs/api/rhi/enums/descriptor-heap-type.md new file mode 100644 index 00000000..51b78190 --- /dev/null +++ b/docs/api/rhi/enums/descriptor-heap-type.md @@ -0,0 +1,39 @@ +# DescriptorHeapType + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 描述符堆类型枚举，定义描述符堆的用途类型 + +## 概述 + +DescriptorHeapType 枚举定义了 GPU 描述符堆的类型，决定了堆中包含的描述符种类。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `CBV_SRV_UAV` | 常量缓冲区、Shader资源、无序访问视图堆 | +| `Sampler` | 采样器堆 | +| `RTV` | 渲染目标视图堆 | +| `DSV` | 深度模板视图堆 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + DescriptorHeapType heapType = DescriptorHeapType::CBV_SRV_UAV; + + if (heapType == DescriptorHeapType::Sampler) { + // 采样器堆 + } +} +``` + +## 相关文档 + +- [DescriptorType](descriptor-type.md) - 描述符类型枚举 +- [RootParameterType](root-parameter-type.md) - 根参数类型枚举 diff --git a/docs/api/rhi/enums/descriptor-type.md b/docs/api/rhi/enums/descriptor-type.md new file mode 100644 index 00000000..cd7ac515 --- /dev/null +++ b/docs/api/rhi/enums/descriptor-type.md @@ -0,0 +1,41 @@ +# DescriptorType + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 描述符类型枚举，定义 GPU 描述符资源的类型 + +## 概述 + +DescriptorType 枚举定义了 RHI 层使用的各种描述符类型，用于绑定资源到渲染管线。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `CBV` | 常量缓冲区视图 | +| `SRV` | 着色器资源视图 | +| `UAV` | 无序访问视图 | +| `Sampler` | 采样器描述符 | +| `RTV` | 渲染目标视图 | +| `DSV` | 深度模板视图 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + DescriptorType descType = DescriptorType::CBV; + + if (descType == DescriptorType::SRV) { + // 着色器资源视图处理 + } +} +``` + +## 相关文档 + +- [DescriptorHeapType](descriptor-heap-type.md) - 描述符堆类型枚举 +- [BufferType](buffer-type.md) - 缓冲区类型枚举 diff --git a/docs/api/rhi/enums/enums.md b/docs/api/rhi/enums/enums.md index e3b72b2d..7116ce55 100644 --- a/docs/api/rhi/enums/enums.md +++ b/docs/api/rhi/enums/enums.md @@ -4,43 +4,451 @@ **类型**: `enums` +**头文件**: `XCEngine/RHI/RHIEnums.h` + **描述**: RHI 模块中使用的所有枚举类型汇总。 -## 主要枚举 +## 概述 -| 枚举 | 描述 | -|------|------| -| `ShaderType` | 着色器类型 | -| `ShaderVisibility` | 着色器可见性 | -| `CullMode` | 背面剔除模式 | -| `FillMode` | 填充模式 | -| `BlendOp` | 混合操作 | +本模块汇总了 RHI 模块中定义的所有枚举类型，用于配置渲染管线的各种状态和参数。 + +## 着色器类型 + +### ShaderType + +着色器类型枚举。 + +| 枚举值 | 描述 | +|--------|------| +| `Vertex` | 顶点着色器 | +| `Fragment` | 片元着色器 (像素着色器) | +| `Geometry` | 几何着色器 | +| `Compute` | 计算着色器 | +| `TessControl` | 曲面细分控制着色器 | +| `TessEvaluation` | 曲面细分评估着色器 | +| `Hull` | 外壳着色器 (Hull shader) | +| `Domain` | 域着色器 (Domain shader) | +| `Amplification` | 放大着色器 (Mesh Shader) | +| `Mesh` | 网格着色器 | +| `Library` | 着色器库 | + +### ShaderVisibility + +着色器可见性，控制根签名参数对哪些着色器可见。 + +| 枚举值 | 描述 | +|--------|------| +| `All` | 对所有着色器可见 | +| `Vertex` | 仅对顶点着色器可见 | +| `Hull` | 仅对外壳着色器可见 | +| `Domain` | 仅对域着色器可见 | +| `Geometry` | 仅对几何着色器可见 | +| `Pixel` | 仅对像素着色器可见 | +| `Amplification` | 仅对放大着色器可见 | +| `Mesh` | 仅对网格着色器可见 | + +## 图元设置 + +### CullMode + +背面剔除模式。 + +| 枚举值 | 描述 | +|--------|------| +| `None` | 不剔除 | +| `Front` | 剔除正面 | +| `Back` | 剔除背面 | + +### FillMode + +填充模式。 + +| 枚举值 | 描述 | +|--------|------| +| `Wireframe` | 线框模式 | +| `Solid` | 实体模式 | + +### PrimitiveTopology + +图元拓扑类型。 + +| 枚举值 | 描述 | +|--------|------| +| `Undefined` | 未定义 | +| `PointList` | 点列表 | +| `LineList` | 线段列表 | +| `LineStrip` | 线段条带 | +| `TriangleList` | 三角形列表 | +| `TriangleStrip` | 三角形条带 | +| `LineListAdj` | 带邻接的线段列表 | +| `LineStripAdj` | 带邻接的线段条带 | +| `TriangleListAdj` | 带邻接的三角形列表 | +| `TriangleStripAdj` | 带邻接的三角形条带 | +| `PatchList` | 补丁列表 (用于曲面细分) | + +## 混合操作 + +### BlendOp + +混合操作。 + +| 枚举值 | 描述 | +|--------|------| +| `Add` | 加法 | +| `Subtract` | 减法 (Src - Dst) | +| `ReverseSubtract` | 反向减法 (Dst - Src) | +| `Min` | 最小值 | +| `Max` | 最大值 | + +### BlendFactor + +混合因子。 + +| 枚举值 | 描述 | +|--------|------| +| `Zero` | 0 | +| `One` | 1 | +| `SrcColor` | 源颜色 | +| `InvSrcColor` | 源颜色的逆 | +| `SrcAlpha` | 源透明度 | +| `InvSrcAlpha` | 源透明度的逆 | +| `DstAlpha` | 目标透明度 | +| `InvDstAlpha` | 目标透明度的逆 | +| `DstColor` | 目标颜色 | +| `InvDstColor` | 目标颜色的逆 | +| `SrcAlphaSat` | 源透明度饱和值 | | `BlendFactor` | 混合因子 | -| `ComparisonFunc` | 比较函数 | -| `StencilOp` | 模板操作 | -| `PrimitiveTopology` | 图元拓扑 | -| `TextureType` | 纹理类型 | -| `Format` | 纹理/缓冲区格式 | -| `FilterMode` | 采样器过滤模式 | -| `TextureAddressMode` | 纹理寻址模式 | -| `BorderColor` | 边框颜色 | -| `BufferType` | 缓冲区类型 | -| `ResourceStates` | 资源状态 | -| `HeapType` | 内存堆类型 | -| `DescriptorType` | 描述符类型 | -| `DescriptorHeapType` | 描述符堆类型 | -| `CommandQueueType` | 命令队列类型 | -| `PipelineType` | 管线类型 | -| `LoadAction` | 加载操作 | -| `StoreAction` | 存储操作 | -| `PresentFlags` | 呈现标志 | -| `QueryType` | 查询类型 | -| `RootParameterType` | 根参数类型 | -| `LogicOp` | 逻辑操作 | -| `ColorWriteMask` | 颜色写入掩码 | -| `RHIType` | RHI 后端类型 | +| `InvBlendFactor` | 混合因子的逆 | +| `Src1Color` | 源颜色 1 | +| `InvSrc1Color` | 源颜色 1 的逆 | +| `Src1Alpha` | 源透明度 1 | +| `InvSrc1Alpha` | 源透明度 1 的逆 | + +### LogicOp + +逻辑操作。 + +| 枚举值 | 描述 | +|--------|------| +| `Clear` | 清除 | +| `Set` | 设置 | +| `Copy` | 复制 | +| `CopyInverted` | 反转复制 | +| `Noop` | 无操作 | +| `Invert` | 反转 | +| `And` | 与 | +| `Nand` | 与非 | +| `Or` | 或 | +| `Nor` | 或非 | +| `Xor` | 异或 | +| `Equiv` | 等价 | +| `AndReverse` | 反向与 | +| `AndInverted` | 反向与 (输入反转) | +| `OrReverse` | 反向或 | +| `OrInverted` | 反向或 (输入反转) | + +### ColorWriteMask + +颜色写入掩码，控制颜色通道写入。 + +| 枚举值 | 值 | 描述 | +|--------|---|------| +| `Red` | 1 | 红色通道 | +| `Green` | 2 | 绿色通道 | +| `Blue` | 4 | 蓝色通道 | +| `Alpha` | 8 | 透明度通道 | +| `All` | 15 | 所有通道 | + +**使用示例**: + +```cpp +// 组合多个通道 +ColorWriteMask mask = ColorWriteMask::Red | ColorWriteMask::Green | ColorWriteMask::Blue; +// 或者使用 All +ColorWriteMask mask = ColorWriteMask::All; +``` + +## 深度和模板 + +### ComparisonFunc + +比较函数，用于深度/模板测试。 + +| 枚举值 | 描述 | +|--------|------| +| `Never` | 从不通过 | +| `Less` | 小于 | +| `Equal` | 等于 | +| `LessEqual` | 小于等于 | +| `Greater` | 大于 | +| `NotEqual` | 不等于 | +| `GreaterEqual` | 大于等于 | +| `Always` | 永远通过 | + +### StencilOp + +模板操作。 + +| 枚举值 | 描述 | +|--------|------| +| `Keep` | 保持当前值 | +| `Zero` | 设为 0 | +| `Replace` | 替换为参考值 | +| `IncrSat` | 增加并饱和 | +| `DecrSat` | 减少并饱和 | +| `Invert` | 反转位 | +| `Incr` | 增加 (溢出回绕) | +| `Decr` | 减少 (溢出回绕) | + +## 纹理采样 + +### FilterMode + +采样器过滤模式。 + +| 枚举值 | 描述 | +|--------|------| +| `Point` | 点采样 | +| `Linear` | 线性采样 | +| `Anisotropic` | 各向异性采样 | +| `ComparisonPoint` | 比较点采样 | +| `ComparisonLinear` | 比较线性采样 | +| `ComparisonAnisotropic` | 比较各向异性采样 | +| `MinimumPoint` | 最小值点采样 | +| `MinimumLinear` | 最小值线性采样 | +| `MinimumAnisotropic` | 最小值各向异性采样 | +| `MaximumPoint` | 最大值点采样 | +| `MaximumLinear` | 最大值线性采样 | +| `MaximumAnisotropic` | 最大值各向异性采样 | + +### TextureAddressMode + +纹理寻址模式。 + +| 枚举值 | 描述 | +|--------|------| +| `Wrap` | 重复寻址 | +| `Mirror` | 镜像寻址 | +| `Clamp` | 钳制寻址 | +| `Border` | 边框颜色寻址 | +| `MirrorOnce` | 单次镜像寻址 | + +### BorderColor + +边框颜色。 + +| 枚举值 | 描述 | +|--------|------| +| `TransparentBlack` | 透明黑色 (0,0,0,0) | +| `OpaqueBlack` | 不透明黑色 (0,0,0,1) | +| `OpaqueWhite` | 不透明白色 (1,1,1,1) | + +## 纹理和缓冲区类型 + +### TextureType + +纹理类型。 + +| 枚举值 | 描述 | +|--------|------| +| `Texture1D` | 1D 纹理 | +| `Texture2D` | 2D 纹理 | +| `Texture2DArray` | 2D 纹理数组 | +| `Texture3D` | 3D 纹理 | +| `TextureCube` | 立方体纹理 | +| `TextureCubeArray` | 立方体纹理数组 | + +### BufferType + +缓冲区类型。 + +| 枚举值 | 描述 | +|--------|------| +| `Vertex` | 顶点缓冲区 | +| `Index` | 索引缓冲区 | +| `Constant` | 常量缓冲区 (CBV) | +| `ReadBack` | 回读缓冲区 | +| `Indirect` | 间接执行缓冲区 | +| `RaytracingAccelerationStructure` | 光线追踪加速结构 | +| `ShaderBindingTable` | 着色器绑定表 | + +### Format + +纹理和缓冲区格式。 + +| 枚举值 | 描述 | +|--------|------| +| `Unknown` | 未知格式 | +| `R8_UNorm` | 单通道 8 位归一化 | +| `R8G8_UNorm` | 双通道 8 位归一化 | +| `R8G8B8A8_UNorm` | 四通道 8 位归一化 | +| `R16G16B16A16_Float` | 四通道 16 位浮点 | +| `R32G32B32A32_Float` | 四通道 32 位浮点 | +| `R16_Float` | 单通道 16 位浮点 | +| `R32_Float` | 单通道 32 位浮点 | +| `D16_UNorm` | 16 位深度 | +| `D24_UNorm_S8_UInt` | 24 位深度 + 8 位模板 | +| `D32_Float` | 32 位深度 | +| `BC1_UNorm` | BC1 压缩格式 | +| `BC2_UNorm` | BC2 压缩格式 | +| `BC3_UNorm` | BC3 压缩格式 | +| `BC4_UNorm` | BC4 压缩格式 | +| `BC5_UNorm` | BC5 压缩格式 | +| `BC6H_UF16` | BC6H 压缩格式 (无符号) | +| `BC7_UNorm` | BC7 压缩格式 | +| `R32G32B32A32_UInt` | 四通道 32 位无符号整数 | +| `R32_UInt` | 单通道 32 位无符号整数 | + +## 资源和内存 + +### ResourceStates + +资源状态，描述资源当前的使用方式。 + +| 枚举值 | 描述 | +|--------|------| +| `Common` | 通用状态 | +| `VertexAndConstantBuffer` | 顶点缓冲/常量缓冲 | +| `IndexBuffer` | 索引缓冲 | +| `RenderTarget` | 渲染目标 | +| `UnorderedAccess` | 无序访问 | +| `DepthWrite` | 深度写入 | +| `DepthRead` | 深度读取 | +| `NonPixelShaderResource` | 非像素着色器资源 | +| `PixelShaderResource` | 像素着色器资源 | +| `CopySrc` | 复制源 | +| `CopyDst` | 复制目标 | +| `Present` | 显示呈现 | +| `GenericRead` | 通用读取 | + +### HeapType + +内存堆类型。 + +| 枚举值 | 描述 | +|--------|------| +| `Default` | 默认堆 (GPU 直接访问) | +| `Upload` | 上传堆 (CPU 写入 GPU 读取) | +| `Readback` | 回读堆 (GPU 写入 CPU 读取) | +| `Custom` | 自定义堆 | + +## 描述符类型 + +### DescriptorType + +描述符类型。 + +| 枚举值 | 描述 | +|--------|------| +| `CBV` | 常量缓冲区视图 | +| `SRV` | 着色器资源视图 | +| `UAV` | 无序访问视图 | +| `Sampler` | 采样器 | +| `RTV` | 渲染目标视图 | +| `DSV` | 深度模板视图 | + +### DescriptorHeapType + +描述符堆类型。 + +| 枚举值 | 描述 | +|--------|------| +| `CBV_SRV_UAV` | CBV/SRV/UAV 混合堆 | +| `Sampler` | 采样器堆 | +| `RTV` | 渲染目标视图堆 | +| `DSV` | 深度模板视图堆 | + +### RootParameterType + +根参数类型。 + +| 枚举值 | 描述 | +|--------|------| +| `DescriptorTable` | 描述符表 | +| `Constants` | 常量 (32-bit 常量) | +| `CBV` | 常量缓冲区视图 | +| `SRV` | 着色器资源视图 | +| `UAV` | 无序访问视图 | + +## 命令相关 + +### CommandQueueType + +命令队列类型。 + +| 枚举值 | 描述 | +|--------|------| +| `Direct` | 直接命令队列 (图形/计算) | +| `Compute` | 计算命令队列 | +| `Copy` | 复制命令队列 | + +### PipelineType + +管线类型。 + +| 枚举值 | 描述 | +|--------|------| +| `Graphics` | 图形管线 | +| `Compute` | 计算管线 | +| `Raytracing` | 光线追踪管线 | + +### LoadAction + +加载操作，渲染通道开始时的加载行为。 + +| 枚举值 | 描述 | +|--------|------| +| `Undefined` | 未定义 | +| `Load` | 加载现有内容 | +| `Clear` | 清除为指定值 | + +### StoreAction + +存储操作，渲染通道结束时的存储行为。 + +| 枚举值 | 描述 | +|--------|------| +| `Undefined` | 未定义 | +| `Store` | 存储结果 | +| `Resolve` | 解析 (多重采样) | +| `StoreAndResolve` | 存储并解析 | +| `Discard` | 丢弃 | + +### PresentFlags + +呈现标志。 + +| 枚举值 | 描述 | +|--------|------| +| `None` | 无标志 | +| `AllowTearing` | 允许垂直同步撕裂 | +| `StrictlyTimedFrame` | 严格计时帧 | +| `AllowDisplayLatencyWaitableObject` | 允许显示延迟等待对象 | + +### QueryType + +查询类型。 + +| 枚举值 | 描述 | +|--------|------| +| `Occlusion` | 遮挡查询 | +| `Timestamp` | 时间戳查询 | +| `PipelineStatistics` | 管线统计查询 | + +## RHI 后端 + +### RHIType + +RHI 后端类型。 + +| 枚举值 | 描述 | +|--------|------| +| `D3D12` | DirectX 12 | +| `OpenGL` | OpenGL | +| `Vulkan` | Vulkan (预留) | +| `Metal` | Metal (预留) | ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [../rhi.md](../rhi.md) - RHI 模块总览 - [RHITypes](../types/types.md) - 结构体类型汇总 diff --git a/docs/api/rhi/enums/fill-mode.md b/docs/api/rhi/enums/fill-mode.md new file mode 100644 index 00000000..9527e0a4 --- /dev/null +++ b/docs/api/rhi/enums/fill-mode.md @@ -0,0 +1,37 @@ +# FillMode + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 填充模式枚举，控制几何图形的渲染方式 + +## 概述 + +FillMode 枚举定义了几何图形的渲染填充方式，用于控制渲染输出是实体填充还是线框模式。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Wireframe` | 线框模式，只渲染图元边缘 | +| `Solid` | 实体模式，填充图元内部（默认值） | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + FillMode fillMode = FillMode::Solid; + + if (fillMode == FillMode::Wireframe) { + // 线框渲染模式 + } +} +``` + +## 相关文档 + +- [CullMode](cull-mode.md) - 背面剔除模式枚举 +- [PrimitiveTopology](primitive-topology.md) - 图元拓扑枚举 diff --git a/docs/api/rhi/enums/filter-mode.md b/docs/api/rhi/enums/filter-mode.md new file mode 100644 index 00000000..ef895408 --- /dev/null +++ b/docs/api/rhi/enums/filter-mode.md @@ -0,0 +1,47 @@ +# FilterMode + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 过滤模式枚举，定义纹理采样的过滤方式 + +## 概述 + +FilterMode 枚举定义了纹理采样时使用的过滤模式，包括点过滤、线性过滤和各向异性过滤。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Point` | 点采样 | +| `Linear` | 线性过滤 | +| `Anisotropic` | 各向异性过滤 | +| `ComparisonPoint` | 比较点采样 | +| `ComparisonLinear` | 比较线性过滤 | +| `ComparisonAnisotropic` | 比较各向异性过滤 | +| `MinimumPoint` | 最小值点采样 | +| `MinimumLinear` | 最小值线性过滤 | +| `MinimumAnisotropic` | 最小值各向异性过滤 | +| `MaximumPoint` | 最大值点采样 | +| `MaximumLinear` | 最大值线性过滤 | +| `MaximumAnisotropic` | 最大值各向异性过滤 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + FilterMode filterMode = FilterMode::Linear; + + if (filterMode == FilterMode::Anisotropic) { + // 各向异性过滤 + } +} +``` + +## 相关文档 + +- [TextureAddressMode](texture-address-mode.md) - 纹理寻址模式枚举 +- [ComparisonFunc](comparison-func.md) - 比较函数枚举 diff --git a/docs/api/rhi/enums/format.md b/docs/api/rhi/enums/format.md new file mode 100644 index 00000000..b76b5bf5 --- /dev/null +++ b/docs/api/rhi/enums/format.md @@ -0,0 +1,55 @@ +# Format + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 格式枚举，定义 GPU 资源的像素格式 + +## 概述 + +Format 枚举定义了引擎支持的各种纹理和缓冲区格式，包括颜色格式和深度格式。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Unknown` | 未知格式 | +| `R8_UNorm` | 单通道 8 位归一化 | +| `R8G8_UNorm` | 双通道 8 位归一化 | +| `R8G8B8A8_UNorm` | 四通道 8 位归一化 | +| `R16G16B16A16_Float` | 四通道 16 位浮点 | +| `R32G32B32A32_Float` | 四通道 32 位浮点 | +| `R16_Float` | 单通道 16 位浮点 | +| `R32_Float` | 单通道 32 位浮点 | +| `D16_UNorm` | 16 位深度格式 | +| `D24_UNorm_S8_UInt` | 24 位深度 8 位模板格式 | +| `D32_Float` | 32 位浮点深度格式 | +| `BC1_UNorm` | 压缩格式 BC1 | +| `BC2_UNorm` | 压缩格式 BC2 | +| `BC3_UNorm` | 压缩格式 BC3 | +| `BC4_UNorm` | 单通道压缩格式 BC4 | +| `BC5_UNorm` | 双通道压缩格式 BC5 | +| `BC6H_UF16` | HDR 压缩格式 BC6H | +| `BC7_UNorm` | 高质量压缩格式 BC7 | +| `R32G32B32A32_UInt` | 四通道 32 位无符号整数 | +| `R32_UInt` | 单通道 32 位无符号整数 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + Format format = Format::R8G8B8A8_UNorm; + + if (format == Format::D32_Float) { + // 深度格式 + } +} +``` + +## 相关文档 + +- [TextureType](texture-type.md) - 纹理类型枚举 +- [BufferType](buffer-type.md) - 缓冲区类型枚举 diff --git a/docs/api/rhi/enums/heap-type.md b/docs/api/rhi/enums/heap-type.md new file mode 100644 index 00000000..f77f74f9 --- /dev/null +++ b/docs/api/rhi/enums/heap-type.md @@ -0,0 +1,39 @@ +# HeapType + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 堆类型枚举，定义 GPU 内存堆的类型 + +## 概述 + +HeapType 枚举定义了 GPU 内存分配的不同堆类型，每种类型有不同的访问模式和用途。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Default` | 默认堆，GPU 最优访问 | +| `Upload` | 上传堆，CPU 可写 GPU 可读 | +| `Readback` | 回读堆，CPU 可读 GPU 可写 | +| `Custom` | 自定义堆类型 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + HeapType heapType = HeapType::Default; + + if (heapType == HeapType::Upload) { + // 上传堆 + } +} +``` + +## 相关文档 + +- [ResourceStates](resource-states.md) - 资源状态枚举 +- [BufferType](buffer-type.md) - 缓冲区类型枚举 diff --git a/docs/api/rhi/enums/load-action.md b/docs/api/rhi/enums/load-action.md new file mode 100644 index 00000000..a30b9338 --- /dev/null +++ b/docs/api/rhi/enums/load-action.md @@ -0,0 +1,38 @@ +# LoadAction + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 加载操作枚举，定义渲染目标加载时的操作 + +## 概述 + +LoadAction 枚举定义了资源加载时的行为，用于控制渲染目标在渲染开始前的状态。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Undefined` | 未定义，不执行加载 | +| `Load` | 加载现有内容 | +| `Clear` | 清除为指定颜色/深度值 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + LoadAction loadAction = LoadAction::Clear; + + if (loadAction == LoadAction::Load) { + // 保留现有内容 + } +} +``` + +## 相关文档 + +- [StoreAction](store-action.md) - 存储操作枚举 +- [LoadAction](load-action.md) - 加载操作枚举 diff --git a/docs/api/rhi/enums/logic-op.md b/docs/api/rhi/enums/logic-op.md new file mode 100644 index 00000000..4f2af3fa --- /dev/null +++ b/docs/api/rhi/enums/logic-op.md @@ -0,0 +1,51 @@ +# LogicOp + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 逻辑操作枚举，定义颜色混合时的逻辑运算 + +## 概述 + +LogicOp 枚举定义了像素颜色上的逻辑运算操作，用于实现各种颜色混合效果。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Clear` | 清除为 0 | +| `Set` | 设置为 1 | +| `Copy` | 复制源值 | +| `CopyInverted` | 复制反转源值 | +| `Noop` | 无操作 | +| `Invert` | 反转目标值 | +| `And` | 源与目标 | +| `Nand` | 源与非目标 | +| `Or` | 源或目标 | +| `Nor` | 源或非目标 | +| `Xor` | 源异或目标 | +| `Equiv` | 源异或非目标 | +| `AndReverse` | 反转源与目标 | +| `AndInverted` | 源与反转目标 | +| `OrReverse` | 反转源或目标 | +| `OrInverted` | 源或反转目标 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + LogicOp logicOp = LogicOp::Copy; + + if (logicOp == LogicOp::Xor) { + // 异或操作 + } +} +``` + +## 相关文档 + +- [BlendOp](blend-op.md) - 混合操作枚举 +- [BlendFactor](blend-factor.md) - 混合因子枚举 diff --git a/docs/api/rhi/enums/pipeline-type.md b/docs/api/rhi/enums/pipeline-type.md new file mode 100644 index 00000000..20f712fb --- /dev/null +++ b/docs/api/rhi/enums/pipeline-type.md @@ -0,0 +1,38 @@ +# PipelineType + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 管线类型枚举，定义渲染管线的类型 + +## 概述 + +PipelineType 枚举定义了引擎支持的渲染管线类型，包括图形管线、计算管线和光线追踪管线。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Graphics` | 图形渲染管线 | +| `Compute` | 计算管线 | +| `Raytracing` | 光线追踪管线 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + PipelineType pipelineType = PipelineType::Graphics; + + if (pipelineType == PipelineType::Raytracing) { + // 光线追踪渲染 + } +} +``` + +## 相关文档 + +- [ShaderType](shader-type.md) - 着色器类型枚举 +- [CommandQueueType](command-queue-type.md) - 命令队列类型枚举 diff --git a/docs/api/rhi/enums/present-flags.md b/docs/api/rhi/enums/present-flags.md new file mode 100644 index 00000000..244ee7e9 --- /dev/null +++ b/docs/api/rhi/enums/present-flags.md @@ -0,0 +1,39 @@ +# PresentFlags + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 显示标志枚举，定义帧显示的选项 + +## 概述 + +PresentFlags 枚举定义了_present_操作的标志，用于控制交换链呈现行为。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `None` | 无特殊标志 | +| `AllowTearing` | 允许垂直同步撕裂 | +| `StrictlyTimedFrame` | 严格计时帧 | +| `AllowDisplayLatencyWaitableObject` | 允许显示延迟等待对象 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + PresentFlags flags = PresentFlags::AllowTearing; + + if (flags == PresentFlags::None) { + // 标准呈现 + } +} +``` + +## 相关文档 + +- [StoreAction](store-action.md) - 存储操作枚举 +- [ResourceStates](resource-states.md) - 资源状态枚举 diff --git a/docs/api/rhi/enums/primitive-topology.md b/docs/api/rhi/enums/primitive-topology.md new file mode 100644 index 00000000..4d5c1500 --- /dev/null +++ b/docs/api/rhi/enums/primitive-topology.md @@ -0,0 +1,46 @@ +# PrimitiveTopology + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 图元拓扑枚举，定义几何图元的绘制方式 + +## 概述 + +PrimitiveTopology 枚举定义了如何解释顶点数据以形成几何图元，是渲染管线的重要参数。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Undefined` | 未定义拓扑 | +| `PointList` | 点列表 | +| `LineList` | 线段列表 | +| `LineStrip` | 线段条带 | +| `TriangleList` | 三角形列表 | +| `TriangleStrip` | 三角形条带 | +| `LineListAdj` | 带邻接信息的线段列表 | +| `LineStripAdj` | 带邻接信息的线段条带 | +| `TriangleListAdj` | 带邻接信息的三角形列表 | +| `TriangleStripAdj` | 带邻接信息的三角形条带 | +| `PatchList` | 补丁列表（细分几何） | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + PrimitiveTopology topology = PrimitiveTopology::TriangleList; + + if (topology == PrimitiveTopology::LineStrip) { + // 线段条带渲染 + } +} +``` + +## 相关文档 + +- [FillMode](fill-mode.md) - 填充模式枚举 +- [ShaderType](shader-type.md) - 着色器类型枚举 diff --git a/docs/api/rhi/enums/query-type.md b/docs/api/rhi/enums/query-type.md new file mode 100644 index 00000000..d49d4c98 --- /dev/null +++ b/docs/api/rhi/enums/query-type.md @@ -0,0 +1,38 @@ +# QueryType + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 查询类型枚举，定义 GPU 查询的类型 + +## 概述 + +QueryType 枚举定义了引擎支持的 GPU 查询类型，用于获取渲染管线的各种统计信息。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Occlusion` | 遮挡查询 | +| `Timestamp` | 时间戳查询 | +| `PipelineStatistics` | 管线统计查询 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + QueryType queryType = QueryType::Timestamp; + + if (queryType == QueryType::Occlusion) { + // 遮挡查询 + } +} +``` + +## 相关文档 + +- [DescriptorType](descriptor-type.md) - 描述符类型枚举 +- [ResourceStates](resource-states.md) - 资源状态枚举 diff --git a/docs/api/rhi/enums/resource-states.md b/docs/api/rhi/enums/resource-states.md new file mode 100644 index 00000000..7799b6fe --- /dev/null +++ b/docs/api/rhi/enums/resource-states.md @@ -0,0 +1,48 @@ +# ResourceStates + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 资源状态枚举，定义 GPU 资源的使用状态 + +## 概述 + +ResourceStates 枚举定义了 GPU 资源的当前状态，用于资源 barriers 和同步管理。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Common` | 通用状态 | +| `VertexAndConstantBuffer` | 顶点或常量缓冲区 | +| `IndexBuffer` | 索引缓冲区 | +| `RenderTarget` | 渲染目标 | +| `UnorderedAccess` | 无序访问 | +| `DepthWrite` | 深度写入 | +| `DepthRead` | 深度读取 | +| `NonPixelShaderResource` | 非像素着色器资源 | +| `PixelShaderResource` | 像素着色器资源 | +| `CopySrc` | 复制源 | +| `CopyDst` | 复制目标 | +| `Present` | 呈现状态 | +| `GenericRead` | 通用读取 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + ResourceStates state = ResourceStates::RenderTarget; + + if (state == ResourceStates::Common) { + // 通用状态 + } +} +``` + +## 相关文档 + +- [HeapType](heap-type.md) - 堆类型枚举 +- [BufferType](buffer-type.md) - 缓冲区类型枚举 diff --git a/docs/api/rhi/enums/rhi-type.md b/docs/api/rhi/enums/rhi-type.md new file mode 100644 index 00000000..f673e8db --- /dev/null +++ b/docs/api/rhi/enums/rhi-type.md @@ -0,0 +1,39 @@ +# RHIType + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: RHI 类型枚举，定义底层图形 API 的类型 + +## 概述 + +RHIType 枚举定义了引擎支持的底层图形 API 类型，用于抽象不同平台的图形接口。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `D3D12` | DirectX 12 | +| `OpenGL` | OpenGL | +| `Vulkan` | Vulkan | +| `Metal` | Apple Metal | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + RHIType rhiType = RHIType::D3D12; + + if (rhiType == RHIType::Vulkan) { + // Vulkan 特定处理 + } +} +``` + +## 相关文档 + +- [PipelineType](pipeline-type.md) - 管线类型枚举 +- [CommandQueueType](command-queue-type.md) - 命令队列类型枚举 diff --git a/docs/api/rhi/enums/root-parameter-type.md b/docs/api/rhi/enums/root-parameter-type.md new file mode 100644 index 00000000..44f600e1 --- /dev/null +++ b/docs/api/rhi/enums/root-parameter-type.md @@ -0,0 +1,40 @@ +# RootParameterType + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 根参数类型枚举，定义根签名中参数的类型 + +## 概述 + +RootParameterType 枚举定义了根签名中参数的不同类型，用于配置渲染管线的资源绑定。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `DescriptorTable` | 描述符表 | +| `Constants` | 内联常量（32位常量） | +| `CBV` | 内联常量缓冲区视图 | +| `SRV` | 内联着色器资源视图 | +| `UAV` | 内联无序访问视图 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + RootParameterType paramType = RootParameterType::DescriptorTable; + + if (paramType == RootParameterType::Constants) { + // 内联常量 + } +} +``` + +## 相关文档 + +- [DescriptorType](descriptor-type.md) - 描述符类型枚举 +- [ShaderVisibility](shader-visibility.md) - 着色器可见性枚举 diff --git a/docs/api/rhi/enums/shader-type.md b/docs/api/rhi/enums/shader-type.md new file mode 100644 index 00000000..cb05bf45 --- /dev/null +++ b/docs/api/rhi/enums/shader-type.md @@ -0,0 +1,47 @@ +# ShaderType + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 着色器类型枚举，定义不同阶段的着色器类型 + +## 概述 + +ShaderType 枚举定义了 GPU 渲染管线中不同阶段的着色器类型。这些类型对应于图形渲染和计算任务中的各个着色器阶段。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Vertex` | 顶点着色器，处理顶点变换 | +| `Fragment` | 片元着色器，处理像素着色 | +| `Geometry` | 几何着色器，处理图元操作 | +| `Compute` | 计算着色器，用于通用计算 | +| `TessControl` | 细分控制着色器 | +| `TessEvaluation` | 细分评估着色器 | +| `Hull` | 外壳着色器（DirectX 11） | +| `Domain` | 域着色器（DirectX 11） | +| `Amplification` | 放大着色器（Mesh Shader） | +| `Mesh` | 网格着色器 | +| `Library` | 着色器库 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + ShaderType vertexShader = ShaderType::Vertex; + ShaderType computeShader = ShaderType::Compute; + + if (vertexShader == ShaderType::Vertex) { + // 处理顶点着色器 + } +} +``` + +## 相关文档 + +- [CullMode](cull-mode.md) - 渲染状态枚举 +- [PipelineType](pipeline-type.md) - 管线类型枚举 diff --git a/docs/api/rhi/enums/shader-visibility.md b/docs/api/rhi/enums/shader-visibility.md new file mode 100644 index 00000000..19b3db3f --- /dev/null +++ b/docs/api/rhi/enums/shader-visibility.md @@ -0,0 +1,43 @@ +# ShaderVisibility + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 着色器可见性枚举，定义根签名参数对哪些着色器阶段可见 + +## 概述 + +ShaderVisibility 枚举控制根签名中的描述符或常量对渲染管线中哪些着色器阶段可见。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `All` | 对所有着色器阶段可见 | +| `Vertex` | 仅对顶点着色器可见 | +| `Hull` | 仅对外壳着色器可见 | +| `Domain` | 仅对域着色器可见 | +| `Geometry` | 仅对几何着色器可见 | +| `Pixel` | 仅对像素着色器可见 | +| `Amplification` | 仅对放大着色器可见 | +| `Mesh` | 仅对网格着色器可见 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + ShaderVisibility visibility = ShaderVisibility::All; + + if (visibility == ShaderVisibility::Pixel) { + // 仅像素着色器可见 + } +} +``` + +## 相关文档 + +- [ShaderType](shader-type.md) - 着色器类型枚举 +- [RootParameterType](root-parameter-type.md) - 根参数类型枚举 diff --git a/docs/api/rhi/enums/stencil-op.md b/docs/api/rhi/enums/stencil-op.md new file mode 100644 index 00000000..d49478c0 --- /dev/null +++ b/docs/api/rhi/enums/stencil-op.md @@ -0,0 +1,43 @@ +# StencilOp + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 模板操作枚举，定义模板测试失败时的操作 + +## 概述 + +StencilOp 枚举定义了当模板测试失败时对模板缓冲区执行的操作，用于实现各种遮罩和剪裁效果。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Keep` | 保持现有模板值 | +| `Zero` | 将模板值设为 0 | +| `Replace` | 用参考值替换模板值 | +| `IncrSat` | 递增模板值，饱和到最大值 | +| `DecrSat` | 递减模板值，饱和到最小值 | +| `Invert` | 按位翻转模板值 | +| `Incr` | 递增模板值（可回绕） | +| `Decr` | 递减模板值（可回绕） | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + StencilOp failOp = StencilOp::Keep; + + if (failOp == StencilOp::Replace) { + // 替换模板值 + } +} +``` + +## 相关文档 + +- [ComparisonFunc](comparison-func.md) - 比较函数枚举 +- [LoadAction](load-action.md) - 加载操作枚举 diff --git a/docs/api/rhi/enums/store-action.md b/docs/api/rhi/enums/store-action.md new file mode 100644 index 00000000..c4eeef14 --- /dev/null +++ b/docs/api/rhi/enums/store-action.md @@ -0,0 +1,40 @@ +# StoreAction + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 存储操作枚举，定义渲染目标存储时的操作 + +## 概述 + +StoreAction 枚举定义了资源存储时的行为，用于控制渲染结果如何保存到目标资源。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Undefined` | 未定义，不执行存储 | +| `Store` | 存储渲染结果 | +| `Resolve` | 解析多重采样 | +| `StoreAndResolve` | 存储并解析 | +| `Discard` | 丢弃渲染结果 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + StoreAction storeAction = StoreAction::Store; + + if (storeAction == StoreAction::Resolve) { + // 解析多重采样 + } +} +``` + +## 相关文档 + +- [LoadAction](load-action.md) - 加载操作枚举 +- [PresentFlags](present-flags.md) - 显示标志枚举 diff --git a/docs/api/rhi/enums/texture-address-mode.md b/docs/api/rhi/enums/texture-address-mode.md new file mode 100644 index 00000000..a3188dd2 --- /dev/null +++ b/docs/api/rhi/enums/texture-address-mode.md @@ -0,0 +1,40 @@ +# TextureAddressMode + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 纹理寻址模式枚举，定义纹理坐标超出范围时的行为 + +## 概述 + +TextureAddressMode 枚举定义了当纹理坐标超出 [0, 1] 范围时的采样行为。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Wrap` | 重复寻址 | +| `Mirror` | 镜像重复寻址 | +| `Clamp` | 夹取到边缘 | +| `Border` | 使用边界颜色 | +| `MirrorOnce` | 单次镜像后夹取 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + TextureAddressMode addressMode = TextureAddressMode::Wrap; + + if (addressMode == TextureAddressMode::Clamp) { + // 夹取到边缘 + } +} +``` + +## 相关文档 + +- [FilterMode](filter-mode.md) - 过滤模式枚举 +- [BorderColor](border-color.md) - 边界颜色枚举 diff --git a/docs/api/rhi/enums/texture-type.md b/docs/api/rhi/enums/texture-type.md new file mode 100644 index 00000000..759fde21 --- /dev/null +++ b/docs/api/rhi/enums/texture-type.md @@ -0,0 +1,41 @@ +# TextureType + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 纹理类型枚举，定义不同维度的纹理类型 + +## 概述 + +TextureType 枚举定义了引擎支持的各种纹理类型，包括 1D、2D、3D 纹理以及纹理数组和立方体贴图。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Texture1D` | 一维纹理 | +| `Texture2D` | 二维纹理 | +| `Texture2DArray` | 二维纹理数组 | +| `Texture3D` | 三维纹理 | +| `TextureCube` | 立方体贴图 | +| `TextureCubeArray` | 立方体贴图数组 | + +## 使用示例 + +```cpp +#include "RHI/RHIEnums.h" + +void Example() { + TextureType texType = TextureType::Texture2D; + + if (texType == TextureType::TextureCube) { + // 立方体贴图处理 + } +} +``` + +## 相关文档 + +- [BufferType](buffer-type.md) - 缓冲区类型枚举 +- [DescriptorType](descriptor-type.md) - 描述符类型枚举 diff --git a/docs/api/rhi/factory/create-rhi-device-string.md b/docs/api/rhi/factory/create-rhi-device-string.md index 36810bf3..cb8a55ab 100644 --- a/docs/api/rhi/factory/create-rhi-device-string.md +++ b/docs/api/rhi/factory/create-rhi-device-string.md @@ -1,31 +1,59 @@ -# RHIFactory::CreateRHIDevice (string) +# RHIFactory::CreateRHIDevice ```cpp static RHIDevice* CreateRHIDevice(const std::string& typeName); ``` -根据字符串名称创建 RHI 设备。 +根据指定的 RHI 类型名称创建一个新的 RHI 设备实例。 **参数：** -- `typeName` - 后端类型名称字符串（不区分大小写） +- `typeName` - RHI 类型的字符串名称，支持的值包括： + - `"D3D12"` - DirectX 12 + - `"OpenGL"` - OpenGL + - `"Vulkan"` - Vulkan + - `"Metal"` - Metal -**返回：** 新创建的设备指针，失败返回 `nullptr` +**返回：** 新创建的 RHIDevice 指针，如果创建失败则返回 nullptr。 -**复杂度：** O(1) +**异常：** 无 -**支持的类型名称：** -- `"D3D12"` / `"d3d12"` -- `"OpenGL"` / `"opengl"` / `"GL"` -- Vulkan 和 Metal 暂不支持 +**线程安全：** ❌ 该方法本身是线程安全的，但返回的 RHIDevice 实例通常不是线程安全的。 + +**复杂度：** O(n)，其中 n 为 typeName 字符串长度 **示例：** ```cpp -// 从配置文件读取后端类型 -std::string backendType = "D3D12"; -RHIDevice* device = RHIFactory::CreateRHIDevice(backendType); +#include "XCEngine/RHI/RHIFactory.h" +#include "XCEngine/RHI/RHIDevice.h" +#include + +using namespace XCEngine::RHI; + +int main() { + RHIDevice* device = RHIFactory::CreateRHIDevice("Vulkan"); + if (!device) { + std::cerr << "Failed to create Vulkan device" << std::endl; + return 1; + } + + RHIDeviceDesc desc; + if (!device->Initialize(desc)) { + std::cerr << "Failed to initialize device" << std::endl; + delete device; + return 1; + } + + const RHIDeviceInfo& info = device->GetDeviceInfo(); + std::cout << "Device created: " << info.deviceName << std::endl; + + device->Shutdown(); + delete device; + return 0; +} ``` ## 相关文档 -- [RHIFactory 总览](factory.md) - 返回类总览 +- [RHIFactory](factory.md) - 返回类总览 +- [`CreateRHIDevice(RHIType)`](create-rhi-device-type.md) - 根据枚举类型创建设备 diff --git a/docs/api/rhi/factory/create-rhi-device-type.md b/docs/api/rhi/factory/create-rhi-device-type.md index deaeb840..0243fbbc 100644 --- a/docs/api/rhi/factory/create-rhi-device-type.md +++ b/docs/api/rhi/factory/create-rhi-device-type.md @@ -4,25 +4,56 @@ static RHIDevice* CreateRHIDevice(RHIType type); ``` -根据枚举类型创建 RHI 设备。 +根据指定的 RHI 类型创建一个新的 RHI 设备实例。 **参数：** -- `type` - 后端类型枚举值 +- `type` - RHI 类型，指定要创建的图形 API 类型，可选值包括： + - `RHIType::D3D12` - DirectX 12 + - `RHIType::OpenGL` - OpenGL + - `RHIType::Vulkan` - Vulkan + - `RHIType::Metal` - Metal -**返回：** 新创建的设备指针，失败返回 `nullptr` +**返回：** 新创建的 RHIDevice 指针，如果创建失败则返回 nullptr。 + +**异常：** 无 + +**线程安全：** ❌ 该方法本身是线程安全的，但返回的 RHIDevice 实例通常不是线程安全的。 **复杂度：** O(1) **示例：** ```cpp -RHIDevice* device = RHIFactory::CreateRHIDevice(RHIType::D3D12); -if (device) { - device->Initialize(desc); +#include "XCEngine/RHI/RHIFactory.h" +#include "XCEngine/RHI/RHIDevice.h" +#include + +using namespace XCEngine::RHI; + +int main() { + RHIDevice* device = RHIFactory::CreateRHIDevice(RHIType::D3D12); + if (!device) { + std::cerr << "Failed to create D3D12 device" << std::endl; + return 1; + } + + RHIDeviceDesc desc; + if (!device->Initialize(desc)) { + std::cerr << "Failed to initialize device" << std::endl; + delete device; + return 1; + } + + const RHIDeviceInfo& info = device->GetDeviceInfo(); + std::cout << "Device created: " << info.deviceName << std::endl; + + device->Shutdown(); + delete device; + return 0; } ``` ## 相关文档 -- [RHIFactory 总览](factory.md) - 返回类总览 -- [RHIType](../enums/enums.md) - 枚举类型 +- [RHIFactory](factory.md) - 返回类总览 +- [`CreateRHIDevice(string)`](create-rhi-device-string.md) - 根据字符串名称创建设备 diff --git a/docs/api/rhi/factory/factory.md b/docs/api/rhi/factory/factory.md index 8b0729d5..55705be4 100644 --- a/docs/api/rhi/factory/factory.md +++ b/docs/api/rhi/factory/factory.md @@ -2,7 +2,9 @@ **命名空间**: `XCEngine::RHI` -**类型**: `class` (static) +**类型**: `class` (static methods only) + +**头文件**: `XCEngine/RHI/RHIFactory.h` **描述**: RHI 设备工厂，用于创建不同图形 API 后端的渲染设备。 diff --git a/docs/api/rhi/fence/fence.md b/docs/api/rhi/fence/fence.md index cf7592ec..84d54324 100644 --- a/docs/api/rhi/fence/fence.md +++ b/docs/api/rhi/fence/fence.md @@ -4,31 +4,56 @@ **类型**: `class` (abstract) -**描述**: GPU 同步栅栏抽象接口，用于 GPU/CPU 同步和跨队列同步。 +**头文件**: `XCEngine/RHI/RHIFence.h` + +**描述**: 围栏接口，用于 GPU 同步 + +## 概述 + +RHIFence 是 RHI（Render Hardware Interface）子系统中的围栏抽象接口，用于在 CPU 和 GPU 之间进行同步操作。围栏是一种常用的 GPU 同步机制，允许 CPU 等待 GPU 完成特定任务，或让 GPU 等待 CPU 提交特定命令。 + +作为抽象基类，RHIFence 定义了一组纯虚接口，具体实现由底层图形 API（如 DirectX 12、Vulkan）提供。 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Shutdown`](shutdown.md) | 关闭并释放资源 | -| [`Signal`](signal.md) | 信号栅栏 | -| [`Wait`](wait.md) | 等待栅栏 | -| [`GetCompletedValue`](get-completed-value.md) | 获取完成值 | -| [`IsSignaled`](is-signaled.md) | 检查是否已信号 | -| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | +| [`Shutdown`](shutdown.md) | 关闭围栏并释放资源 | +| [`Signal`](signal.md) | 发送信号（无参数版本） | +| [`Signal`](signal-value.md) | 发送信号（带值版本） | +| [`Wait`](wait.md) | 等待围栏达到指定值 | +| [`GetCompletedValue`](getcompletedvalue.md) | 获取已完成的值 | +| [`IsSignaled`](issignaled.md) | 检查围栏是否已发出信号 | +| [`GetNativeHandle`](getnativehandle.md) | 获取原生句柄 | ## 使用示例 ```cpp -FenceDesc desc; -desc.initialValue = 0; -RHIFence* fence = device->CreateFence(desc); +#include "XCEngine/RHI/RHIFence.h" -commandQueue->Signal(fence, 1); -fence->Wait(1); +// 假设通过 RHI 设备创建围栏 +RHIFence* fence = device->CreateFence(); + +// 提交 GPU 命令... + +// 发送信号 +fence->Signal(); + +// 在 CPU 端等待 GPU 完成 +fence->Wait(fence->GetCompletedValue()); + +// 检查是否已完成 +if (fence->IsSignaled()) { + // GPU 工作已完成 +} + +// 获取原生句柄用于平台特定操作 +void* nativeHandle = fence->GetNativeHandle(); + +// 关闭围栏 +fence->Shutdown(); ``` ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 -- [RHICommandQueue](../command-queue/command-queue.md) - 命令队列 +- [RHI 模块总览](../rhi.md) - RHI 模块介绍 diff --git a/docs/api/rhi/fence/get-completed-value.md b/docs/api/rhi/fence/get-completed-value.md index 7d83dc99..4d1c9188 100644 --- a/docs/api/rhi/fence/get-completed-value.md +++ b/docs/api/rhi/fence/get-completed-value.md @@ -6,7 +6,9 @@ virtual uint64_t GetCompletedValue() const = 0; 获取已完成信号值。 -**返回：** 已完成的信号值 +**参数：** 无 + +**返回值：** (uint64_t) 已完成的信号值 **示例：** diff --git a/docs/api/rhi/fence/get-native-handle.md b/docs/api/rhi/fence/get-native-handle.md index c4722461..838e8c69 100644 --- a/docs/api/rhi/fence/get-native-handle.md +++ b/docs/api/rhi/fence/get-native-handle.md @@ -6,7 +6,9 @@ virtual void* GetNativeHandle() = 0; 获取原生 API 句柄。 -**返回：** 原生栅栏句柄 +**参数：** 无 + +**返回值：** (void*) 原生栅栏句柄 **复杂度：** O(1) diff --git a/docs/api/rhi/fence/getcompletedvalue.md b/docs/api/rhi/fence/getcompletedvalue.md new file mode 100644 index 00000000..6c46dbda --- /dev/null +++ b/docs/api/rhi/fence/getcompletedvalue.md @@ -0,0 +1,34 @@ +# RHIFence::GetCompletedValue + +```cpp +virtual uint64_t GetCompletedValue() const = 0; +``` + +获取围栏已完成的最大值。该值表示 GPU 已完成的所有信号操作中的最高值。 + +**参数：** 无 + +**返回：** 已完成的围栏值（`uint64_t`） + +**线程安全**：✅ + +**复杂度**：O(1) + +**示例**： + +```cpp +RHIFence* fence = device->CreateFence(); + +fence->Signal(100ULL); + +uint64_t completed = fence->GetCompletedValue(); +// completed >= 100 表示 GPU 已完成该信号 + +if (completed >= 100) { + // GPU 已完成 100 之前的所有工作 +} +``` + +## 相关文档 + +- [RHIFence](fence.md) - 返回类总览 diff --git a/docs/api/rhi/fence/getnativehandle.md b/docs/api/rhi/fence/getnativehandle.md new file mode 100644 index 00000000..a72f4821 --- /dev/null +++ b/docs/api/rhi/fence/getnativehandle.md @@ -0,0 +1,32 @@ +# RHIFence::GetNativeHandle + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +获取围栏的原生句柄，用于平台特定的图形 API 操作。返回的句柄类型取决于具体的 RHI 实现： +- DirectX 12：`ID3D12Fence*` +- Vulkan：`VkFence` + +**参数：** 无 + +**返回：** 原生句柄指针（`void*`） + +**线程安全**：❌ + +**复杂度**：O(1) + +**示例**： + +```cpp +RHIFence* fence = device->CreateFence(); + +void* nativeHandle = fence->GetNativeHandle(); + +// 平台特定用法示例（DirectX 12） +// ID3D12Fence* dxFence = static_cast(nativeHandle); +``` + +## 相关文档 + +- [RHIFence](fence.md) - 返回类总览 diff --git a/docs/api/rhi/fence/is-signaled.md b/docs/api/rhi/fence/is-signaled.md index b595f56f..af51c57b 100644 --- a/docs/api/rhi/fence/is-signaled.md +++ b/docs/api/rhi/fence/is-signaled.md @@ -6,7 +6,9 @@ virtual bool IsSignaled() const = 0; 检查栅栏是否被信号触发。 -**返回：** 如果栅栏已被信号触发返回 true +**参数：** 无 + +**返回值：** (bool) 如果栅栏已被信号触发返回 true，否则返回 false **示例：** diff --git a/docs/api/rhi/fence/issignaled.md b/docs/api/rhi/fence/issignaled.md new file mode 100644 index 00000000..62a7bcb6 --- /dev/null +++ b/docs/api/rhi/fence/issignaled.md @@ -0,0 +1,35 @@ +# RHIFence::IsSignaled + +```cpp +virtual bool IsSignaled() const = 0; +``` + +检查围栏是否已发出信号。如果返回 `true`，表示围栏的当前值已达到或超过其初始信号值。 + +**参数：** 无 + +**返回：** 如果围栏已发出信号返回 `true`，否则返回 `false` + +**线程安全**：✅ + +**复杂度**：O(1) + +**示例**： + +```cpp +RHIFence* fence = device->CreateFence(); + +fence->Signal(); + +// 非阻塞检查围栏状态 +while (!fence->IsSignaled()) { + // 执行其他任务或短暂等待 + std::this_thread::sleep_for(std::chrono::milliseconds(1)); +} + +// 围栏已发出信号，继续处理 +``` + +## 相关文档 + +- [RHIFence](fence.md) - 返回类总览 diff --git a/docs/api/rhi/fence/methods.md b/docs/api/rhi/fence/methods.md deleted file mode 100644 index 8b715be5..00000000 --- a/docs/api/rhi/fence/methods.md +++ /dev/null @@ -1,50 +0,0 @@ -# RHIFence 方法 - -## Shutdown - -```cpp -virtual void Shutdown() = 0; -``` - -释放栅栏资源。 - -## Signal - -```cpp -virtual void Signal() = 0; -virtual void Signal(uint64_t value) = 0; -``` - -信号通知（值为 1）或指定值。 - -## Wait - -```cpp -virtual void Wait(uint64_t value) = 0; -``` - -等待指定值。 - -## GetCompletedValue - -```cpp -virtual uint64_t GetCompletedValue() const = 0; -``` - -获取已完成的值。 - -## IsSignaled - -```cpp -virtual bool IsSignaled() const = 0; -``` - -检查是否已信号通知。 - -## GetNativeHandle - -```cpp -virtual void* GetNativeHandle() = 0; -``` - -获取原生 API 句柄。 diff --git a/docs/api/rhi/fence/shutdown.md b/docs/api/rhi/fence/shutdown.md index 9b2477c9..e3f44d1c 100644 --- a/docs/api/rhi/fence/shutdown.md +++ b/docs/api/rhi/fence/shutdown.md @@ -4,10 +4,25 @@ virtual void Shutdown() = 0; ``` -释放栅栏资源。 +关闭围栏并释放所有相关资源。此方法将围栏置于不可用状态，任何后续调用行为未定义。 -**复杂度：** O(1) +**线程安全**：❌ + +**复杂度**：O(1) + +**示例**： + +```cpp +RHIFence* fence = device->CreateFence(); + +// 使用围栏... +fence->Signal(); + +// 关闭围栏，释放资源 +fence->Shutdown(); +fence = nullptr; +``` ## 相关文档 -- [RHIFence 总览](fence.md) - 返回类总览 +- [RHIFence](fence.md) - 返回类总览 diff --git a/docs/api/rhi/fence/signal-value.md b/docs/api/rhi/fence/signal-value.md new file mode 100644 index 00000000..4b2acad4 --- /dev/null +++ b/docs/api/rhi/fence/signal-value.md @@ -0,0 +1,34 @@ +# RHIFence::Signal + +```cpp +virtual void Signal(uint64_t value) = 0; +``` + +将围栏设置为指定的值并通知 GPU。该方法允许设置自定义的围栏值，用于更精细的同步控制。 + +**参数：** +- `value` - 要设置的围栏值，一个 64 位无符号整数 + +**返回：** 无 + +**线程安全**：❌ + +**复杂度**：O(1) + +**示例**： + +```cpp +RHIFence* fence = device->CreateFence(); + +// 设置围栏值为特定标记 +const uint64_t kFrameFenceValue = 1000ULL; +fence->Signal(kFrameFenceValue); + +// 等待直到围栏达到指定值 +fence->Wait(kFrameFenceValue); +``` + +## 相关文档 + +- [RHIFence](fence.md) - 返回类总览 +- [Signal](signal.md) - 无参数版本的 Signal diff --git a/docs/api/rhi/fence/signal.md b/docs/api/rhi/fence/signal.md index 2319c426..ab50c2a8 100644 --- a/docs/api/rhi/fence/signal.md +++ b/docs/api/rhi/fence/signal.md @@ -2,21 +2,31 @@ ```cpp virtual void Signal() = 0; -virtual void Signal(uint64_t value) = 0; ``` -向栅栏发送信号。 +将围栏值设置为当前设备的信号值，并通知 GPU 该围栏已被触发。此方法使围栏处于有信号状态，CPU 和 GPU 可以据此进行同步操作。 -**参数：** -- `value` - 信号值（重载版本） +**参数：** 无 -**示例：** +**返回：** 无 + +**线程安全**：❌ + +**复杂度**：O(1) + +**示例**： ```cpp +RHIFence* fence = device->CreateFence(); + +// 提交 GPU 命令后发送信号 fence->Signal(); -fence->Signal(1); + +// 或者在 CPU 端等待 +fence->Wait(fence->GetCompletedValue()); ``` ## 相关文档 -- [RHIFence 总览](fence.md) - 返回类总览 +- [RHIFence](fence.md) - 返回类总览 +- [Signal(value)](signal-value.md) - 带值版本的 Signal diff --git a/docs/api/rhi/fence/wait.md b/docs/api/rhi/fence/wait.md index b7d6d048..16956013 100644 --- a/docs/api/rhi/fence/wait.md +++ b/docs/api/rhi/fence/wait.md @@ -4,17 +4,32 @@ virtual void Wait(uint64_t value) = 0; ``` -等待栅栏达到指定值。 +阻塞当前线程，直到围栏值达到或超过指定值。此方法用于 CPU 端等待 GPU 完成特定任务。 **参数：** -- `value` - 要等待的值 +- `value` - 要等待的围栏值 -**示例：** +**返回：** 无 + +**线程安全**：❌ + +**复杂度**：O(n)，具体取决于 GPU 完成指定值所需时间 + +**示例**： ```cpp -fence->Wait(1); +RHIFence* fence = device->CreateFence(); + +fence->Signal(500ULL); + +// 执行其他 CPU 工作... + +// 等待 GPU 完成到指定值 +fence->Wait(500ULL); + +// 继续后续处理 ``` ## 相关文档 -- [RHIFence 总览](fence.md) - 返回类总览 +- [RHIFence](fence.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/buffer/bind-base.md b/docs/api/rhi/opengl/buffer/bind-base.md index 6baa0123..9776fe53 100644 --- a/docs/api/rhi/opengl/buffer/bind-base.md +++ b/docs/api/rhi/opengl/buffer/bind-base.md @@ -1,7 +1,7 @@ # OpenGLBuffer::BindBase ```cpp -void BindBase(unsigned int target, unsigned int index) const +void BindBase(unsigned int target, unsigned int index) const; ``` 将缓冲区绑定到固定的 binding point。 diff --git a/docs/api/rhi/opengl/buffer/buffer.md b/docs/api/rhi/opengl/buffer/buffer.md index 7dc0134c..15286729 100644 --- a/docs/api/rhi/opengl/buffer/buffer.md +++ b/docs/api/rhi/opengl/buffer/buffer.md @@ -11,13 +11,13 @@ | [`Initialize`](initialize.md) | 初始化缓冲区 | | [`InitializeVertexBuffer`](initialize-vertex-buffer.md) | 初始化顶点缓冲 | | [`InitializeIndexBuffer`](initialize-index-buffer.md) | 初始化索引缓冲 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭缓冲区 | +| [`Shutdown`](../../buffer/shutdown.md) | 关闭缓冲区 | | [`Bind`](bind.md) | 绑定缓冲区 | | [`Unbind`](unbind.md) | 解绑缓冲区 | | [`BindBase`](bind-base.md) | 绑定到基准点 | -| [`Map`](../../buffer/map.md) | 映射缓冲区 | -| [`Unmap`](../../buffer/unmap.md) | 取消映射 | -| [`SetData`](../../buffer/set-data.md) | 设置数据 | +| [`Map`](map.md) | 映射缓冲区 | +| [`Unmap`](unmap.md) | 取消映射 | +| [`SetData`](set-data.md) | 设置数据 | | [`GetID`](get-id.md) | 获取 OpenGL 缓冲 ID | | [`GetSize`](../../buffer/get-size.md) | 获取缓冲区大小 | | [`GetType`](get-type.md) | 获取缓冲区类型 | diff --git a/docs/api/rhi/opengl/buffer/get-id.md b/docs/api/rhi/opengl/buffer/get-id.md index 76db6159..f6c2a314 100644 --- a/docs/api/rhi/opengl/buffer/get-id.md +++ b/docs/api/rhi/opengl/buffer/get-id.md @@ -1,7 +1,7 @@ # OpenGLBuffer::GetID ```cpp -unsigned int GetID() const +unsigned int GetID() const; ``` 获取 OpenGL buffer 的 GLuint ID。 diff --git a/docs/api/rhi/opengl/buffer/is-dynamic.md b/docs/api/rhi/opengl/buffer/is-dynamic.md index 40e892d1..ad4642a9 100644 --- a/docs/api/rhi/opengl/buffer/is-dynamic.md +++ b/docs/api/rhi/opengl/buffer/is-dynamic.md @@ -1,7 +1,7 @@ # OpenGLBuffer::IsDynamic ```cpp -bool IsDynamic() const +bool IsDynamic() const; ``` 判断缓冲区是否为动态缓冲区。 diff --git a/docs/api/rhi/opengl/buffer/map.md b/docs/api/rhi/opengl/buffer/map.md new file mode 100644 index 00000000..42fc8da1 --- /dev/null +++ b/docs/api/rhi/opengl/buffer/map.md @@ -0,0 +1,27 @@ +# OpenGLBuffer::Map + +```cpp +void* Map() override; +``` + +映射缓冲区到客户端地址空间，使用 `GL_WRITE_ONLY` 访问模式。 + +**返回：** 指向缓冲区数据的指针 + +**示例：** + +```cpp +void* data = buffer.Map(); +if (data) { + memcpy(data, vertices, size); + buffer.Unmap(); +} +``` + +**注意：** 此方法以 `GL_WRITE_ONLY` 模式映射缓冲区，适用于写入操作。 + +## 相关文档 + +- [OpenGLBuffer 总览](buffer.md) - 返回类总览 +- [Unmap](unmap.md) - 取消映射缓冲区 +- [SetData](set-data.md) - 设置缓冲区数据 \ No newline at end of file diff --git a/docs/api/rhi/opengl/buffer/set-data.md b/docs/api/rhi/opengl/buffer/set-data.md new file mode 100644 index 00000000..d2b110c3 --- /dev/null +++ b/docs/api/rhi/opengl/buffer/set-data.md @@ -0,0 +1,30 @@ +# OpenGLBuffer::SetData + +```cpp +void SetData(const void* data, size_t size, size_t offset = 0) override; +``` + +设置缓冲区数据。支持部分更新：当 `offset == 0` 且 `size` 等于缓冲区大小时，使用 `glBufferData` 替换整个缓冲区；否则使用 `glBufferSubData` 进行部分更新。 + +**参数：** +- `data` - 要写入的数据指针 +- `size` - 数据大小（字节） +- `offset` - 缓冲区内的偏移量（默认 0） + +**示例：** + +```cpp +// 更新整个缓冲区 +buffer.SetData(vertices, sizeof(vertices)); + +// 部分更新 +buffer.SetData(newVertices, sizeof(newVertices), sizeof(vertices)); +``` + +**注意：** 动态缓冲区使用 `GL_DYNAMIC_DRAW`，静态缓冲区使用 `GL_STATIC_DRAW`。 + +## 相关文档 + +- [OpenGLBuffer 总览](buffer.md) - 返回类总览 +- [Map](map.md) - 映射缓冲区方式写入 +- [Initialize](initialize.md) - 初始化缓冲区 \ No newline at end of file diff --git a/docs/api/rhi/opengl/buffer/unmap.md b/docs/api/rhi/opengl/buffer/unmap.md new file mode 100644 index 00000000..f5db1575 --- /dev/null +++ b/docs/api/rhi/opengl/buffer/unmap.md @@ -0,0 +1,22 @@ +# OpenGLBuffer::Unmap + +```cpp +void Unmap() override; +``` + +取消映射缓冲区，使数据对 GPU 可见。 + +**示例：** + +```cpp +void* data = buffer.Map(); +if (data) { + memcpy(data, vertices, size); + buffer.Unmap(); +} +``` + +## 相关文档 + +- [OpenGLBuffer 总览](buffer.md) - 返回类总览 +- [Map](map.md) - 映射缓冲区到客户端地址空间 \ No newline at end of file diff --git a/docs/api/rhi/opengl/command-list/clear.md b/docs/api/rhi/opengl/command-list/clear.md index 3eedf543..ce81213f 100644 --- a/docs/api/rhi/opengl/command-list/clear.md +++ b/docs/api/rhi/opengl/command-list/clear.md @@ -1,24 +1,46 @@ # OpenGLCommandList::Clear ```cpp -void Clear(float r, float g, float b, float a, unsigned int buffers); +void Clear(float r, float g, float b, float a, unsigned int buffers) ``` -清除缓冲区。 +清除指定的缓冲区。 **参数：** -- `r` - 红色分量 -- `g` - 绿色分量 -- `b` - 蓝色分量 -- `a` - Alpha 分量 -- `buffers` - 要清除的缓冲区标志 +- `r` - 清除颜色红色分量（范围 0.0f - 1.0f） +- `g` - 清除颜色绿色分量（范围 0.0f - 1.0f） +- `b` - 清除颜色蓝色分量（范围 0.0f - 1.0f） +- `a` - 清除颜色 Alpha 分量（范围 0.0f - 1.0f） +- `buffers` - 要清除的缓冲区标志，使用 `ClearFlag` 枚举值的位或组合： + - `ClearFlag::Color` (1) - 清除颜色缓冲区 + - `ClearFlag::Depth` (2) - 清除深度缓冲区 + - `ClearFlag::Stencil` (4) - 清除模板缓冲区 + +**返回值**：无 **示例：** ```cpp -commandList->Clear(0.0f, 0.0f, 0.0f, 1.0f, Color | Depth); +// 清除颜色缓冲区 +commandList->Clear(0.0f, 0.0f, 0.0f, 1.0f, static_cast(ClearFlag::Color)); + +// 清除颜色和深度缓冲区 +commandList->Clear(0.0f, 0.0f, 0.0f, 1.0f, + static_cast(ClearFlag::Color) | + static_cast(ClearFlag::Depth)); + +// 清除所有缓冲区 +commandList->Clear(0.0f, 0.0f, 0.0f, 1.0f, + static_cast(ClearFlag::Color) | + static_cast(ClearFlag::Depth) | + static_cast(ClearFlag::Stencil)); ``` ## 相关文档 - [OpenGLCommandList 总览](command-list.md) - 返回类总览 +- [ClearColor](clear-color.md) - 仅清除颜色缓冲区 +- [ClearDepth](clear-depth.md) - 仅清除深度缓冲区 +- [ClearStencil](clear-stencil.md) - 仅清除模板缓冲区 +- [ClearDepthStencil](clear-depth-stencil.md) - 清除深度和模板缓冲区 +- [ClearFlag 枚举](../../enums/clear-flag.md) - 清除缓冲区标志 diff --git a/docs/api/rhi/opengl/command-list/command-list.md b/docs/api/rhi/opengl/command-list/command-list.md index 56f82432..478e18cb 100644 --- a/docs/api/rhi/opengl/command-list/command-list.md +++ b/docs/api/rhi/opengl/command-list/command-list.md @@ -2,41 +2,112 @@ **命名空间**: `XCEngine::RHI` -**描述**: OpenGL 命令列表实现，继承自 `RHICommandList`。 +**描述**: OpenGL 命令列表实现，继承自 `RHICommandList`。提供 OpenGL 图形 API 的命令录制与执行接口，支持底层 OpenGL 状态操作以及跨平台 RHI 抽象接口。 + +## 概述 + +`OpenGLCommandList` 是 XCEngine RHI（渲染硬件接口）层在 OpenGL 后端的实现类。它封装了 OpenGL 图形命令的调用，提供了两类接口： + +1. **RHI 抽象接口**：继承自 `RHICommandList`，提供跨后端一致性接口 +2. **OpenGL 特有方法**：底层逃逸接口，用于需要直接操作 OpenGL 状态的场景 ## 公共方法 +### 生命周期 + +| 方法 | 描述 | +|------|------| +| [`Shutdown`](opengl-methods.md#shutdown) | 关闭命令列表（占位实现） | +| [`Reset`](opengl-methods.md#reset) | 重置命令列表（占位实现） | +| [`Close`](opengl-methods.md#close) | 关闭命令列表（占位实现） | + +### 清除操作 + +| 方法 | 描述 | +|------|------| +| [`Clear`](clear.md) | 清除指定缓冲区 | +| [`ClearColor`](clear-color.md) | 清除颜色缓冲区 | +| [`ClearDepth`](clear-depth.md) | 清除深度缓冲区 | +| [`ClearStencil`](clear-stencil.md) | 清除模板缓冲区 | +| [`ClearDepthStencil`](clear-depth-stencil.md) | 清除深度和模板缓冲区 | +| [`ClearRenderTarget`](clear-render-target.md) | 清除渲染目标 | + +### 状态设置 + | 方法 | 描述 | |------|------| -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭命令列表 | -| [`Reset`](../../command-list/reset.md) | 重置命令列表 | -| [`Close`](../../command-list/close.md) | 关闭命令列表 | -| [`Clear`](clear.md) | 清除 | -| [`ClearColor`](clear-color.md) | 清除颜色 | -| [`ClearDepth`](clear-depth.md) | 清除深度 | -| [`ClearStencil`](clear-stencil.md) | 清除模板 | -| [`ClearDepthStencil`](clear-depth-stencil.md) | 清除深度模板 | | [`SetPipelineState`](set-pipeline-state.md) | 设置管线状态 | -| [`SetVertexBuffer`](set-vertex-buffer.md) | 设置顶点缓冲 | -| [`SetVertexBuffers`](set-vertex-buffers.md) | 设置多个顶点缓冲 | -| [`SetIndexBuffer`](set-index-buffer.md) | 设置索引缓冲 | -| [`TransitionBarrier`](transition-barrier.md) | 资源状态转换 | -| [`SetPrimitiveTopology`](set-primitive-topology.md) | 设置图元拓扑 | -| [`SetViewport`](set-viewport.md) | 设置视口 | -| [`SetViewports`](set-viewports.md) | 设置多个视口 | -| [`SetScissorRect`](set-scissor-rect.md) | 设置裁剪矩形 | -| [`SetScissorRects`](set-scissor-rects.md) | 设置多个裁剪矩形 | +| [`SetVertexBuffer`](set-vertex-buffer.md) | 设置顶点缓冲区 | +| [`SetVertexBuffers`](set-vertex-buffers.md) | 批量设置顶点缓冲区 | +| [`SetIndexBuffer`](set-index-buffer.md) | 设置索引缓冲区 | | [`SetRenderTargets`](set-render-targets.md) | 设置渲染目标 | | [`SetDepthStencilState`](set-depth-stencil-state.md) | 设置深度模板状态 | | [`SetStencilRef`](set-stencil-ref.md) | 设置模板引用值 | | [`SetBlendState`](set-blend-state.md) | 设置混合状态 | -| [`SetBlendFactor`](set-blend-factor.md) | 设置混合因子 | -| [`ClearRenderTarget`](clear-render-target.md) | 清除渲染目标 | -| [`Draw`](draw.md) | 绘制 | -| [`DrawIndexed`](draw-indexed.md) | 索引绘制 | +| [`SetBlendFactor`](set-blend-factor.md) | 设置混合因子颜色 | +| [`SetPrimitiveTopology`](set-primitive-topology.md) | 设置图元拓扑 | + +### 视口与裁剪 + +| 方法 | 描述 | +|------|------| +| [`SetViewport`](set-viewport.md) | 设置视口 | +| [`SetViewports`](set-viewports.md) | 批量设置视口 | +| [`SetScissorRect`](set-scissor-rect.md) | 设置裁剪矩形 | +| [`SetScissorRects`](set-scissor-rects.md) | 批量设置裁剪矩形 | + +### 绘制 + +| 方法 | 描述 | +|------|------| +| [`Draw`](draw.md) | 绘制非索引图元 | +| [`DrawIndexed`](draw-indexed.md) | 绘制索引图元 | + +### 计算 + +| 方法 | 描述 | +|------|------| | [`Dispatch`](dispatch.md) | 分发计算任务 | -| [`CopyResource`](copy-resource.md) | 复制资源 | -| [`OpenGLMethods`](opengl-methods.md) | OpenGL 特有方法 | +| [`CopyResource`](copy-resource.md) | 复制资源（占位实现） | +| [`TransitionBarrier`](transition-barrier.md) | 资源状态转换（占位实现） | + +### OpenGL 特有方法 + +| 方法 | 描述 | +|------|------| +| [`OpenGLMethods`](opengl-methods.md) | 底层 OpenGL 逃逸接口 | + +## 使用示例 + +```cpp +#include "XCEngine/RHI/OpenGL/OpenGLCommandList.h" + +using namespace XCEngine::RHI; + +// 创建命令列表 +OpenGLCommandList* cmdList = new OpenGLCommandList(); + +// 清除颜色缓冲区 +cmdList->ClearColor(0.0f, 0.0f, 0.0f, 1.0f); + +// 设置视口 +Viewport viewport; +viewport.topLeftX = 0.0f; +viewport.topLeftY = 0.0f; +viewport.width = 800.0f; +viewport.height = 600.0f; +viewport.minDepth = 0.0f; +viewport.maxDepth = 1.0f; +cmdList->SetViewport(viewport); + +// 绑定 shader program +cmdList->UseShader(shaderProgram); + +// 绘制 +cmdList->Draw(3, 1, 0, 0); + +delete cmdList; +``` ## 相关文档 diff --git a/docs/api/rhi/opengl/command-list/draw.md b/docs/api/rhi/opengl/command-list/draw.md index bbdf9387..ea0d9de2 100644 --- a/docs/api/rhi/opengl/command-list/draw.md +++ b/docs/api/rhi/opengl/command-list/draw.md @@ -4,20 +4,34 @@ void Draw(uint32_t vertexCount, uint32_t instanceCount, uint32_t startVertex, uint32_t startInstance) ``` -绘制非索引图元。 +绘制非索引图元（实例化绘制）。 **参数：** -- `vertexCount` - 顶点数量 -- `instanceCount` - 实例数量 -- `startVertex` - 起始顶点 -- `startInstance` - 起始实例 +- `vertexCount` - 每个实例的顶点数量 +- `instanceCount` - 要绘制的实例数量 +- `startVertex` - 第一个顶点的索引 +- `startInstance` - 第一个实例的 ID + +**返回值**：无 + +**详细描述**： +此方法使用 `glDrawArraysInstanced` 执行实例化绘制。当 `instanceCount` 为 1 时，等同于普通的非实例化绘制。 **示例：** ```cpp +// 绘制单个实例（相当于 glDrawArrays） commandList->Draw(3, 1, 0, 0); + +// 绘制 100 个实例 +commandList->Draw(3, 100, 0, 0); + +// 绘制多个实例，从实例 ID 10 开始 +commandList->Draw(3, 50, 0, 10); ``` ## 相关文档 -- [OpenGLCommandList](command-list.md) - 返回类总览 +- [OpenGLCommandList 总览](command-list.md) - 返回类总览 +- [DrawIndexed](draw-indexed.md) - 索引绘制 +- [OpenGL 特有 Draw 方法](opengl-methods.md#draw-primitivetype) - 使用 PrimitiveType 的版本 diff --git a/docs/api/rhi/opengl/command-list/opengl-methods.md b/docs/api/rhi/opengl/command-list/opengl-methods.md index e6c13273..45d97a87 100644 --- a/docs/api/rhi/opengl/command-list/opengl-methods.md +++ b/docs/api/rhi/opengl/command-list/opengl-methods.md @@ -1,6 +1,36 @@ # OpenGLCommandList - OpenGL 特有方法 -以下是 `OpenGLCommandList` 中 OpenGL 特有的底层逃逸方法。这些方法不存在于 RHI 抽象接口中，用于需要直接操作 OpenGL 状态的高级场景。 +以下方法是 `OpenGLCommandList` 中 OpenGL 特有的底层逃逸方法。这些方法不存在于 RHI 抽象接口中，用于需要直接操作 OpenGL 状态的高级场景。 + +**注意**：这些方法直接映射到对应的 OpenGL 函数，调用时需确保 OpenGL 上下文已正确设置。 + +## 生命周期（占位实现） + +### Shutdown + +```cpp +void Shutdown() +``` + +关闭命令列表并释放资源。当前为空实现。 + +### Reset + +```cpp +void Reset() +``` + +重置命令列表状态。当前为空实现。 + +### Close + +```cpp +void Close() +``` + +关闭命令列表。当前为空实现。 + +--- ## 顶点缓冲区（OpenGL 逃逸） @@ -12,13 +42,35 @@ void SetVertexBuffer(unsigned int buffer, size_t offset, size_t stride) 直接使用 OpenGL buffer ID 设置顶点缓冲区。 +**参数：** +- `buffer` - OpenGL buffer 对象的名称（ID） +- `offset` - 缓冲区中的字节偏移量 +- `stride` - 顶点之间的字节 stride + +**返回值**：无 + +**示例：** + +```cpp +cmdList->SetVertexBuffer(vbo, 0, sizeof(Vertex)); +``` + ### SetVertexBuffers (GL uint) ```cpp void SetVertexBuffers(unsigned int startSlot, unsigned int count, const unsigned int* buffers, const size_t* offsets, const size_t* strides) ``` -批量设置顶点缓冲区。 +批量设置多个顶点缓冲区。 + +**参数：** +- `startSlot` - 起始顶点属性槽位 +- `count` - 缓冲区数量 +- `buffers` - OpenGL buffer ID 数组 +- `offsets` - 偏移量数组 +- `strides` - stride 数组 + +**返回值**：无 ### SetIndexBuffer (GL uint) @@ -29,6 +81,15 @@ void SetIndexBuffer(unsigned int buffer, unsigned int type, size_t offset) 直接设置索引缓冲区。 +**参数：** +- `buffer` - OpenGL buffer ID +- `type` - 索引数据类型（如 GL_UNSIGNED_INT） +- `offset` - 缓冲区中的字节偏移量（可选） + +**返回值**：无 + +--- + ## 顶点数组 ### BindVertexArray @@ -38,7 +99,20 @@ void BindVertexArray(unsigned int vao) void BindVertexArray(unsigned int vao, unsigned int indexBuffer, unsigned int indexType) ``` -绑定 VAO，可同时设置索引缓冲区。 +绑定顶点数组对象（VAO），可同时设置索引缓冲区。 + +**参数：** +- `vao` - 顶点数组对象 ID +- `indexBuffer` - 索引缓冲区 ID（可选） +- `indexType` - 索引数据类型（可选） + +**返回值**：无 + +**示例：** + +```cpp +cmdList->BindVertexArray(vao); +``` ### UseShader @@ -46,7 +120,20 @@ void BindVertexArray(unsigned int vao, unsigned int indexBuffer, unsigned int in void UseShader(unsigned int program) ``` -使用 shader program。 +激活 OpenGL shader program。 + +**参数：** +- `program` - Shader program ID + +**返回值**：无 + +**示例：** + +```cpp +cmdList->UseShader(shaderProgram); +``` + +--- ## 视口与裁剪 @@ -58,13 +145,31 @@ void SetViewport(int x, int y, int width, int height) 使用整数参数设置视口。 +**参数：** +- `x` - 视口左下角 X 坐标 +- `y` - 视口左下角 Y 坐标 +- `width` - 视口宽度 +- `height` - 视口高度 + +**返回值**：无 + ### SetViewport (float) ```cpp void SetViewport(float x, float y, float width, float height, float minDepth, float maxDepth) ``` -使用浮点参数设置视口。 +使用浮点参数设置视口，包含深度范围。 + +**参数：** +- `x` - 视口左下角 X 坐标 +- `y` - 视口左下角 Y 坐标 +- `width` - 视口宽度 +- `height` - 视口高度 +- `minDepth` - 最小深度值（通常为 0.0） +- `maxDepth` - 最大深度值（通常为 1.0） + +**返回值**：无 ### SetViewports @@ -72,7 +177,23 @@ void SetViewport(float x, float y, float width, float height, float minDepth, fl void SetViewports(unsigned int count, const float* viewports) ``` -批量设置视口（6 个浮点值 per viewport: x, y, width, height, minDepth, maxDepth）。 +批量设置多个视口。 + +**参数：** +- `count` - 视口数量 +- `viewports` - 视口数组，每6个浮点数表示一个视口（x, y, width, height, minDepth, maxDepth） + +**返回值**：无 + +**示例：** + +```cpp +float viewports[12] = { + 0.0f, 0.0f, 800.0f, 600.0f, 0.0f, 1.0f, + 400.0f, 0.0f, 400.0f, 600.0f, 0.0f, 1.0f +}; +cmdList->SetViewports(2, viewports); +``` ### SetScissor @@ -82,13 +203,27 @@ void SetScissor(int x, int y, int width, int height) 设置裁剪矩形。 +**参数：** +- `x` - 裁剪矩形左下角 X 坐标 +- `y` - 裁剪矩形左下角 Y 坐标 +- `width` - 裁剪矩形宽度 +- `height` - 裁剪矩形高度 + +**返回值**：无 + ### SetScissorRects ```cpp void SetScissorRects(unsigned int count, const int* rects) ``` -批量设置裁剪矩形（4 个整数值 per rect: x, y, width, height）。 +批量设置裁剪矩形。 + +**参数：** +- `count` - 裁剪矩形数量 +- `rects` - 裁剪矩形数组，每4个整数表示一个矩形（x, y, width, height） + +**返回值**：无 ### EnableScissorTest @@ -96,7 +231,14 @@ void SetScissorRects(unsigned int count, const int* rects) void EnableScissorTest(bool enable) ``` -启用/禁用裁剪测试。 +启用或禁用裁剪测试。 + +**参数：** +- `enable` - true 启用，false 禁用 + +**返回值**：无 + +--- ## 深度测试 @@ -106,7 +248,12 @@ void EnableScissorTest(bool enable) void EnableDepthTest(bool enable) ``` -启用/禁用深度测试。 +启用或禁用深度测试。 + +**参数：** +- `enable` - true 启用，false 禁用 + +**返回值**：无 ### EnableDepthWrite @@ -114,7 +261,12 @@ void EnableDepthTest(bool enable) void EnableDepthWrite(bool enable) ``` -启用/禁用深度写入。 +启用或禁用深度写入。 + +**参数：** +- `enable` - true 启用深度写入，false 禁用 + +**返回值**：无 ### SetDepthFunc @@ -122,7 +274,14 @@ void EnableDepthWrite(bool enable) void SetDepthFunc(unsigned int func) ``` -设置深度比较函数（GL_NEVER, GL_LESS, GL_EQUAL, etc.）。 +设置深度比较函数。 + +**参数：** +- `func` - OpenGL 比较函数（GL_NEVER, GL_LESS, GL_EQUAL, GL_LEQUAL, GL_GREATER, GL_NOTEQUAL, GL_GEQUAL, GL_ALWAYS） + +**返回值**：无 + +--- ## 模板测试 @@ -132,7 +291,12 @@ void SetDepthFunc(unsigned int func) void EnableStencilTest(bool enable) ``` -启用/禁用模板测试。 +启用或禁用模板测试。 + +**参数：** +- `enable` - true 启用，false 禁用 + +**返回值**：无 ### SetStencilFunc @@ -140,7 +304,14 @@ void EnableStencilTest(bool enable) void SetStencilFunc(unsigned int func, int ref, unsigned int mask) ``` -设置模板测试函数。 +设置模板测试函数和参考值。 + +**参数：** +- `func` - OpenGL 比较函数 +- `ref` - 模板参考值 +- `mask` - 模板缓冲区读写掩码 + +**返回值**：无 ### SetStencilOp @@ -148,7 +319,16 @@ void SetStencilFunc(unsigned int func, int ref, unsigned int mask) void SetStencilOp(unsigned int fail, unsigned int zfail, unsigned int zpass) ``` -设置模板操作。 +设置模板缓冲区操作。 + +**参数：** +- `fail` - 模板测试失败时的操作（如 GL_KEEP, GL_ZERO, GL_REPLACE） +- `zfail` - 模板测试通过但深度测试失败时的操作 +- `zpass` - 两者都通过时的操作 + +**返回值**：无 + +--- ## 混合 @@ -158,7 +338,12 @@ void SetStencilOp(unsigned int fail, unsigned int zfail, unsigned int zpass) void EnableBlending(bool enable) ``` -启用/禁用混合。 +启用或禁用颜色混合。 + +**参数：** +- `enable` - true 启用，false 禁用 + +**返回值**：无 ### SetBlendFunc @@ -168,6 +353,18 @@ void SetBlendFunc(unsigned int src, unsigned int dst) 设置混合函数。 +**参数：** +- `src` - 源混合因子（如 GL_ONE, GL_SRC_ALPHA, GL_DST_ALPHA） +- `dst` - 目标混合因子 + +**返回值**：无 + +**示例：** + +```cpp +cmdList->SetBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA); +``` + ### SetBlendFuncSeparate ```cpp @@ -176,6 +373,14 @@ void SetBlendFuncSeparate(unsigned int srcRGB, unsigned int dstRGB, unsigned int 分别设置 RGB 和 Alpha 的混合函数。 +**参数：** +- `srcRGB` - RGB 源混合因子 +- `dstRGB` - RGB 目标混合因子 +- `srcAlpha` - Alpha 源混合因子 +- `dstAlpha` - Alpha 目标混合因子 + +**返回值**：无 + ### SetBlendEquation ```cpp @@ -184,13 +389,28 @@ void SetBlendEquation(unsigned int mode) 设置混合方程。 +**参数：** +- `mode` - 混合方程模式（GL_FUNC_ADD, GL_FUNC_SUBTRACT, GL_FUNC_REVERSE_SUBTRACT, GL_MIN, GL_MAX） + +**返回值**：无 + ### SetBlendColor ```cpp void SetBlendColor(float r, float g, float b, float a) ``` -设置混合因子颜色。 +设置混合常量颜色。 + +**参数：** +- `r` - 红色分量 +- `g` - 绿色分量 +- `b` - 蓝色分量 +- `a` - Alpha 分量 + +**返回值**：无 + +--- ## 光栅化 @@ -200,7 +420,12 @@ void SetBlendColor(float r, float g, float b, float a) void EnableCulling(bool enable) ``` -启用/禁用面剔除。 +启用或禁用面剔除。 + +**参数：** +- `enable` - true 启用，false 禁用 + +**返回值**：无 ### SetCullFace @@ -208,7 +433,12 @@ void EnableCulling(bool enable) void SetCullFace(unsigned int face) ``` -设置剔除面（GL_FRONT, GL_BACK, GL_FRONT_AND_BACK）。 +设置要剔除的面。 + +**参数：** +- `face` - OpenGL 面模式（GL_FRONT, GL_BACK, GL_FRONT_AND_BACK） + +**返回值**：无 ### SetFrontFace @@ -216,7 +446,12 @@ void SetCullFace(unsigned int face) void SetFrontFace(unsigned int face) ``` -设置正面方向（GL_CW, GL_CCW）。 +设置正面顶点的缠绕顺序。 + +**参数：** +- `face` - GL_CW（顺时针）或 GL_CCW（逆时针） + +**返回值**：无 ### SetPolygonMode @@ -224,7 +459,12 @@ void SetFrontFace(unsigned int face) void SetPolygonMode(unsigned int mode) ``` -设置多边形模式（GL_POINT, GL_LINE, GL_FILL）。 +设置多边形光栅化模式。 + +**参数：** +- `mode` - 光栅化模式（GL_POINT, GL_LINE, GL_FILL） + +**返回值**：无 ### SetPolygonOffset @@ -232,7 +472,13 @@ void SetPolygonMode(unsigned int mode) void SetPolygonOffset(float factor, float units) ``` -设置多边形偏移。 +设置多边形深度偏移。 + +**参数：** +- `factor` - 深度偏移因子 +- `units` - 深度偏移单位 + +**返回值**：无 ### SetPrimitiveType @@ -240,7 +486,14 @@ void SetPolygonOffset(float factor, float units) void SetPrimitiveType(PrimitiveType type) ``` -设置图元类型。 +设置图元类型（内部状态保存，不直接调用 GL）。 + +**参数：** +- `type` - 图元类型枚举 + +**返回值**：无 + +--- ## 绘制（OpenGL 类型） @@ -252,6 +505,19 @@ void Draw(PrimitiveType type, unsigned int vertexCount, unsigned int startVertex 绘制非索引图元。 +**参数：** +- `type` - 图元类型 +- `vertexCount` - 顶点数量 +- `startVertex` - 起始顶点偏移 + +**返回值**：无 + +**示例：** + +```cpp +cmdList->Draw(PrimitiveType::Triangles, 3, 0); +``` + ### DrawInstanced ```cpp @@ -260,6 +526,15 @@ void DrawInstanced(PrimitiveType type, unsigned int vertexCount, unsigned int in 实例化绘制。 +**参数：** +- `type` - 图元类型 +- `vertexCount` - 每个实例的顶点数量 +- `instanceCount` - 实例数量 +- `startVertex` - 起始顶点偏移 +- `startInstance` - 起始实例 ID + +**返回值**：无 + ### DrawIndexed (PrimitiveType) ```cpp @@ -268,6 +543,14 @@ void DrawIndexed(PrimitiveType type, unsigned int indexCount, unsigned int start 绘制索引图元。 +**参数：** +- `type` - 图元类型 +- `indexCount` - 索引数量 +- `startIndex` - 起始索引偏移 +- `baseVertex` - 基础顶点偏移（当前实现中未使用） + +**返回值**：无 + ### DrawIndexedInstanced ```cpp @@ -276,13 +559,32 @@ void DrawIndexedInstanced(PrimitiveType type, unsigned int indexCount, unsigned 实例化索引绘制。 +**参数：** +- `type` - 图元类型 +- `indexCount` - 索引数量 +- `instanceCount` - 实例数量 +- `startIndex` - 起始索引偏移 +- `baseVertex` - 基础顶点偏移（当前实现中未使用） +- `startInstance` - 起始实例 ID + +**返回值**：无 + ### DrawIndirect ```cpp void DrawIndirect(PrimitiveType type, unsigned int buffer, size_t offset, unsigned int drawCount, unsigned int stride) ``` -间接绘制。 +间接绘制命令。 + +**参数：** +- `type` - 图元类型 +- `buffer` - 包含绘制参数的缓冲区 +- `offset` - 缓冲区中的字节偏移 +- `drawCount` - 绘制命令数量（当前实现中未使用） +- `stride` - 绘制参数结构 stride（当前实现中未使用） + +**返回值**：无 ### DrawIndexedIndirect @@ -290,7 +592,16 @@ void DrawIndirect(PrimitiveType type, unsigned int buffer, size_t offset, unsign void DrawIndexedIndirect(PrimitiveType type, unsigned int buffer, size_t offset, unsigned int drawCount, unsigned int stride) ``` -间接索引绘制。 +间接索引绘制命令。 + +**参数：** +- `type` - 图元类型 +- `buffer` - 包含绘制参数的缓冲区 +- `offset` - 缓冲区中的字节偏移 +- `drawCount` - 绘制命令数量（当前实现中未使用） +- `stride` - 绘制参数结构 stride（当前实现中未使用） + +**返回值**：无 ### MultiDrawArrays @@ -300,6 +611,14 @@ void MultiDrawArrays(PrimitiveType type, const int* first, const int* count, uns 多重绘制。 +**参数：** +- `type` - 图元类型 +- `first` - 每个绘制命令的起始索引数组 +- `count` - 每个绘制命令的顶点数量数组 +- `drawCount` - 绘制命令数量 + +**返回值**：无 + ### MultiDrawElements ```cpp @@ -308,6 +627,17 @@ void MultiDrawElements(PrimitiveType type, const int* count, unsigned int type_, 多重索引绘制。 +**参数：** +- `type` - 图元类型 +- `count` - 每个绘制命令的索引数量数组 +- `type_` - 索引数据类型 +- `indices` - 索引指针数组 +- `drawCount` - 绘制命令数量 + +**返回值**：无 + +--- + ## 计算着色器 ### DispatchIndirect @@ -318,13 +648,27 @@ void DispatchIndirect(unsigned int buffer, size_t offset) 间接分发计算着色器。 +**参数：** +- `buffer` - 包含分发参数的缓冲区 +- `offset` - 缓冲区中的字节偏移 + +**返回值**：无 + ### DispatchCompute ```cpp void DispatchCompute(unsigned int x, unsigned int y, unsigned int z, unsigned int groupX, unsigned int groupY, unsigned int groupZ) ``` -分发计算着色器（带参数）。 +分发计算着色器（带参数版本）。 + +**参数：** +- `x`, `y`, `z` - 工作组尺寸参数（当前实现中未使用） +- `groupX`, `groupY`, `groupZ` - 工作组数量 + +**返回值**：无 + +--- ## 内存屏障 @@ -336,13 +680,22 @@ void MemoryBarrier(unsigned int barriers) 设置内存屏障。 +**参数：** +- `barriers` - OpenGL 屏障标志（如 GL_VERTEX_ATTRIB_ARRAY_BARRIER_BIT, GL_SHADER_STORAGE_BARRIER_BIT） + +**返回值**：无 + ### TextureBarrier ```cpp void TextureBarrier() ``` -纹理屏障。 +设置纹理屏障。 + +**返回值**：无 + +--- ## 纹理绑定 @@ -354,6 +707,19 @@ void BindTexture(unsigned int target, unsigned int unit, unsigned int texture) 绑定纹理到纹理单元。 +**参数：** +- `target` - 纹理目标（GL_TEXTURE_2D, GL_TEXTURE_3D 等） +- `unit` - 纹理单元索引 +- `texture` - 纹理对象 ID + +**返回值**：无 + +**示例：** + +```cpp +cmdList->BindTexture(GL_TEXTURE_2D, 0, textureID); +``` + ### BindTextures ```cpp @@ -362,6 +728,13 @@ void BindTextures(unsigned int first, unsigned int count, const unsigned int* te 批量绑定纹理。 +**参数：** +- `first` - 起始纹理单元 +- `count` - 纹理数量 +- `textures` - 纹理 ID 数组 + +**返回值**：无 + ### BindSampler ```cpp @@ -370,6 +743,12 @@ void BindSampler(unsigned int unit, unsigned int sampler) 绑定采样器。 +**参数：** +- `unit` - 纹理单元索引 +- `sampler` - 采样器对象 ID + +**返回值**：无 + ### BindSamplers ```cpp @@ -378,13 +757,33 @@ void BindSamplers(unsigned int first, unsigned int count, const unsigned int* sa 批量绑定采样器。 +**参数：** +- `first` - 起始纹理单元 +- `count` - 采样器数量 +- `samplers` - 采样器 ID 数组 + +**返回值**：无 + ### BindImageTexture ```cpp void BindImageTexture(unsigned int unit, unsigned int texture, int level, bool layered, int layer, unsigned int access, unsigned int format) ``` -绑定为 image texture。 +绑定纹理为图像单元。 + +**参数：** +- `unit` - 图像单元索引 +- `texture` - 纹理对象 ID +- `level` - Mipmap 级别 +- `layered` - 是否绑定整个纹理数组 +- `layer` - 数组层索引 +- `access` - 访问权限（GL_READ_ONLY, GL_WRITE_ONLY, GL_READ_WRITE） +- `format` - 纹理格式 + +**返回值**：无 + +--- ## 缓冲区绑定 @@ -394,7 +793,14 @@ void BindImageTexture(unsigned int unit, unsigned int texture, int level, bool l void BindBufferBase(unsigned int target, unsigned int index, unsigned int buffer) ``` -绑定到固定 binding point。 +绑定缓冲区到固定 binding point。 + +**参数：** +- `target` - 缓冲区目标（如 GL_UNIFORM_BUFFER, GL_SHADER_STORAGE_BUFFER） +- `index` - Binding point 索引 +- `buffer` - 缓冲区对象 ID + +**返回值**：无 ### BindBufferRange @@ -402,7 +808,18 @@ void BindBufferBase(unsigned int target, unsigned int index, unsigned int buffer void BindBufferRange(unsigned int target, unsigned int index, unsigned int buffer, size_t offset, size_t size) ``` -绑定到范围 binding point。 +绑定缓冲区到范围 binding point。 + +**参数：** +- `target` - 缓冲区目标 +- `index` - Binding point 索引 +- `buffer` - 缓冲区对象 ID +- `offset` - 缓冲区中的字节偏移 +- `size` - 绑定范围大小 + +**返回值**：无 + +--- ## OpenGL 状态 @@ -415,7 +832,21 @@ void Enablei(unsigned int cap, unsigned int index) void Disablei(unsigned int cap, unsigned int index) ``` -启用/禁用 GL capability。 +启用或禁用 GL capability。 + +**参数：** +- `cap` - OpenGL capability 标识符 +- `index` - 目标索引（用于 indexed capabilities） + +**返回值**：无 + +**示例：** + +```cpp +cmdList->Enable(GL_PROGRAM_POINT_SIZE); +``` + +--- ## Uniform 设置 @@ -426,24 +857,56 @@ void SetUniform1i(int location, int v) void SetUniform1f(int location, float v) ``` +设置单个 uniform 变量。 + +**参数：** +- `location` - Uniform 变量位置 +- `v` - 值 + +**返回值**：无 + ### SetUniform2f ```cpp void SetUniform2f(int location, float x, float y) ``` +设置 vec2 uniform 变量。 + +**参数：** +- `location` - Uniform 变量位置 +- `x`, `y` - 向量分量 + +**返回值**：无 + ### SetUniform3f ```cpp void SetUniform3f(int location, float x, float y, float z) ``` +设置 vec3 uniform 变量。 + +**参数：** +- `location` - Uniform 变量位置 +- `x`, `y`, `z` - 向量分量 + +**返回值**：无 + ### SetUniform4f ```cpp void SetUniform4f(int location, float x, float y, float z, float w) ``` +设置 vec4 uniform 变量。 + +**参数：** +- `location` - Uniform 变量位置 +- `x`, `y`, `z`, `w` - 向量分量 + +**返回值**：无 + ### SetUniform1fv / SetUniform2fv / SetUniform3fv / SetUniform4fv ```cpp @@ -453,12 +916,40 @@ void SetUniform3fv(int location, int count, const float* v) void SetUniform4fv(int location, int count, const float* v) ``` +设置 float 数组 uniform 变量。 + +**参数：** +- `location` - Uniform 变量位置 +- `count` - 数组元素数量 +- `v` - 值数组指针 + +**返回值**：无 + +**示例：** + +```cpp +float vec3Array[3] = {1.0f, 2.0f, 3.0f}; +cmdList->SetUniform3fv(location, 1, vec3Array); +``` + ### SetUniformMatrix4fv ```cpp void SetUniformMatrix4fv(int location, int count, bool transpose, const float* v) ``` +设置矩阵 uniform 变量。 + +**参数：** +- `location` - Uniform 变量位置 +- `count` - 矩阵数量 +- `transpose` - 是否转置矩阵 +- `v` - 矩阵数据指针 + +**返回值**：无 + +--- + ## Shader 程序 ### UseProgram @@ -467,7 +958,12 @@ void SetUniformMatrix4fv(int location, int count, bool transpose, const float* v void UseProgram(unsigned int program) ``` -使用 program。 +激活 shader program。 + +**参数：** +- `program` - Program 对象 ID + +**返回值**：无 ### BindFragDataLocation @@ -476,7 +972,17 @@ void BindFragDataLocation(unsigned int program, unsigned int colorNumber, const void BindFragDataLocationIndexed(unsigned int program, unsigned int colorNumber, unsigned int index, const char* name) ``` -设置颜色输出绑定。 +设置 fragment shader 颜色输出绑定。 + +**参数：** +- `program` - Program 对象 ID +- `colorNumber` - 颜色缓冲区编号 +- `index` - 颜色索引（用于双源混合） +- `name` - Fragment shader 中的输出变量名 + +**返回值**：无 + +--- ## 查询 @@ -487,7 +993,13 @@ void BeginQuery(unsigned int target, unsigned int id) void EndQuery(unsigned int target) ``` -开始/结束查询。 +开始或结束查询。 + +**参数：** +- `target` - 查询目标（如 GL_SAMPLES_PASSED, GL_ANY_SAMPLES_PASSED） +- `id` - 查询对象 ID + +**返回值**：无 ### GetQueryObjectiv / GetQueryObjectuiv @@ -498,6 +1010,15 @@ void GetQueryObjectuiv(unsigned int id, unsigned int pname, unsigned int* params 获取查询结果。 +**参数：** +- `id` - 查询对象 ID +- `pname` - 查询参数（如 GL_QUERY_RESULT, GL_QUERY_RESULT_AVAILABLE） +- `params` - 结果输出数组 + +**返回值**：无 + +--- + ## Framebuffer 操作 ### ReadPixels @@ -506,7 +1027,16 @@ void GetQueryObjectuiv(unsigned int id, unsigned int pname, unsigned int* params void ReadPixels(int x, int y, int width, int height, unsigned int format, unsigned int type, void* data) ``` -读取像素。 +读取像素数据。 + +**参数：** +- `x`, `y` - 读取区域左下角坐标 +- `width`, `height` - 读取区域尺寸 +- `format` - 像素格式（GL_RED, GL_GREEN, GL_BLUE, GL_RGBA 等） +- `type` - 数据类型（GL_UNSIGNED_BYTE, GL_FLOAT 等） +- `data` - 输出数据缓冲区 + +**返回值**：无 ### BlitFramebuffer @@ -516,6 +1046,14 @@ void BlitFramebuffer(int srcX0, int srcY0, int srcX1, int srcY1, int dstX0, int Blit 帧缓冲区。 +**参数：** +- `srcX0, srcY0, srcX1, srcY1` - 源区域 +- `dstX0, dstY0, dstX1, dstY1` - 目标区域 +- `mask` - Blit 缓冲区掩码 +- `filter` - 过滤方式（GL_NEAREST, GL_LINEAR） + +**返回值**：无 + ### CopyImageSubData ```cpp @@ -524,6 +1062,19 @@ void CopyImageSubData(unsigned int srcName, unsigned int srcTarget, int srcLevel 复制图像子数据。 +**参数：** +- `srcName` - 源纹理 ID +- `srcTarget` - 源纹理目标 +- `srcLevel` - 源 Mipmap 级别 +- `srcX/Y/Z` - 源区域偏移 +- `dstName` - 目标纹理 ID +- `dstTarget` - 目标纹理目标 +- `dstLevel` - 目标 Mipmap 级别 +- `dstX/Y/Z` - 目标区域偏移 +- `width/height/depth` - 复制区域尺寸 + +**返回值**：无 + ### InvalidateFramebuffer ```cpp @@ -533,6 +1084,16 @@ void InvalidateSubFramebuffer(unsigned int target, unsigned int count, const uns 使帧缓冲区失效。 +**参数：** +- `target` - 帧缓冲区目标 +- `count` - 附件数量 +- `attachments` - 附件数组 +- `x, y, width, height` - 子区域坐标（仅 InvalidateSubFramebuffer） + +**返回值**：无 + +--- + ## 调试 ### PushDebugGroup / PopDebugGroup @@ -542,4 +1103,26 @@ void PushDebugGroup(unsigned int source, unsigned int id, int length, const char void PopDebugGroup() ``` -推送/弹出调试组。 +推送或弹出调试组。 + +**参数：** +- `source` - 调试源（GL_DEBUG_SOURCE_API, GL_DEBUG_SOURCE_WINDOW_SYSTEM 等） +- `id` - 调试消息 ID +- `length` - 消息长度（-1 表示 null 终止） +- `message` - 调试消息 + +**返回值**：无 + +**示例：** + +```cpp +cmdList->PushDebugGroup(GL_DEBUG_SOURCE_APPLICATION, 1, -1, "Begin Frame"); +cmdList->Draw(PrimitiveType::Triangles, 3, 0); +cmdList->PopDebugGroup(); +``` + +--- + +## 相关文档 + +- [OpenGLCommandList 总览](command-list.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/command-list/set-blend-state.md b/docs/api/rhi/opengl/command-list/set-blend-state.md index cc0daf39..01d20259 100644 --- a/docs/api/rhi/opengl/command-list/set-blend-state.md +++ b/docs/api/rhi/opengl/command-list/set-blend-state.md @@ -4,21 +4,40 @@ void SetBlendState(const BlendState& state) ``` -设置混合状态。 +设置颜色混合状态。 **参数：** -- `state` - 混合状态结构 +- `state` - 混合状态结构，包含以下成员： + - `alphaToCoverageEnable` - Alpha to coverage 使能标志 + - `renderTargets[0]` - 渲染目标混合配置（以第一个为例）： + - `blendEnable` - 混合使能标志 + - `srcBlend` - RGB 源混合因子（参见 `BlendFactor` 枚举） + - `dstBlend` - RGB 目标混合因子 + - `srcBlendAlpha` - Alpha 源混合因子 + - `dstBlendAlpha` - Alpha 目标混合因子 + - `blendOp` - RGB 混合操作（参见 `BlendOp` 枚举） + - `blendOpAlpha` - Alpha 混合操作 + +**返回值**：无 **示例：** ```cpp BlendState state; -state.enable = true; -state.srcBlend = BlendFunc::SrcAlpha; -state.dstBlend = BlendFunc::InvSrcAlpha; +state.alphaToCoverageEnable = false; +state.renderTargets[0].blendEnable = true; +state.renderTargets[0].srcBlend = BlendFactor::SrcAlpha; +state.renderTargets[0].dstBlend = BlendFactor::InvSrcAlpha; +state.renderTargets[0].srcBlendAlpha = BlendFactor::One; +state.renderTargets[0].dstBlendAlpha = BlendFactor::InvSrcAlpha; +state.renderTargets[0].blendOp = BlendOp::Add; +state.renderTargets[0].blendOpAlpha = BlendOp::Add; commandList->SetBlendState(state); ``` ## 相关文档 -- [OpenGLCommandList](command-list.md) - 返回类总览 +- [OpenGLCommandList 总览](command-list.md) - 返回类总览 +- [SetBlendFactor](set-blend-factor.md) - 设置混合常量颜色 +- [BlendFactor](../../enums/blend-factor.md) - 混合因子枚举 +- [BlendOp](../../enums/blend-op.md) - 混合操作枚举 diff --git a/docs/api/rhi/opengl/command-list/set-viewport.md b/docs/api/rhi/opengl/command-list/set-viewport.md index 85a367ca..ecc1c727 100644 --- a/docs/api/rhi/opengl/command-list/set-viewport.md +++ b/docs/api/rhi/opengl/command-list/set-viewport.md @@ -4,21 +4,33 @@ void SetViewport(const Viewport& viewport) ``` -设置视口。 +设置渲染视口区域。 **参数：** -- `viewport` - 视口结构 +- `viewport` - 视口结构，包含以下成员： + - `topLeftX` - 视口左下角 X 坐标 + - `topLeftY` - 视口左下角 Y 坐标 + - `width` - 视口宽度 + - `height` - 视口高度 + - `minDepth` - 最小深度值（通常为 0.0f） + - `maxDepth` - 最大深度值（通常为 1.0f） + +**返回值**：无 **示例：** ```cpp Viewport viewport; -viewport.x = 0; viewport.y = 0; -viewport.width = 800; viewport.height = 600; -viewport.minDepth = 0.0f; viewport.maxDepth = 1.0f; +viewport.topLeftX = 0.0f; +viewport.topLeftY = 0.0f; +viewport.width = 800.0f; +viewport.height = 600.0f; +viewport.minDepth = 0.0f; +viewport.maxDepth = 1.0f; commandList->SetViewport(viewport); ``` ## 相关文档 -- [OpenGLCommandList](command-list.md) - 返回类总览 +- [OpenGLCommandList 总览](command-list.md) - 返回类总览 +- [SetViewports](set-viewports.md) - 批量设置视口 diff --git a/docs/api/rhi/opengl/command-queue/command-queue.md b/docs/api/rhi/opengl/command-queue/command-queue.md index 2c5f6718..c9b66b0e 100644 --- a/docs/api/rhi/opengl/command-queue/command-queue.md +++ b/docs/api/rhi/opengl/command-queue/command-queue.md @@ -2,23 +2,29 @@ **命名空间**: `XCEngine::RHI` +**类型**: `class` + **描述**: OpenGL 命令队列实现，继承自 `RHICommandQueue`。 +## 概述 + +OpenGL 采用立即模式（Immediate Mode）渲染，与 D3D12 的命令列表模式不同。OpenGLCommandQueue 作为 RHI 抽象层接口实现，当前大多数方法为存根（stub）实现，实际渲染操作通过 OpenGL 命令直接执行。 + ## 公共方法 | 方法 | 描述 | |------|------| -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭命令队列 | +| [`Shutdown`](shutdown.md) | 关闭命令队列 | | [`ExecuteCommandLists`](execute-command-lists.md) | 执行命令列表 | -| [`Signal`](signal.md) | 信号栅栏 | -| [`Wait`](../../../threading/task-group/wait.md) | 等待栅栏 | +| [`Signal`](signal.md) | 信号围栏 | +| [`Wait`](wait.md) | 等待围栏 | | [`GetCompletedValue`](get-completed-value.md) | 获取完成值 | | [`WaitForIdle`](wait-for-idle.md) | 等待空闲 | -| [`GetType`](../../command-queue/get-type.md) | 获取队列类型 | +| [`GetType`](get-type.md) | 获取队列类型 | | [`GetTimestampFrequency`](get-timestamp-frequency.md) | 获取时间戳频率 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | ## 相关文档 - [OpenGL 后端总览](../overview.md) -- [RHICommandQueue](../../command-queue/command-queue.md) - 抽象命令队列接口 +- [RHICommandQueue](../../command-queue/command-queue.md) - 抽象命令队列接口 \ No newline at end of file diff --git a/docs/api/rhi/opengl/command-queue/execute-command-lists.md b/docs/api/rhi/opengl/command-queue/execute-command-lists.md index 60ad7d57..d07537c6 100644 --- a/docs/api/rhi/opengl/command-queue/execute-command-lists.md +++ b/docs/api/rhi/opengl/command-queue/execute-command-lists.md @@ -4,12 +4,14 @@ void ExecuteCommandLists(uint32_t count, void** lists) ``` -执行命令列表。 +**详细描述**: 执行命令列表。OpenGL 采用立即模式，此方法当前为存根实现，实际渲染通过 OpenGL 命令直接执行。 **参数：** - `count` - 命令列表数量 - `lists` - 命令列表指针数组 +**返回值：** 无 + **示例：** ```cpp @@ -19,4 +21,4 @@ commandQueue->ExecuteCommandLists(1, lists); ## 相关文档 -- [OpenGLCommandQueue](command-queue.md) - 返回类总览 +- [OpenGLCommandQueue](command-queue.md) - 返回至类概览 \ No newline at end of file diff --git a/docs/api/rhi/opengl/command-queue/get-completed-value.md b/docs/api/rhi/opengl/command-queue/get-completed-value.md index d1107187..bdbbd281 100644 --- a/docs/api/rhi/opengl/command-queue/get-completed-value.md +++ b/docs/api/rhi/opengl/command-queue/get-completed-value.md @@ -4,9 +4,9 @@ uint64_t GetCompletedValue() ``` -获取已完成的值。 +**详细描述**: 获取围栏已完成的值。由于 OpenGLCommandQueue 为存根实现，此方法始终返回 0。 -**返回：** 已完成的围栏值 +**返回值：** `uint64_t` - 已完成的围栏值，当前固定返回 0 **示例：** @@ -16,4 +16,4 @@ uint64_t value = commandQueue->GetCompletedValue(); ## 相关文档 -- [OpenGLCommandQueue](command-queue.md) - 返回类总览 +- [OpenGLCommandQueue](command-queue.md) - 返回至类概览 \ No newline at end of file diff --git a/docs/api/rhi/opengl/command-queue/get-native-handle.md b/docs/api/rhi/opengl/command-queue/get-native-handle.md new file mode 100644 index 00000000..91667a81 --- /dev/null +++ b/docs/api/rhi/opengl/command-queue/get-native-handle.md @@ -0,0 +1,19 @@ +# OpenGLCommandQueue::GetNativeHandle + +```cpp +void* GetNativeHandle() +``` + +**详细描述**: 获取原生句柄。OpenGLCommandQueue 当前为存根实现，因此始终返回 `nullptr`。 + +**返回值：** `void*` - 原生句柄指针，OpenGL 实现当前返回 `nullptr` + +**示例：** + +```cpp +void* handle = commandQueue->GetNativeHandle(); +``` + +## 相关文档 + +- [OpenGLCommandQueue](command-queue.md) - 返回至类概览 \ No newline at end of file diff --git a/docs/api/rhi/opengl/command-queue/get-timestamp-frequency.md b/docs/api/rhi/opengl/command-queue/get-timestamp-frequency.md index a21eb792..3a614d09 100644 --- a/docs/api/rhi/opengl/command-queue/get-timestamp-frequency.md +++ b/docs/api/rhi/opengl/command-queue/get-timestamp-frequency.md @@ -4,9 +4,9 @@ uint64_t GetTimestampFrequency() const ``` -获取时间戳频率。 +**详细描述**: 获取时间戳频率。OpenGLCommandQueue 为存根实现，此方法始终返回 0，表示不支持时间戳查询。 -**返回：** 时间戳频率（Hz） +**返回值：** `uint64_t` - 时间戳频率（Hz），当前固定返回 0 **示例：** @@ -16,4 +16,4 @@ uint64_t frequency = commandQueue->GetTimestampFrequency(); ## 相关文档 -- [OpenGLCommandQueue](command-queue.md) - 返回类总览 +- [OpenGLCommandQueue](command-queue.md) - 返回至类概览 \ No newline at end of file diff --git a/docs/api/rhi/opengl/command-queue/get-type.md b/docs/api/rhi/opengl/command-queue/get-type.md new file mode 100644 index 00000000..a83864a6 --- /dev/null +++ b/docs/api/rhi/opengl/command-queue/get-type.md @@ -0,0 +1,19 @@ +# OpenGLCommandQueue::GetType + +```cpp +CommandQueueType GetType() const +``` + +**详细描述**: 获取命令队列类型。OpenGLCommandQueue 固定返回 `CommandQueueType::Direct`，表示直接命令队列。 + +**返回值：** `CommandQueueType` - 命令队列类型，当前固定返回 `CommandQueueType::Direct` + +**示例：** + +```cpp +CommandQueueType type = commandQueue->GetType(); +``` + +## 相关文档 + +- [OpenGLCommandQueue](command-queue.md) - 返回至类概览 \ No newline at end of file diff --git a/docs/api/rhi/opengl/command-queue/shutdown.md b/docs/api/rhi/opengl/command-queue/shutdown.md new file mode 100644 index 00000000..fa7385f1 --- /dev/null +++ b/docs/api/rhi/opengl/command-queue/shutdown.md @@ -0,0 +1,13 @@ +# OpenGLCommandQueue::Shutdown + +```cpp +void Shutdown() +``` + +**详细描述**: 关闭命令队列并释放相关资源。OpenGLCommandQueue 当前为存根实现，此方法为空实现。 + +**返回值：** 无 + +## 相关文档 + +- [OpenGLCommandQueue](command-queue.md) - 返回至类概览 \ No newline at end of file diff --git a/docs/api/rhi/opengl/command-queue/signal.md b/docs/api/rhi/opengl/command-queue/signal.md index 282b43a0..f36e9295 100644 --- a/docs/api/rhi/opengl/command-queue/signal.md +++ b/docs/api/rhi/opengl/command-queue/signal.md @@ -4,12 +4,14 @@ void Signal(RHIFence* fence, uint64_t value) ``` -发送信号。 +**详细描述**: 向围栏发送信号。OpenGLCommandQueue 当前为存根实现，此方法为空实现。 **参数：** - `fence` - 围栏指针 - `value` - 信号值 +**返回值：** 无 + **示例：** ```cpp @@ -18,4 +20,4 @@ commandQueue->Signal(fence, 1); ## 相关文档 -- [OpenGLCommandQueue](command-queue.md) - 返回类总览 +- [OpenGLCommandQueue](command-queue.md) - 返回至类概览 \ No newline at end of file diff --git a/docs/api/rhi/opengl/command-queue/wait-for-idle.md b/docs/api/rhi/opengl/command-queue/wait-for-idle.md index 7175e75a..091d12a9 100644 --- a/docs/api/rhi/opengl/command-queue/wait-for-idle.md +++ b/docs/api/rhi/opengl/command-queue/wait-for-idle.md @@ -4,7 +4,9 @@ void WaitForIdle() ``` -等待命令队列空闲。 +**详细描述**: 等待命令队列空闲。OpenGLCommandQueue 当前为存根实现，此方法为空实现。 + +**返回值：** 无 **示例：** @@ -14,4 +16,4 @@ commandQueue->WaitForIdle(); ## 相关文档 -- [OpenGLCommandQueue](command-queue.md) - 返回类总览 +- [OpenGLCommandQueue](command-queue.md) - 返回至类概览 \ No newline at end of file diff --git a/docs/api/rhi/opengl/command-queue/wait.md b/docs/api/rhi/opengl/command-queue/wait.md new file mode 100644 index 00000000..b4d4b138 --- /dev/null +++ b/docs/api/rhi/opengl/command-queue/wait.md @@ -0,0 +1,23 @@ +# OpenGLCommandQueue::Wait + +```cpp +void Wait(RHIFence* fence, uint64_t value) +``` + +**详细描述**: 等待围栏达到指定值。OpenGLCommandQueue 当前为存根实现，此方法为空实现。 + +**参数：** +- `fence` - 围栏指针 +- `value` - 等待的围栏值 + +**返回值：** 无 + +**示例：** + +```cpp +commandQueue->Wait(fence, 1); +``` + +## 相关文档 + +- [OpenGLCommandQueue](command-queue.md) - 返回至类概览 \ No newline at end of file diff --git a/docs/api/rhi/opengl/depth-stencil-view/bind-framebuffer.md b/docs/api/rhi/opengl/depth-stencil-view/bind-framebuffer.md index a737aa4b..0d94b417 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/bind-framebuffer.md +++ b/docs/api/rhi/opengl/depth-stencil-view/bind-framebuffer.md @@ -9,6 +9,8 @@ static void BindFramebuffer(unsigned int framebuffer) **参数：** - `framebuffer` - 帧缓冲区 ID（0 表示解除绑定） +**返回值：** `void` + **示例：** ```cpp diff --git a/docs/api/rhi/opengl/depth-stencil-view/bind.md b/docs/api/rhi/opengl/depth-stencil-view/bind.md index b0ba153a..bf3562d3 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/bind.md +++ b/docs/api/rhi/opengl/depth-stencil-view/bind.md @@ -1,10 +1,16 @@ # OpenGLDepthStencilView::Bind ```cpp -void Bind() const; +void Bind(); ``` -绑定深度模板视图。 +将深度模板视图的帧缓冲对象绑定到当前 OpenGL 上下文。绑定后，后续的深度测试和模板测试将使用此视图。 + +**返回值：** `void` + +## 相关文档 + +- [OpenGLDepthStencilView 总览](depth-stencil-view.md) - 返回类总览 ## 相关文档 diff --git a/docs/api/rhi/opengl/depth-stencil-view/clear-depth-stencil.md b/docs/api/rhi/opengl/depth-stencil-view/clear-depth-stencil.md index 5f3f191f..9acc3e3b 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/clear-depth-stencil.md +++ b/docs/api/rhi/opengl/depth-stencil-view/clear-depth-stencil.md @@ -4,12 +4,14 @@ void ClearDepthStencil(float depth, uint8_t stencil) ``` -同时清除深度和模板缓冲区。 +同时清除深度和模板缓冲区。此操作会先绑定帧缓冲，然后执行清除。 **参数：** - `depth` - 深度值（通常为 0.0 到 1.0） - `stencil` - 模板值（0-255） +**返回值：** `void` + **示例：** ```cpp diff --git a/docs/api/rhi/opengl/depth-stencil-view/clear-depth.md b/docs/api/rhi/opengl/depth-stencil-view/clear-depth.md index 8292a28a..0e4e32f6 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/clear-depth.md +++ b/docs/api/rhi/opengl/depth-stencil-view/clear-depth.md @@ -4,11 +4,13 @@ void ClearDepth(float depth) ``` -清除深度缓冲区的深度值。 +清除深度缓冲区的深度值为指定值。此操作会先绑定帧缓冲，然后执行清除。 **参数：** - `depth` - 深度值（通常为 0.0 到 1.0） +**返回值：** `void` + **示例：** ```cpp diff --git a/docs/api/rhi/opengl/depth-stencil-view/clear-stencil.md b/docs/api/rhi/opengl/depth-stencil-view/clear-stencil.md index bca7b5d2..60c36918 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/clear-stencil.md +++ b/docs/api/rhi/opengl/depth-stencil-view/clear-stencil.md @@ -4,11 +4,13 @@ void ClearStencil(uint8_t stencil) ``` -清除模板缓冲区的模板值。 +清除模板缓冲区的模板值为指定值。此操作会先绑定帧缓冲，然后执行清除。 **参数：** - `stencil` - 模板值（0-255） +**返回值：** `void` + **示例：** ```cpp diff --git a/docs/api/rhi/opengl/depth-stencil-view/constructor.md b/docs/api/rhi/opengl/depth-stencil-view/constructor.md new file mode 100644 index 00000000..22aeb4d7 --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/constructor.md @@ -0,0 +1,11 @@ +# OpenGLDepthStencilView::OpenGLDepthStencilView + +```cpp +OpenGLDepthStencilView(); +``` + +默认构造函数，创建一个空的深度模板视图对象。 + +## 相关文档 + +- [OpenGLDepthStencilView 总览](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-format.md b/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-format.md new file mode 100644 index 00000000..2f49e7f8 --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-format.md @@ -0,0 +1,19 @@ +# DepthStencilFormat + +**命名空间**: `XCEngine::RHI` + +**描述**: 深度模板格式枚举。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `D16_UNORM` | 16 位无符号归一化深度格式 | +| `D24_UNORM_S8_UINT` | 24 位无符号归一化深度格式，8 位模板 | +| `D32_FLOAT` | 32 位浮点深度格式 | +| `D32_FLOAT_S8X24_UINT` | 32 位浮点深度格式，8 位模板，24 位未使用 | + +## 相关文档 + +- [OpenGLDepthStencilView 总览](depth-stencil-view.md) - 返回类总览 +- [OpenGLDepthStencilViewDesc](openGLDepthStencilViewDesc.md) - 深度模板视图描述结构体 diff --git a/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-type.md b/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-type.md new file mode 100644 index 00000000..0b753c6d --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-type.md @@ -0,0 +1,18 @@ +# DepthStencilType + +**命名空间**: `XCEngine::RHI` + +**描述**: 深度模板类型枚举。 + +## 枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `Texture2D` | 2D 纹理 | +| `Texture2DArray` | 2D 纹理数组 | +| `TextureCube` | 立方体贴图 | + +## 相关文档 + +- [OpenGLDepthStencilView 总览](depth-stencil-view.md) - 返回类总览 +- [OpenGLDepthStencilViewDesc](openGLDepthStencilViewDesc.md) - 深度模板视图描述结构体 diff --git a/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md b/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md index 7f5c5e74..1960a8be 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md +++ b/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md @@ -2,12 +2,24 @@ **命名空间**: `XCEngine::RHI` -**描述**: OpenGL 深度模板视图实现。 +**描述**: OpenGL 深度模板视图实现，用于管理深度缓冲区和模板缓冲区的帧缓冲对象。 + +## 概述 + +`OpenGLDepthStencilView` 类封装了 OpenGL 深度模板视图（Depth-Stencil View）的功能，通过帧缓冲对象（Framebuffer Object）管理深度缓冲区和模板缓冲区。该类支持多种纹理类型，包括 2D 纹理、2D 纹理数组和立方体贴图。 + +主要功能： +- 创建和管理深度模板帧缓冲对象 +- 绑定/解绑深度模板视图到渲染管线 +- 清除深度缓冲区和/或模板缓冲区的值 +- 查询视图相关的纹理和帧缓冲信息 ## 公共方法 | 方法 | 描述 | |------|------| +| [`OpenGLDepthStencilView`](constructor.md) | 构造函数 | +| [`~OpenGLDepthStencilView`](destructor.md) | 析构函数 | | [`Initialize`](initialize.md) | 初始化深度模板视图 | | [`InitializeCubemap`](initialize-cubemap.md) | 初始化立方体贴图深度模板视图 | | [`Shutdown`](shutdown.md) | 关闭深度模板视图 | @@ -24,6 +36,12 @@ | [`BindFramebuffer`](bind-framebuffer.md) | 绑定帧缓冲 | | [`UnbindFramebuffer`](unbind-framebuffer.md) | 解绑帧缓冲 | +## 相关结构体与枚举 + +- [`OpenGLDepthStencilViewDesc`](openGLDepthStencilViewDesc.md) - 深度模板视图描述结构体 +- [`DepthStencilFormat`](depth-stencil-format.md) - 深度模板格式枚举 +- [`DepthStencilType`](depth-stencil-type.md) - 深度模板类型枚举 + ## 相关文档 - [OpenGL 后端总览](../overview.md) diff --git a/docs/api/rhi/opengl/depth-stencil-view/destructor.md b/docs/api/rhi/opengl/depth-stencil-view/destructor.md new file mode 100644 index 00000000..e8ea6fe9 --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/destructor.md @@ -0,0 +1,11 @@ +# OpenGLDepthStencilView::~OpenGLDepthStencilView + +```cpp +~OpenGLDepthStencilView(); +``` + +析构函数，自动调用 `Shutdown()` 释放资源。 + +## 相关文档 + +- [OpenGLDepthStencilView 总览](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/depth-stencil-view/get-framebuffer.md b/docs/api/rhi/opengl/depth-stencil-view/get-framebuffer.md index 940b5a1b..0bebce59 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/get-framebuffer.md +++ b/docs/api/rhi/opengl/depth-stencil-view/get-framebuffer.md @@ -4,9 +4,9 @@ unsigned int GetFramebuffer() const ``` -获取帧缓冲区对象 ID。 +获取与此深度模板视图关联的帧缓冲对象 ID。 -**返回：** `unsigned int` - 帧缓冲区 ID +**返回：** `unsigned int` - 帧缓冲区 OpenGL 对象 ID **示例：** diff --git a/docs/api/rhi/opengl/depth-stencil-view/get-mip-level.md b/docs/api/rhi/opengl/depth-stencil-view/get-mip-level.md index bc7cfce0..58d52e02 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/get-mip-level.md +++ b/docs/api/rhi/opengl/depth-stencil-view/get-mip-level.md @@ -4,9 +4,9 @@ int GetMipLevel() const ``` -获取 mipmap 级别。 +获取此深度模板视图所绑定的 mipmap 级别。 -**返回：** `int` - mip 级别 +**返回：** `int` - mip 级别索引 **示例：** diff --git a/docs/api/rhi/opengl/depth-stencil-view/get-size.md b/docs/api/rhi/opengl/depth-stencil-view/get-size.md index 58de9881..f32d9d7c 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/get-size.md +++ b/docs/api/rhi/opengl/depth-stencil-view/get-size.md @@ -5,9 +5,9 @@ int GetWidth() const; int GetHeight() const; ``` -获取深度模板视图的宽度和高度。 +获取深度模板视图的宽度和高度（以像素为单位）。 -**返回：** 宽度/高度 +**返回：** `int` - 视图的宽度/高度值 ## 相关文档 diff --git a/docs/api/rhi/opengl/depth-stencil-view/get-texture.md b/docs/api/rhi/opengl/depth-stencil-view/get-texture.md index 7958415f..379c2200 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/get-texture.md +++ b/docs/api/rhi/opengl/depth-stencil-view/get-texture.md @@ -4,9 +4,9 @@ unsigned int GetTexture() const ``` -获取关联的纹理对象 ID。 +获取创建此深度模板视图时使用的原始纹理对象 ID。 -**返回：** `unsigned int` - 纹理 ID +**返回：** `unsigned int` - 纹理 OpenGL 对象 ID **示例：** diff --git a/docs/api/rhi/opengl/depth-stencil-view/initialize.md b/docs/api/rhi/opengl/depth-stencil-view/initialize.md index 6e9b4ace..b3aa6ee9 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/initialize.md +++ b/docs/api/rhi/opengl/depth-stencil-view/initialize.md @@ -1,17 +1,61 @@ # OpenGLDepthStencilView::Initialize -```cpp -bool Initialize(unsigned int texture, int width, int height); -``` - 初始化深度模板视图。 +## 重载 1 + +```cpp +bool Initialize(unsigned int texture, const OpenGLDepthStencilViewDesc& desc); +``` + +使用描述结构体初始化深度模板视图，将指定的 OpenGL 纹理创建为深度模板帧缓冲对象。 + **参数：** - `texture` - OpenGL 纹理 ID -- `width` - 宽度 -- `height` - 高度 +- `desc` - 深度模板视图描述结构体 -**返回：** 成功返回 true +**返回：** 成功返回 `true`，失败返回 `false`。失败时帧缓冲不会被创建。 + +**示例：** + +```cpp +OpenGLDepthStencilView dsv; +OpenGLDepthStencilViewDesc desc; +desc.type = DepthStencilType::Texture2D; +desc.mipLevel = 0; +desc.baseArraySlice = 0; +desc.arraySize = 1; +dsv.Initialize(textureID, desc); +``` + +## 重载 2 + +```cpp +bool Initialize(unsigned int texture, int mipLevel = 0); +``` + +使用简单参数初始化深度模板视图。 + +**参数：** +- `texture` - OpenGL 纹理 ID +- `mipLevel` - mipmap 级别（默认为 0） + +**返回：** 成功返回 true，失败返回 false + +**示例：** + +```cpp +// 使用描述结构体初始化 +OpenGLDepthStencilViewDesc desc; +desc.type = DepthStencilType::Texture2D; +desc.mipLevel = 0; +desc.baseArraySlice = 0; +desc.arraySize = 1; +dsv.Initialize(textureID, desc); + +// 使用简单参数初始化 +dsv.Initialize(textureID, 0); +``` ## 相关文档 diff --git a/docs/api/rhi/opengl/depth-stencil-view/openGLDepthStencilViewDesc.md b/docs/api/rhi/opengl/depth-stencil-view/openGLDepthStencilViewDesc.md new file mode 100644 index 00000000..fdbafd04 --- /dev/null +++ b/docs/api/rhi/opengl/depth-stencil-view/openGLDepthStencilViewDesc.md @@ -0,0 +1,30 @@ +# OpenGLDepthStencilViewDesc + +**命名空间**: `XCEngine::RHI` + +**描述**: 深度模板视图描述结构体。 + +## 成员变量 + +| 成员 | 类型 | 默认值 | 描述 | +|------|------|--------|------| +| `type` | `DepthStencilType` | `Texture2D` | 深度模板视图类型 | +| `mipLevel` | `int` | `0` | mipmap 级别 | +| `baseArraySlice` | `int` | `0` | 数组起始索引 | +| `arraySize` | `int` | `1` | 数组大小 | +| `layer` | `int` | `0` | 层索引 | + +## 示例 + +```cpp +OpenGLDepthStencilViewDesc desc; +desc.type = DepthStencilType::Texture2D; +desc.mipLevel = 0; +desc.baseArraySlice = 0; +desc.arraySize = 1; +desc.layer = 0; +``` + +## 相关文档 + +- [OpenGLDepthStencilView 总览](depth-stencil-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/depth-stencil-view/shutdown.md b/docs/api/rhi/opengl/depth-stencil-view/shutdown.md index 51497b76..e231b213 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/shutdown.md +++ b/docs/api/rhi/opengl/depth-stencil-view/shutdown.md @@ -4,7 +4,13 @@ void Shutdown(); ``` -关闭深度模板视图。 +关闭深度模板视图，释放关联的帧缓冲对象资源。调用此方法后会删除帧缓冲并将内部状态重置为初始值。 + +**返回值：** `void` + +## 相关文档 + +- [OpenGLDepthStencilView 总览](depth-stencil-view.md) - 返回类总览 ## 相关文档 diff --git a/docs/api/rhi/opengl/depth-stencil-view/unbind-framebuffer.md b/docs/api/rhi/opengl/depth-stencil-view/unbind-framebuffer.md index a686aa0b..932cb27a 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/unbind-framebuffer.md +++ b/docs/api/rhi/opengl/depth-stencil-view/unbind-framebuffer.md @@ -4,7 +4,9 @@ static void UnbindFramebuffer() ``` -静态方法，解除当前深度模板帧缓冲区的绑定。 +静态方法，将默认帧缓冲（framebuffer 0）绑定为当前深度模板帧缓冲区，用于解除任何自定义深度模板帧缓冲的绑定。 + +**返回值：** `void` **示例：** diff --git a/docs/api/rhi/opengl/depth-stencil-view/unbind.md b/docs/api/rhi/opengl/depth-stencil-view/unbind.md index 1a010d30..98ba8a57 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/unbind.md +++ b/docs/api/rhi/opengl/depth-stencil-view/unbind.md @@ -1,10 +1,16 @@ # OpenGLDepthStencilView::Unbind ```cpp -void Unbind() const; +void Unbind(); ``` -解除绑定深度模板视图。 +解除深度模板视图的帧缓冲绑定，将主帧缓冲（默认帧缓冲）重新绑定到当前 OpenGL 上下文。 + +**返回值：** `void` + +## 相关文档 + +- [OpenGLDepthStencilView 总览](depth-stencil-view.md) - 返回类总览 ## 相关文档 diff --git a/docs/api/rhi/opengl/device/compile-shader.md b/docs/api/rhi/opengl/device/compile-shader.md new file mode 100644 index 00000000..1b441aad --- /dev/null +++ b/docs/api/rhi/opengl/device/compile-shader.md @@ -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 着色器实现 diff --git a/docs/api/rhi/opengl/device/constructor.md b/docs/api/rhi/opengl/device/constructor.md new file mode 100644 index 00000000..ed4e8f0e --- /dev/null +++ b/docs/api/rhi/opengl/device/constructor.md @@ -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) - 使用现有窗口初始化 diff --git a/docs/api/rhi/opengl/device/create-buffer.md b/docs/api/rhi/opengl/device/create-buffer.md new file mode 100644 index 00000000..7ee45bd6 --- /dev/null +++ b/docs/api/rhi/opengl/device/create-buffer.md @@ -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 缓冲区实现 diff --git a/docs/api/rhi/opengl/device/create-command-list.md b/docs/api/rhi/opengl/device/create-command-list.md new file mode 100644 index 00000000..3ec31154 --- /dev/null +++ b/docs/api/rhi/opengl/device/create-command-list.md @@ -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 命令列表实现 diff --git a/docs/api/rhi/opengl/device/create-command-queue.md b/docs/api/rhi/opengl/device/create-command-queue.md new file mode 100644 index 00000000..6e4fe54e --- /dev/null +++ b/docs/api/rhi/opengl/device/create-command-queue.md @@ -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 命令队列实现 diff --git a/docs/api/rhi/opengl/device/create-fence.md b/docs/api/rhi/opengl/device/create-fence.md new file mode 100644 index 00000000..16282d36 --- /dev/null +++ b/docs/api/rhi/opengl/device/create-fence.md @@ -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 栅栏实现 diff --git a/docs/api/rhi/opengl/device/create-pipeline-state.md b/docs/api/rhi/opengl/device/create-pipeline-state.md new file mode 100644 index 00000000..a12f41dd --- /dev/null +++ b/docs/api/rhi/opengl/device/create-pipeline-state.md @@ -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 管线状态实现 diff --git a/docs/api/rhi/opengl/device/create-sampler.md b/docs/api/rhi/opengl/device/create-sampler.md new file mode 100644 index 00000000..c7ed62d1 --- /dev/null +++ b/docs/api/rhi/opengl/device/create-sampler.md @@ -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 采样器实现 diff --git a/docs/api/rhi/opengl/device/create-swap-chain.md b/docs/api/rhi/opengl/device/create-swap-chain.md new file mode 100644 index 00000000..2be34e3f --- /dev/null +++ b/docs/api/rhi/opengl/device/create-swap-chain.md @@ -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) - 交换缓冲区 diff --git a/docs/api/rhi/opengl/device/create-texture.md b/docs/api/rhi/opengl/device/create-texture.md new file mode 100644 index 00000000..08133d3b --- /dev/null +++ b/docs/api/rhi/opengl/device/create-texture.md @@ -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 纹理实现 diff --git a/docs/api/rhi/opengl/device/destructor.md b/docs/api/rhi/opengl/device/destructor.md new file mode 100644 index 00000000..cba0dccc --- /dev/null +++ b/docs/api/rhi/opengl/device/destructor.md @@ -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) - 关闭设备 diff --git a/docs/api/rhi/opengl/device/device.md b/docs/api/rhi/opengl/device/device.md index c63ade7d..194058f1 100644 --- a/docs/api/rhi/opengl/device/device.md +++ b/docs/api/rhi/opengl/device/device.md @@ -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)) { + // 使用已有窗口继续渲染 +} +``` ## 相关文档 diff --git a/docs/api/rhi/opengl/device/get-capabilities.md b/docs/api/rhi/opengl/device/get-capabilities.md new file mode 100644 index 00000000..abb9fdf6 --- /dev/null +++ b/docs/api/rhi/opengl/device/get-capabilities.md @@ -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) - 获取设备信息 diff --git a/docs/api/rhi/opengl/device/get-device-info-impl.md b/docs/api/rhi/opengl/device/get-device-info-impl.md new file mode 100644 index 00000000..c6fbc87a --- /dev/null +++ b/docs/api/rhi/opengl/device/get-device-info-impl.md @@ -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) - 获取设备信息（公共接口） diff --git a/docs/api/rhi/opengl/device/get-device-info.md b/docs/api/rhi/opengl/device/get-device-info.md new file mode 100644 index 00000000..656ef1f1 --- /dev/null +++ b/docs/api/rhi/opengl/device/get-device-info.md @@ -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) - 获取设备信息实现 diff --git a/docs/api/rhi/opengl/device/get-native-device.md b/docs/api/rhi/opengl/device/get-native-device.md new file mode 100644 index 00000000..be03fc3c --- /dev/null +++ b/docs/api/rhi/opengl/device/get-native-device.md @@ -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) - 获取设备能力 diff --git a/docs/api/rhi/opengl/device/get-native-handle.md b/docs/api/rhi/opengl/device/get-native-handle.md new file mode 100644 index 00000000..b6735a84 --- /dev/null +++ b/docs/api/rhi/opengl/device/get-native-handle.md @@ -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 窗口指针 diff --git a/docs/api/rhi/opengl/device/initialize.md b/docs/api/rhi/opengl/device/initialize.md new file mode 100644 index 00000000..527ab646 --- /dev/null +++ b/docs/api/rhi/opengl/device/initialize.md @@ -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) - 关闭设备 diff --git a/docs/api/rhi/opengl/device/shutdown.md b/docs/api/rhi/opengl/device/shutdown.md new file mode 100644 index 00000000..2f554580 --- /dev/null +++ b/docs/api/rhi/opengl/device/shutdown.md @@ -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) - 创建渲染窗口 diff --git a/docs/api/rhi/opengl/fence/fence.md b/docs/api/rhi/opengl/fence/fence.md index 4a50e3d1..5177b033 100644 --- a/docs/api/rhi/opengl/fence/fence.md +++ b/docs/api/rhi/opengl/fence/fence.md @@ -2,22 +2,71 @@ **命名空间**: `XCEngine::RHI` -**描述**: OpenGL 栅栏同步实现，继承自 `RHIFence`。 +**描述**: OpenGL 栅栏同步实现，继承自 `RHIFence`。使用 OpenGL `GLsync` 对象实现 CPU-GPU 同步机制。 + +## 概述 + +`OpenGLFence` 提供基于 OpenGL 同步对象（`GLsync`）的栅栏实现，用于 CPU-GPU 同步。当 GPU 完成特定操作后，栅栏会被设置为 signaled 状态，CPU 可以通过 `Wait` 方法等待该状态。 + +### FenceStatus 枚举 + +```cpp +enum class FenceStatus { + Signaled, // 栅栏已signaled，操作已完成 + Unsignaled, // 栅栏未signaled，操作未完成 + Error // 发生错误 +}; +``` + +### 私有成员 + +| 成员 | 类型 | 描述 | +|------|------|------| +| `m_sync` | `void*` | OpenGL GLsync 句柄 | +| `m_fenceValue` | `uint64_t` | 当前栅栏值 | +| `m_completedValue` | `uint64_t` | 已完成的栅栏值 | +| `m_signaled` | `bool` | 软件层面的signaled状态标志 | ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](initialize.md) | 初始化栅栏 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭栅栏 | -| [`Signal`](signal.md) | 信号栅栏 | -| [`Wait`](../../../threading/task-group/wait.md) | 等待栅栏 | -| [`Reset`](reset.md) | 重置栅栏 | -| [`IsSignaled`](is-signaled.md) | 检查是否已信号 | -| [`GetStatus`](get-status.md) | 获取状态 | -| [`GetCompletedValue`](get-completed-value.md) | 获取完成值 | -| [`GetCurrentValue`](get-current-value.md) | 获取当前值 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| [`Initialize`](initialize.md) | 初始化栅栏，设置初始值和状态 | +| [`Shutdown`](shutdown.md) | 关闭栅栏，释放 GLsync 资源 | +| [`Signal`](signal.md) | 信号栅栏，创建/更新同步对象 | +| [`Wait`](wait.md) | 等待栅栏达到 signaled 状态 | +| [`Reset`](reset.md) | 重置栅栏，删除同步对象 | +| [`IsSignaled`](is-signaled.md) | 检查软件层面的signaled状态 | +| [`GetStatus`](get-status.md) | 获取 OpenGL 层面的同步状态 | +| [`GetCompletedValue`](get-completed-value.md) | 获取已完成的栅栏值 | +| [`GetCurrentValue`](get-current-value.md) | 获取当前栅栏值 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生 GLsync 句柄 | + +## 使用示例 + +```cpp +#include "XCEngine/RHI/OpenGL/OpenGLFence.h" + +using namespace XCEngine::RHI; + +// 创建并初始化栅栏 +OpenGLFence fence; +fence.Initialize(false); + +// 执行 GPU 操作后信号栅栏 +fence.Signal(); + +// 等待栅栏，最多等待 1 秒 +fence.Wait(1000000000); + +// 检查状态 +if (fence.IsSignaled()) { + // 操作已完成 +} + +// 重置并复用 +fence.Reset(); +``` ## 相关文档 diff --git a/docs/api/rhi/opengl/fence/get-completed-value.md b/docs/api/rhi/opengl/fence/get-completed-value.md index 0d03ce1c..9566180f 100644 --- a/docs/api/rhi/opengl/fence/get-completed-value.md +++ b/docs/api/rhi/opengl/fence/get-completed-value.md @@ -1,19 +1,41 @@ # OpenGLFence::GetCompletedValue ```cpp -uint64_t GetCompletedValue() const override +uint64_t GetCompletedValue() const override; ``` 获取已完成的最大栅栏值。 -**返回：** `uint64_t` - 已完成的栅栏值 +## 详细描述 -**示例：** +返回 `m_completedValue`，表示已确认完成的栅栏值。每次 `Wait()` 成功返回且同步对象已信号时更新。 + +此值用于判断在 `Wait(value)` 中指定的栅栏值是否已完成。 + +## 参数 + +无 + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `uint64_t` | 已完成的栅栏值 | + +## 示例 ```cpp +OpenGLFence fence; +fence.Initialize(false); +fence.Signal(5); +fence.Wait(1000000000); // 等待完成后 + uint64_t completed = fence.GetCompletedValue(); +// completed >= 5 ``` ## 相关文档 -- [OpenGLFence](fence.md) - 返回类总览 +- [OpenGLFence 总览](fence.md) - 返回类总览 +- [GetCurrentValue](get-current-value.md) - 获取当前栅栏值 +- [Wait](wait.md) - 等待特定栅栏值 diff --git a/docs/api/rhi/opengl/fence/get-current-value.md b/docs/api/rhi/opengl/fence/get-current-value.md index 22433f9f..810a814b 100644 --- a/docs/api/rhi/opengl/fence/get-current-value.md +++ b/docs/api/rhi/opengl/fence/get-current-value.md @@ -1,19 +1,41 @@ # OpenGLFence::GetCurrentValue ```cpp -uint64_t GetCurrentValue() const +uint64_t GetCurrentValue() const; ``` 获取栅栏的当前值。 -**返回：** `uint64_t` - 当前栅栏值 +## 详细描述 -**示例：** +返回 `m_fenceValue`，表示栅栏的最新值。每次调用 `Signal()` 时更新。 + +## 参数 + +无 + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `uint64_t` | 当前栅栏值 | + +## 示例 ```cpp -uint64_t current = fence.GetCurrentValue(); +OpenGLFence fence; +fence.Initialize(false); + +uint64_t initial = fence.GetCurrentValue(); // 0 + +fence.Signal(); +uint64_t afterSignal = fence.GetCurrentValue(); // 1 + +fence.Signal(10); +uint64_t afterValue = fence.GetCurrentValue(); // 10 ``` ## 相关文档 -- [OpenGLFence](fence.md) - 返回类总览 +- [OpenGLFence 总览](fence.md) - 返回类总览 +- [GetCompletedValue](get-completed-value.md) - 获取已完成的栅栏值 diff --git a/docs/api/rhi/opengl/fence/get-native-handle.md b/docs/api/rhi/opengl/fence/get-native-handle.md new file mode 100644 index 00000000..3fbe7973 --- /dev/null +++ b/docs/api/rhi/opengl/fence/get-native-handle.md @@ -0,0 +1,43 @@ +# OpenGLFence::GetNativeHandle + +```cpp +void* GetNativeHandle() override; +``` + +获取 OpenGL 同步对象句柄。 + +## 详细描述 + +返回指向 `GLsync` 对象的指针。返回值为 `m_sync`，类型为 `void*`。 + +## 参数 + +无 + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `void*` | OpenGL `GLsync` 句柄。如果未调用过 `Signal()`，则返回 `nullptr` | + +## 复杂度 + +O(1) - 常数时间 + +## 示例 + +```cpp +OpenGLFence fence; +fence.Initialize(false); +fence.Signal(); + +void* handle = fence.GetNativeHandle(); +if (handle != nullptr) { + // 可以传递给其他 OpenGL 函数 + GLsync sync = static_cast(handle); +} +``` + +## 相关文档 + +- [OpenGLFence 总览](fence.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/fence/get-status.md b/docs/api/rhi/opengl/fence/get-status.md index e9412168..fff16e5d 100644 --- a/docs/api/rhi/opengl/fence/get-status.md +++ b/docs/api/rhi/opengl/fence/get-status.md @@ -1,25 +1,50 @@ # OpenGLFence::GetStatus ```cpp -FenceStatus GetStatus() const +FenceStatus GetStatus() const; ``` 获取栅栏的当前状态。 -**返回：** `FenceStatus` - 栅栏状态，可能的值： -- `FenceStatus::Signaled` - 栅栏已signaled -- `FenceStatus::Unsignaled` - 栅栏未signaled -- `FenceStatus::Error` - 发生错误 +## 详细描述 -**示例：** +此方法查询 OpenGL 同步对象的实际状态： + +1. 如果 `m_sync` 为 `nullptr`，返回软件层面的 `m_signaled` 状态 +2. 如果 `m_sync` 存在，调用 `glGetSynciv(sync, GL_SYNC_STATUS, ...)` 查询 OpenGL 状态 +3. 根据 `GL_SYNC_STATUS` 返回 `FenceStatus::Signaled` 或 `FenceStatus::Unsignaled` + +与 `IsSignaled()` 的区别： +- `GetStatus()`：查询 OpenGL 同步对象状态，更准确但有 GPU 开销 +- `IsSignaled()`：返回软件标志，快速但不反映 GPU 实际状态 + +## 参数 + +无 + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `FenceStatus` | 栅栏状态，值为以下之一： | +| | `FenceStatus::Signaled` - 栅栏已signaled，GPU 操作已完成 | +| | `FenceStatus::Unsignaled` - 栅栏未signaled，GPU 操作未完成 | +| | `FenceStatus::Error` - 此实现不会返回此值（错误处理在底层） | + +## 示例 ```cpp +OpenGLFence fence; +fence.Initialize(false); +fence.Signal(); + FenceStatus status = fence.GetStatus(); if (status == FenceStatus::Signaled) { - // 操作已完成 + // GPU 操作已完成 } ``` ## 相关文档 -- [OpenGLFence](fence.md) - 返回类总览 +- [OpenGLFence 总览](fence.md) - 返回类总览 +- [IsSignaled](is-signaled.md) - 快速状态检查 diff --git a/docs/api/rhi/opengl/fence/initialize.md b/docs/api/rhi/opengl/fence/initialize.md index ca64bb08..03838756 100644 --- a/docs/api/rhi/opengl/fence/initialize.md +++ b/docs/api/rhi/opengl/fence/initialize.md @@ -4,20 +4,38 @@ bool Initialize(bool signaled = false); ``` -初始化 OpenGL 栅栏。 +初始化 OpenGLFence 实例，设置栅栏的初始值和状态。 -**参数：** -- `signaled` - 初始是否为 signaled 状态 +## 详细描述 -**返回：** 成功返回 true +此方法不创建 OpenGL 同步对象（`GLsync`），仅初始化内部状态。`GLsync` 对象在首次调用 `Signal()` 时才被创建。 -**示例：** +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `signaled` | `bool` | 初始是否为 signaled 状态。默认为 `false`（Unsignaled） | + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `bool` | 始终返回 `true`。初始化成功 | + +## 示例 ```cpp OpenGLFence fence; -fence.Initialize(true); +// 创建为 unsignaled 状态 +fence.Initialize(false); + +// 或创建为 already signaled 状态 +OpenGLFence fence2; +fence2.Initialize(true); ``` ## 相关文档 - [OpenGLFence 总览](fence.md) - 返回类总览 +- [Signal](signal.md) - 创建 GLsync 对象 +- [Shutdown](shutdown.md) - 释放资源 diff --git a/docs/api/rhi/opengl/fence/is-signaled.md b/docs/api/rhi/opengl/fence/is-signaled.md index 8ec86c88..45f240e0 100644 --- a/docs/api/rhi/opengl/fence/is-signaled.md +++ b/docs/api/rhi/opengl/fence/is-signaled.md @@ -1,21 +1,43 @@ # OpenGLFence::IsSignaled ```cpp -bool IsSignaled() const override +bool IsSignaled() const override; ``` 检查栅栏是否处于 signaled 状态。 -**返回：** `bool` - 如果栅栏已signaled返回 true，否则返回 false +## 详细描述 -**示例：** +此方法返回软件层面的 `m_signaled` 标志状态，不查询 OpenGL 同步对象。 + +与 `GetStatus()` 的区别： +- `IsSignaled()`：返回软件标志，快速但可能不反映 GPU 实际状态 +- `GetStatus()`：查询 `GLsync` 对象的 OpenGL 状态，结果更准确但有额外开销 + +## 参数 + +无 + +## 返回值 + +| 类型 | 描述 | +|------|------| +| `bool` | `true` 表示栅栏已信号，`false` 表示未信号 | + +## 示例 ```cpp +OpenGLFence fence; +fence.Initialize(false); + if (fence.IsSignaled()) { - // 可以安全地继续执行 + // 操作已完成 +} else { + // 操作未完成 } ``` ## 相关文档 -- [OpenGLFence](fence.md) - 返回类总览 +- [OpenGLFence 总览](fence.md) - 返回类总览 +- [GetStatus](get-status.md) - 查询 OpenGL 同步状态 diff --git a/docs/api/rhi/opengl/fence/reset.md b/docs/api/rhi/opengl/fence/reset.md index a3951268..94d739f6 100644 --- a/docs/api/rhi/opengl/fence/reset.md +++ b/docs/api/rhi/opengl/fence/reset.md @@ -4,14 +4,44 @@ void Reset(); ``` -重置栅栏。 +重置栅栏为 unsignaled 状态。 -**示例：** +## 详细描述 + +此方法执行以下操作： + +1. 如果存在 `m_sync`，调用 `glDeleteSync()` 删除 OpenGL 同步对象 +2. 将 `m_sync` 置为 `nullptr` +3. 将 `m_signaled` 设置为 `false` + +重置后，栅栏的 `IsSignaled()` 将返回 `false`，可重新用于新的同步操作。 + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 ```cpp -fence->Reset(); +OpenGLFence fence; +fence.Initialize(false); +fence.Signal(); + +// 使用后重置 +fence.Reset(); + +// 此时 IsSignaled() 返回 false +if (!fence.IsSignaled()) { + // 可以重新使用 +} ``` ## 相关文档 - [OpenGLFence 总览](fence.md) - 返回类总览 +- [Signal](signal.md) - 信号栅栏 +- [IsSignaled](is-signaled.md) - 检查状态 diff --git a/docs/api/rhi/opengl/fence/shutdown.md b/docs/api/rhi/opengl/fence/shutdown.md new file mode 100644 index 00000000..4cde248e --- /dev/null +++ b/docs/api/rhi/opengl/fence/shutdown.md @@ -0,0 +1,39 @@ +# OpenGLFence::Shutdown + +```cpp +void Shutdown() override; +``` + +释放 OpenGL 栅栏资源。 + +## 详细描述 + +如果 `m_sync` 不为 `nullptr`，调用 `glDeleteSync()` 删除 OpenGL 同步对象，然后将 `m_sync` 置为 `nullptr`。 + +此方法由析构函数自动调用，确保资源正确释放。 + +## 参数 + +无 + +## 返回值 + +无 + +## 示例 + +```cpp +OpenGLFence fence; +fence.Initialize(false); +fence.Signal(); + +// 显式关闭，释放 GLsync 资源 +fence.Shutdown(); + +// fence 对象销毁时会再次调用 Shutdown，但已是安全操作 +``` + +## 相关文档 + +- [OpenGLFence 总览](fence.md) - 返回类总览 +- [Initialize](initialize.md) - 初始化 diff --git a/docs/api/rhi/opengl/fence/signal.md b/docs/api/rhi/opengl/fence/signal.md index 52eb47a6..d14d6ea5 100644 --- a/docs/api/rhi/opengl/fence/signal.md +++ b/docs/api/rhi/opengl/fence/signal.md @@ -1,20 +1,48 @@ # OpenGLFence::Signal ```cpp -void Signal() override -void Signal(uint64_t value) override +void Signal() override; +void Signal(uint64_t value) override; ``` 将栅栏设置为 signaled 状态，通知等待的线程操作完成。 -**示例：** +## 详细描述 + +`Signal()` 执行以下操作： + +1. 调用 `glFlush()` 确保所有挂起的 OpenGL 命令已发送到 GPU +2. 增加 `m_fenceValue`（无参版本）或设置为指定值 +3. 设置 `m_signaled = true` +4. 如果 `m_sync` 已存在，先删除旧对象 +5. 调用 `glFenceSync()` 创建新的 `GLsync` 对象 + +## 参数 + +| 重载 | 参数 | 类型 | 描述 | +|------|------|------|------| +| `Signal()` | 无 | - | 将栅栏值增加 1 | +| `Signal(uint64_t value)` | `value` | `uint64_t` | 设置栅栏为指定值 | + +## 返回值 + +无 + +## 示例 ```cpp OpenGLFence fence; fence.Initialize(false); + +// 无参版本：栅栏值 +1 fence.Signal(); + +// 带值版本：设置指定栅栏值 +fence.Signal(5); ``` ## 相关文档 -- [OpenGLFence](fence.md) - 返回类总览 +- [OpenGLFence 总览](fence.md) - 返回类总览 +- [Wait](wait.md) - 等待栅栏 +- [Initialize](initialize.md) - 初始化 diff --git a/docs/api/rhi/opengl/fence/wait.md b/docs/api/rhi/opengl/fence/wait.md new file mode 100644 index 00000000..be6fbb5c --- /dev/null +++ b/docs/api/rhi/opengl/fence/wait.md @@ -0,0 +1,50 @@ +# OpenGLFence::Wait + +```cpp +void Wait(uint64_t timeoutNs) override; +``` + +等待栅栏达到 signaled 状态或超时。 + +## 详细描述 + +此方法尝试等待 `m_sync`（OpenGL 同步对象）变为 signaled 状态： + +- **未信号或无同步对象**：直接调用 `glFinish()` 阻塞 CPU，直到 GPU 完成所有命令，然后将 `m_completedValue` 更新为 `m_fenceValue` +- **已信号状态**：调用 `glClientWaitSync()` 尝试获取同步状态，支持超时 +- **timeout = 0**：立即返回，不阻塞 + +内部使用 `GL_SYNC_FLUSH_COMMANDS_BIT` 标志确保客户端命令已刷新。 + +## 参数 + +| 参数 | 类型 | 描述 | +|------|------|------| +| `timeoutNs` | `uint64_t` | 超时时间，以纳秒为单位。为 `0` 时立即返回 | + +## 返回值 + +无 + +## 示例 + +```cpp +OpenGLFence fence; +fence.Initialize(false); +fence.Signal(); + +// 等待最多 1 秒 (1000000000 ns) +fence.Wait(1000000000); + +// 等待最多 100 毫秒 +fence.Wait(100000000); + +// timeout = 0 立即返回 +fence.Wait(0); +``` + +## 相关文档 + +- [OpenGLFence 总览](fence.md) - 返回类总览 +- [Signal](signal.md) - 信号栅栏 +- [IsSignaled](is-signaled.md) - 非阻塞检查状态 diff --git a/docs/api/rhi/opengl/overview.md b/docs/api/rhi/opengl/overview.md index 777487f9..3dcedf24 100644 --- a/docs/api/rhi/opengl/overview.md +++ b/docs/api/rhi/opengl/overview.md @@ -37,5 +37,5 @@ ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHI 模块总览](../rhi.md) - RHI 模块总览 - [D3D12 后端](overview.md) diff --git a/docs/api/rhi/opengl/pipeline-state/bind.md b/docs/api/rhi/opengl/pipeline-state/bind.md new file mode 100644 index 00000000..b5e77914 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/bind.md @@ -0,0 +1,24 @@ +# OpenGLPipelineState::Bind + +```cpp +void Bind() override; +``` + +绑定管线状态到当前渲染上下文。 + +**线程安全：** ❌ + +**注意：** 如果 shader 已附加（通过 `AttachShader`），则调用 `glUseProgram`。然后调用 `Apply()` 应用所有状态。 + +**示例：** + +```cpp +pipelineState->AttachShader(program); +pipelineState->Bind(); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [Unbind](unbind.md) - 解绑管线状态 +- [AttachShader](attach-shader.md) - 附加着色器 diff --git a/docs/api/rhi/opengl/pipeline-state/clear.md b/docs/api/rhi/opengl/pipeline-state/clear.md new file mode 100644 index 00000000..7ef8b309 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/clear.md @@ -0,0 +1,31 @@ +# OpenGLPipelineState::Clear + +```cpp +void Clear(unsigned int buffers); +``` + +清除指定的缓冲区。 + +**参数：** +- `buffers` - 要清除的缓冲区标志位 + - `1` - 颜色缓冲区 (`GL_COLOR_BUFFER_BIT`) + - `2` - 深度缓冲区 (`GL_DEPTH_BUFFER_BIT`) + - `4` - 模板缓冲区 (`GL_STENCIL_BUFFER_BIT`) + +**线程安全：** ❌ + +**注意：** 调用此方法前应先通过 `SetClearColor` 设置清除颜色。 + +**示例：** + +```cpp +pipelineState->SetClearColor(0.0f, 0.0f, 0.0f, 1.0f); +pipelineState->Clear(0x1); // 清除颜色缓冲 +pipelineState->Clear(0x3); // 清除颜色和深度缓冲 +pipelineState->Clear(0x7); // 清除所有缓冲 +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [SetClearColor](set-clear-color.md) - 设置清除颜色 diff --git a/docs/api/rhi/opengl/pipeline-state/constructor.md b/docs/api/rhi/opengl/pipeline-state/constructor.md new file mode 100644 index 00000000..ca49c45e --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/constructor.md @@ -0,0 +1,21 @@ +# OpenGLPipelineState::OpenGLPipelineState + +```cpp +OpenGLPipelineState(); +``` + +构造一个 `OpenGLPipelineState` 对象。 + +**线程安全：** ❌ + +**注意：** 初始化清除颜色为 (0, 0, 0, 0)，program 句柄为 0，附加标志为 false。 + +**示例：** + +```cpp +auto* pipelineState = new OpenGLPipelineState(); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/pipeline-state/destructor.md b/docs/api/rhi/opengl/pipeline-state/destructor.md new file mode 100644 index 00000000..1fde42d3 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/destructor.md @@ -0,0 +1,22 @@ +# OpenGLPipelineState::~OpenGLPipelineState + +```cpp +~OpenGLPipelineState() override; +``` + +销毁 `OpenGLPipelineState` 对象。 + +**线程安全：** ❌ + +**注意：** 不会调用 `Shutdown()`，如果资源需要释放，应在销毁前手动调用 `Shutdown()`。 + +**示例：** + +```cpp +delete pipelineState; +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [Shutdown](shutdown.md) - 关闭管线状态 diff --git a/docs/api/rhi/opengl/pipeline-state/get-native-handle.md b/docs/api/rhi/opengl/pipeline-state/get-native-handle.md new file mode 100644 index 00000000..998b5fe2 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/get-native-handle.md @@ -0,0 +1,26 @@ +# OpenGLPipelineState::GetNativeHandle + +```cpp +void* GetNativeHandle() override; +``` + +获取 OpenGL shader program 的原生句柄。 + +**返回：** +- OpenGL: `void*` 指向 `GLuint` 类型的 program 值 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +void* handle = pipelineState->GetNativeHandle(); +GLuint program = static_cast(reinterpret_cast(handle)); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [AttachShader](attach-shader.md) - 附加着色器 diff --git a/docs/api/rhi/opengl/pipeline-state/get-type.md b/docs/api/rhi/opengl/pipeline-state/get-type.md new file mode 100644 index 00000000..e2d8eba0 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/get-type.md @@ -0,0 +1,27 @@ +# OpenGLPipelineState::GetType + +```cpp +PipelineType GetType() const override; +``` + +获取管线类型。 + +**返回：** `PipelineType::Graphics` - OpenGL 只支持图形管线 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +PipelineType type = pipelineState->GetType(); +if (type == PipelineType::Graphics) { + // graphics pipeline +} +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [RHIPipelineState 总览](../../pipeline-state/pipeline-state.md) - 抽象管线状态接口 diff --git a/docs/api/rhi/opengl/pipeline-state/pipeline-state.md b/docs/api/rhi/opengl/pipeline-state/pipeline-state.md index 9b853bd3..4092e172 100644 --- a/docs/api/rhi/opengl/pipeline-state/pipeline-state.md +++ b/docs/api/rhi/opengl/pipeline-state/pipeline-state.md @@ -8,11 +8,13 @@ | 方法 | 描述 | |------|------| -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭管线状态 | -| [`Bind`](../../shader/bind.md) | 绑定管线状态 | -| [`Unbind`](../../shader/unbind.md) | 解绑管线状态 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | -| [`GetType`](../../command-queue/get-type.md) | 获取管线类型 | +| [`OpenGLPipelineState`](constructor.md) | 构造函数 | +| [`~OpenGLPipelineState`](destructor.md) | 析构函数 | +| [`Shutdown`](shutdown.md) | 关闭管线状态 | +| [`Bind`](bind.md) | 绑定管线状态 | +| [`Unbind`](unbind.md) | 解绑管线状态 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | +| [`GetType`](get-type.md) | 获取管线类型 | | [`SetDepthStencilState`](set-depth-stencil-state.md) | 设置深度模板状态 | | [`SetBlendState`](set-blend-state.md) | 设置混合状态 | | [`SetRasterizerState`](set-rasterizer-state.md) | 设置光栅化状态 | @@ -26,7 +28,7 @@ | [`ApplyViewport`](apply-viewport.md) | 应用视口 | | [`ApplyScissor`](apply-scissor.md) | 应用裁剪 | | [`SetClearColor`](set-clear-color.md) | 设置清除颜色 | -| [`Clear`](../../command-list/clear.md) | 清除 | +| [`Clear`](clear.md) | 清除 | | [`AttachShader`](attach-shader.md) | 附加着色器 | | [`DetachShader`](detach-shader.md) | 分离着色器 | | [`GetDepthStencilState`](get-depth-stencil-state.md) | 获取深度模板状态 | diff --git a/docs/api/rhi/opengl/pipeline-state/shutdown.md b/docs/api/rhi/opengl/pipeline-state/shutdown.md new file mode 100644 index 00000000..f8d5ed82 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/shutdown.md @@ -0,0 +1,21 @@ +# OpenGLPipelineState::Shutdown + +```cpp +void Shutdown() override; +``` + +关闭管线状态并释放资源。 + +**线程安全：** ❌ + +**注意：** 此方法将 shader program 置零，但不会调用 glDeleteProgram。 + +**示例：** + +```cpp +pipelineState->Shutdown(); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/pipeline-state/unbind.md b/docs/api/rhi/opengl/pipeline-state/unbind.md new file mode 100644 index 00000000..ade1f334 --- /dev/null +++ b/docs/api/rhi/opengl/pipeline-state/unbind.md @@ -0,0 +1,20 @@ +# OpenGLPipelineState::Unbind + +```cpp +void Unbind() override; +``` + +解绑管线状态，将当前 program 设为 0。 + +**线程安全：** ❌ + +**示例：** + +```cpp +pipelineState->Unbind(); +``` + +## 相关文档 + +- [OpenGLPipelineState 总览](pipeline-state.md) - 返回类总览 +- [Bind](bind.md) - 绑定管线状态 diff --git a/docs/api/rhi/opengl/render-target-view/bind.md b/docs/api/rhi/opengl/render-target-view/bind.md index 4a621cfe..4c603d72 100644 --- a/docs/api/rhi/opengl/render-target-view/bind.md +++ b/docs/api/rhi/opengl/render-target-view/bind.md @@ -1,10 +1,35 @@ # OpenGLRenderTargetView::Bind ```cpp -void Bind() const; +void Bind(unsigned int slot = 0); +void Bind(unsigned int count, const unsigned int* framebuffers, const int* drawBuffers); ``` -绑定渲染目标视图。 +绑定渲染目标视图作为当前渲染目标。 + +**重载 1 参数：** +- `slot` - 绑定槽位（预留参数，当前实现中未使用） + +**重载 2 参数：** +- `count` - 帧缓冲区数量 +- `framebuffers` - 帧缓冲区 ID 数组 +- `drawBuffers` - 对应每个帧缓冲区的绘制缓冲附件 + +**行为说明：** +- 当 `count` 为 1 时，直接绑定单个帧缓冲区 +- 当 `count` 大于 1 时，启用多重渲染目标（MRT），依次绑定各帧缓冲区并设置绘制缓冲附件 + +**示例：** + +```cpp +// 单帧缓冲绑定 +rtv.Bind(); + +// 多帧缓冲绑定 +unsigned int fbos[] = { fbo1, fbo2 }; +int attachments[] = { GL_COLOR_ATTACHMENT0, GL_COLOR_ATTACHMENT1 }; +rtv.Bind(2, fbos, attachments); +``` ## 相关文档 diff --git a/docs/api/rhi/opengl/render-target-view/clear.md b/docs/api/rhi/opengl/render-target-view/clear.md index 36c15411..484830db 100644 --- a/docs/api/rhi/opengl/render-target-view/clear.md +++ b/docs/api/rhi/opengl/render-target-view/clear.md @@ -2,15 +2,34 @@ ```cpp void Clear(float r, float g, float b, float a); +void Clear(float r, float g, float b, float a, float depth, uint8_t stencil); ``` -清除渲染目标视图。 +清除渲染目标视图的颜色缓冲区和可选的深度/模板缓冲区。 -**参数：** +**重载 1 参数（仅清除颜色）：** +- `r` - 红色分量（0.0f - 1.0f） +- `g` - 绿色分量（0.0f - 1.0f） +- `b` - 蓝色分量（0.0f - 1.0f） +- `a` - Alpha 分量（0.0f - 1.0f） + +**重载 2 参数（清除颜色、深度和模板）：** - `r` - 红色分量 - `g` - 绿色分量 - `b` - 蓝色分量 - `a` - Alpha 分量 +- `depth` - 深度值（通常 0.0f 或 1.0f） +- `stencil` - 模板值（0-255） + +**示例：** + +```cpp +// 仅清除颜色缓冲 +rtv.Clear(0.1f, 0.1f, 0.1f, 1.0f); + +// 清除颜色、深度和模板缓冲 +rtv.Clear(0.1f, 0.1f, 0.1f, 1.0f, 1.0f, 0); +``` ## 相关文档 diff --git a/docs/api/rhi/opengl/render-target-view/get-height.md b/docs/api/rhi/opengl/render-target-view/get-height.md new file mode 100644 index 00000000..3bbfc9e6 --- /dev/null +++ b/docs/api/rhi/opengl/render-target-view/get-height.md @@ -0,0 +1,19 @@ +# OpenGLRenderTargetView::GetHeight + +```cpp +int GetHeight() const; +``` + +获取渲染目标视图的高度（像素）。 + +**返回：** `int` - 渲染目标高度 + +**示例：** + +```cpp +int height = rtv.GetHeight(); +``` + +## 相关文档 + +- [OpenGLRenderTargetView 总览](render-target-view.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/render-target-view/get-size.md b/docs/api/rhi/opengl/render-target-view/get-size.md index eacc3d46..fde66303 100644 --- a/docs/api/rhi/opengl/render-target-view/get-size.md +++ b/docs/api/rhi/opengl/render-target-view/get-size.md @@ -1,13 +1,18 @@ -# OpenGLRenderTargetView::GetWidth / GetHeight +# OpenGLRenderTargetView::GetWidth ```cpp int GetWidth() const; -int GetHeight() const; ``` -获取渲染目标视图的宽度和高度。 +获取渲染目标视图的宽度（像素）。 -**返回：** 宽度/高度 +**返回：** `int` - 渲染目标宽度 + +**示例：** + +```cpp +int width = rtv.GetWidth(); +``` ## 相关文档 diff --git a/docs/api/rhi/opengl/render-target-view/initialize.md b/docs/api/rhi/opengl/render-target-view/initialize.md index d3f48c67..9a208cbb 100644 --- a/docs/api/rhi/opengl/render-target-view/initialize.md +++ b/docs/api/rhi/opengl/render-target-view/initialize.md @@ -1,17 +1,28 @@ # OpenGLRenderTargetView::Initialize ```cpp -bool Initialize(unsigned int texture, int width, int height); +bool Initialize(unsigned int texture, const OpenGLRenderTargetViewDesc& desc); +bool Initialize(unsigned int texture, int mipLevel = 0); ``` 初始化渲染目标视图。 -**参数：** +**重载 1 参数：** - `texture` - OpenGL 纹理 ID -- `width` - 宽度 -- `height` - 高度 +- `desc` - 渲染目标视图描述 -**返回：** 成功返回 true +**重载 2 参数：** +- `texture` - OpenGL 纹理 ID +- `mipLevel` - mipmap 级别（默认为 0） + +**返回：** `bool` - 成功返回 true，失败返回 false + +**示例：** + +```cpp +OpenGLRenderTargetView rtv; +rtv.Initialize(texture, 0); +``` ## 相关文档 diff --git a/docs/api/rhi/opengl/render-target-view/render-target-view.md b/docs/api/rhi/opengl/render-target-view/render-target-view.md index 5d071bb2..ed80d144 100644 --- a/docs/api/rhi/opengl/render-target-view/render-target-view.md +++ b/docs/api/rhi/opengl/render-target-view/render-target-view.md @@ -2,26 +2,87 @@ **命名空间**: `XCEngine::RHI` -**描述**: OpenGL 渲染目标视图实现。 +**描述**: OpenGL 渲染目标视图实现，用于将纹理绑定为渲染目标进行渲染输出。 + +## 类型定义 + +### RenderTargetType + +```cpp +enum class RenderTargetType { + Texture2D, // 2D 纹理 + Texture2DArray, // 2D 纹理数组 + Texture3D, // 3D 纹理 + TextureCube, // 立方体贴图 + TextureCubeArray // 立方体贴图数组 +}; +``` + +### OpenGLRenderTargetViewDesc + +```cpp +struct OpenGLRenderTargetViewDesc { + RenderTargetType type = RenderTargetType::Texture2D; // 渲染目标类型 + int mipLevel = 0; // Mip 级别 + int baseArraySlice = 0; // 数组起始索引 + int arraySize = 1; // 数组大小 + int layer = 0; // 层级（用于 3D 纹理） + uint32_t format = 0; // 格式 +}; +``` ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](initialize.md) | 初始化渲染目标视图 | +| [`Initialize`](initialize.md) | 初始化渲染目标视图（2 个重载） | | [`InitializeCubemap`](initialize-cubemap.md) | 初始化立方体贴图渲染目标视图 | | [`Shutdown`](shutdown.md) | 关闭渲染目标视图 | -| [`Bind`](bind.md) | 绑定渲染目标视图 | +| [`Bind`](bind.md) | 绑定渲染目标视图（2 个重载） | | [`Unbind`](unbind.md) | 解绑渲染目标视图 | -| [`Clear`](clear.md) | 清除 | +| [`Clear`](clear.md) | 清除（2 个重载） | | [`GetFramebuffer`](get-framebuffer.md) | 获取帧缓冲 | | [`GetTexture`](get-texture.md) | 获取纹理 | | [`GetMipLevel`](get-mip-level.md) | 获取 Mip 级别 | | [`GetWidth`](get-size.md) | 获取宽度 | -| [`GetHeight`](get-size.md) | 获取高度 | +| [`GetHeight`](get-height.md) | 获取高度 | | [`BindFramebuffer`](bind-framebuffer.md) | 绑定帧缓冲 | | [`UnbindFramebuffer`](unbind-framebuffer.md) | 解绑帧缓冲 | +## 使用示例 + +```cpp +#include "XCEngine/RHI/OpenGL/OpenGLRenderTargetView.h" + +void RenderToTexture() { + OpenGLRenderTargetView rtv; + + // 初始化为 2D 纹理渲染目标 + if (rtv.Initialize(textureID, 0)) { + rtv.Bind(); + rtv.Clear(0.0f, 0.0f, 0.0f, 1.0f); + // 执行渲染... + rtv.Unbind(); + } + + rtv.Shutdown(); +} + +void RenderToCubemap() { + OpenGLRenderTargetView rtv; + + // 初始化为立方体贴图的第一面 + if (rtv.InitializeCubemap(cubemapID, 0, 0)) { + rtv.Bind(); + rtv.Clear(0.0f, 0.0f, 0.0f, 1.0f); + // 执行渲染... + rtv.Unbind(); + } + + rtv.Shutdown(); +} +``` + ## 相关文档 - [OpenGL 后端总览](../overview.md) diff --git a/docs/api/rhi/opengl/render-target-view/shutdown.md b/docs/api/rhi/opengl/render-target-view/shutdown.md index 46cfebd2..f99c1b07 100644 --- a/docs/api/rhi/opengl/render-target-view/shutdown.md +++ b/docs/api/rhi/opengl/render-target-view/shutdown.md @@ -4,7 +4,20 @@ void Shutdown(); ``` -关闭渲染目标视图。 +关闭渲染目标视图，释放关联的帧缓冲区资源。此方法会在析构时自动调用，但也可手动调用以提前释放资源。 + +**注意：** 此方法仅删除帧缓冲区对象，不会删除关联的纹理对象。 + +**示例：** + +```cpp +OpenGLRenderTargetView rtv; +rtv.Initialize(texture, 0); + +// 使用 rtv... + +rtv.Shutdown(); // 释放帧缓冲区资源 +``` ## 相关文档 diff --git a/docs/api/rhi/opengl/render-target-view/unbind.md b/docs/api/rhi/opengl/render-target-view/unbind.md index 425460f0..b9e59043 100644 --- a/docs/api/rhi/opengl/render-target-view/unbind.md +++ b/docs/api/rhi/opengl/render-target-view/unbind.md @@ -1,10 +1,18 @@ # OpenGLRenderTargetView::Unbind ```cpp -void Unbind() const; +void Unbind(); ``` -解除绑定渲染目标视图。 +解除当前渲染目标视图的绑定，将默认帧缓冲区（framebuffer 0）设为当前渲染目标。 + +**示例：** + +```cpp +rtv.Bind(); +// 执行渲染... +rtv.Unbind(); // 解除绑定，恢复默认帧缓冲 +``` ## 相关文档 diff --git a/docs/api/rhi/opengl/sampler/bind.md b/docs/api/rhi/opengl/sampler/bind.md index a8d86494..141a0f5c 100644 --- a/docs/api/rhi/opengl/sampler/bind.md +++ b/docs/api/rhi/opengl/sampler/bind.md @@ -4,10 +4,14 @@ void Bind(unsigned int unit); ``` -绑定采样器到纹理单元。 +绑定采样器到指定纹理单元。调用 `glBindSampler` 将采样器对象绑定到对应的纹理单元，后续纹理采样操作将使用该采样器。 **参数：** -- `unit` - 纹理单元编号 +- `unit` - 纹理单元编号，通常为 0-15 + +**返回：** 无 + +**线程安全：** ❌ **复杂度：** O(1) diff --git a/docs/api/rhi/opengl/sampler/constructor.md b/docs/api/rhi/opengl/sampler/constructor.md new file mode 100644 index 00000000..d103099e --- /dev/null +++ b/docs/api/rhi/opengl/sampler/constructor.md @@ -0,0 +1,23 @@ +# OpenGLSampler::OpenGLSampler + +```cpp +OpenGLSampler(); +``` + +构造一个空的 OpenGLSampler 对象。实际采样器 ID 在调用 `Initialize` 之前无效（为 0）。 + +**参数：** 无 + +**返回：** 无 + +**复杂度：** O(1) + +**示例：** + +```cpp +OpenGLSampler sampler; +``` + +## 相关文档 + +- [OpenGLSampler 总览](sampler.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/sampler/get-id.md b/docs/api/rhi/opengl/sampler/get-id.md index 80340840..62564275 100644 --- a/docs/api/rhi/opengl/sampler/get-id.md +++ b/docs/api/rhi/opengl/sampler/get-id.md @@ -1,13 +1,19 @@ # OpenGLSampler::GetID ```cpp -unsigned int GetID() const -unsigned int GetID() override +unsigned int GetID() const; +unsigned int GetID() override; ``` -获取 OpenGL 采样器对象 ID。 +获取 OpenGL 采样器对象 ID。返回 `glGenSamplers` 生成的采样器对象名称。 -**返回：** `unsigned int` - 采样器 ID +**参数：** 无 + +**返回：** `unsigned int` - OpenGL 采样器 ID + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** diff --git a/docs/api/rhi/opengl/sampler/initialize.md b/docs/api/rhi/opengl/sampler/initialize.md index 59be4c5a..ba380f12 100644 --- a/docs/api/rhi/opengl/sampler/initialize.md +++ b/docs/api/rhi/opengl/sampler/initialize.md @@ -4,13 +4,25 @@ bool Initialize(const OpenGLSamplerDesc& desc); ``` -初始化采样器。 +初始化采样器。创建 OpenGL 采样器对象并根据描述符设置各项参数，包括过滤模式、环绕模式、各向异性级别和 LOD 范围。 **参数：** -- `desc` - 采样器描述符 +- `desc` - 采样器描述符，包含以下字段： + - `minFilter` - 缩小过滤模式 + - `magFilter` - 放大过滤模式 + - `wrapS` - S轴环绕模式 + - `wrapT` - T轴环绕模式 + - `wrapR` - R轴环绕模式 + - `maxAnisotropy` - 各向异性级别 + - `minLod` - 最小 LOD 值 + - `maxLod` - 最大 LOD 值 + - `compareMode` - 比较模式（当前实现未使用） + - `compareFunc` - 比较函数（当前实现未使用） **返回：** 成功返回 `true`，失败返回 `false` +**线程安全：** ❌ + **复杂度：** O(1) **示例：** @@ -21,7 +33,14 @@ desc.minFilter = SamplerFilter::LinearMipmapLinear; desc.magFilter = SamplerFilter::Linear; desc.wrapS = SamplerWrapMode::Repeat; desc.wrapT = SamplerWrapMode::Repeat; -sampler.Initialize(desc); +desc.maxAnisotropy = 16.0f; +desc.minLod = -1000.0f; +desc.maxLod = 1000.0f; + +OpenGLSampler sampler; +if (sampler.Initialize(desc)) { + // 采样器初始化成功 +} ``` ## 相关文档 diff --git a/docs/api/rhi/opengl/sampler/sampler.md b/docs/api/rhi/opengl/sampler/sampler.md index e90b9cbe..130911ba 100644 --- a/docs/api/rhi/opengl/sampler/sampler.md +++ b/docs/api/rhi/opengl/sampler/sampler.md @@ -1,19 +1,70 @@ # OpenGLSampler -**命名空间**: `XCEngine::RHI` +## 命名空间 -**描述**: OpenGL 采样器实现，继承自 `RHISampler`。 +`XCEngine::RHI` + +## 头文件 + +`XCEngine/RHI/OpenGL/OpenGLSampler.h` + +## 类型 + +| 类型 | 说明 | +|------|------| +| `OpenGLSampler` | OpenGL 采样器封装类，继承自 `RHISampler` | +| `OpenGLSamplerDesc` | 采样器描述结构体 | +| `SamplerWrapMode` | 采样器环绕模式枚举 | +| `SamplerFilter` | 采样器滤镜模式枚举 | +| `SamplerCompareMode` | 采样器比较模式枚举 | + +## 描述 + +OpenGL 采样器实现，继承自 `RHISampler`。 + +## 概述 + +`OpenGLSampler` 是 RHI 抽象层对 OpenGL 纹理采样器的封装。通过 `OpenGLSamplerDesc` 配置采样参数（过滤模式、环绕模式、各向异性、LOD 等），`Initialize` 方法创建 OpenGL 采样器对象，`Bind`/`Unbind` 控制采样器与纹理单元的绑定状态。 + +**关键特性：** +- 支持点采样、线性采样、各向异性采样 +- 支持 Repeat、Mirror、Clamp、Border 等寻址模式 +- 支持 Mipmap 多级渐远纹理过滤 +- 支持各向异性过滤和 LOD 范围控制 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](initialize.md) | 初始化采样器 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭采样器 | -| [`Bind`](bind.md) | 绑定采样器 | +| [`OpenGLSampler`](constructor.md) | 构造函数 | +| [`Initialize`](initialize.md) | 初始化采样器（OpenGL 特有） | +| [`Shutdown`](shutdown.md) | 关闭采样器 | +| [`Bind`](bind.md) | 绑定采样器到纹理单元 | | [`Unbind`](unbind.md) | 解绑采样器 | | [`GetID`](get-id.md) | 获取采样器 ID | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| [`GetNativeHandle`](../../sampler/get-native-handle.md) | 获取原生句柄（继承自 `RHISampler`） | + +## 使用示例 + +```cpp +#include "XCEngine/RHI/OpenGL/OpenGLSampler.h" + +using namespace XCEngine::RHI; + +OpenGLSamplerDesc desc; +desc.minFilter = SamplerFilter::LinearMipmapLinear; +desc.magFilter = SamplerFilter::Linear; +desc.wrapS = SamplerWrapMode::Repeat; +desc.wrapT = SamplerWrapMode::Repeat; +desc.maxAnisotropy = 16.0f; + +OpenGLSampler sampler; +if (sampler.Initialize(desc)) { + sampler.Bind(0); + sampler.Unbind(0); + sampler.Shutdown(); +} +``` ## 相关文档 diff --git a/docs/api/rhi/opengl/sampler/shutdown.md b/docs/api/rhi/opengl/sampler/shutdown.md new file mode 100644 index 00000000..1f1f8de4 --- /dev/null +++ b/docs/api/rhi/opengl/sampler/shutdown.md @@ -0,0 +1,29 @@ +# OpenGLSampler::Shutdown + +```cpp +void Shutdown() override; +``` + +关闭采样器。释放 OpenGL 采样器对象，调用 `glDeleteSamplers` 删除采样器并重置 ID 为 0。 + +**参数：** 无 + +**返回：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +OpenGLSampler sampler; +if (sampler.Initialize(desc)) { + sampler.Bind(0); + sampler.Shutdown(); +} +``` + +## 相关文档 + +- [OpenGLSampler 总览](sampler.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/sampler/unbind.md b/docs/api/rhi/opengl/sampler/unbind.md index d7263d61..466f47d1 100644 --- a/docs/api/rhi/opengl/sampler/unbind.md +++ b/docs/api/rhi/opengl/sampler/unbind.md @@ -4,10 +4,14 @@ void Unbind(unsigned int unit); ``` -解绑采样器。 +解绑采样器。将指定纹理单元的采样器绑定解除，实际调用 `glBindSampler(unit, 0)`。 **参数：** -- `unit` - 纹理单元编号 +- `unit` - 纹理单元编号，通常为 0-15 + +**返回：** 无 + +**线程安全：** ❌ **复杂度：** O(1) diff --git a/docs/api/rhi/opengl/shader/compile-type.md b/docs/api/rhi/opengl/shader/compile-type.md new file mode 100644 index 00000000..41656d78 --- /dev/null +++ b/docs/api/rhi/opengl/shader/compile-type.md @@ -0,0 +1,31 @@ +# OpenGLShader::Compile (单着色器) + +```cpp +bool Compile(const char* source, ShaderType type); +``` + +从源代码编译单个着色器（顶点、片段、几何、计算或细分着色器）。 + +**参数：** +- `source` - 着色器源代码 +- `type` - 着色器类型（`ShaderType::Vertex`、`ShaderType::Fragment`、`ShaderType::Geometry`、`ShaderType::Compute`、`ShaderType::TessControl`、`ShaderType::TessEvaluation`） + +**返回：** 成功返回 `true`，失败返回 `false` + +**线程安全：** ❌ + +**示例：** + +```cpp +const char* vs = R"( + #version 330 core + void main() { gl_Position = vec4(0.0); } +)"; +shader->Compile(vs, ShaderType::Vertex); +``` + +## 相关文档 + +- [OpenGLShader 总览](shader.md) - 返回类总览 +- [Compile (VS+FS)](compile-vs-fs.md) - 顶点+片段着色器版本 +- [CompileCompute](compile-compute.md) - 计算着色器版本 diff --git a/docs/api/rhi/opengl/shader/shader.md b/docs/api/rhi/opengl/shader/shader.md index 0e2dd213..8ac60d9f 100644 --- a/docs/api/rhi/opengl/shader/shader.md +++ b/docs/api/rhi/opengl/shader/shader.md @@ -8,9 +8,11 @@ | 方法 | 描述 | |------|------| -| [`CompileFromFile`](../../shader/compile-from-file.md) | 从文件编译着色器 | -| [`Compile`](../../shader/compile.md) | 从源码编译着色器 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭着色器 | +| [`CompileFromFile`](compile-from-file-vs-fs.md) | 从文件编译顶点+片段着色器 | +| [`Compile`](compile-vs-fs.md) | 从源码编译顶点+片段着色器 | +| [`Compile`](compile-type.md) | 从源码编译单着色器 | +| [`CompileCompute`](compile-compute.md) | 编译计算着色器 | +| [`Shutdown`](../../shader/shutdown.md) | 关闭着色器 | | [`Use`](use.md) | 使用着色器 | | [`Bind`](../../shader/bind.md) | 绑定着色器 | | [`Unbind`](../../shader/unbind.md) | 解绑着色器 | @@ -25,7 +27,7 @@ | [`GetID`](get-id.md) | 获取着色器 ID | | [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | | [`IsValid`](../../shader/is-valid.md) | 检查是否有效 | -| [`GetType`](../../command-queue/get-type.md) | 获取着色器类型 | +| [`GetType`](../../shader/get-type.md) | 获取着色器类型 | ## 相关文档 diff --git a/docs/api/rhi/opengl/swap-chain/constructor.md b/docs/api/rhi/opengl/swap-chain/constructor.md new file mode 100644 index 00000000..74ddeb19 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/constructor.md @@ -0,0 +1,24 @@ +# OpenGLSwapChain::OpenGLSwapChain + +```cpp +OpenGLSwapChain(); +``` + +构造空的 OpenGL 交换链对象。 + +**注意：** +- 构造函数不初始化交换链，需调用 `Initialize` 方法完成初始化 +- 初始化参数由 `Initialize` 方法指定 + +**示例：** + +```cpp +OpenGLSwapChain swapChain; +swapChain.Initialize(window, true); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [Initialize](initialize.md) - 初始化方法 +- [析构函数](destructor.md) - 析构函数 diff --git a/docs/api/rhi/opengl/swap-chain/destructor.md b/docs/api/rhi/opengl/swap-chain/destructor.md new file mode 100644 index 00000000..9da425d9 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/destructor.md @@ -0,0 +1,27 @@ +# OpenGLSwapChain::~OpenGLSwapChain + +```cpp +~OpenGLSwapChain() override; +``` + +销毁 OpenGL 交换链对象，自动调用 `Shutdown`。 + +**注意：** +- 析构函数自动调用 `Shutdown` 释放资源 +- 确保在销毁前调用 `Shutdown` 或确保交换链已初始化 + +**示例：** + +```cpp +{ + OpenGLSwapChain swapChain; + swapChain.Initialize(window, true); + // 使用交换链... +} // 析构函数自动调用 Shutdown +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [Shutdown](shutdown.md) - 关闭方法 +- [构造函数](constructor.md) - 构造函数 diff --git a/docs/api/rhi/opengl/swap-chain/get-current-back-buffer-index.md b/docs/api/rhi/opengl/swap-chain/get-current-back-buffer-index.md new file mode 100644 index 00000000..1e91af8e --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/get-current-back-buffer-index.md @@ -0,0 +1,26 @@ +# OpenGLSwapChain::GetCurrentBackBufferIndex + +```cpp +uint32_t GetCurrentBackBufferIndex() const override; +``` + +获取当前后台缓冲区的索引。 + +**返回：** 始终返回 0（OpenGL 交换链使用单一帧缓冲） + +**线程安全：** ❌ + +**注意：** +- OpenGL 交换链实现返回 0，因为使用单一帧缓冲而非多缓冲 +- 该方法继承自 `RHISwapChain` 抽象接口 + +**示例：** + +```cpp +uint32_t index = swapChain->GetCurrentBackBufferIndex(); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) +- [GetCurrentBackBuffer](get-current-back-buffer.md) - 获取当前后台缓冲区 diff --git a/docs/api/rhi/opengl/swap-chain/get-current-back-buffer.md b/docs/api/rhi/opengl/swap-chain/get-current-back-buffer.md new file mode 100644 index 00000000..3f648a06 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/get-current-back-buffer.md @@ -0,0 +1,28 @@ +# OpenGLSwapChain::GetCurrentBackBuffer + +```cpp +RHITexture* GetCurrentBackBuffer() override; +``` + +获取当前后台缓冲区纹理对象。 + +**返回：** `nullptr`（OpenGL 交换链不支持此方法） + +**线程安全：** ❌ + +**注意：** +- OpenGL 交换链基于 GLFW 窗口，不提供独立的后台缓冲区纹理 +- 该方法继承自 `RHISwapChain` 抽象接口 +- 如需渲染到纹理，请使用 Framebuffer Object (FBO) + +**示例：** + +```cpp +RHITexture* backBuffer = swapChain->GetCurrentBackBuffer(); +// 返回 nullptr +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) +- [GetCurrentBackBufferIndex](get-current-back-buffer-index.md) - 获取当前后台缓冲区索引 diff --git a/docs/api/rhi/opengl/swap-chain/get-framebuffer-height.md b/docs/api/rhi/opengl/swap-chain/get-framebuffer-height.md new file mode 100644 index 00000000..674cf4b5 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/get-framebuffer-height.md @@ -0,0 +1,26 @@ +# OpenGLSwapChain::GetFramebufferHeight + +```cpp +int GetFramebufferHeight() const; +``` + +获取帧缓冲区高度。 + +**返回：** 帧缓冲区高度（像素） + +**线程安全：** ❌ + +**注意：** +- 帧缓冲区大小可能与窗口大小不同（HiDPI 显示） +- 通过 `glfwGetFramebufferSize` 获取 + +**示例：** + +```cpp +int fbHeight = swapChain->GetFramebufferHeight(); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) +- [GetFramebufferWidth](get-framebuffer-width.md) - 获取帧缓冲宽度 diff --git a/docs/api/rhi/opengl/swap-chain/get-framebuffer-size.md b/docs/api/rhi/opengl/swap-chain/get-framebuffer-size.md deleted file mode 100644 index 871a7987..00000000 --- a/docs/api/rhi/opengl/swap-chain/get-framebuffer-size.md +++ /dev/null @@ -1,23 +0,0 @@ -# OpenGLSwapChain::SetFramebufferSize - -```cpp -void SetFramebufferSize(int width, int height); -``` - -设置帧缓冲区大小。 - -**参数：** -- `width` - 帧缓冲区宽度 -- `height` - 帧缓冲区高度 - -**线程安全：** ❌ - -**示例：** - -```cpp -swapChain->SetFramebufferSize(1920, 1080); -``` - -## 相关文档 - -- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/swap-chain/get-framebuffer-width.md b/docs/api/rhi/opengl/swap-chain/get-framebuffer-width.md new file mode 100644 index 00000000..010b61e8 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/get-framebuffer-width.md @@ -0,0 +1,26 @@ +# OpenGLSwapChain::GetFramebufferWidth + +```cpp +int GetFramebufferWidth() const; +``` + +获取帧缓冲区宽度。 + +**返回：** 帧缓冲区宽度（像素） + +**线程安全：** ❌ + +**注意：** +- 帧缓冲区大小可能与窗口大小不同（HiDPI 显示） +- 通过 `glfwGetFramebufferSize` 获取 + +**示例：** + +```cpp +int fbWidth = swapChain->GetFramebufferWidth(); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) +- [GetFramebufferHeight](get-framebuffer-height.md) - 获取帧缓冲高度 diff --git a/docs/api/rhi/opengl/swap-chain/get-height.md b/docs/api/rhi/opengl/swap-chain/get-height.md new file mode 100644 index 00000000..48782f46 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/get-height.md @@ -0,0 +1,22 @@ +# OpenGLSwapChain::GetHeight + +```cpp +int GetHeight() const; +``` + +获取交换链的窗口高度。 + +**返回：** 窗口高度（像素） + +**线程安全：** ❌ + +**示例：** + +```cpp +int height = swapChain->GetHeight(); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) +- [GetWidth](get-width.md) - 获取宽度 diff --git a/docs/api/rhi/opengl/swap-chain/get-native-handle.md b/docs/api/rhi/opengl/swap-chain/get-native-handle.md new file mode 100644 index 00000000..c29870e4 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/get-native-handle.md @@ -0,0 +1,26 @@ +# OpenGLSwapChain::GetNativeHandle + +```cpp +void* GetNativeHandle() override; +``` + +获取 OpenGL 交换链的原生句柄。 + +**返回：** `nullptr`（OpenGL 交换链不提供原生句柄） + +**线程安全：** ❌ + +**注意：** +- OpenGL 交换链基于 GLFW，不直接提供 OpenGL 句柄 +- 使用 `GetWindow()` 获取 GLFW 窗口指针 + +**示例：** + +```cpp +void* handle = swapChain->GetNativeHandle(); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [GetWindow](get-window.md) - 获取 GLFW 窗口 diff --git a/docs/api/rhi/opengl/swap-chain/get-size.md b/docs/api/rhi/opengl/swap-chain/get-size.md deleted file mode 100644 index 6671d162..00000000 --- a/docs/api/rhi/opengl/swap-chain/get-size.md +++ /dev/null @@ -1,21 +0,0 @@ -# OpenGLSwapChain::GetWidth / GetHeight - -```cpp -int GetWidth() const; -int GetHeight() const; -``` - -获取交换链的宽度和高度。 - -**返回：** 宽度/高度（像素） - -**示例：** - -```cpp -int width = swapChain->GetWidth(); -int height = swapChain->GetHeight(); -``` - -## 相关文档 - -- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/swap-chain/get-width.md b/docs/api/rhi/opengl/swap-chain/get-width.md new file mode 100644 index 00000000..62fae284 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/get-width.md @@ -0,0 +1,22 @@ +# OpenGLSwapChain::GetWidth + +```cpp +int GetWidth() const; +``` + +获取交换链的窗口宽度。 + +**返回：** 窗口宽度（像素） + +**线程安全：** ❌ + +**示例：** + +```cpp +int width = swapChain->GetWidth(); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) +- [GetHeight](get-height.md) - 获取高度 diff --git a/docs/api/rhi/opengl/swap-chain/is-fullscreen.md b/docs/api/rhi/opengl/swap-chain/is-fullscreen.md index 73b7059a..080055ac 100644 --- a/docs/api/rhi/opengl/swap-chain/is-fullscreen.md +++ b/docs/api/rhi/opengl/swap-chain/is-fullscreen.md @@ -1,7 +1,7 @@ # OpenGLSwapChain::IsFullscreen ```cpp -bool IsFullscreen() const; +bool IsFullscreen() const override; ``` 查询是否处于全屏模式。 diff --git a/docs/api/rhi/opengl/swap-chain/poll-events.md b/docs/api/rhi/opengl/swap-chain/poll-events.md index caa6ba40..5efe4f8b 100644 --- a/docs/api/rhi/opengl/swap-chain/poll-events.md +++ b/docs/api/rhi/opengl/swap-chain/poll-events.md @@ -1,7 +1,7 @@ # OpenGLSwapChain::PollEvents ```cpp -void PollEvents(); +void PollEvents() override; ``` 处理所有待处理的窗口事件。 diff --git a/docs/api/rhi/opengl/swap-chain/present-mode.md b/docs/api/rhi/opengl/swap-chain/present-mode.md new file mode 100644 index 00000000..6a9ffdb7 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/present-mode.md @@ -0,0 +1,21 @@ +# PresentMode + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 指定交换链的呈现模式，控制帧缓冲交换的同步方式。 + +## 枚举值 + +| 值 | 描述 | +|------|------| +| `Immediate` | 立即呈现，不等待垂直同步 | +| `VSync` | 等待垂直同步（默认） | +| `Mailbox` | 邮箱模式，三重缓冲 | +| `Fifo` | 先进先出，标准垂直同步 | + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) +- [SurfaceFormat](surface-format.md) diff --git a/docs/api/rhi/opengl/swap-chain/present.md b/docs/api/rhi/opengl/swap-chain/present.md index 4eb86faf..7b866bab 100644 --- a/docs/api/rhi/opengl/swap-chain/present.md +++ b/docs/api/rhi/opengl/swap-chain/present.md @@ -1,7 +1,7 @@ # OpenGLSwapChain::Present ```cpp -void Present(uint32_t syncInterval = 1, uint32_t flags = 0); +void Present(uint32_t syncInterval = 1, uint32_t flags = 0) override; ``` 呈现渲染结果到屏幕。 diff --git a/docs/api/rhi/opengl/swap-chain/resize.md b/docs/api/rhi/opengl/swap-chain/resize.md new file mode 100644 index 00000000..ebdabfb3 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/resize.md @@ -0,0 +1,28 @@ +# OpenGLSwapChain::Resize + +```cpp +void Resize(uint32_t width, uint32_t height) override; +``` + +调整交换链大小。 + +**参数：** +- `width` - 新的宽度 +- `height` - 新的高度 + +**注意：** +- OpenGL 实现目前不执行实际的调整大小操作 +- 仅更新内部宽度和高度记录 + +**线程安全：** ❌ + +**示例：** + +```cpp +swapChain->Resize(1920, 1080); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [RHISwapChain::Resize](../../swap-chain/resize.md) - 基类 resize 接口 diff --git a/docs/api/rhi/opengl/swap-chain/set-framebuffer-size.md b/docs/api/rhi/opengl/swap-chain/set-framebuffer-size.md new file mode 100644 index 00000000..8f701fdf --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/set-framebuffer-size.md @@ -0,0 +1,29 @@ +# OpenGLSwapChain::SetFramebufferSize + +```cpp +void SetFramebufferSize(int width, int height); +``` + +设置帧缓冲区大小。 + +**参数：** +- `width` - 帧缓冲区宽度 +- `height` - 帧缓冲区高度 + +**线程安全：** ❌ + +**注意：** +- 此方法仅设置内部记录值，不实际调整帧缓冲对象 +- 用于同步 GLFW 报告的帧缓冲区大小 + +**示例：** + +```cpp +swapChain->SetFramebufferSize(1920, 1080); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) +- [GetFramebufferWidth](get-framebuffer-width.md) - 获取帧缓冲宽度 +- [GetFramebufferHeight](get-framebuffer-height.md) - 获取帧缓冲高度 diff --git a/docs/api/rhi/opengl/swap-chain/set-fullscreen.md b/docs/api/rhi/opengl/swap-chain/set-fullscreen.md index 92ef5733..672af78d 100644 --- a/docs/api/rhi/opengl/swap-chain/set-fullscreen.md +++ b/docs/api/rhi/opengl/swap-chain/set-fullscreen.md @@ -1,7 +1,7 @@ # OpenGLSwapChain::SetFullscreen ```cpp -void SetFullscreen(bool fullscreen); +void SetFullscreen(bool fullscreen) override; ``` 设置全屏模式。 diff --git a/docs/api/rhi/opengl/swap-chain/set-should-close.md b/docs/api/rhi/opengl/swap-chain/set-should-close.md index ccfd3316..efb60840 100644 --- a/docs/api/rhi/opengl/swap-chain/set-should-close.md +++ b/docs/api/rhi/opengl/swap-chain/set-should-close.md @@ -1,7 +1,7 @@ # OpenGLSwapChain::SetShouldClose ```cpp -void SetShouldClose(bool shouldClose); +void SetShouldClose(bool shouldClose) override; ``` 设置窗口关闭标志。 diff --git a/docs/api/rhi/opengl/swap-chain/should-close.md b/docs/api/rhi/opengl/swap-chain/should-close.md index 2ba2d565..aa6049b6 100644 --- a/docs/api/rhi/opengl/swap-chain/should-close.md +++ b/docs/api/rhi/opengl/swap-chain/should-close.md @@ -1,7 +1,7 @@ # OpenGLSwapChain::ShouldClose ```cpp -bool ShouldClose() const; +bool ShouldClose() const override; ``` 查询窗口是否应该关闭。 diff --git a/docs/api/rhi/opengl/swap-chain/shutdown.md b/docs/api/rhi/opengl/swap-chain/shutdown.md new file mode 100644 index 00000000..89106272 --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/shutdown.md @@ -0,0 +1,24 @@ +# OpenGLSwapChain::Shutdown + +```cpp +void Shutdown() override; +``` + +关闭交换链并释放资源。 + +**线程安全：** ❌ + +**注意：** +- 此方法由析构函数自动调用 +- 调用后交换链将处于未初始化状态 + +**示例：** + +```cpp +swapChain->Shutdown(); +``` + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) - 返回类总览 +- [构造函数](constructor.md) - 构造函数 diff --git a/docs/api/rhi/opengl/swap-chain/surface-format.md b/docs/api/rhi/opengl/swap-chain/surface-format.md new file mode 100644 index 00000000..4b516ccd --- /dev/null +++ b/docs/api/rhi/opengl/swap-chain/surface-format.md @@ -0,0 +1,21 @@ +# SurfaceFormat + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum class` + +**描述**: 指定交换链的表面格式，控制颜色缓冲的像素格式。 + +## 枚举值 + +| 值 | 描述 | +|------|------| +| `RGBA8` | 8 位 RGBA（每个通道 8 位） | +| `RGBA16F` | 16 位浮点 RGBA | +| `RGBA32F` | 32 位浮点 RGBA | +| `BGRA8` | 8 位 BGRA | + +## 相关文档 + +- [OpenGLSwapChain 总览](swap-chain.md) +- [PresentMode](present-mode.md) diff --git a/docs/api/rhi/opengl/swap-chain/swap-chain.md b/docs/api/rhi/opengl/swap-chain/swap-chain.md index 7ced78ce..b6a3262b 100644 --- a/docs/api/rhi/opengl/swap-chain/swap-chain.md +++ b/docs/api/rhi/opengl/swap-chain/swap-chain.md @@ -2,18 +2,33 @@ **命名空间**: `XCEngine::RHI` -**描述**: OpenGL 交换链实现，继承自 `RHISwapChain`。 +**类型**: `class` + +**描述**: OpenGL 交换链实现，继承自 `RHISwapChain`。基于 GLFW 窗口管理，用于 OpenGL 渲染的帧缓冲交换。 + +## 概述 + +`OpenGLSwapChain` 是 OpenGL 后端的交换链实现，负责管理渲染目标帧缓冲的呈现。它继承自 `RHISwapChain` 抽象接口，通过 GLFW 窗口系统进行帧缓冲交换。 + +### 枚举类型 + +| 枚举 | 描述 | +|------|------| +| [`PresentMode`](present-mode.md) | 呈现模式（Immediate/VSync/Mailbox/Fifo） | +| [`SurfaceFormat`](surface-format.md) | 表面格式（RGBA8/RGBA16F/RGBA32F/BGRA8） | ## 公共方法 | 方法 | 描述 | |------|------| +| [`OpenGLSwapChain`](constructor.md) | 构造函数 | +| [`~OpenGLSwapChain`](destructor.md) | 析构函数 | | [`Initialize`](initialize.md) | 初始化交换链 | -| [`InitializeMode`](initialize-mode.md) | 使用模式初始化 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭交换链 | +| [`Initialize(mode)`](initialize-mode.md) | 使用模式初始化 | +| [`Shutdown`](shutdown.md) | 关闭交换链 | | [`Present`](present.md) | 呈现画面 | | [`SwapBuffers`](swap-buffers.md) | 交换缓冲 | -| [`Resize`](../../swap-chain/resize.md) | 调整交换链大小 | +| [`Resize`](resize.md) | 调整交换链大小 | | [`SetVSync`](set-vsync.md) | 设置垂直同步 | | [`IsVSync`](is-vsync.md) | 检查是否垂直同步 | | [`SetFullscreen`](set-fullscreen.md) | 设置全屏模式 | @@ -21,14 +36,39 @@ | [`ShouldClose`](should-close.md) | 检查是否应关闭 | | [`SetShouldClose`](set-should-close.md) | 设置关闭标志 | | [`PollEvents`](poll-events.md) | 处理窗口事件 | -| [`GetCurrentBackBufferIndex`](../../swap-chain/get-current-back-buffer-index.md) | 获取当前后台缓冲区索引 | -| [`GetCurrentBackBuffer`](../../swap-chain/get-current-back-buffer.md) | 获取当前后台缓冲区 | -| [`GetWidth`](get-size.md) | 获取宽度 | -| [`GetHeight`](get-size.md) | 获取高度 | -| [`GetFramebufferWidth`](get-framebuffer-size.md) | 获取帧缓冲宽度 | -| [`GetFramebufferHeight`](get-framebuffer-size.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`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | + +## 使用示例 + +```cpp +#include + +// 创建并初始化 +XCEngine::RHI::OpenGLSwapChain swapChain; +GLFWwindow* window = /* 获取 GLFW 窗口 */; +swapChain.Initialize(window, true); + +// 游戏循环 +while (!swapChain.ShouldClose()) { + swapChain.PollEvents(); + + // 渲染逻辑 + Render(); + + swapChain.Present(1, 0); +} + +// 关闭 +swapChain.Shutdown(); +``` ## 相关文档 diff --git a/docs/api/rhi/opengl/texture/bind.md b/docs/api/rhi/opengl/texture/bind.md new file mode 100644 index 00000000..a824589b --- /dev/null +++ b/docs/api/rhi/opengl/texture/bind.md @@ -0,0 +1,22 @@ +# OpenGLTexture::Bind + +```cpp +void Bind(int slot = 0) const +``` + +将纹理绑定到纹理单元。 + +**参数：** +- `slot` - 纹理单元槽位（默认为 0） + +**示例：** + +```cpp +texture.Bind(0); // 绑定到纹理单元 0 +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 +- [Unbind](unbind.md) - 解绑纹理 +- [BindImage](bind-image.md) - 绑定图像单元 diff --git a/docs/api/rhi/opengl/texture/constructors.md b/docs/api/rhi/opengl/texture/constructors.md new file mode 100644 index 00000000..6e96811e --- /dev/null +++ b/docs/api/rhi/opengl/texture/constructors.md @@ -0,0 +1,28 @@ +# OpenGLTexture 构造与析构 + +## 构造函数 + +```cpp +OpenGLTexture() +``` + +创建 OpenGLTexture 对象，初始化内部状态。 + +**示例：** + +```cpp +OpenGLTexture texture; +``` + +## 析构函数 + +```cpp +~OpenGLTexture() override +``` + +销毁 OpenGLTexture 对象，自动调用 `Shutdown()` 释放资源。 + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 +- [Shutdown](../../../threading/task-system/shutdown.md) - 关闭纹理 diff --git a/docs/api/rhi/opengl/texture/initialize.md b/docs/api/rhi/opengl/texture/initialize.md new file mode 100644 index 00000000..864643e9 --- /dev/null +++ b/docs/api/rhi/opengl/texture/initialize.md @@ -0,0 +1,31 @@ +# OpenGLTexture::Initialize + +```cpp +bool Initialize(OpenGLTextureType type, int width, int height, int depth, int mipLevels, OpenGLFormat format, const void* data = nullptr) +``` + +初始化通用纹理。 + +**参数：** +- `type` - 纹理类型（`OpenGLTextureType::Texture1D`、`Texture2D`、`Texture3D` 等） +- `width` - 纹理宽度 +- `height` - 纹理高度 +- `depth` - 纹理深度（1D/2D 纹理为 1） +- `mipLevels` - mipmap 级别数量 +- `format` - 纹理格式（`OpenGLFormat` 枚举值） +- `data` - 纹理数据指针（可以为 nullptr 创建空纹理） + +**返回：** `bool` - 成功返回 true，失败返回 false + +**示例：** + +```cpp +OpenGLTexture texture; +texture.Initialize(OpenGLTextureType::Texture2D, 1024, 1024, 1, 1, OpenGLFormat::RGBA8, nullptr); +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 +- [Initialize2D](initialize-2d.md) - 2D 纹理初始化 +- [InitializeCubeMap](initialize-cube-map.md) - 立方体贴图初始化 diff --git a/docs/api/rhi/opengl/texture/set-format.md b/docs/api/rhi/opengl/texture/set-format.md new file mode 100644 index 00000000..226f6a0a --- /dev/null +++ b/docs/api/rhi/opengl/texture/set-format.md @@ -0,0 +1,21 @@ +# OpenGLTexture::SetFormat + +```cpp +void SetFormat(Format format) +``` + +设置纹理格式。 + +**参数：** +- `format` - 纹理格式（`Format` 枚举值） + +**示例：** + +```cpp +texture.SetFormat(Format::R8G8B8A8_UNorm); +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 +- [GetFormat](../../texture/get-format.md) - 获取纹理格式 diff --git a/docs/api/rhi/opengl/texture/texture.md b/docs/api/rhi/opengl/texture/texture.md index 597946b6..f0300c26 100644 --- a/docs/api/rhi/opengl/texture/texture.md +++ b/docs/api/rhi/opengl/texture/texture.md @@ -8,13 +8,15 @@ | 方法 | 描述 | |------|------| -| [`Initialize`](initialize-2d.md) | 初始化 2D 纹理 | +| [`OpenGLTexture`](constructors.md) | 构造函数 | +| [`~OpenGLTexture`](constructors.md#destructor) | 析构函数 | +| [`Initialize`](initialize.md) | 初始化通用纹理 | | [`Initialize2D`](initialize-2d.md) | 初始化 2D 纹理 | | [`InitializeCubeMap`](initialize-cube-map.md) | 初始化立方体贴图 | | [`LoadFromFile`](load-from-file.md) | 从文件加载纹理 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭纹理 | -| [`Bind`](bind-image.md) | 绑定纹理 | -| [`Unbind`](../../shader/unbind.md) | 解绑纹理 | +| [`Shutdown`](../../texture/shutdown.md) | 关闭纹理 | +| [`Bind`](bind.md) | 绑定纹理 | +| [`Unbind`](unbind.md) | 解绑纹理 | | [`BindImage`](bind-image.md) | 绑定图像 | | [`GenerateMipmap`](generate-mipmap.md) | 生成多级渐远纹理 | | [`SetFiltering`](set-filtering.md) | 设置过滤模式 | @@ -26,12 +28,13 @@ | [`GetDepth`](../../texture/get-depth.md) | 获取纹理深度 | | [`GetMipLevels`](../../texture/get-mip-levels.md) | 获取 Mip 级别 | | [`GetTextureType`](../../texture/get-texture-type.md) | 获取纹理类型 | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | -| [`GetState`](../../buffer/get-state.md) | 获取资源状态 | -| [`SetState`](../../buffer/set-state.md) | 设置资源状态 | -| [`GetName`](../../buffer/get-name.md) | 获取资源名称 | -| [`SetName`](../../buffer/set-name.md) | 设置资源名称 | +| [`GetNativeHandle`](../../texture/get-native-handle.md) | 获取原生句柄 | +| [`GetState`](../../texture/get-state.md) | 获取资源状态 | +| [`SetState`](../../texture/set-state.md) | 设置资源状态 | +| [`GetName`](../../texture/get-name.md) | 获取资源名称 | +| [`SetName`](../../texture/set-name.md) | 设置资源名称 | | [`GetFormat`](../../texture/get-format.md) | 获取纹理格式 | +| [`SetFormat`](set-format.md) | 设置纹理格式 | ## 相关文档 diff --git a/docs/api/rhi/opengl/texture/unbind.md b/docs/api/rhi/opengl/texture/unbind.md new file mode 100644 index 00000000..8e7b1212 --- /dev/null +++ b/docs/api/rhi/opengl/texture/unbind.md @@ -0,0 +1,18 @@ +# OpenGLTexture::Unbind + +```cpp +void Unbind() const +``` + +解绑纹理，将其从当前纹理单元分离。 + +**示例：** + +```cpp +texture.Unbind(); +``` + +## 相关文档 + +- [OpenGLTexture](texture.md) - 返回类总览 +- [Bind](bind.md) - 绑定纹理 diff --git a/docs/api/rhi/opengl/vertex-array/add-vertex-buffer.md b/docs/api/rhi/opengl/vertex-array/add-vertex-buffer.md index 5af59a05..0e6bdd3c 100644 --- a/docs/api/rhi/opengl/vertex-array/add-vertex-buffer.md +++ b/docs/api/rhi/opengl/vertex-array/add-vertex-buffer.md @@ -4,25 +4,45 @@ void AddVertexBuffer(unsigned int buffer, const VertexAttribute& attribute) ``` -添加顶点缓冲区并指定顶点属性。 +添加顶点缓冲区并配置顶点属性。 + +**详细描述：** +将顶点缓冲区绑定到 VAO，并配置顶点属性的读取方式。调用时： +1. 绑定 VAO +2. 绑定顶点缓冲区 +3. 启用顶点属性数组 +4. 使用 `glVertexAttribPointer` 配置属性格式 +5. 解绑缓冲区和 VAO **参数：** -- `buffer` - OpenGL 缓冲区对象 ID -- `attribute` - 顶点属性描述结构体 +- `buffer` - OpenGL 缓冲区对象 ID（GL_ARRAY_BUFFER 类型） +- `attribute` - 顶点属性描述结构体 [`VertexAttribute`](vertex-attribute.md) **示例：** ```cpp +// 位置属性 (对应着色器 layout(location = 0)) VertexAttribute attr; attr.index = 0; -attr.count = 3; -attr.type = GL_FLOAT; -attr.normalized = GL_FALSE; -attr.stride = sizeof(Vertex); -attr.offset = 0; -vao.AddVertexBuffer(vbo, attr); +attr.count = 3; // xyz 三个分量 +attr.type = GL_FLOAT; // float 类型 +attr.normalized = GL_FALSE; // 不归一化 +attr.stride = sizeof(Vertex); // 顶点结构体大小 +attr.offset = 0; // 位置在结构体起始处 +vao.AddVertexBuffer(positionVBO, attr); + +// 纹理坐标属性 (对应着色器 layout(location = 1)) +VertexAttribute texAttr; +texAttr.index = 1; +texAttr.count = 2; // uv 两个分量 +texAttr.type = GL_FLOAT; +texAttr.normalized = GL_FALSE; +texAttr.stride = sizeof(Vertex); +texAttr.offset = offsetof(Vertex, texCoord); // 纹理坐标偏移 +vao.AddVertexBuffer(texCoordVBO, texAttr); ``` ## 相关文档 - [OpenGLVertexArray](vertex-array.md) - 返回类总览 +- [VertexAttribute](vertex-attribute.md) - 属性结构体详细说明 diff --git a/docs/api/rhi/opengl/vertex-array/bind.md b/docs/api/rhi/opengl/vertex-array/bind.md new file mode 100644 index 00000000..01d8847b --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/bind.md @@ -0,0 +1,18 @@ +# OpenGLVertexArray::Bind + +```cpp +void Bind() const +``` + +绑定顶点数组对象到当前 OpenGL 上下文。 + +**示例：** + +```cpp +vao.Bind(); +glDrawElements(GL_TRIANGLES, indexCount, GL_UNSIGNED_INT, 0); +``` + +## 相关文档 + +- [OpenGLVertexArray](vertex-array.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/vertex-array/constructor.md b/docs/api/rhi/opengl/vertex-array/constructor.md new file mode 100644 index 00000000..9696f7ef --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/constructor.md @@ -0,0 +1,31 @@ +# OpenGLVertexArray::OpenGLVertexArray + +```cpp +OpenGLVertexArray() +``` + +默认构造函数。初始化所有成员变量为默认值。 + +**详细描述：** +- `m_vao` = 0 +- `m_indexBuffer` = 0 +- `m_indexCount` = 0 +- `m_vertexBufferCount` = 0 + +不创建任何 OpenGL 资源，需调用 `Initialize()` 后才能使用。 + +**示例：** + +```cpp +OpenGLVertexArray vao; +// 此时 vao 未初始化，不能使用 Bind 等方法 +if (vao.Initialize()) { + vao.Bind(); // 现在可以使用了 +} +``` + +## 相关文档 + +- [OpenGLVertexArray](vertex-array.md) - 返回类总览 +- [Initialize](initialize.md) - 初始化方法 +- [Shutdown](shutdown.md) - 关闭方法 \ No newline at end of file diff --git a/docs/api/rhi/opengl/vertex-array/destructor.md b/docs/api/rhi/opengl/vertex-array/destructor.md new file mode 100644 index 00000000..7b1d2cb7 --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/destructor.md @@ -0,0 +1,29 @@ +# OpenGLVertexArray::~OpenGLVertexArray + +```cpp +~OpenGLVertexArray() +``` + +析构函数。在对象销毁时自动调用 `Shutdown()` 释放 OpenGL 资源。 + +**详细描述：** +确保 VAO 资源被正确释放。如果 `Shutdown()` 尚未调用，会自动调用以释放 `glGenVertexArrays` 创建的资源。 + +**注意：** +- 不会释放关联的顶点缓冲区和索引缓冲区（它们通常由独立的缓冲区管理对象管理） +- 仅释放 `glGenVertexArrays` 生成的 VAO + +**示例：** + +```cpp +{ + OpenGLVertexArray vao; + vao.Initialize(); + // 使用 vao... +} // vao 超出作用域时自动调用析构函数，释放资源 +``` + +## 相关文档 + +- [OpenGLVertexArray](vertex-array.md) - 返回类总览 +- [Shutdown](shutdown.md) - 关闭方法 \ No newline at end of file diff --git a/docs/api/rhi/opengl/vertex-array/get-index-count.md b/docs/api/rhi/opengl/vertex-array/get-index-count.md index 14b5ec7f..bf6867bc 100644 --- a/docs/api/rhi/opengl/vertex-array/get-index-count.md +++ b/docs/api/rhi/opengl/vertex-array/get-index-count.md @@ -6,15 +6,24 @@ unsigned int GetIndexCount() const 获取索引数量。 -**返回：** `unsigned int` - 索引数量 +**详细描述：** +返回 `m_indexCount` 成员的值。**注意**：当前实现中 `m_indexCount` 仅在构造函数中初始化为 0， +`SetIndexBuffer` 不会更新此值。如需获取索引数量，需在调用 `SetIndexBuffer` 后手动维护或通过其他方式获取。 + +**返回：** `unsigned int` - 索引数量（当前实现中始终为 0，需手动维护） **示例：** ```cpp -unsigned int count = vao.GetIndexCount(); -glDrawElements(GL_TRIANGLES, count, GL_UNSIGNED_INT, 0); +// 注意：GetIndexCount() 总是返回 0 +// 建议自行维护索引数量 +unsigned int indexCount = /* 从外部获取或手动设置 */; +glDrawElements(GL_TRIANGLES, indexCount, GL_UNSIGNED_INT, 0); ``` +**另见：** +- [SetIndexBuffer](set-index-buffer.md) - 设置索引缓冲（不更新 m_indexCount） + ## 相关文档 - [OpenGLVertexArray](vertex-array.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/vertex-array/initialize.md b/docs/api/rhi/opengl/vertex-array/initialize.md new file mode 100644 index 00000000..fdd9344c --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/initialize.md @@ -0,0 +1,33 @@ +# OpenGLVertexArray::Initialize + +```cpp +bool Initialize() +``` + +初始化 OpenGL 顶点数组对象。 + +**详细描述：** +调用 `glGenVertexArrays(1, &m_vao)` 生成一个新的顶点数组对象并存储其 ID。 +必须在使用 VAO 之前调用。 + +**返回：** `bool` - 始终返回 `true`（当前实现不进行错误检查） + +**注意：** +- 如果初始化失败，`m_vao` 将保持为 0 +- 当前实现不检查 OpenGL 错误，建议在调用前确保 OpenGL 上下文已创建 + +**示例：** + +```cpp +OpenGLVertexArray vao; +if (vao.Initialize()) { + // VAO 初始化成功，可以添加缓冲和绑定 + vao.AddVertexBuffer(vbo, positionAttr); + vao.Bind(); +} +``` + +## 相关文档 + +- [OpenGLVertexArray](vertex-array.md) - 返回类总览 +- [Shutdown](shutdown.md) - 关闭方法 diff --git a/docs/api/rhi/opengl/vertex-array/set-index-buffer.md b/docs/api/rhi/opengl/vertex-array/set-index-buffer.md index 866316b3..4de6fe61 100644 --- a/docs/api/rhi/opengl/vertex-array/set-index-buffer.md +++ b/docs/api/rhi/opengl/vertex-array/set-index-buffer.md @@ -6,9 +6,14 @@ void SetIndexBuffer(unsigned int buffer, unsigned int type) 设置索引缓冲区。 +**详细描述：** +将索引缓冲区绑定到此 VAO。绑定后，绘制调用 `glDrawElements` 将使用此索引缓冲。 +注意：当前实现中 `type` 参数仅存储，不影响实际 OpenGL 调用；`m_indexCount` 也不会被更新， +需通过其他方式跟踪索引数量。 + **参数：** -- `buffer` - OpenGL 缓冲区对象 ID -- `type` - 索引数据类型（GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT, GL_UNSIGNED_INT） +- `buffer` - OpenGL 缓冲区对象 ID（ELEMENT_ARRAY_BUFFER） +- `type` - 索引数据类型（`GL_UNSIGNED_BYTE`、`GL_UNSIGNED_SHORT`、`GL_UNSIGNED_INT`），当前未使用 **示例：** @@ -16,6 +21,10 @@ void SetIndexBuffer(unsigned int buffer, unsigned int type) vao.SetIndexBuffer(ibo, GL_UNSIGNED_INT); ``` +**注意：** +- `m_indexCount` 在调用此方法后不会自动更新，需手动维护索引数量 +- 索引缓冲区的实际类型信息由 OpenGL 绑定时确定 + ## 相关文档 - [OpenGLVertexArray](vertex-array.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/vertex-array/shutdown.md b/docs/api/rhi/opengl/vertex-array/shutdown.md new file mode 100644 index 00000000..9181bb98 --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/shutdown.md @@ -0,0 +1,32 @@ +# OpenGLVertexArray::Shutdown + +```cpp +void Shutdown() +``` + +关闭顶点数组对象，释放 OpenGL 资源。 + +**详细描述：** +调用 `glDeleteVertexArrays(1, &m_vao)` 释放 VAO 资源，并将 `m_vao` 重置为 0。 + +**释放的资源：** +- `m_vao` - 顶点数组对象 + +**不释放的资源：** +- 顶点缓冲区（由独立的缓冲区管理对象管理） +- 索引缓冲区（由独立的缓冲区管理对象管理） + +**幂等性：** +可安全多次调用。如果 `m_vao` 为 0，则不执行任何操作。 + +**示例：** + +```cpp +vao.Shutdown(); // 释放 VAO +// 此后不能再调用 Bind() +``` + +## 相关文档 + +- [OpenGLVertexArray](vertex-array.md) - 返回类总览 +- [Initialize](initialize.md) - 初始化方法 diff --git a/docs/api/rhi/opengl/vertex-array/unbind.md b/docs/api/rhi/opengl/vertex-array/unbind.md new file mode 100644 index 00000000..23f9e399 --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/unbind.md @@ -0,0 +1,17 @@ +# OpenGLVertexArray::Unbind + +```cpp +void Unbind() const +``` + +解除当前绑定的顶点数组对象。 + +**示例：** + +```cpp +vao.Unbind(); +``` + +## 相关文档 + +- [OpenGLVertexArray](vertex-array.md) - 返回类总览 diff --git a/docs/api/rhi/opengl/vertex-array/vertex-array.md b/docs/api/rhi/opengl/vertex-array/vertex-array.md index ecbcbce6..5200da88 100644 --- a/docs/api/rhi/opengl/vertex-array/vertex-array.md +++ b/docs/api/rhi/opengl/vertex-array/vertex-array.md @@ -2,22 +2,67 @@ **命名空间**: `XCEngine::RHI` -**描述**: OpenGL 顶点数组对象 (VAO) 封装。 +**描述**: OpenGL 顶点数组对象 (VAO) 封装。管理顶点属性配置和索引缓冲绑定。 + +## 概述 + +`OpenGLVertexArray` 封装了 OpenGL 顶点数组对象 (Vertex Array Object, VAO)，用于： +- 存储顶点属性配置 +- 绑定顶点缓冲区和索引缓冲区 +- 提供便捷的绑定/解绑接口 + +## 类型 + +| 类型 | 描述 | +|------|------| +| [`VertexAttribute`](vertex-attribute.md) | 顶点属性描述结构体 | + +## 构造函数/析构函数 + +| 方法 | 描述 | +|------|------| +| [`OpenGLVertexArray()`](constructor.md) | 默认构造函数 | +| [`~OpenGLVertexArray()`](destructor.md) | 析构函数，调用 `Shutdown()` 释放资源 | ## 公共方法 | 方法 | 描述 | |------|------| -| [`Initialize`](../../../threading/task-system/initialize.md) | 初始化顶点数组 | -| [`AddVertexBuffer`](add-vertex-buffer.md) | 添加顶点缓冲 | +| [`Initialize`](initialize.md) | 初始化顶点数组，生成 VAO | +| [`AddVertexBuffer`](add-vertex-buffer.md) | 添加顶点缓冲并配置属性 | | [`SetIndexBuffer`](set-index-buffer.md) | 设置索引缓冲 | -| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭顶点数组 | -| [`Bind`](../../shader/bind.md) | 绑定顶点数组 | -| [`Unbind`](../../shader/unbind.md) | 解绑顶点数组 | +| [`Shutdown`](shutdown.md) | 关闭顶点数组，释放 VAO 资源 | +| [`Bind`](bind.md) | 绑定顶点数组到当前 OpenGL 上下文 | +| [`Unbind`](unbind.md) | 解绑顶点数组 | | [`GetID`](get-id.md) | 获取 OpenGL VAO ID | -| [`GetIndexBuffer`](get-index-buffer.md) | 获取索引缓冲 | -| [`GetIndexCount`](get-index-count.md) | 获取索引数量 | +| [`GetIndexBuffer`](get-index-buffer.md) | 获取索引缓冲区 ID | +| [`GetIndexCount`](get-index-count.md) | 获取索引数量（需手动维护） | + +## 使用示例 + +```cpp +// 创建 VAO +OpenGLVertexArray vao; +vao.Initialize(); + +// 添加顶点缓冲和属性 +vao.AddVertexBuffer(vbo, positionAttr); +vao.AddVertexBuffer(vbo, normalAttr); +vao.AddVertexBuffer(vbo, texCoordAttr); + +// 设置索引缓冲 +vao.SetIndexBuffer(ibo, GL_UNSIGNED_INT); + +// 绑定并绘制 +vao.Bind(); +glDrawElements(GL_TRIANGLES, indexCount, GL_UNSIGNED_INT, 0); +vao.Unbind(); + +// 销毁 +vao.Shutdown(); +``` ## 相关文档 - [OpenGL 后端总览](../overview.md) +- [VertexAttribute 结构体](vertex-attribute.md) diff --git a/docs/api/rhi/opengl/vertex-array/vertex-attribute.md b/docs/api/rhi/opengl/vertex-array/vertex-attribute.md new file mode 100644 index 00000000..bb5a0dd4 --- /dev/null +++ b/docs/api/rhi/opengl/vertex-array/vertex-attribute.md @@ -0,0 +1,72 @@ +# VertexAttribute + +**命名空间**: `XCEngine::RHI` + +**描述**: 顶点属性描述结构体，用于定义顶点缓冲区中单个属性的布局。 + +## 成员 + +| 成员 | 类型 | 描述 | +|------|------|------| +| `index` | `unsigned int` | 属性索引，对应着色器中 `layout(location = n)` | +| `count` | `int` | 分量数量（1-4），如位置用 3，纹理坐标用 2 | +| `type` | `unsigned int` | OpenGL 数据类型，如 `GL_FLOAT`、`GL_INT` | +| `normalized` | `bool` | 是否归一化Fixed-point类型 | +| `stride` | `size_t` | 连续顶点属性之间的字节偏移 | +| `offset` | `size_t` | 此属性在顶点结构体中的字节偏移 | + +## 类型取值参考 + +| 类型常量 | 描述 | +|----------|------| +| `GL_BYTE` | 有符号字节 | +| `GL_UNSIGNED_BYTE` | 无符号字节 | +| `GL_SHORT` | 有符号短整型 | +| `GL_UNSIGNED_SHORT` | 无符号短整型 | +| `GL_INT` | 有符号整型 | +| `GL_UNSIGNED_INT` | 无符号整型 | +| `GL_FLOAT` | 单精度浮点 | +| `GL_DOUBLE` | 双精度浮点 | + +## 使用示例 + +```cpp +// 定义顶点结构体 +struct Vertex { + float position[3]; + float normal[3]; + float texCoord[2]; +}; + +// 位置属性 (index=0) +VertexAttribute posAttr; +posAttr.index = 0; +posAttr.count = 3; +posAttr.type = GL_FLOAT; +posAttr.normalized = GL_FALSE; +posAttr.stride = sizeof(Vertex); +posAttr.offset = 0; + +// 法线属性 (index=1) +VertexAttribute normalAttr; +normalAttr.index = 1; +normalAttr.count = 3; +normalAttr.type = GL_FLOAT; +normalAttr.normalized = GL_FALSE; +normalAttr.stride = sizeof(Vertex); +normalAttr.offset = offsetof(Vertex, normal); + +// 纹理坐标属性 (index=2) +VertexAttribute texAttr; +texAttr.index = 2; +texAttr.count = 2; +texAttr.type = GL_FLOAT; +texAttr.normalized = GL_FALSE; +texAttr.stride = sizeof(Vertex); +texAttr.offset = offsetof(Vertex, texCoord); +``` + +## 相关文档 + +- [OpenGLVertexArray](vertex-array.md) - 返回类总览 +- [AddVertexBuffer](add-vertex-buffer.md) - 添加顶点缓冲方法 \ No newline at end of file diff --git a/docs/api/rhi/pipeline-layout/get-native-handle.md b/docs/api/rhi/pipeline-layout/get-native-handle.md index 954d6557..d7f40dcf 100644 --- a/docs/api/rhi/pipeline-layout/get-native-handle.md +++ b/docs/api/rhi/pipeline-layout/get-native-handle.md @@ -6,10 +6,20 @@ virtual void* GetNativeHandle() = 0; 获取原生 API 句柄。 -**返回：** 原生管线布局句柄 +**参数：** 无 + +**返回：** 原生管线布局句柄（类型为 `void*`，需要根据实际图形API进行类型转换） **复杂度：** O(1) +## 示例代码 + +```cpp +// 获取 D3D12 管线布局句柄 +void* nativeHandle = pipelineLayout->GetNativeHandle(); +// D3D12PipelineLayout* d3d12Layout = static_cast(nativeHandle); +``` + ## 相关文档 - [RHIPipelineLayout 总览](pipeline-layout.md) - 返回类总览 diff --git a/docs/api/rhi/pipeline-layout/initialize.md b/docs/api/rhi/pipeline-layout/initialize.md index 85ee66b0..3a55823a 100644 --- a/docs/api/rhi/pipeline-layout/initialize.md +++ b/docs/api/rhi/pipeline-layout/initialize.md @@ -7,12 +7,32 @@ virtual bool Initialize(const RHIPipelineLayoutDesc& desc) = 0; 初始化管线布局。 **参数：** -- `desc` - 管线布局描述符 +- `desc` - 管线布局描述符，包含以下成员： + - `constantBufferCount` - 常量缓冲区数量 + - `textureCount` - 纹理数量 + - `samplerCount` - 采样器数量 + - `uavCount` - 无序访问视图数量 **返回：** 成功返回 `true`，失败返回 `false` **复杂度：** O(1) +## 示例代码 + +```cpp +RHIPipelineLayoutDesc desc; +desc.constantBufferCount = 2; +desc.textureCount = 4; +desc.samplerCount = 2; +desc.uavCount = 1; + +if (pipelineLayout->Initialize(desc)) { + // 初始化成功，可以继续使用 +} else { + // 初始化失败，处理错误 +} +``` + ## 相关文档 - [RHIPipelineLayout 总览](pipeline-layout.md) - 返回类总览 diff --git a/docs/api/rhi/pipeline-layout/methods.md b/docs/api/rhi/pipeline-layout/methods.md deleted file mode 100644 index b0372042..00000000 --- a/docs/api/rhi/pipeline-layout/methods.md +++ /dev/null @@ -1,25 +0,0 @@ -# RHIPipelineLayout 方法 - -## Initialize - -```cpp -virtual bool Initialize(const RHIPipelineLayoutDesc& desc) = 0; -``` - -初始化管线布局。 - -## Shutdown - -```cpp -virtual void Shutdown() = 0; -``` - -释放管线布局资源。 - -## GetNativeHandle - -```cpp -virtual void* GetNativeHandle() = 0; -``` - -获取原生 API 句柄。 diff --git a/docs/api/rhi/pipeline-layout/pipeline-layout.md b/docs/api/rhi/pipeline-layout/pipeline-layout.md index 44195303..ca6c98c9 100644 --- a/docs/api/rhi/pipeline-layout/pipeline-layout.md +++ b/docs/api/rhi/pipeline-layout/pipeline-layout.md @@ -4,8 +4,14 @@ **类型**: `class` (abstract) +**头文件**: `XCEngine/RHI/RHIPipelineLayout.h` + **描述**: GPU 渲染管线布局抽象接口，用于定义着色器资源的绑定布局。 +## 概述 + +`RHIPipelineLayout` 是 RHI（Rendering Hardware Interface）模块的核心类之一，负责描述GPU渲染管线中着色器资源的绑定布局。它定义了管线中使用的常量缓冲区、纹理采样器和无序访问视图的数量和配置。作为抽象基类，`RHIPipelineLayout` 需要由具体的图形API实现（如 D3D12、OpenGL）提供具体实现。 + ## 公共方法 | 方法 | 描述 | @@ -14,7 +20,32 @@ | [`Shutdown`](shutdown.md) | 关闭并释放资源 | | [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | +## 使用示例 + +```cpp +#include "RHI/RHIPipelineLayout.h" +#include "RHI/RHIDevice.h" + +// 创建设备后创建管线布局 +RHIPipelineLayoutDesc layoutDesc; +layoutDesc.constantBufferCount = 2; +layoutDesc.textureCount = 4; +layoutDesc.samplerCount = 2; +layoutDesc.uavCount = 1; + +RHIPipelineLayout* pipelineLayout = device->CreatePipelineLayout(layoutDesc); +if (pipelineLayout->Initialize(layoutDesc)) { + // 管线布局初始化成功 + void* nativeHandle = pipelineLayout->GetNativeHandle(); + + // 使用原生句柄进行绑定... + + pipelineLayout->Shutdown(); +} +delete pipelineLayout; +``` + ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [../rhi.md](../rhi.md) - RHI 模块总览 - [RHIDevice](../device/device.md) - 创建设备 diff --git a/docs/api/rhi/pipeline-layout/shutdown.md b/docs/api/rhi/pipeline-layout/shutdown.md index c4b2a22f..f334a45c 100644 --- a/docs/api/rhi/pipeline-layout/shutdown.md +++ b/docs/api/rhi/pipeline-layout/shutdown.md @@ -6,8 +6,19 @@ virtual void Shutdown() = 0; 释放管线布局资源。 +**参数：** 无 + +**返回：** 无 + **复杂度：** O(1) +## 示例代码 + +```cpp +// 使用完毕后释放资源 +pipelineLayout->Shutdown(); +``` + ## 相关文档 - [RHIPipelineLayout 总览](pipeline-layout.md) - 返回类总览 diff --git a/docs/api/rhi/pipeline-state/bind.md b/docs/api/rhi/pipeline-state/bind.md new file mode 100644 index 00000000..794dfcda --- /dev/null +++ b/docs/api/rhi/pipeline-state/bind.md @@ -0,0 +1,37 @@ +# RHIPipelineState::Bind + +```cpp +virtual void Bind() = 0; +``` + +将管线状态绑定到渲染上下文。调用此方法后，该管线状态将成为当前活跃的渲染管线。 + +**参数：** 无 + +**返回：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/RHI/RHIPipelineState.h" + +class MyRenderer { + void DrawWithPipeline(RHIPipelineState* pipeline) { + pipeline->Bind(); + + // 执行绘制操作 + // Draw calls... + + pipeline->Unbind(); + } +}; +``` + +## 相关文档 + +- [RHIPipelineState](pipeline-state.md) - 返回类总览 +- [RHIPipelineState::Unbind](unbind.md) - 解绑管线状态 diff --git a/docs/api/rhi/pipeline-state/get-native-handle.md b/docs/api/rhi/pipeline-state/get-native-handle.md index 0b543fcc..fbd38665 100644 --- a/docs/api/rhi/pipeline-state/get-native-handle.md +++ b/docs/api/rhi/pipeline-state/get-native-handle.md @@ -4,12 +4,40 @@ virtual void* GetNativeHandle() = 0; ``` -获取原生 API 句柄。 +获取底层图形 API 的原生句柄。此方法返回的句柄类型取决于具体实现： -**返回：** 原生管线状态句柄 +- **D3D12**: `ID3D12PipelineState*` +- **OpenGL**: `GLuint`（管线对象 ID） +- **Vulkan**: `VkPipeline` +- **Metal**: `id` + +**参数：** 无 + +**返回：** `void*` - 指向底层图形 API 管线状态对象的指针 + +**线程安全：** ❌ **复杂度：** O(1) +**示例：** + +```cpp +#include "XCEngine/RHI/RHIPipelineState.h" +#include "XCEngine/RHI/RHIEnums.h" + +void InspectNativeHandle(RHIPipelineState* pipeline) { + void* handle = pipeline->GetNativeHandle(); + + PipelineType type = pipeline->GetType(); + + if (type == PipelineType::Graphics && handle) { + // D3D12: ID3D12PipelineState* d3d12Pipeline = static_cast(handle); + // OpenGL: GLuint glPipeline = static_cast(reinterpret_cast(handle)); + } +} +``` + ## 相关文档 -- [RHIPipelineState 总览](pipeline-state.md) - 返回类总览 +- [RHIPipelineState](pipeline-state.md) - 返回类总览 +- [RHIPipelineState::GetType](get-type.md) - 获取管线类型 diff --git a/docs/api/rhi/pipeline-state/get-type.md b/docs/api/rhi/pipeline-state/get-type.md index a63b47ea..e360c8fd 100644 --- a/docs/api/rhi/pipeline-state/get-type.md +++ b/docs/api/rhi/pipeline-state/get-type.md @@ -4,12 +4,46 @@ virtual PipelineType GetType() const = 0; ``` -获取管线类型。 +获取管线类型。返回的管线类型用于区分不同的渲染管线类别。 -**返回：** 管线类型枚举值 +**参数：** 无 + +**返回：** `PipelineType` - 管线类型枚举值 + +| 枚举值 | 描述 | +|--------|------| +| `PipelineType::Graphics` | 图形管线，用于常规渲染（顶点着色器、片段着色器） | +| `PipelineType::Compute` | 计算管线，用于通用 GPU 计算 | +| `PipelineType::Raytracing` | 光线追踪管线，用于光线追踪渲染 | + +**线程安全：** ✅（const 方法） **复杂度：** O(1) +**示例：** + +```cpp +#include "XCEngine/RHI/RHIPipelineState.h" +#include "XCEngine/RHI/RHIEnums.h" + +void ProcessPipeline(RHIPipelineState* pipeline) { + PipelineType type = pipeline->GetType(); + + switch (type) { + case PipelineType::Graphics: + pipeline->Bind(); + break; + case PipelineType::Compute: + // 分发计算任务 + break; + case PipelineType::Raytracing: + // 执行光线追踪 + break; + } +} +``` + ## 相关文档 -- [RHIPipelineState 总览](pipeline-state.md) - 返回类总览 +- [RHIPipelineState](pipeline-state.md) - 返回类总览 +- [RHIPipelineState::GetNativeHandle](get-native-handle.md) - 获取原生句柄 diff --git a/docs/api/rhi/pipeline-state/methods.md b/docs/api/rhi/pipeline-state/methods.md deleted file mode 100644 index c5618d64..00000000 --- a/docs/api/rhi/pipeline-state/methods.md +++ /dev/null @@ -1,41 +0,0 @@ -# RHIPipelineState 方法 - -## Shutdown - -```cpp -virtual void Shutdown() = 0; -``` - -释放管线状态对象。 - -## Bind - -```cpp -virtual void Bind() = 0; -``` - -绑定管线状态到管线。 - -## Unbind - -```cpp -virtual void Unbind() = 0; -``` - -解绑管线状态。 - -## GetNativeHandle - -```cpp -virtual void* GetNativeHandle() = 0; -``` - -获取原生 API 句柄。 - -## GetType - -```cpp -virtual PipelineType GetType() const = 0; -``` - -获取管线类型。 diff --git a/docs/api/rhi/pipeline-state/pipeline-state.md b/docs/api/rhi/pipeline-state/pipeline-state.md index 4abd8da0..8bdb693c 100644 --- a/docs/api/rhi/pipeline-state/pipeline-state.md +++ b/docs/api/rhi/pipeline-state/pipeline-state.md @@ -4,27 +4,55 @@ **类型**: `class` (abstract) -**描述**: GPU 渲染管线状态抽象接口，封装了渲染管线的各种固定功能配置。 +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +**描述**: 管线状态接口，管理渲染管线状态 + +## 概述 + +`RHIPipelineState` 是 XCEngine RHI 模块中的抽象基类，定义了渲染管线状态的统一接口。它提供了绑定、解绑定、获取原生句柄以及查询管线类型等基本操作。作为抽象基类，具体实现由各图形 API（D3D12、OpenGL、Vulkan、Metal）自行实现。 + +此接口的主要作用是： +- 提供统一的管线状态管理抽象 +- 屏蔽不同图形 API 的底层差异 +- 支持图形管线、计算管线和光线追踪管线的管理 ## 公共方法 | 方法 | 描述 | |------|------| -| [`Shutdown`](shutdown.md) | 关闭并释放资源 | -| [`Bind`](../shader/bind.md) | 绑定管线状态 | -| [`Unbind`](../shader/unbind.md) | 解绑管线状态 | -| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | -| [`GetType`](get-type.md) | 获取管线类型 | +| [`Shutdown`](shutdown.md) | 关闭并释放管线状态资源 | +| [`Bind`](bind.md) | 将管线状态绑定到渲染上下文 | +| [`Unbind`](unbind.md) | 将管线状态从渲染上下文解绑 | +| [`GetNativeHandle`](get-native-handle.md) | 获取底层图形 API 的原生句柄 | +| [`GetType`](get-type.md) | 获取管线类型（图形/计算/光线追踪） | -## 管线类型 (PipelineType) +## 使用示例 -| 枚举值 | 描述 | -|--------|------| -| `Graphics` | 图形渲染管线 | -| `Compute` | 计算管线 | -| `Raytracing` | 光线追踪管线 | +```cpp +#include "XCEngine/RHI/RHIPipelineState.h" +#include "XCEngine/RHI/RHIEnums.h" + +void ExampleUsage(RHIPipelineState* pipelineState) { + if (!pipelineState) { + return; + } + + PipelineType type = pipelineState->GetType(); + + if (type == PipelineType::Graphics) { + pipelineState->Bind(); + } + + void* nativeHandle = pipelineState->GetNativeHandle(); + + pipelineState->Unbind(); + pipelineState->Shutdown(); +} +``` ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 -- [RHIDevice](../device/device.md) - 创建设备 +- [RHIDevice](../device/device.md) - 设备接口，创建管线状态 +- [RHIPipelineLayout](../pipeline-layout/pipeline-layout.md) - 管线布局 +- [RHICommandList](../command-list/command-list.md) - 命令列表，执行绘制命令 diff --git a/docs/api/rhi/pipeline-state/shutdown.md b/docs/api/rhi/pipeline-state/shutdown.md index 551b01a2..e8658bf8 100644 --- a/docs/api/rhi/pipeline-state/shutdown.md +++ b/docs/api/rhi/pipeline-state/shutdown.md @@ -4,10 +4,30 @@ virtual void Shutdown() = 0; ``` -释放管线状态对象资源。 +关闭并释放管线状态资源。此方法用于在管线状态不再需要时进行清理工作，释放底层图形 API 分配的资源。 + +**参数：** 无 + +**返回：** 无 + +**线程安全：** ❌ **复杂度：** O(1) +**示例：** + +```cpp +#include "XCEngine/RHI/RHIPipelineState.h" + +class MyRenderer { + void ReleasePipeline(RHIPipelineState* pipeline) { + if (pipeline) { + pipeline->Shutdown(); + } + } +}; +``` + ## 相关文档 -- [RHIPipelineState 总览](pipeline-state.md) - 返回类总览 +- [RHIPipelineState](pipeline-state.md) - 返回类总览 diff --git a/docs/api/rhi/pipeline-state/unbind.md b/docs/api/rhi/pipeline-state/unbind.md new file mode 100644 index 00000000..9baabbe5 --- /dev/null +++ b/docs/api/rhi/pipeline-state/unbind.md @@ -0,0 +1,32 @@ +# RHIPipelineState::Unbind + +```cpp +virtual void Unbind() = 0; +``` + +将管线状态从渲染上下文解绑。此方法用于结束当前管线状态的使用，使其不再是当前活跃的渲染管线。 + +**参数：** 无 + +**返回：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/RHI/RHIPipelineState.h" + +class MyRenderer { + void EndRendering(RHIPipelineState* pipeline) { + pipeline->Unbind(); + } +}; +``` + +## 相关文档 + +- [RHIPipelineState](pipeline-state.md) - 返回类总览 +- [RHIPipelineState::Bind](bind.md) - 绑定管线状态 diff --git a/docs/api/rhi/rhi.md b/docs/api/rhi/rhi.md index b667787f..ed5a3b02 100644 --- a/docs/api/rhi/rhi.md +++ b/docs/api/rhi/rhi.md @@ -4,6 +4,8 @@ **描述**: RHI (Rendering Hardware Interface) 是 XCEngine 的硬件抽象层，提供统一的图形 API 接口，支持多个后端实现。 +**头文件**: `XCEngine/RHI/RHI.h` + ## 概述 RHI 模块将上层渲染逻辑与底层图形 API 解耦，通过抽象接口层提供对 DirectX 12、OpenGL 等图形 API 的统一访问。这种设计使得渲染代码可以在不同的图形 API 之间无缝切换，无需修改上层业务逻辑。 @@ -38,7 +40,7 @@ RHI 模块将上层渲染逻辑与底层图形 API 解耦，通过抽象接口 | 类 | 文档 | 描述 | |----|------|------| | [RHIDevice](device/device.md) | `RHIDevice.h` | 渲染设备抽象，代表图形适配器实例 | -| [RHIFactory](factory/factory.md) | `RHIFactory.h` | 设备工厂，用于创建不同后端的设备实例 | +| [RHIFactory](rhifactory/rhifactory.md) | `RHIFactory.h` | 设备工厂，用于创建不同后端的设备实例 | ### 资源管理 @@ -60,7 +62,7 @@ RHI 模块将上层渲染逻辑与底层图形 API 解耦，通过抽象接口 | 类 | 文档 | 描述 | |----|------|------| -| [RHIFence](fence/fence.md) | `RHIFence.h` | 同步栅栏，CPU/GPU 同步原语 | +| [RHIFence](rhi-fence/fence.md) | `RHIFence.h` | 同步栅栏，CPU/GPU 同步原语 | | [RHIPipelineState](pipeline-state/pipeline-state.md) | `RHIPipelineState.h` | 管线状态对象，封装渲染管线配置 | | [RHISampler](sampler/sampler.md) | `RHISampler.h` | 纹理采样器，配置纹理过滤和寻址模式 | | [RHIPipelineLayout](pipeline-layout/pipeline-layout.md) | `RHIPipelineLayout.h` | 管线布局，定义着色器资源绑定布局 | @@ -113,9 +115,28 @@ delete device; ## 后端文档 -- [D3D12 后端](opengl/overview.md) - DirectX 12 实现详情 +- [D3D12 后端](d3d12/d3d12.md) - DirectX 12 实现详情 - [OpenGL 后端](opengl/overview.md) - OpenGL 实现详情 +### D3D12 实现 + +| 类 | 文档 | 描述 | +|----|------|------| +| [D3D12RenderTargetView](d3d12/render-target-view/render-target-view.md) | `D3D12RenderTargetView.h` | DirectX 12 渲染目标视图实现 | +| [D3D12Shader](d3d12shader/d3d12shader.md) | `D3D12Shader.h` | DirectX 12 着色器资源实现 | +| [D3D12Texture](d3d12texture/d3d12texture.md) | `D3D12Texture.h` | DirectX 12 纹理资源实现 | +| [D3D12SwapChain](d3d12swapchain/d3d12swapchain.md) | `D3D12SwapChain.h` | DirectX 12 交换链实现 | +| [D3D12UnorderedAccessView](d3d12unorderedaccessview/d3d12unorderedaccessview.md) | `D3D12UnorderedAccessView.h` | DirectX 12 无序访问视图实现 | +| [D3D12Screenshot](d3d12screenshot/d3d12screenshot.md) | `D3D12Screenshot.h` | DirectX 12 渲染目标截图工具 | +| [D3D12Enum](d3d12enum/d3d12enum.md) | `D3D12Enum.h` | DirectX 12 枚举类型转换函数 | + +### OpenGL 实现 + +| 类 | 文档 | 描述 | +|----|------|------| +| [OpenGLBuffer](openglbuffer/openglbuffer.md) | `OpenGLBuffer.h` | OpenGL 缓冲区资源实现 | +| [OpenGLRenderTargetView](openglrendertargetview/openglrendertargetview.md) | `OpenGLRenderTargetView.h` | OpenGL 渲染目标视图实现 | + ## 相关文档 - [RHI 模块源码](../../engine/include/XCEngine/RHI/) - 源代码位置 diff --git a/docs/api/rhi/sampler/bind.md b/docs/api/rhi/sampler/bind.md new file mode 100644 index 00000000..978f6ba2 --- /dev/null +++ b/docs/api/rhi/sampler/bind.md @@ -0,0 +1,55 @@ +# RHISampler::Bind + +```cpp +virtual void Bind(unsigned int unit) = 0; +``` + +将采样器绑定到指定的纹理单元。该方法将采样器状态设置到渲染管线的对应纹理采样槽位，使其后续的纹理采样操作可以使用此采样器。 + +**参数：** + +| 参数 | 类型 | 描述 | +|------|------|------| +| `unit` | `unsigned int` | 纹理单元索引，指定绑定到哪个纹理采样槽位（通常 0-15） | + +**返回：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/RHI/RHISampler.h" + +class MySampler : public XCEngine::RHI::RHISampler { +public: + void Shutdown() override { } + void Bind(unsigned int unit) override { + m_boundUnit = unit; + } + void Unbind(unsigned int unit) override { + if (m_boundUnit == unit) { + m_boundUnit = -1; + } + } + void* GetNativeHandle() override { return nullptr; } + unsigned int GetID() override { return 0; } + +private: + int m_boundUnit = -1; +}; + +void Example() { + MySampler sampler; + sampler.Bind(0); + sampler.Bind(1); + sampler.Bind(2); +} +``` + +## 相关文档 + +- [RHISampler 总览](sampler.md) - 返回类总览 +- [RHISampler::Unbind](unbind.md) - 解绑采样器 diff --git a/docs/api/rhi/sampler/get-id.md b/docs/api/rhi/sampler/get-id.md index a38a1c38..be050653 100644 --- a/docs/api/rhi/sampler/get-id.md +++ b/docs/api/rhi/sampler/get-id.md @@ -4,16 +4,42 @@ virtual unsigned int GetID() = 0; ``` -获取采样器 ID。 +获取采样器的唯一标识符。该方法返回分配给采样器的唯一整数 ID，可用于采样器的识别、缓存管理或调试目的。 -**返回：** 采样器唯一标识符 +**参数：** 无 + +**返回：** 采样器的唯一无符号整数标识符 + +**线程安全：** ❌ + +**复杂度：** O(1) **示例：** ```cpp -unsigned int id = sampler->GetID(); +#include "XCEngine/RHI/RHISampler.h" + +class MySampler : public XCEngine::RHI::RHISampler { +public: + void Shutdown() override { } + void Bind(unsigned int unit) override { } + void Unbind(unsigned int unit) override { } + void* GetNativeHandle() override { return nullptr; } + unsigned int GetID() override { return m_id; } + +private: + unsigned int m_id = 1; +}; + +void Example() { + MySampler sampler1; + MySampler sampler2; + unsigned int id1 = sampler1.GetID(); + unsigned int id2 = sampler2.GetID(); +} ``` ## 相关文档 - [RHISampler 总览](sampler.md) - 返回类总览 +- [RHISampler::GetNativeHandle](get-native-handle.md) - 获取原生句柄 diff --git a/docs/api/rhi/sampler/get-native-handle.md b/docs/api/rhi/sampler/get-native-handle.md index 5cf1eb08..b0be5881 100644 --- a/docs/api/rhi/sampler/get-native-handle.md +++ b/docs/api/rhi/sampler/get-native-handle.md @@ -4,12 +4,43 @@ virtual void* GetNativeHandle() = 0; ``` -获取原生 API 句柄。 +获取底层图形 API 的原生句柄。该方法返回采样器在对应图形 API 中的原生对象指针或句柄，可用于调试或高级图形 API 互操作。 -**返回：** 原生采样器句柄 +**参数：** 无 + +**返回：** 指向原生图形 API 采样器对象的 void 指针，具体类型取决于底层实现（D3D11: `ID3D11SamplerState*`，D3D12: `D3D12_GPU_VIRTUAL_ADDRESS` 或 `ID3D12Resource*`，Vulkan: `VkSampler`） + +**线程安全：** ❌ **复杂度：** O(1) +**示例：** + +```cpp +#include "XCEngine/RHI/RHISampler.h" + +class MySampler : public XCEngine::RHI::RHISampler { +public: + void Shutdown() override { } + void Bind(unsigned int unit) override { } + void Unbind(unsigned int unit) override { } + void* GetNativeHandle() override { return reinterpret_cast(m_nativeHandle); } + unsigned int GetID() override { return 0; } + +private: + uint64_t m_nativeHandle = 0x12345678; +}; + +void Example() { + MySampler sampler; + void* handle = sampler.GetNativeHandle(); + if (handle != nullptr) { + // 使用原生句柄进行调试或高级操作 + } +} +``` + ## 相关文档 - [RHISampler 总览](sampler.md) - 返回类总览 +- [RHISampler::GetID](get-id.md) - 获取采样器 ID diff --git a/docs/api/rhi/sampler/methods.md b/docs/api/rhi/sampler/methods.md deleted file mode 100644 index a4307b0e..00000000 --- a/docs/api/rhi/sampler/methods.md +++ /dev/null @@ -1,41 +0,0 @@ -# RHISampler 方法 - -## Shutdown - -```cpp -virtual void Shutdown() = 0; -``` - -释放采样器资源。 - -## Bind - -```cpp -virtual void Bind(unsigned int unit) = 0; -``` - -绑定采样器到纹理单元。 - -## Unbind - -```cpp -virtual void Unbind(unsigned int unit) = 0; -``` - -解绑采样器。 - -## GetNativeHandle - -```cpp -virtual void* GetNativeHandle() = 0; -``` - -获取原生 API 句柄。 - -## GetID - -```cpp -virtual unsigned int GetID() = 0; -``` - -获取采样器 ID。 diff --git a/docs/api/rhi/sampler/sampler.md b/docs/api/rhi/sampler/sampler.md index 67224046..5c91c1d1 100644 --- a/docs/api/rhi/sampler/sampler.md +++ b/docs/api/rhi/sampler/sampler.md @@ -4,19 +4,53 @@ **类型**: `class` (abstract) -**描述**: GPU 纹理采样器抽象接口，用于配置纹理过滤和寻址模式。 +**头文件**: `RHISampler.h` + +**描述**: GPU 纹理采样器抽象接口，用于配置纹理过滤和寻址模式。采样器定义了如何对纹理进行采样，包括过滤模式、寻址模式和各向异性级别等参数。 + +## 概述 + +`RHISampler` 是 RHI 抽象层中的纹理采样器接口，提供跨平台的纹理采样配置能力。通过 `RHIDevice::CreateSampler` 创建采样器实例。 + +**关键特性**: +- 支持点采样、线性采样和各向异性采样 +- 支持 Wrap、Mirror、Clamp、Border 等寻址模式 +- 提供原生 API 句柄访问 ## 公共方法 | 方法 | 描述 | |------|------| | [`Shutdown`](shutdown.md) | 关闭并释放资源 | -| [`Bind`](../shader/bind.md) | 绑定采样器 | -| [`Unbind`](../shader/unbind.md) | 解绑采样器 | +| [`Bind`](bind.md) | 绑定采样器到纹理单元 | +| [`Unbind`](unbind.md) | 解绑采样器 | | [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | | [`GetID`](get-id.md) | 获取采样器 ID | +## 使用示例 + +```cpp +// 通过 RHIDevice 创建采样器 +SamplerDesc samplerDesc; +samplerDesc.filter = static_cast(FilterMode::Anisotropic); +samplerDesc.addressU = static_cast(TextureAddressMode::Wrap); +samplerDesc.addressV = static_cast(TextureAddressMode::Wrap); +samplerDesc.addressW = static_cast(TextureAddressMode::Wrap); +samplerDesc.maxAnisotropy = 16; +samplerDesc.minLod = 0; +samplerDesc.maxLod = FLT_MAX; + +RHISampler* sampler = device->CreateSampler(samplerDesc); + +// 绑定到纹理单元 0 +sampler->Bind(0); + +// 使用完毕后关闭 +sampler->Shutdown(); +``` + ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHI 模块总览](../rhi.md) - RHI 模块总览 - [RHITexture](../texture/texture.md) - 纹理资源 +- [RHIDevice::CreateSampler](../device/create-sampler.md) - 创建采样器 diff --git a/docs/api/rhi/sampler/shutdown.md b/docs/api/rhi/sampler/shutdown.md index 9fe18951..e588da5d 100644 --- a/docs/api/rhi/sampler/shutdown.md +++ b/docs/api/rhi/sampler/shutdown.md @@ -4,10 +4,45 @@ virtual void Shutdown() = 0; ``` -释放采样器资源。 +关闭并释放采样器资源。该方法用于在采样器不再需要时进行清理工作，释放底层图形 API 分配的资源。 + +**参数：** 无 + +**返回：** 无 + +**线程安全：** ❌ **复杂度：** O(1) +**示例：** + +```cpp +#include "XCEngine/RHI/RHISampler.h" + +class MySampler : public XCEngine::RHI::RHISampler { +public: + void Shutdown() override { + if (m_initialized) { + ReleaseNativeResource(); + m_initialized = false; + } + } + void Bind(unsigned int unit) override { } + void Unbind(unsigned int unit) override { } + void* GetNativeHandle() override { return nullptr; } + unsigned int GetID() override { return 0; } + +private: + bool m_initialized = true; + void ReleaseNativeResource() { } +}; + +void Example() { + MySampler sampler; + sampler.Shutdown(); +} +``` + ## 相关文档 - [RHISampler 总览](sampler.md) - 返回类总览 diff --git a/docs/api/rhi/sampler/unbind.md b/docs/api/rhi/sampler/unbind.md new file mode 100644 index 00000000..17ce74b7 --- /dev/null +++ b/docs/api/rhi/sampler/unbind.md @@ -0,0 +1,52 @@ +# RHISampler::Unbind + +```cpp +virtual void Unbind(unsigned int unit) = 0; +``` + +将采样器从指定的纹理单元解绑。该方法将指定的纹理单元上的采样器状态清除，使其不再占用该采样槽位。 + +**参数：** + +| 参数 | 类型 | 描述 | +|------|------|------| +| `unit` | `unsigned int` | 纹理单元索引，指定从哪个纹理采样槽位解绑 | + +**返回：** 无 + +**线程安全：** ❌ + +**复杂度：** O(1) + +**示例：** + +```cpp +#include "XCEngine/RHI/RHISampler.h" + +class MySampler : public XCEngine::RHI::RHISampler { +public: + void Shutdown() override { } + void Bind(unsigned int unit) override { m_boundUnit = unit; } + void Unbind(unsigned int unit) override { + if (m_boundUnit == unit) { + m_boundUnit = -1; + } + } + void* GetNativeHandle() override { return nullptr; } + unsigned int GetID() override { return 0; } + +private: + int m_boundUnit = -1; +}; + +void Example() { + MySampler sampler; + sampler.Bind(0); + sampler.Unbind(0); +} +``` + +## 相关文档 + +- [RHISampler 总览](sampler.md) - 返回类总览 +- [RHISampler::Bind](bind.md) - 绑定采样器 diff --git a/docs/api/rhi/shader/bind.md b/docs/api/rhi/shader/bind.md index b5461119..f24309b0 100644 --- a/docs/api/rhi/shader/bind.md +++ b/docs/api/rhi/shader/bind.md @@ -4,17 +4,37 @@ virtual void Bind() = 0; ``` -绑定着色器到管线。 +绑定着色器到渲染管线。 + +将当前着色器实例设置为活跃状态，使其参与后续的渲染操作。绑定后，着色器的 uniform 参数和资源将供 GPU 使用。 + +**线程安全：** ❌（需要在渲染线程调用） **复杂度：** O(1) **示例：** ```cpp -vs->Bind(); -ps->Bind(); +RHIShader* vertexShader = device->CreateShader(); +RHIShader* fragmentShader = device->CreateShader(); + +vertexShader->CompileFromFile(L"shaders/vertex.cso", "VSMain", "vs_5_0"); +fragmentShader->CompileFromFile(L"shaders/pixel.cso", "PSMain", "ps_5_0"); + +vertexShader->Bind(); +fragmentShader->Bind(); + +// 设置 uniform +float modelMatrix[16] = { /* 4x4 矩阵数据 */ }; +vertexShader->SetMat4("u_modelViewProj", modelMatrix); + +// 执行渲染... + +vertexShader->Unbind(); +fragmentShader->Unbind(); ``` ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 +- [`Unbind`](unbind.md) - 解绑着色器 diff --git a/docs/api/rhi/shader/compile-from-file.md b/docs/api/rhi/shader/compile-from-file.md index 92a28a53..c7a97573 100644 --- a/docs/api/rhi/shader/compile-from-file.md +++ b/docs/api/rhi/shader/compile-from-file.md @@ -4,23 +4,36 @@ virtual bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target) = 0; ``` -从文件编译着色器。 +从文件加载并编译着色器。 + +从指定的文件路径读取着色器代码并编译为 GPU 可执行的着色器程序。该方法支持各种着色器目标平台（如 D3D12 的 `vs_5_0`、`ps_5_0` 等，或 Vulkan 的 SPIR-V）。 **参数：** -- `filePath` - 着色器源文件路径 -- `entryPoint` - 入口点函数名 -- `target` - 编译目标（如 `"vs_6_0"`, `"ps_6_0"`） +- `filePath` - 着色器文件路径（宽字符字符串，支持 Unicode 路径） +- `entryPoint` - 着色器入口点函数名称（如 `"VSMain"`、`"PSMain"`） +- `target` - 着色器目标配置文件（如 `"vs_5_0"`、`"ps_5_0"`、`"spv"`） -**返回：** 成功返回 `true`，失败返回 `false` +**返回：** 编译成功返回 `true`，失败返回 `false` -**复杂度：** O(n) - 取决于着色器代码复杂度 +**线程安全：** ❌（多线程同时编译同一着色器可能导致未定义行为） + +**复杂度：** O(n)，其中 n 为着色器代码行数 **示例：** ```cpp -shader->CompileFromFile(L"shaders/vertex.hlsl", "main", "vs_6_0"); +RHIShader* vertexShader = device->CreateShader(); +if (vertexShader->CompileFromFile(L"shaders/vertex.cso", "VSMain", "vs_5_0")) { + vertexShader->Bind(); + // 使用着色器... +} else { + printf("Vertex shader compilation failed!\n"); +} +vertexShader->Shutdown(); +device->DestroyShader(vertexShader); ``` ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 +- [`Compile`](compile.md) - 从内存数据编译着色器 diff --git a/docs/api/rhi/shader/compile.md b/docs/api/rhi/shader/compile.md index b9032398..b16a666c 100644 --- a/docs/api/rhi/shader/compile.md +++ b/docs/api/rhi/shader/compile.md @@ -4,18 +4,37 @@ virtual bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target) = 0; ``` -从内存编译着色器。 +从内存数据编译着色器。 + +将已加载到内存中的着色器代码编译为 GPU 可执行的着色器程序。适用于从资源包、网络或自定义加载器获取着色器代码的场景。 **参数：** -- `sourceData` - 着色器源代码指针 -- `sourceSize` - 源代码大小 -- `entryPoint` - 入口点函数名 -- `target` - 编译目标 +- `sourceData` - 指向着色器源代码或字节码的指针 +- `sourceSize` - 源数据大小（字节数） +- `entryPoint` - 着色器入口点函数名称 +- `target` - 着色器目标配置文件 -**返回：** 成功返回 `true`，失败返回 `false` +**返回：** 编译成功返回 `true`，失败返回 `false` -**复杂度：** O(n) +**线程安全：** ❌（多线程同时编译同一着色器可能导致未定义行为） + +**复杂度：** O(n)，其中 n 为着色器代码行数 + +**示例：** + +```cpp +std::vector shaderBytes = LoadShaderFromResource("vertex_shader"); +if (!shaderBytes.empty()) { + RHIShader* shader = device->CreateShader(); + if (shader->Compile(shaderBytes.data(), shaderBytes.size(), "VSMain", "vs_5_0")) { + shader->Bind(); + // 使用着色器... + } + shader->Shutdown(); +} +``` ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 +- [`CompileFromFile`](compile-from-file.md) - 从文件编译着色器 diff --git a/docs/api/rhi/shader/get-native-handle.md b/docs/api/rhi/shader/get-native-handle.md index d46e059e..15dd4b1d 100644 --- a/docs/api/rhi/shader/get-native-handle.md +++ b/docs/api/rhi/shader/get-native-handle.md @@ -4,12 +4,32 @@ virtual void* GetNativeHandle() = 0; ``` -获取原生 API 句柄。 +获取原生图形 API 句柄。 -**返回：** 原生着色器句柄 +返回底层图形 API（如 D3D12、Vulkan）的原生着色器对象指针。用于需要直接访问底层 API 的高级场景，或与外部库互操作。 + +**返回：** 指向原生着色器对象的指针，类型取决于具体实现（如 D3D12: `ID3DBlob*`，Vulkan: `VkShaderModule`） + +**线程安全：** ❌（访问底层资源，非线程安全） **复杂度：** O(1) +**示例：** + +```cpp +RHIShader* shader = device->CreateShader(); +shader->CompileFromFile(L"shaders/compute.cso", "CSMain", "cs_5_0"); + +void* nativeHandle = shader->GetNativeHandle(); +#ifdef XCENGINE_D3D12 + ID3DBlob* d3dBlob = static_cast(nativeHandle); + // 使用 D3D12 API... +#elif defined(XCENGINE_VULKAN) + VkShaderModule vkModule = reinterpret_cast(nativeHandle); + // 使用 Vulkan API... +#endif +``` + ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/get-type.md b/docs/api/rhi/shader/get-type.md index 5b364da5..16786f12 100644 --- a/docs/api/rhi/shader/get-type.md +++ b/docs/api/rhi/shader/get-type.md @@ -6,10 +6,35 @@ virtual ShaderType GetType() const = 0; 获取着色器类型。 -**返回：** 着色器类型枚举值 +返回该着色器实例的类型，类型由 `ShaderType` 枚举定义，包括顶点着色器、像素着色器、几何着色器、计算着色器等。 + +**返回：** `ShaderType` 枚举值，表示着色器类型 + +**线程安全：** ✅（只读操作） **复杂度：** O(1) +**示例：** + +```cpp +RHIShader* shader = device->CreateShader(); +shader->CompileFromFile(L"shaders/vertex.cso", "VSMain", "vs_5_0"); + +ShaderType type = shader->GetType(); +switch (type) { + case ShaderType::Vertex: + printf("This is a vertex shader\n"); + break; + case ShaderType::Fragment: + printf("This is a fragment shader\n"); + break; + default: + printf("Other shader type\n"); + break; +} +``` + ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 +- [`ShaderType`](./shader.md#公共属性) - 着色器类型枚举定义 diff --git a/docs/api/rhi/shader/is-valid.md b/docs/api/rhi/shader/is-valid.md index 56597ea1..3d8ae5a0 100644 --- a/docs/api/rhi/shader/is-valid.md +++ b/docs/api/rhi/shader/is-valid.md @@ -4,12 +4,33 @@ virtual bool IsValid() const = 0; ``` -检查着色器是否有效（已成功编译）。 +检查着色器是否有效。 -**返回：** 有效返回 `true`，无效返回 `false` +验证着色器是否已成功编译并可以用于渲染。应在调用 `Bind()` 之前使用此方法确保着色器可用。 + +**返回：** 着色器有效返回 `true`，无效返回 `false` + +**线程安全：** ✅（只读操作） **复杂度：** O(1) +**示例：** + +```cpp +RHIShader* shader = device->CreateShader(); +if (shader->CompileFromFile(L"shaders/pixel.cso", "PSMain", "ps_5_0")) { + if (shader->IsValid()) { + shader->Bind(); + // 渲染... + shader->Unbind(); + } else { + printf("Shader is not valid!\n"); + } +} +shader->Shutdown(); +``` + ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 +- [`Bind`](bind.md) - 绑定着色器 diff --git a/docs/api/rhi/shader/set-float.md b/docs/api/rhi/shader/set-float.md index 89f6ad17..4f96fc18 100644 --- a/docs/api/rhi/shader/set-float.md +++ b/docs/api/rhi/shader/set-float.md @@ -4,14 +4,38 @@ virtual void SetFloat(const char* name, float value) = 0; ``` -设置浮点 uniform。 +设置浮点数 uniform 变量。 + +通过名称查找并设置着色器中的单精度浮点数 uniform 变量。常见用途包括设置时间值、透明度、缩放因子等。 **参数：** -- `name` - uniform 变量名 -- `value` - 浮点值 +- `name` - uniform 变量名称 +- `value` - 要设置的浮点数值 -**复杂度：** O(1) +**线程安全：** ❌（需要在渲染线程调用） + +**复杂度：** O(1)（通常为哈希表查找） + +**示例：** + +```cpp +RHIShader* shader = device->CreateShader(); +shader->CompileFromFile(L"shaders/pixel.cso", "PSMain", "ps_5_0"); +shader->Bind(); + +// 设置时间 +shader->SetFloat("u_time", elapsedTime); + +// 设置透明度 +shader->SetFloat("u_alpha", 0.5f); + +// 设置雾的起始距离 +shader->SetFloat("u_fogStart", 10.0f); +shader->SetFloat("u_fogEnd", 100.0f); +``` ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 +- [`SetInt`](set-int.md) - 设置整数 uniform +- [`SetVec3`](set-vec3.md) - 设置三维向量 uniform diff --git a/docs/api/rhi/shader/set-int.md b/docs/api/rhi/shader/set-int.md index 1bddd314..352acca7 100644 --- a/docs/api/rhi/shader/set-int.md +++ b/docs/api/rhi/shader/set-int.md @@ -4,14 +4,37 @@ virtual void SetInt(const char* name, int value) = 0; ``` -设置整数 uniform。 +设置整数 uniform 变量。 + +通过名称查找并设置着色器中的整数 uniform 变量。常见用途包括设置布尔值、纹理采样索引、渲染模式标志等。 **参数：** -- `name` - uniform 变量名 -- `value` - 整数值 +- `name` - uniform 变量名称（需与着色器代码中的变量名一致） +- `value` - 要设置的整数值 -**复杂度：** O(1) +**线程安全：** ❌（需要在渲染线程调用） + +**复杂度：** O(1)（通常为哈希表查找） + +**示例：** + +```cpp +RHIShader* shader = device->CreateShader(); +shader->CompileFromFile(L"shaders/pixel.cso", "PSMain", "ps_5_0"); +shader->Bind(); + +// 设置纹理是否启用 +shader->SetInt("u_texEnabled", 1); + +// 设置渲染模式 +shader->SetInt("u_renderMode", 2); + +// 设置阴影开关 +shader->SetInt("u_shadowEnabled", 0); +``` ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 +- [`SetFloat`](set-float.md) - 设置浮点数 uniform +- [`SetVec3`](set-vec3.md) - 设置三维向量 uniform diff --git a/docs/api/rhi/shader/set-mat4.md b/docs/api/rhi/shader/set-mat4.md index b739e3f1..8c0e97b0 100644 --- a/docs/api/rhi/shader/set-mat4.md +++ b/docs/api/rhi/shader/set-mat4.md @@ -4,14 +4,36 @@ virtual void SetMat4(const char* name, const float* value) = 0; ``` -设置 4x4 矩阵 uniform。 +设置 4x4 矩阵 uniform 变量。 + +通过名称查找并设置着色器中的 4x4 变换矩阵 uniform 变量。常见用途包括设置模型矩阵、视图矩阵、投影矩阵及其组合（MVP）、法线矩阵等。 **参数：** -- `name` - uniform 变量名 -- `value` - 矩阵数据指针（16 个 float） +- `name` - uniform 变量名称 +- `value` - 指向 16 个 float 元素的数组指针 -**复杂度：** O(1) +**线程安全：** ❌（需要在渲染线程调用） + +**复杂度：** O(1)（通常为哈希表查找） + +**示例：** + +```cpp +RHIShader* shader = device->CreateShader(); +shader->CompileFromFile(L"shaders/vertex.cso", "VSMain", "vs_5_0"); +shader->Bind(); + +// 设置变换矩阵 +float modelMatrix[16] = { /* 4x4 模型矩阵数据 */ }; +float viewMatrix[16] = { /* 4x4 视图矩阵数据 */ }; +float projMatrix[16] = { /* 4x4 投影矩阵数据 */ }; + +shader->SetMat4("u_model", modelMatrix); +shader->SetMat4("u_view", viewMatrix); +shader->SetMat4("u_proj", projMatrix); +``` ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 +- [`SetVec4`](set-vec4.md) - 设置四维向量 uniform diff --git a/docs/api/rhi/shader/set-vec3.md b/docs/api/rhi/shader/set-vec3.md index 3ef86651..a1a21bc8 100644 --- a/docs/api/rhi/shader/set-vec3.md +++ b/docs/api/rhi/shader/set-vec3.md @@ -4,14 +4,39 @@ virtual void SetVec3(const char* name, float x, float y, float z) = 0; ``` -设置三维向量 uniform。 +设置三维向量 uniform 变量。 + +通过名称查找并设置着色器中的三维向量 uniform 变量。常见用途包括设置位置、法线、方向、光照方向、颜色等。 **参数：** -- `name` - uniform 变量名 -- `x, y, z` - 向量分量 +- `name` - uniform 变量名称 +- `x` - 向量的 X 分量 +- `y` - 向量的 Y 分量 +- `z` - 向量的 Z 分量 -**复杂度：** O(1) +**线程安全：** ❌（需要在渲染线程调用） + +**复杂度：** O(1)（通常为哈希表查找） + +**示例：** + +```cpp +RHIShader* shader = device->CreateShader(); +shader->CompileFromFile(L"shaders/pixel.cso", "PSMain", "ps_5_0"); +shader->Bind(); + +// 设置光照方向 +shader->SetVec3("u_lightDir", 0.5f, 1.0f, 0.3f); + +// 设置相机位置 +shader->SetVec3("u_cameraPos", camera.x, camera.y, camera.z); + +// 设置材质颜色 +shader->SetVec3("u_baseColor", 1.0f, 0.8f, 0.6f); +``` ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 +- [`SetFloat`](set-float.md) - 设置浮点数 uniform +- [`SetVec4`](set-vec4.md) - 设置四维向量 uniform diff --git a/docs/api/rhi/shader/set-vec4.md b/docs/api/rhi/shader/set-vec4.md index b3e456f3..a1a5dccf 100644 --- a/docs/api/rhi/shader/set-vec4.md +++ b/docs/api/rhi/shader/set-vec4.md @@ -4,14 +4,40 @@ virtual void SetVec4(const char* name, float x, float y, float z, float w) = 0; ``` -设置四维向量 uniform。 +设置四维向量 uniform 变量。 + +通过名称查找并设置着色器中的四维向量 uniform 变量。常见用途包括设置齐次坐标、颜色（带透明度）、平面方程等。 **参数：** -- `name` - uniform 变量名 -- `x, y, z, w` - 向量分量 +- `name` - uniform 变量名称 +- `x` - 向量的 X 分量 +- `y` - 向量的 Y 分量 +- `z` - 向量的 Z 分量 +- `w` - 向量的 W 分量（齐次坐标或透明度） -**复杂度：** O(1) +**线程安全：** ❌（需要在渲染线程调用） + +**复杂度：** O(1)（通常为哈希表查找） + +**示例：** + +```cpp +RHIShader* shader = device->CreateShader(); +shader->CompileFromFile(L"shaders/pixel.cso", "PSMain", "ps_5_0"); +shader->Bind(); + +// 设置带透明度的颜色 +shader->SetVec4("u_color", 1.0f, 0.0f, 0.0f, 0.8f); + +// 设置平面方程 (ax + by + cz + d = 0) +shader->SetVec4("u_clipPlane", 0.0f, 1.0f, 0.0f, 0.0f); + +// 设置纹理坐标变换 +shader->SetVec4("u_texOffset", 0.1f, 0.1f, 2.0f, 2.0f); +``` ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 +- [`SetVec3`](set-vec3.md) - 设置三维向量 uniform +- [`SetMat4`](set-mat4.md) - 设置 4x4 矩阵 uniform diff --git a/docs/api/rhi/shader/shader.md b/docs/api/rhi/shader/shader.md index 89932473..568d7403 100644 --- a/docs/api/rhi/shader/shader.md +++ b/docs/api/rhi/shader/shader.md @@ -4,27 +4,44 @@ **类型**: `class` (abstract) -**描述**: GPU 着色器资源抽象接口，用于管理着色器代码的编译和绑定。 +**头文件**: `XCEngine/RHI/RHIShader.h` + +**描述**: 着色器接口，管理 GPU 着色器程序 + +## 概述 + +`RHIShader` 是 XCEngine RHI 模块中的抽象着色器接口类，定义了 GPU 着色器程序的标准 API。该类是所有具体着色器实现（如 D3D12Shader、VulkanShader 等）的基类，提供了统一的着色器编译、绑定和参数设置接口。 + +设计目的： +- 提供跨平台的着色器抽象 +- 统一着色器资源管理和绑定流程 +- 简化渲染管线中着色器的使用 ## 公共方法 | 方法 | 描述 | |------|------| | [`CompileFromFile`](compile-from-file.md) | 从文件编译着色器 | -| [`Compile`](compile.md) | 从源码编译着色器 | +| [`Compile`](compile.md) | 从内存数据编译着色器 | | [`GetType`](get-type.md) | 获取着色器类型 | | [`IsValid`](is-valid.md) | 检查着色器是否有效 | -| [`Bind`](bind.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) | 设置 vec3 uniform | -| [`SetVec4`](set-vec4.md) | 设置 vec4 uniform | -| [`SetMat4`](set-mat4.md) | 设置 mat4 uniform | -| [`Shutdown`](shutdown.md) | 关闭并释放资源 | -| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | +| [`SetVec3`](set-vec3.md) | 设置三维向量 uniform | +| [`SetVec4`](set-vec4.md) | 设置四维向量 uniform | +| [`SetMat4`](set-mat4.md) | 设置 4x4 矩阵 uniform | +| [`Shutdown`](shutdown.md) | 释放着色器资源 | -## 着色器类型 (ShaderType) +## 公共属性 + +| 属性 | 类型 | 描述 | +|------|------|------| +| `ShaderType` | `enum` | 着色器类型枚举 | + +### ShaderType 枚举值 | 枚举值 | 描述 | |--------|------| @@ -43,13 +60,36 @@ ## 使用示例 ```cpp -RHIShader* vs = device->CompileShader({}); -vs->CompileFromFile(L"shaders/vertex.hlsl", "main", "vs_6_0"); -vs->SetMat4("modelMatrix", modelMatrix); -vs->Bind(); +#include "XCEngine/RHI/RHIShader.h" +#include "XCEngine/RHI/RHIDevice.h" + +using namespace XCEngine::RHI; + +// 通过 RHIDevice 编译着色器 +ShaderCompileDesc vsDesc; +vsDesc.fileName = L"shaders/vertex.cso"; +vsDesc.entryPoint = "VSMain"; +vsDesc.profile = "vs_5_0"; +RHIShader* vertexShader = device->CompileShader(vsDesc); +if (vertexShader && vertexShader->IsValid()) { + vertexShader->Bind(); + + // 设置 uniform 参数 + float modelMatrix[16] = { /* 4x4 模型矩阵数据 */ }; + vertexShader->SetMat4("u_modelMatrix", modelMatrix); + + // 渲染... + + vertexShader->Unbind(); +} + +if (vertexShader) { + vertexShader->Shutdown(); + delete vertexShader; +} ``` ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHI 模块总览](../rhi.md) - RHI 模块总览 - [RHIDevice](../device/device.md) - 创建设备 diff --git a/docs/api/rhi/shader/shutdown.md b/docs/api/rhi/shader/shutdown.md index 9972cefe..b770a99e 100644 --- a/docs/api/rhi/shader/shutdown.md +++ b/docs/api/rhi/shader/shutdown.md @@ -6,8 +6,27 @@ virtual void Shutdown() = 0; 释放着色器资源。 +销毁着色器并释放关联的 GPU 资源。调用此方法后，着色器实例将变为无效状态，不应再被使用。通常在渲染系统关闭或切换渲染设备时调用。 + +**线程安全：** ❌（需要在渲染线程调用，且调用后不能在其他线程访问） + **复杂度：** O(1) +**示例：** + +```cpp +RHIShader* shader = device->CreateShader(); +if (shader->CompileFromFile(L"shaders/vertex.cso", "VSMain", "vs_5_0")) { + shader->Bind(); + // 使用着色器... + shader->Unbind(); +} + +shader->Shutdown(); +// shader 现在已无效，不能再使用 +device->DestroyShader(shader); +``` + ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 diff --git a/docs/api/rhi/shader/unbind.md b/docs/api/rhi/shader/unbind.md index 53aedf60..9a256f50 100644 --- a/docs/api/rhi/shader/unbind.md +++ b/docs/api/rhi/shader/unbind.md @@ -6,8 +6,25 @@ virtual void Unbind() = 0; 解绑着色器。 +将当前着色器从渲染管线中移除，终止其参与后续渲染操作。通常在切换渲染状态或结束特定渲染 Pass 时调用。 + +**线程安全：** ❌（需要在渲染线程调用） + **复杂度：** O(1) +**示例：** + +```cpp +shader->Bind(); +// 渲染使用该着色器的物体... +shader->Unbind(); + +// 切换到其他着色器 +otherShader->Bind(); +// ... +``` + ## 相关文档 -- [RHIShader 总览](shader.md) - 返回类总览 +- [RHIShader](shader.md) - 返回类总览 +- [`Bind`](bind.md) - 绑定着色器 diff --git a/docs/api/rhi/swap-chain/get-current-back-buffer-index.md b/docs/api/rhi/swap-chain/get-current-back-buffer-index.md index 18666dfa..94d835a0 100644 --- a/docs/api/rhi/swap-chain/get-current-back-buffer-index.md +++ b/docs/api/rhi/swap-chain/get-current-back-buffer-index.md @@ -8,6 +8,8 @@ virtual uint32_t GetCurrentBackBufferIndex() const = 0; **返回：** 当前后台缓冲区索引 +**线程安全：** ✅ + **示例：** ```cpp diff --git a/docs/api/rhi/swap-chain/get-current-back-buffer.md b/docs/api/rhi/swap-chain/get-current-back-buffer.md index b068535c..c4bfb907 100644 --- a/docs/api/rhi/swap-chain/get-current-back-buffer.md +++ b/docs/api/rhi/swap-chain/get-current-back-buffer.md @@ -6,7 +6,9 @@ virtual RHITexture* GetCurrentBackBuffer() = 0; 获取当前后台缓冲区纹理。 -**返回：** 当前后台缓冲区纹理指针 +**返回：** `RHITexture*` - 当前后台缓冲区纹理指针 + +**线程安全：** ✅ **示例：** diff --git a/docs/api/rhi/swap-chain/get-native-handle.md b/docs/api/rhi/swap-chain/get-native-handle.md index eeacab3c..a19c2543 100644 --- a/docs/api/rhi/swap-chain/get-native-handle.md +++ b/docs/api/rhi/swap-chain/get-native-handle.md @@ -8,8 +8,16 @@ virtual void* GetNativeHandle() = 0; **返回：** 原生交换链句柄 +**线程安全：** ✅ + **复杂度：** O(1) +**示例：** + +```cpp +void* handle = swapChain->GetNativeHandle(); +``` + ## 相关文档 - [RHISwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/swap-chain/is-fullscreen.md b/docs/api/rhi/swap-chain/is-fullscreen.md index f7ef1b0b..c430aad0 100644 --- a/docs/api/rhi/swap-chain/is-fullscreen.md +++ b/docs/api/rhi/swap-chain/is-fullscreen.md @@ -8,6 +8,8 @@ virtual bool IsFullscreen() const = 0; **返回：** 如果全屏返回 true +**线程安全：** ✅ + **示例：** ```cpp diff --git a/docs/api/rhi/swap-chain/methods.md b/docs/api/rhi/swap-chain/methods.md deleted file mode 100644 index 5f2ac89e..00000000 --- a/docs/api/rhi/swap-chain/methods.md +++ /dev/null @@ -1,89 +0,0 @@ -# RHISwapChain 方法 - -## Shutdown - -```cpp -virtual void Shutdown() = 0; -``` - -关闭交换链。 - -## GetCurrentBackBufferIndex - -```cpp -virtual uint32_t GetCurrentBackBufferIndex() const = 0; -``` - -获取当前后台缓冲索引。 - -## GetCurrentBackBuffer - -```cpp -virtual RHITexture* GetCurrentBackBuffer() = 0; -``` - -获取当前后台缓冲纹理。 - -## Present - -```cpp -virtual void Present(uint32_t syncInterval = 1, uint32_t flags = 0) = 0; -``` - -呈现渲染结果。 - -## Resize - -```cpp -virtual void Resize(uint32_t width, uint32_t height) = 0; -``` - -调整交换链大小。 - -## SetFullscreen - -```cpp -virtual void SetFullscreen(bool fullscreen) = 0; -``` - -设置全屏模式。 - -## IsFullscreen - -```cpp -virtual bool IsFullscreen() const = 0; -``` - -检查是否全屏。 - -## ShouldClose - -```cpp -virtual bool ShouldClose() const = 0; -``` - -检查是否应该关闭。 - -## SetShouldClose - -```cpp -virtual void SetShouldClose(bool shouldClose) = 0; -``` - -设置关闭标志。 - -## PollEvents - -```cpp -virtual void PollEvents() = 0; -``` - -处理窗口事件。 - -## GetNativeHandle - -```cpp -virtual void* GetNativeHandle() = 0; -``` - -获取原生 API 句柄。 diff --git a/docs/api/rhi/swap-chain/poll-events.md b/docs/api/rhi/swap-chain/poll-events.md index c49d8723..91399ad5 100644 --- a/docs/api/rhi/swap-chain/poll-events.md +++ b/docs/api/rhi/swap-chain/poll-events.md @@ -6,6 +6,10 @@ virtual void PollEvents() = 0; 处理窗口事件。 +**返回：** 无 + +**线程安全：** ❌ + **示例：** ```cpp diff --git a/docs/api/rhi/swap-chain/present.md b/docs/api/rhi/swap-chain/present.md index ca10e72d..f04fa609 100644 --- a/docs/api/rhi/swap-chain/present.md +++ b/docs/api/rhi/swap-chain/present.md @@ -10,6 +10,10 @@ virtual void Present(uint32_t syncInterval = 1, uint32_t flags = 0) = 0; - `syncInterval` - 垂直同步间隔（0=立即，1+=等待） - `flags` - 呈现标志 +**返回：** 无 + +**线程安全：** ❌ + **示例：** ```cpp diff --git a/docs/api/rhi/swap-chain/resize.md b/docs/api/rhi/swap-chain/resize.md index d18a0983..98f75851 100644 --- a/docs/api/rhi/swap-chain/resize.md +++ b/docs/api/rhi/swap-chain/resize.md @@ -10,7 +10,9 @@ virtual void Resize(uint32_t width, uint32_t height) = 0; - `width` - 新的宽度 - `height` - 新的高度 -**复杂度：** O(n) - 取决于缓冲区数量 +**返回：** 无 + +**线程安全：** ❌ **注意：** - 调整大小会导致所有后台缓冲区重建 diff --git a/docs/api/rhi/swap-chain/set-fullscreen.md b/docs/api/rhi/swap-chain/set-fullscreen.md index bdc99ac9..41ad5677 100644 --- a/docs/api/rhi/swap-chain/set-fullscreen.md +++ b/docs/api/rhi/swap-chain/set-fullscreen.md @@ -9,6 +9,10 @@ virtual void SetFullscreen(bool fullscreen) = 0; **参数：** - `fullscreen` - 是否全屏 +**返回：** 无 + +**线程安全：** ❌ + **示例：** ```cpp diff --git a/docs/api/rhi/swap-chain/set-should-close.md b/docs/api/rhi/swap-chain/set-should-close.md index f16d4dc0..841c9e1f 100644 --- a/docs/api/rhi/swap-chain/set-should-close.md +++ b/docs/api/rhi/swap-chain/set-should-close.md @@ -9,6 +9,10 @@ virtual void SetShouldClose(bool shouldClose) = 0; **参数：** - `shouldClose` - 是否应该关闭 +**返回：** 无 + +**线程安全：** ❌ + **示例：** ```cpp diff --git a/docs/api/rhi/swap-chain/should-close.md b/docs/api/rhi/swap-chain/should-close.md index 7d7eed36..d51e630b 100644 --- a/docs/api/rhi/swap-chain/should-close.md +++ b/docs/api/rhi/swap-chain/should-close.md @@ -8,6 +8,8 @@ virtual bool ShouldClose() const = 0; **返回：** 如果应该关闭返回 true +**线程安全：** ✅ + **示例：** ```cpp diff --git a/docs/api/rhi/swap-chain/shutdown.md b/docs/api/rhi/swap-chain/shutdown.md index 07f8d25d..b2d82325 100644 --- a/docs/api/rhi/swap-chain/shutdown.md +++ b/docs/api/rhi/swap-chain/shutdown.md @@ -6,8 +6,16 @@ virtual void Shutdown() = 0; 关闭交换链，释放所有相关资源。 +**线程安全：** ❌ + **复杂度：** O(n) - 取决于管理的缓冲区数量 +**示例：** + +```cpp +swapChain->Shutdown(); +``` + ## 相关文档 - [RHISwapChain 总览](swap-chain.md) - 返回类总览 diff --git a/docs/api/rhi/swap-chain/swap-chain.md b/docs/api/rhi/swap-chain/swap-chain.md index 9deaa4df..89492b69 100644 --- a/docs/api/rhi/swap-chain/swap-chain.md +++ b/docs/api/rhi/swap-chain/swap-chain.md @@ -2,9 +2,21 @@ **命名空间**: `XCEngine::RHI` -**类型**: `class` (abstract) +**类型**: `class` (抽象基类) -**描述**: GPU 交换链抽象接口，用于管理窗口渲染和帧缓冲区切换。 +**头文件**: `XCEngine/RHI/RHISwapChain.h` + +**描述**: GPU 交换链抽象接口，管理窗口渲染和帧缓冲区切换。 + +## 概述 + +`RHISwapChain` 是 RHI 模块中的核心接口之一，负责管理渲染目标帧缓冲区的切换和呈现。该抽象类为不同图形 API（D3D12、Vulkan 等）提供统一接口，使上层渲染代码无需关心底层实现细节。 + +主要职责： +- 管理前后台缓冲区切换 +- 处理窗口全屏/窗口化模式切换 +- 协调垂直同步呈现 +- 提供原生 API 句柄供高级用法 ## 公共方法 @@ -39,5 +51,5 @@ while (!swapChain->ShouldClose()) { ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [RHI 模块总览](../rhi.md) - RHI 模块总览 - [RHITexture](../texture/texture.md) - 纹理资源 diff --git a/docs/api/rhi/texture/dtor.md b/docs/api/rhi/texture/dtor.md new file mode 100644 index 00000000..cd60d979 --- /dev/null +++ b/docs/api/rhi/texture/dtor.md @@ -0,0 +1,28 @@ +# RHITexture::~RHITexture + +```cpp +virtual ~RHITexture() = default; +``` + +虚析构函数，确保派生类对象通过基类指针删除时能正确调用析构函数。 + +**参数：** 无 + +**返回：** 无 + +**线程安全：** ✅ + +**复杂度：** O(1) + +**示例：** + +```cpp +// 通过基类指针销毁纹理对象 +RHITexture* texture = device->CreateTexture(desc); +// ... 使用 texture ... +delete texture; // 自动调用派生类析构函数 +``` + +## 相关文档 + +- [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-depth.md b/docs/api/rhi/texture/get-depth.md index fdaf4ddd..8aa0d886 100644 --- a/docs/api/rhi/texture/get-depth.md +++ b/docs/api/rhi/texture/get-depth.md @@ -6,10 +6,20 @@ virtual uint32_t GetDepth() const = 0; 获取纹理深度（3D 纹理）。 -**返回：** 纹理深度 +**参数：** 无 + +**返回：** 纹理深度。对于 1D/2D 纹理返回 1 + +**线程安全：** ✅ **复杂度：** O(1) +**示例：** + +```cpp +uint32_t depth = texture->GetDepth(); +``` + ## 相关文档 - [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-format.md b/docs/api/rhi/texture/get-format.md index 50fd3c95..b59651ff 100644 --- a/docs/api/rhi/texture/get-format.md +++ b/docs/api/rhi/texture/get-format.md @@ -6,10 +6,20 @@ virtual Format GetFormat() const = 0; 获取纹理格式。 +**参数：** 无 + **返回：** 纹理格式枚举值 +**线程安全：** ✅ + **复杂度：** O(1) +**示例：** + +```cpp +Format format = texture->GetFormat(); +``` + ## 相关文档 - [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-height.md b/docs/api/rhi/texture/get-height.md index fe5675e8..5158d084 100644 --- a/docs/api/rhi/texture/get-height.md +++ b/docs/api/rhi/texture/get-height.md @@ -6,10 +6,20 @@ virtual uint32_t GetHeight() const = 0; 获取纹理高度（像素）。 -**返回：** 纹理高度 +**参数：** 无 + +**返回：** 纹理高度（像素） + +**线程安全：** ✅ **复杂度：** O(1) +**示例：** + +```cpp +uint32_t height = texture->GetHeight(); +``` + ## 相关文档 - [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-mip-levels.md b/docs/api/rhi/texture/get-mip-levels.md index 3c0e74c0..cf596961 100644 --- a/docs/api/rhi/texture/get-mip-levels.md +++ b/docs/api/rhi/texture/get-mip-levels.md @@ -6,10 +6,20 @@ virtual uint32_t GetMipLevels() const = 0; 获取 Mipmap 级别数。 +**参数：** 无 + **返回：** Mipmap 级别数 +**线程安全：** ✅ + **复杂度：** O(1) +**示例：** + +```cpp +uint32_t mipLevels = texture->GetMipLevels(); +``` + ## 相关文档 - [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-name.md b/docs/api/rhi/texture/get-name.md index a2ede79c..de0da41e 100644 --- a/docs/api/rhi/texture/get-name.md +++ b/docs/api/rhi/texture/get-name.md @@ -1,20 +1,26 @@ -# RHITexture::GetName / SetName +# RHITexture::GetName ```cpp virtual const std::string& GetName() const = 0; -virtual void SetName(const std::string& name) = 0; ``` -获取或设置纹理名称（用于调试）。 +获取纹理名称（用于调试）。 + +**参数：** 无 + +**返回：** 纹理名称字符串引用 + +**线程安全：** ❌ **复杂度：** O(1) **示例：** ```cpp -texture->SetName("DiffuseMap_Main"); +const std::string& name = texture->GetName(); ``` ## 相关文档 - [RHITexture 总览](texture.md) - 返回类总览 +- [SetName](set-name.md) - 设置资源名称 diff --git a/docs/api/rhi/texture/get-native-handle.md b/docs/api/rhi/texture/get-native-handle.md index eac0e540..a623d0f0 100644 --- a/docs/api/rhi/texture/get-native-handle.md +++ b/docs/api/rhi/texture/get-native-handle.md @@ -4,12 +4,22 @@ virtual void* GetNativeHandle() = 0; ``` -获取原生 API 句柄。 +获取原生 API 句柄（用于平台特定操作）。 -**返回：** 原生纹理句柄 +**参数：** 无 + +**返回：** 原生纹理句柄（根据后端返回 D3D12 纹理指针或 OpenGL 纹理 ID 等） + +**线程安全：** ✅ **复杂度：** O(1) +**示例：** + +```cpp +void* handle = texture->GetNativeHandle(); +``` + ## 相关文档 - [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-state.md b/docs/api/rhi/texture/get-state.md index 2b907ad0..573211aa 100644 --- a/docs/api/rhi/texture/get-state.md +++ b/docs/api/rhi/texture/get-state.md @@ -6,10 +6,20 @@ virtual ResourceStates GetState() const = 0; 获取当前资源状态。 -**返回：** 资源状态枚举值 +**参数：** 无 + +**返回：** 当前资源状态枚举值 + +**线程安全：** ❌ **复杂度：** O(1) +**示例：** + +```cpp +ResourceStates state = texture->GetState(); +``` + ## 相关文档 - [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-texture-type.md b/docs/api/rhi/texture/get-texture-type.md index 3081d471..b2172314 100644 --- a/docs/api/rhi/texture/get-texture-type.md +++ b/docs/api/rhi/texture/get-texture-type.md @@ -6,10 +6,23 @@ virtual TextureType GetTextureType() const = 0; 获取纹理类型。 -**返回：** 纹理类型枚举值 +**参数：** 无 + +**返回：** 纹理类型枚举值（1D、2D、3D、立方体等） + +**线程安全：** ✅ **复杂度：** O(1) +**示例：** + +```cpp +TextureType type = texture->GetTextureType(); +if (type == TextureType::TextureCube) { + // 处理立方体贴图 +} +``` + ## 相关文档 - [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/get-width.md b/docs/api/rhi/texture/get-width.md index 9b339620..ffdc96da 100644 --- a/docs/api/rhi/texture/get-width.md +++ b/docs/api/rhi/texture/get-width.md @@ -6,10 +6,20 @@ virtual uint32_t GetWidth() const = 0; 获取纹理宽度（像素）。 -**返回：** 纹理宽度 +**参数：** 无 + +**返回：** 纹理宽度（像素） + +**线程安全：** ✅ **复杂度：** O(1) +**示例：** + +```cpp +uint32_t width = texture->GetWidth(); +``` + ## 相关文档 - [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/set-name.md b/docs/api/rhi/texture/set-name.md index 5300884d..4878fb79 100644 --- a/docs/api/rhi/texture/set-name.md +++ b/docs/api/rhi/texture/set-name.md @@ -9,6 +9,10 @@ virtual void SetName(const std::string& name) = 0; **参数：** - `name` - 新名称 +**返回：** 无 + +**线程安全：** ❌ + **复杂度：** O(1) **示例：** diff --git a/docs/api/rhi/texture/set-state.md b/docs/api/rhi/texture/set-state.md index 5956f72a..dce587c3 100644 --- a/docs/api/rhi/texture/set-state.md +++ b/docs/api/rhi/texture/set-state.md @@ -9,6 +9,10 @@ virtual void SetState(ResourceStates state) = 0; **参数：** - `state` - 新的资源状态 +**返回：** 无 + +**线程安全：** ❌ + **复杂度：** O(1) **示例：** diff --git a/docs/api/rhi/texture/shutdown.md b/docs/api/rhi/texture/shutdown.md index 9ccf4beb..0754c028 100644 --- a/docs/api/rhi/texture/shutdown.md +++ b/docs/api/rhi/texture/shutdown.md @@ -4,10 +4,22 @@ virtual void Shutdown() = 0; ``` -释放纹理资源。 +关闭并释放纹理资源。 + +**参数：** 无 + +**返回：** 无 + +**线程安全：** ❌ **复杂度：** O(1) +**示例：** + +```cpp +texture->Shutdown(); +``` + ## 相关文档 - [RHITexture 总览](texture.md) - 返回类总览 diff --git a/docs/api/rhi/texture/texture.md b/docs/api/rhi/texture/texture.md index 2b27912e..26bcd9d9 100644 --- a/docs/api/rhi/texture/texture.md +++ b/docs/api/rhi/texture/texture.md @@ -4,12 +4,19 @@ **类型**: `class` (abstract) +**头文件**: `XCEngine/RHI/RHITexture.h` + **描述**: GPU 纹理资源抽象接口，用于管理 1D、2D、3D 纹理和立方体贴图等 GPU 资源。 +## 概述 + +`RHITexture` 是 GPU 纹理资源的抽象接口，封装了 1D、2D、3D 纹理和立方体贴图等资源的创建、状态管理、查询等操作。通过 RHI 抽象层，RHITexture 可在不同图形 API（DirectX 12、OpenGL）之间无缝切换。 + ## 公共方法 | 方法 | 描述 | |------|------| +| [`~RHITexture`](dtor.md) | 虚析构函数 | | [`GetWidth`](get-width.md) | 获取纹理宽度 | | [`GetHeight`](get-height.md) | 获取纹理高度 | | [`GetDepth`](get-depth.md) | 获取纹理深度 | @@ -18,10 +25,10 @@ | [`GetTextureType`](get-texture-type.md) | 获取纹理类型 | | [`GetState`](get-state.md) | 获取资源状态 | | [`SetState`](set-state.md) | 设置资源状态 | -| [`Shutdown`](shutdown.md) | 关闭并释放资源 | | [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | | [`GetName`](get-name.md) | 获取资源名称 | | [`SetName`](set-name.md) | 设置资源名称 | +| [`Shutdown`](shutdown.md) | 关闭并释放资源 | ## 纹理类型 (TextureType) @@ -62,19 +69,30 @@ ## 使用示例 ```cpp -TextureDesc desc; -desc.width = 1024; -desc.height = 1024; -desc.format = (uint32_t)Format::R8G8B8A8_UNorm; -desc.textureType = (uint32_t)TextureType::Texture2D; - +// 假设已通过 RHIDevice 创建了纹理 RHITexture* texture = device->CreateTexture(desc); + +// 查询纹理属性 +uint32_t width = texture->GetWidth(); +uint32_t height = texture->GetHeight(); +Format format = texture->GetFormat(); +TextureType type = texture->GetTextureType(); + +// 设置资源状态 texture->SetState(ResourceStates::PixelShaderResource); + +// 设置调试名称 +texture->SetName("DiffuseMap_Main"); + +// 获取原生句柄（用于平台特定操作） +void* nativeHandle = texture->GetNativeHandle(); + +// 关闭并释放资源 texture->Shutdown(); ``` ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [../rhi.md](../rhi.md) - RHI 模块总览 - [RHIDevice](../device/device.md) - 创建设备 - [RHIBuffer](../buffer/buffer.md) - 缓冲区资源 diff --git a/docs/api/rhi/types/types.md b/docs/api/rhi/types/types.md index 67e72f18..ba71da75 100644 --- a/docs/api/rhi/types/types.md +++ b/docs/api/rhi/types/types.md @@ -4,78 +4,553 @@ **类型**: `structs` +**头文件**: `XCEngine/RHI/RHITypes.h` + **描述**: RHI 模块中使用的所有结构体类型汇总。 ## 概述 本模块汇总了 RHI 模块中定义的所有结构体类型。这些结构体用于配置各种资源的创建和渲染状态。 -## 主要结构体 +## 视口和矩形 -### 视口和矩形 +### Viewport -| 结构体 | 描述 | -|--------|------| -| `Viewport` | 视口结构体 | -| `Rect` | 裁剪矩形结构体 | -| `Color` | 颜色结构体 | -| `ClearValue` | 清除值结构体 | +视口结构体，定义渲染区域。 -### 着色器 +```cpp +struct Viewport { + float topLeftX; // 左上角 X 坐标 + float topLeftY; // 左上角 Y 坐标 + float width; // 视口宽度 + float height; // 视口高度 + float minDepth; // 最小深度值 + float maxDepth; // 最大深度值 +}; +``` -| 结构体 | 描述 | -|--------|------| -| `ShaderCompileMacro` | 着色器编译宏定义 | -| `ShaderCompileDesc` | 着色器编译描述 | -| `InputElementDesc` | 输入布局元素描述 | -| `InputLayoutDesc` | 输入布局描述 | +### Rect -### 资源和描述符 +裁剪矩形结构体。 -| 结构体 | 描述 | -|--------|------| -| `TextureDesc` | 纹理描述 | -| `BufferDesc` | 缓冲区描述 | -| `RenderTargetDesc` | 渲染目标描述 | -| `DepthStencilDesc` | 深度模板描述 | -| `DescriptorHeapDesc` | 描述符堆描述 | -| `RenderTargetViewDesc` | 渲染目标视图描述 | -| `DepthStencilViewDesc` | 深度模板视图描述 | -| `ShaderResourceViewDesc` | 着色器资源视图描述 | -| `ConstantBufferViewDesc` | 常量缓冲视图描述 | -| `UnorderedAccessViewDesc` | 无序访问视图描述 | +```cpp +struct Rect { + int32_t left; // 左边 X 坐标 + int32_t top; // 顶边 Y 坐标 + int32_t right; // 右边 X 坐标 + int32_t bottom; // 底边 Y 坐标 +}; +``` -### 命令 +### Color -| 结构体 | 描述 | -|--------|------| -| `CommandQueueDesc` | 命令队列描述 | -| `CommandListDesc` | 命令列表描述 | -| `CommandAllocatorDesc` | 命令分配器描述 | -| `FenceDesc` | 栅栏描述 | -| `QueryHeapDesc` | 查询堆描述 | -| `SamplerDesc` | 采样器描述 | -| `SwapChainDesc` | 交换链描述 | +颜色结构体，使用 RGBA 分量。 -### 设备 +```cpp +struct Color { + float r; // 红色分量 + float g; // 绿色分量 + float b; // 蓝色分量 + float a; // 透明度分量 +}; +``` -| 结构体 | 描述 | -|--------|------| -| `RHIDeviceDesc` | 设备描述 | -| `RHIDeviceInfo` | 设备信息 | -| `RHIRenderPassDesc` | 渲染通道描述 | -| `RHIPipelineLayoutDesc` | 管线布局描述 | +### ClearValue -### 句柄 +清除值结构体，用于渲染目标清除操作。 -| 结构体 | 描述 | -|--------|------| -| `DescriptorHandle` | 描述符句柄 | -| `GPUDescriptorHandle` | GPU 描述符句柄 | -| `CPUDescriptorHandle` | CPU 描述符句柄 | -| `SubresourceRange` | 子资源范围 | +```cpp +struct ClearValue { + Color color; // 清除颜色 + float depth; // 清除深度值 + uint8_t stencil; // 清除模板值 +}; +``` + +## 着色器相关 + +### ShaderCompileMacro + +着色器编译宏定义。 + +```cpp +struct ShaderCompileMacro { + std::wstring name; // 宏名称 + std::wstring definition; // 宏定义值 +}; +``` + +### ShaderCompileDesc + +着色器编译描述。 + +```cpp +struct ShaderCompileDesc { + std::wstring entryPoint; // 入口点函数名 + std::wstring profile; // 着色器配置文件 + std::wstring fileName; // 着色器源文件名 + std::vector macros; // 宏定义列表 +}; +``` + +### InputElementDesc + +输入布局元素描述，定义顶点缓冲区的数据布局。 + +```cpp +struct InputElementDesc { + std::string semanticName; // 语义名称 (如 "POSITION", "TEXCOORD") + uint32_t semanticIndex; // 语义索引 + uint32_t format; // 数据格式 (参见 Format 枚举) + uint32_t inputSlot; // 输入槽位 + uint32_t alignedByteOffset; // 对齐字节偏移 + uint32_t inputSlotClass; // 输入槽类别 + uint32_t instanceDataStepRate; // 实例数据步进率 +}; +``` + +### InputLayoutDesc + +输入布局描述，包含多个输入元素。 + +```cpp +struct InputLayoutDesc { + std::vector elements; // 输入元素描述列表 +}; +``` + +### VertexBufferBinding + +顶点缓冲区绑定信息。 + +```cpp +struct VertexBufferBinding { + uint64_t bufferLocation; // 缓冲区 GPU 地址 + uint32_t sizeInBytes; // 缓冲区大小 + uint32_t strideInBytes; // 顶点 stride +}; +``` + +## 资源和描述符 + +### TextureCopyLocation + +纹理复制位置，用于纹理复制操作。 + +```cpp +struct TextureCopyLocation { + uint64_t plSubresourceIndex; // 子资源索引 + void* pResource; // 资源指针 +}; +``` + +### DescriptorHandle + +通用描述符句柄。 + +```cpp +struct DescriptorHandle { + uint64_t ptr; // 描述符指针 +}; +``` + +### GPUDescriptorHandle + +GPU 描述符句柄。 + +```cpp +struct GPUDescriptorHandle { + uint64_t ptr; // GPU 描述符指针 +}; +``` + +### CPUDescriptorHandle + +CPU 描述符句柄。 + +```cpp +struct CPUDescriptorHandle { + uint64_t ptr; // CPU 描述符指针 +}; +``` + +### SubresourceRange + +子资源范围，定义纹理Mip级别和数组切片范围。 + +```cpp +struct SubresourceRange { + uint32_t baseMipLevel; // 基础 Mip 级别 + uint32_t mipLevels; // Mip 级别数量 + uint32_t baseArraySlice; // 基础数组切片 + uint32_t arraySize; // 数组切片数量 +}; +``` + +### TextureDesc + +纹理描述，创建纹理资源的配置参数。 + +```cpp +struct TextureDesc { + uint32_t width; // 纹理宽度 + uint32_t height; // 纹理高度 + uint32_t depth; // 纹理深度 (3D 纹理) + uint32_t mipLevels; // Mip 级别数量 + uint32_t arraySize; // 数组纹理元素数量 + uint32_t format; // 纹理格式 (参见 Format 枚举) + uint32_t textureType; // 纹理类型 (参见 TextureType 枚举) + uint32_t sampleCount; // 多重采样数 + uint32_t sampleQuality; // 采样质量等级 + uint64_t flags; // 纹理标志 +}; +``` + +### BufferDesc + +缓冲区描述，创建缓冲区资源的配置参数。 + +```cpp +struct BufferDesc { + uint64_t size; // 缓冲区大小 (字节) + uint32_t stride; // 元素 stride (用于顶点/索引缓冲区) + uint32_t bufferType; // 缓冲区类型 (参见 BufferType 枚举) + uint64_t flags; // 缓冲区标志 +}; +``` + +### RenderTargetDesc + +渲染目标描述。 + +```cpp +struct RenderTargetDesc { + uint32_t width; // 渲染目标宽度 + uint32_t height; // 渲染目标高度 + uint32_t format; // 渲染目标格式 (参见 Format 枚举) + uint32_t sampleCount; // 多重采样数 + uint32_t sampleQuality; // 采样质量等级 +}; +``` + +### DepthStencilDesc + +深度模板描述。 + +```cpp +struct DepthStencilDesc { + uint32_t width; // 宽度 + uint32_t height; // 高度 + uint32_t format; // 格式 (参见 Format 枚举) + uint32_t sampleCount; // 多重采样数 + uint32_t sampleQuality; // 采样质量等级 + bool depthEnable; // 是否启用深度测试 + bool stencilEnable; // 是否启用模板测试 +}; +``` + +### DescriptorHeapDesc + +描述符堆描述。 + +```cpp +struct DescriptorHeapDesc { + uint32_t descriptorCount; // 描述符数量 + uint32_t heapType; // 堆类型 (参见 DescriptorHeapType 枚举) + uint32_t flags; // 堆标志 + uint32_t nodeMask; // 节点掩码 (多适配器) +}; +``` + +### RenderTargetViewDesc + +渲染目标视图描述。 + +```cpp +struct RenderTargetViewDesc { + uint32_t format; // 视图格式 + uint32_t viewDimension; // 视图维度 + uint32_t mipSlice; // Mip 级别 + uint32_t firstArraySlice; // 首个数组切片 + uint32_t arraySize; // 数组切片数量 +}; +``` + +### DepthStencilViewDesc + +深度模板视图描述。 + +```cpp +struct DepthStencilViewDesc { + uint32_t format; // 视图格式 + uint32_t viewDimension; // 视图维度 + uint32_t mipSlice; // Mip 级别 + uint32_t firstArraySlice; // 首个数组切片 + uint32_t arraySize; // 数组切片数量 +}; +``` + +### ShaderResourceViewDesc + +着色器资源视图描述。 + +```cpp +struct ShaderResourceViewDesc { + uint32_t format; // 视图格式 + uint32_t viewDimension; // 视图维度 + uint32_t shader4ComponentMapping; // 组件映射 + TextureDesc textureDesc; // 关联的纹理描述 +}; +``` + +### ConstantBufferViewDesc + +常量缓冲区视图描述。 + +```cpp +struct ConstantBufferViewDesc { + uint64_t bufferLocation; // 缓冲区 GPU 地址 + uint32_t sizeInBytes; // 视图大小 +}; +``` + +### UnorderedAccessViewDesc + +无序访问视图描述。 + +```cpp +struct UnorderedAccessViewDesc { + uint32_t format; // 视图格式 + uint32_t viewDimension; // 视图维度 + uint32_t mipSlice; // Mip 级别 + uint32_t firstArraySlice; // 首个数组切片 + uint32_t arraySize; // 数组切片数量 +}; +``` + +### RootSignatureDesc + +根签名描述。 + +```cpp +struct RootSignatureDesc { + const void* pBlob; // 根签名二进制数据 + uint32_t size; // 数据大小 +}; +``` + +### PipelineStateDesc + +管线状态描述。 + +```cpp +struct PipelineStateDesc { + const void* pBlob; // 管线状态二进制数据 + uint32_t size; // 数据大小 +}; +``` + +## 命令相关 + +### CommandQueueDesc + +命令队列描述。 + +```cpp +struct CommandQueueDesc { + uint32_t queueType; // 队列类型 (参见 CommandQueueType 枚举) + uint32_t priority; // 优先级 + uint32_t nodeMask; // 节点掩码 + uint64_t flags; // 标志 +}; +``` + +### CommandListDesc + +命令列表描述。 + +```cpp +struct CommandListDesc { + uint32_t commandListType; // 命令列表类型 + uint32_t nodeMask; // 节点掩码 +}; +``` + +### CommandAllocatorDesc + +命令分配器描述。 + +```cpp +struct CommandAllocatorDesc { + uint32_t commandListType; // 命令列表类型 +}; +``` + +### FenceDesc + +栅栏描述。 + +```cpp +struct FenceDesc { + uint64_t initialValue; // 初始值 + uint32_t flags; // 标志 +}; +``` + +### QueryHeapDesc + +查询堆描述。 + +```cpp +struct QueryHeapDesc { + uint32_t queryType; // 查询类型 (参见 QueryType 枚举) + uint32_t count; // 查询数量 + uint32_t nodeMask; // 节点掩码 +}; +``` + +### SamplerDesc + +采样器描述，配置纹理采样状态。 + +```cpp +struct SamplerDesc { + uint32_t filter; // 过滤器模式 (参见 FilterMode 枚举) + uint32_t addressU; // U 方向寻址模式 (参见 TextureAddressMode 枚举) + uint32_t addressV; // V 方向寻址模式 + uint32_t addressW; // W 方向寻址模式 + float mipLodBias; // Mip LOD 偏移 + uint32_t maxAnisotropy; // 最大各向异性级别 + uint32_t comparisonFunc; // 比较函数 (参见 ComparisonFunc 枚举) + float borderColorR; // 边框颜色 R 分量 + float borderColorG; // 边框颜色 G 分量 + float borderColorB; // 边框颜色 B 分量 + float borderColorA; // 边框颜色 A 分量 + float minLod; // 最小 LOD + float maxLod; // 最大 LOD +}; +``` + +### SwapChainDesc + +交换链描述。 + +```cpp +struct SwapChainDesc { + uint32_t width; // 交换链宽度 + uint32_t height; // 交换链高度 + uint32_t bufferCount; // 缓冲区数量 + uint32_t format; // 格式 (参见 Format 枚举) + uint32_t refreshRate; // 刷新率 + uint32_t sampleCount; // 多重采样数 + uint32_t sampleQuality; // 采样质量等级 + uint32_t swapEffect; // 交换效果 + uint32_t flags; // 标志 +}; +``` + +## 设备相关 + +### RHIDeviceDesc + +设备描述，创建 RHI 设备的配置参数。 + +```cpp +struct RHIDeviceDesc { + bool enableDebugLayer = false; // 启用调试层 + bool enableGPUValidation = false; // 启用 GPU 验证 + uint32_t adapterIndex = 0; // 适配器索引 + void* windowHandle = nullptr; // 窗口句柄 + uint32_t width = 1280; // 窗口宽度 + uint32_t height = 720; // 窗口高度 + std::wstring appName = L"XCEngine"; // 应用程序名称 +}; +``` + +**使用示例**: + +```cpp +RHIDeviceDesc desc; +desc.enableDebugLayer = true; +desc.windowHandle = hwnd; +desc.width = 1920; +desc.height = 1080; +desc.appName = L"MyGame"; +``` + +### RHIDeviceInfo + +设备信息结构体，包含设备详细信息。 + +```cpp +struct RHIDeviceInfo { + std::wstring description; // 设备描述 + std::wstring vendor; // 供应商 + std::wstring renderer; // 渲染器名称 + std::wstring version; // 驱动版本 + uint32_t majorVersion = 0; // 主版本号 + uint32_t minorVersion = 0; // 次版本号 + uint64_t dedicatedVideoMemory = 0; // 专用显存 + uint64_t dedicatedSystemMemory = 0; // 专用系统内存 + uint64_t sharedSystemMemory = 0; // 共享系统内存 + uint32_t vendorId = 0; // 供应商 ID + uint32_t deviceId = 0; // 设备 ID + bool isSoftware = false; // 是否为软件设备 +}; +``` + +### RHIRenderPassDesc + +渲染通道描述。 + +```cpp +struct RHIRenderPassDesc { + struct ColorAttachment { + void* texture = nullptr; // 纹理指针 + uint32_t loadAction = 0; // 加载操作 + uint32_t storeAction = 0; // 存储操作 + float clearColor[4] = {0.0f, 0.0f, 0.0f, 1.0f}; // 清除颜色 + }; + ColorAttachment colorAttachments[8]; // 颜色附件数组 + uint32_t colorAttachmentCount = 0; // 颜色附件数量 + + struct DepthStencilAttachment { + void* texture = nullptr; // 纹理指针 + uint32_t loadAction = 0; // 加载操作 + uint32_t storeAction = 0; // 存储操作 + float clearDepth = 1.0f; // 清除深度 + uint8_t clearStencil = 0; // 清除模板值 + } depthStencilAttachment; + bool hasDepthStencil = false; // 是否有深度模板附件 +}; +``` + +**使用示例**: + +```cpp +RHIRenderPassDesc passDesc; +passDesc.colorAttachmentCount = 1; +passDesc.colorAttachments[0].texture = renderTargetTexture; +passDesc.colorAttachments[0].loadAction = static_cast(LoadAction::Clear); +passDesc.colorAttachments[0].storeAction = static_cast(StoreAction::Store); +passDesc.hasDepthStencil = true; +passDesc.depthStencilAttachment.texture = depthStencilTexture; +``` + +### RHIPipelineLayoutDesc + +管线布局描述。 + +```cpp +struct RHIPipelineLayoutDesc { + uint32_t constantBufferCount = 0; // 常量缓冲区数量 + uint32_t textureCount = 0; // 纹理数量 + uint32_t samplerCount = 0; // 采样器数量 + uint32_t uavCount = 0; // UAV 数量 +}; +``` ## 相关文档 -- [../rhi/rhi.md](../rhi.md) - RHI 模块总览 +- [../rhi.md](../rhi.md) - RHI 模块总览 - [RHIEnums](../enums/enums.md) - 枚举类型汇总