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

docs(api): deepen D3D12 and OpenGL backend docs

Browse Source
This commit is contained in:
ssdfasd
2026-03-27 22:09:58 +08:00
parent 37a90b39e2
commit c7ef9191e4
67 changed files with 1347 additions and 1841 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
docs/api/XCEngine/RHI/D3D12/D3D12.md
View File

@@ -1,42 +1,76 @@
# D3D12 # D3D12
**命名空间**: `XCEngine::RHI::D3D12` **命名空间**: `XCEngine::RHI`
**类型**: `submodule` **类型**: `submodule`
**描述**: DirectX 12 后端 public headers。 **描述**: XCEngine 的 Direct3D 12 后端入口，负责把抽象 RHI 设备、命令、描述符、资源和交换链映射到 DXGI 与 D3D12 原生对象。
## 概览 ## 概览
该目录与 `XCEngine/RHI/D3D12` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。 `D3D12` 子模块可以理解成引擎图形后端里更接近商业引擎 `GfxDevice` / `Render Backend` 的那一层，而不是脚本层会直接操作的高层渲染 API。
## 头文件 当前目录下的类型大体分成四组：
- [D3D12Buffer](D3D12Buffer/D3D12Buffer.md) - `D3D12Buffer.h` - 设备与提交基础设施：[`D3D12Device`](D3D12Device/D3D12Device.md)、[`D3D12CommandQueue`](D3D12CommandQueue/D3D12CommandQueue.md)、[`D3D12CommandAllocator`](D3D12CommandAllocator/D3D12CommandAllocator.md)、[`D3D12CommandList`](D3D12CommandList/D3D12CommandList.md)
- [D3D12CommandAllocator](D3D12CommandAllocator/D3D12CommandAllocator.md) - `D3D12CommandAllocator.h` - 资源与视图：[`D3D12Buffer`](D3D12Buffer/D3D12Buffer.md)、[`D3D12Texture`](D3D12Texture/D3D12Texture.md)、[`D3D12ResourceView`](D3D12ResourceView/D3D12ResourceView.md)
- [D3D12CommandList](D3D12CommandList/D3D12CommandList.md) - `D3D12CommandList.h` - 管线与绑定：[`D3D12PipelineLayout`](D3D12PipelineLayout/D3D12PipelineLayout.md)、[`D3D12PipelineState`](D3D12PipelineState/D3D12PipelineState.md)、[`D3D12RootSignature`](D3D12RootSignature/D3D12RootSignature.md)、[`D3D12DescriptorHeap`](D3D12DescriptorHeap/D3D12DescriptorHeap.md)、[`D3D12DescriptorSet`](D3D12DescriptorSet/D3D12DescriptorSet.md)
- [D3D12CommandQueue](D3D12CommandQueue/D3D12CommandQueue.md) - `D3D12CommandQueue.h` - 呈现与同步：[`D3D12SwapChain`](D3D12SwapChain/D3D12SwapChain.md)、[`D3D12RenderPass`](D3D12RenderPass/D3D12RenderPass.md)、[`D3D12Framebuffer`](D3D12Framebuffer/D3D12Framebuffer.md)、[`D3D12Fence`](D3D12Fence/D3D12Fence.md)
- [D3D12Common](D3D12Common/D3D12Common.md) - `D3D12Common.h`
- [D3D12DescriptorHeap](D3D12DescriptorHeap/D3D12DescriptorHeap.md) - `D3D12DescriptorHeap.h` ## 设计要点
- [D3D12DescriptorSet](D3D12DescriptorSet/D3D12DescriptorSet.md) - `D3D12DescriptorSet.h`
- [D3D12Device](D3D12Device/D3D12Device.md) - `D3D12Device.h` - 这套后端明显偏向“显式控制、轻量工厂、调用方自行管理生命周期”的风格，而不是 Unity 那种高度托管对象模型。
- [D3D12Enums](D3D12Enums/D3D12Enums.md) - `D3D12Enums.h` - RHI 层暴露了“descriptor set / pipeline layout”这一套跨后端抽象，但在 D3D12 中真正落地的是 root signature、descriptor heap 和 root parameter 映射。
- [D3D12Fence](D3D12Fence/D3D12Fence.md) - `D3D12Fence.h` - 代码把“先打通统一语义”放在更高优先级，因此部分实现是简化版。例如队列空闲等待、常量缓冲上传、资源状态跟踪都先覆盖主路径，再逐步补足更成熟的工程策略。
- [D3D12Framebuffer](D3D12Framebuffer/D3D12Framebuffer.md) - `D3D12Framebuffer.h`
- [D3D12PipelineLayout](D3D12PipelineLayout/D3D12PipelineLayout.md) - `D3D12PipelineLayout.h` ## 当前实现边界
- [D3D12PipelineState](D3D12PipelineState/D3D12PipelineState.md) - `D3D12PipelineState.h`
- [D3D12QueryHeap](D3D12QueryHeap/D3D12QueryHeap.md) - `D3D12QueryHeap.h` - 平台路径是 Windows + DXGI + D3D12。
- [D3D12RenderPass](D3D12RenderPass/D3D12RenderPass.md) - `D3D12RenderPass.h` - 设备初始化会从 `adapterIndex` 开始枚举适配器，跳过软件适配器，选择第一个能创建 `D3D_FEATURE_LEVEL_11_0` 设备的硬件适配器。
- [D3D12ResourceView](D3D12ResourceView/D3D12ResourceView.md) - `D3D12ResourceView.h` - `D3D12CommandQueue`、`D3D12CommandList`、`D3D12DescriptorSet` 已经形成了可跑通的核心路径，但仍存在一些明显的占位或简化实现。
- [D3D12RootSignature](D3D12RootSignature/D3D12RootSignature.md) - `D3D12RootSignature.h` - 若你熟悉 Unity，可以把这里理解成“比 SRP backend 更低一层”的运行时封装；它强调可组合性和后端细节可见性，而不是隐藏 D3D12 的显式同步和绑定成本。
- [D3D12Sampler](D3D12Sampler/D3D12Sampler.md) - `D3D12Sampler.h`
- [D3D12Screenshot](D3D12Screenshot/D3D12Screenshot.md) - `D3D12Screenshot.h` ## 推荐阅读顺序
- [D3D12Shader](D3D12Shader/D3D12Shader.md) - `D3D12Shader.h`
- [D3D12SwapChain](D3D12SwapChain/D3D12SwapChain.md) - `D3D12SwapChain.h` 1. [D3D12Device](D3D12Device/D3D12Device.md)
- [D3D12Texture](D3D12Texture/D3D12Texture.md) - `D3D12Texture.h` 2. [D3D12CommandQueue](D3D12CommandQueue/D3D12CommandQueue.md)
- [D3D12Types](D3D12Types/D3D12Types.md) - `D3D12Types.h` 3. [D3D12CommandList](D3D12CommandList/D3D12CommandList.md)
4. [D3D12PipelineLayout](D3D12PipelineLayout/D3D12PipelineLayout.md)
5. [D3D12DescriptorSet](D3D12DescriptorSet/D3D12DescriptorSet.md)
## 与测试的对应关系
- `tests/RHI/D3D12/unit/` 直接验证 D3D12 后端实现细节。
- `tests/RHI/unit/test_device.cpp`、`tests/RHI/unit/test_descriptor_set.cpp`、`tests/RHI/unit/test_pipeline_layout.cpp` 会通过抽象层接口回归统一语义。
- `tests/RHI/D3D12/integration/` 与 `tests/Rendering/integration/*` 负责覆盖真正的提交、呈现与截图链路。
## 头文件索引
- [D3D12Buffer](D3D12Buffer/D3D12Buffer.md)
- [D3D12CommandAllocator](D3D12CommandAllocator/D3D12CommandAllocator.md)
- [D3D12CommandList](D3D12CommandList/D3D12CommandList.md)
- [D3D12CommandQueue](D3D12CommandQueue/D3D12CommandQueue.md)
- [D3D12Common](D3D12Common/D3D12Common.md)
- [D3D12DescriptorHeap](D3D12DescriptorHeap/D3D12DescriptorHeap.md)
- [D3D12DescriptorSet](D3D12DescriptorSet/D3D12DescriptorSet.md)
- [D3D12Device](D3D12Device/D3D12Device.md)
- [D3D12Enums](D3D12Enums/D3D12Enums.md)
- [D3D12Fence](D3D12Fence/D3D12Fence.md)
- [D3D12Framebuffer](D3D12Framebuffer/D3D12Framebuffer.md)
- [D3D12PipelineLayout](D3D12PipelineLayout/D3D12PipelineLayout.md)
- [D3D12PipelineState](D3D12PipelineState/D3D12PipelineState.md)
- [D3D12QueryHeap](D3D12QueryHeap/D3D12QueryHeap.md)
- [D3D12RenderPass](D3D12RenderPass/D3D12RenderPass.md)
- [D3D12ResourceView](D3D12ResourceView/D3D12ResourceView.md)
- [D3D12RootSignature](D3D12RootSignature/D3D12RootSignature.md)
- [D3D12Sampler](D3D12Sampler/D3D12Sampler.md)
- [D3D12Screenshot](D3D12Screenshot/D3D12Screenshot.md)
- [D3D12Shader](D3D12Shader/D3D12Shader.md)
- [D3D12SwapChain](D3D12SwapChain/D3D12SwapChain.md)
- [D3D12Texture](D3D12Texture/D3D12Texture.md)
- [D3D12Types](D3D12Types/D3D12Types.md)
## 相关文档 ## 相关文档
- [上级目录](../RHI.md) - [RHI](../RHI.md)
- [API 总索引](../../../main.md) - [Devices, Queues, Command Lists, And Resource Creation](../../../_guides/RHI/Devices-Queues-CommandLists-And-Resource-Creation.md)

41
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/BeginRenderPass.md
View File

@@ -1,35 +1,32 @@
# D3D12CommandList::BeginRenderPass # D3D12CommandList::BeginRenderPass
公开方法，详见头文件声明。
```cpp ```cpp
void BeginRenderPass(class RHIRenderPass* renderPass, class RHIFramebuffer* framebuffer, const Rect& renderArea, uint32_t clearValueCount, const ClearValue* clearValues) override; void BeginRenderPass(RHIRenderPass* renderPass, RHIFramebuffer* framebuffer, const Rect& renderArea, uint32_t clearValueCount, const ClearValue* clearValues) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 根据 render pass 描述和 framebuffer 句柄设置视口、裁剪区、清屏策略和输出目标。
- `renderPass` - 参数语义详见头文件声明。
- `framebuffer` - 参数语义详见头文件声明。
- `renderArea` - 参数语义详见头文件声明。
- `clearValueCount` - 参数语义详见头文件声明。
- `clearValues` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 前置条件
**示例：** - `renderPass` 与 `framebuffer` 都必须有效
```cpp ## 当前实现行为
#include <XCEngine/RHI/D3D12/D3D12CommandList.h>
void Example() { - 根据 `renderArea` 设置一组 viewport 和 scissor
XCEngine::RHI::D3D12CommandList object; - 从 `D3D12Framebuffer` 取出颜色附件句柄和深度句柄
// 根据上下文补齐参数后调用 D3D12CommandList::BeginRenderPass(...)。 - 从 `D3D12RenderPass` 读取 load action
(void)object; - 对 `LoadAction::Clear` 的颜色附件执行 `ClearRenderTargetView`
} - 若深度/模板附件配置为 clear，则执行 `ClearDepthStencilView`
``` - 最后调用 `OMSetRenderTargets(...)`
- 同时缓存当前绑定的 RT / DS handle，供 [`Clear`](Clear.md) 使用
## 当前限制
这条实现更接近“render pass 语义翻译层”，而不是利用 D3D12 enhanced barrier / native render pass 的完整高级路径。
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [SetRenderTargets](SetRenderTargets.md)
- [返回模块目录](../D3D12.md) - [Clear](Clear.md)

33
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Clear.md
View File

