From cba3823ea23b2e58019af6a685c7680914bbfdbe Mon Sep 17 00:00:00 2001
From: ssdfasd <2156608475@qq.com>
Date: Fri, 10 Apr 2026 17:51:45 +0800
Subject: [PATCH] docs(rhi): document buffer init overload and sample quality

---
 .../D3D12PipelineState/D3D12PipelineState.md  |  1 +
 .../D3D12PipelineState/SetSampleCount.md      |  3 +-
 .../D3D12PipelineState/SetSampleQuality.md    | 28 +++++++++++++++++
 .../OpenGLPipelineState.md                    |  2 +-
 .../OpenGLPipelineState/SetSampleCount.md     |  3 +-
 .../OpenGLPipelineState/SetSampleQuality.md   | 20 +++++++++++++
 .../XCEngine/RHI/RHIDevice/CreateBuffer.md    | 24 +++++++++++++--
 docs/api/XCEngine/RHI/RHIDevice/RHIDevice.md  | 19 ++++++++++++
 .../RHI/RHIPipelineState/RHIPipelineState.md  |  2 ++
 .../RHI/RHIPipelineState/SetSampleCount.md    |  5 ++--
 .../RHI/RHIPipelineState/SetSampleQuality.md  | 30 +++++++++++++++++++
 .../VulkanPipelineState/SetSampleCount.md     |  3 +-
 .../VulkanPipelineState/SetSampleQuality.md   | 19 ++++++++++++
 .../VulkanPipelineState.md                    |  2 ++
 14 files changed, 153 insertions(+), 8 deletions(-)
 create mode 100644 docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetSampleQuality.md
 create mode 100644 docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetSampleQuality.md
 create mode 100644 docs/api/XCEngine/RHI/RHIPipelineState/SetSampleQuality.md
 create mode 100644 docs/api/XCEngine/RHI/Vulkan/VulkanPipelineState/SetSampleQuality.md

diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/D3D12PipelineState.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/D3D12PipelineState.md
index b75be98d..763f9844 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/D3D12PipelineState.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/D3D12PipelineState.md
@@ -37,6 +37,7 @@
 | [SetTopology](SetTopology.md) | 写入 `m_topologyType`。 |
 | [SetRenderTargetFormats](SetRenderTargetFormats.md) | 执行该公开方法对应的当前实现。 |
 | [SetSampleCount](SetSampleCount.md) | 写入 `m_sampleCount`。 |
+| [SetSampleQuality](SetSampleQuality.md) | 写入 `m_sampleQuality`，并影响最终 `D3D12_SAMPLE_DESC` 与 hash。 |
 | [SetComputeShader](SetComputeShader.md) | 执行 `Reset`、`IsValid` 协同流程。 |
 | [SetRootSignature](SetRootSignature.md) | 写入 `m_rootSignature`。 |
 | [GetRasterizerState](GetRasterizerState.md) | 返回 `m_rasterizerDesc` 当前值。 |
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetSampleCount.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetSampleCount.md
index af48c9ff..59ff6049 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetSampleCount.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetSampleCount.md
@@ -14,11 +14,12 @@ void SetSampleCount(uint32_t count) override;
 
 ## 作用
 
-更新 `m_sampleCount`。
+更新 `m_sampleCount`；`quality` 维度现在由 [SetSampleQuality](SetSampleQuality.md) 单独负责。
 
 ## 当前实现
 
 - 会更新 `m_sampleCount`。
