docs: update RHI API docs

docs/api/rhi/d3d12/descriptor-heap/constructor.md

@@ -0,0 +1,18 @@
+# D3D12DescriptorHeap::D3D12DescriptorHeap
+
+```cpp
+D3D12DescriptorHeap();
+```
+
+默认构造函数。创建空的描述符堆对象，所有成员变量初始化为默认值：
+- `m_type` 初始化为 `CBV_SRV_UAV`
+- `m_numDescriptors` 初始化为 0
+- `m_descriptorSize` 初始化为 0
+- `m_shaderVisible` 初始化为 false
+
+构造的对象需要调用 `Initialize` 方法进行实际初始化。
+
+## 相关文档
+
+- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览
+- [Initialize](initialize-from-desc.md) - 初始化方法

docs/api/rhi/d3d12/descriptor-heap/descriptor-heap.md

@@ -2,26 +2,61 @@
 
 **命名空间**: `XCEngine::RHI`
 
-**描述**: DirectX 12 描述符堆的 D3D12 实现，继承自 `RHIDescriptorPool`。
+**继承自**: [`RHIDescriptorPool`](../../descriptor-pool/descriptor-pool.md)
+
+**描述**: DirectX 12 描述符堆的 D3D12 实现，继承自 `RHIDescriptorPool`。描述符堆是 D3D12 中用于存储描述符（CBV/SRV/UAV/Sampler）的内存块，支持 CPU 可访问和 GPU 可访问两种模式。
+
+**概述**:
+
+`D3D12DescriptorHeap` 封装了 D3D12 的描述符堆资源，提供描述符的分配、句柄计算和资源管理功能。描述符堆类型包括：
+- `CBV_SRV_UAV` - 常量缓冲区、Shader资源和无序访问视图
+- `SAMPLER` - 采样器
+
+描述符堆可以标记为 `shaderVisible`，使其可被 GPU shader 访问。仅当需要绑定到命令列表时才应使用 shader visible 堆。
 
 ## 公共方法
 
 | 方法 | 描述 |
 |------|------|
+| [`D3D12DescriptorHeap`](constructor.md) | 构造函数 |
 | [`Initialize`](initialize-from-desc.md) | 从描述符初始化 |
-| [`Shutdown`](../../../threading/task-system/shutdown.md) | 关闭描述符堆 |
+| [`Initialize(ID3D12Device*,...)`](initialize-device.md) | 直接初始化 |
+| [`Shutdown`](shutdown.md) | 关闭描述符堆 |
 | [`GetDescriptorHeap`](get-descriptor-heap.md) | 获取 D3D12 描述符堆 |
 | [`GetCPUDescriptorHandle`](get-cpu-descriptor-handle.md) | 获取 CPU 描述符句柄 |
 | [`GetGPUDescriptorHandle`](get-gpu-descriptor-handle.md) | 获取 GPU 描述符句柄 |
 | [`GetDescriptorCount`](get-descriptor-count.md) | 获取描述符数量 |
-| [`GetType`](../../command-queue/get-type.md) | 获取描述符类型 |
+| [`GetType`](get-type.md) | 获取描述符类型 |
 | [`GetDescriptorSize`](get-descriptor-size.md) | 获取描述符大小 |
 | [`GetCPUDescriptorHandleForHeapStart`](get-cpu-descriptor-handle-for-heap-start.md) | 获取堆起始 CPU 句柄 |
 | [`GetGPUDescriptorHandleForHeapStart`](get-gpu-descriptor-handle-for-heap-start.md) | 获取堆起始 GPU 句柄 |
-| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 |
+| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 |
 | [`CreateDesc`](create-desc.md) | 创建描述符（静态） |
 