@@ -1,35 +1,26 @@
# D3D12CommandList::Clear # D3D12CommandList::Clear
清空内部数据。
```cpp ```cpp
void Clear(float r, float g, float b, float a, uint32_t buffers) override; void Clear(float r, float g, float b, float a, uint32_t buffers) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 对当前已绑定的颜色/深度/模板输出目标执行清屏。
- `r` - 参数语义详见头文件声明。
- `g` - 参数语义详见头文件声明。
- `b` - 参数语义详见头文件声明。
- `a` - 参数语义详见头文件声明。
- `buffers` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 若 `buffers & 1`，遍历当前缓存的 render target handle 并清颜色
- 若 `buffers & 2` 或 `buffers & 4`，且当前存在深度模板目标：
- 组装 `D3D12_CLEAR_FLAG_DEPTH`
- 组装 `D3D12_CLEAR_FLAG_STENCIL`
- 对缓存的深度模板 handle 清屏
```cpp ## 注意事项
#include <XCEngine/RHI/D3D12/D3D12CommandList.h>
void Example() { 这条方法依赖此前已经通过 [`BeginRenderPass`](BeginRenderPass.md) 或 [`SetRenderTargets`](SetRenderTargets.md) 建立了当前绑定目标。
XCEngine::RHI::D3D12CommandList object;
// 根据上下文补齐参数后调用 D3D12CommandList::Clear(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [BeginRenderPass](BeginRenderPass.md)
- [返回模块目录](../D3D12.md) - [SetRenderTargets](SetRenderTargets.md)

29
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyResource.md
View File

@@ -1,32 +1,25 @@
# D3D12CommandList::CopyResource # D3D12CommandList::CopyResource
公开方法，详见头文件声明。
```cpp ```cpp
void CopyResource(RHIResourceView* dst, RHIResourceView* src) override; void CopyResource(RHIResourceView* dst, RHIResourceView* src) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 对两个资源 view 底层指向的 D3D12 资源执行整资源复制。
- `dst` - 参数语义详见头文件声明。
- `src` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 要求 `dst`、`src` 都有效
- 将二者转成 `D3D12ResourceView`
- 取出底层 `ID3D12Resource*`
- 调用 `ID3D12GraphicsCommandList::CopyResource(...)`
```cpp ## 注意事项
#include <XCEngine/RHI/D3D12/D3D12CommandList.h>
void Example() { 这条路径不会自动插入资源状态转换；调用方应自行在复制前后安排合适的 barrier。
XCEngine::RHI::D3D12CommandList object;
// 根据上下文补齐参数后调用 D3D12CommandList::CopyResource(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [TransitionBarrier](TransitionBarrier.md)
- [返回模块目录](../D3D12.md) - [SetRenderTargets](SetRenderTargets.md)

157
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/D3D12CommandList.md
View File

@@ -6,96 +6,85 @@
**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` **头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h`
**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12CommandList` public API。 **描述**: D3D12 后端的图形/计算命令列表封装，负责记录 barrier、render pass、管线绑定、描述符绑定、绘制与 dispatch。
## 概述 ## 概览
`D3D12CommandList.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `D3D12CommandList` 对应一条真实的 `ID3D12GraphicsCommandList`。它不是高层 render graph，也不是自动同步系统，而是更接近“backend recorder”的薄层实现。
## 声明概览 这类类型在商业引擎里通常承担两件事：
| 声明 | 类型 | 说明 | - 把抽象 RHI 命令翻译成 D3D12 调用
|------|------|------| - 在不引入太多调度系统复杂度的前提下，补一层最基本的状态缓存和参数装配
| `D3D12CommandList` | `class` | 继承自 `RHICommandList` 的公开声明。 |
## 公共方法 ## 生命周期
| 方法 | 描述 | - `Initialize()` 需要外部设备和 command allocator
|------|------| - `Reset()` 重新开始录制，并清空软件侧状态缓存
| [D3D12CommandList()](Constructor.md) | 构造对象。 | - `Close()` 结束录制
| [~D3D12CommandList()](Destructor.md) | 销毁对象并释放相关资源。 | - 提交由 [`D3D12CommandQueue`](../D3D12CommandQueue/D3D12CommandQueue.md) 完成
| [Initialize](Initialize.md) | 初始化内部状态。 |
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | ## 当前实现的真实行为
| [Reset](Reset.md) | 公开方法，详见头文件声明。 |
| [Close](Close.md) | 公开方法，详见头文件声明。 | ### 资源状态与 barrier
| [GetCommandList](GetCommandList.md) | 获取相关状态或对象。 |
| [SetShader](SetShader.md) | 设置相关状态或配置。 | - [`TransitionBarrier`](TransitionBarrier.md) 会直接发出 `ResourceBarrier`
| [TransitionBarrier](TransitionBarrier.md) | 公开方法，详见头文件声明。 | - 同时把 `stateAfter` 记入 `m_resourceStateMap`
| [TransitionBarrierInternal](TransitionBarrierInternal.md) | 公开方法，详见头文件声明。 | - 这份状态表只是本命令列表内的软跟踪，不等同于跨队列、跨帧的全局真值
| [UAVBarrier](UAVBarrier.md) | 公开方法，详见头文件声明。 |
| [UAVBarrierInternal](UAVBarrierInternal.md) | 公开方法，详见头文件声明。 | ### 管线与描述符绑定
| [AliasBarrier](AliasBarrier.md) | 公开方法，详见头文件声明。 |
| [AliasBarrierInternal](AliasBarrierInternal.md) | 公开方法，详见头文件声明。 | - [`SetPipelineState`](SetPipelineState.md) 会先调用 `EnsureValid()`
| [BeginRenderPass](BeginRenderPass.md) | 公开方法，详见头文件声明。 | - Graphics 路径依赖 graphics PSO 和 graphics root signature
| [EndRenderPass](EndRenderPass.md) | 公开方法，详见头文件声明。 | - Compute 路径会改走 `SetComputeRootSignature()` 和 compute pipeline state
| [SetPipelineState](SetPipelineState.md) | 设置相关状态或配置。 | - [`SetGraphicsDescriptorSets`](SetGraphicsDescriptorSets.md) / [`SetComputeDescriptorSets`](SetComputeDescriptorSets.md) 会根据 `D3D12PipelineLayout` 的映射，把 CBV 写到 root CBV，把 SRV/UAV/Sampler 绑定到 descriptor table
| [SetPipelineStateInternal](SetPipelineStateInternal.md) | 设置相关状态或配置。 |
| [SetPipelineLayout](SetPipelineLayout.md) | 设置相关状态或配置。 | ### Render pass 与输出目标
| [SetRootSignature](SetRootSignature.md) | 设置相关状态或配置。 |
| [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md) | 设置相关状态或配置。 | - [`BeginRenderPass`](BeginRenderPass.md) 当前更像“根据 `D3D12RenderPass` 描述执行清屏并调用 `OMSetRenderTargets`”
| [SetComputeDescriptorSets](SetComputeDescriptorSets.md) | 设置相关状态或配置。 | - `EndRenderPass()` 目前是空实现，不会生成额外 D3D12 结束命令
| [SetViewport](SetViewport.md) | 设置相关状态或配置。 | - [`SetRenderTargets`](SetRenderTargets.md) 直接消费传入的 `D3D12ResourceView` CPU handle
| [SetViewports](SetViewports.md) | 设置相关状态或配置。 |
| [SetScissorRect](SetScissorRect.md) | 设置相关状态或配置。 | ### 绘制与计算
| [SetScissorRects](SetScissorRects.md) | 设置相关状态或配置。 |
| [SetPrimitiveTopology](SetPrimitiveTopology.md) | 设置相关状态或配置。 | - [`Draw`](Draw.md) / [`DrawIndexed`](DrawIndexed.md) 直接转发到 `DrawInstanced` / `DrawIndexedInstanced`
| [SetRenderTargets](SetRenderTargets.md) | 设置相关状态或配置。 | - [`Dispatch`](Dispatch.md) 直接转发到 `ID3D12GraphicsCommandList::Dispatch`
| [SetRenderTargetsInternal](SetRenderTargetsInternal.md) | 设置相关状态或配置。 | - 间接绘制/间接 dispatch 相关内部接口当前调用 `ExecuteIndirect(nullptr, ...)`，说明这条能力还处在占位或未完工状态
| [SetRenderTargetsHandle](SetRenderTargetsHandle.md) | 设置相关状态或配置。 |
| [SetVertexBuffers](SetVertexBuffers.md) | 设置相关状态或配置。 | ## 值得注意的限制
| [SetVertexBuffersInternal](SetVertexBuffersInternal.md) | 设置相关状态或配置。 |
| [SetVertexBuffer](SetVertexBuffer.md) | 设置相关状态或配置。 | - `SetDepthBias()` 目前为空实现
| [SetIndexBuffer](SetIndexBuffer.md) | 设置相关状态或配置。 | - `EndRenderPass()` 目前为空实现
| [SetIndexBufferInternal](SetIndexBufferInternal.md) | 设置相关状态或配置。 | - `ClearDepthStencilView(ID3D12Resource* ...)` 这一重载内部构造的是空 DSV handle，实用路径应优先走 view/handle 版本
| [SetDescriptorHeap](SetDescriptorHeap.md) | 设置相关状态或配置。 | - `SetRenderTargetsInternal()` 传入的是空 descriptor handle 数组，属于低层占位接口，不应视为成熟主路径
| [SetDescriptorHeaps](SetDescriptorHeaps.md) | 设置相关状态或配置。 |
| [SetGraphicsDescriptorTable](SetGraphicsDescriptorTable.md) | 设置相关状态或配置。 | ## 线程语义
| [SetComputeDescriptorTable](SetComputeDescriptorTable.md) | 设置相关状态或配置。 |
| [SetGraphicsRootConstantBufferView](SetGraphicsRootConstantBufferView.md) | 设置相关状态或配置。 | 命令列表对象没有显式并发保护。建议把它视为：
| [SetGraphicsRoot32BitConstants](SetGraphicsRoot32BitConstants.md) | 设置相关状态或配置。 |
| [SetGraphicsRootDescriptorTable](SetGraphicsRootDescriptorTable.md) | 设置相关状态或配置。 | - 单线程录制对象
| [SetGraphicsRootShaderResourceView](SetGraphicsRootShaderResourceView.md) | 设置相关状态或配置。 | - 一次只由一个提交上下文持有和驱动
| [SetStencilRef](SetStencilRef.md) | 设置相关状态或配置。 |
| [SetBlendFactor](SetBlendFactor.md) | 设置相关状态或配置。 | ## 重点公共方法
| [SetDepthBias](SetDepthBias.md) | 设置相关状态或配置。 |
| [Draw](Draw.md) | 公开方法，详见头文件声明。 | - [TransitionBarrier](TransitionBarrier.md)
| [DrawIndexed](DrawIndexed.md) | 公开方法，详见头文件声明。 | - [BeginRenderPass](BeginRenderPass.md)
| [DrawInstancedIndirect](DrawInstancedIndirect.md) | 公开方法，详见头文件声明。 | - [SetPipelineState](SetPipelineState.md)
| [DrawInstancedIndirectInternal](DrawInstancedIndirectInternal.md) | 公开方法，详见头文件声明。 | - [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md)
| [DrawIndexedInstancedIndirect](DrawIndexedInstancedIndirect.md) | 公开方法，详见头文件声明。 | - [SetComputeDescriptorSets](SetComputeDescriptorSets.md)
| [DrawIndexedInstancedIndirectInternal](DrawIndexedInstancedIndirectInternal.md) | 公开方法，详见头文件声明。 | - [SetRenderTargets](SetRenderTargets.md)
| [Clear](Clear.md) | 清空内部数据。 | - [SetVertexBuffers](SetVertexBuffers.md)
| [ClearRenderTarget](ClearRenderTarget.md) | 清空内部数据。 | - [SetIndexBuffer](SetIndexBuffer.md)
| [ClearRenderTargetView](ClearRenderTargetView.md) | 清空内部数据。 | - [Clear](Clear.md)
| [ClearDepthStencil](ClearDepthStencil.md) | 清空内部数据。 | - [CopyResource](CopyResource.md)
| [ClearDepthStencilView](ClearDepthStencilView.md) | 清空内部数据。 | - [Draw](Draw.md)
| [ClearUnorderedAccessView](ClearUnorderedAccessView.md) | 清空内部数据。 | - [DrawIndexed](DrawIndexed.md)
| [CopyResource](CopyResource.md) | 公开方法，详见头文件声明。 | - [Dispatch](Dispatch.md)
| [CopyResourceInternal](CopyResourceInternal.md) | 公开方法，详见头文件声明。 |
| [CopyBuffer](CopyBuffer.md) | 公开方法，详见头文件声明。 |
| [CopyTexture](CopyTexture.md) | 公开方法，详见头文件声明。 |
| [BeginQuery](BeginQuery.md) | 公开方法，详见头文件声明。 |
| [EndQuery](EndQuery.md) | 公开方法，详见头文件声明。 |
| [ResolveQueryData](ResolveQueryData.md) | 解析并返回目标结果。 |
| [Dispatch](Dispatch.md) | 公开方法，详见头文件声明。 |
| [DispatchIndirect](DispatchIndirect.md) | 公开方法，详见头文件声明。 |
| [DispatchIndirectInternal](DispatchIndirectInternal.md) | 公开方法，详见头文件声明。 |
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
| [ExecuteBundle](ExecuteBundle.md) | 公开方法，详见头文件声明。 |
| [GetResourceState](GetResourceState.md) | 获取相关状态或对象。 |
| [TrackResource](TrackResource.md) | 公开方法，详见头文件声明。 |
## 相关文档 ## 相关文档
- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录 - [D3D12](../D3D12.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [D3D12Device](../D3D12Device/D3D12Device.md)
- [D3D12CommandQueue](../D3D12CommandQueue/D3D12CommandQueue.md)
- [D3D12DescriptorSet](../D3D12DescriptorSet/D3D12DescriptorSet.md)
- [D3D12PipelineLayout](../D3D12PipelineLayout/D3D12PipelineLayout.md)

28
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Dispatch.md
View File

@@ -1,33 +1,23 @@
# D3D12CommandList::Dispatch # D3D12CommandList::Dispatch
公开方法，详见头文件声明。
```cpp ```cpp
void Dispatch(uint32_t x, uint32_t y, uint32_t z) override; void Dispatch(uint32_t x, uint32_t y, uint32_t z) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 发出一次 compute dispatch。
- `x` - 参数语义详见头文件声明。
- `y` - 参数语义详见头文件声明。
- `z` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** 直接调用 `ID3D12GraphicsCommandList::Dispatch(...)`。
```cpp ## 前置条件
#include <XCEngine/RHI/D3D12/D3D12CommandList.h>
void Example() { - 已经绑定有效的 compute pipeline state
XCEngine::RHI::D3D12CommandList object; - 已经通过 [`SetComputeDescriptorSets`](SetComputeDescriptorSets.md) 或其他 compute 根参数接口配置好资源
// 根据上下文补齐参数后调用 D3D12CommandList::Dispatch(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [SetComputeDescriptorSets](SetComputeDescriptorSets.md)
- [返回模块目录](../D3D12.md) - [SetPipelineState](SetPipelineState.md)

28
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Draw.md
View File

@@ -1,34 +1,22 @@
# D3D12CommandList::Draw # D3D12CommandList::Draw
公开方法，详见头文件声明。
```cpp ```cpp
void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0) override; void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 发出一次非索引绘制。
- `vertexCount` - 参数语义详见头文件声明。
- `instanceCount` - 参数语义详见头文件声明。
- `startVertex` - 参数语义详见头文件声明。
- `startInstance` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** 直接调用 `ID3D12GraphicsCommandList::DrawInstanced(...)`。
```cpp ## 前置条件
#include <XCEngine/RHI/D3D12/D3D12CommandList.h>
void Example() { - 顶点缓冲、拓扑、PSO、root signature 等图形状态已由调用方提前配置
XCEngine::RHI::D3D12CommandList object;
// 根据上下文补齐参数后调用 D3D12CommandList::Draw(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [SetVertexBuffers](SetVertexBuffers.md)
- [返回模块目录](../D3D12.md) - [SetPipelineState](SetPipelineState.md)

30
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexed.md
View File

@@ -1,35 +1,23 @@
# D3D12CommandList::DrawIndexed # D3D12CommandList::DrawIndexed
公开方法，详见头文件声明。
```cpp ```cpp
void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0) override; void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 发出一次索引绘制。
- `indexCount` - 参数语义详见头文件声明。
- `instanceCount` - 参数语义详见头文件声明。
- `startIndex` - 参数语义详见头文件声明。
- `baseVertex` - 参数语义详见头文件声明。
- `startInstance` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** 直接调用 `ID3D12GraphicsCommandList::DrawIndexedInstanced(...)`。
```cpp ## 前置条件
#include <XCEngine/RHI/D3D12/D3D12CommandList.h>
void Example() { - 已经通过 [`SetIndexBuffer`](SetIndexBuffer.md) 绑定索引缓冲
XCEngine::RHI::D3D12CommandList object; - 图形管线状态已配置完成
// 根据上下文补齐参数后调用 D3D12CommandList::DrawIndexed(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [SetIndexBuffer](SetIndexBuffer.md)
- [返回模块目录](../D3D12.md) - [Draw](Draw.md)

34
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetComputeDescriptorSets.md
View File

@@ -1,34 +1,22 @@
# D3D12CommandList::SetComputeDescriptorSets # D3D12CommandList::SetComputeDescriptorSets
设置相关状态或配置。
```cpp ```cpp
void SetComputeDescriptorSets( uint32_t firstSet, uint32_t count, RHIDescriptorSet** descriptorSets, RHIPipelineLayout* pipelineLayout) override; void SetComputeDescriptorSets(uint32_t firstSet, uint32_t count, RHIDescriptorSet** descriptorSets, RHIPipelineLayout* pipelineLayout) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把一组 descriptor set 绑定到 compute bind point。
- `firstSet` - 参数语义详见头文件声明。
- `count` - 参数语义详见头文件声明。
- `descriptorSets` - 参数语义详见头文件声明。
- `pipelineLayout` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 流程与 [`SetGraphicsDescriptorSets`](SetGraphicsDescriptorSets.md) 基本一致
- 区别在于：
```cpp - 会显式调用 `SetComputeRootSignature(...)`
#include <XCEngine/RHI/D3D12/D3D12CommandList.h> - `CBV` 绑定使用 `SetComputeRootConstantBufferView(...)`
- SRV/UAV/Sampler descriptor table 绑定使用 compute 版本接口
void Example() {
XCEngine::RHI::D3D12CommandList object;
// 根据上下文补齐参数后调用 D3D12CommandList::SetComputeDescriptorSets(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md)
- [返回模块目录](../D3D12.md) - [Dispatch](Dispatch.md)

45
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsDescriptorSets.md
View File

@@ -1,34 +1,37 @@
# D3D12CommandList::SetGraphicsDescriptorSets # D3D12CommandList::SetGraphicsDescriptorSets
设置相关状态或配置。
```cpp ```cpp
void SetGraphicsDescriptorSets( uint32_t firstSet, uint32_t count, RHIDescriptorSet** descriptorSets, RHIPipelineLayout* pipelineLayout) override; void SetGraphicsDescriptorSets(uint32_t firstSet, uint32_t count, RHIDescriptorSet** descriptorSets, RHIPipelineLayout* pipelineLayout) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把一组 descriptor set 绑定到 graphics bind point。
- `firstSet` - 参数语义详见头文件声明。
- `count` - 参数语义详见头文件声明。
- `descriptorSets` - 参数语义详见头文件声明。
- `pipelineLayout` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 前置条件
**示例：** - `pipelineLayout != nullptr`
- `descriptorSets != nullptr`
```cpp ## 当前实现行为
#include <XCEngine/RHI/D3D12/D3D12CommandList.h>
void Example() { - 把 `pipelineLayout` 转成 `D3D12PipelineLayout`
XCEngine::RHI::D3D12CommandList object; - 若 set 所在 heap 是 shader-visible 且包含 SRV/UAV/Sampler 绑定，则先收集并设置 descriptor heaps
// 根据上下文补齐参数后调用 D3D12CommandList::SetGraphicsDescriptorSets(...)。 - 对每个 set：
(void)object; - 遍历所有 binding
} - 若 binding 是 `CBV`，且 pipeline layout 存在对应 root parameter，就触发 `UploadConstantBuffer(...)`，并设置 graphics root CBV
``` - 若 heap 类型是 `CBV_SRV_UAV`，则把第一个 SRV / UAV binding 对应的 GPU handle 绑定到对应 descriptor table
- 若 heap 类型是 `Sampler`，则把 sampler table 绑定到相应 root parameter
## 设计说明
这条路径体现了当前引擎对 D3D12 绑定模型的核心适配逻辑：
- `CBV` 走 root parameter
- `SRV/UAV/Sampler` 走 shader-visible descriptor heap + descriptor table
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [SetComputeDescriptorSets](SetComputeDescriptorSets.md)
- [返回模块目录](../D3D12.md) - [D3D12DescriptorSet](../D3D12DescriptorSet/D3D12DescriptorSet.md)
- [D3D12PipelineLayout](../D3D12PipelineLayout/D3D12PipelineLayout.md)

42
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetIndexBuffer.md
View File

@@ -1,47 +1,21 @@
# D3D12CommandList::SetIndexBuffer # D3D12CommandList::SetIndexBuffer
设置相关状态或配置。
该方法在 `XCEngine/RHI/D3D12/D3D12CommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
void SetIndexBuffer(RHIResourceView* buffer, uint64_t offset) override; void SetIndexBuffer(RHIResourceView* buffer, uint64_t offset) override;
```
**参数：**
- `buffer` - 参数语义详见头文件声明。
- `offset` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
## 重载 2: 声明
```cpp
void SetIndexBuffer(ID3D12Resource* buffer, uint64_t offset, Format format); void SetIndexBuffer(ID3D12Resource* buffer, uint64_t offset, Format format);
``` ```
**参数：** ## 作用
- `buffer` - 参数语义详见头文件声明。
- `offset` - 参数语义详见头文件声明。
- `format` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 绑定索引缓冲。
**示例：** ## 当前实现行为
```cpp - `RHIResourceView*` 重载会从 view 读取底层资源、buffer offset 和 format
#include <XCEngine/RHI/D3D12/D3D12CommandList.h> - 若 format 为 `Unknown`，当前实现回退为 `Format::R32_UInt`
- 最终组装 `D3D12_INDEX_BUFFER_VIEW` 并调用 `IASetIndexBuffer(...)`
void Example() {
XCEngine::RHI::D3D12CommandList object;
// 根据上下文补齐参数后调用 D3D12CommandList::SetIndexBuffer(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [SetVertexBuffers](SetVertexBuffers.md)
- [返回模块目录](../D3D12.md) - [DrawIndexed](DrawIndexed.md)

47
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineState.md
View File

@@ -1,44 +1,31 @@
# D3D12CommandList::SetPipelineState # D3D12CommandList::SetPipelineState
设置相关状态或配置。
该方法在 `XCEngine/RHI/D3D12/D3D12CommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
void SetPipelineState(RHIPipelineState* pso) override; void SetPipelineState(RHIPipelineState* pso) override;
```
**参数：**
- `pso` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
## 重载 2: 声明
```cpp
void SetPipelineState(ID3D12PipelineState* pso); void SetPipelineState(ID3D12PipelineState* pso);
``` ```
**参数：** ## 作用
- `pso` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 绑定图形或计算管线状态对象。
**示例：** ## 当前实现行为
```cpp - 若 `pso == nullptr`，直接返回
#include <XCEngine/RHI/D3D12/D3D12CommandList.h> - 会先调用 `pso->EnsureValid()`
- 计算管线路径：
- 读取 compute root signature 和 compute pipeline state
- 调用 `SetComputeRootSignature(...)`
- 调用 `SetPipelineState(...)`
- 图形管线路径：
- 若 PSO 自带 root signature，则先设为当前 graphics root signature
- 再取 native `ID3D12PipelineState*` 绑定
void Example() { ## 注意事项
XCEngine::RHI::D3D12CommandList object;
// 根据上下文补齐参数后调用 D3D12CommandList::SetPipelineState(...)。 图形和计算路径的根签名绑定方式不同，不能简单把它理解成“只是设置一个 PSO 指针”。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md)
- [返回模块目录](../D3D12.md) - [SetComputeDescriptorSets](SetComputeDescriptorSets.md)

30
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargets.md
View File

@@ -1,33 +1,25 @@
# D3D12CommandList::SetRenderTargets # D3D12CommandList::SetRenderTargets
设置相关状态或配置。
```cpp ```cpp
void SetRenderTargets(uint32_t count, RHIResourceView** renderTargets, RHIResourceView* depthStencil = nullptr) override; void SetRenderTargets(uint32_t count, RHIResourceView** renderTargets, RHIResourceView* depthStencil = nullptr) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 绑定颜色输出目标和可选深度模板目标。
- `count` - 参数语义详见头文件声明。
- `renderTargets` - 参数语义详见头文件声明。
- `depthStencil` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 把每个 `RHIResourceView` 转成 `D3D12ResourceView`
- 从 view 中取出 CPU descriptor handle
- 调用 `OMSetRenderTargets(...)`
- 把当前绑定的 RT / DS handle 缓存到成员变量中
```cpp ## 为什么要缓存
#include <XCEngine/RHI/D3D12/D3D12CommandList.h>
void Example() { 后续 [`Clear`](Clear.md) 会复用这些 handle，对当前输出目标执行清屏。
XCEngine::RHI::D3D12CommandList object;
// 根据上下文补齐参数后调用 D3D12CommandList::SetRenderTargets(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [BeginRenderPass](BeginRenderPass.md)
- [返回模块目录](../D3D12.md) - [Clear](Clear.md)

34
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffers.md
View File

@@ -1,35 +1,23 @@
# D3D12CommandList::SetVertexBuffers # D3D12CommandList::SetVertexBuffers
设置相关状态或配置。
```cpp ```cpp
void SetVertexBuffers(uint32_t startSlot, uint32_t count, RHIResourceView** buffers, const uint64_t* offsets, const uint32_t* strides) override; void SetVertexBuffers(uint32_t startSlot, uint32_t count, RHIResourceView** buffers, const uint64_t* offsets, const uint32_t* strides) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 根据一组顶点缓冲 view 生成 `D3D12_VERTEX_BUFFER_VIEW` 并绑定到 IA 阶段。
- `startSlot` - 参数语义详见头文件声明。
- `count` - 参数语义详见头文件声明。
- `buffers` - 参数语义详见头文件声明。
- `offsets` - 参数语义详见头文件声明。
- `strides` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 为每个输入 view 读取：
- GPU 地址
```cpp - buffer size
#include <XCEngine/RHI/D3D12/D3D12CommandList.h> - view 自带 stride
- 若调用方显式提供 `strides[i] > 0`，优先使用调用方 stride
void Example() { - 最终调用 `IASetVertexBuffers(...)`
XCEngine::RHI::D3D12CommandList object;
// 根据上下文补齐参数后调用 D3D12CommandList::SetVertexBuffers(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [SetIndexBuffer](SetIndexBuffer.md)
- [返回模块目录](../D3D12.md) - [Draw](Draw.md)

46
docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TransitionBarrier.md
View File

@@ -1,48 +1,26 @@
# D3D12CommandList::TransitionBarrier # D3D12CommandList::TransitionBarrier
公开方法，详见头文件声明。
该方法在 `XCEngine/RHI/D3D12/D3D12CommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
void TransitionBarrier(RHIResourceView* resource, ResourceStates stateBefore, ResourceStates stateAfter) override; void TransitionBarrier(RHIResourceView* resource, ResourceStates stateBefore, ResourceStates stateAfter) override;
```
**参数：**
- `resource` - 参数语义详见头文件声明。
- `stateBefore` - 参数语义详见头文件声明。
- `stateAfter` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
## 重载 2: 声明
```cpp
void TransitionBarrier(ID3D12Resource* resource, ResourceStates stateBefore, ResourceStates stateAfter); void TransitionBarrier(ID3D12Resource* resource, ResourceStates stateBefore, ResourceStates stateAfter);
``` ```
**参数：** ## 作用
- `resource` - 参数语义详见头文件声明。
- `stateBefore` - 参数语义详见头文件声明。
- `stateAfter` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 对资源插入 D3D12 transition barrier，并更新命令列表内部的软件状态缓存。
**示例：** ## 当前实现行为
```cpp - `RHIResourceView*` 重载会先转成 `D3D12ResourceView`，再取出底层 `ID3D12Resource*`
#include <XCEngine/RHI/D3D12/D3D12CommandList.h> - 最终调用 `TransitionBarrierInternal(...)`
- barrier 的 `StateBefore` / `StateAfter` 来自调用方传入值
- 成功发出 barrier 后，`m_resourceStateMap[resource] = stateAfter`
void Example() { ## 设计说明
XCEngine::RHI::D3D12CommandList object;
// 根据上下文补齐参数后调用 D3D12CommandList::TransitionBarrier(...)。 这里的状态缓存只是“本命令列表认为资源现在处于什么状态”，方便后续查询和调试，不是跨队列、跨帧同步的权威来源。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandList.md) - [BeginRenderPass](BeginRenderPass.md)
- [返回模块目录](../D3D12.md) - [CopyResource](CopyResource.md)

75
docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/D3D12CommandQueue.md
View File

@@ -6,40 +6,59 @@
**头文件**: `XCEngine/RHI/D3D12/D3D12CommandQueue.h` **头文件**: `XCEngine/RHI/D3D12/D3D12CommandQueue.h`
**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12CommandQueue` public API。 **描述**: D3D12 后端的命令提交队列封装，负责提交命令列表、与 fence 交互，并维护一条简化的“当前帧计数”时间线。
## 概述 ## 概览
`D3D12CommandQueue.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `D3D12CommandQueue` 是抽象 [`RHICommandQueue`](../../RHICommandQueue/RHICommandQueue.md) 在 D3D12 上的直接映射。它内部持有一个真实的 `ID3D12CommandQueue`，并额外维护了一个仅供队列自身使用的 `m_frameFence`。
## 声明概览 这类设计和商业引擎的 backend queue 很像：
| 声明 | 类型 | 说明 | - 上层只关心“把哪些命令列表送到哪类队列”
|------|------|------| - 后端负责把抽象 `CommandQueueType` 翻译成 D3D12 queue type
| `D3D12CommandQueue` | `class` | 继承自 `RHICommandQueue` 的公开声明。 | - 同步仍然是显式的，不会像 OpenGL 那样把提交和执行揉成同一个概念
## 公共方法 ## 生命周期
| 方法 | 描述 | 典型顺序是：
|------|------|
| [D3D12CommandQueue()](Constructor.md) | 构造对象。 | 1. 构造对象
| [~D3D12CommandQueue()](Destructor.md) | 销毁对象并释放相关资源。 | 2. 调用 [`Initialize`](Initialize.md)
| [Initialize](Initialize.md) | 初始化内部状态。 | 3. 反复调用 [`ExecuteCommandLists`](ExecuteCommandLists.md)、[`Signal`](Signal.md)、[`Wait`](Wait.md)
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | 4. 在需要粗粒度同步时调用 [`WaitForIdle`](WaitForIdle.md)
| [ExecuteCommandLists](ExecuteCommandLists.md) | 公开方法，详见头文件声明。 | 5. 销毁前调用 `Shutdown()`
| [Signal](Signal.md) | 公开方法，详见头文件声明。 |
| [Wait](Wait.md) | 公开方法，详见头文件声明。 | ## 当前实现的真实行为
| [GetCompletedValue](GetCompletedValue.md) | 获取相关状态或对象。 |
| [WaitForIdle](WaitForIdle.md) | 公开方法，详见头文件声明。 | - `Initialize()` 会创建真实的 `ID3D12CommandQueue`
| [GetType](GetType.md) | 获取相关状态或对象。 | - 同时会创建一条 `m_frameFence` 和一个 Win32 event，用于 `WaitForPreviousFrame()`
| [GetTimestampFrequency](GetTimestampFrequency.md) | 获取相关状态或对象。 | - `ExecuteCommandLists()` 提交后会把 `m_currentFrame` 加一，并用 `m_frameFence` signal 这个值
| [GetCommandQueue](GetCommandQueue.md) | 获取相关状态或对象。 | - [`GetCompletedValue`](GetCompletedValue.md) 返回的是 `m_frameFence` 的完成值，不是某个外部 fence 的值
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | - [`WaitForIdle`](WaitForIdle.md) 当前不是复用 `m_frameFence`，而是临时创建一个 fence 后轮询等待，这属于可用但不够成熟的实现
| [ExecuteCommandListsInternal](ExecuteCommandListsInternal.md) | 公开方法，详见头文件声明。 |
| [WaitForPreviousFrame](WaitForPreviousFrame.md) | 公开方法，详见头文件声明。 | ## 线程语义
| [GetCurrentFrame](GetCurrentFrame.md) | 获取相关状态或对象。 |
队列对象本身没有做额外并发保护。更合理的假设是：
- 一条队列由渲染线程或提交线程顺序驱动
- 外部若要并发 signal / wait / submit，需要自行加锁或做任务级调度
## 当前限制
- `WaitForIdle()` 采用临时 fence + `Sleep(1)` 轮询，适合调试和初始化路径，不适合高频帧间同步
- `GetCompletedValue()` 只反映内部帧 fence 的状态，不等同于 GPU 全局时间线
## 重点公共方法
- [Initialize](Initialize.md)
- [ExecuteCommandLists](ExecuteCommandLists.md)
- [Signal](Signal.md)
- [Wait](Wait.md)
- [GetCompletedValue](GetCompletedValue.md)
- [WaitForIdle](WaitForIdle.md)
## 相关文档 ## 相关文档
- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录 - [D3D12](../D3D12.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [D3D12Device](../D3D12Device/D3D12Device.md)
- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)

33
docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/ExecuteCommandLists.md
View File

@@ -1,32 +1,29 @@
# D3D12CommandQueue::ExecuteCommandLists # D3D12CommandQueue::ExecuteCommandLists
公开方法，详见头文件声明。
```cpp ```cpp
void ExecuteCommandLists(uint32_t count, void** lists) override; void ExecuteCommandLists(uint32_t count, void** lists) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandQueue.h`，当前页面用于固定 `D3D12CommandQueue` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把一组抽象命令列表提交到当前 D3D12 队列。
- `count` - 参数语义详见头文件声明。
- `lists` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 前置条件
**示例：** - 队列已经初始化
- `lists` 指向的是可提交的 `RHICommandList` 实例
```cpp ## 当前实现行为
#include <XCEngine/RHI/D3D12/D3D12CommandQueue.h>
void Example() { - 当 `count == 0` 或 `lists == nullptr` 时直接返回
XCEngine::RHI::D3D12CommandQueue object; - 把每个 `RHICommandList` 的 `GetNativeHandle()` 转成 `ID3D12CommandList*`
// 根据上下文补齐参数后调用 D3D12CommandQueue::ExecuteCommandLists(...)。 - 调用内部 `ExecuteCommandListsInternal()`
(void)object; - `ExecuteCommandListsInternal()` 提交后会：
} - `m_currentFrame++`
``` - 对 `m_frameFence` signal 当前帧值
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandQueue.md) - [D3D12CommandQueue](D3D12CommandQueue.md)
- [返回模块目录](../D3D12.md) - [GetCompletedValue](GetCompletedValue.md)
- [WaitForIdle](WaitForIdle.md)

25
docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/GetCompletedValue.md
View File

@@ -1,30 +1,23 @@
# D3D12CommandQueue::GetCompletedValue # D3D12CommandQueue::GetCompletedValue
获取相关状态或对象。
```cpp ```cpp
uint64_t GetCompletedValue() override; uint64_t GetCompletedValue() override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandQueue.h`，当前页面用于固定 `D3D12CommandQueue` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 查询队列内部帧 fence 当前已经完成到哪一帧。
**返回：** `uint64_t` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 若 `m_frameFence` 存在，则返回其 `GetCompletedValue()`
- 否则返回 `0`
```cpp ## 注意事项
#include <XCEngine/RHI/D3D12/D3D12CommandQueue.h>
void Example() { 这不是对“所有提交过的外部 fence”的统一查询；它只反映队列自身维护的那条帧时间线。
XCEngine::RHI::D3D12CommandQueue object;
// 根据上下文补齐参数后调用 D3D12CommandQueue::GetCompletedValue(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandQueue.md) - [ExecuteCommandLists](ExecuteCommandLists.md)
- [返回模块目录](../D3D12.md) - [WaitForIdle](WaitForIdle.md)

32
docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Initialize.md
View File

@@ -1,32 +1,28 @@
# D3D12CommandQueue::Initialize # D3D12CommandQueue::Initialize
初始化内部状态。
```cpp ```cpp
bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct); bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct);
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandQueue.h`，当前页面用于固定 `D3D12CommandQueue` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 创建原生 D3D12 队列对象和队列自身使用的帧 fence。
- `device` - 参数语义详见头文件声明。
- `type` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 把 `CommandQueueType` 转成 `D3D12_COMMAND_QUEUE_DESC.Type`
- 创建 `ID3D12CommandQueue`
- 创建一只初始值为 `0` 的 `m_frameFence`
- 创建 Win32 event 保存到 `m_frameEvent`
- 缓存队列类型和 timestamp frequency
```cpp ## 失败路径
#include <XCEngine/RHI/D3D12/D3D12CommandQueue.h>
void Example() { - 创建原生队列失败返回 `false`
XCEngine::RHI::D3D12CommandQueue object; - 创建 `m_frameFence` 失败返回 `false`
// 根据上下文补齐参数后调用 D3D12CommandQueue::Initialize(...)。 - 创建 event 失败返回 `false`
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandQueue.md) - [D3D12CommandQueue](D3D12CommandQueue.md)
- [返回模块目录](../D3D12.md) - [ExecuteCommandLists](ExecuteCommandLists.md)

42
docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Signal.md
View File

@@ -1,46 +1,24 @@
# D3D12CommandQueue::Signal # D3D12CommandQueue::Signal
公开方法，详见头文件声明。
该方法在 `XCEngine/RHI/D3D12/D3D12CommandQueue.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
void Signal(RHIFence* fence, uint64_t value) override; void Signal(RHIFence* fence, uint64_t value) override;
``` ```
**参数：** ## 作用
- `fence` - 参数语义详见头文件声明。
- `value` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 让当前队列对指定 fence signal 一个值。
## 重载 2: 声明 ## 当前实现行为
```cpp - 若 `fence == nullptr`，直接返回
void Signal(ID3D12Fence* fence, uint64_t value); - 把抽象 `RHIFence` 转成 `D3D12Fence`
``` - 调用原生 `ID3D12CommandQueue::Signal(...)`
**参数：** ## 注意事项
- `fence` - 参数语义详见头文件声明。
- `value` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 这里使用的是调用方传入的 fence，不是队列自己的 `m_frameFence`。
**示例：**
```cpp
#include <XCEngine/RHI/D3D12/D3D12CommandQueue.h>
void Example() {
XCEngine::RHI::D3D12CommandQueue object;
// 根据上下文补齐参数后调用 D3D12CommandQueue::Signal(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandQueue.md) - [D3D12CommandQueue](D3D12CommandQueue.md)
- [返回模块目录](../D3D12.md) - [Wait](Wait.md)

42
docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Wait.md
View File

@@ -1,46 +1,24 @@
# D3D12CommandQueue::Wait # D3D12CommandQueue::Wait
公开方法，详见头文件声明。
该方法在 `XCEngine/RHI/D3D12/D3D12CommandQueue.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
void Wait(RHIFence* fence, uint64_t value) override; void Wait(RHIFence* fence, uint64_t value) override;
``` ```
**参数：** ## 作用
- `fence` - 参数语义详见头文件声明。
- `value` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 让当前队列等待指定 fence 达到目标值。
## 重载 2: 声明 ## 当前实现行为
```cpp - 若 `fence == nullptr`，直接返回
void Wait(ID3D12Fence* fence, uint64_t value); - 把 `RHIFence` 转成 `D3D12Fence`
``` - 调用原生 `ID3D12CommandQueue::Wait(...)`
**参数：** ## 设计说明
- `fence` - 参数语义详见头文件声明。
- `value` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 这是一条 GPU 侧队列等待路径，不是 CPU 阻塞等待。它的语义更接近 D3D12 原生 queue dependency，而不是 `WaitForIdle()` 那种“CPU 等 GPU”。
**示例：**
```cpp
#include <XCEngine/RHI/D3D12/D3D12CommandQueue.h>
void Example() {
XCEngine::RHI::D3D12CommandQueue object;
// 根据上下文补齐参数后调用 D3D12CommandQueue::Wait(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandQueue.md) - [Signal](Signal.md)
- [返回模块目录](../D3D12.md) - [WaitForIdle](WaitForIdle.md)

27
docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/WaitForIdle.md
View File

@@ -1,30 +1,25 @@
# D3D12CommandQueue::WaitForIdle # D3D12CommandQueue::WaitForIdle
公开方法，详见头文件声明。
```cpp ```cpp
void WaitForIdle() override; void WaitForIdle() override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandQueue.h`，当前页面用于固定 `D3D12CommandQueue` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 阻塞 CPU，直到当前队列在调用点之前提交的工作全部完成。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 从队列反查 `ID3D12Device`
- 临时创建一只 fence
- 对该 fence signal `1`
- 通过 `while (fence->GetCompletedValue() < 1) { Sleep(1); }` 轮询等待
```cpp ## 设计说明
#include <XCEngine/RHI/D3D12/D3D12CommandQueue.h>
void Example() { 这是一条简单、稳定、易懂的空闲等待路径，适合初始化、销毁和测试代码，但并不适合高频帧循环。更成熟的实现通常会复用长期存在的 fence，并用事件等待代替忙轮询。
XCEngine::RHI::D3D12CommandQueue object;
// 根据上下文补齐参数后调用 D3D12CommandQueue::WaitForIdle(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12CommandQueue.md) - [ExecuteCommandLists](ExecuteCommandLists.md)
- [返回模块目录](../D3D12.md) - [GetCompletedValue](GetCompletedValue.md)

29
docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Bind.md
View File

@@ -1,30 +1,27 @@
# D3D12DescriptorSet::Bind # D3D12DescriptorSet::Bind
公开方法，详见头文件声明。
```cpp ```cpp
void Bind() override; void Bind() override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 抽象层保留的绑定入口。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** 当前实现为空，不会直接向 D3D12 pipeline 绑定任何内容。
```cpp ## 正确理解
#include <XCEngine/RHI/D3D12/D3D12DescriptorSet.h>
void Example() { 在 D3D12 后端里，descriptor set 的真正消费点是：
XCEngine::RHI::D3D12DescriptorSet object;
// 根据上下文补齐参数后调用 D3D12DescriptorSet::Bind(...)。 - `D3D12CommandList::SetGraphicsDescriptorSets()`
(void)object; - `D3D12CommandList::SetComputeDescriptorSets()`
}
``` 因此这里应把 `Bind()` 视为抽象层兼容接口，而不是成熟主路径。
## 相关文档 ## 相关文档
- [返回类总览](D3D12DescriptorSet.md) - [Unbind](Unbind.md)
- [返回模块目录](../D3D12.md) - [D3D12CommandList::SetGraphicsDescriptorSets](../D3D12CommandList/SetGraphicsDescriptorSets.md)

105
docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/D3D12DescriptorSet.md
View File

@@ -6,49 +6,80 @@
**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` **头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`
**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12DescriptorSet` public API。 **描述**: D3D12 后端对“descriptor set”抽象的适配层，负责把 layout 绑定映射到 descriptor heap 槽位与 root CBV 上传逻辑。
## 概述 ## 概览
`D3D12DescriptorSet.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 严格来说，D3D12 并没有 Vulkan 式的原生 descriptor set。`D3D12DescriptorSet` 的价值在于给跨后端 RHI 提供一个统一的“成组绑定”接口，然后在 D3D12 侧分解成：
## 声明概览 - descriptor heap 中的 SRV / UAV / Sampler 段
- root signature 中的 CBV root parameter
- 每个常量绑定独立维护的 upload buffer
| 声明 | 类型 | 说明 | 这就是它和商业引擎底层“绑定组抽象”的典型相似点：上层继续按 set 思维写代码，后端负责把它拆成 D3D12 真正需要的绑定形式。
|------|------|------|
| `D3D12DescriptorSet` | `class` | 继承自 `RHIDescriptorSet` 的公开声明。 |
## 公共方法 ## 生命周期
| 方法 | 描述 | 1. 由 [`D3D12DescriptorHeap`](../D3D12DescriptorHeap/D3D12DescriptorHeap.md) 调用 [`Initialize`](Initialize.md)
|------|------| 2. 通过 [`Update`](Update.md)、[`UpdateSampler`](UpdateSampler.md)、[`WriteConstant`](WriteConstant.md) 写入内容
| [D3D12DescriptorSet()](Constructor.md) | 构造对象。 | 3. 在命令列表绑定阶段由 [`D3D12CommandList`](../D3D12CommandList/D3D12CommandList.md) 消费
| [~D3D12DescriptorSet()](Destructor.md) | 销毁对象并释放相关资源。 | 4. 销毁时调用 `Shutdown()`
| [Initialize](Initialize.md) | 初始化内部状态。 |
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | ## 当前实现的真实行为
| [Bind](Bind.md) | 公开方法，详见头文件声明。 |
| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 | ### 绑定索引分配
| [Update](Update.md) | 更新运行时状态。 |
| [UpdateSampler](UpdateSampler.md) | 更新运行时状态。 | - 初始化时会复制 layout
| [WriteConstant](WriteConstant.md) | 公开方法，详见头文件声明。 | - 只为当前 heap 类型真正可承载的绑定分配 descriptor index
| [GetBindingCount](GetBindingCount.md) | 获取相关状态或对象。 | - 分配顺序不是“按声明原顺序平铺全部绑定”，而是按类型分组：
| [GetBindings](GetBindings.md) | 获取相关状态或对象。 | - `SRV`
| [GetConstantBufferData](GetConstantBufferData.md) | 获取相关状态或对象。 | - `UAV`
| [GetConstantBufferSize](GetConstantBufferSize.md) | 获取相关状态或对象。 | - `Sampler`
| [IsConstantDirty](IsConstantDirty.md) | 查询当前状态。 | - 每组内部再按 `binding` 升序排列
| [MarkConstantClean](MarkConstantClean.md) | 公开方法，详见头文件声明。 | - `CBV` 不占用 descriptor heap 槽位
| [GetGPUHandle](GetGPUHandle.md) | 获取相关状态或对象。 |
| [GetGPUHandleForBinding](GetGPUHandleForBinding.md) | 获取相关状态或对象。 | ### 常量缓冲策略
| [GetOffset](GetOffset.md) | 获取相关状态或对象。 |
| [GetCount](GetCount.md) | 获取相关状态或对象。 | - [`WriteConstant`](WriteConstant.md) 只改写 CPU 侧字节缓存，并标记 dirty
| [GetHeap](GetHeap.md) | 获取相关状态或对象。 | - [`UploadConstantBuffer`](UploadConstantBuffer.md) 才会真正创建或更新 GPU 侧 upload buffer
| [HasBindingType](HasBindingType.md) | 判断是否具备指定状态或能力。 | - upload buffer 按 256 字节对齐，这是 D3D12 常量缓冲视图的基本约束
| [GetFirstBindingOfType](GetFirstBindingOfType.md) | 获取相关状态或对象。 | - 每个 `CBV` binding 都可能拥有一块独立的 `D3D12Buffer`
| [GetDescriptorIndexForBinding](GetDescriptorIndexForBinding.md) | 获取相关状态或对象。 |
| [UploadConstantBuffer](UploadConstantBuffer.md) | 公开方法，详见头文件声明。 | ### Bind / Unbind 的真实语义
| [GetConstantBufferGPUAddress](GetConstantBufferGPUAddress.md) | 获取相关状态或对象。 |
- [`Bind`](Bind.md) 当前是空实现
- [`Unbind`](Unbind.md) 当前也是空实现
- 真正的绑定动作发生在 `D3D12CommandList::SetGraphicsDescriptorSets()` / `SetComputeDescriptorSets()`
也就是说，`D3D12DescriptorSet` 更像“绑定数据容器”，而不是一个会自己把内容推到 GPU pipeline 的主动对象。
## 线程语义
没有内部锁。更安全的假设是：
- 更新描述符与写常量发生在提交前、单线程阶段
- 绑定后不要同时从其他线程修改同一个 set
## 当前限制
- `Update()` 只处理 `CBV_SRV_UAV` heap 路径
- `UpdateSampler()` 只处理 sampler heap 路径
- `Bind()` / `Unbind()` 仍是 no-op
- 常量缓冲上传是惰性的，只有命令列表绑定阶段显式触发时才会真正落到 GPU 资源
## 重点公共方法
- [Initialize](Initialize.md)
- [Update](Update.md)
- [UpdateSampler](UpdateSampler.md)
- [WriteConstant](WriteConstant.md)
- [UploadConstantBuffer](UploadConstantBuffer.md)
- [Bind](Bind.md)
- [Unbind](Unbind.md)
## 相关文档 ## 相关文档
- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录 - [D3D12](../D3D12.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [D3D12DescriptorHeap](../D3D12DescriptorHeap/D3D12DescriptorHeap.md)
- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)
- [D3D12PipelineLayout](../D3D12PipelineLayout/D3D12PipelineLayout.md)

34
docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Initialize.md
View File

@@ -1,34 +1,28 @@
# D3D12DescriptorSet::Initialize # D3D12DescriptorSet::Initialize
初始化内部状态。
```cpp ```cpp
bool Initialize(D3D12DescriptorHeap* heap, uint32_t offset, uint32_t count, const DescriptorSetLayoutDesc& layout); bool Initialize(D3D12DescriptorHeap* heap, uint32_t offset, uint32_t count, const DescriptorSetLayoutDesc& layout);
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 按给定 layout 初始化 descriptor set 的绑定记录，并为需要落到 descriptor heap 的绑定计算 descriptor index。
- `heap` - 参数语义详见头文件声明。
- `offset` - 参数语义详见头文件声明。
- `count` - 参数语义详见头文件声明。
- `layout` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 保存 `heap`、`offset`、`count`
- 复制 `layout.bindings`
- 为每个 binding 创建一条 `BindingRecord`
- 只对当前 heap 类型真正支持的绑定分配 descriptor index
- 分配顺序按类型分组：`SRV`、`UAV`、`Sampler`
- 每组内部再按 `binding` 升序排列
```cpp ## 注意事项
#include <XCEngine/RHI/D3D12/D3D12DescriptorSet.h>
void Example() { - `CBV` 不占用 heap descriptor 槽位
XCEngine::RHI::D3D12DescriptorSet object; - `count` 表示这个 set 在 heap 中实际占用的 descriptor 数，而不是 layout 的 binding 数
// 根据上下文补齐参数后调用 D3D12DescriptorSet::Initialize(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12DescriptorSet.md) - [D3D12DescriptorSet](D3D12DescriptorSet.md)
- [返回模块目录](../D3D12.md) - [Update](Update.md)

24
docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Unbind.md
View File

@@ -1,30 +1,18 @@
# D3D12DescriptorSet::Unbind # D3D12DescriptorSet::Unbind
公开方法，详见头文件声明。
```cpp ```cpp
void Unbind() override; void Unbind() override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 抽象层保留的解绑入口。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** 当前实现为空，不会主动清理 root signature、descriptor heap 或 descriptor table 绑定。
```cpp
#include <XCEngine/RHI/D3D12/D3D12DescriptorSet.h>
void Example() {
XCEngine::RHI::D3D12DescriptorSet object;
// 根据上下文补齐参数后调用 D3D12DescriptorSet::Unbind(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12DescriptorSet.md) - [Bind](Bind.md)
- [返回模块目录](../D3D12.md) - [D3D12DescriptorSet](D3D12DescriptorSet.md)

40
docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Update.md
View File

@@ -1,32 +1,36 @@
# D3D12DescriptorSet::Update # D3D12DescriptorSet::Update
更新运行时状态。
```cpp ```cpp
void Update(uint32_t offset, RHIResourceView* view) override; void Update(uint32_t offset, RHIResourceView* view) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把一个资源视图写入当前 descriptor set 对应 binding 的 descriptor heap 槽位。
- `offset` - 参数语义详见头文件声明。
- `view` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 前置条件
**示例：** - 当前 set 对应的 heap 类型必须是 `DescriptorHeapType::CBV_SRV_UAV`
- `view` 必须有效
```cpp ## 当前实现行为
#include <XCEngine/RHI/D3D12/D3D12DescriptorSet.h>
void Example() { - 根据 `offset` 查找 binding 对应的 descriptor index
XCEngine::RHI::D3D12DescriptorSet object; - 若该 binding 在当前 heap 上没有 descriptor 槽位，则直接返回
// 根据上下文补齐参数后调用 D3D12DescriptorSet::Update(...)。 - 把 `RHIResourceView` 转成 `D3D12ResourceView`
(void)object; - 使用 `CopyDescriptorsSimple(...)` 把源 descriptor 复制到 set 自己的 heap 位置
}
``` ## 失败路径
以下情况会静默返回：
- `m_heap == nullptr`
- `view == nullptr`
- heap 类型不是 `CBV_SRV_UAV`
- binding 没有可用 descriptor index
- `view` 无效
## 相关文档 ## 相关文档
- [返回类总览](D3D12DescriptorSet.md) - [UpdateSampler](UpdateSampler.md)
- [返回模块目录](../D3D12.md) - [SetGraphicsDescriptorSets](../D3D12CommandList/SetGraphicsDescriptorSets.md)

29
docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/UpdateSampler.md
View File

@@ -1,32 +1,21 @@
# D3D12DescriptorSet::UpdateSampler # D3D12DescriptorSet::UpdateSampler
更新运行时状态。
```cpp ```cpp
void UpdateSampler(uint32_t offset, RHISampler* sampler) override; void UpdateSampler(uint32_t offset, RHISampler* sampler) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把一个 sampler 描述写入当前 set 的 sampler heap 槽位。
- `offset` - 参数语义详见头文件声明。
- `sampler` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 仅当 heap 类型是 `DescriptorHeapType::Sampler` 时生效
- 根据 binding 计算 descriptor index
```cpp - 把 `RHISampler` 转成 `D3D12Sampler`
#include <XCEngine/RHI/D3D12/D3D12DescriptorSet.h> - 调用 `ID3D12Device::CreateSampler(...)` 直接写入目标 CPU descriptor handle
void Example() {
XCEngine::RHI::D3D12DescriptorSet object;
// 根据上下文补齐参数后调用 D3D12DescriptorSet::UpdateSampler(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12DescriptorSet.md) - [Update](Update.md)
- [返回模块目录](../D3D12.md) - [D3D12Sampler](../D3D12Sampler/D3D12Sampler.md)

33
docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/UploadConstantBuffer.md
View File

@@ -1,31 +1,30 @@
# D3D12DescriptorSet::UploadConstantBuffer # D3D12DescriptorSet::UploadConstantBuffer
公开方法，详见头文件声明。
```cpp ```cpp
bool UploadConstantBuffer(uint32_t binding); bool UploadConstantBuffer(uint32_t binding);
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 确保指定 `CBV` binding 对应的 GPU upload buffer 已存在，并在需要时把 CPU 缓存写入该 buffer。
- `binding` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 若 binding 不是 `CBV`，返回 `false`
- 按 256 字节对齐计算目标容量
- 若尚未分配 buffer，或现有容量不足：
- 新建 `D3D12Buffer`
- 以 `D3D12_HEAP_TYPE_UPLOAD` 和 `D3D12_RESOURCE_STATE_GENERIC_READ` 初始化
- 设置 `BufferType::Constant`
- 若数据 dirty，则调用 `SetData(...)` 把 CPU 缓存写入 GPU upload buffer
- 上传后清除 dirty 标记
```cpp ## 返回值
#include <XCEngine/RHI/D3D12/D3D12DescriptorSet.h>
void Example() { - `true`：GPU 侧常量缓冲已可用
XCEngine::RHI::D3D12DescriptorSet object; - `false`：无法为该 binding 创建或更新常量缓冲
// 根据上下文补齐参数后调用 D3D12DescriptorSet::UploadConstantBuffer(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12DescriptorSet.md) - [WriteConstant](WriteConstant.md)
- [返回模块目录](../D3D12.md) - [D3D12CommandList::SetGraphicsDescriptorSets](../D3D12CommandList/SetGraphicsDescriptorSets.md)

32
docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/WriteConstant.md
View File

@@ -1,34 +1,26 @@
# D3D12DescriptorSet::WriteConstant # D3D12DescriptorSet::WriteConstant
公开方法，详见头文件声明。
```cpp ```cpp
void WriteConstant(uint32_t binding, const void* data, size_t size, size_t offset = 0) override; void WriteConstant(uint32_t binding, const void* data, size_t size, size_t offset = 0) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把一段常量数据写入指定 `CBV` binding 的 CPU 侧缓存。
- `binding` - 参数语义详见头文件声明。
- `data` - 参数语义详见头文件声明。
- `size` - 参数语义详见头文件声明。
- `offset` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 查找对应 binding
- 只接受 `DescriptorType::CBV`
- 若内部字节数组不够大，会自动扩容到 `offset + size`
- 执行 `memcpy`
- 把该 binding 标记为 dirty
```cpp ## 注意事项
#include <XCEngine/RHI/D3D12/D3D12DescriptorSet.h>
void Example() { 该方法本身不会创建或更新 GPU buffer。真正把数据上传到 GPU 的步骤在 [`UploadConstantBuffer`](UploadConstantBuffer.md)。
XCEngine::RHI::D3D12DescriptorSet object;
// 根据上下文补齐参数后调用 D3D12DescriptorSet::WriteConstant(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](D3D12DescriptorSet.md) - [UploadConstantBuffer](UploadConstantBuffer.md)
- [返回模块目录](../D3D12.md) - [Initialize](Initialize.md)

35
docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandList.md
View File

@@ -1,31 +1,32 @@
# D3D12Device::CreateCommandList # D3D12Device::CreateCommandList
创建新对象或资源。
```cpp ```cpp
RHICommandList* CreateCommandList(const CommandListDesc& desc) override; RHICommandList* CreateCommandList(const CommandListDesc& desc) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 创建一条 D3D12 命令列表，并为它同时准备一只匹配类型的 command allocator。
- `desc` - 参数语义详见头文件声明。
**返回：** `RHICommandList*` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 若 `m_device` 为空，直接返回 `nullptr`
- 先创建临时 `D3D12CommandAllocator`
- allocator 初始化类型来自 `desc.commandListType`
- 再创建 `D3D12CommandList`
- 命令列表初始化时把 allocator 传入，并由内部 `ComPtr` 接管引用
```cpp ## 设计说明
#include <XCEngine/RHI/D3D12/D3D12Device.h>
void Example() { 这条路径把“命令列表必须依赖 allocator”这一 D3D12 前置条件封装起来了。对上层来说，`CreateCommandList()` 返回的是现成可用的 recorder；对后端来说，它仍保留了 D3D12 allocator/list 的真实关系。
XCEngine::RHI::D3D12Device object;
// 根据上下文补齐参数后调用 D3D12Device::CreateCommandList(...)。 ## 返回值
(void)object;
} - 成功返回 `D3D12CommandList*`
``` - 任一步失败返回 `nullptr`
## 相关文档 ## 相关文档
- [返回类总览](D3D12Device.md) - [D3D12Device](D3D12Device.md)
- [返回模块目录](../D3D12.md) - [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)
- [D3D12CommandAllocator](../D3D12CommandAllocator/D3D12CommandAllocator.md)

34
docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandQueue.md
View File

@@ -1,31 +1,31 @@
# D3D12Device::CreateCommandQueue # D3D12Device::CreateCommandQueue
创建新对象或资源。
```cpp ```cpp
RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc) override; RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 创建一条 D3D12 命令队列。
- `desc` - 参数语义详见头文件声明。
**返回：** `RHICommandQueue*` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 直接 `new D3D12CommandQueue()`
- 以 `desc.queueType` 调用 `D3D12CommandQueue::Initialize(...)`
- 初始化成功则返回该对象
- 初始化失败则删除对象并返回 `nullptr`
```cpp ## 前置条件
#include <XCEngine/RHI/D3D12/D3D12Device.h>
void Example() { - 设备已经初始化
XCEngine::RHI::D3D12Device object; - `m_device` 有效
// 根据上下文补齐参数后调用 D3D12Device::CreateCommandQueue(...)。
(void)object; ## 返回值
}
``` - 成功返回 `D3D12CommandQueue*`
- 失败返回 `nullptr`
## 相关文档 ## 相关文档
- [返回类总览](D3D12Device.md) - [D3D12Device](D3D12Device.md)
- [返回模块目录](../D3D12.md) - [D3D12CommandQueue](../D3D12CommandQueue/D3D12CommandQueue.md)

74
docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateTexture.md
View File

@@ -1,47 +1,55 @@
# D3D12Device::CreateTexture # D3D12Device::CreateTexture
创建新对象或资源。
该方法在 `XCEngine/RHI/D3D12/D3D12Device.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
RHITexture* CreateTexture(const TextureDesc& desc) override; RHITexture* CreateTexture(const TextureDesc& desc) override;
```
**参数：**
- `desc` - 参数语义详见头文件声明。
**返回：** `RHITexture*` - 返回值语义详见头文件声明。
## 重载 2: 声明
```cpp
RHITexture* CreateTexture(const TextureDesc& desc, const void* initialData, size_t initialDataSize, uint32_t rowPitch = 0) override; RHITexture* CreateTexture(const TextureDesc& desc, const void* initialData, size_t initialDataSize, uint32_t rowPitch = 0) override;
``` ```
**参数：** ## 作用
- `desc` - 参数语义详见头文件声明。
- `initialData` - 参数语义详见头文件声明。
- `initialDataSize` - 参数语义详见头文件声明。
- `rowPitch` - 参数语义详见头文件声明。
**返回：** `RHITexture*` - 返回值语义详见头文件声明。 创建 D3D12 纹理资源；可选地在创建后同步上传一份初始数据。
**示例：** ## 前置条件
```cpp - 设备已经成功初始化
#include <XCEngine/RHI/D3D12/D3D12Device.h> - `desc` 中的尺寸、格式、类型组合必须是 D3D12 可接受的
- 若传入 `initialData`，当前实现只支持 `Texture2D`
void Example() { ## 当前实现行为
XCEngine::RHI::D3D12Device object;
// 根据上下文补齐参数后调用 D3D12Device::CreateTexture(...)。 ### 无初始数据路径
(void)object;
} - 根据 `TextureDesc` 组装 `D3D12_RESOURCE_DESC`
``` - 深度格式会自动补 `D3D12_RESOURCE_FLAG_ALLOW_DEPTH_STENCIL`
- 普通 2D 纹理在宽高有效时会自动补 `D3D12_RESOURCE_FLAG_ALLOW_RENDER_TARGET`
- 深度纹理初始状态为 `D3D12_RESOURCE_STATE_DEPTH_WRITE`
- 其他纹理初始状态为 `D3D12_RESOURCE_STATE_COMMON`
### 带初始数据路径
- 若 `rowPitch == 0`，会按格式字节数自行推导
- 会临时创建一条 direct queue、一只 command allocator 和一条 command list
- 调用 `D3D12Texture::InitializeFromData(...)` 完成 staging/upload
- 上传完成后把纹理的软件侧状态设为 `ResourceStates::PixelShaderResource`
- 关闭并提交 upload command list，然后调用队列的 `WaitForIdle()`
## 返回值
- 成功返回 `D3D12Texture*`
- 失败返回 `nullptr`
## 失败路径
- 初始数据路径下若纹理类型不是 `Texture2D`，直接返回 `nullptr`
- 若格式无法推导 `rowPitch`，返回 `nullptr`
- 任一上传辅助对象创建失败，返回 `nullptr`
## 设计说明
这种“创建时同步上传”的路径很好理解，也方便测试与离线资源初始化，但不适合作为高频流式上传方案。商业引擎通常会把这类上传移到长期驻留的 upload manager 或 copy queue 里。
## 相关文档 ## 相关文档
- [返回类总览](D3D12Device.md) - [D3D12Device](D3D12Device.md)
- [返回模块目录](../D3D12.md) - [CreateCommandQueue](CreateCommandQueue.md)
- [D3D12Texture](../D3D12Texture/D3D12Texture.md)

131
docs/api/XCEngine/RHI/D3D12/D3D12Device/D3D12Device.md
View File

@@ -6,67 +6,88 @@
**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` **头文件**: `XCEngine/RHI/D3D12/D3D12Device.h`
**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Device` public API。 **描述**: D3D12 后端的设备根对象，负责创建 DXGI factory、选择适配器、创建 `ID3D12Device`，并作为所有 D3D12 资源工厂的统一入口。
## 概述 ## 概览
`D3D12Device.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 如果把抽象层里的 [`RHIDevice`](../../RHIDevice/RHIDevice.md) 理解成“跨后端设备契约”，那么 `D3D12Device` 就是该契约在 Direct3D 12 上的落地实现。
## 声明概览 它承担三类职责：
| 声明 | 类型 | 说明 | - 初始化 D3D12 运行时根对象：`IDXGIFactory4`、`IDXGIAdapter1`、`ID3D12Device`
|------|------|------| - 缓存设备信息与能力信息，供测试、日志和上层系统查询
| `AdapterInfo` | `struct` | 头文件中的公开声明。 | - 把 RHI 的资源创建请求翻译成 D3D12 后端对象，例如 buffer、texture、command queue、command list、pipeline state、descriptor heap 与 descriptor set
| `D3D12Device` | `class` | 继承自 `RHIDevice` 的公开声明。 |
## 公共方法 ## 生命周期
| 方法 | 描述 | 推荐顺序是：
|------|------|
| [D3D12Device()](Constructor.md) | 构造对象。 | 1. 构造 `D3D12Device`
| [~D3D12Device()](Destructor.md) | 销毁对象并释放相关资源。 | 2. 调用 [`Initialize`](Initialize.md)
| [Initialize](Initialize.md) | 初始化内部状态。 | 3. 通过设备创建队列、命令列表、资源和状态对象
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | 4. 先销毁由设备创建出来的对象
| [GetDevice](GetDevice.md) | 获取相关状态或对象。 | 5. 最后调用 `Shutdown()`
| [GetFactory](GetFactory.md) | 获取相关状态或对象。 |
| [GetAdapterInfo](GetAdapterInfo.md) | 获取相关状态或对象。 | 析构函数会调用 `Shutdown()`，但工程上仍应把显式关闭视为标准用法。
| [EnumerateAdapters](EnumerateAdapters.md) | 公开方法，详见头文件声明。 |
| [GetDescriptorHandleIncrementSize](GetDescriptorHandleIncrementSize.md) | 获取相关状态或对象。 | ## 当前实现的真实行为
| [CheckFeatureSupport](CheckFeatureSupport.md) | 公开方法，详见头文件声明。 |
| [SetDeviceRemoved](SetDeviceRemoved.md) | 设置相关状态或配置。 | ### 适配器与调试层
| [IsDeviceRemoved](IsDeviceRemoved.md) | 查询当前状态。 |
| [CreateBuffer](CreateBuffer.md) | 创建新对象或资源。 | - `Initialize()` 会先创建 DXGI factory，然后从 `adapterIndex` 开始枚举适配器。
| [CreateTexture](CreateTexture.md) | 创建新对象或资源。 | - 软件适配器会被跳过。
| [CreateSwapChain](CreateSwapChain.md) | 创建新对象或资源。 | - 当前实现选择“第一个能以 `D3D_FEATURE_LEVEL_11_0` 创建设备的硬件适配器”，而不是做更复杂的打分排序。
| [CreateCommandList](CreateCommandList.md) | 创建新对象或资源。 | - `enableDebugLayer` 会尝试启用 `ID3D12Debug` 和 `DXGI_CREATE_FACTORY_DEBUG`，这是真正接线了的；但它仍然属于基础调试层支持，不等同于完整 GPU validation 工作流。
| [CreateCommandQueue](CreateCommandQueue.md) | 创建新对象或资源。 |
| [CreateShader](CreateShader.md) | 创建新对象或资源。 | ### 资源工厂策略
| [CreatePipelineState](CreatePipelineState.md) | 创建新对象或资源。 |
| [CreatePipelineLayout](CreatePipelineLayout.md) | 创建新对象或资源。 | - [`CreateBuffer`](CreateBuffer.md) 会按 `BufferType` 粗粒度选择 heap：
| [CreateFence](CreateFence.md) | 创建新对象或资源。 | - `ReadBack` -> `D3D12_HEAP_TYPE_READBACK`
| [CreateSampler](CreateSampler.md) | 创建新对象或资源。 | - `Constant / Vertex / Index` -> `D3D12_HEAP_TYPE_UPLOAD`
| [CreateRenderPass](CreateRenderPass.md) | 创建新对象或资源。 | - 其他 -> `D3D12_HEAP_TYPE_DEFAULT`
| [CreateFramebuffer](CreateFramebuffer.md) | 创建新对象或资源。 | - [`CreateTexture`](CreateTexture.md) 对深度格式自动补 `ALLOW_DEPTH_STENCIL`，对常规 2D 纹理自动补 `ALLOW_RENDER_TARGET`。
| [CreateDescriptorPool](CreateDescriptorPool.md) | 创建新对象或资源。 | - 带初始数据的 `CreateTexture()` 会临时创建 upload queue、allocator、command list，同步上传后再 `WaitForIdle()`，因此这是一个阻塞式初始化路径。
| [CreateDescriptorSet](CreateDescriptorSet.md) | 创建新对象或资源。 | - [`CreateCommandList`](CreateCommandList.md) 会先创建专用 `D3D12CommandAllocator`，再创建 `D3D12CommandList`；命令列表内部通过 `ComPtr` 持有 allocator。
| [CreateVertexBufferView](CreateVertexBufferView.md) | 创建新对象或资源。 | - [`CreateDescriptorSet`](CreateDescriptorSet.md) 实际上把分配工作转交给 `D3D12DescriptorHeap::AllocateSet()`。
| [CreateIndexBufferView](CreateIndexBufferView.md) | 创建新对象或资源。 |
| [CreateRenderTargetView](CreateRenderTargetView.md) | 创建新对象或资源。 | ### 能力与设备信息
| [CreateDepthStencilView](CreateDepthStencilView.md) | 创建新对象或资源。 |
| [CreateShaderResourceView](CreateShaderResourceView.md) | 创建新对象或资源。 | - `QueryAdapterInfo()` 会填充 `AdapterInfo` 与 `RHIDeviceInfo`
| [CreateUnorderedAccessView](CreateUnorderedAccessView.md) | 创建新对象或资源。 | - 能力查询覆盖了 ray tracing、mesh shader、conservative rasterization、shader model 等字段
| [GetCapabilities](GetCapabilities.md) | 获取相关状态或对象。 | - 一部分上限值直接来自 D3D12 常量，而不是运行时逐项探测
| [GetDeviceInfo](GetDeviceInfo.md) | 获取相关状态或对象。 |
| [GetNativeDevice](GetNativeDevice.md) | 获取相关状态或对象。 | ## 所有权与资源管理
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
| [CreateCommandQueueImpl](CreateCommandQueueImpl.md) | 创建新对象或资源。 | - 绝大多数 `Create*()` 返回裸指针，调用方负责 `Shutdown()` 与 `delete`
| [CreateCommandListImpl](CreateCommandListImpl.md) | 创建新对象或资源。 | - `D3D12Device` 不做集中式对象注册和统一回收
| [CreateCommandAllocator](CreateCommandAllocator.md) | 创建新对象或资源。 | - 这更接近商业引擎底层 backend 的“轻工厂”模式：好处是后端简单直接，代价是上层必须严格控制释放顺序
| [CreateDescriptorHeap](CreateDescriptorHeap.md) | 创建新对象或资源。 |
| [CreateQueryHeap](CreateQueryHeap.md) | 创建新对象或资源。 | ## 线程语义
| [CreateRootSignature](CreateRootSignature.md) | 创建新对象或资源。 |
`D3D12Device` 自身没有显式加锁。更稳妥的使用方式是：
- 初始化与关闭在单线程串行完成
- 资源创建由调用方保证外部同步
- 不要把它当成天然线程安全的全局服务
## 当前限制
- 适配器选择仍是“从起始索引往后取第一个可用硬件设备”
- 带初始数据的纹理创建走同步上传路径，初始化成本偏高
- 某些能力字段是“基础探测 + 常量填充”的组合，不是完整 profile
## 重点公共方法
- [Initialize](Initialize.md)
- [CreateTexture](CreateTexture.md)
- [CreateCommandQueue](CreateCommandQueue.md)
- [CreateCommandList](CreateCommandList.md)
- [CreateDescriptorPool](CreateDescriptorPool.md)
- [CreateDescriptorSet](CreateDescriptorSet.md)
## 相关文档 ## 相关文档
- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录 - [D3D12](../D3D12.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [D3D12CommandQueue](../D3D12CommandQueue/D3D12CommandQueue.md)
- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)
- [D3D12DescriptorSet](../D3D12DescriptorSet/D3D12DescriptorSet.md)

44
docs/api/XCEngine/RHI/D3D12/D3D12Device/Initialize.md
View File

@@ -1,31 +1,41 @@
# D3D12Device::Initialize # D3D12Device::Initialize
初始化内部状态。
```cpp ```cpp
bool Initialize(const RHIDeviceDesc& desc) override; bool Initialize(const RHIDeviceDesc& desc) override;
``` ```
该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 初始化 D3D12 后端设备根对象，创建 DXGI factory、选择适配器、创建 `ID3D12Device`，并填充能力与设备信息缓存。
- `desc` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 前置条件
**示例：** - 进程运行环境必须能加载 DXGI 与 D3D12 runtime
- 如果对象已经初始化过，当前实现会直接返回 `true`
```cpp ## 当前实现行为
#include <XCEngine/RHI/D3D12/D3D12Device.h>
void Example() { - 保存 `desc`
XCEngine::RHI::D3D12Device object; - 调用 `CreateDXGIFactory(desc.enableDebugLayer)`
// 根据上下文补齐参数后调用 D3D12Device::Initialize(...)。 - 从 `desc.adapterIndex` 开始枚举适配器
(void)object; - 跳过 `DXGI_ADAPTER_FLAG_SOFTWARE` 适配器
} - 选择第一个能成功执行 `D3D12CreateDevice(..., D3D_FEATURE_LEVEL_11_0, ...)` 的硬件适配器
``` - 调用 `CreateDevice()` 和 `QueryAdapterInfo()`
- 成功后把 `m_initialized` 置为 `true`
## 失败路径
- 创建 factory 失败返回 `false`
- 未找到可用硬件适配器返回 `false`
- 创建设备失败返回 `false`
## 返回值
- `true`：设备可用于后续资源与队列创建
- `false`：初始化未完成
## 相关文档 ## 相关文档
- [返回类总览](D3D12Device.md) - [D3D12Device](D3D12Device.md)
- [返回模块目录](../D3D12.md) - [CreateCommandQueue](CreateCommandQueue.md)
- [CreateCommandList](CreateCommandList.md)

93
docs/api/XCEngine/RHI/OpenGL/OpenGL.md
View File

@@ -1,42 +1,77 @@
# OpenGL # OpenGL
**命名空间**: `XCEngine::RHI::OpenGL` **命名空间**: `XCEngine::RHI`
**类型**: `submodule` **类型**: `submodule`
**描述**: OpenGL 后端 public headers。 **描述**: XCEngine 的 OpenGL 后端入口，负责在 Win32/WGL 上建立上下文，并把抽象 RHI 设备、命令、资源和绑定模型适配为有状态的 OpenGL 调用序列。
## 概览 ## 概览
该目录与 `XCEngine/RHI/OpenGL` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。 与 D3D12、Vulkan 这种“先记录、再提交”的显式后端不同，当前 `OpenGL` 子模块的核心特点是：
## 头文件 - 它依赖一个活动的 OpenGL 上下文
- 很多“命令列表”接口实际会立即对当前上下文生效
- descriptor set、pipeline layout、pipeline state 等抽象概念，在这里大多是适配层，而不是 OpenGL 原生对象
- [OpenGLBuffer](OpenGLBuffer/OpenGLBuffer.md) - `OpenGLBuffer.h` 如果你熟悉 Unity，可以把它理解成“老牌状态机图形 API 的一层引擎化封装”：重点不在提交队列，而在把状态切换、纹理单元、uniform buffer 绑定和 framebuffer 组合管理好。
- [OpenGLCommandList](OpenGLCommandList/OpenGLCommandList.md) - `OpenGLCommandList.h`
- [OpenGLCommandQueue](OpenGLCommandQueue/OpenGLCommandQueue.md) - `OpenGLCommandQueue.h` ## 设计要点
- [OpenGLDepthStencilView](OpenGLDepthStencilView/OpenGLDepthStencilView.md) - `OpenGLDepthStencilView.h`
- [OpenGLDescriptorPool](OpenGLDescriptorPool/OpenGLDescriptorPool.md) - `OpenGLDescriptorPool.h` - 设备层负责 WGL 上下文与能力探测。
- [OpenGLDescriptorSet](OpenGLDescriptorSet/OpenGLDescriptorSet.md) - `OpenGLDescriptorSet.h` - `OpenGLCommandQueue` 更像兼容抽象层的门面，而不是一条真实的 GPU 提交队列。
- [OpenGLDevice](OpenGLDevice/OpenGLDevice.md) - `OpenGLDevice.h` - `OpenGLCommandList` 更接近“状态与调用包装器”，不是可延迟提交的录制命令缓冲。
- [OpenGLEnums](OpenGLEnums/OpenGLEnums.md) - `OpenGLEnums.h` - `OpenGLPipelineState` 是 CPU 侧状态容器，`Bind()` 时把状态应用到当前上下文。
- [OpenGLFence](OpenGLFence/OpenGLFence.md) - `OpenGLFence.h` - `OpenGLDescriptorSet` 是对纹理单元、sampler 绑定点和 uniform buffer 绑定点的统一封装。
- [OpenGLFramebuffer](OpenGLFramebuffer/OpenGLFramebuffer.md) - `OpenGLFramebuffer.h`
- [OpenGLPipelineLayout](OpenGLPipelineLayout/OpenGLPipelineLayout.md) - `OpenGLPipelineLayout.h` ## 当前实现边界
- [OpenGLPipelineState](OpenGLPipelineState/OpenGLPipelineState.md) - `OpenGLPipelineState.h`
- [OpenGLRenderPass](OpenGLRenderPass/OpenGLRenderPass.md) - `OpenGLRenderPass.h` - 平台路径是 Windows + WGL。
- [OpenGLRenderTargetView](OpenGLRenderTargetView/OpenGLRenderTargetView.md) - `OpenGLRenderTargetView.h` - 设备初始化支持隐藏窗口自建上下文，也支持附着到现有窗口。
- [OpenGLResourceView](OpenGLResourceView/OpenGLResourceView.md) - `OpenGLResourceView.h` - 命令队列和命令列表抽象已经能打通统一 RHI 路径，但不少接口仍然是适配性质的轻包装。
- [OpenGLSampler](OpenGLSampler/OpenGLSampler.md) - `OpenGLSampler.h` - 部分能力字段或设备信息字段带有“近似值”或“哨兵值”性质，不能把它们当作驱动级精确信息。
- [OpenGLScreenshot](OpenGLScreenshot/OpenGLScreenshot.md) - `OpenGLScreenshot.h`
- [OpenGLShader](OpenGLShader/OpenGLShader.md) - `OpenGLShader.h` ## 推荐阅读顺序
- [OpenGLSwapChain](OpenGLSwapChain/OpenGLSwapChain.md) - `OpenGLSwapChain.h`
- [OpenGLTexture](OpenGLTexture/OpenGLTexture.md) - `OpenGLTexture.h` 1. [OpenGLDevice](OpenGLDevice/OpenGLDevice.md)
- [OpenGLTextureUnitAllocator](OpenGLTextureUnitAllocator/OpenGLTextureUnitAllocator.md) - `OpenGLTextureUnitAllocator.h` 2. [OpenGLCommandList](OpenGLCommandList/OpenGLCommandList.md)
- [OpenGLUniformBufferManager](OpenGLUniformBufferManager/OpenGLUniformBufferManager.md) - `OpenGLUniformBufferManager.h` 3. [OpenGLPipelineState](OpenGLPipelineState/OpenGLPipelineState.md)
- [OpenGLVertexArray](OpenGLVertexArray/OpenGLVertexArray.md) - `OpenGLVertexArray.h` 4. [OpenGLShader](OpenGLShader/OpenGLShader.md)
5. [OpenGLDescriptorSet](OpenGLDescriptorSet/OpenGLDescriptorSet.md)
## 与测试的对应关系
- `tests/RHI/OpenGL/unit/` 用于覆盖 OpenGL 后端专项行为。
- `tests/RHI/unit/test_shader.cpp`、`tests/RHI/unit/test_pipeline_layout.cpp` 会通过统一抽象验证 OpenGL 路径。
- `tests/RHI/OpenGL/integration/` 与 `tests/Rendering/integration/*` 覆盖真实绘制和截图结果。
## 头文件索引
- [OpenGLBuffer](OpenGLBuffer/OpenGLBuffer.md)
- [OpenGLCommandList](OpenGLCommandList/OpenGLCommandList.md)
- [OpenGLCommandQueue](OpenGLCommandQueue/OpenGLCommandQueue.md)
- [OpenGLDepthStencilView](OpenGLDepthStencilView/OpenGLDepthStencilView.md)
- [OpenGLDescriptorPool](OpenGLDescriptorPool/OpenGLDescriptorPool.md)
- [OpenGLDescriptorSet](OpenGLDescriptorSet/OpenGLDescriptorSet.md)
- [OpenGLDevice](OpenGLDevice/OpenGLDevice.md)
- [OpenGLEnums](OpenGLEnums/OpenGLEnums.md)
- [OpenGLFence](OpenGLFence/OpenGLFence.md)
- [OpenGLFramebuffer](OpenGLFramebuffer/OpenGLFramebuffer.md)
- [OpenGLPipelineLayout](OpenGLPipelineLayout/OpenGLPipelineLayout.md)
- [OpenGLPipelineState](OpenGLPipelineState/OpenGLPipelineState.md)
- [OpenGLRenderPass](OpenGLRenderPass/OpenGLRenderPass.md)
- [OpenGLRenderTargetView](OpenGLRenderTargetView/OpenGLRenderTargetView.md)
- [OpenGLResourceView](OpenGLResourceView/OpenGLResourceView.md)
- [OpenGLSampler](OpenGLSampler/OpenGLSampler.md)
- [OpenGLScreenshot](OpenGLScreenshot/OpenGLScreenshot.md)
- [OpenGLShader](OpenGLShader/OpenGLShader.md)
- [OpenGLSwapChain](OpenGLSwapChain/OpenGLSwapChain.md)
- [OpenGLTexture](OpenGLTexture/OpenGLTexture.md)
- [OpenGLTextureUnitAllocator](OpenGLTextureUnitAllocator/OpenGLTextureUnitAllocator.md)
- [OpenGLUniformBufferManager](OpenGLUniformBufferManager/OpenGLUniformBufferManager.md)
- [OpenGLVertexArray](OpenGLVertexArray/OpenGLVertexArray.md)
## 相关文档 ## 相关文档
- [上级目录](../RHI.md) - [RHI](../RHI.md)
- [API 总索引](../../../main.md) - [Devices, Queues, Command Lists, And Resource Creation](../../../_guides/RHI/Devices-Queues-CommandLists-And-Resource-Creation.md)

36
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/BeginRenderPass.md
View File

@@ -1,35 +1,27 @@
# OpenGLCommandList::BeginRenderPass # OpenGLCommandList::BeginRenderPass
公开方法，详见头文件声明。
```cpp ```cpp
void BeginRenderPass(class RHIRenderPass* renderPass, class RHIFramebuffer* framebuffer, const Rect& renderArea, uint32_t clearValueCount, const ClearValue* clearValues) override; void BeginRenderPass(RHIRenderPass* renderPass, RHIFramebuffer* framebuffer, const Rect& renderArea, uint32_t clearValueCount, const ClearValue* clearValues) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 绑定 framebuffer，并按 render pass 描述执行必要的颜色/深度/模板清屏。
- `renderPass` - 参数语义详见头文件声明。
- `framebuffer` - 参数语义详见头文件声明。
- `renderArea` - 参数语义详见头文件声明。
- `clearValueCount` - 参数语义详见头文件声明。
- `clearValues` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 当前忽略 `renderArea`
- 若 `framebuffer` 为空，直接返回
- 先绑定 `OpenGLFramebuffer`
- 若 `renderPass` 有效，则读取各附件的 `loadOp`
- 对 `LoadAction::Clear` 的颜色附件执行 `glClearBufferfv(GL_COLOR, ...)`
- 对深度/模板附件执行 `glClearBufferfv(GL_DEPTH, ...)` / `glClearBufferfv(GL_STENCIL, ...)`
```cpp ## 注意事项
#include <XCEngine/RHI/OpenGL/OpenGLCommandList.h>
void Example() { `EndRenderPass()` 当前只会把 framebuffer 绑定回默认帧缓冲，不存在显式 API 那种 render pass instance 生命周期管理。
XCEngine::RHI::OpenGLCommandList object;
// 根据上下文补齐参数后调用 OpenGLCommandList::BeginRenderPass(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandList.md) - [SetRenderTargets](SetRenderTargets.md)
- [返回模块目录](../OpenGL.md) - [OpenGLRenderPass](../OpenGLRenderPass/OpenGLRenderPass.md)

29
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/CopyResource.md
View File

@@ -1,32 +1,25 @@
# OpenGLCommandList::CopyResource # OpenGLCommandList::CopyResource
公开方法，详见头文件声明。
```cpp ```cpp
void CopyResource(RHIResourceView* dst, RHIResourceView* src) override; void CopyResource(RHIResourceView* dst, RHIResourceView* src) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把一个纹理资源的内容复制到另一个纹理资源。
- `dst` - 参数语义详见头文件声明。
- `src` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 要求 `dst` 和 `src` 都有效
- 只处理双方都能解析出 texture object 的路径
- 根据源/目标纹理尺寸取较小的宽高深
- 调用 `glCopyImageSubData(...)`
```cpp ## 当前限制
#include <XCEngine/RHI/OpenGL/OpenGLCommandList.h>
void Example() { 当前主路径只覆盖纹理复制，不是一个通用的“任意资源复制”实现。
XCEngine::RHI::OpenGLCommandList object;
// 根据上下文补齐参数后调用 OpenGLCommandList::CopyResource(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandList.md) - [SetRenderTargets](SetRenderTargets.md)
- [返回模块目录](../OpenGL.md) - [TransitionBarrier](TransitionBarrier.md)

28
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Dispatch.md
View File

@@ -1,33 +1,23 @@
# OpenGLCommandList::Dispatch # OpenGLCommandList::Dispatch
公开方法，详见头文件声明。
```cpp ```cpp
void Dispatch(uint32_t x, uint32_t y, uint32_t z) override; void Dispatch(uint32_t x, uint32_t y, uint32_t z) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 发出一次 compute dispatch。
- `x` - 参数语义详见头文件声明。
- `y` - 参数语义详见头文件声明。
- `z` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** 直接调用 `glDispatchCompute(x, y, z)`。
```cpp ## 前置条件
#include <XCEngine/RHI/OpenGL/OpenGLCommandList.h>
void Example() { - 当前上下文已绑定 compute program
XCEngine::RHI::OpenGLCommandList object; - 相关 descriptor set / image / buffer 已由调用方提前绑定
// 根据上下文补齐参数后调用 OpenGLCommandList::Dispatch(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandList.md) - [SetComputeDescriptorSets](SetComputeDescriptorSets.md)
- [返回模块目录](../OpenGL.md) - [TransitionBarrier](TransitionBarrier.md)

45
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Draw.md
View File

@@ -1,49 +1,22 @@
# OpenGLCommandList::Draw # OpenGLCommandList::Draw
公开方法，详见头文件声明。
该方法在 `XCEngine/RHI/OpenGL/OpenGLCommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp
void Draw(PrimitiveType type, unsigned int vertexCount, unsigned int startVertex);
```
**参数：**
- `type` - 参数语义详见头文件声明。
- `vertexCount` - 参数语义详见头文件声明。
- `startVertex` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
## 重载 2: 声明
```cpp ```cpp
void Draw(uint32_t vertexCount, uint32_t instanceCount, uint32_t startVertex, uint32_t startInstance) override; void Draw(uint32_t vertexCount, uint32_t instanceCount, uint32_t startVertex, uint32_t startInstance) override;
``` ```
**参数：** ## 作用
- `vertexCount` - 参数语义详见头文件声明。
- `instanceCount` - 参数语义详见头文件声明。
- `startVertex` - 参数语义详见头文件声明。
- `startInstance` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 发出一次非索引绘制。
**示例：** ## 当前实现行为
```cpp 直接调用 `glDrawArraysInstanced(...)`。
#include <XCEngine/RHI/OpenGL/OpenGLCommandList.h>
void Example() { ## 注意事项
XCEngine::RHI::OpenGLCommandList object;
// 根据上下文补齐参数后调用 OpenGLCommandList::Draw(...)。 `startInstance` 当前没有真实参与 OpenGL 调用。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandList.md) - [SetVertexBuffers](SetVertexBuffers.md)
- [返回模块目录](../OpenGL.md) - [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md)

49
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/DrawIndexed.md
View File

@@ -1,51 +1,24 @@
# OpenGLCommandList::DrawIndexed # OpenGLCommandList::DrawIndexed
公开方法，详见头文件声明。
该方法在 `XCEngine/RHI/OpenGL/OpenGLCommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp
void DrawIndexed(PrimitiveType type, unsigned int indexCount, unsigned int startIndex, int baseVertex);
```
**参数：**
- `type` - 参数语义详见头文件声明。
- `indexCount` - 参数语义详见头文件声明。
- `startIndex` - 参数语义详见头文件声明。
- `baseVertex` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
## 重载 2: 声明
```cpp ```cpp
void DrawIndexed(uint32_t indexCount, uint32_t instanceCount, uint32_t startIndex, int32_t baseVertex, uint32_t startInstance) override; void DrawIndexed(uint32_t indexCount, uint32_t instanceCount, uint32_t startIndex, int32_t baseVertex, uint32_t startInstance) override;
``` ```
**参数：** ## 作用
- `indexCount` - 参数语义详见头文件声明。
- `instanceCount` - 参数语义详见头文件声明。
- `startIndex` - 参数语义详见头文件声明。
- `baseVertex` - 参数语义详见头文件声明。
- `startInstance` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 发出一次索引绘制。
**示例：** ## 当前实现行为
```cpp - 根据 `startIndex` 和当前 index type 计算字节偏移
#include <XCEngine/RHI/OpenGL/OpenGLCommandList.h> - 调用 `glDrawElementsInstanced(...)`
void Example() { ## 当前限制
XCEngine::RHI::OpenGLCommandList object;
// 根据上下文补齐参数后调用 OpenGLCommandList::DrawIndexed(...)。 - `baseVertex` 当前未生效
(void)object; - `startInstance` 当前未生效
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandList.md) - [SetIndexBuffer](SetIndexBuffer.md)
- [返回模块目录](../OpenGL.md) - [Draw](Draw.md)

181
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/OpenGLCommandList.md
View File

@@ -6,130 +6,75 @@
**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` **头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h`
**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLCommandList` public API。 **描述**: OpenGL 后端的命令包装器；它更接近“对当前 GL 上下文执行状态设置和 draw/dispatch 调用”的即时接口，而不是可延迟提交的录制命令缓冲。
## 概述 ## 概览
`OpenGLCommandList.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 这是当前 OpenGL 后端最容易被误解的类型。虽然名字叫 `CommandList`，但从实现看，它承担的是：
## 声明概览 - 包装 OpenGL 状态切换和绘制调用
- 组合 framebuffer、纹理绑定、descriptor set 绑定与顶点输入装配
- 为抽象层保留和 D3D12/Vulkan 接近的调用形状
| 声明 | 类型 | 说明 | 换句话说，它更像“统一 RHI 语义下的 OpenGL immediate command facade”。
|------|------|------|
| `PrimitiveType` | `enum class` | 头文件中的公开声明。 |
| `ClearFlag` | `enum class` | 头文件中的公开声明。 |
| `OpenGLCommandList` | `class` | 继承自 `RHICommandList` 的公开声明。 |
## 公共方法 ## 生命周期
| 方法 | 描述 | - 默认构造即可使用
|------|------| - `Reset()` 只会清理少量软件侧缓存
| [OpenGLCommandList()](Constructor.md) | 构造对象。 | - `Close()` 当前为空实现
| [~OpenGLCommandList()](Destructor.md) | 销毁对象并释放相关资源。 | - `Shutdown()` 负责释放内部拼装的 framebuffer 与内部 VAO
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
| [Reset](Reset.md) | 公开方法，详见头文件声明。 | ## 当前实现的真实行为
| [Close](Close.md) | 公开方法，详见头文件声明。 |
| [Clear](Clear.md) | 清空内部数据。 | ### 状态与 barrier
| [ClearColor](ClearColor.md) | 清空内部数据。 |
| [ClearDepth](ClearDepth.md) | 清空内部数据。 | - [`TransitionBarrier`](TransitionBarrier.md) 不会生成显式资源状态机
| [ClearStencil](ClearStencil.md) | 清空内部数据。 | - 它会把纹理的软状态改成 `stateAfter`
| [ClearDepthStencil](ClearDepthStencil.md) | 清空内部数据。 | - 然后直接调用 `glMemoryBarrier(GL_ALL_BARRIER_BITS)`
| [SetShader](SetShader.md) | 设置相关状态或配置。 |
| [SetUniformInt](SetUniformInt.md) | 设置相关状态或配置。 | ### Render pass 与 framebuffer
| [SetUniformFloat](SetUniformFloat.md) | 设置相关状态或配置。 |
| [SetUniformVec3](SetUniformVec3.md) | 设置相关状态或配置。 | - [`BeginRenderPass`](BeginRenderPass.md) 会绑定 framebuffer，并按 render pass 描述决定是否清颜色/深度/模板
| [SetUniformVec4](SetUniformVec4.md) | 设置相关状态或配置。 | - [`SetRenderTargets`](SetRenderTargets.md) 在多 RT 或带 DS 的情况下会临时构造 `OpenGLFramebuffer`
| [SetUniformMat4](SetUniformMat4.md) | 设置相关状态或配置。 | - `EndRenderPass()` 只是把 `GL_FRAMEBUFFER` 绑定回 `0`
| [SetPipelineState](SetPipelineState.md) | 设置相关状态或配置。 |
| [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md) | 设置相关状态或配置。 | ### 描述符与顶点输入
| [SetComputeDescriptorSets](SetComputeDescriptorSets.md) | 设置相关状态或配置。 |
| [SetVertexBuffers](SetVertexBuffers.md) | 设置相关状态或配置。 | - [`SetGraphicsDescriptorSets`](SetGraphicsDescriptorSets.md) / [`SetComputeDescriptorSets`](SetComputeDescriptorSets.md) 会调用 `OpenGLDescriptorSet::BindWithPipelineLayout(...)`
| [SetIndexBuffer](SetIndexBuffer.md) | 设置相关状态或配置。 | - [`SetVertexBuffers`](SetVertexBuffers.md) 会使用内部 VAO，并尽量按照当前 `OpenGLPipelineState` 的 input layout 配置 vertex attribute
| [SetVertexBuffer](SetVertexBuffer.md) | 设置相关状态或配置。 | - [`SetIndexBuffer`](SetIndexBuffer.md) 绑定 `GL_ELEMENT_ARRAY_BUFFER`，并缓存 index type 与偏移
| [BindVertexArray](BindVertexArray.md) | 公开方法，详见头文件声明。 |
| [UseShader](UseShader.md) | 公开方法，详见头文件声明。 | ### 绘制与计算
| [SetViewport](SetViewport.md) | 设置相关状态或配置。 |
| [SetViewports](SetViewports.md) | 设置相关状态或配置。 | - [`Draw`](Draw.md) 直接调用 `glDrawArraysInstanced(...)`
| [SetScissor](SetScissor.md) | 设置相关状态或配置。 | - [`DrawIndexed`](DrawIndexed.md) 直接调用 `glDrawElementsInstanced(...)`
| [SetScissorRects](SetScissorRects.md) | 设置相关状态或配置。 | - `baseVertex` 与 `startInstance` 当前都没有真实生效
| [EnableScissorTest](EnableScissorTest.md) | 公开方法，详见头文件声明。 | - [`Dispatch`](Dispatch.md) 直接调用 `glDispatchCompute(...)`
| [EnableDepthTest](EnableDepthTest.md) | 公开方法，详见头文件声明。 |
| [EnableDepthWrite](EnableDepthWrite.md) | 公开方法，详见头文件声明。 | ## 当前限制
| [SetDepthFunc](SetDepthFunc.md) | 设置相关状态或配置。 |
| [EnableStencilTest](EnableStencilTest.md) | 公开方法，详见头文件声明。 | - 不是录制型命令缓冲，很多调用会立刻影响当前上下文
| [SetStencilFunc](SetStencilFunc.md) | 设置相关状态或配置。 | - `Close()` 当前为空实现
| [SetStencilOp](SetStencilOp.md) | 设置相关状态或配置。 | - `DrawIndexed()` 不使用 `baseVertex`
| [EnableBlending](EnableBlending.md) | 公开方法，详见头文件声明。 | - `SetStencilRef()` 当前通过 `glStencilFunc(GL_FRONT_AND_BACK, ...)` 设置，语义比较粗
| [SetBlendFunc](SetBlendFunc.md) | 设置相关状态或配置。 |
| [SetBlendFuncSeparate](SetBlendFuncSeparate.md) | 设置相关状态或配置。 | ## 重点公共方法
| [SetBlendEquation](SetBlendEquation.md) | 设置相关状态或配置。 |
| [SetBlendColor](SetBlendColor.md) | 设置相关状态或配置。 | - [TransitionBarrier](TransitionBarrier.md)
| [EnableCulling](EnableCulling.md) | 公开方法，详见头文件声明。 | - [BeginRenderPass](BeginRenderPass.md)
| [SetCullFace](SetCullFace.md) | 设置相关状态或配置。 | - [SetRenderTargets](SetRenderTargets.md)
| [SetFrontFace](SetFrontFace.md) | 设置相关状态或配置。 | - [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md)
| [SetPolygonMode](SetPolygonMode.md) | 设置相关状态或配置。 | - [SetComputeDescriptorSets](SetComputeDescriptorSets.md)
| [SetPolygonOffset](SetPolygonOffset.md) | 设置相关状态或配置。 | - [SetVertexBuffers](SetVertexBuffers.md)
| [SetPrimitiveType](SetPrimitiveType.md) | 设置相关状态或配置。 | - [SetIndexBuffer](SetIndexBuffer.md)
| [Draw](Draw.md) | 公开方法，详见头文件声明。 | - [CopyResource](CopyResource.md)
| [DrawInstanced](DrawInstanced.md) | 公开方法，详见头文件声明。 | - [Draw](Draw.md)
| [DrawIndexed](DrawIndexed.md) | 公开方法，详见头文件声明。 | - [DrawIndexed](DrawIndexed.md)
| [DrawIndexedInstanced](DrawIndexedInstanced.md) | 公开方法，详见头文件声明。 | - [Dispatch](Dispatch.md)
| [DrawIndirect](DrawIndirect.md) | 公开方法，详见头文件声明。 |
| [DrawIndexedIndirect](DrawIndexedIndirect.md) | 公开方法，详见头文件声明。 |
| [MultiDrawArrays](MultiDrawArrays.md) | 公开方法，详见头文件声明。 |
| [MultiDrawElements](MultiDrawElements.md) | 公开方法，详见头文件声明。 |
| [Dispatch](Dispatch.md) | 公开方法，详见头文件声明。 |
| [DispatchIndirect](DispatchIndirect.md) | 公开方法，详见头文件声明。 |
| [DispatchCompute](DispatchCompute.md) | 公开方法，详见头文件声明。 |
| [MemoryBarrier](MemoryBarrier.md) | 公开方法，详见头文件声明。 |
| [TextureBarrier](TextureBarrier.md) | 公开方法，详见头文件声明。 |
| [BindTexture](BindTexture.md) | 公开方法，详见头文件声明。 |
| [BindTextures](BindTextures.md) | 公开方法，详见头文件声明。 |
| [BindSampler](BindSampler.md) | 公开方法，详见头文件声明。 |
| [BindSamplers](BindSamplers.md) | 公开方法，详见头文件声明。 |
| [BindImageTexture](BindImageTexture.md) | 公开方法，详见头文件声明。 |
| [BindBufferBase](BindBufferBase.md) | 公开方法，详见头文件声明。 |
| [BindBufferRange](BindBufferRange.md) | 公开方法，详见头文件声明。 |
| [Enable](Enable.md) | 公开方法，详见头文件声明。 |
| [Disable](Disable.md) | 公开方法，详见头文件声明。 |
| [Enablei](Enablei.md) | 公开方法，详见头文件声明。 |
| [Disablei](Disablei.md) | 公开方法，详见头文件声明。 |
| [SetUniform1i](SetUniform1i.md) | 设置相关状态或配置。 |
| [SetUniform1f](SetUniform1f.md) | 设置相关状态或配置。 |
| [SetUniform2f](SetUniform2f.md) | 设置相关状态或配置。 |
| [SetUniform3f](SetUniform3f.md) | 设置相关状态或配置。 |
| [SetUniform4f](SetUniform4f.md) | 设置相关状态或配置。 |
| [SetUniform1fv](SetUniform1fv.md) | 设置相关状态或配置。 |
| [SetUniform2fv](SetUniform2fv.md) | 设置相关状态或配置。 |
| [SetUniform3fv](SetUniform3fv.md) | 设置相关状态或配置。 |
| [SetUniform4fv](SetUniform4fv.md) | 设置相关状态或配置。 |
| [SetUniformMatrix4fv](SetUniformMatrix4fv.md) | 设置相关状态或配置。 |
| [UseProgram](UseProgram.md) | 公开方法，详见头文件声明。 |
| [BindFragDataLocation](BindFragDataLocation.md) | 公开方法，详见头文件声明。 |
| [BindFragDataLocationIndexed](BindFragDataLocationIndexed.md) | 公开方法，详见头文件声明。 |
| [BeginQuery](BeginQuery.md) | 公开方法，详见头文件声明。 |
| [EndQuery](EndQuery.md) | 公开方法，详见头文件声明。 |
| [GetQueryObjectiv](GetQueryObjectiv.md) | 获取相关状态或对象。 |
| [GetQueryObjectuiv](GetQueryObjectuiv.md) | 获取相关状态或对象。 |
| [ReadPixels](ReadPixels.md) | 公开方法，详见头文件声明。 |
| [BlitFramebuffer](BlitFramebuffer.md) | 公开方法，详见头文件声明。 |
| [CopyImageSubData](CopyImageSubData.md) | 公开方法，详见头文件声明。 |
| [CopyResource](CopyResource.md) | 公开方法，详见头文件声明。 |
| [InvalidateFramebuffer](InvalidateFramebuffer.md) | 公开方法，详见头文件声明。 |
| [InvalidateSubFramebuffer](InvalidateSubFramebuffer.md) | 公开方法，详见头文件声明。 |
| [PushDebugGroup](PushDebugGroup.md) | 公开方法，详见头文件声明。 |
| [PopDebugGroup](PopDebugGroup.md) | 公开方法，详见头文件声明。 |
| [TransitionBarrier](TransitionBarrier.md) | 公开方法，详见头文件声明。 |
| [BeginRenderPass](BeginRenderPass.md) | 公开方法，详见头文件声明。 |
| [EndRenderPass](EndRenderPass.md) | 公开方法，详见头文件声明。 |
| [SetPrimitiveTopology](SetPrimitiveTopology.md) | 设置相关状态或配置。 |
| [SetScissorRect](SetScissorRect.md) | 设置相关状态或配置。 |
| [SetRenderTargets](SetRenderTargets.md) | 设置相关状态或配置。 |
| [SetStencilRef](SetStencilRef.md) | 设置相关状态或配置。 |
| [SetBlendFactor](SetBlendFactor.md) | 设置相关状态或配置。 |
| [ClearRenderTarget](ClearRenderTarget.md) | 清空内部数据。 |
## 相关文档 ## 相关文档
- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录 - [OpenGL](../OpenGL.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md)
- [OpenGLDescriptorSet](../OpenGLDescriptorSet/OpenGLDescriptorSet.md)

30
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetComputeDescriptorSets.md
View File

@@ -1,34 +1,22 @@
# OpenGLCommandList::SetComputeDescriptorSets # OpenGLCommandList::SetComputeDescriptorSets
设置相关状态或配置。
```cpp ```cpp
void SetComputeDescriptorSets( uint32_t firstSet, uint32_t count, RHIDescriptorSet** descriptorSets, RHIPipelineLayout* pipelineLayout) override; void SetComputeDescriptorSets(uint32_t firstSet, uint32_t count, RHIDescriptorSet** descriptorSets, RHIPipelineLayout* pipelineLayout) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把一组 descriptor set 绑定到 compute 路径。
- `firstSet` - 参数语义详见头文件声明。
- `count` - 参数语义详见头文件声明。
- `descriptorSets` - 参数语义详见头文件声明。
- `pipelineLayout` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** 实现与 [`SetGraphicsDescriptorSets`](SetGraphicsDescriptorSets.md) 基本相同，同样依赖 `OpenGLDescriptorSet::BindWithPipelineLayout(...)`。
```cpp ## 设计说明
#include <XCEngine/RHI/OpenGL/OpenGLCommandList.h>
void Example() { 在当前 OpenGL 后端里，graphics/compute 资源绑定并没有完全不同的两套容器模型，差别主要体现在最终 program 的使用方式和某些资源目标的解释上。
XCEngine::RHI::OpenGLCommandList object;
// 根据上下文补齐参数后调用 OpenGLCommandList::SetComputeDescriptorSets(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandList.md) - [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md)
- [返回模块目录](../OpenGL.md) - [Dispatch](Dispatch.md)

39
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetGraphicsDescriptorSets.md
View File

@@ -1,34 +1,31 @@
# OpenGLCommandList::SetGraphicsDescriptorSets # OpenGLCommandList::SetGraphicsDescriptorSets
设置相关状态或配置。
```cpp ```cpp
void SetGraphicsDescriptorSets( uint32_t firstSet, uint32_t count, RHIDescriptorSet** descriptorSets, RHIPipelineLayout* pipelineLayout) override; void SetGraphicsDescriptorSets(uint32_t firstSet, uint32_t count, RHIDescriptorSet** descriptorSets, RHIPipelineLayout* pipelineLayout) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把一组 descriptor set 绑定到 graphics 路径。
- `firstSet` - 参数语义详见头文件声明。
- `count` - 参数语义详见头文件声明。
- `descriptorSets` - 参数语义详见头文件声明。
- `pipelineLayout` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 把 `pipelineLayout` 转成 `OpenGLPipelineLayout`
- 对每个非空 descriptor set 调用：
- `OpenGLDescriptorSet::BindWithPipelineLayout(openGLPipelineLayout, firstSet + i)`
```cpp ## 正确理解
#include <XCEngine/RHI/OpenGL/OpenGLCommandList.h>
void Example() { 这里绑定的不是 D3D12/Vulkan 意义上的原生 descriptor table，而是：
XCEngine::RHI::OpenGLCommandList object;
// 根据上下文补齐参数后调用 OpenGLCommandList::SetGraphicsDescriptorSets(...)。 - uniform buffer binding point
(void)object; - texture unit
} - sampler binding point
``` - image unit
的统一适配。
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandList.md) - [SetComputeDescriptorSets](SetComputeDescriptorSets.md)
- [返回模块目录](../OpenGL.md) - [OpenGLDescriptorSet](../OpenGLDescriptorSet/OpenGLDescriptorSet.md)

56
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetIndexBuffer.md
View File

@@ -1,59 +1,21 @@
# OpenGLCommandList::SetIndexBuffer # OpenGLCommandList::SetIndexBuffer
设置相关状态或配置。
该方法在 `XCEngine/RHI/OpenGL/OpenGLCommandList.h` 中提供了 3 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
void SetIndexBuffer(RHIResourceView* buffer, uint64_t offset) override; void SetIndexBuffer(RHIResourceView* buffer, uint64_t offset) override;
``` ```
**参数：** ## 作用
- `buffer` - 参数语义详见头文件声明。
- `offset` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 绑定索引缓冲，并缓存索引格式与字节偏移。
## 重载 2: 声明 ## 当前实现行为
```cpp - 确保内部 VAO 已绑定
void SetIndexBuffer(unsigned int buffer, unsigned int type); - 把 view 底层 buffer 绑定到 `GL_ELEMENT_ARRAY_BUFFER`
``` - 根据 view 的 `Format` 推导 `GL_UNSIGNED_SHORT` 或 `GL_UNSIGNED_INT`
- 缓存 `m_currentIndexType` 和 `m_currentIndexOffset`
**参数：**
- `buffer` - 参数语义详见头文件声明。
- `type` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
## 重载 3: 声明
```cpp
void SetIndexBuffer(unsigned int buffer, unsigned int type, size_t offset);
```
**参数：**
- `buffer` - 参数语义详见头文件声明。
- `type` - 参数语义详见头文件声明。
- `offset` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
**示例：**
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLCommandList.h>
void Example() {
XCEngine::RHI::OpenGLCommandList object;
// 根据上下文补齐参数后调用 OpenGLCommandList::SetIndexBuffer(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandList.md) - [SetVertexBuffers](SetVertexBuffers.md)
- [返回模块目录](../OpenGL.md) - [DrawIndexed](DrawIndexed.md)

32
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetRenderTargets.md
View File

@@ -1,33 +1,27 @@
# OpenGLCommandList::SetRenderTargets # OpenGLCommandList::SetRenderTargets
设置相关状态或配置。
```cpp ```cpp
void SetRenderTargets(uint32_t count, RHIResourceView** renderTargets, RHIResourceView* depthStencil = nullptr) override; void SetRenderTargets(uint32_t count, RHIResourceView** renderTargets, RHIResourceView* depthStencil = nullptr) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 设置当前绘制输出目标。
- `count` - 参数语义详见头文件声明。
- `renderTargets` - 参数语义详见头文件声明。
- `depthStencil` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 若存在多个颜色附件，或同时存在颜色附件与深度附件：
- 动态创建一个临时 `OpenGLFramebuffer`
- 把传入的附件重新组合进这个 framebuffer
- 若只有单个颜色附件，则直接绑定该 view 自带的 framebuffer
- 若只有深度附件，则绑定深度 view 的 framebuffer 并关闭 draw buffers
- 若没有任何附件，则绑定默认 framebuffer
```cpp ## 设计说明
#include <XCEngine/RHI/OpenGL/OpenGLCommandList.h>
void Example() { 这条实现体现了 OpenGL 后端的一个关键现实：抽象层可以把“颜色附件视图”和“深度附件视图”分开传入，但最终 OpenGL 仍需要一个具体 framebuffer 对象来承载组合结果。
XCEngine::RHI::OpenGLCommandList object;
// 根据上下文补齐参数后调用 OpenGLCommandList::SetRenderTargets(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandList.md) - [BeginRenderPass](BeginRenderPass.md)
- [返回模块目录](../OpenGL.md) - [CopyResource](CopyResource.md)

51
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetVertexBuffers.md
View File

@@ -1,52 +1,27 @@
# OpenGLCommandList::SetVertexBuffers # OpenGLCommandList::SetVertexBuffers
设置相关状态或配置。
该方法在 `XCEngine/RHI/OpenGL/OpenGLCommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
void SetVertexBuffers(uint32_t startSlot, uint32_t count, RHIResourceView** buffers, const uint64_t* offsets, const uint32_t* strides) override; void SetVertexBuffers(uint32_t startSlot, uint32_t count, RHIResourceView** buffers, const uint64_t* offsets, const uint32_t* strides) override;
``` ```
**参数：** ## 作用
- `startSlot` - 参数语义详见头文件声明。
- `count` - 参数语义详见头文件声明。
- `buffers` - 参数语义详见头文件声明。
- `offsets` - 参数语义详见头文件声明。
- `strides` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 为当前输入布局配置顶点属性，并绑定顶点缓冲。
## 重载 2: 声明 ## 当前实现行为
```cpp - 确保内部 VAO 已创建并绑定
void SetVertexBuffers(unsigned int startSlot, unsigned int count, const unsigned int* buffers, const size_t* offsets, const size_t* strides); - 先禁用上一次配置过的顶点属性
``` - 如果当前存在 `OpenGLPipelineState` 且其 `InputLayoutDesc` 非空：
- 按 input layout 逐元素配置 `glVertexAttribPointer` 或 `glVertexAttribIPointer`
- 否则走退化路径：
- 按 slot 顺序把每个 buffer 当作一组连续 float 属性
**参数：** ## 设计说明
- `startSlot` - 参数语义详见头文件声明。
- `count` - 参数语义详见头文件声明。
- `buffers` - 参数语义详见头文件声明。
- `offsets` - 参数语义详见头文件声明。
- `strides` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 OpenGL 顶点输入配置强依赖 VAO 和当前 attribute 状态，因此这里需要命令列表自己维护一个内部 VAO，来把抽象层的输入布局概念落到 GL 状态机上。
**示例：**
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLCommandList.h>
void Example() {
XCEngine::RHI::OpenGLCommandList object;
// 根据上下文补齐参数后调用 OpenGLCommandList::SetVertexBuffers(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandList.md) - [SetIndexBuffer](SetIndexBuffer.md)
- [返回模块目录](../OpenGL.md) - [Draw](Draw.md)

32
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/TransitionBarrier.md
View File

@@ -1,33 +1,27 @@
# OpenGLCommandList::TransitionBarrier # OpenGLCommandList::TransitionBarrier
公开方法，详见头文件声明。
```cpp ```cpp
void TransitionBarrier(RHIResourceView* resource, ResourceStates stateBefore, ResourceStates stateAfter) override; void TransitionBarrier(RHIResourceView* resource, ResourceStates stateBefore, ResourceStates stateAfter) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 在 OpenGL 后端里表达一次抽象资源状态转换。
- `resource` - 参数语义详见头文件声明。
- `stateBefore` - 参数语义详见头文件声明。
- `stateAfter` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - `stateBefore` 当前不参与逻辑
- 若 view 指向纹理资源，则把该纹理的软状态改成 `stateAfter`
- 随后无条件调用 `glMemoryBarrier(GL_ALL_BARRIER_BITS)`
```cpp ## 正确理解
#include <XCEngine/RHI/OpenGL/OpenGLCommandList.h>
void Example() { 这不是 D3D12/Vulkan 那种精确资源状态机。它更像：
XCEngine::RHI::OpenGLCommandList object;
// 根据上下文补齐参数后调用 OpenGLCommandList::TransitionBarrier(...)。 - 抽象层状态字段更新
(void)object; - 外加一条最保守的全局内存屏障
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandList.md) - [SetRenderTargets](SetRenderTargets.md)
- [返回模块目录](../OpenGL.md) - [Dispatch](Dispatch.md)

26
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/ExecuteCommandLists.md
View File

@@ -1,32 +1,22 @@
# OpenGLCommandQueue::ExecuteCommandLists # OpenGLCommandQueue::ExecuteCommandLists
公开方法，详见头文件声明。
```cpp ```cpp
void ExecuteCommandLists(uint32_t count, void** lists) override; void ExecuteCommandLists(uint32_t count, void** lists) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 抽象层保留的“提交命令列表”入口。
- `count` - 参数语义详见头文件声明。
- `lists` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** 当前实现为空。
```cpp ## 正确理解
#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
void Example() { 这并不是疏漏，而是当前 OpenGL 后端架构决定的结果：`OpenGLCommandList` 上的大部分操作会立刻作用到当前上下文，因此这里不存在 D3D12/Vulkan 意义上的“统一提交时刻”。
XCEngine::RHI::OpenGLCommandQueue object;
// 根据上下文补齐参数后调用 OpenGLCommandQueue::ExecuteCommandLists(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandQueue.md) - [OpenGLCommandQueue](OpenGLCommandQueue.md)
- [返回模块目录](../OpenGL.md) - [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)

55
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/OpenGLCommandQueue.md
View File

@@ -6,37 +6,42 @@
**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h` **头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`
**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLCommandQueue` public API。 **描述**: 为统一 RHI 抽象保留的 OpenGL 队列门面；它不是一条真实的 GPU 提交队列。
## 概述 ## 概览
`OpenGLCommandQueue.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 OpenGL 没有 D3D12/Vulkan 那种显式命令队列模型，所以 `OpenGLCommandQueue` 的主要价值是：
## 声明概览 - 让统一抽象层还能继续通过 `RHICommandQueue` 组织代码
- 提供少量和 flush / finish / fence 相关的后端适配
| 声明 | 类型 | 说明 | ## 当前实现的真实行为
|------|------|------|
| `OpenGLCommandQueue` | `class` | 继承自 `RHICommandQueue` 的公开声明。 |
## 公共方法 - `GetType()` 永远返回 `CommandQueueType::Direct`
- `ExecuteCommandLists()` 当前为空实现
- `Signal()` 会先调用抽象 fence 的 `Signal(value)`，再 `glFlush()`
- `Wait()` 当前为空实现
- `GetCompletedValue()` 当前固定返回 `0`
- `WaitForIdle()` 调用 `glFinish()`
- `GetTimestampFrequency()` 读取 `GL_TIMESTAMP`；这更像“当前时间戳查询”，不是严格意义上的硬件频率接口
| 方法 | 描述 | ## 正确理解
|------|------|
| [OpenGLCommandQueue()](Constructor.md) | 构造对象。 | 如果从商业引擎角度看，它更像“为了保持跨后端接口整齐而保留的一层 shim”，而不是调度核心。
| [~OpenGLCommandQueue()](Destructor.md) | 销毁对象并释放相关资源。 |
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | ## 当前限制
| [ExecuteCommandLists](ExecuteCommandLists.md) | 公开方法，详见头文件声明。 |
| [Signal](Signal.md) | 公开方法，详见头文件声明。 | - 不支持真正的命令列表提交
| [Wait](Wait.md) | 公开方法，详见头文件声明。 | - 不提供成熟的 GPU timeline 语义
| [GetCompletedValue](GetCompletedValue.md) | 获取相关状态或对象。 | - `Wait()` / `ExecuteCommandLists()` 仍是占位实现
| [WaitForIdle](WaitForIdle.md) | 公开方法，详见头文件声明。 |
| [GetType](GetType.md) | 获取相关状态或对象。 | ## 重点公共方法
| [GetTimestampFrequency](GetTimestampFrequency.md) | 获取相关状态或对象。 |
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | - [ExecuteCommandLists](ExecuteCommandLists.md)
| [WaitForPreviousFrame](WaitForPreviousFrame.md) | 公开方法，详见头文件声明。 | - [Signal](Signal.md)
| [GetCurrentFrame](GetCurrentFrame.md) | 获取相关状态或对象。 | - [WaitForIdle](WaitForIdle.md)
## 相关文档 ## 相关文档
- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录 - [OpenGL](../OpenGL.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)

27
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Signal.md
View File

@@ -1,32 +1,19 @@
# OpenGLCommandQueue::Signal # OpenGLCommandQueue::Signal
公开方法，详见头文件声明。
```cpp ```cpp
void Signal(RHIFence* fence, uint64_t value) override; void Signal(RHIFence* fence, uint64_t value) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 给抽象 fence 写入一个值，并通过 `glFlush()` 触发驱动尽快开始处理已发出的 OpenGL 命令。
- `fence` - 参数语义详见头文件声明。
- `value` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 若 `fence` 非空，则调用 `fence->Signal(value)`
- 随后调用 `glFlush()`
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
void Example() {
XCEngine::RHI::OpenGLCommandQueue object;
// 根据上下文补齐参数后调用 OpenGLCommandQueue::Signal(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandQueue.md) - [WaitForIdle](WaitForIdle.md)
- [返回模块目录](../OpenGL.md) - [OpenGLCommandQueue](OpenGLCommandQueue.md)

24
docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForIdle.md
View File

@@ -1,30 +1,22 @@
# OpenGLCommandQueue::WaitForIdle # OpenGLCommandQueue::WaitForIdle
公开方法，详见头文件声明。
```cpp ```cpp
void WaitForIdle() override; void WaitForIdle() override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 阻塞 CPU，直到当前上下文之前发出的 OpenGL 命令全部完成。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** 直接调用 `glFinish()`。
```cpp ## 设计说明
#include <XCEngine/RHI/OpenGL/OpenGLCommandQueue.h>
void Example() { 这是一条非常强的同步原语，适合初始化、截图、调试和测试，不适合高频帧循环。
XCEngine::RHI::OpenGLCommandQueue object;
// 根据上下文补齐参数后调用 OpenGLCommandQueue::WaitForIdle(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLCommandQueue.md) - [Signal](Signal.md)
- [返回模块目录](../OpenGL.md) - [OpenGLCommandQueue](OpenGLCommandQueue.md)

32
docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreatePipelineState.md
View File

@@ -1,31 +1,29 @@
# OpenGLDevice::CreatePipelineState # OpenGLDevice::CreatePipelineState
创建新对象或资源。
```cpp ```cpp
RHIPipelineState* CreatePipelineState(const GraphicsPipelineDesc& desc) override; RHIPipelineState* CreatePipelineState(const GraphicsPipelineDesc& desc) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 创建一份 OpenGL 管线状态对象，并在需要时同时构建 graphics program。
- `desc` - 参数语义详见头文件声明。
**返回：** `RHIPipelineState*` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 总是先创建 `OpenGLPipelineState`
- 把输入布局、光栅化、混合、深度模板、拓扑、RT format、sample count 写入该对象
- 若没有任何 graphics shader payload，直接返回仅含状态的 PSO
- 若有 shader payload，则要求至少同时存在 vertex 和 fragment shader
- 会 `MakeContextCurrent()`
- 根据源码或文件路径构建 `OpenGLShader`
- 成功后把该 shader 作为 owned graphics shader 挂到 PSO 上
```cpp ## 返回值
#include <XCEngine/RHI/OpenGL/OpenGLDevice.h>
void Example() { - 成功返回 `OpenGLPipelineState*`
XCEngine::RHI::OpenGLDevice object; - shader 不完整、上下文不可用或编译失败时返回 `nullptr`
// 根据上下文补齐参数后调用 OpenGLDevice::CreatePipelineState(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLDevice.md) - [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md)
- [返回模块目录](../OpenGL.md) - [CreateShader](CreateShader.md)

28
docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateShader.md
View File

@@ -1,31 +1,25 @@
# OpenGLDevice::CreateShader # OpenGLDevice::CreateShader
创建新对象或资源。
```cpp ```cpp
RHIShader* CreateShader(const ShaderCompileDesc& desc) override; RHIShader* CreateShader(const ShaderCompileDesc& desc) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 在当前 OpenGL 上下文中创建并编译一个 `OpenGLShader`。
- `desc` - 参数语义详见头文件声明。
**返回：** `RHIShader*` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 先 `MakeContextCurrent()`
- 若 `desc.sourceLanguage == ShaderLanguage::GLSL` 且提供了源码，走源码编译路径
- 若提供了 `fileName`，走文件编译路径
- 其他情况直接失败
```cpp ## 注意事项
#include <XCEngine/RHI/OpenGL/OpenGLDevice.h>
void Example() { 当前实现不负责 HLSL 到 GLSL 的转换；这里期待的就是 GLSL 源码或 GLSL 文件。
XCEngine::RHI::OpenGLDevice object;
// 根据上下文补齐参数后调用 OpenGLDevice::CreateShader(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLDevice.md) - [OpenGLShader](../OpenGLShader/OpenGLShader.md)
- [返回模块目录](../OpenGL.md) - [CreatePipelineState](CreatePipelineState.md)

54
docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateTexture.md
View File

@@ -1,47 +1,35 @@
# OpenGLDevice::CreateTexture # OpenGLDevice::CreateTexture
创建新对象或资源。
该方法在 `XCEngine/RHI/OpenGL/OpenGLDevice.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
RHITexture* CreateTexture(const TextureDesc& desc) override; RHITexture* CreateTexture(const TextureDesc& desc) override;
```
**参数：**
- `desc` - 参数语义详见头文件声明。
**返回：** `RHITexture*` - 返回值语义详见头文件声明。
## 重载 2: 声明
```cpp
RHITexture* CreateTexture(const TextureDesc& desc, const void* initialData, size_t initialDataSize, uint32_t rowPitch = 0) override; RHITexture* CreateTexture(const TextureDesc& desc, const void* initialData, size_t initialDataSize, uint32_t rowPitch = 0) override;
``` ```
**参数：** ## 作用
- `desc` - 参数语义详见头文件声明。
- `initialData` - 参数语义详见头文件声明。
- `initialDataSize` - 参数语义详见头文件声明。
- `rowPitch` - 参数语义详见头文件声明。
**返回：** `RHITexture*` - 返回值语义详见头文件声明。 创建 OpenGL 纹理对象；可选地带一份初始数据。
**示例：** ## 当前实现行为
```cpp ### 无初始数据路径
#include <XCEngine/RHI/OpenGL/OpenGLDevice.h>
void Example() { - 根据 `TextureType` 选择 `OpenGLTextureType`
XCEngine::RHI::OpenGLDevice object; - 把抽象 `Format` 转为 `OpenGLFormat`
// 根据上下文补齐参数后调用 OpenGLDevice::CreateTexture(...)。 - 调用 `OpenGLTexture::Initialize(...)`
(void)object; - 设置抽象层格式字段
}
``` ### 带初始数据路径
- 会先 `MakeContextCurrent()`
- 只在当前上下文可用时继续
- 初始化成功后把纹理状态设为 `ResourceStates::PixelShaderResource`
## 注意事项
- 带初始数据路径显式保证了上下文当前；无初始数据路径则默认假设当前上下文已经可用
- `rowPitch` 和 `initialDataSize` 当前没有形成复杂的数据上传策略
## 相关文档 ## 相关文档
- [返回类总览](OpenGLDevice.md) - [OpenGLDevice](OpenGLDevice.md)
- [返回模块目录](../OpenGL.md) - [OpenGLTexture](../OpenGLTexture/OpenGLTexture.md)

34
docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Initialize.md
View File

@@ -1,31 +1,31 @@
# OpenGLDevice::Initialize # OpenGLDevice::Initialize
初始化内部状态。
```cpp ```cpp
bool Initialize(const RHIDeviceDesc& desc) override; bool Initialize(const RHIDeviceDesc& desc) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 创建隐藏窗口并在其上建立 OpenGL 上下文，初始化当前设备。
- `desc` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 若设备已经初始化，直接返回 `true`
- 忽略 `desc` 中的大部分字段
- 创建隐藏窗口
- 调用 `AttachWindow(...)`
- `AttachWindow(...)` 会继续配置像素格式、建立上下文、加载 GLAD 并填充能力信息
```cpp ## 设计说明
#include <XCEngine/RHI/OpenGL/OpenGLDevice.h>
void Example() { 这条路径适合无现成窗口的测试、离屏初始化和工具场景。它让 OpenGL 后端能像显式 API 一样先把“设备”建起来，再逐步创建资源。
XCEngine::RHI::OpenGLDevice object;
// 根据上下文补齐参数后调用 OpenGLDevice::Initialize(...)。 ## 返回值
(void)object;
} - `true`：上下文已可用
``` - `false`：窗口、像素格式或上下文建立失败
## 相关文档 ## 相关文档
- [返回类总览](OpenGLDevice.md) - [InitializeWithExistingWindow](InitializeWithExistingWindow.md)
- [返回模块目录](../OpenGL.md) - [OpenGLDevice](OpenGLDevice.md)

30
docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/InitializeWithExistingWindow.md
View File

@@ -1,31 +1,27 @@
# OpenGLDevice::InitializeWithExistingWindow # OpenGLDevice::InitializeWithExistingWindow
初始化内部状态。
```cpp ```cpp
bool InitializeWithExistingWindow(HWND hwnd); bool InitializeWithExistingWindow(HWND hwnd);
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把 OpenGL 设备附着到调用方已经拥有的窗口上。
- `hwnd` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 若设备尚未初始化：
- 要求 `hwnd` 非空
- 直接走 `AttachWindow(hwnd)`
- 若设备已初始化：
- 若传入的就是当前窗口，返回 `true`
- 否则尝试切换附着窗口
```cpp ## 适用场景
#include <XCEngine/RHI/OpenGL/OpenGLDevice.h>
void Example() { 这是交换链、实时窗口渲染和编辑器嵌入式视口更常用的路径。
XCEngine::RHI::OpenGLDevice object;
// 根据上下文补齐参数后调用 OpenGLDevice::InitializeWithExistingWindow(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLDevice.md) - [Initialize](Initialize.md)
- [返回模块目录](../OpenGL.md) - [CreateTexture](CreateTexture.md)

101
docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/OpenGLDevice.md
View File

@@ -6,56 +6,69 @@
**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` **头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h`
**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLDevice` public API。 **描述**: OpenGL 后端的设备根对象，负责创建或接管 Win32 窗口上的 WGL 上下文、探测 OpenGL 能力，并作为 OpenGL 资源工厂入口。
## 概述 ## 概览
`OpenGLDevice.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `OpenGLDevice` 不是“GPU 设备对象”的严格硬件抽象，而更像“当前 OpenGL 上下文与其周边服务的拥有者”。它负责：
## 声明概览 - 管理窗口句柄、设备上下文和渲染上下文
- 尝试创建 debug context
- 初始化 GLAD
- 收集驱动、版本和能力信息
- 创建 OpenGL 风格的 buffer、texture、shader、pipeline state、descriptor pool 等对象
| 声明 | 类型 | 说明 | ## 生命周期
|------|------|------|
| `OpenGLDevice` | `class` | 继承自 `RHIDevice` 的公开声明。 |
## 公共方法 支持两种典型用法：
| 方法 | 描述 | 1. 通过 [`Initialize`](Initialize.md) 让设备自己创建隐藏窗口和上下文
|------|------| 2. 通过 [`InitializeWithExistingWindow`](InitializeWithExistingWindow.md) 绑定到现有窗口
| [OpenGLDevice()](Constructor.md) | 构造对象。 |
| [~OpenGLDevice()](Destructor.md) | 销毁对象并释放相关资源。 | ## 当前实现的真实行为
| [Initialize](Initialize.md) | 初始化内部状态。 |
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | ### 上下文与窗口管理
| [InitializeWithExistingWindow](InitializeWithExistingWindow.md) | 初始化内部状态。 |
| [GetDeviceInfoImpl](GetDeviceInfoImpl.md) | 获取相关状态或对象。 | - 若走 `Initialize()`，设备会创建一个隐藏窗口，再附着像素格式并建立上下文
| [MakeContextCurrent](MakeContextCurrent.md) | 公开方法，详见头文件声明。 | - 若走 `InitializeWithExistingWindow()`，设备会直接接管调用方窗口
| [GetNativeContext](GetNativeContext.md) | 获取相关状态或对象。 | - 会先用临时 context 探测 `WGL_ARB_create_context`，再尝试创建 OpenGL 4.6 debug context
| [CreateBuffer](CreateBuffer.md) | 创建新对象或资源。 | - 若高级上下文创建失败，会回退到 `wglCreateContext()`
| [CreateTexture](CreateTexture.md) | 创建新对象或资源。 |
| [CreateSwapChain](CreateSwapChain.md) | 创建新对象或资源。 | ### 能力和设备信息
| [CreateCommandList](CreateCommandList.md) | 创建新对象或资源。 |
| [CreateCommandQueue](CreateCommandQueue.md) | 创建新对象或资源。 | - `vendor`、`renderer`、`version` 来自 `glGetString(...)`
| [CreateShader](CreateShader.md) | 创建新对象或资源。 | - `vendorId` 由厂商字符串启发式推断
| [CreatePipelineState](CreatePipelineState.md) | 创建新对象或资源。 | - `deviceId` 由 renderer 字符串哈希得到，不是真实 PCI device id
| [CreatePipelineLayout](CreatePipelineLayout.md) | 创建新对象或资源。 | - `dedicatedVideoMemory` 在非软件渲染器情况下被写成 `1`，这只是“非零哨兵值”，不是显存探测结果
| [CreateFence](CreateFence.md) | 创建新对象或资源。 |
| [CreateSampler](CreateSampler.md) | 创建新对象或资源。 | ### 工厂行为
| [CreateRenderPass](CreateRenderPass.md) | 创建新对象或资源。 |
| [CreateFramebuffer](CreateFramebuffer.md) | 创建新对象或资源。 | - [`CreateShader`](CreateShader.md) 与 [`CreatePipelineState`](CreatePipelineState.md) 会显式 `MakeContextCurrent()`
| [CreateDescriptorPool](CreateDescriptorPool.md) | 创建新对象或资源。 | - [`CreateTexture`](CreateTexture.md) 的带初始数据路径也会显式切当前上下文
| [CreateDescriptorSet](CreateDescriptorSet.md) | 创建新对象或资源。 | - `CreateCommandList()` 和 `CreateCommandQueue()` 当前只是构造轻量对象，不做和设备的深度关联
| [CreateVertexBufferView](CreateVertexBufferView.md) | 创建新对象或资源。 | - `CreateDescriptorPool()` 会把 `OpenGLTextureUnitAllocator` 注入 pool
| [CreateIndexBufferView](CreateIndexBufferView.md) | 创建新对象或资源。 |
| [CreateRenderTargetView](CreateRenderTargetView.md) | 创建新对象或资源。 | ## 设计说明
| [CreateDepthStencilView](CreateDepthStencilView.md) | 创建新对象或资源。 |
| [CreateShaderResourceView](CreateShaderResourceView.md) | 创建新对象或资源。 | OpenGL 后端的“设备”更多是上下文拥有者和运行环境协调者。它不可能像 D3D12 那样把提交、队列、同步都做成显式对象，因此文档必须把“上下文当前性”当成使用前提讲清楚。
| [CreateUnorderedAccessView](CreateUnorderedAccessView.md) | 创建新对象或资源。 |
| [GetCapabilities](GetCapabilities.md) | 获取相关状态或对象。 | ## 当前限制
| [GetDeviceInfo](GetDeviceInfo.md) | 获取相关状态或对象。 |
| [GetNativeDevice](GetNativeDevice.md) | 获取相关状态或对象。 | - 平台路径目前是 Win32/WGL
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | - 某些设备信息字段是推断值或哨兵值，不可当作驱动级精确数据
- `CreateCommandQueue()` / `CreateCommandList()` 仍是轻量门面，不要用 D3D12/Vulkan 的思维期待它们承担真实提交调度
## 重点公共方法
- [Initialize](Initialize.md)
- [InitializeWithExistingWindow](InitializeWithExistingWindow.md)
- [CreateTexture](CreateTexture.md)
- [CreateShader](CreateShader.md)
- [CreatePipelineState](CreatePipelineState.md)
## 相关文档 ## 相关文档
- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录 - [OpenGL](../OpenGL.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
- [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md)
- [OpenGLShader](../OpenGLShader/OpenGLShader.md)

29
docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/Bind.md
View File

@@ -1,30 +1,27 @@
# OpenGLPipelineState::Bind # OpenGLPipelineState::Bind
公开方法，详见头文件声明。
```cpp ```cpp
void Bind() override; void Bind() override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 把当前 `OpenGLPipelineState` 缓存的 program 和渲染状态应用到活动 OpenGL 上下文。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 若存在 compute program，优先 `glUseProgram(m_computeProgram)`
- 否则若绑定了 graphics program，则 `glUseProgram(m_program)`
- 之后调用 `Apply()`：
- `ApplyDepthStencil()`
- `ApplyBlend()`
- `ApplyRasterizer()`
```cpp ## 注意事项
#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
void Example() { 当前 `Bind()` 不会自动调用 `ApplyViewport()` 和 `ApplyScissor()`。
XCEngine::RHI::OpenGLPipelineState object;
// 根据上下文补齐参数后调用 OpenGLPipelineState::Bind(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLPipelineState.md) - [SetComputeShader](SetComputeShader.md)
- [返回模块目录](../OpenGL.md) - [OpenGLCommandList::SetPipelineState](../OpenGLCommandList/SetPipelineState.md)

93
docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/OpenGLPipelineState.md
View File

@@ -6,71 +6,46 @@
**头文件**: `XCEngine/RHI/OpenGL/OpenGLPipelineState.h` **头文件**: `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`
**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLPipelineState` public API。 **描述**: OpenGL 后端的 CPU 侧管线状态容器；它不是原生 GPU pipeline object，而是在 `Bind()` 时把缓存状态应用到当前上下文。
## 概述 ## 概览
`OpenGLPipelineState.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 在 D3D12/Vulkan 里，pipeline state 更接近“预烘焙对象”。而在当前 OpenGL 后端里，`OpenGLPipelineState` 更像一个状态包，里面存的是：
## 声明概览 - 光栅化状态
- 混合状态
- 深度模板状态
- 输入布局
- 绑定的 graphics program 或 compute program
| 声明 | 类型 | 说明 | ## 当前实现的真实行为
|------|------|------|
| `OpenGLDepthStencilState` | `struct` | 头文件中的公开声明。 |
| `OpenGLBlendState` | `struct` | 头文件中的公开声明。 |
| `OpenGLRasterizerState` | `struct` | 头文件中的公开声明。 |
| `ViewportState` | `struct` | 头文件中的公开声明。 |
| `ScissorState` | `struct` | 头文件中的公开声明。 |
| `OpenGLPipelineState` | `class` | 继承自 `RHIPipelineState` 的公开声明。 |
## 公共方法 - `Bind()`：
- 若存在 compute shader，调用 `glUseProgram(m_computeProgram)`
- 否则若绑定了 graphics program，则调用 `glUseProgram(m_program)`
- 然后执行 `Apply()`，应用深度模板、混合、光栅化状态
- `Unbind()` 会 `glUseProgram(0)`
- `IsValid()` 永远返回 `true`
- `EnsureValid()` 当前为空实现
- `SetComputeShader()` 只是缓存 shader 指针并记录 program id
- `SetRenderTargetFormats()`、`SetSampleCount()`、`GetHash()` 当前基本是占位或空实现
| 方法 | 描述 | ## 重要限制
|------|------|
| [OpenGLPipelineState()](Constructor.md) | 构造对象。 | - 这不是 OpenGL 原生对象，不要把它理解成可脱离上下文独立执行的 pipeline
| [~OpenGLPipelineState()](Destructor.md) | 销毁对象并释放相关资源。 | - `Bind()` 当前不会自动调用 `ApplyViewport()` 和 `ApplyScissor()`
| [SetInputLayout](SetInputLayout.md) | 设置相关状态或配置。 | - 因此 viewport / scissor 更常由命令列表直接设置
| [SetRasterizerState](SetRasterizerState.md) | 设置相关状态或配置。 |
| [SetBlendState](SetBlendState.md) | 设置相关状态或配置。 | ## 设计说明
| [SetDepthStencilState](SetDepthStencilState.md) | 设置相关状态或配置。 |
| [SetTopology](SetTopology.md) | 设置相关状态或配置。 | 这种做法的好处是容易把跨后端 PSO 概念统一起来；代价是它无法像显式 API 那样把“状态已经完全固化”这件事表达得很强。
| [SetRenderTargetFormats](SetRenderTargetFormats.md) | 设置相关状态或配置。 |
| [SetSampleCount](SetSampleCount.md) | 设置相关状态或配置。 | ## 重点公共方法
| [SetComputeShader](SetComputeShader.md) | 设置相关状态或配置。 |
| [GetRasterizerState](GetRasterizerState.md) | 获取相关状态或对象。 | - [Bind](Bind.md)
| [GetBlendState](GetBlendState.md) | 获取相关状态或对象。 | - [SetComputeShader](SetComputeShader.md)
| [GetDepthStencilState](GetDepthStencilState.md) | 获取相关状态或对象。 |
| [GetInputLayout](GetInputLayout.md) | 获取相关状态或对象。 |
| [GetHash](GetHash.md) | 获取相关状态或对象。 |
| [GetComputeShader](GetComputeShader.md) | 获取相关状态或对象。 |
| [HasComputeShader](HasComputeShader.md) | 判断是否具备指定状态或能力。 |
| [IsValid](IsValid.md) | 查询当前状态。 |
| [EnsureValid](EnsureValid.md) | 公开方法，详见头文件声明。 |
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
| [GetType](GetType.md) | 获取相关状态或对象。 |
| [Bind](Bind.md) | 公开方法，详见头文件声明。 |
| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 |
| [Apply](Apply.md) | 公开方法，详见头文件声明。 |
| [ApplyDepthStencil](ApplyDepthStencil.md) | 公开方法，详见头文件声明。 |
| [ApplyBlend](ApplyBlend.md) | 公开方法，详见头文件声明。 |
| [ApplyRasterizer](ApplyRasterizer.md) | 公开方法，详见头文件声明。 |
| [ApplyViewport](ApplyViewport.md) | 公开方法，详见头文件声明。 |
| [ApplyScissor](ApplyScissor.md) | 公开方法，详见头文件声明。 |
| [SetProgram](SetProgram.md) | 设置相关状态或配置。 |
| [GetProgram](GetProgram.md) | 获取相关状态或对象。 |
| [SetViewport](SetViewport.md) | 设置相关状态或配置。 |
| [SetScissor](SetScissor.md) | 设置相关状态或配置。 |
| [SetClearColor](SetClearColor.md) | 设置相关状态或配置。 |
| [Clear](Clear.md) | 清空内部数据。 |
| [AttachShader](AttachShader.md) | 公开方法，详见头文件声明。 |
| [DetachShader](DetachShader.md) | 公开方法，详见头文件声明。 |
| [SetOwnedGraphicsShader](SetOwnedGraphicsShader.md) | 设置相关状态或配置。 |
| [GetOpenGLDepthStencilState](GetOpenGLDepthStencilState.md) | 获取相关状态或对象。 |
| [GetOpenGLBlendState](GetOpenGLBlendState.md) | 获取相关状态或对象。 |
| [GetOpenGLRasterizerState](GetOpenGLRasterizerState.md) | 获取相关状态或对象。 |
## 相关文档 ## 相关文档
- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录 - [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [OpenGLShader](../OpenGLShader/OpenGLShader.md)

27
docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetComputeShader.md
View File

@@ -1,31 +1,24 @@
# OpenGLPipelineState::SetComputeShader # OpenGLPipelineState::SetComputeShader
设置相关状态或配置。
```cpp ```cpp
void SetComputeShader(RHIShader* shader) override; void SetComputeShader(RHIShader* shader) override;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 把一个 compute shader 绑定为当前 PSO 的 compute program 来源。
- `shader` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** - 缓存 `m_computeShader`
- 若 `shader != nullptr`，则把 `m_computeProgram` 设为该 `OpenGLShader` 的 program id
- 若 `shader == nullptr`，则清空 `m_computeProgram`
```cpp ## 设计说明
#include <XCEngine/RHI/OpenGL/OpenGLPipelineState.h>
void Example() { 这里并不会重新编译或链接 shader；它只是引用已有 `OpenGLShader`。
XCEngine::RHI::OpenGLPipelineState object;
// 根据上下文补齐参数后调用 OpenGLPipelineState::SetComputeShader(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLPipelineState.md) - [Bind](Bind.md)
- [返回模块目录](../OpenGL.md) - [OpenGLShader](../OpenGLShader/OpenGLShader.md)

76
docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Compile.md
View File

@@ -1,73 +1,35 @@
# OpenGLShader::Compile # OpenGLShader::Compile
公开方法，详见头文件声明。
该方法在 `XCEngine/RHI/OpenGL/OpenGLShader.h` 中提供了 4 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target) override; bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target) override;
```
**参数：**
- `sourceData` - 参数语义详见头文件声明。
- `sourceSize` - 参数语义详见头文件声明。
- `entryPoint` - 参数语义详见头文件声明。
- `target` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。
## 重载 2: 声明
```cpp
bool Compile(const char* vertexSource, const char* fragmentSource); bool Compile(const char* vertexSource, const char* fragmentSource);
```
**参数：**
- `vertexSource` - 参数语义详见头文件声明。
- `fragmentSource` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。
## 重载 3: 声明
```cpp
bool Compile(const char* vertexSource, const char* fragmentSource, const char* geometrySource); bool Compile(const char* vertexSource, const char* fragmentSource, const char* geometrySource);
```
**参数：**
- `vertexSource` - 参数语义详见头文件声明。
- `fragmentSource` - 参数语义详见头文件声明。
- `geometrySource` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。
## 重载 4: 声明
```cpp
bool Compile(const char* source, ShaderType type); bool Compile(const char* source, ShaderType type);
``` ```
**参数：** ## 作用
- `source` - 参数语义详见头文件声明。
- `type` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 从源码字符串编译并链接 OpenGL shader/program。
**示例：** ## 当前实现行为
```cpp - `sourceData` 重载：
#include <XCEngine/RHI/OpenGL/OpenGLShader.h> - 只接受文本源码
- 先用 `target` 推断 type
- 若失败，再尝试根据 GLSL 源码特征启发式判断 type
- graphics 多阶段重载：
- 分别创建 shader object
- 编译
- attach 到同一个 program
- link
- `Compile(const char*, ShaderType)`：
- 适合单阶段 program / compute path / 逐阶段 attach 逻辑
void Example() { ## 注意事项
XCEngine::RHI::OpenGLShader object;
// 根据上下文补齐参数后调用 OpenGLShader::Compile(...)。 这里的“类型推断”是启发式的，不应视为稳定资产编译系统。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLShader.md) - [CompileFromFile](CompileFromFile.md)
- [返回模块目录](../OpenGL.md) - [Use](Use.md)

28
docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileCompute.md
View File

@@ -1,31 +1,21 @@
# OpenGLShader::CompileCompute # OpenGLShader::CompileCompute
公开方法，详见头文件声明。
```cpp ```cpp
bool CompileCompute(const char* computeSource); bool CompileCompute(const char* computeSource);
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 编译并链接一个 compute program。
- `computeSource` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 当前实现行为
**示例：** - 创建 `GL_COMPUTE_SHADER`
- 编译后 attach 到新 program
```cpp - link
#include <XCEngine/RHI/OpenGL/OpenGLShader.h> - 成功后把 `m_type` 设为 `ShaderType::Compute`
void Example() {
XCEngine::RHI::OpenGLShader object;
// 根据上下文补齐参数后调用 OpenGLShader::CompileCompute(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLShader.md) - [Compile](Compile.md)
- [返回模块目录](../OpenGL.md) - [Use](Use.md)

63
docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileFromFile.md
View File

@@ -1,60 +1,33 @@
# OpenGLShader::CompileFromFile # OpenGLShader::CompileFromFile
公开方法，详见头文件声明。
该方法在 `XCEngine/RHI/OpenGL/OpenGLShader.h` 中提供了 3 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target) override; bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target) override;
```
**参数：**
- `filePath` - 参数语义详见头文件声明。
- `entryPoint` - 参数语义详见头文件声明。
- `target` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。
## 重载 2: 声明
```cpp
bool CompileFromFile(const char* vertexPath, const char* fragmentPath); bool CompileFromFile(const char* vertexPath, const char* fragmentPath);
```
**参数：**
- `vertexPath` - 参数语义详见头文件声明。
- `fragmentPath` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。
## 重载 3: 声明
```cpp
bool CompileFromFile(const char* vertexPath, const char* fragmentPath, const char* geometryPath); bool CompileFromFile(const char* vertexPath, const char* fragmentPath, const char* geometryPath);
``` ```
**参数：** ## 作用
- `vertexPath` - 参数语义详见头文件声明。
- `fragmentPath` - 参数语义详见头文件声明。
- `geometryPath` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 从文件读取 GLSL 源码并构建 OpenGL program。
**示例：** ## 当前实现行为
```cpp - `wchar_t*` 重载：
#include <XCEngine/RHI/OpenGL/OpenGLShader.h> - 把路径转为窄字符串
- 根据 `target` 或文件扩展名推断 shader type
- 读取整个文件
- 走单阶段 `Compile(source, type)` 路径
- 多文件 graphics 重载：
- 分别读取顶点/片元/几何着色器文件
- 再执行多阶段编译和链接
void Example() { ## 失败路径
XCEngine::RHI::OpenGLShader object;
// 根据上下文补齐参数后调用 OpenGLShader::CompileFromFile(...)。 - 文件打不开返回 `false`
(void)object; - 无法推断 shader type 返回 `false`
} - 任一编译或链接失败返回 `false`
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLShader.md) - [Compile](Compile.md)
- [返回模块目录](../OpenGL.md) - [CompileCompute](CompileCompute.md)

56
docs/api/XCEngine/RHI/OpenGL/OpenGLShader/OpenGLShader.md
View File

@@ -6,38 +6,42 @@
**头文件**: `XCEngine/RHI/OpenGL/OpenGLShader.h` **头文件**: `XCEngine/RHI/OpenGL/OpenGLShader.h`
**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLShader` public API。 **描述**: OpenGL 后端的着色器/程序封装，负责 GLSL 编译、链接、基础反射和 program 使用。
## 概述 ## 概览
`OpenGLShader.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `OpenGLShader` 同时承担了“单阶段 shader 编译器”和“完整 graphics/compute program 封装器”两种职责：
## 声明概览 - 多阶段 graphics program：通过顶点/片元或顶点/片元/几何路径构建
- 单阶段 shader：通过 `Compile(const void*, size_t, ...)` 或 `Compile(const char*, ShaderType)` 推断类型后编译并链接
- compute program：通过 [`CompileCompute`](CompileCompute.md) 构建
| 声明 | 类型 | 说明 | ## 当前实现的真实行为
|------|------|------|
| `OpenGLShader` | `class` | 继承自 `RHIShader` 的公开声明。 |
## 公共方法 - [`CompileFromFile`](CompileFromFile.md) 会根据 `target` 或文件扩展名推断 shader type
- [`Compile`](Compile.md) 的 `sourceData` 路径会根据 `target` 或 GLSL 源码特征猜测 shader type
- `Compile(const char*, ShaderType)` 会把 shader attach 到 `m_program` 上并立即 link
- `GetUniformInfos()` 通过 `glGetProgramInterfaceiv(GL_UNIFORM, ...)` 做反射
- `Use()` 只是 `glUseProgram(m_program)`
| 方法 | 描述 | ## 设计说明
|------|------|
| [OpenGLShader()](Constructor.md) | 构造对象。 | 当前实现追求的是“足够统一、足够易用”，而不是做一套完整的 shader asset pipeline。因此类型推断里存在明显的启发式逻辑，文档里必须明确说明，不应把它误解成强约束编译系统。
| [~OpenGLShader()](Destructor.md) | 销毁对象并释放相关资源。 |
| [CompileFromFile](CompileFromFile.md) | 公开方法，详见头文件声明。 | ## 当前限制
| [Compile](Compile.md) | 公开方法，详见头文件声明。 |
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | - `Compile(const void*, size_t, ...)` 只处理 GLSL 文本，不负责 HLSL 到 GLSL 转译
| [CompileCompute](CompileCompute.md) | 公开方法，详见头文件声明。 | - shader type 推断带启发式性质，失败时会直接返回 `false`
| [Use](Use.md) | 公开方法，详见头文件声明。 | - 链接错误和编译错误当前主要输出到标准输出
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
| [IsValid](IsValid.md) | 查询当前状态。 | ## 重点公共方法
| [GetType](GetType.md) | 获取相关状态或对象。 |
| [GetUniformInfos](GetUniformInfos.md) | 获取相关状态或对象。 | - [CompileFromFile](CompileFromFile.md)
| [GetUniformInfo](GetUniformInfo.md) | 获取相关状态或对象。 | - [Compile](Compile.md)
| [GetUniformLocation](GetUniformLocation.md) | 获取相关状态或对象。 | - [CompileCompute](CompileCompute.md)
| [GetID](GetID.md) | 获取相关状态或对象。 | - [Use](Use.md)
## 相关文档 ## 相关文档
- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录 - [OpenGLDevice](../OpenGLDevice/OpenGLDevice.md)
- [API 总索引](../../../../main.md) - 返回顶层索引 - [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md)

24
docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Use.md
View File

@@ -1,30 +1,18 @@
# OpenGLShader::Use # OpenGLShader::Use
公开方法，详见头文件声明。
```cpp ```cpp
void Use() const; void Use() const;
``` ```
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。 ## 作用
**参数：** 无。 把当前 shader program 设为活动 program。
**返回：** `void` - 无返回值。 ## 当前实现行为
**示例：** 直接调用 `glUseProgram(m_program)`。
```cpp
#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
void Example() {
XCEngine::RHI::OpenGLShader object;
// 根据上下文补齐参数后调用 OpenGLShader::Use(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](OpenGLShader.md) - [Compile](Compile.md)
- [返回模块目录](../OpenGL.md) - [OpenGLPipelineState::Bind](../OpenGLPipelineState/Bind.md)

44
docs/api/_meta/rebuild-status.md
View File

@@ -1,16 +1,16 @@
# API 文档重构状态 # API 文档重构状态
**生成时间**: `2026-03-27 19:11:24` **生成时间**: `2026-03-27 22:08:19`
**来源**: `docs/api/_tools/audit_api_docs.py` **来源**: `docs/api/_tools/audit_api_docs.py`
## 摘要 ## 摘要
- Markdown 页面数（全部）: `2629` - Markdown 页面数（全部）: `2756`
- Markdown 页面数（canonical）: `2610` - Markdown 页面数（canonical）: `2736`
- Public headers 数: `227` - Public headers 数: `227`
- 有效头文件引用数（全部）: `197` - 有效头文件引用数（全部）: `216`
- 有效头文件引用数（canonical）: `197` - 有效头文件引用数（canonical）: `216`
- 无效头文件引用数: `0` - 无效头文件引用数: `0`
- 失效 `.md` 链接数: `0` - 失效 `.md` 链接数: `0`
- 非 `.md` 相对链接数: `0` - 非 `.md` 相对链接数: `0`
@@ -21,8 +21,8 @@
- Canonical 根目录: `XCEngine` - Canonical 根目录: `XCEngine`
- 源码目录节点数: `29` - 源码目录节点数: `29`
- 已生成目录总览页节点数: `26` - 已生成目录总览页节点数: `27`
- 缺失目录总览页节点数: `3` - 缺失目录总览页节点数: `2`
- 支撑目录: `_meta, _tools` - 支撑目录: `_meta, _tools`
## 模块覆盖 ## 模块覆盖
@@ -36,7 +36,7 @@
| `Input` | `5` | `5` | `0` | | `Input` | `5` | `5` | `0` |
| `Memory` | `5` | `5` | `0` | | `Memory` | `5` | `5` | `0` |
| `Platform` | `11` | `11` | `0` | | `Platform` | `11` | `11` | `0` |
| `RHI` | `87` | `68` | `19` | | `RHI` | `87` | `87` | `0` |
| `Rendering` | `13` | `10` | `3` | | `Rendering` | `13` | `10` | `3` |
| `Resources` | `13` | `13` | `0` | | `Resources` | `13` | `13` | `0` |
| `Scene` | `3` | `2` | `1` | | `Scene` | `3` | `2` | `1` |
@@ -47,38 +47,18 @@
| 字段 | 页面数 | | 字段 | 页面数 |
|------|--------| |------|--------|
| `命名空间` | `305` | | `命名空间` | `325` |
| `类型` | `305` | | `类型` | `325` |
| `描述` | `305` | | `描述` | `325` |
| `头文件` | `197` | | `头文件` | `216` |
## 缺失的平行目录总览页 ## 缺失的平行目录总览页
- `XCEngine/RHI/Vulkan`
- `XCEngine/Scripting` - `XCEngine/Scripting`
- `XCEngine/Scripting/Mono` - `XCEngine/Scripting/Mono`
## 未覆盖的 public headers ## 未覆盖的 public headers
- `XCEngine/RHI/Vulkan/VulkanBuffer.h`
- `XCEngine/RHI/Vulkan/VulkanCommandList.h`
- `XCEngine/RHI/Vulkan/VulkanCommandQueue.h`
- `XCEngine/RHI/Vulkan/VulkanCommon.h`
- `XCEngine/RHI/Vulkan/VulkanDescriptorPool.h`
- `XCEngine/RHI/Vulkan/VulkanDescriptorSet.h`
- `XCEngine/RHI/Vulkan/VulkanDevice.h`
- `XCEngine/RHI/Vulkan/VulkanFence.h`
- `XCEngine/RHI/Vulkan/VulkanFramebuffer.h`
- `XCEngine/RHI/Vulkan/VulkanPipelineLayout.h`
- `XCEngine/RHI/Vulkan/VulkanPipelineState.h`
- `XCEngine/RHI/Vulkan/VulkanRenderPass.h`
- `XCEngine/RHI/Vulkan/VulkanResourceView.h`
- `XCEngine/RHI/Vulkan/VulkanSampler.h`
- `XCEngine/RHI/Vulkan/VulkanScreenshot.h`
- `XCEngine/RHI/Vulkan/VulkanShader.h`
- `XCEngine/RHI/Vulkan/VulkanShaderCompiler.h`
- `XCEngine/RHI/Vulkan/VulkanSwapChain.h`
- `XCEngine/RHI/Vulkan/VulkanTexture.h`
- `XCEngine/Rendering/CameraRenderRequest.h` - `XCEngine/Rendering/CameraRenderRequest.h`
- `XCEngine/Rendering/CameraRenderer.h` - `XCEngine/Rendering/CameraRenderer.h`
- `XCEngine/Rendering/RenderMaterialUtility.h` - `XCEngine/Rendering/RenderMaterialUtility.h`