+- `D3D12_SAMPLE_DESC.Quality` 不在这里设置，而是在 `SetSampleQuality(...)` 中写入 `m_sampleQuality`。
 
 ## 相关文档
 
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetSampleQuality.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetSampleQuality.md
new file mode 100644
index 00000000..7369078c
--- /dev/null
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetSampleQuality.md
@@ -0,0 +1,28 @@
+# D3D12PipelineState::SetSampleQuality
+
+**命名空间**: `XCEngine::RHI`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h`
+
+## 签名
+
+```cpp
+void SetSampleQuality(uint32_t quality) override;
+```
+
+## 作用
+
+更新 D3D12 后端缓存的 sample quality 值。
+
+## 当前实现
+
+- 会把参数写入 `m_sampleQuality`。
+- 该值会进入 `GetHash()` 的 `renderTargetHash`。
+- 在 graphics PSO 创建路径里，最终会写入 `D3D12_GRAPHICS_PIPELINE_STATE_DESC::SampleDesc.Quality`。
+
+## 相关文档
+
+- [D3D12PipelineState](D3D12PipelineState.md)
+- [SetSampleCount](SetSampleCount.md)
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/OpenGLPipelineState.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/OpenGLPipelineState.md
index 2f30252e..7e3cb53f 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/OpenGLPipelineState.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/OpenGLPipelineState.md
@@ -26,7 +26,7 @@
 - [Bind](Bind.md) 会优先绑定 compute program，否则绑定 graphics program
 - `Bind()` 之后只会调用 [Apply](Apply.md)，即深度/模板、混合、光栅化三类状态
 - [ApplyViewport](ApplyViewport.md) 与 [ApplyScissor](ApplyScissor.md) 需要单独调用
-- [SetRenderTargetFormats](SetRenderTargetFormats.md)、[SetSampleCount](SetSampleCount.md)、[GetHash](GetHash.md) 目前基本是占位实现
+- [SetRenderTargetFormats](SetRenderTargetFormats.md)、[SetSampleCount](SetSampleCount.md)、[SetSampleQuality](SetSampleQuality.md)、[GetHash](GetHash.md) 目前基本是占位实现
 - [IsValid](IsValid.md) 永远返回 `true`
 - [EnsureValid](EnsureValid.md) 为空实现
 - [GetNativeHandle](GetNativeHandle.md) 只返回 graphics `m_program`
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetSampleCount.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetSampleCount.md
index 514ecbc3..7d54cf49 100644
--- a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetSampleCount.md
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetSampleCount.md
@@ -6,12 +6,13 @@ void SetSampleCount(uint32_t count) override;
 
 ## 作用
 
-为统一 RHI 接口预留采样数设置入口。
+为统一 RHI 接口预留 sample count 设置入口；`quality` 维度在 [SetSampleQuality](SetSampleQuality.md) 中单独暴露。
 
 ## 当前实现行为
 
 - 空实现
 - `count` 当前不会被缓存，也不会驱动 `GL_MULTISAMPLE` 之外的任何行为
+- OpenGL 后端当前也不会在这里处理 sample quality
 
 ## 相关文档
 
diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetSampleQuality.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetSampleQuality.md
new file mode 100644
index 00000000..68ee1993
--- /dev/null
+++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/SetSampleQuality.md
@@ -0,0 +1,20 @@
+# OpenGLPipelineState::SetSampleQuality()
+
+```cpp
+void SetSampleQuality(uint32_t quality) override;
+```
+
+## 作用
+
+为跨后端 `RHIPipelineState` 接口保留 sample quality 入口。
+
+## 当前实现行为
+
+- 空实现。
+- `quality` 当前不会被缓存，也不会映射到额外的 OpenGL 状态。
+- 现阶段 OpenGL 后端的多采样行为仍主要落在 rasterizer 状态里的 `multisampleEnable`。
+
+## 相关文档
+
+- [OpenGLPipelineState](OpenGLPipelineState.md)
+- [SetSampleCount](SetSampleCount.md)
diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateBuffer.md b/docs/api/XCEngine/RHI/RHIDevice/CreateBuffer.md
index 38e8b82e..c254b323 100644
--- a/docs/api/XCEngine/RHI/RHIDevice/CreateBuffer.md
+++ b/docs/api/XCEngine/RHI/RHIDevice/CreateBuffer.md
@@ -10,15 +10,35 @@
 
 ```cpp
 virtual RHIBuffer* CreateBuffer(const BufferDesc& desc) = 0;