+## 使用示例
+
+```cpp
+#include "XCEngine/RHI/D3D12/D3D12DescriptorHeap.h"
+
+using namespace XCEngine::RHI;
+
+// 创建设备
+ID3D12Device* device = ...;
+
+// 创建 CBV/SRV/UAV 描述符堆
+D3D12DescriptorHeap heap;
+heap.Initialize(device, DescriptorHeapType::CBV_SRV_UAV, 256, true);
+
+// 获取描述符句柄
+CPUDescriptorHandle cpuHandle = heap.GetCPUDescriptorHandle(0);
+GPUDescriptorHandle gpuHandle = heap.GetGPUDescriptorHandle(0);
+
+// 关闭
+heap.Shutdown();
+```
+
 ## 相关文档
 
-- [D3D12 后端总览](../../opengl/overview.md)
+- [D3D12 后端总览](../d3d12.md)
 - [RHIDescriptorPool](../../descriptor-pool/descriptor-pool.md) - 抽象描述符池接口
+- [D3D12Enum](d3d12-enum.md) - D3D12 类型枚举映射

docs/api/rhi/d3d12/descriptor-heap/get-cpu-descriptor-handle-for-heap-start.md

@@ -4,12 +4,14 @@
 D3D12_CPU_DESCRIPTOR_HANDLE GetCPUDescriptorHandleForHeapStart() const;
 ```
 
-获取堆起始处的 CPU 描述符句柄。
+获取描述符堆起始位置的 CPU 描述符句柄。此句柄指向堆中第一个描述符，可作为遍历和偏移计算的基准。
 
-**返回：** CPU 描述符句柄
+**返回：** `D3D12_CPU_DESCRIPTOR_HANDLE` 结构体，包含堆起始 CPU 指针
 
 **复杂度：** O(1)
 
 ## 相关文档
 
 - [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览
+- [GetCPUDescriptorHandle](get-cpu-descriptor-handle.md) - 获取指定索引的 CPU 句柄
+- [GetGPUDescriptorHandleForHeapStart](get-gpu-descriptor-handle-for-heap-start.md) - GPU 版本

docs/api/rhi/d3d12/descriptor-heap/get-gpu-descriptor-handle-for-heap-start.md

@@ -4,12 +4,14 @@
 D3D12_GPU_DESCRIPTOR_HANDLE GetGPUDescriptorHandleForHeapStart() const;
 ```
 
-获取堆起始处的 GPU 描述符句柄。
+获取描述符堆起始位置的 GPU 描述符句柄。此句柄指向堆中第一个描述符，可作为遍历和偏移计算的基准。仅当堆创建时 `shaderVisible` 为 `true` 时返回的句柄才有效。
 
