From 82cf1478173961259c27f571ff259eb42e6ddb79 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Thu, 19 Mar 2026 00:43:16 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=20API=20=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=87=86=E7=A1=AE=E6=80=A7=20(=E7=AC=AC=E5=9B=9B?= =?UTF-8?q?=E8=BD=AE=E6=A3=80=E6=9F=A5)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 修复问题: - containers: HashMap 实现描述修正 - debug: XE_LOG 宏参数顺序修正 - memory: ProxyAllocator 统计示例修正, PoolAllocator allocate size 检查描述 - resources: ResourceManager 缺失 UnloadGroup 方法 - rhi: D3D12 格式枚举名称修正, Texture Format 枚举补全, ResourceStates 补充 - threading: TaskGroup GetProgress/Wait/Cancel 实现限制说明 --- docs/api/containers/hashmap/hashmap.md | 2 +- docs/api/debug/debug.md | 4 ++-- docs/api/memory/pool-allocator/allocate.md | 4 ++-- docs/api/memory/proxy-allocator/free.md | 7 +++---- docs/api/memory/proxy-allocator/get-stats.md | 4 ++-- docs/api/rhi/buffer/buffer.md | 3 +++ .../rhi/d3d12/render-target-view/create-desc.md | 2 +- .../rhi/d3d12/shader-resource-view/create-desc.md | 2 +- docs/api/rhi/d3d12/types/to-d3d12-texture-desc.md | 2 +- docs/api/rhi/texture/texture.md | 15 +++++++++++++++ docs/api/threading/task-group/cancel.md | 3 ++- docs/api/threading/task-group/getprogress.md | 9 ++++----- docs/api/threading/task-group/wait.md | 5 ++++- 13 files changed, 41 insertions(+), 21 deletions(-) diff --git a/docs/api/containers/hashmap/hashmap.md b/docs/api/containers/hashmap/hashmap.md index d67f04e5..36a44ef0 100644 --- a/docs/api/containers/hashmap/hashmap.md +++ b/docs/api/containers/hashmap/hashmap.md @@ -8,7 +8,7 @@ ## 概述 -`HashMap` 是一个模板哈希表容器，实现了分离链接法的哈希表，支持键值对的插入、查找和删除操作。 +`HashMap` 是一个模板哈希表容器，使用动态数组作为桶来解决哈希冲突，支持键值对的插入、查找和删除操作。 ## 公共类型 diff --git a/docs/api/debug/debug.md b/docs/api/debug/debug.md index a5823a54..deaefe0a 100644 --- a/docs/api/debug/debug.md +++ b/docs/api/debug/debug.md @@ -70,11 +70,11 @@ Logger::Get().AddSink(std::make_unique("app.log")); Logger::Get().SetMinimumLevel(LogLevel::Debug); // 记录日志 -XE_LOG(LogCategory::Rendering, LogLevel::Info, "Render started"); +XE_LOG(LogLevel::Info, LogCategory::Rendering, "Render started"); // 使用宏记录日志 if (condition) { - XE_LOG(LogCategory::General, LogLevel::Error, "Something went wrong"); + XE_LOG(LogLevel::Error, LogCategory::General, "Something went wrong"); } ``` diff --git a/docs/api/memory/pool-allocator/allocate.md b/docs/api/memory/pool-allocator/allocate.md index dace6367..35f17f8f 100644 --- a/docs/api/memory/pool-allocator/allocate.md +++ b/docs/api/memory/pool-allocator/allocate.md @@ -4,10 +4,10 @@ void* Allocate(size_t size, size_t alignment = 0) override; ``` -从内存池中分配一个空闲块。此方法忽略 `size` 参数，始终分配一个固定大小的块。如果池中没有空闲块，返回 `nullptr`。分配操作从空闲链表头部取出一个块。 +从内存池中分配一个空闲块。每次分配一个固定大小的块。如果 `size` 超过块大小或池中没有空闲块，返回 `nullptr`。分配操作从空闲链表头部取出一个块。 **参数：** -- `size` - 被忽略（始终分配固定块大小） +- `size` - 请求的大小，如果超过构造时指定的块大小则分配失败 - `alignment` - 被忽略（构造时确定） **返回：** 分配成功返回块指针，池空返回 `nullptr` diff --git a/docs/api/memory/proxy-allocator/free.md b/docs/api/memory/proxy-allocator/free.md index e0ce339a..bb88289b 100644 --- a/docs/api/memory/proxy-allocator/free.md +++ b/docs/api/memory/proxy-allocator/free.md @@ -29,11 +29,10 @@ proxy.Free(p1); proxy.Free(p2); const auto& stats = proxy.GetStats(); -// totalFreed 累加了每次释放时的 allocationCount +// totalFreed 累加了每次释放时的 allocationCount（次数，非字节） // allocationCount 最终为 0 -printf("Total allocated: %zu, Total freed: %zu, Current: %zu\n", - stats.totalAllocated, stats.totalFreed, - stats.totalAllocated - stats.totalFreed); +printf("Total allocated: %zu bytes, Freed count: %zu, Current count: %zu\n", + stats.totalAllocated, stats.totalFreed, stats.allocationCount); ``` ## 相关文档 diff --git a/docs/api/memory/proxy-allocator/get-stats.md b/docs/api/memory/proxy-allocator/get-stats.md index 693041c7..6fab8a5f 100644 --- a/docs/api/memory/proxy-allocator/get-stats.md +++ b/docs/api/memory/proxy-allocator/get-stats.md @@ -27,12 +27,12 @@ proxy.Free(proxy.Allocate(256)); const ProxyAllocator::Stats& stats = proxy.GetStats(); printf("Total allocated: %zu bytes\n", stats.totalAllocated); -printf("Total freed: %zu bytes\n", stats.totalFreed); +printf("Total freed: %zu times\n", stats.totalFreed); printf("Peak allocated: %zu bytes\n", stats.peakAllocated); printf("Allocation count: %zu\n", stats.allocationCount); printf("Memory overhead: %zu bytes\n", stats.memoryOverhead); printf("Current in use: %zu bytes\n", - stats.totalAllocated - stats.totalFreed); + stats.totalAllocated - stats.allocationCount * sizeof(/* typical block */ size_t)); ``` ## 相关文档 diff --git a/docs/api/rhi/buffer/buffer.md b/docs/api/rhi/buffer/buffer.md index 76ea0733..f9148e7d 100644 --- a/docs/api/rhi/buffer/buffer.md +++ b/docs/api/rhi/buffer/buffer.md @@ -74,9 +74,12 @@ | `UnorderedAccess` | 无序访问 | | `DepthWrite` | 深度写入 | | `DepthRead` | 深度读取 | +| `NonPixelShaderResource` | 非像素着色器资源 | +| `PixelShaderResource` | 像素着色器资源 | | `CopySrc` | 复制源 | | `CopyDst` | 复制目标 | | `Present` | 呈现状态 | +| `GenericRead` | 通用读取 | ## 使用示例 diff --git a/docs/api/rhi/d3d12/render-target-view/create-desc.md b/docs/api/rhi/d3d12/render-target-view/create-desc.md index 269b94b5..fc0675ce 100644 --- a/docs/api/rhi/d3d12/render-target-view/create-desc.md +++ b/docs/api/rhi/d3d12/render-target-view/create-desc.md @@ -28,7 +28,7 @@ O(1) ## 示例 ```cpp -D3D12_RENDER_TARGET_VIEW_DESC desc = D3D12RenderTargetView::CreateDesc(Format::R8G8B8A8_UNORM); +D3D12_RENDER_TARGET_VIEW_DESC desc = D3D12RenderTargetView::CreateDesc(Format::R8G8B8A8_UNorm); ``` ## 相关文档 diff --git a/docs/api/rhi/d3d12/shader-resource-view/create-desc.md b/docs/api/rhi/d3d12/shader-resource-view/create-desc.md index 93b26bd7..019e4273 100644 --- a/docs/api/rhi/d3d12/shader-resource-view/create-desc.md +++ b/docs/api/rhi/d3d12/shader-resource-view/create-desc.md @@ -29,7 +29,7 @@ O(1) ## 示例 ```cpp -D3D12_SHADER_RESOURCE_VIEW_DESC desc = D3D12ShaderResourceView::CreateDesc(Format::R8G8B8A8_UNORM); +D3D12_SHADER_RESOURCE_VIEW_DESC desc = D3D12ShaderResourceView::CreateDesc(Format::R8G8B8A8_UNorm); ``` ## 相关文档 diff --git a/docs/api/rhi/d3d12/types/to-d3d12-texture-desc.md b/docs/api/rhi/d3d12/types/to-d3d12-texture-desc.md index ef9320e0..4d059a69 100644 --- a/docs/api/rhi/d3d12/types/to-d3d12-texture-desc.md +++ b/docs/api/rhi/d3d12/types/to-d3d12-texture-desc.md @@ -27,7 +27,7 @@ O(1) ## 示例 ```cpp -TextureDesc td = { TextureType::Texture2D, 1920, 1080, 1, Format::R8G8B8A8_UNORM }; +TextureDesc td = { TextureType::Texture2D, 1920, 1080, 1, Format::R8G8B8A8_UNorm }; D3D12_RESOURCE_DESC d3d12Desc = ToD3D12(td); ``` diff --git a/docs/api/rhi/texture/texture.md b/docs/api/rhi/texture/texture.md index da8e59dc..fe6c94ab 100644 --- a/docs/api/rhi/texture/texture.md +++ b/docs/api/rhi/texture/texture.md @@ -55,11 +55,26 @@ | 格式 | 描述 | |------|------| +| `Format::Unknown` | 未知格式 | +| `Format::R8_UNorm` | 单通道 8 位归一化 | +| `Format::R8G8_UNorm` | 双通道 8 位归一化 | | `Format::R8G8B8A8_UNorm` | 四通道 8 位归一化 | | `Format::R16G16B16A16_Float` | 四通道 16 位浮点 | +| `Format::R32G32B32A32_Float` | 四通道 32 位浮点 | +| `Format::R16_Float` | 单通道 16 位浮点 | +| `Format::R32_Float` | 单通道 32 位浮点 | +| `Format::D16_UNorm` | 16 位深度 | +| `Format::D24_UNorm_S8_UInt` | 24 位深度 + 8 位模板 | | `Format::D32_Float` | 32 位深度 | | `Format::BC1_UNorm` | BC1 压缩 (DXT1) | +| `Format::BC2_UNorm` | BC2 压缩 (DXT2/3) | +| `Format::BC3_UNorm` | BC3 压缩 (DXT4/5) | +| `Format::BC4_UNorm` | BC4 压缩 | +| `Format::BC5_UNorm` | BC5 压缩 | +| `Format::BC6H_UF16` | BC6H 压缩 (UF16) | | `Format::BC7_UNorm` | BC7 高质量压缩 | +| `Format::R32G32B32A32_UInt` | 四通道 32 位无符号整数 | +| `Format::R32_UInt` | 单通道 32 位无符号整数 | ## 使用示例 diff --git a/docs/api/threading/task-group/cancel.md b/docs/api/threading/task-group/cancel.md index 5c8038f2..1d0ed472 100644 --- a/docs/api/threading/task-group/cancel.md +++ b/docs/api/threading/task-group/cancel.md @@ -15,7 +15,8 @@ void Cancel() **注意：** - 已完成的任务不受影响。 - 正在执行的任务继续执行直到完成。 -- 调用后所有 Wait/WaitFor 会立即返回。 +- 调用后所有 Wait/WaitFor 会立即返回（但请参见下方警告）。 +- **警告**：`Cancel()` 调用 `OnCancel()` 后不会减少待完成任务数，因此如果任务组中还有未执行的任务，调用 `Wait()` 会导致永久阻塞。建议在 `Cancel()` 后使用 `IsComplete()` 轮询或使用带超时的 `WaitFor()`。 **示例：** diff --git a/docs/api/threading/task-group/getprogress.md b/docs/api/threading/task-group/getprogress.md index cfa8b28d..b150491a 100644 --- a/docs/api/threading/task-group/getprogress.md +++ b/docs/api/threading/task-group/getprogress.md @@ -12,6 +12,8 @@ float GetProgress() const **复杂度：** O(1) +**注意：** 当前实现中 `m_completedCount` 未被更新，此方法始终返回 0.0f（任务组为空时返回 1.0f）。此为实现限制。 + **示例：** ```cpp @@ -21,13 +23,10 @@ for (int i = 0; i < 1000; ++i) { group->AddTask([i]() { ProcessItem(i); }); } -// 显示进度 +// 显示进度（注意：当前实现始终返回 0.0f） while (!group->IsComplete()) { float progress = group->GetProgress(); - printf("\rLoading: [%-50s] %.1f%%", - std::string(50, '=').substr(0, (int)(progress * 50)).c_str(), - progress * 100.0f); - fflush(stdout); + printf("\rProgress: %.1f%%", progress * 100.0f); Thread::Sleep(100); } printf("\n"); diff --git a/docs/api/threading/task-group/wait.md b/docs/api/threading/task-group/wait.md index 9303d1d9..ad0c2064 100644 --- a/docs/api/threading/task-group/wait.md +++ b/docs/api/threading/task-group/wait.md @@ -12,7 +12,10 @@ void Wait() **复杂度：** O(n)，n 为任务数量 -**注意：** 如果任务组已被取消，此方法将立即返回。 +**注意：** +- 如果任务组已被取消，此方法将立即返回。 +- 如果任务组中还有未执行且未被取消的任务，调用此方法将永久阻塞（这是当前实现的限制）。 +- 建议使用 `WaitFor()` 代替以避免永久阻塞。 **示例：**