+
+virtual RHIBuffer* CreateBuffer(
+    const BufferDesc& desc,
+    const void* initialData,
+    size_t initialDataSize,
+    ResourceStates finalState = ResourceStates::GenericRead);
 ```
 
 ## 作用
 
-纯虚接口。
+创建 `RHIBuffer`。当前既有后端必须实现的基础重载，也有基类直接提供的“创建并写入初始数据”便捷重载。
 
 ## 当前实现
 
-- 该声明是纯虚接口，基类不提供实现。
+- `CreateBuffer(const BufferDesc& desc)`
+  - 仍然是纯虚接口，具体后端必须提供基础 buffer 创建逻辑。
+- `CreateBuffer(desc, initialData, initialDataSize, finalState)`
+  - 当 `initialData == nullptr` 或 `initialDataSize == 0` 时，会回退到基础重载。
+  - 当 `initialDataSize > desc.size` 时，返回 `nullptr`。
+  - 成功创建后会先调用 `buffer->SetData(...)` 写入初始数据。
+  - 若 `initialDataSize < desc.size`，会把剩余空间补零。
+  - 最后会调用 `buffer->SetState(finalState)`。
+
+当前 `VulkanDevice` / `OpenGLDevice` 只实现了基础重载，因此会走基类默认实现；`D3D12Device` 另外提供了后端自定义重载。
+
+## 真实调用点
+
+- `engine/src/Rendering/Caches/RenderResourceCache.cpp`
+  - 当前体积 payload 上传路径会用这个重载创建 storage buffer，并把最终状态设置为 `GenericRead`。
 
 ## 相关文档
 
diff --git a/docs/api/XCEngine/RHI/RHIDevice/RHIDevice.md b/docs/api/XCEngine/RHI/RHIDevice/RHIDevice.md
index c0f96df3..e92496a9 100644
--- a/docs/api/XCEngine/RHI/RHIDevice/RHIDevice.md
+++ b/docs/api/XCEngine/RHI/RHIDevice/RHIDevice.md
@@ -56,6 +56,7 @@
 - [CreateSwapChain](CreateSwapChain.md)
 
 `CreateTexture()` 还有一个带 `initialData` 和 `rowPitch` 的重载，允许直接创建并上传初始数据。
+`CreateBuffer()` 现在也有一个由基类提供默认实现的带初始数据重载，可在创建后立即写入 payload、补零剩余区间并设置最终资源状态。
 
 ### 执行与同步
 
@@ -88,6 +89,24 @@
 
 从接口形状就能看出，当前 `RHIDevice` 同时承担了资源创建器、视图工厂、descriptor 工厂和 pipeline 工厂的职责。
 
+### Buffer 初始化重载
+
+`RHIDevice.h` 当前新增了：
+
+```cpp
+virtual RHIBuffer* CreateBuffer(
+    const BufferDesc& desc,
+    const void* initialData,
+    size_t initialDataSize,
+    ResourceStates finalState = ResourceStates::GenericRead);
+```
+
+它不是新的纯虚接口，而是基类直接给出的默认实现。对调用方来说，这意味着：
+
+1. 非 D3D12 后端即使只实现了基础 `CreateBuffer(const BufferDesc&)`，也天然获得了“创建后写入初始数据”的统一入口。
+2. 这个重载会在必要时自动把剩余空间补零，并把 buffer 状态切到 `finalState`。
+3. 当前 `RenderResourceCache` 的体积 payload 上传已经在使用这一路径。
+
 ## 所有权约定
 
 这是这页最关键的现实语义。
diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/RHIPipelineState.md b/docs/api/XCEngine/RHI/RHIPipelineState/RHIPipelineState.md
index bf334525..b9f972f4 100644
--- a/docs/api/XCEngine/RHI/RHIPipelineState/RHIPipelineState.md
+++ b/docs/api/XCEngine/RHI/RHIPipelineState/RHIPipelineState.md
@@ -32,6 +32,7 @@
 - [SetTopology](SetTopology.md)
 - [SetRenderTargetFormats](SetRenderTargetFormats.md)
 - [SetSampleCount](SetSampleCount.md)
+- [SetSampleQuality](SetSampleQuality.md)
 
 ### 计算路径
 
@@ -110,6 +111,7 @@
 - [SetTopology](SetTopology.md)
 - [SetRenderTargetFormats](SetRenderTargetFormats.md)
 - [SetSampleCount](SetSampleCount.md)
+- [SetSampleQuality](SetSampleQuality.md)
 - [SetComputeShader](SetComputeShader.md)
 - [GetRasterizerState](GetRasterizerState.md)
 - [GetBlendState](GetBlendState.md)
diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/SetSampleCount.md b/docs/api/XCEngine/RHI/RHIPipelineState/SetSampleCount.md
index 96efd0d4..bc39098e 100644
--- a/docs/api/XCEngine/RHI/RHIPipelineState/SetSampleCount.md
+++ b/docs/api/XCEngine/RHI/RHIPipelineState/SetSampleCount.md
@@ -14,11 +14,12 @@ virtual void SetSampleCount(uint32_t count) = 0;
 
 ## 作用
 
-纯虚接口。
+设置多采样的 sample count 维度；当前接口已经把 sample quality 拆到独立的 [SetSampleQuality](SetSampleQuality.md)。
 
 ## 当前实现
 
-- 该声明是纯虚接口，基类不提供实现。
+- 该声明仍是纯虚接口，基类不提供实现。
+- 当前不要把它理解成“多采样配置的唯一入口”，因为 `quality` 已经是单独方法。
 
 ## 相关文档
 
diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/SetSampleQuality.md b/docs/api/XCEngine/RHI/RHIPipelineState/SetSampleQuality.md
new file mode 100644
index 00000000..ff65932f
--- /dev/null
+++ b/docs/api/XCEngine/RHI/RHIPipelineState/SetSampleQuality.md
@@ -0,0 +1,30 @@
+# RHIPipelineState::SetSampleQuality
+
+**命名空间**: `XCEngine::RHI`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/RHI/RHIPipelineState.h`
+
+## 签名
+
+```cpp
+virtual void SetSampleQuality(uint32_t quality) = 0;
+```
+
+## 作用
+
+设置多采样的 quality 维度；与 [SetSampleCount](SetSampleCount.md) 共同表达完整的 multisample 配置。
+
+## 当前实现
+
+- 该声明是纯虚接口，基类不提供实现。
+- 各后端当前语义并不完全一致：
+  - D3D12 会把它写入 `D3D12_SAMPLE_DESC.Quality` 并纳入 pipeline hash。
+  - Vulkan 当前显式忽略这个参数。
+  - OpenGL 当前也是空实现。
+
+## 相关文档
+
+- [RHIPipelineState](RHIPipelineState.md)
+- [SetSampleCount](SetSampleCount.md)
diff --git a/docs/api/XCEngine/RHI/Vulkan/VulkanPipelineState/SetSampleCount.md b/docs/api/XCEngine/RHI/Vulkan/VulkanPipelineState/SetSampleCount.md
index 6d501ee4..6a969fd7 100644
--- a/docs/api/XCEngine/RHI/Vulkan/VulkanPipelineState/SetSampleCount.md
+++ b/docs/api/XCEngine/RHI/Vulkan/VulkanPipelineState/SetSampleCount.md
@@ -6,12 +6,13 @@ void SetSampleCount(uint32_t count) override;
 
 ## 作用
 