-**返回：** GPU 描述符句柄
+**返回：** `D3D12_GPU_DESCRIPTOR_HANDLE` 结构体，包含堆起始 GPU 指针
 
 **复杂度：** O(1)
 
 ## 相关文档
 
 - [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览
+- [GetGPUDescriptorHandle](get-gpu-descriptor-handle.md) - 获取指定索引的 GPU 句柄
+- [GetCPUDescriptorHandleForHeapStart](get-cpu-descriptor-handle-for-heap-start.md) - CPU 版本

docs/api/rhi/d3d12/descriptor-heap/get-native-handle.md

@@ -0,0 +1,17 @@
+# D3D12DescriptorHeap::GetNativeHandle
+
+```cpp
+void* GetNativeHandle() override;
+```
+
+获取底层 D3D12 描述符堆原生句柄。返回 `ID3D12DescriptorHeap*` 的 `void*` 形式，用于泛型接口获取原生资源。
+
+**返回：** `void*` 指向 `ID3D12DescriptorHeap` 的指针
+
+**复杂度：** O(1)
+
+## 相关文档
+
+- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览
+- [RHIDescriptorPool::GetNativeHandle](../../descriptor-pool/get-native-handle.md) - 基类方法
+- [GetDescriptorHeap](get-descriptor-heap.md) - 类型安全的获取方法

docs/api/rhi/d3d12/descriptor-heap/get-type.md

@@ -0,0 +1,16 @@
+# D3D12DescriptorHeap::GetType
+
+```cpp
+DescriptorHeapType GetType() const override;
+```
+
+获取描述符堆类型。
+
+**返回：** 描述符堆类型枚举值
+
+**复杂度：** O(1)
+
+## 相关文档
+
+- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览
+- [RHIDescriptorPool::GetType](../../descriptor-pool/get-type.md) - 基类方法

docs/api/rhi/d3d12/descriptor-heap/initialize-device.md

@@ -0,0 +1,40 @@
+# D3D12DescriptorHeap::Initialize
+
+```cpp
+bool Initialize(ID3D12Device* device, DescriptorHeapType type, uint32_t numDescriptors, bool shaderVisible = false);
+```
+
+直接使用 D3D12 设备创描述符堆。这是主要初始化方法，会创建底层的 `ID3D12DescriptorHeap` COM 对象。
+
+**参数：**
+- `device` - D3D12 设备指针，不得为 `nullptr`
+- `type` - 描述符堆类型，决定堆中存储的描述符种类
+- `numDescriptors` - 描述符数量，必须大于 0
+- `shaderVisible` - 是否创建为 shader visible 模式。shader visible 的堆可绑定到命令列表供 shader 访问，但会增加 GPU 访问开销
+
+**返回：** 是否初始化成功。失败时返回 `false`，可能原因包括：
+- 设备指针无效
+- 描述符数量为 0
+- D3D12 API 创建堆失败
+
+**复杂度：** O(1)
+
+## 示例
+
+```cpp
+ID3D12Device* device = ...;
+
+// 创建不可见的 CPU 描述符堆
+D3D12DescriptorHeap cpuHeap;
+cpuHeap.Initialize(device, DescriptorHeapType::CBV_SRV_UAV, 64, false);
+
+// 创建 GPU 可见的描述符堆
+D3D12DescriptorHeap gpuHeap;
+gpuHeap.Initialize(device, DescriptorHeapType::CBV_SRV_UAV, 256, true);
+```
+
+## 相关文档
+
+- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览
+- [Initialize(const DescriptorPoolDesc&)](initialize-from-desc.md) - 描述符重载
+- [CreateDesc](create-desc.md) - 创建描述符结构体

docs/api/rhi/d3d12/descriptor-heap/initialize-from-desc.md

@@ -4,15 +4,31 @@
 bool Initialize(const DescriptorPoolDesc& desc) override;
 ```
 
-从描述符初始化。
+从描述符池描述结构体初始化描述符堆。该方法是 `RHIDescriptorPool` 基类接口的实现，内部调用 `Initialize(ID3D12Device*, ...)` 重载。
 
 **参数：**
-- `desc` - 描述符池描述
+- `desc` - 描述符池描述，包含设备指针、堆类型、描述符数量和 shader visible 标志
 
-**返回：** 是否初始化成功
+**返回：** 是否初始化成功。失败时返回 `false`，可能由于 D3D12 API 调用失败导致。
 
-**复杂度：** O(n)
+**复杂度：** O(1)
+
+## 示例
+
+```cpp
+DescriptorPoolDesc desc = {};
+desc.device = device;
+desc.type = DescriptorHeapType::CBV_SRV_UAV;
+desc.descriptorCount = 256;
+desc.shaderVisible = true;
+
+D3D12DescriptorHeap heap;
+if (!heap.Initialize(desc)) {
+    // 处理初始化失败
+}
+```
 
 ## 相关文档
 
 - [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览
+- [Initialize(ID3D12Device*,...)](initialize-device.md) - 直接初始化重载

docs/api/rhi/d3d12/descriptor-heap/shutdown.md

@@ -0,0 +1,14 @@
+# D3D12DescriptorHeap::Shutdown
+
+```cpp
+void Shutdown() override;
+```
+
+关闭描述符堆，释放底层 D3D12 描述符堆资源。
+
+**复杂度：** O(1)
+
+## 相关文档
+
+- [D3D12DescriptorHeap 总览](descriptor-heap.md) - 返回类总览
+- [RHIDescriptorPool::Shutdown](../../descriptor-pool/shutdown.md) - 基类方法