docs: update RHI API docs

docs/api/rhi/buffer/buffer.md

@@ -4,6 +4,8 @@
 
 **类型**: `class` (abstract)
 
+**头文件**: `XCEngine/RHI/RHIBuffer.h`
+
 **描述**: GPU 缓冲区资源抽象接口，用于管理顶点缓冲、索引缓冲、常量缓冲等 GPU 内存资源。
 
 ## 概述

docs/api/rhi/buffer/get-buffer-type.md

@@ -4,12 +4,25 @@
 virtual BufferType GetBufferType() const = 0;
 ```
 
-获取缓冲区类型。
+获取缓冲区的类型，用于区分顶点缓冲、索引缓冲、常量缓冲等。
 
-**返回：** 缓冲区类型枚举值
+**返回：** `BufferType` 枚举值
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+BufferType type = buffer->GetBufferType();
+if (type == BufferType::Vertex) {
+    printf("This is a vertex buffer\n");
+} else if (type == BufferType::Index) {
+    printf("This is an index buffer\n");
+}
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/get-name.md

@@ -4,12 +4,21 @@
 virtual const std::string& GetName() const = 0;
 ```
 
-获取缓冲区名称（用于调试）。
+获取缓冲区名称（用于调试和诊断）。名称通常在图形调试器（如 RenderDoc、PIX）中显示。
 
-**返回：** 缓冲区名称
+**返回：** 缓冲区名称字符串
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+const std::string& name = buffer->GetName();
+printf("Buffer name: %s\n", name.c_str());
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/get-native-handle.md

@@ -4,14 +4,26 @@
 virtual void* GetNativeHandle() = 0;
 ```
 
-获取原生 API 句柄。
+获取底层图形 API 的原生资源句柄，用于平台特定操作或调试。
 
-**返回：** 
+**返回：**
 - D3D12: `ID3D12Resource*`
-- OpenGL: `GLuint` 指针
+- Vulkan: `VkBuffer`
+- OpenGL: `GLuint`
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+void* handle = buffer->GetNativeHandle();
+#ifdef _WIN32
+    ID3D12Resource* d3d12Resource = static_cast<ID3D12Resource*>(handle);
+#endif
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/get-size.md

@@ -4,12 +4,21 @@
 virtual uint64_t GetSize() const = 0;
 ```
 
-获取缓冲区大小（字节）。
+获取缓冲区总大小（字节）。
 
-**返回：** 缓冲区大小
+**返回：** 缓冲区大小（字节）
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+uint64_t size = buffer->GetSize();
+printf("Buffer size: %llu bytes\n", (unsigned long long)size);
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/get-state.md

@@ -4,12 +4,23 @@
 virtual ResourceStates GetState() const = 0;
 ```
 
-获取当前资源状态。
+获取缓冲区当前所处的资源状态。资源状态决定缓冲区可以用于哪些 GPU 操作。
 
-**返回：** 资源状态枚举值
+**返回：** `ResourceStates` 枚举值
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+ResourceStates state = buffer->GetState();
+if (state == ResourceStates::VertexAndConstantBuffer) {
+    printf("Buffer is ready for vertex binding\n");
+}
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/get-stride.md

@@ -4,12 +4,21 @@
 virtual uint32_t GetStride() const = 0;
 ```
 
-获取单个元素的字节大小。
+获取单个元素的字节大小（步长）。对于顶点缓冲是单个顶点的字节大小，对于索引缓冲是单个索引的字节大小。
 
 **返回：** 元素步长（字节）
 
+**线程安全：** ✅
+
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+uint32_t stride = buffer->GetStride();
+printf("Element stride: %u bytes\n", stride);
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/map.md

@@ -4,9 +4,11 @@
 virtual void* Map() = 0;
 ```
 
-映射缓冲区内存到 CPU 可访问空间。
+将缓冲区 GPU 内存映射到 CPU 可访问的虚拟地址空间。映射后可直接使用 memcpy 等 CPU 内存操作函数写入数据。
 
-**返回：** 指向缓冲区数据的指针
+**返回：** 指向缓冲区数据的指针，映射失败返回 `nullptr`
+
+**线程安全：** ❌
 
 **复杂度：** O(1)
 

docs/api/rhi/buffer/set-buffer-type.md

@@ -4,13 +4,21 @@
 virtual void SetBufferType(BufferType type) = 0;
 ```
 
-设置缓冲区类型。
+设置缓冲区的类型。应在缓冲区创建后立即设置，确保后续绑定到渲染管线时使用正确的类型。
 
 **参数：**
-- `type` - 新的缓冲区类型
+- `type` - 缓冲区类型（`Vertex`、`Index`、`Constant` 等）
+
+**线程安全：** ❌
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+buffer->SetBufferType(BufferType::Vertex);
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/set-stride.md

@@ -4,13 +4,21 @@
 virtual void SetStride(uint32_t stride) = 0;
 ```
 
-设置元素字节大小。
+设置单个元素的字节大小（步长）。
 
 **参数：**
-- `stride` - 新的步长值
+- `stride` - 新的步长值（字节）
+
+**线程安全：** ❌
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+buffer->SetStride(sizeof(Vertex));
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/shutdown.md

@@ -4,10 +4,20 @@
 virtual void Shutdown() = 0;
 ```
 
-释放缓冲区资源。
+关闭并释放缓冲区资源。调用后缓冲区不再可用，所有已绑定的命令列表中的引用将失效。
+
+**线程安全：** ❌
 
 **复杂度：** O(1)
 
+**示例：**
+
+```cpp
+buffer->Shutdown();
+// buffer is now invalid
+delete buffer;
+```
+
 ## 相关文档
 
 - [RHIBuffer 总览](buffer.md) - 返回类总览

docs/api/rhi/buffer/unmap.md

@@ -4,15 +4,17 @@
 virtual void Unmap() = 0;
 ```
 
-取消内存映射。
+取消缓冲区内存映射，使 GPU 可以继续访问该内存。在调用 `Map()` 后必须调用此方法。
+
+**线程安全：** ❌
 
 **复杂度：** O(1)
 
 **示例：**
 
 ```cpp
-buffer->Map();
-memcpy(mappedData, sourceData, size);
+void* data = buffer->Map();
+memcpy(data, sourceData, size);
 buffer->Unmap();
 ```