-更新缓存的采样数。
+更新缓存的 sample count；`quality` 维度由 [SetSampleQuality](SetSampleQuality.md) 单独暴露。
 
 ## 当前实现行为
 
 - `count > 0` 时保存原值
 - 否则回退为 `1`
+- Vulkan 后端当前不会在这里处理 sample quality
 
 ## 相关文档
 
diff --git a/docs/api/XCEngine/RHI/Vulkan/VulkanPipelineState/SetSampleQuality.md b/docs/api/XCEngine/RHI/Vulkan/VulkanPipelineState/SetSampleQuality.md
new file mode 100644
index 00000000..6ec664a2
--- /dev/null
+++ b/docs/api/XCEngine/RHI/Vulkan/VulkanPipelineState/SetSampleQuality.md
@@ -0,0 +1,19 @@
+# VulkanPipelineState::SetSampleQuality
+
+```cpp
+void SetSampleQuality(uint32_t quality) override;
+```
+
+## 作用
+
+保留与抽象层一致的 sample quality 入口。
+
+## 当前实现行为
+
+- 当前实现显式 `(void)quality`，也就是直接忽略这个参数。
+- Vulkan 后端当前只把 [SetSampleCount](SetSampleCount.md) 写入 `VkSampleCountFlagBits` 路径，没有额外的 sample quality 映射。
+
+## 相关文档
+
+- [VulkanPipelineState](VulkanPipelineState.md)
+- [SetSampleCount](SetSampleCount.md)
diff --git a/docs/api/XCEngine/RHI/Vulkan/VulkanPipelineState/VulkanPipelineState.md b/docs/api/XCEngine/RHI/Vulkan/VulkanPipelineState/VulkanPipelineState.md
index 5c32f360..29621645 100644
--- a/docs/api/XCEngine/RHI/Vulkan/VulkanPipelineState/VulkanPipelineState.md
+++ b/docs/api/XCEngine/RHI/Vulkan/VulkanPipelineState/VulkanPipelineState.md
@@ -96,6 +96,7 @@
 
 - `Bind()` / `Unbind()` 当前都是 no-op
 - `GetHash()` 目前只用了拓扑和第一个 render target format 做轻量 hash
+- `SetSampleQuality()` 当前显式忽略 `quality` 参数，只保留接口对齐
 - `HasDepthStencilAttachment()` 只按 `m_depthStencilFormat` 是否为 `Unknown` 判断
 
 ## 线程语义
@@ -140,6 +141,7 @@
 - `void SetTopology(uint32_t topologyType)`
 - `void SetRenderTargetFormats(uint32_t count, const uint32_t* formats, uint32_t depthFormat)`
 - `void SetSampleCount(uint32_t count)`
+- `void SetSampleQuality(uint32_t quality)`
 - `void SetComputeShader(RHIShader* shader)`
 - `PipelineStateHash GetHash() const`
 - `RHIShader* GetComputeShader() const`