From c7ef9191e44d0057e7692833f836496101182a1d Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Fri, 27 Mar 2026 22:09:58 +0800 Subject: [PATCH] docs(api): deepen D3D12 and OpenGL backend docs --- docs/api/XCEngine/RHI/D3D12/D3D12.md | 92 ++++++--- .../D3D12/D3D12CommandList/BeginRenderPass.md | 41 ++-- .../RHI/D3D12/D3D12CommandList/Clear.md | 33 ++-- .../D3D12/D3D12CommandList/CopyResource.md | 29 ++- .../D3D12CommandList/D3D12CommandList.md | 157 +++++++-------- .../RHI/D3D12/D3D12CommandList/Dispatch.md | 28 +-- .../RHI/D3D12/D3D12CommandList/Draw.md | 28 +-- .../RHI/D3D12/D3D12CommandList/DrawIndexed.md | 30 +-- .../SetComputeDescriptorSets.md | 34 ++-- .../SetGraphicsDescriptorSets.md | 45 +++-- .../D3D12/D3D12CommandList/SetIndexBuffer.md | 42 +--- .../D3D12CommandList/SetPipelineState.md | 47 ++--- .../D3D12CommandList/SetRenderTargets.md | 30 ++- .../D3D12CommandList/SetVertexBuffers.md | 34 ++-- .../D3D12CommandList/TransitionBarrier.md | 46 ++--- .../D3D12CommandQueue/D3D12CommandQueue.md | 75 +++++--- .../D3D12CommandQueue/ExecuteCommandLists.md | 33 ++-- .../D3D12CommandQueue/GetCompletedValue.md | 25 +-- .../RHI/D3D12/D3D12CommandQueue/Initialize.md | 32 ++-- .../RHI/D3D12/D3D12CommandQueue/Signal.md | 42 +--- .../RHI/D3D12/D3D12CommandQueue/Wait.md | 42 +--- .../D3D12/D3D12CommandQueue/WaitForIdle.md | 27 ++- .../RHI/D3D12/D3D12DescriptorSet/Bind.md | 29 ++- .../D3D12DescriptorSet/D3D12DescriptorSet.md | 105 ++++++---- .../D3D12/D3D12DescriptorSet/Initialize.md | 34 ++-- .../RHI/D3D12/D3D12DescriptorSet/Unbind.md | 24 +-- .../RHI/D3D12/D3D12DescriptorSet/Update.md | 40 ++-- .../D3D12/D3D12DescriptorSet/UpdateSampler.md | 29 +-- .../UploadConstantBuffer.md | 33 ++-- .../D3D12/D3D12DescriptorSet/WriteConstant.md | 32 ++-- .../D3D12/D3D12Device/CreateCommandList.md | 35 ++-- .../D3D12/D3D12Device/CreateCommandQueue.md | 34 ++-- .../RHI/D3D12/D3D12Device/CreateTexture.md | 74 +++---- .../RHI/D3D12/D3D12Device/D3D12Device.md | 131 +++++++------ .../RHI/D3D12/D3D12Device/Initialize.md | 44 +++-- docs/api/XCEngine/RHI/OpenGL/OpenGL.md | 93 ++++++--- .../OpenGLCommandList/BeginRenderPass.md | 36 ++-- .../OpenGL/OpenGLCommandList/CopyResource.md | 29 ++- .../RHI/OpenGL/OpenGLCommandList/Dispatch.md | 28 +-- .../RHI/OpenGL/OpenGLCommandList/Draw.md | 45 +---- .../OpenGL/OpenGLCommandList/DrawIndexed.md | 49 ++--- .../OpenGLCommandList/OpenGLCommandList.md | 181 ++++++------------ .../SetComputeDescriptorSets.md | 30 +-- .../SetGraphicsDescriptorSets.md | 39 ++-- .../OpenGLCommandList/SetIndexBuffer.md | 56 +----- .../OpenGLCommandList/SetRenderTargets.md | 32 ++-- .../OpenGLCommandList/SetVertexBuffers.md | 51 ++--- .../OpenGLCommandList/TransitionBarrier.md | 32 ++-- .../OpenGLCommandQueue/ExecuteCommandLists.md | 26 +-- .../OpenGLCommandQueue/OpenGLCommandQueue.md | 55 +++--- .../RHI/OpenGL/OpenGLCommandQueue/Signal.md | 27 +-- .../OpenGL/OpenGLCommandQueue/WaitForIdle.md | 24 +-- .../OpenGLDevice/CreatePipelineState.md | 32 ++-- .../RHI/OpenGL/OpenGLDevice/CreateShader.md | 28 ++- .../RHI/OpenGL/OpenGLDevice/CreateTexture.md | 54 ++---- .../RHI/OpenGL/OpenGLDevice/Initialize.md | 34 ++-- .../InitializeWithExistingWindow.md | 30 ++- .../RHI/OpenGL/OpenGLDevice/OpenGLDevice.md | 101 +++++----- .../RHI/OpenGL/OpenGLPipelineState/Bind.md | 29 ++- .../OpenGLPipelineState.md | 93 ++++----- .../OpenGLPipelineState/SetComputeShader.md | 27 +-- .../RHI/OpenGL/OpenGLShader/Compile.md | 76 ++------ .../RHI/OpenGL/OpenGLShader/CompileCompute.md | 28 +-- .../OpenGL/OpenGLShader/CompileFromFile.md | 63 ++---- .../RHI/OpenGL/OpenGLShader/OpenGLShader.md | 56 +++--- .../XCEngine/RHI/OpenGL/OpenGLShader/Use.md | 24 +-- docs/api/_meta/rebuild-status.md | 44 ++--- 67 files changed, 1347 insertions(+), 1841 deletions(-) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12.md b/docs/api/XCEngine/RHI/D3D12/D3D12.md index 36cdd0e8..ad2495ce 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12.md @@ -1,42 +1,76 @@ # D3D12 -**命名空间**: `XCEngine::RHI::D3D12` +**命名空间**: `XCEngine::RHI` **类型**: `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` -- [D3D12CommandAllocator](D3D12CommandAllocator/D3D12CommandAllocator.md) - `D3D12CommandAllocator.h` -- [D3D12CommandList](D3D12CommandList/D3D12CommandList.md) - `D3D12CommandList.h` -- [D3D12CommandQueue](D3D12CommandQueue/D3D12CommandQueue.md) - `D3D12CommandQueue.h` -- [D3D12Common](D3D12Common/D3D12Common.md) - `D3D12Common.h` -- [D3D12DescriptorHeap](D3D12DescriptorHeap/D3D12DescriptorHeap.md) - `D3D12DescriptorHeap.h` -- [D3D12DescriptorSet](D3D12DescriptorSet/D3D12DescriptorSet.md) - `D3D12DescriptorSet.h` -- [D3D12Device](D3D12Device/D3D12Device.md) - `D3D12Device.h` -- [D3D12Enums](D3D12Enums/D3D12Enums.md) - `D3D12Enums.h` -- [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` -- [D3D12RenderPass](D3D12RenderPass/D3D12RenderPass.md) - `D3D12RenderPass.h` -- [D3D12ResourceView](D3D12ResourceView/D3D12ResourceView.md) - `D3D12ResourceView.h` -- [D3D12RootSignature](D3D12RootSignature/D3D12RootSignature.md) - `D3D12RootSignature.h` -- [D3D12Sampler](D3D12Sampler/D3D12Sampler.md) - `D3D12Sampler.h` -- [D3D12Screenshot](D3D12Screenshot/D3D12Screenshot.md) - `D3D12Screenshot.h` -- [D3D12Shader](D3D12Shader/D3D12Shader.md) - `D3D12Shader.h` -- [D3D12SwapChain](D3D12SwapChain/D3D12SwapChain.md) - `D3D12SwapChain.h` -- [D3D12Texture](D3D12Texture/D3D12Texture.md) - `D3D12Texture.h` -- [D3D12Types](D3D12Types/D3D12Types.md) - `D3D12Types.h` +- 设备与提交基础设施：[`D3D12Device`](D3D12Device/D3D12Device.md)、[`D3D12CommandQueue`](D3D12CommandQueue/D3D12CommandQueue.md)、[`D3D12CommandAllocator`](D3D12CommandAllocator/D3D12CommandAllocator.md)、[`D3D12CommandList`](D3D12CommandList/D3D12CommandList.md) +- 资源与视图：[`D3D12Buffer`](D3D12Buffer/D3D12Buffer.md)、[`D3D12Texture`](D3D12Texture/D3D12Texture.md)、[`D3D12ResourceView`](D3D12ResourceView/D3D12ResourceView.md) +- 管线与绑定：[`D3D12PipelineLayout`](D3D12PipelineLayout/D3D12PipelineLayout.md)、[`D3D12PipelineState`](D3D12PipelineState/D3D12PipelineState.md)、[`D3D12RootSignature`](D3D12RootSignature/D3D12RootSignature.md)、[`D3D12DescriptorHeap`](D3D12DescriptorHeap/D3D12DescriptorHeap.md)、[`D3D12DescriptorSet`](D3D12DescriptorSet/D3D12DescriptorSet.md) +- 呈现与同步：[`D3D12SwapChain`](D3D12SwapChain/D3D12SwapChain.md)、[`D3D12RenderPass`](D3D12RenderPass/D3D12RenderPass.md)、[`D3D12Framebuffer`](D3D12Framebuffer/D3D12Framebuffer.md)、[`D3D12Fence`](D3D12Fence/D3D12Fence.md) + +## 设计要点 + +- 这套后端明显偏向“显式控制、轻量工厂、调用方自行管理生命周期”的风格，而不是 Unity 那种高度托管对象模型。 +- RHI 层暴露了“descriptor set / pipeline layout”这一套跨后端抽象，但在 D3D12 中真正落地的是 root signature、descriptor heap 和 root parameter 映射。 +- 代码把“先打通统一语义”放在更高优先级，因此部分实现是简化版。例如队列空闲等待、常量缓冲上传、资源状态跟踪都先覆盖主路径，再逐步补足更成熟的工程策略。 + +## 当前实现边界 + +- 平台路径是 Windows + DXGI + D3D12。 +- 设备初始化会从 `adapterIndex` 开始枚举适配器，跳过软件适配器，选择第一个能创建 `D3D_FEATURE_LEVEL_11_0` 设备的硬件适配器。 +- `D3D12CommandQueue`、`D3D12CommandList`、`D3D12DescriptorSet` 已经形成了可跑通的核心路径，但仍存在一些明显的占位或简化实现。 +- 若你熟悉 Unity，可以把这里理解成“比 SRP backend 更低一层”的运行时封装；它强调可组合性和后端细节可见性，而不是隐藏 D3D12 的显式同步和绑定成本。 + +## 推荐阅读顺序 + +1. [D3D12Device](D3D12Device/D3D12Device.md) +2. [D3D12CommandQueue](D3D12CommandQueue/D3D12CommandQueue.md) +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) -- [API 总索引](../../../main.md) +- [RHI](../RHI.md) +- [Devices, Queues, Command Lists, And Resource Creation](../../../_guides/RHI/Devices-Queues-CommandLists-And-Resource-Creation.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/BeginRenderPass.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/BeginRenderPass.md index 31d294ec..10ea93d1 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/BeginRenderPass.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/BeginRenderPass.md @@ -1,35 +1,32 @@ # D3D12CommandList::BeginRenderPass -公开方法，详见头文件声明。 - ```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 路径。 +## 作用 -**参数：** -- `renderPass` - 参数语义详见头文件声明。 -- `framebuffer` - 参数语义详见头文件声明。 -- `renderArea` - 参数语义详见头文件声明。 -- `clearValueCount` - 参数语义详见头文件声明。 -- `clearValues` - 参数语义详见头文件声明。 +根据 render pass 描述和 framebuffer 句柄设置视口、裁剪区、清屏策略和输出目标。 -**返回：** `void` - 无返回值。 +## 前置条件 -**示例：** +- `renderPass` 与 `framebuffer` 都必须有效 -```cpp -#include +## 当前实现行为 -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::BeginRenderPass(...)。 - (void)object; -} -``` +- 根据 `renderArea` 设置一组 viewport 和 scissor +- 从 `D3D12Framebuffer` 取出颜色附件句柄和深度句柄 +- 从 `D3D12RenderPass` 读取 load action +- 对 `LoadAction::Clear` 的颜色附件执行 `ClearRenderTargetView` +- 若深度/模板附件配置为 clear，则执行 `ClearDepthStencilView` +- 最后调用 `OMSetRenderTargets(...)` +- 同时缓存当前绑定的 RT / DS handle，供 [`Clear`](Clear.md) 使用 + +## 当前限制 + +这条实现更接近“render pass 语义翻译层”，而不是利用 D3D12 enhanced barrier / native render pass 的完整高级路径。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [SetRenderTargets](SetRenderTargets.md) +- [Clear](Clear.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Clear.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Clear.md index 1be9b4e9..2d106b3c 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Clear.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Clear.md @@ -1,35 +1,26 @@ # D3D12CommandList::Clear -清空内部数据。 - ```cpp 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 +## 注意事项 -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::Clear(...)。 - (void)object; -} -``` +这条方法依赖此前已经通过 [`BeginRenderPass`](BeginRenderPass.md) 或 [`SetRenderTargets`](SetRenderTargets.md) 建立了当前绑定目标。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [BeginRenderPass](BeginRenderPass.md) +- [SetRenderTargets](SetRenderTargets.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyResource.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyResource.md index a3233fc5..a3d539c0 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyResource.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyResource.md @@ -1,32 +1,25 @@ # D3D12CommandList::CopyResource -公开方法，详见头文件声明。 - ```cpp void CopyResource(RHIResourceView* dst, RHIResourceView* src) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `dst` - 参数语义详见头文件声明。 -- `src` - 参数语义详见头文件声明。 +对两个资源 view 底层指向的 D3D12 资源执行整资源复制。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 要求 `dst`、`src` 都有效 +- 将二者转成 `D3D12ResourceView` +- 取出底层 `ID3D12Resource*` +- 调用 `ID3D12GraphicsCommandList::CopyResource(...)` -```cpp -#include +## 注意事项 -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::CopyResource(...)。 - (void)object; -} -``` +这条路径不会自动插入资源状态转换；调用方应自行在复制前后安排合适的 barrier。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [TransitionBarrier](TransitionBarrier.md) +- [SetRenderTargets](SetRenderTargets.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/D3D12CommandList.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/D3D12CommandList.md index fa7a5f26..d8bb80cd 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/D3D12CommandList.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/D3D12CommandList.md @@ -6,96 +6,85 @@ **头文件**: `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”的薄层实现。 -## 声明概览 +这类类型在商业引擎里通常承担两件事： -| 声明 | 类型 | 说明 | -|------|------|------| -| `D3D12CommandList` | `class` | 继承自 `RHICommandList` 的公开声明。 | +- 把抽象 RHI 命令翻译成 D3D12 调用 +- 在不引入太多调度系统复杂度的前提下，补一层最基本的状态缓存和参数装配 -## 公共方法 +## 生命周期 -| 方法 | 描述 | -|------|------| -| [D3D12CommandList()](Constructor.md) | 构造对象。 | -| [~D3D12CommandList()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Initialize](Initialize.md) | 初始化内部状态。 | -| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | -| [Reset](Reset.md) | 公开方法，详见头文件声明。 | -| [Close](Close.md) | 公开方法，详见头文件声明。 | -| [GetCommandList](GetCommandList.md) | 获取相关状态或对象。 | -| [SetShader](SetShader.md) | 设置相关状态或配置。 | -| [TransitionBarrier](TransitionBarrier.md) | 公开方法，详见头文件声明。 | -| [TransitionBarrierInternal](TransitionBarrierInternal.md) | 公开方法，详见头文件声明。 | -| [UAVBarrier](UAVBarrier.md) | 公开方法，详见头文件声明。 | -| [UAVBarrierInternal](UAVBarrierInternal.md) | 公开方法，详见头文件声明。 | -| [AliasBarrier](AliasBarrier.md) | 公开方法，详见头文件声明。 | -| [AliasBarrierInternal](AliasBarrierInternal.md) | 公开方法，详见头文件声明。 | -| [BeginRenderPass](BeginRenderPass.md) | 公开方法，详见头文件声明。 | -| [EndRenderPass](EndRenderPass.md) | 公开方法，详见头文件声明。 | -| [SetPipelineState](SetPipelineState.md) | 设置相关状态或配置。 | -| [SetPipelineStateInternal](SetPipelineStateInternal.md) | 设置相关状态或配置。 | -| [SetPipelineLayout](SetPipelineLayout.md) | 设置相关状态或配置。 | -| [SetRootSignature](SetRootSignature.md) | 设置相关状态或配置。 | -| [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md) | 设置相关状态或配置。 | -| [SetComputeDescriptorSets](SetComputeDescriptorSets.md) | 设置相关状态或配置。 | -| [SetViewport](SetViewport.md) | 设置相关状态或配置。 | -| [SetViewports](SetViewports.md) | 设置相关状态或配置。 | -| [SetScissorRect](SetScissorRect.md) | 设置相关状态或配置。 | -| [SetScissorRects](SetScissorRects.md) | 设置相关状态或配置。 | -| [SetPrimitiveTopology](SetPrimitiveTopology.md) | 设置相关状态或配置。 | -| [SetRenderTargets](SetRenderTargets.md) | 设置相关状态或配置。 | -| [SetRenderTargetsInternal](SetRenderTargetsInternal.md) | 设置相关状态或配置。 | -| [SetRenderTargetsHandle](SetRenderTargetsHandle.md) | 设置相关状态或配置。 | -| [SetVertexBuffers](SetVertexBuffers.md) | 设置相关状态或配置。 | -| [SetVertexBuffersInternal](SetVertexBuffersInternal.md) | 设置相关状态或配置。 | -| [SetVertexBuffer](SetVertexBuffer.md) | 设置相关状态或配置。 | -| [SetIndexBuffer](SetIndexBuffer.md) | 设置相关状态或配置。 | -| [SetIndexBufferInternal](SetIndexBufferInternal.md) | 设置相关状态或配置。 | -| [SetDescriptorHeap](SetDescriptorHeap.md) | 设置相关状态或配置。 | -| [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) | 公开方法，详见头文件声明。 | -| [DrawIndexed](DrawIndexed.md) | 公开方法，详见头文件声明。 | -| [DrawInstancedIndirect](DrawInstancedIndirect.md) | 公开方法，详见头文件声明。 | -| [DrawInstancedIndirectInternal](DrawInstancedIndirectInternal.md) | 公开方法，详见头文件声明。 | -| [DrawIndexedInstancedIndirect](DrawIndexedInstancedIndirect.md) | 公开方法，详见头文件声明。 | -| [DrawIndexedInstancedIndirectInternal](DrawIndexedInstancedIndirectInternal.md) | 公开方法，详见头文件声明。 | -| [Clear](Clear.md) | 清空内部数据。 | -| [ClearRenderTarget](ClearRenderTarget.md) | 清空内部数据。 | -| [ClearRenderTargetView](ClearRenderTargetView.md) | 清空内部数据。 | -| [ClearDepthStencil](ClearDepthStencil.md) | 清空内部数据。 | -| [ClearDepthStencilView](ClearDepthStencilView.md) | 清空内部数据。 | -| [ClearUnorderedAccessView](ClearUnorderedAccessView.md) | 清空内部数据。 | -| [CopyResource](CopyResource.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) | 公开方法，详见头文件声明。 | +- `Initialize()` 需要外部设备和 command allocator +- `Reset()` 重新开始录制，并清空软件侧状态缓存 +- `Close()` 结束录制 +- 提交由 [`D3D12CommandQueue`](../D3D12CommandQueue/D3D12CommandQueue.md) 完成 + +## 当前实现的真实行为 + +### 资源状态与 barrier + +- [`TransitionBarrier`](TransitionBarrier.md) 会直接发出 `ResourceBarrier` +- 同时把 `stateAfter` 记入 `m_resourceStateMap` +- 这份状态表只是本命令列表内的软跟踪，不等同于跨队列、跨帧的全局真值 + +### 管线与描述符绑定 + +- [`SetPipelineState`](SetPipelineState.md) 会先调用 `EnsureValid()` +- Graphics 路径依赖 graphics PSO 和 graphics root signature +- Compute 路径会改走 `SetComputeRootSignature()` 和 compute pipeline state +- [`SetGraphicsDescriptorSets`](SetGraphicsDescriptorSets.md) / [`SetComputeDescriptorSets`](SetComputeDescriptorSets.md) 会根据 `D3D12PipelineLayout` 的映射，把 CBV 写到 root CBV，把 SRV/UAV/Sampler 绑定到 descriptor table + +### Render pass 与输出目标 + +- [`BeginRenderPass`](BeginRenderPass.md) 当前更像“根据 `D3D12RenderPass` 描述执行清屏并调用 `OMSetRenderTargets`” +- `EndRenderPass()` 目前是空实现，不会生成额外 D3D12 结束命令 +- [`SetRenderTargets`](SetRenderTargets.md) 直接消费传入的 `D3D12ResourceView` CPU handle + +### 绘制与计算 + +- [`Draw`](Draw.md) / [`DrawIndexed`](DrawIndexed.md) 直接转发到 `DrawInstanced` / `DrawIndexedInstanced` +- [`Dispatch`](Dispatch.md) 直接转发到 `ID3D12GraphicsCommandList::Dispatch` +- 间接绘制/间接 dispatch 相关内部接口当前调用 `ExecuteIndirect(nullptr, ...)`，说明这条能力还处在占位或未完工状态 + +## 值得注意的限制 + +- `SetDepthBias()` 目前为空实现 +- `EndRenderPass()` 目前为空实现 +- `ClearDepthStencilView(ID3D12Resource* ...)` 这一重载内部构造的是空 DSV handle，实用路径应优先走 view/handle 版本 +- `SetRenderTargetsInternal()` 传入的是空 descriptor handle 数组，属于低层占位接口，不应视为成熟主路径 + +## 线程语义 + +命令列表对象没有显式并发保护。建议把它视为： + +- 单线程录制对象 +- 一次只由一个提交上下文持有和驱动 + +## 重点公共方法 + +- [TransitionBarrier](TransitionBarrier.md) +- [BeginRenderPass](BeginRenderPass.md) +- [SetPipelineState](SetPipelineState.md) +- [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md) +- [SetComputeDescriptorSets](SetComputeDescriptorSets.md) +- [SetRenderTargets](SetRenderTargets.md) +- [SetVertexBuffers](SetVertexBuffers.md) +- [SetIndexBuffer](SetIndexBuffer.md) +- [Clear](Clear.md) +- [CopyResource](CopyResource.md) +- [Draw](Draw.md) +- [DrawIndexed](DrawIndexed.md) +- [Dispatch](Dispatch.md) ## 相关文档 -- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录 -- [API 总索引](../../../../main.md) - 返回顶层索引 +- [D3D12](../D3D12.md) +- [D3D12Device](../D3D12Device/D3D12Device.md) +- [D3D12CommandQueue](../D3D12CommandQueue/D3D12CommandQueue.md) +- [D3D12DescriptorSet](../D3D12DescriptorSet/D3D12DescriptorSet.md) +- [D3D12PipelineLayout](../D3D12PipelineLayout/D3D12PipelineLayout.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Dispatch.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Dispatch.md index f4252b1b..94ab577d 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Dispatch.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Dispatch.md @@ -1,33 +1,23 @@ # D3D12CommandList::Dispatch -公开方法，详见头文件声明。 - ```cpp void Dispatch(uint32_t x, uint32_t y, uint32_t z) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `x` - 参数语义详见头文件声明。 -- `y` - 参数语义详见头文件声明。 -- `z` - 参数语义详见头文件声明。 +发出一次 compute dispatch。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +直接调用 `ID3D12GraphicsCommandList::Dispatch(...)`。 -```cpp -#include +## 前置条件 -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::Dispatch(...)。 - (void)object; -} -``` +- 已经绑定有效的 compute pipeline state +- 已经通过 [`SetComputeDescriptorSets`](SetComputeDescriptorSets.md) 或其他 compute 根参数接口配置好资源 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [SetComputeDescriptorSets](SetComputeDescriptorSets.md) +- [SetPipelineState](SetPipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Draw.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Draw.md index d4758496..93c48ba4 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Draw.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Draw.md @@ -1,34 +1,22 @@ # D3D12CommandList::Draw -公开方法，详见头文件声明。 - ```cpp 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 +## 前置条件 -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::Draw(...)。 - (void)object; -} -``` +- 顶点缓冲、拓扑、PSO、root signature 等图形状态已由调用方提前配置 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [SetVertexBuffers](SetVertexBuffers.md) +- [SetPipelineState](SetPipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexed.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexed.md index f9625fa1..e3752fa5 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexed.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexed.md @@ -1,35 +1,23 @@ # D3D12CommandList::DrawIndexed -公开方法，详见头文件声明。 - ```cpp 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 +## 前置条件 -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::DrawIndexed(...)。 - (void)object; -} -``` +- 已经通过 [`SetIndexBuffer`](SetIndexBuffer.md) 绑定索引缓冲 +- 图形管线状态已配置完成 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [SetIndexBuffer](SetIndexBuffer.md) +- [Draw](Draw.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetComputeDescriptorSets.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetComputeDescriptorSets.md index 0e163df2..7db10b5e 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetComputeDescriptorSets.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetComputeDescriptorSets.md @@ -1,34 +1,22 @@ # D3D12CommandList::SetComputeDescriptorSets -设置相关状态或配置。 - ```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 路径。 +## 作用 -**参数：** -- `firstSet` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `descriptorSets` - 参数语义详见头文件声明。 -- `pipelineLayout` - 参数语义详见头文件声明。 +把一组 descriptor set 绑定到 compute bind point。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetComputeDescriptorSets(...)。 - (void)object; -} -``` +- 流程与 [`SetGraphicsDescriptorSets`](SetGraphicsDescriptorSets.md) 基本一致 +- 区别在于： + - 会显式调用 `SetComputeRootSignature(...)` + - `CBV` 绑定使用 `SetComputeRootConstantBufferView(...)` + - SRV/UAV/Sampler descriptor table 绑定使用 compute 版本接口 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md) +- [Dispatch](Dispatch.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsDescriptorSets.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsDescriptorSets.md index 403ac018..2ca51039 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsDescriptorSets.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsDescriptorSets.md @@ -1,34 +1,37 @@ # D3D12CommandList::SetGraphicsDescriptorSets -设置相关状态或配置。 - ```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 路径。 +## 作用 -**参数：** -- `firstSet` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `descriptorSets` - 参数语义详见头文件声明。 -- `pipelineLayout` - 参数语义详见头文件声明。 +把一组 descriptor set 绑定到 graphics bind point。 -**返回：** `void` - 无返回值。 +## 前置条件 -**示例：** +- `pipelineLayout != nullptr` +- `descriptorSets != nullptr` -```cpp -#include +## 当前实现行为 -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetGraphicsDescriptorSets(...)。 - (void)object; -} -``` +- 把 `pipelineLayout` 转成 `D3D12PipelineLayout` +- 若 set 所在 heap 是 shader-visible 且包含 SRV/UAV/Sampler 绑定，则先收集并设置 descriptor heaps +- 对每个 set： + - 遍历所有 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) -- [返回模块目录](../D3D12.md) +- [SetComputeDescriptorSets](SetComputeDescriptorSets.md) +- [D3D12DescriptorSet](../D3D12DescriptorSet/D3D12DescriptorSet.md) +- [D3D12PipelineLayout](../D3D12PipelineLayout/D3D12PipelineLayout.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetIndexBuffer.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetIndexBuffer.md index 1add5463..424c3d91 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetIndexBuffer.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetIndexBuffer.md @@ -1,47 +1,21 @@ # D3D12CommandList::SetIndexBuffer -设置相关状态或配置。 - -该方法在 `XCEngine/RHI/D3D12/D3D12CommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 - -## 重载 1: 声明 - ```cpp void SetIndexBuffer(RHIResourceView* buffer, uint64_t offset) override; -``` - -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void SetIndexBuffer(ID3D12Resource* buffer, uint64_t offset, Format format); ``` -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 -- `format` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +绑定索引缓冲。 -**示例：** +## 当前实现行为 -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetIndexBuffer(...)。 - (void)object; -} -``` +- `RHIResourceView*` 重载会从 view 读取底层资源、buffer offset 和 format +- 若 format 为 `Unknown`，当前实现回退为 `Format::R32_UInt` +- 最终组装 `D3D12_INDEX_BUFFER_VIEW` 并调用 `IASetIndexBuffer(...)` ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [SetVertexBuffers](SetVertexBuffers.md) +- [DrawIndexed](DrawIndexed.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineState.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineState.md index 7a7dc9cd..30ede931 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineState.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineState.md @@ -1,44 +1,31 @@ # D3D12CommandList::SetPipelineState -设置相关状态或配置。 - -该方法在 `XCEngine/RHI/D3D12/D3D12CommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 - -## 重载 1: 声明 - ```cpp void SetPipelineState(RHIPipelineState* pso) override; -``` - -**参数：** -- `pso` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void SetPipelineState(ID3D12PipelineState* pso); ``` -**参数：** -- `pso` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +绑定图形或计算管线状态对象。 -**示例：** +## 当前实现行为 -```cpp -#include +- 若 `pso == nullptr`，直接返回 +- 会先调用 `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(...)。 - (void)object; -} -``` +## 注意事项 + +图形和计算路径的根签名绑定方式不同，不能简单把它理解成“只是设置一个 PSO 指针”。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md) +- [SetComputeDescriptorSets](SetComputeDescriptorSets.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargets.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargets.md index 883c572c..e40869f0 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargets.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargets.md @@ -1,33 +1,25 @@ # D3D12CommandList::SetRenderTargets -设置相关状态或配置。 - ```cpp 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 +## 为什么要缓存 -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetRenderTargets(...)。 - (void)object; -} -``` +后续 [`Clear`](Clear.md) 会复用这些 handle，对当前输出目标执行清屏。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [BeginRenderPass](BeginRenderPass.md) +- [Clear](Clear.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffers.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffers.md index 62a6cc6b..95ff3172 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffers.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffers.md @@ -1,35 +1,23 @@ # D3D12CommandList::SetVertexBuffers -设置相关状态或配置。 - ```cpp 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 路径。 +## 作用 -**参数：** -- `startSlot` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `buffers` - 参数语义详见头文件声明。 -- `offsets` - 参数语义详见头文件声明。 -- `strides` - 参数语义详见头文件声明。 +根据一组顶点缓冲 view 生成 `D3D12_VERTEX_BUFFER_VIEW` 并绑定到 IA 阶段。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetVertexBuffers(...)。 - (void)object; -} -``` +- 为每个输入 view 读取： + - GPU 地址 + - buffer size + - view 自带 stride +- 若调用方显式提供 `strides[i] > 0`，优先使用调用方 stride +- 最终调用 `IASetVertexBuffers(...)` ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [SetIndexBuffer](SetIndexBuffer.md) +- [Draw](Draw.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TransitionBarrier.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TransitionBarrier.md index aee75989..1af04565 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TransitionBarrier.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TransitionBarrier.md @@ -1,48 +1,26 @@ # D3D12CommandList::TransitionBarrier -公开方法，详见头文件声明。 - -该方法在 `XCEngine/RHI/D3D12/D3D12CommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 - -## 重载 1: 声明 - ```cpp void TransitionBarrier(RHIResourceView* resource, ResourceStates stateBefore, ResourceStates stateAfter) override; -``` - -**参数：** -- `resource` - 参数语义详见头文件声明。 -- `stateBefore` - 参数语义详见头文件声明。 -- `stateAfter` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void TransitionBarrier(ID3D12Resource* resource, ResourceStates stateBefore, ResourceStates stateAfter); ``` -**参数：** -- `resource` - 参数语义详见头文件声明。 -- `stateBefore` - 参数语义详见头文件声明。 -- `stateAfter` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +对资源插入 D3D12 transition barrier，并更新命令列表内部的软件状态缓存。 -**示例：** +## 当前实现行为 -```cpp -#include +- `RHIResourceView*` 重载会先转成 `D3D12ResourceView`，再取出底层 `ID3D12Resource*` +- 最终调用 `TransitionBarrierInternal(...)` +- barrier 的 `StateBefore` / `StateAfter` 来自调用方传入值 +- 成功发出 barrier 后，`m_resourceStateMap[resource] = stateAfter` -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::TransitionBarrier(...)。 - (void)object; -} -``` +## 设计说明 + +这里的状态缓存只是“本命令列表认为资源现在处于什么状态”，方便后续查询和调试，不是跨队列、跨帧同步的权威来源。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [BeginRenderPass](BeginRenderPass.md) +- [CopyResource](CopyResource.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/D3D12CommandQueue.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/D3D12CommandQueue.md index 422710e8..b7c645a8 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/D3D12CommandQueue.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/D3D12CommandQueue.md @@ -6,40 +6,59 @@ **头文件**: `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 很像： -| 声明 | 类型 | 说明 | -|------|------|------| -| `D3D12CommandQueue` | `class` | 继承自 `RHICommandQueue` 的公开声明。 | +- 上层只关心“把哪些命令列表送到哪类队列” +- 后端负责把抽象 `CommandQueueType` 翻译成 D3D12 queue type +- 同步仍然是显式的，不会像 OpenGL 那样把提交和执行揉成同一个概念 -## 公共方法 +## 生命周期 -| 方法 | 描述 | -|------|------| -| [D3D12CommandQueue()](Constructor.md) | 构造对象。 | -| [~D3D12CommandQueue()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Initialize](Initialize.md) | 初始化内部状态。 | -| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | -| [ExecuteCommandLists](ExecuteCommandLists.md) | 公开方法，详见头文件声明。 | -| [Signal](Signal.md) | 公开方法，详见头文件声明。 | -| [Wait](Wait.md) | 公开方法，详见头文件声明。 | -| [GetCompletedValue](GetCompletedValue.md) | 获取相关状态或对象。 | -| [WaitForIdle](WaitForIdle.md) | 公开方法，详见头文件声明。 | -| [GetType](GetType.md) | 获取相关状态或对象。 | -| [GetTimestampFrequency](GetTimestampFrequency.md) | 获取相关状态或对象。 | -| [GetCommandQueue](GetCommandQueue.md) | 获取相关状态或对象。 | -| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | -| [ExecuteCommandListsInternal](ExecuteCommandListsInternal.md) | 公开方法，详见头文件声明。 | -| [WaitForPreviousFrame](WaitForPreviousFrame.md) | 公开方法，详见头文件声明。 | -| [GetCurrentFrame](GetCurrentFrame.md) | 获取相关状态或对象。 | +典型顺序是： + +1. 构造对象 +2. 调用 [`Initialize`](Initialize.md) +3. 反复调用 [`ExecuteCommandLists`](ExecuteCommandLists.md)、[`Signal`](Signal.md)、[`Wait`](Wait.md) +4. 在需要粗粒度同步时调用 [`WaitForIdle`](WaitForIdle.md) +5. 销毁前调用 `Shutdown()` + +## 当前实现的真实行为 + +- `Initialize()` 会创建真实的 `ID3D12CommandQueue` +- 同时会创建一条 `m_frameFence` 和一个 Win32 event，用于 `WaitForPreviousFrame()` +- `ExecuteCommandLists()` 提交后会把 `m_currentFrame` 加一，并用 `m_frameFence` signal 这个值 +- [`GetCompletedValue`](GetCompletedValue.md) 返回的是 `m_frameFence` 的完成值，不是某个外部 fence 的值 +- [`WaitForIdle`](WaitForIdle.md) 当前不是复用 `m_frameFence`，而是临时创建一个 fence 后轮询等待，这属于可用但不够成熟的实现 + +## 线程语义 + +队列对象本身没有做额外并发保护。更合理的假设是： + +- 一条队列由渲染线程或提交线程顺序驱动 +- 外部若要并发 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` 平行目录 -- [API 总索引](../../../../main.md) - 返回顶层索引 +- [D3D12](../D3D12.md) +- [D3D12Device](../D3D12Device/D3D12Device.md) +- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/ExecuteCommandLists.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/ExecuteCommandLists.md index 8d8d4b26..fc08d8c7 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/ExecuteCommandLists.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/ExecuteCommandLists.md @@ -1,32 +1,29 @@ # D3D12CommandQueue::ExecuteCommandLists -公开方法，详见头文件声明。 - ```cpp void ExecuteCommandLists(uint32_t count, void** lists) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandQueue.h`，当前页面用于固定 `D3D12CommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `lists` - 参数语义详见头文件声明。 +把一组抽象命令列表提交到当前 D3D12 队列。 -**返回：** `void` - 无返回值。 +## 前置条件 -**示例：** +- 队列已经初始化 +- `lists` 指向的是可提交的 `RHICommandList` 实例 -```cpp -#include +## 当前实现行为 -void Example() { - XCEngine::RHI::D3D12CommandQueue object; - // 根据上下文补齐参数后调用 D3D12CommandQueue::ExecuteCommandLists(...)。 - (void)object; -} -``` +- 当 `count == 0` 或 `lists == nullptr` 时直接返回 +- 把每个 `RHICommandList` 的 `GetNativeHandle()` 转成 `ID3D12CommandList*` +- 调用内部 `ExecuteCommandListsInternal()` +- `ExecuteCommandListsInternal()` 提交后会： + - `m_currentFrame++` + - 对 `m_frameFence` signal 当前帧值 ## 相关文档 -- [返回类总览](D3D12CommandQueue.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandQueue](D3D12CommandQueue.md) +- [GetCompletedValue](GetCompletedValue.md) +- [WaitForIdle](WaitForIdle.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/GetCompletedValue.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/GetCompletedValue.md index d1651cb7..d3bd483a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/GetCompletedValue.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/GetCompletedValue.md @@ -1,30 +1,23 @@ # D3D12CommandQueue::GetCompletedValue -获取相关状态或对象。 - ```cpp uint64_t GetCompletedValue() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandQueue.h`，当前页面用于固定 `D3D12CommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +查询队列内部帧 fence 当前已经完成到哪一帧。 -**返回：** `uint64_t` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 若 `m_frameFence` 存在，则返回其 `GetCompletedValue()` +- 否则返回 `0` -```cpp -#include +## 注意事项 -void Example() { - XCEngine::RHI::D3D12CommandQueue object; - // 根据上下文补齐参数后调用 D3D12CommandQueue::GetCompletedValue(...)。 - (void)object; -} -``` +这不是对“所有提交过的外部 fence”的统一查询；它只反映队列自身维护的那条帧时间线。 ## 相关文档 -- [返回类总览](D3D12CommandQueue.md) -- [返回模块目录](../D3D12.md) +- [ExecuteCommandLists](ExecuteCommandLists.md) +- [WaitForIdle](WaitForIdle.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Initialize.md index 95f2a5b7..5e787ffc 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Initialize.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Initialize.md @@ -1,32 +1,28 @@ # D3D12CommandQueue::Initialize -初始化内部状态。 - ```cpp bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandQueue.h`，当前页面用于固定 `D3D12CommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `device` - 参数语义详见头文件声明。 -- `type` - 参数语义详见头文件声明。 +创建原生 D3D12 队列对象和队列自身使用的帧 fence。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 把 `CommandQueueType` 转成 `D3D12_COMMAND_QUEUE_DESC.Type` +- 创建 `ID3D12CommandQueue` +- 创建一只初始值为 `0` 的 `m_frameFence` +- 创建 Win32 event 保存到 `m_frameEvent` +- 缓存队列类型和 timestamp frequency -```cpp -#include +## 失败路径 -void Example() { - XCEngine::RHI::D3D12CommandQueue object; - // 根据上下文补齐参数后调用 D3D12CommandQueue::Initialize(...)。 - (void)object; -} -``` +- 创建原生队列失败返回 `false` +- 创建 `m_frameFence` 失败返回 `false` +- 创建 event 失败返回 `false` ## 相关文档 -- [返回类总览](D3D12CommandQueue.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandQueue](D3D12CommandQueue.md) +- [ExecuteCommandLists](ExecuteCommandLists.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Signal.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Signal.md index 76545da5..d6e32948 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Signal.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Signal.md @@ -1,46 +1,24 @@ # D3D12CommandQueue::Signal -公开方法，详见头文件声明。 - -该方法在 `XCEngine/RHI/D3D12/D3D12CommandQueue.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 - -## 重载 1: 声明 - ```cpp void Signal(RHIFence* fence, uint64_t value) override; ``` -**参数：** -- `fence` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +让当前队列对指定 fence signal 一个值。 -## 重载 2: 声明 +## 当前实现行为 -```cpp -void Signal(ID3D12Fence* fence, uint64_t value); -``` +- 若 `fence == nullptr`，直接返回 +- 把抽象 `RHIFence` 转成 `D3D12Fence` +- 调用原生 `ID3D12CommandQueue::Signal(...)` -**参数：** -- `fence` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +## 注意事项 -**返回：** `void` - 无返回值。 - -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandQueue object; - // 根据上下文补齐参数后调用 D3D12CommandQueue::Signal(...)。 - (void)object; -} -``` +这里使用的是调用方传入的 fence，不是队列自己的 `m_frameFence`。 ## 相关文档 -- [返回类总览](D3D12CommandQueue.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandQueue](D3D12CommandQueue.md) +- [Wait](Wait.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Wait.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Wait.md index 93284663..43a0b50a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Wait.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/Wait.md @@ -1,46 +1,24 @@ # D3D12CommandQueue::Wait -公开方法，详见头文件声明。 - -该方法在 `XCEngine/RHI/D3D12/D3D12CommandQueue.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 - -## 重载 1: 声明 - ```cpp void Wait(RHIFence* fence, uint64_t value) override; ``` -**参数：** -- `fence` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +让当前队列等待指定 fence 达到目标值。 -## 重载 2: 声明 +## 当前实现行为 -```cpp -void Wait(ID3D12Fence* fence, uint64_t value); -``` +- 若 `fence == nullptr`，直接返回 +- 把 `RHIFence` 转成 `D3D12Fence` +- 调用原生 `ID3D12CommandQueue::Wait(...)` -**参数：** -- `fence` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +## 设计说明 -**返回：** `void` - 无返回值。 - -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandQueue object; - // 根据上下文补齐参数后调用 D3D12CommandQueue::Wait(...)。 - (void)object; -} -``` +这是一条 GPU 侧队列等待路径，不是 CPU 阻塞等待。它的语义更接近 D3D12 原生 queue dependency，而不是 `WaitForIdle()` 那种“CPU 等 GPU”。 ## 相关文档 -- [返回类总览](D3D12CommandQueue.md) -- [返回模块目录](../D3D12.md) +- [Signal](Signal.md) +- [WaitForIdle](WaitForIdle.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/WaitForIdle.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/WaitForIdle.md index ce14f28a..5337cf61 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/WaitForIdle.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandQueue/WaitForIdle.md @@ -1,30 +1,25 @@ # D3D12CommandQueue::WaitForIdle -公开方法，详见头文件声明。 - ```cpp 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 +## 设计说明 -void Example() { - XCEngine::RHI::D3D12CommandQueue object; - // 根据上下文补齐参数后调用 D3D12CommandQueue::WaitForIdle(...)。 - (void)object; -} -``` +这是一条简单、稳定、易懂的空闲等待路径，适合初始化、销毁和测试代码，但并不适合高频帧循环。更成熟的实现通常会复用长期存在的 fence，并用事件等待代替忙轮询。 ## 相关文档 -- [返回类总览](D3D12CommandQueue.md) -- [返回模块目录](../D3D12.md) +- [ExecuteCommandLists](ExecuteCommandLists.md) +- [GetCompletedValue](GetCompletedValue.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Bind.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Bind.md index fd6cc517..94e4dc33 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Bind.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Bind.md @@ -1,30 +1,27 @@ # D3D12DescriptorSet::Bind -公开方法，详见头文件声明。 - ```cpp void Bind() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +抽象层保留的绑定入口。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +当前实现为空，不会直接向 D3D12 pipeline 绑定任何内容。 -```cpp -#include +## 正确理解 -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::Bind(...)。 - (void)object; -} -``` +在 D3D12 后端里，descriptor set 的真正消费点是： + +- `D3D12CommandList::SetGraphicsDescriptorSets()` +- `D3D12CommandList::SetComputeDescriptorSets()` + +因此这里应把 `Bind()` 视为抽象层兼容接口，而不是成熟主路径。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [Unbind](Unbind.md) +- [D3D12CommandList::SetGraphicsDescriptorSets](../D3D12CommandList/SetGraphicsDescriptorSets.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/D3D12DescriptorSet.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/D3D12DescriptorSet.md index c3accd24..25e42b5c 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/D3D12DescriptorSet.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/D3D12DescriptorSet.md @@ -6,49 +6,80 @@ **头文件**: `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 -| 声明 | 类型 | 说明 | -|------|------|------| -| `D3D12DescriptorSet` | `class` | 继承自 `RHIDescriptorSet` 的公开声明。 | +这就是它和商业引擎底层“绑定组抽象”的典型相似点：上层继续按 set 思维写代码，后端负责把它拆成 D3D12 真正需要的绑定形式。 -## 公共方法 +## 生命周期 -| 方法 | 描述 | -|------|------| -| [D3D12DescriptorSet()](Constructor.md) | 构造对象。 | -| [~D3D12DescriptorSet()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Initialize](Initialize.md) | 初始化内部状态。 | -| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | -| [Bind](Bind.md) | 公开方法，详见头文件声明。 | -| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 | -| [Update](Update.md) | 更新运行时状态。 | -| [UpdateSampler](UpdateSampler.md) | 更新运行时状态。 | -| [WriteConstant](WriteConstant.md) | 公开方法，详见头文件声明。 | -| [GetBindingCount](GetBindingCount.md) | 获取相关状态或对象。 | -| [GetBindings](GetBindings.md) | 获取相关状态或对象。 | -| [GetConstantBufferData](GetConstantBufferData.md) | 获取相关状态或对象。 | -| [GetConstantBufferSize](GetConstantBufferSize.md) | 获取相关状态或对象。 | -| [IsConstantDirty](IsConstantDirty.md) | 查询当前状态。 | -| [MarkConstantClean](MarkConstantClean.md) | 公开方法，详见头文件声明。 | -| [GetGPUHandle](GetGPUHandle.md) | 获取相关状态或对象。 | -| [GetGPUHandleForBinding](GetGPUHandleForBinding.md) | 获取相关状态或对象。 | -| [GetOffset](GetOffset.md) | 获取相关状态或对象。 | -| [GetCount](GetCount.md) | 获取相关状态或对象。 | -| [GetHeap](GetHeap.md) | 获取相关状态或对象。 | -| [HasBindingType](HasBindingType.md) | 判断是否具备指定状态或能力。 | -| [GetFirstBindingOfType](GetFirstBindingOfType.md) | 获取相关状态或对象。 | -| [GetDescriptorIndexForBinding](GetDescriptorIndexForBinding.md) | 获取相关状态或对象。 | -| [UploadConstantBuffer](UploadConstantBuffer.md) | 公开方法，详见头文件声明。 | -| [GetConstantBufferGPUAddress](GetConstantBufferGPUAddress.md) | 获取相关状态或对象。 | +1. 由 [`D3D12DescriptorHeap`](../D3D12DescriptorHeap/D3D12DescriptorHeap.md) 调用 [`Initialize`](Initialize.md) +2. 通过 [`Update`](Update.md)、[`UpdateSampler`](UpdateSampler.md)、[`WriteConstant`](WriteConstant.md) 写入内容 +3. 在命令列表绑定阶段由 [`D3D12CommandList`](../D3D12CommandList/D3D12CommandList.md) 消费 +4. 销毁时调用 `Shutdown()` + +## 当前实现的真实行为 + +### 绑定索引分配 + +- 初始化时会复制 layout +- 只为当前 heap 类型真正可承载的绑定分配 descriptor index +- 分配顺序不是“按声明原顺序平铺全部绑定”，而是按类型分组： + - `SRV` + - `UAV` + - `Sampler` +- 每组内部再按 `binding` 升序排列 +- `CBV` 不占用 descriptor heap 槽位 + +### 常量缓冲策略 + +- [`WriteConstant`](WriteConstant.md) 只改写 CPU 侧字节缓存，并标记 dirty +- [`UploadConstantBuffer`](UploadConstantBuffer.md) 才会真正创建或更新 GPU 侧 upload buffer +- upload buffer 按 256 字节对齐，这是 D3D12 常量缓冲视图的基本约束 +- 每个 `CBV` binding 都可能拥有一块独立的 `D3D12Buffer` + +### Bind / Unbind 的真实语义 + +- [`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` 平行目录 -- [API 总索引](../../../../main.md) - 返回顶层索引 +- [D3D12](../D3D12.md) +- [D3D12DescriptorHeap](../D3D12DescriptorHeap/D3D12DescriptorHeap.md) +- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md) +- [D3D12PipelineLayout](../D3D12PipelineLayout/D3D12PipelineLayout.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Initialize.md index fe7d37c6..07d6684f 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Initialize.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Initialize.md @@ -1,34 +1,28 @@ # D3D12DescriptorSet::Initialize -初始化内部状态。 - ```cpp bool Initialize(D3D12DescriptorHeap* heap, uint32_t offset, uint32_t count, const DescriptorSetLayoutDesc& layout); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `heap` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `layout` - 参数语义详见头文件声明。 +按给定 layout 初始化 descriptor set 的绑定记录，并为需要落到 descriptor heap 的绑定计算 descriptor index。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 保存 `heap`、`offset`、`count` +- 复制 `layout.bindings` +- 为每个 binding 创建一条 `BindingRecord` +- 只对当前 heap 类型真正支持的绑定分配 descriptor index +- 分配顺序按类型分组：`SRV`、`UAV`、`Sampler` +- 每组内部再按 `binding` 升序排列 -```cpp -#include +## 注意事项 -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::Initialize(...)。 - (void)object; -} -``` +- `CBV` 不占用 heap descriptor 槽位 +- `count` 表示这个 set 在 heap 中实际占用的 descriptor 数，而不是 layout 的 binding 数 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) +- [Update](Update.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Unbind.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Unbind.md index faaba23f..89e5891a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Unbind.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Unbind.md @@ -1,30 +1,18 @@ # D3D12DescriptorSet::Unbind -公开方法，详见头文件声明。 - ```cpp void Unbind() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +抽象层保留的解绑入口。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::Unbind(...)。 - (void)object; -} -``` +当前实现为空，不会主动清理 root signature、descriptor heap 或 descriptor table 绑定。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [Bind](Bind.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Update.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Update.md index cd36bbbf..2231c039 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Update.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Update.md @@ -1,32 +1,36 @@ # D3D12DescriptorSet::Update -更新运行时状态。 - ```cpp void Update(uint32_t offset, RHIResourceView* view) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `offset` - 参数语义详见头文件声明。 -- `view` - 参数语义详见头文件声明。 +把一个资源视图写入当前 descriptor set 对应 binding 的 descriptor heap 槽位。 -**返回：** `void` - 无返回值。 +## 前置条件 -**示例：** +- 当前 set 对应的 heap 类型必须是 `DescriptorHeapType::CBV_SRV_UAV` +- `view` 必须有效 -```cpp -#include +## 当前实现行为 -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::Update(...)。 - (void)object; -} -``` +- 根据 `offset` 查找 binding 对应的 descriptor index +- 若该 binding 在当前 heap 上没有 descriptor 槽位，则直接返回 +- 把 `RHIResourceView` 转成 `D3D12ResourceView` +- 使用 `CopyDescriptorsSimple(...)` 把源 descriptor 复制到 set 自己的 heap 位置 + +## 失败路径 + +以下情况会静默返回： + +- `m_heap == nullptr` +- `view == nullptr` +- heap 类型不是 `CBV_SRV_UAV` +- binding 没有可用 descriptor index +- `view` 无效 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [UpdateSampler](UpdateSampler.md) +- [SetGraphicsDescriptorSets](../D3D12CommandList/SetGraphicsDescriptorSets.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/UpdateSampler.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/UpdateSampler.md index f9d3659c..13295b30 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/UpdateSampler.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/UpdateSampler.md @@ -1,32 +1,21 @@ # D3D12DescriptorSet::UpdateSampler -更新运行时状态。 - ```cpp void UpdateSampler(uint32_t offset, RHISampler* sampler) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `offset` - 参数语义详见头文件声明。 -- `sampler` - 参数语义详见头文件声明。 +把一个 sampler 描述写入当前 set 的 sampler heap 槽位。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::UpdateSampler(...)。 - (void)object; -} -``` +- 仅当 heap 类型是 `DescriptorHeapType::Sampler` 时生效 +- 根据 binding 计算 descriptor index +- 把 `RHISampler` 转成 `D3D12Sampler` +- 调用 `ID3D12Device::CreateSampler(...)` 直接写入目标 CPU descriptor handle ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [Update](Update.md) +- [D3D12Sampler](../D3D12Sampler/D3D12Sampler.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/UploadConstantBuffer.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/UploadConstantBuffer.md index fcb29c1d..3bf60c52 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/UploadConstantBuffer.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/UploadConstantBuffer.md @@ -1,31 +1,30 @@ # D3D12DescriptorSet::UploadConstantBuffer -公开方法，详见头文件声明。 - ```cpp bool UploadConstantBuffer(uint32_t binding); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `binding` - 参数语义详见头文件声明。 +确保指定 `CBV` binding 对应的 GPU upload buffer 已存在，并在需要时把 CPU 缓存写入该 buffer。 -**返回：** `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 +## 返回值 -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::UploadConstantBuffer(...)。 - (void)object; -} -``` +- `true`：GPU 侧常量缓冲已可用 +- `false`：无法为该 binding 创建或更新常量缓冲 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [WriteConstant](WriteConstant.md) +- [D3D12CommandList::SetGraphicsDescriptorSets](../D3D12CommandList/SetGraphicsDescriptorSets.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/WriteConstant.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/WriteConstant.md index 14d3acd5..87873d8e 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/WriteConstant.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/WriteConstant.md @@ -1,34 +1,26 @@ # D3D12DescriptorSet::WriteConstant -公开方法，详见头文件声明。 - ```cpp void WriteConstant(uint32_t binding, const void* data, size_t size, size_t offset = 0) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `binding` - 参数语义详见头文件声明。 -- `data` - 参数语义详见头文件声明。 -- `size` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 +把一段常量数据写入指定 `CBV` binding 的 CPU 侧缓存。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 查找对应 binding +- 只接受 `DescriptorType::CBV` +- 若内部字节数组不够大，会自动扩容到 `offset + size` +- 执行 `memcpy` +- 把该 binding 标记为 dirty -```cpp -#include +## 注意事项 -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::WriteConstant(...)。 - (void)object; -} -``` +该方法本身不会创建或更新 GPU buffer。真正把数据上传到 GPU 的步骤在 [`UploadConstantBuffer`](UploadConstantBuffer.md)。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [UploadConstantBuffer](UploadConstantBuffer.md) +- [Initialize](Initialize.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandList.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandList.md index eb4d1580..56d88574 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandList.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandList.md @@ -1,31 +1,32 @@ # D3D12Device::CreateCommandList -创建新对象或资源。 - ```cpp RHICommandList* CreateCommandList(const CommandListDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +创建一条 D3D12 命令列表，并为它同时准备一只匹配类型的 command allocator。 -**返回：** `RHICommandList*` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 若 `m_device` 为空，直接返回 `nullptr` +- 先创建临时 `D3D12CommandAllocator` +- allocator 初始化类型来自 `desc.commandListType` +- 再创建 `D3D12CommandList` +- 命令列表初始化时把 allocator 传入，并由内部 `ComPtr` 接管引用 -```cpp -#include +## 设计说明 -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateCommandList(...)。 - (void)object; -} -``` +这条路径把“命令列表必须依赖 allocator”这一 D3D12 前置条件封装起来了。对上层来说，`CreateCommandList()` 返回的是现成可用的 recorder；对后端来说，它仍保留了 D3D12 allocator/list 的真实关系。 + +## 返回值 + +- 成功返回 `D3D12CommandList*` +- 任一步失败返回 `nullptr` ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) +- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md) +- [D3D12CommandAllocator](../D3D12CommandAllocator/D3D12CommandAllocator.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandQueue.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandQueue.md index 4c3e4a05..123e5a11 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandQueue.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandQueue.md @@ -1,31 +1,31 @@ # D3D12Device::CreateCommandQueue -创建新对象或资源。 - ```cpp RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +创建一条 D3D12 命令队列。 -**返回：** `RHICommandQueue*` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 直接 `new D3D12CommandQueue()` +- 以 `desc.queueType` 调用 `D3D12CommandQueue::Initialize(...)` +- 初始化成功则返回该对象 +- 初始化失败则删除对象并返回 `nullptr` -```cpp -#include +## 前置条件 -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateCommandQueue(...)。 - (void)object; -} -``` +- 设备已经初始化 +- `m_device` 有效 + +## 返回值 + +- 成功返回 `D3D12CommandQueue*` +- 失败返回 `nullptr` ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) +- [D3D12CommandQueue](../D3D12CommandQueue/D3D12CommandQueue.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateTexture.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateTexture.md index 1bdfeb4d..691d5a4a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateTexture.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateTexture.md @@ -1,47 +1,55 @@ # D3D12Device::CreateTexture -创建新对象或资源。 - -该方法在 `XCEngine/RHI/D3D12/D3D12Device.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 - -## 重载 1: 声明 - ```cpp 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; ``` -**参数：** -- `desc` - 参数语义详见头文件声明。 -- `initialData` - 参数语义详见头文件声明。 -- `initialDataSize` - 参数语义详见头文件声明。 -- `rowPitch` - 参数语义详见头文件声明。 +## 作用 -**返回：** `RHITexture*` - 返回值语义详见头文件声明。 +创建 D3D12 纹理资源；可选地在创建后同步上传一份初始数据。 -**示例：** +## 前置条件 -```cpp -#include +- 设备已经成功初始化 +- `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) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) +- [CreateCommandQueue](CreateCommandQueue.md) +- [D3D12Texture](../D3D12Texture/D3D12Texture.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/D3D12Device.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/D3D12Device.md index 19f3595b..8fa846a4 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/D3D12Device.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/D3D12Device.md @@ -6,67 +6,88 @@ **头文件**: `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 上的落地实现。 -## 声明概览 +它承担三类职责： -| 声明 | 类型 | 说明 | -|------|------|------| -| `AdapterInfo` | `struct` | 头文件中的公开声明。 | -| `D3D12Device` | `class` | 继承自 `RHIDevice` 的公开声明。 | +- 初始化 D3D12 运行时根对象：`IDXGIFactory4`、`IDXGIAdapter1`、`ID3D12Device` +- 缓存设备信息与能力信息，供测试、日志和上层系统查询 +- 把 RHI 的资源创建请求翻译成 D3D12 后端对象，例如 buffer、texture、command queue、command list、pipeline state、descriptor heap 与 descriptor set -## 公共方法 +## 生命周期 -| 方法 | 描述 | -|------|------| -| [D3D12Device()](Constructor.md) | 构造对象。 | -| [~D3D12Device()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Initialize](Initialize.md) | 初始化内部状态。 | -| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | -| [GetDevice](GetDevice.md) | 获取相关状态或对象。 | -| [GetFactory](GetFactory.md) | 获取相关状态或对象。 | -| [GetAdapterInfo](GetAdapterInfo.md) | 获取相关状态或对象。 | -| [EnumerateAdapters](EnumerateAdapters.md) | 公开方法，详见头文件声明。 | -| [GetDescriptorHandleIncrementSize](GetDescriptorHandleIncrementSize.md) | 获取相关状态或对象。 | -| [CheckFeatureSupport](CheckFeatureSupport.md) | 公开方法，详见头文件声明。 | -| [SetDeviceRemoved](SetDeviceRemoved.md) | 设置相关状态或配置。 | -| [IsDeviceRemoved](IsDeviceRemoved.md) | 查询当前状态。 | -| [CreateBuffer](CreateBuffer.md) | 创建新对象或资源。 | -| [CreateTexture](CreateTexture.md) | 创建新对象或资源。 | -| [CreateSwapChain](CreateSwapChain.md) | 创建新对象或资源。 | -| [CreateCommandList](CreateCommandList.md) | 创建新对象或资源。 | -| [CreateCommandQueue](CreateCommandQueue.md) | 创建新对象或资源。 | -| [CreateShader](CreateShader.md) | 创建新对象或资源。 | -| [CreatePipelineState](CreatePipelineState.md) | 创建新对象或资源。 | -| [CreatePipelineLayout](CreatePipelineLayout.md) | 创建新对象或资源。 | -| [CreateFence](CreateFence.md) | 创建新对象或资源。 | -| [CreateSampler](CreateSampler.md) | 创建新对象或资源。 | -| [CreateRenderPass](CreateRenderPass.md) | 创建新对象或资源。 | -| [CreateFramebuffer](CreateFramebuffer.md) | 创建新对象或资源。 | -| [CreateDescriptorPool](CreateDescriptorPool.md) | 创建新对象或资源。 | -| [CreateDescriptorSet](CreateDescriptorSet.md) | 创建新对象或资源。 | -| [CreateVertexBufferView](CreateVertexBufferView.md) | 创建新对象或资源。 | -| [CreateIndexBufferView](CreateIndexBufferView.md) | 创建新对象或资源。 | -| [CreateRenderTargetView](CreateRenderTargetView.md) | 创建新对象或资源。 | -| [CreateDepthStencilView](CreateDepthStencilView.md) | 创建新对象或资源。 | -| [CreateShaderResourceView](CreateShaderResourceView.md) | 创建新对象或资源。 | -| [CreateUnorderedAccessView](CreateUnorderedAccessView.md) | 创建新对象或资源。 | -| [GetCapabilities](GetCapabilities.md) | 获取相关状态或对象。 | -| [GetDeviceInfo](GetDeviceInfo.md) | 获取相关状态或对象。 | -| [GetNativeDevice](GetNativeDevice.md) | 获取相关状态或对象。 | -| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | -| [CreateCommandQueueImpl](CreateCommandQueueImpl.md) | 创建新对象或资源。 | -| [CreateCommandListImpl](CreateCommandListImpl.md) | 创建新对象或资源。 | -| [CreateCommandAllocator](CreateCommandAllocator.md) | 创建新对象或资源。 | -| [CreateDescriptorHeap](CreateDescriptorHeap.md) | 创建新对象或资源。 | -| [CreateQueryHeap](CreateQueryHeap.md) | 创建新对象或资源。 | -| [CreateRootSignature](CreateRootSignature.md) | 创建新对象或资源。 | +推荐顺序是： + +1. 构造 `D3D12Device` +2. 调用 [`Initialize`](Initialize.md) +3. 通过设备创建队列、命令列表、资源和状态对象 +4. 先销毁由设备创建出来的对象 +5. 最后调用 `Shutdown()` + +析构函数会调用 `Shutdown()`，但工程上仍应把显式关闭视为标准用法。 + +## 当前实现的真实行为 + +### 适配器与调试层 + +- `Initialize()` 会先创建 DXGI factory，然后从 `adapterIndex` 开始枚举适配器。 +- 软件适配器会被跳过。 +- 当前实现选择“第一个能以 `D3D_FEATURE_LEVEL_11_0` 创建设备的硬件适配器”，而不是做更复杂的打分排序。 +- `enableDebugLayer` 会尝试启用 `ID3D12Debug` 和 `DXGI_CREATE_FACTORY_DEBUG`，这是真正接线了的；但它仍然属于基础调试层支持，不等同于完整 GPU validation 工作流。 + +### 资源工厂策略 + +- [`CreateBuffer`](CreateBuffer.md) 会按 `BufferType` 粗粒度选择 heap： + - `ReadBack` -> `D3D12_HEAP_TYPE_READBACK` + - `Constant / Vertex / Index` -> `D3D12_HEAP_TYPE_UPLOAD` + - 其他 -> `D3D12_HEAP_TYPE_DEFAULT` +- [`CreateTexture`](CreateTexture.md) 对深度格式自动补 `ALLOW_DEPTH_STENCIL`，对常规 2D 纹理自动补 `ALLOW_RENDER_TARGET`。 +- 带初始数据的 `CreateTexture()` 会临时创建 upload queue、allocator、command list，同步上传后再 `WaitForIdle()`，因此这是一个阻塞式初始化路径。 +- [`CreateCommandList`](CreateCommandList.md) 会先创建专用 `D3D12CommandAllocator`，再创建 `D3D12CommandList`；命令列表内部通过 `ComPtr` 持有 allocator。 +- [`CreateDescriptorSet`](CreateDescriptorSet.md) 实际上把分配工作转交给 `D3D12DescriptorHeap::AllocateSet()`。 + +### 能力与设备信息 + +- `QueryAdapterInfo()` 会填充 `AdapterInfo` 与 `RHIDeviceInfo` +- 能力查询覆盖了 ray tracing、mesh shader、conservative rasterization、shader model 等字段 +- 一部分上限值直接来自 D3D12 常量，而不是运行时逐项探测 + +## 所有权与资源管理 + +- 绝大多数 `Create*()` 返回裸指针，调用方负责 `Shutdown()` 与 `delete` +- `D3D12Device` 不做集中式对象注册和统一回收 +- 这更接近商业引擎底层 backend 的“轻工厂”模式：好处是后端简单直接，代价是上层必须严格控制释放顺序 + +## 线程语义 + +`D3D12Device` 自身没有显式加锁。更稳妥的使用方式是： + +- 初始化与关闭在单线程串行完成 +- 资源创建由调用方保证外部同步 +- 不要把它当成天然线程安全的全局服务 + +## 当前限制 + +- 适配器选择仍是“从起始索引往后取第一个可用硬件设备” +- 带初始数据的纹理创建走同步上传路径，初始化成本偏高 +- 某些能力字段是“基础探测 + 常量填充”的组合，不是完整 profile + +## 重点公共方法 + +- [Initialize](Initialize.md) +- [CreateTexture](CreateTexture.md) +- [CreateCommandQueue](CreateCommandQueue.md) +- [CreateCommandList](CreateCommandList.md) +- [CreateDescriptorPool](CreateDescriptorPool.md) +- [CreateDescriptorSet](CreateDescriptorSet.md) ## 相关文档 -- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录 -- [API 总索引](../../../../main.md) - 返回顶层索引 +- [D3D12](../D3D12.md) +- [D3D12CommandQueue](../D3D12CommandQueue/D3D12CommandQueue.md) +- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md) +- [D3D12DescriptorSet](../D3D12DescriptorSet/D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/Initialize.md index 75d2f0f7..7f385a07 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/Initialize.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/Initialize.md @@ -1,31 +1,41 @@ # D3D12Device::Initialize -初始化内部状态。 - ```cpp bool Initialize(const RHIDeviceDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +初始化 D3D12 后端设备根对象，创建 DXGI factory、选择适配器、创建 `ID3D12Device`，并填充能力与设备信息缓存。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 前置条件 -**示例：** +- 进程运行环境必须能加载 DXGI 与 D3D12 runtime +- 如果对象已经初始化过，当前实现会直接返回 `true` -```cpp -#include +## 当前实现行为 -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::Initialize(...)。 - (void)object; -} -``` +- 保存 `desc` +- 调用 `CreateDXGIFactory(desc.enableDebugLayer)` +- 从 `desc.adapterIndex` 开始枚举适配器 +- 跳过 `DXGI_ADAPTER_FLAG_SOFTWARE` 适配器 +- 选择第一个能成功执行 `D3D12CreateDevice(..., D3D_FEATURE_LEVEL_11_0, ...)` 的硬件适配器 +- 调用 `CreateDevice()` 和 `QueryAdapterInfo()` +- 成功后把 `m_initialized` 置为 `true` + +## 失败路径 + +- 创建 factory 失败返回 `false` +- 未找到可用硬件适配器返回 `false` +- 创建设备失败返回 `false` + +## 返回值 + +- `true`：设备可用于后续资源与队列创建 +- `false`：初始化未完成 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) +- [CreateCommandQueue](CreateCommandQueue.md) +- [CreateCommandList](CreateCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGL.md b/docs/api/XCEngine/RHI/OpenGL/OpenGL.md index ea6bc86c..e1a11d3f 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGL.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGL.md @@ -1,42 +1,77 @@ # OpenGL -**命名空间**: `XCEngine::RHI::OpenGL` +**命名空间**: `XCEngine::RHI` **类型**: `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` -- [OpenGLCommandList](OpenGLCommandList/OpenGLCommandList.md) - `OpenGLCommandList.h` -- [OpenGLCommandQueue](OpenGLCommandQueue/OpenGLCommandQueue.md) - `OpenGLCommandQueue.h` -- [OpenGLDepthStencilView](OpenGLDepthStencilView/OpenGLDepthStencilView.md) - `OpenGLDepthStencilView.h` -- [OpenGLDescriptorPool](OpenGLDescriptorPool/OpenGLDescriptorPool.md) - `OpenGLDescriptorPool.h` -- [OpenGLDescriptorSet](OpenGLDescriptorSet/OpenGLDescriptorSet.md) - `OpenGLDescriptorSet.h` -- [OpenGLDevice](OpenGLDevice/OpenGLDevice.md) - `OpenGLDevice.h` -- [OpenGLEnums](OpenGLEnums/OpenGLEnums.md) - `OpenGLEnums.h` -- [OpenGLFence](OpenGLFence/OpenGLFence.md) - `OpenGLFence.h` -- [OpenGLFramebuffer](OpenGLFramebuffer/OpenGLFramebuffer.md) - `OpenGLFramebuffer.h` -- [OpenGLPipelineLayout](OpenGLPipelineLayout/OpenGLPipelineLayout.md) - `OpenGLPipelineLayout.h` -- [OpenGLPipelineState](OpenGLPipelineState/OpenGLPipelineState.md) - `OpenGLPipelineState.h` -- [OpenGLRenderPass](OpenGLRenderPass/OpenGLRenderPass.md) - `OpenGLRenderPass.h` -- [OpenGLRenderTargetView](OpenGLRenderTargetView/OpenGLRenderTargetView.md) - `OpenGLRenderTargetView.h` -- [OpenGLResourceView](OpenGLResourceView/OpenGLResourceView.md) - `OpenGLResourceView.h` -- [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` -- [OpenGLTextureUnitAllocator](OpenGLTextureUnitAllocator/OpenGLTextureUnitAllocator.md) - `OpenGLTextureUnitAllocator.h` -- [OpenGLUniformBufferManager](OpenGLUniformBufferManager/OpenGLUniformBufferManager.md) - `OpenGLUniformBufferManager.h` -- [OpenGLVertexArray](OpenGLVertexArray/OpenGLVertexArray.md) - `OpenGLVertexArray.h` +如果你熟悉 Unity，可以把它理解成“老牌状态机图形 API 的一层引擎化封装”：重点不在提交队列，而在把状态切换、纹理单元、uniform buffer 绑定和 framebuffer 组合管理好。 + +## 设计要点 + +- 设备层负责 WGL 上下文与能力探测。 +- `OpenGLCommandQueue` 更像兼容抽象层的门面，而不是一条真实的 GPU 提交队列。 +- `OpenGLCommandList` 更接近“状态与调用包装器”，不是可延迟提交的录制命令缓冲。 +- `OpenGLPipelineState` 是 CPU 侧状态容器，`Bind()` 时把状态应用到当前上下文。 +- `OpenGLDescriptorSet` 是对纹理单元、sampler 绑定点和 uniform buffer 绑定点的统一封装。 + +## 当前实现边界 + +- 平台路径是 Windows + WGL。 +- 设备初始化支持隐藏窗口自建上下文，也支持附着到现有窗口。 +- 命令队列和命令列表抽象已经能打通统一 RHI 路径，但不少接口仍然是适配性质的轻包装。 +- 部分能力字段或设备信息字段带有“近似值”或“哨兵值”性质，不能把它们当作驱动级精确信息。 + +## 推荐阅读顺序 + +1. [OpenGLDevice](OpenGLDevice/OpenGLDevice.md) +2. [OpenGLCommandList](OpenGLCommandList/OpenGLCommandList.md) +3. [OpenGLPipelineState](OpenGLPipelineState/OpenGLPipelineState.md) +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) -- [API 总索引](../../../main.md) +- [RHI](../RHI.md) +- [Devices, Queues, Command Lists, And Resource Creation](../../../_guides/RHI/Devices-Queues-CommandLists-And-Resource-Creation.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/BeginRenderPass.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/BeginRenderPass.md index 95456b99..f56937f4 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/BeginRenderPass.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/BeginRenderPass.md @@ -1,35 +1,27 @@ # OpenGLCommandList::BeginRenderPass -公开方法，详见头文件声明。 - ```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 路径。 +## 作用 -**参数：** -- `renderPass` - 参数语义详见头文件声明。 -- `framebuffer` - 参数语义详见头文件声明。 -- `renderArea` - 参数语义详见头文件声明。 -- `clearValueCount` - 参数语义详见头文件声明。 -- `clearValues` - 参数语义详见头文件声明。 +绑定 framebuffer，并按 render pass 描述执行必要的颜色/深度/模板清屏。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 当前忽略 `renderArea` +- 若 `framebuffer` 为空，直接返回 +- 先绑定 `OpenGLFramebuffer` +- 若 `renderPass` 有效，则读取各附件的 `loadOp` +- 对 `LoadAction::Clear` 的颜色附件执行 `glClearBufferfv(GL_COLOR, ...)` +- 对深度/模板附件执行 `glClearBufferfv(GL_DEPTH, ...)` / `glClearBufferfv(GL_STENCIL, ...)` -```cpp -#include +## 注意事项 -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::BeginRenderPass(...)。 - (void)object; -} -``` +`EndRenderPass()` 当前只会把 framebuffer 绑定回默认帧缓冲，不存在显式 API 那种 render pass instance 生命周期管理。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [SetRenderTargets](SetRenderTargets.md) +- [OpenGLRenderPass](../OpenGLRenderPass/OpenGLRenderPass.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/CopyResource.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/CopyResource.md index 392fed75..4b2f89d5 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/CopyResource.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/CopyResource.md @@ -1,32 +1,25 @@ # OpenGLCommandList::CopyResource -公开方法，详见头文件声明。 - ```cpp void CopyResource(RHIResourceView* dst, RHIResourceView* src) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `dst` - 参数语义详见头文件声明。 -- `src` - 参数语义详见头文件声明。 +把一个纹理资源的内容复制到另一个纹理资源。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 要求 `dst` 和 `src` 都有效 +- 只处理双方都能解析出 texture object 的路径 +- 根据源/目标纹理尺寸取较小的宽高深 +- 调用 `glCopyImageSubData(...)` -```cpp -#include +## 当前限制 -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::CopyResource(...)。 - (void)object; -} -``` +当前主路径只覆盖纹理复制，不是一个通用的“任意资源复制”实现。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [SetRenderTargets](SetRenderTargets.md) +- [TransitionBarrier](TransitionBarrier.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Dispatch.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Dispatch.md index 8217d4e8..7f74c725 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Dispatch.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Dispatch.md @@ -1,33 +1,23 @@ # OpenGLCommandList::Dispatch -公开方法，详见头文件声明。 - ```cpp void Dispatch(uint32_t x, uint32_t y, uint32_t z) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `x` - 参数语义详见头文件声明。 -- `y` - 参数语义详见头文件声明。 -- `z` - 参数语义详见头文件声明。 +发出一次 compute dispatch。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +直接调用 `glDispatchCompute(x, y, z)`。 -```cpp -#include +## 前置条件 -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::Dispatch(...)。 - (void)object; -} -``` +- 当前上下文已绑定 compute program +- 相关 descriptor set / image / buffer 已由调用方提前绑定 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [SetComputeDescriptorSets](SetComputeDescriptorSets.md) +- [TransitionBarrier](TransitionBarrier.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Draw.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Draw.md index 190872bb..8e1c80d1 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Draw.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Draw.md @@ -1,49 +1,22 @@ # 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 void Draw(uint32_t vertexCount, uint32_t instanceCount, uint32_t startVertex, uint32_t startInstance) override; ``` -**参数：** -- `vertexCount` - 参数语义详见头文件声明。 -- `instanceCount` - 参数语义详见头文件声明。 -- `startVertex` - 参数语义详见头文件声明。 -- `startInstance` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +发出一次非索引绘制。 -**示例：** +## 当前实现行为 -```cpp -#include +直接调用 `glDrawArraysInstanced(...)`。 -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::Draw(...)。 - (void)object; -} -``` +## 注意事项 + +`startInstance` 当前没有真实参与 OpenGL 调用。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [SetVertexBuffers](SetVertexBuffers.md) +- [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/DrawIndexed.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/DrawIndexed.md index f2667e83..39d9cf17 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/DrawIndexed.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/DrawIndexed.md @@ -1,51 +1,24 @@ # 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 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 -#include +- 根据 `startIndex` 和当前 index type 计算字节偏移 +- 调用 `glDrawElementsInstanced(...)` -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::DrawIndexed(...)。 - (void)object; -} -``` +## 当前限制 + +- `baseVertex` 当前未生效 +- `startInstance` 当前未生效 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [SetIndexBuffer](SetIndexBuffer.md) +- [Draw](Draw.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/OpenGLCommandList.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/OpenGLCommandList.md index 2c0c7063..8b3830fe 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/OpenGLCommandList.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/OpenGLCommandList.md @@ -6,130 +6,75 @@ **头文件**: `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 接近的调用形状 -| 声明 | 类型 | 说明 | -|------|------|------| -| `PrimitiveType` | `enum class` | 头文件中的公开声明。 | -| `ClearFlag` | `enum class` | 头文件中的公开声明。 | -| `OpenGLCommandList` | `class` | 继承自 `RHICommandList` 的公开声明。 | +换句话说，它更像“统一 RHI 语义下的 OpenGL immediate command facade”。 -## 公共方法 +## 生命周期 -| 方法 | 描述 | -|------|------| -| [OpenGLCommandList()](Constructor.md) | 构造对象。 | -| [~OpenGLCommandList()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | -| [Reset](Reset.md) | 公开方法，详见头文件声明。 | -| [Close](Close.md) | 公开方法，详见头文件声明。 | -| [Clear](Clear.md) | 清空内部数据。 | -| [ClearColor](ClearColor.md) | 清空内部数据。 | -| [ClearDepth](ClearDepth.md) | 清空内部数据。 | -| [ClearStencil](ClearStencil.md) | 清空内部数据。 | -| [ClearDepthStencil](ClearDepthStencil.md) | 清空内部数据。 | -| [SetShader](SetShader.md) | 设置相关状态或配置。 | -| [SetUniformInt](SetUniformInt.md) | 设置相关状态或配置。 | -| [SetUniformFloat](SetUniformFloat.md) | 设置相关状态或配置。 | -| [SetUniformVec3](SetUniformVec3.md) | 设置相关状态或配置。 | -| [SetUniformVec4](SetUniformVec4.md) | 设置相关状态或配置。 | -| [SetUniformMat4](SetUniformMat4.md) | 设置相关状态或配置。 | -| [SetPipelineState](SetPipelineState.md) | 设置相关状态或配置。 | -| [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md) | 设置相关状态或配置。 | -| [SetComputeDescriptorSets](SetComputeDescriptorSets.md) | 设置相关状态或配置。 | -| [SetVertexBuffers](SetVertexBuffers.md) | 设置相关状态或配置。 | -| [SetIndexBuffer](SetIndexBuffer.md) | 设置相关状态或配置。 | -| [SetVertexBuffer](SetVertexBuffer.md) | 设置相关状态或配置。 | -| [BindVertexArray](BindVertexArray.md) | 公开方法，详见头文件声明。 | -| [UseShader](UseShader.md) | 公开方法，详见头文件声明。 | -| [SetViewport](SetViewport.md) | 设置相关状态或配置。 | -| [SetViewports](SetViewports.md) | 设置相关状态或配置。 | -| [SetScissor](SetScissor.md) | 设置相关状态或配置。 | -| [SetScissorRects](SetScissorRects.md) | 设置相关状态或配置。 | -| [EnableScissorTest](EnableScissorTest.md) | 公开方法，详见头文件声明。 | -| [EnableDepthTest](EnableDepthTest.md) | 公开方法，详见头文件声明。 | -| [EnableDepthWrite](EnableDepthWrite.md) | 公开方法，详见头文件声明。 | -| [SetDepthFunc](SetDepthFunc.md) | 设置相关状态或配置。 | -| [EnableStencilTest](EnableStencilTest.md) | 公开方法，详见头文件声明。 | -| [SetStencilFunc](SetStencilFunc.md) | 设置相关状态或配置。 | -| [SetStencilOp](SetStencilOp.md) | 设置相关状态或配置。 | -| [EnableBlending](EnableBlending.md) | 公开方法，详见头文件声明。 | -| [SetBlendFunc](SetBlendFunc.md) | 设置相关状态或配置。 | -| [SetBlendFuncSeparate](SetBlendFuncSeparate.md) | 设置相关状态或配置。 | -| [SetBlendEquation](SetBlendEquation.md) | 设置相关状态或配置。 | -| [SetBlendColor](SetBlendColor.md) | 设置相关状态或配置。 | -| [EnableCulling](EnableCulling.md) | 公开方法，详见头文件声明。 | -| [SetCullFace](SetCullFace.md) | 设置相关状态或配置。 | -| [SetFrontFace](SetFrontFace.md) | 设置相关状态或配置。 | -| [SetPolygonMode](SetPolygonMode.md) | 设置相关状态或配置。 | -| [SetPolygonOffset](SetPolygonOffset.md) | 设置相关状态或配置。 | -| [SetPrimitiveType](SetPrimitiveType.md) | 设置相关状态或配置。 | -| [Draw](Draw.md) | 公开方法，详见头文件声明。 | -| [DrawInstanced](DrawInstanced.md) | 公开方法，详见头文件声明。 | -| [DrawIndexed](DrawIndexed.md) | 公开方法，详见头文件声明。 | -| [DrawIndexedInstanced](DrawIndexedInstanced.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) | 清空内部数据。 | +- 默认构造即可使用 +- `Reset()` 只会清理少量软件侧缓存 +- `Close()` 当前为空实现 +- `Shutdown()` 负责释放内部拼装的 framebuffer 与内部 VAO + +## 当前实现的真实行为 + +### 状态与 barrier + +- [`TransitionBarrier`](TransitionBarrier.md) 不会生成显式资源状态机 +- 它会把纹理的软状态改成 `stateAfter` +- 然后直接调用 `glMemoryBarrier(GL_ALL_BARRIER_BITS)` + +### Render pass 与 framebuffer + +- [`BeginRenderPass`](BeginRenderPass.md) 会绑定 framebuffer，并按 render pass 描述决定是否清颜色/深度/模板 +- [`SetRenderTargets`](SetRenderTargets.md) 在多 RT 或带 DS 的情况下会临时构造 `OpenGLFramebuffer` +- `EndRenderPass()` 只是把 `GL_FRAMEBUFFER` 绑定回 `0` + +### 描述符与顶点输入 + +- [`SetGraphicsDescriptorSets`](SetGraphicsDescriptorSets.md) / [`SetComputeDescriptorSets`](SetComputeDescriptorSets.md) 会调用 `OpenGLDescriptorSet::BindWithPipelineLayout(...)` +- [`SetVertexBuffers`](SetVertexBuffers.md) 会使用内部 VAO，并尽量按照当前 `OpenGLPipelineState` 的 input layout 配置 vertex attribute +- [`SetIndexBuffer`](SetIndexBuffer.md) 绑定 `GL_ELEMENT_ARRAY_BUFFER`，并缓存 index type 与偏移 + +### 绘制与计算 + +- [`Draw`](Draw.md) 直接调用 `glDrawArraysInstanced(...)` +- [`DrawIndexed`](DrawIndexed.md) 直接调用 `glDrawElementsInstanced(...)` +- `baseVertex` 与 `startInstance` 当前都没有真实生效 +- [`Dispatch`](Dispatch.md) 直接调用 `glDispatchCompute(...)` + +## 当前限制 + +- 不是录制型命令缓冲，很多调用会立刻影响当前上下文 +- `Close()` 当前为空实现 +- `DrawIndexed()` 不使用 `baseVertex` +- `SetStencilRef()` 当前通过 `glStencilFunc(GL_FRONT_AND_BACK, ...)` 设置，语义比较粗 + +## 重点公共方法 + +- [TransitionBarrier](TransitionBarrier.md) +- [BeginRenderPass](BeginRenderPass.md) +- [SetRenderTargets](SetRenderTargets.md) +- [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md) +- [SetComputeDescriptorSets](SetComputeDescriptorSets.md) +- [SetVertexBuffers](SetVertexBuffers.md) +- [SetIndexBuffer](SetIndexBuffer.md) +- [CopyResource](CopyResource.md) +- [Draw](Draw.md) +- [DrawIndexed](DrawIndexed.md) +- [Dispatch](Dispatch.md) ## 相关文档 -- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录 -- [API 总索引](../../../../main.md) - 返回顶层索引 +- [OpenGL](../OpenGL.md) +- [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md) +- [OpenGLDescriptorSet](../OpenGLDescriptorSet/OpenGLDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetComputeDescriptorSets.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetComputeDescriptorSets.md index 71c0120d..384700fc 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetComputeDescriptorSets.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetComputeDescriptorSets.md @@ -1,34 +1,22 @@ # OpenGLCommandList::SetComputeDescriptorSets -设置相关状态或配置。 - ```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 路径。 +## 作用 -**参数：** -- `firstSet` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `descriptorSets` - 参数语义详见头文件声明。 -- `pipelineLayout` - 参数语义详见头文件声明。 +把一组 descriptor set 绑定到 compute 路径。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +实现与 [`SetGraphicsDescriptorSets`](SetGraphicsDescriptorSets.md) 基本相同，同样依赖 `OpenGLDescriptorSet::BindWithPipelineLayout(...)`。 -```cpp -#include +## 设计说明 -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetComputeDescriptorSets(...)。 - (void)object; -} -``` +在当前 OpenGL 后端里，graphics/compute 资源绑定并没有完全不同的两套容器模型，差别主要体现在最终 program 的使用方式和某些资源目标的解释上。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [SetGraphicsDescriptorSets](SetGraphicsDescriptorSets.md) +- [Dispatch](Dispatch.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetGraphicsDescriptorSets.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetGraphicsDescriptorSets.md index c30a5a94..21757e83 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetGraphicsDescriptorSets.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetGraphicsDescriptorSets.md @@ -1,34 +1,31 @@ # OpenGLCommandList::SetGraphicsDescriptorSets -设置相关状态或配置。 - ```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 路径。 +## 作用 -**参数：** -- `firstSet` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `descriptorSets` - 参数语义详见头文件声明。 -- `pipelineLayout` - 参数语义详见头文件声明。 +把一组 descriptor set 绑定到 graphics 路径。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 把 `pipelineLayout` 转成 `OpenGLPipelineLayout` +- 对每个非空 descriptor set 调用： + - `OpenGLDescriptorSet::BindWithPipelineLayout(openGLPipelineLayout, firstSet + i)` -```cpp -#include +## 正确理解 -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetGraphicsDescriptorSets(...)。 - (void)object; -} -``` +这里绑定的不是 D3D12/Vulkan 意义上的原生 descriptor table，而是： + +- uniform buffer binding point +- texture unit +- sampler binding point +- image unit + +的统一适配。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [SetComputeDescriptorSets](SetComputeDescriptorSets.md) +- [OpenGLDescriptorSet](../OpenGLDescriptorSet/OpenGLDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetIndexBuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetIndexBuffer.md index f1d0b0e5..e3b9e1f5 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetIndexBuffer.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetIndexBuffer.md @@ -1,59 +1,21 @@ # OpenGLCommandList::SetIndexBuffer -设置相关状态或配置。 - -该方法在 `XCEngine/RHI/OpenGL/OpenGLCommandList.h` 中提供了 3 个重载，当前页面统一汇总这些公开声明。 - -## 重载 1: 声明 - ```cpp void SetIndexBuffer(RHIResourceView* buffer, uint64_t offset) override; ``` -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +绑定索引缓冲，并缓存索引格式与字节偏移。 -## 重载 2: 声明 +## 当前实现行为 -```cpp -void SetIndexBuffer(unsigned int buffer, unsigned int type); -``` - -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `type` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 3: 声明 - -```cpp -void SetIndexBuffer(unsigned int buffer, unsigned int type, size_t offset); -``` - -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `type` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetIndexBuffer(...)。 - (void)object; -} -``` +- 确保内部 VAO 已绑定 +- 把 view 底层 buffer 绑定到 `GL_ELEMENT_ARRAY_BUFFER` +- 根据 view 的 `Format` 推导 `GL_UNSIGNED_SHORT` 或 `GL_UNSIGNED_INT` +- 缓存 `m_currentIndexType` 和 `m_currentIndexOffset` ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [SetVertexBuffers](SetVertexBuffers.md) +- [DrawIndexed](DrawIndexed.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetRenderTargets.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetRenderTargets.md index 1023a145..3d822ce8 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetRenderTargets.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetRenderTargets.md @@ -1,33 +1,27 @@ # OpenGLCommandList::SetRenderTargets -设置相关状态或配置。 - ```cpp 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 +## 设计说明 -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetRenderTargets(...)。 - (void)object; -} -``` +这条实现体现了 OpenGL 后端的一个关键现实：抽象层可以把“颜色附件视图”和“深度附件视图”分开传入，但最终 OpenGL 仍需要一个具体 framebuffer 对象来承载组合结果。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [BeginRenderPass](BeginRenderPass.md) +- [CopyResource](CopyResource.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetVertexBuffers.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetVertexBuffers.md index c18816eb..03ee7f76 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetVertexBuffers.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetVertexBuffers.md @@ -1,52 +1,27 @@ # OpenGLCommandList::SetVertexBuffers -设置相关状态或配置。 - -该方法在 `XCEngine/RHI/OpenGL/OpenGLCommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 - -## 重载 1: 声明 - ```cpp 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 -void SetVertexBuffers(unsigned int startSlot, unsigned int count, const unsigned int* buffers, const size_t* offsets, const size_t* strides); -``` +- 确保内部 VAO 已创建并绑定 +- 先禁用上一次配置过的顶点属性 +- 如果当前存在 `OpenGLPipelineState` 且其 `InputLayoutDesc` 非空： + - 按 input layout 逐元素配置 `glVertexAttribPointer` 或 `glVertexAttribIPointer` +- 否则走退化路径： + - 按 slot 顺序把每个 buffer 当作一组连续 float 属性 -**参数：** -- `startSlot` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `buffers` - 参数语义详见头文件声明。 -- `offsets` - 参数语义详见头文件声明。 -- `strides` - 参数语义详见头文件声明。 +## 设计说明 -**返回：** `void` - 无返回值。 - -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetVertexBuffers(...)。 - (void)object; -} -``` +OpenGL 顶点输入配置强依赖 VAO 和当前 attribute 状态，因此这里需要命令列表自己维护一个内部 VAO，来把抽象层的输入布局概念落到 GL 状态机上。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [SetIndexBuffer](SetIndexBuffer.md) +- [Draw](Draw.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/TransitionBarrier.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/TransitionBarrier.md index 0cc7f30e..25dd0f89 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/TransitionBarrier.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/TransitionBarrier.md @@ -1,33 +1,27 @@ # OpenGLCommandList::TransitionBarrier -公开方法，详见头文件声明。 - ```cpp void TransitionBarrier(RHIResourceView* resource, ResourceStates stateBefore, ResourceStates stateAfter) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `resource` - 参数语义详见头文件声明。 -- `stateBefore` - 参数语义详见头文件声明。 -- `stateAfter` - 参数语义详见头文件声明。 +在 OpenGL 后端里表达一次抽象资源状态转换。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- `stateBefore` 当前不参与逻辑 +- 若 view 指向纹理资源，则把该纹理的软状态改成 `stateAfter` +- 随后无条件调用 `glMemoryBarrier(GL_ALL_BARRIER_BITS)` -```cpp -#include +## 正确理解 -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::TransitionBarrier(...)。 - (void)object; -} -``` +这不是 D3D12/Vulkan 那种精确资源状态机。它更像： + +- 抽象层状态字段更新 +- 外加一条最保守的全局内存屏障 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [SetRenderTargets](SetRenderTargets.md) +- [Dispatch](Dispatch.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/ExecuteCommandLists.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/ExecuteCommandLists.md index e023a4d2..a496b71e 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/ExecuteCommandLists.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/ExecuteCommandLists.md @@ -1,32 +1,22 @@ # OpenGLCommandQueue::ExecuteCommandLists -公开方法，详见头文件声明。 - ```cpp void ExecuteCommandLists(uint32_t count, void** lists) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `lists` - 参数语义详见头文件声明。 +抽象层保留的“提交命令列表”入口。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +当前实现为空。 -```cpp -#include +## 正确理解 -void Example() { - XCEngine::RHI::OpenGLCommandQueue object; - // 根据上下文补齐参数后调用 OpenGLCommandQueue::ExecuteCommandLists(...)。 - (void)object; -} -``` +这并不是疏漏，而是当前 OpenGL 后端架构决定的结果：`OpenGLCommandList` 上的大部分操作会立刻作用到当前上下文，因此这里不存在 D3D12/Vulkan 意义上的“统一提交时刻”。 ## 相关文档 -- [返回类总览](OpenGLCommandQueue.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandQueue](OpenGLCommandQueue.md) +- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/OpenGLCommandQueue.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/OpenGLCommandQueue.md index ac26836c..6e3f2acb 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/OpenGLCommandQueue.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/OpenGLCommandQueue.md @@ -6,37 +6,42 @@ **头文件**: `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) | 构造对象。 | -| [~OpenGLCommandQueue()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | -| [ExecuteCommandLists](ExecuteCommandLists.md) | 公开方法，详见头文件声明。 | -| [Signal](Signal.md) | 公开方法，详见头文件声明。 | -| [Wait](Wait.md) | 公开方法，详见头文件声明。 | -| [GetCompletedValue](GetCompletedValue.md) | 获取相关状态或对象。 | -| [WaitForIdle](WaitForIdle.md) | 公开方法，详见头文件声明。 | -| [GetType](GetType.md) | 获取相关状态或对象。 | -| [GetTimestampFrequency](GetTimestampFrequency.md) | 获取相关状态或对象。 | -| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | -| [WaitForPreviousFrame](WaitForPreviousFrame.md) | 公开方法，详见头文件声明。 | -| [GetCurrentFrame](GetCurrentFrame.md) | 获取相关状态或对象。 | +## 正确理解 + +如果从商业引擎角度看，它更像“为了保持跨后端接口整齐而保留的一层 shim”，而不是调度核心。 + +## 当前限制 + +- 不支持真正的命令列表提交 +- 不提供成熟的 GPU timeline 语义 +- `Wait()` / `ExecuteCommandLists()` 仍是占位实现 + +## 重点公共方法 + +- [ExecuteCommandLists](ExecuteCommandLists.md) +- [Signal](Signal.md) +- [WaitForIdle](WaitForIdle.md) ## 相关文档 -- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录 -- [API 总索引](../../../../main.md) - 返回顶层索引 +- [OpenGL](../OpenGL.md) +- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Signal.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Signal.md index 6a165efe..32e14331 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Signal.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/Signal.md @@ -1,32 +1,19 @@ # OpenGLCommandQueue::Signal -公开方法，详见头文件声明。 - ```cpp void Signal(RHIFence* fence, uint64_t value) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `fence` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +给抽象 fence 写入一个值，并通过 `glFlush()` 触发驱动尽快开始处理已发出的 OpenGL 命令。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandQueue object; - // 根据上下文补齐参数后调用 OpenGLCommandQueue::Signal(...)。 - (void)object; -} -``` +- 若 `fence` 非空，则调用 `fence->Signal(value)` +- 随后调用 `glFlush()` ## 相关文档 -- [返回类总览](OpenGLCommandQueue.md) -- [返回模块目录](../OpenGL.md) +- [WaitForIdle](WaitForIdle.md) +- [OpenGLCommandQueue](OpenGLCommandQueue.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForIdle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForIdle.md index bf315677..5c0364e6 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForIdle.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandQueue/WaitForIdle.md @@ -1,30 +1,22 @@ # OpenGLCommandQueue::WaitForIdle -公开方法，详见头文件声明。 - ```cpp void WaitForIdle() override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandQueue.h`，当前页面用于固定 `OpenGLCommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +阻塞 CPU，直到当前上下文之前发出的 OpenGL 命令全部完成。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +直接调用 `glFinish()`。 -```cpp -#include +## 设计说明 -void Example() { - XCEngine::RHI::OpenGLCommandQueue object; - // 根据上下文补齐参数后调用 OpenGLCommandQueue::WaitForIdle(...)。 - (void)object; -} -``` +这是一条非常强的同步原语，适合初始化、截图、调试和测试，不适合高频帧循环。 ## 相关文档 -- [返回类总览](OpenGLCommandQueue.md) -- [返回模块目录](../OpenGL.md) +- [Signal](Signal.md) +- [OpenGLCommandQueue](OpenGLCommandQueue.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreatePipelineState.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreatePipelineState.md index 8b49ac8b..69bb3c12 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreatePipelineState.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreatePipelineState.md @@ -1,31 +1,29 @@ # OpenGLDevice::CreatePipelineState -创建新对象或资源。 - ```cpp RHIPipelineState* CreatePipelineState(const GraphicsPipelineDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +创建一份 OpenGL 管线状态对象，并在需要时同时构建 graphics program。 -**返回：** `RHIPipelineState*` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 总是先创建 `OpenGLPipelineState` +- 把输入布局、光栅化、混合、深度模板、拓扑、RT format、sample count 写入该对象 +- 若没有任何 graphics shader payload，直接返回仅含状态的 PSO +- 若有 shader payload，则要求至少同时存在 vertex 和 fragment shader +- 会 `MakeContextCurrent()` +- 根据源码或文件路径构建 `OpenGLShader` +- 成功后把该 shader 作为 owned graphics shader 挂到 PSO 上 -```cpp -#include +## 返回值 -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreatePipelineState(...)。 - (void)object; -} -``` +- 成功返回 `OpenGLPipelineState*` +- shader 不完整、上下文不可用或编译失败时返回 `nullptr` ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md) +- [CreateShader](CreateShader.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateShader.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateShader.md index 56b5113f..8276195a 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateShader.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateShader.md @@ -1,31 +1,25 @@ # OpenGLDevice::CreateShader -创建新对象或资源。 - ```cpp RHIShader* CreateShader(const ShaderCompileDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +在当前 OpenGL 上下文中创建并编译一个 `OpenGLShader`。 -**返回：** `RHIShader*` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 先 `MakeContextCurrent()` +- 若 `desc.sourceLanguage == ShaderLanguage::GLSL` 且提供了源码，走源码编译路径 +- 若提供了 `fileName`，走文件编译路径 +- 其他情况直接失败 -```cpp -#include +## 注意事项 -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateShader(...)。 - (void)object; -} -``` +当前实现不负责 HLSL 到 GLSL 的转换；这里期待的就是 GLSL 源码或 GLSL 文件。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLShader](../OpenGLShader/OpenGLShader.md) +- [CreatePipelineState](CreatePipelineState.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateTexture.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateTexture.md index cdb4d700..e78c8e6b 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateTexture.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateTexture.md @@ -1,47 +1,35 @@ # OpenGLDevice::CreateTexture -创建新对象或资源。 - -该方法在 `XCEngine/RHI/OpenGL/OpenGLDevice.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 - -## 重载 1: 声明 - ```cpp 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; ``` -**参数：** -- `desc` - 参数语义详见头文件声明。 -- `initialData` - 参数语义详见头文件声明。 -- `initialDataSize` - 参数语义详见头文件声明。 -- `rowPitch` - 参数语义详见头文件声明。 +## 作用 -**返回：** `RHITexture*` - 返回值语义详见头文件声明。 +创建 OpenGL 纹理对象；可选地带一份初始数据。 -**示例：** +## 当前实现行为 -```cpp -#include +### 无初始数据路径 -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateTexture(...)。 - (void)object; -} -``` +- 根据 `TextureType` 选择 `OpenGLTextureType` +- 把抽象 `Format` 转为 `OpenGLFormat` +- 调用 `OpenGLTexture::Initialize(...)` +- 设置抽象层格式字段 + +### 带初始数据路径 + +- 会先 `MakeContextCurrent()` +- 只在当前上下文可用时继续 +- 初始化成功后把纹理状态设为 `ResourceStates::PixelShaderResource` + +## 注意事项 + +- 带初始数据路径显式保证了上下文当前；无初始数据路径则默认假设当前上下文已经可用 +- `rowPitch` 和 `initialDataSize` 当前没有形成复杂的数据上传策略 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) +- [OpenGLTexture](../OpenGLTexture/OpenGLTexture.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Initialize.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Initialize.md index 0e36090b..cc4792ac 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Initialize.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Initialize.md @@ -1,31 +1,31 @@ # OpenGLDevice::Initialize -初始化内部状态。 - ```cpp bool Initialize(const RHIDeviceDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +创建隐藏窗口并在其上建立 OpenGL 上下文，初始化当前设备。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 若设备已经初始化，直接返回 `true` +- 忽略 `desc` 中的大部分字段 +- 创建隐藏窗口 +- 调用 `AttachWindow(...)` +- `AttachWindow(...)` 会继续配置像素格式、建立上下文、加载 GLAD 并填充能力信息 -```cpp -#include +## 设计说明 -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::Initialize(...)。 - (void)object; -} -``` +这条路径适合无现成窗口的测试、离屏初始化和工具场景。它让 OpenGL 后端能像显式 API 一样先把“设备”建起来，再逐步创建资源。 + +## 返回值 + +- `true`：上下文已可用 +- `false`：窗口、像素格式或上下文建立失败 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [InitializeWithExistingWindow](InitializeWithExistingWindow.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/InitializeWithExistingWindow.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/InitializeWithExistingWindow.md index 55e110e5..7d26a915 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/InitializeWithExistingWindow.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/InitializeWithExistingWindow.md @@ -1,31 +1,27 @@ # OpenGLDevice::InitializeWithExistingWindow -初始化内部状态。 - ```cpp bool InitializeWithExistingWindow(HWND hwnd); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `hwnd` - 参数语义详见头文件声明。 +把 OpenGL 设备附着到调用方已经拥有的窗口上。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 若设备尚未初始化： + - 要求 `hwnd` 非空 + - 直接走 `AttachWindow(hwnd)` +- 若设备已初始化： + - 若传入的就是当前窗口，返回 `true` + - 否则尝试切换附着窗口 -```cpp -#include +## 适用场景 -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::InitializeWithExistingWindow(...)。 - (void)object; -} -``` +这是交换链、实时窗口渲染和编辑器嵌入式视口更常用的路径。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [Initialize](Initialize.md) +- [CreateTexture](CreateTexture.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/OpenGLDevice.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/OpenGLDevice.md index 369414f1..e7040152 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/OpenGLDevice.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/OpenGLDevice.md @@ -6,56 +6,69 @@ **头文件**: `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` 的公开声明。 | +## 生命周期 -## 公共方法 +支持两种典型用法： -| 方法 | 描述 | -|------|------| -| [OpenGLDevice()](Constructor.md) | 构造对象。 | -| [~OpenGLDevice()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Initialize](Initialize.md) | 初始化内部状态。 | -| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | -| [InitializeWithExistingWindow](InitializeWithExistingWindow.md) | 初始化内部状态。 | -| [GetDeviceInfoImpl](GetDeviceInfoImpl.md) | 获取相关状态或对象。 | -| [MakeContextCurrent](MakeContextCurrent.md) | 公开方法，详见头文件声明。 | -| [GetNativeContext](GetNativeContext.md) | 获取相关状态或对象。 | -| [CreateBuffer](CreateBuffer.md) | 创建新对象或资源。 | -| [CreateTexture](CreateTexture.md) | 创建新对象或资源。 | -| [CreateSwapChain](CreateSwapChain.md) | 创建新对象或资源。 | -| [CreateCommandList](CreateCommandList.md) | 创建新对象或资源。 | -| [CreateCommandQueue](CreateCommandQueue.md) | 创建新对象或资源。 | -| [CreateShader](CreateShader.md) | 创建新对象或资源。 | -| [CreatePipelineState](CreatePipelineState.md) | 创建新对象或资源。 | -| [CreatePipelineLayout](CreatePipelineLayout.md) | 创建新对象或资源。 | -| [CreateFence](CreateFence.md) | 创建新对象或资源。 | -| [CreateSampler](CreateSampler.md) | 创建新对象或资源。 | -| [CreateRenderPass](CreateRenderPass.md) | 创建新对象或资源。 | -| [CreateFramebuffer](CreateFramebuffer.md) | 创建新对象或资源。 | -| [CreateDescriptorPool](CreateDescriptorPool.md) | 创建新对象或资源。 | -| [CreateDescriptorSet](CreateDescriptorSet.md) | 创建新对象或资源。 | -| [CreateVertexBufferView](CreateVertexBufferView.md) | 创建新对象或资源。 | -| [CreateIndexBufferView](CreateIndexBufferView.md) | 创建新对象或资源。 | -| [CreateRenderTargetView](CreateRenderTargetView.md) | 创建新对象或资源。 | -| [CreateDepthStencilView](CreateDepthStencilView.md) | 创建新对象或资源。 | -| [CreateShaderResourceView](CreateShaderResourceView.md) | 创建新对象或资源。 | -| [CreateUnorderedAccessView](CreateUnorderedAccessView.md) | 创建新对象或资源。 | -| [GetCapabilities](GetCapabilities.md) | 获取相关状态或对象。 | -| [GetDeviceInfo](GetDeviceInfo.md) | 获取相关状态或对象。 | -| [GetNativeDevice](GetNativeDevice.md) | 获取相关状态或对象。 | -| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | +1. 通过 [`Initialize`](Initialize.md) 让设备自己创建隐藏窗口和上下文 +2. 通过 [`InitializeWithExistingWindow`](InitializeWithExistingWindow.md) 绑定到现有窗口 + +## 当前实现的真实行为 + +### 上下文与窗口管理 + +- 若走 `Initialize()`，设备会创建一个隐藏窗口，再附着像素格式并建立上下文 +- 若走 `InitializeWithExistingWindow()`，设备会直接接管调用方窗口 +- 会先用临时 context 探测 `WGL_ARB_create_context`，再尝试创建 OpenGL 4.6 debug context +- 若高级上下文创建失败，会回退到 `wglCreateContext()` + +### 能力和设备信息 + +- `vendor`、`renderer`、`version` 来自 `glGetString(...)` +- `vendorId` 由厂商字符串启发式推断 +- `deviceId` 由 renderer 字符串哈希得到，不是真实 PCI device id +- `dedicatedVideoMemory` 在非软件渲染器情况下被写成 `1`，这只是“非零哨兵值”，不是显存探测结果 + +### 工厂行为 + +- [`CreateShader`](CreateShader.md) 与 [`CreatePipelineState`](CreatePipelineState.md) 会显式 `MakeContextCurrent()` +- [`CreateTexture`](CreateTexture.md) 的带初始数据路径也会显式切当前上下文 +- `CreateCommandList()` 和 `CreateCommandQueue()` 当前只是构造轻量对象，不做和设备的深度关联 +- `CreateDescriptorPool()` 会把 `OpenGLTextureUnitAllocator` 注入 pool + +## 设计说明 + +OpenGL 后端的“设备”更多是上下文拥有者和运行环境协调者。它不可能像 D3D12 那样把提交、队列、同步都做成显式对象，因此文档必须把“上下文当前性”当成使用前提讲清楚。 + +## 当前限制 + +- 平台路径目前是 Win32/WGL +- 某些设备信息字段是推断值或哨兵值，不可当作驱动级精确数据 +- `CreateCommandQueue()` / `CreateCommandList()` 仍是轻量门面，不要用 D3D12/Vulkan 的思维期待它们承担真实提交调度 + +## 重点公共方法 + +- [Initialize](Initialize.md) +- [InitializeWithExistingWindow](InitializeWithExistingWindow.md) +- [CreateTexture](CreateTexture.md) +- [CreateShader](CreateShader.md) +- [CreatePipelineState](CreatePipelineState.md) ## 相关文档 -- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录 -- [API 总索引](../../../../main.md) - 返回顶层索引 +- [OpenGL](../OpenGL.md) +- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md) +- [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md) +- [OpenGLShader](../OpenGLShader/OpenGLShader.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/Bind.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/Bind.md index dc8a7d66..0a06710b 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/Bind.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/Bind.md @@ -1,30 +1,27 @@ # OpenGLPipelineState::Bind -公开方法，详见头文件声明。 - ```cpp 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 +## 注意事项 -void Example() { - XCEngine::RHI::OpenGLPipelineState object; - // 根据上下文补齐参数后调用 OpenGLPipelineState::Bind(...)。 - (void)object; -} -``` +当前 `Bind()` 不会自动调用 `ApplyViewport()` 和 `ApplyScissor()`。 ## 相关文档 -- [返回类总览](OpenGLPipelineState.md) -- [返回模块目录](../OpenGL.md) +- [SetComputeShader](SetComputeShader.md) +- [OpenGLCommandList::SetPipelineState](../OpenGLCommandList/SetPipelineState.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/OpenGLPipelineState.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/OpenGLPipelineState.md index 0aef0118..aeca286a 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/OpenGLPipelineState.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/OpenGLPipelineState.md @@ -6,71 +6,46 @@ **头文件**: `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) | 构造对象。 | -| [~OpenGLPipelineState()](Destructor.md) | 销毁对象并释放相关资源。 | -| [SetInputLayout](SetInputLayout.md) | 设置相关状态或配置。 | -| [SetRasterizerState](SetRasterizerState.md) | 设置相关状态或配置。 | -| [SetBlendState](SetBlendState.md) | 设置相关状态或配置。 | -| [SetDepthStencilState](SetDepthStencilState.md) | 设置相关状态或配置。 | -| [SetTopology](SetTopology.md) | 设置相关状态或配置。 | -| [SetRenderTargetFormats](SetRenderTargetFormats.md) | 设置相关状态或配置。 | -| [SetSampleCount](SetSampleCount.md) | 设置相关状态或配置。 | -| [SetComputeShader](SetComputeShader.md) | 设置相关状态或配置。 | -| [GetRasterizerState](GetRasterizerState.md) | 获取相关状态或对象。 | -| [GetBlendState](GetBlendState.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 原生对象，不要把它理解成可脱离上下文独立执行的 pipeline +- `Bind()` 当前不会自动调用 `ApplyViewport()` 和 `ApplyScissor()` +- 因此 viewport / scissor 更常由命令列表直接设置 + +## 设计说明 + +这种做法的好处是容易把跨后端 PSO 概念统一起来；代价是它无法像显式 API 那样把“状态已经完全固化”这件事表达得很强。 + +## 重点公共方法 + +- [Bind](Bind.md) +- [SetComputeShader](SetComputeShader.md) ## 相关文档 -- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录 -- [API 总索引](../../../../main.md) - 返回顶层索引 +- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md) +- [OpenGLShader](../OpenGLShader/OpenGLShader.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetComputeShader.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetComputeShader.md index a486525c..071f8875 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetComputeShader.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetComputeShader.md @@ -1,31 +1,24 @@ # OpenGLPipelineState::SetComputeShader -设置相关状态或配置。 - ```cpp void SetComputeShader(RHIShader* shader) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `shader` - 参数语义详见头文件声明。 +把一个 compute shader 绑定为当前 PSO 的 compute program 来源。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 缓存 `m_computeShader` +- 若 `shader != nullptr`，则把 `m_computeProgram` 设为该 `OpenGLShader` 的 program id +- 若 `shader == nullptr`，则清空 `m_computeProgram` -```cpp -#include +## 设计说明 -void Example() { - XCEngine::RHI::OpenGLPipelineState object; - // 根据上下文补齐参数后调用 OpenGLPipelineState::SetComputeShader(...)。 - (void)object; -} -``` +这里并不会重新编译或链接 shader；它只是引用已有 `OpenGLShader`。 ## 相关文档 -- [返回类总览](OpenGLPipelineState.md) -- [返回模块目录](../OpenGL.md) +- [Bind](Bind.md) +- [OpenGLShader](../OpenGLShader/OpenGLShader.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Compile.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Compile.md index a8978937..e580e192 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Compile.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Compile.md @@ -1,73 +1,35 @@ # OpenGLShader::Compile -公开方法，详见头文件声明。 - -该方法在 `XCEngine/RHI/OpenGL/OpenGLShader.h` 中提供了 4 个重载，当前页面统一汇总这些公开声明。 - -## 重载 1: 声明 - ```cpp 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); -``` - -**参数：** -- `vertexSource` - 参数语义详见头文件声明。 -- `fragmentSource` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -## 重载 3: 声明 - -```cpp bool Compile(const char* vertexSource, const char* fragmentSource, const char* geometrySource); -``` - -**参数：** -- `vertexSource` - 参数语义详见头文件声明。 -- `fragmentSource` - 参数语义详见头文件声明。 -- `geometrySource` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -## 重载 4: 声明 - -```cpp bool Compile(const char* source, ShaderType type); ``` -**参数：** -- `source` - 参数语义详见头文件声明。 -- `type` - 参数语义详见头文件声明。 +## 作用 -**返回：** `bool` - 返回值语义详见头文件声明。 +从源码字符串编译并链接 OpenGL shader/program。 -**示例：** +## 当前实现行为 -```cpp -#include +- `sourceData` 重载： + - 只接受文本源码 + - 先用 `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) -- [返回模块目录](../OpenGL.md) +- [CompileFromFile](CompileFromFile.md) +- [Use](Use.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileCompute.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileCompute.md index d466200d..0cdf098a 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileCompute.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileCompute.md @@ -1,31 +1,21 @@ # OpenGLShader::CompileCompute -公开方法，详见头文件声明。 - ```cpp bool CompileCompute(const char* computeSource); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `computeSource` - 参数语义详见头文件声明。 +编译并链接一个 compute program。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLShader object; - // 根据上下文补齐参数后调用 OpenGLShader::CompileCompute(...)。 - (void)object; -} -``` +- 创建 `GL_COMPUTE_SHADER` +- 编译后 attach 到新 program +- link +- 成功后把 `m_type` 设为 `ShaderType::Compute` ## 相关文档 -- [返回类总览](OpenGLShader.md) -- [返回模块目录](../OpenGL.md) +- [Compile](Compile.md) +- [Use](Use.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileFromFile.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileFromFile.md index 7234490e..e943681b 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileFromFile.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/CompileFromFile.md @@ -1,60 +1,33 @@ # OpenGLShader::CompileFromFile -公开方法，详见头文件声明。 - -该方法在 `XCEngine/RHI/OpenGL/OpenGLShader.h` 中提供了 3 个重载，当前页面统一汇总这些公开声明。 - -## 重载 1: 声明 - ```cpp 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); -``` - -**参数：** -- `vertexPath` - 参数语义详见头文件声明。 -- `fragmentPath` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -## 重载 3: 声明 - -```cpp bool CompileFromFile(const char* vertexPath, const char* fragmentPath, const char* geometryPath); ``` -**参数：** -- `vertexPath` - 参数语义详见头文件声明。 -- `fragmentPath` - 参数语义详见头文件声明。 -- `geometryPath` - 参数语义详见头文件声明。 +## 作用 -**返回：** `bool` - 返回值语义详见头文件声明。 +从文件读取 GLSL 源码并构建 OpenGL program。 -**示例：** +## 当前实现行为 -```cpp -#include +- `wchar_t*` 重载： + - 把路径转为窄字符串 + - 根据 `target` 或文件扩展名推断 shader type + - 读取整个文件 + - 走单阶段 `Compile(source, type)` 路径 +- 多文件 graphics 重载： + - 分别读取顶点/片元/几何着色器文件 + - 再执行多阶段编译和链接 -void Example() { - XCEngine::RHI::OpenGLShader object; - // 根据上下文补齐参数后调用 OpenGLShader::CompileFromFile(...)。 - (void)object; -} -``` +## 失败路径 + +- 文件打不开返回 `false` +- 无法推断 shader type 返回 `false` +- 任一编译或链接失败返回 `false` ## 相关文档 -- [返回类总览](OpenGLShader.md) -- [返回模块目录](../OpenGL.md) +- [Compile](Compile.md) +- [CompileCompute](CompileCompute.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/OpenGLShader.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/OpenGLShader.md index 0bc494cd..de389baa 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/OpenGLShader.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/OpenGLShader.md @@ -6,38 +6,42 @@ **头文件**: `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) | 构造对象。 | -| [~OpenGLShader()](Destructor.md) | 销毁对象并释放相关资源。 | -| [CompileFromFile](CompileFromFile.md) | 公开方法，详见头文件声明。 | -| [Compile](Compile.md) | 公开方法，详见头文件声明。 | -| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | -| [CompileCompute](CompileCompute.md) | 公开方法，详见头文件声明。 | -| [Use](Use.md) | 公开方法，详见头文件声明。 | -| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | -| [IsValid](IsValid.md) | 查询当前状态。 | -| [GetType](GetType.md) | 获取相关状态或对象。 | -| [GetUniformInfos](GetUniformInfos.md) | 获取相关状态或对象。 | -| [GetUniformInfo](GetUniformInfo.md) | 获取相关状态或对象。 | -| [GetUniformLocation](GetUniformLocation.md) | 获取相关状态或对象。 | -| [GetID](GetID.md) | 获取相关状态或对象。 | +## 设计说明 + +当前实现追求的是“足够统一、足够易用”，而不是做一套完整的 shader asset pipeline。因此类型推断里存在明显的启发式逻辑，文档里必须明确说明，不应把它误解成强约束编译系统。 + +## 当前限制 + +- `Compile(const void*, size_t, ...)` 只处理 GLSL 文本，不负责 HLSL 到 GLSL 转译 +- shader type 推断带启发式性质，失败时会直接返回 `false` +- 链接错误和编译错误当前主要输出到标准输出 + +## 重点公共方法 + +- [CompileFromFile](CompileFromFile.md) +- [Compile](Compile.md) +- [CompileCompute](CompileCompute.md) +- [Use](Use.md) ## 相关文档 -- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录 -- [API 总索引](../../../../main.md) - 返回顶层索引 +- [OpenGLDevice](../OpenGLDevice/OpenGLDevice.md) +- [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Use.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Use.md index b170fb80..07677527 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Use.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLShader/Use.md @@ -1,30 +1,18 @@ # OpenGLShader::Use -公开方法，详见头文件声明。 - ```cpp void Use() const; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +把当前 shader program 设为活动 program。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLShader object; - // 根据上下文补齐参数后调用 OpenGLShader::Use(...)。 - (void)object; -} -``` +直接调用 `glUseProgram(m_program)`。 ## 相关文档 -- [返回类总览](OpenGLShader.md) -- [返回模块目录](../OpenGL.md) +- [Compile](Compile.md) +- [OpenGLPipelineState::Bind](../OpenGLPipelineState/Bind.md) diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md index a0b8ad94..a0536775 100644 --- a/docs/api/_meta/rebuild-status.md +++ b/docs/api/_meta/rebuild-status.md @@ -1,16 +1,16 @@ # API 文档重构状态 -**生成时间**: `2026-03-27 19:11:24` +**生成时间**: `2026-03-27 22:08:19` **来源**: `docs/api/_tools/audit_api_docs.py` ## 摘要 -- Markdown 页面数（全部）: `2629` -- Markdown 页面数（canonical）: `2610` +- Markdown 页面数（全部）: `2756` +- Markdown 页面数（canonical）: `2736` - Public headers 数: `227` -- 有效头文件引用数（全部）: `197` -- 有效头文件引用数（canonical）: `197` +- 有效头文件引用数（全部）: `216` +- 有效头文件引用数（canonical）: `216` - 无效头文件引用数: `0` - 失效 `.md` 链接数: `0` - 非 `.md` 相对链接数: `0` @@ -21,8 +21,8 @@ - Canonical 根目录: `XCEngine` - 源码目录节点数: `29` -- 已生成目录总览页节点数: `26` -- 缺失目录总览页节点数: `3` +- 已生成目录总览页节点数: `27` +- 缺失目录总览页节点数: `2` - 支撑目录: `_meta, _tools` ## 模块覆盖 @@ -36,7 +36,7 @@ | `Input` | `5` | `5` | `0` | | `Memory` | `5` | `5` | `0` | | `Platform` | `11` | `11` | `0` | -| `RHI` | `87` | `68` | `19` | +| `RHI` | `87` | `87` | `0` | | `Rendering` | `13` | `10` | `3` | | `Resources` | `13` | `13` | `0` | | `Scene` | `3` | `2` | `1` | @@ -47,38 +47,18 @@ | 字段 | 页面数 | |------|--------| -| `命名空间` | `305` | -| `类型` | `305` | -| `描述` | `305` | -| `头文件` | `197` | +| `命名空间` | `325` | +| `类型` | `325` | +| `描述` | `325` | +| `头文件` | `216` | ## 缺失的平行目录总览页 -- `XCEngine/RHI/Vulkan` - `XCEngine/Scripting` - `XCEngine/Scripting/Mono` ## 未覆盖的 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/CameraRenderer.h` - `XCEngine/Rendering/RenderMaterialUtility.h`