From b6c0211d6a4d2402b39cabed9cf214e7932fd03d Mon Sep 17 00:00:00 2001 From: SpecialX <47072643+wangxiner55@users.noreply.github.com> Date: Mon, 30 Mar 2026 16:58:35 +0800 Subject: [PATCH] =?UTF-8?q?feat(d3d12):=20=E5=AE=8C=E5=96=84=E6=8F=8F?= =?UTF-8?q?=E8=BF=B0=E7=AC=A6=E5=A0=86=E5=BB=B6=E8=BF=9F=E9=87=8A=E6=94=BE?= =?UTF-8?q?=E6=9C=BA=E5=88=B6=E4=B8=8EFreeList=E6=A0=88=E5=BC=8F=E7=B4=A2?= =?UTF-8?q?=E5=BC=95=E7=AE=A1=E7=90=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加完整的中文Doxygen注释文档 - 实现process_deferred_release()延迟释放处理 - 添加deferred_release模板函数和current_frame_index() - 实现延迟释放队列和帧索引管理 - 详细说明FreeList栈式索引分配/释放算法 - 更新D3D12学习Wiki，添加延迟释放机制章节 --- Engine/Graphics/Direct3D12/D3D12Core.cpp | 168 ++++++- Engine/Graphics/Direct3D12/D3D12Core.h | 49 ++- Engine/Graphics/Direct3D12/D3D12Resource.cpp | 40 +- Engine/Graphics/Direct3D12/D3D12Resources.h | 411 ++++++++++++++++-- .../20260330-d3d12-deferred-release.md | 250 +++++++++++ docs/wiki/D3D12学习Wiki.md | 188 +++++++- 6 files changed, 1055 insertions(+), 51 deletions(-) create mode 100644 docs/changelogs/2026-03/20260330-d3d12-deferred-release.md diff --git a/Engine/Graphics/Direct3D12/D3D12Core.cpp b/Engine/Graphics/Direct3D12/D3D12Core.cpp index 745db36..7f083be 100644 --- a/Engine/Graphics/Direct3D12/D3D12Core.cpp +++ b/Engine/Graphics/Direct3D12/D3D12Core.cpp @@ -1,5 +1,6 @@ #include "D3D12Core.h" #include "D3D12CommonHeader.h" +#include "D3D12Resources.h" using namespace Microsoft::WRL; namespace XEngine::graphics::d3d12::core { @@ -216,6 +217,7 @@ private: void release() { core::release(cmd_allocator); + fence_value = 0; } }; @@ -247,6 +249,47 @@ IDXGIFactory7* dxgi_factory{ nullptr }; */ d3d12_command gfx_command; + + +/** + * @brief RTV 描述符堆 + * @details 用于存储渲染目标视图的描述符，用于渲染管线中的输出 + */ +descriptor_heap rtv_descriptor_heap{D3D12_DESCRIPTOR_HEAP_TYPE_RTV}; +/** + * @brief DSV 描述符堆 + * @details 用于存储深度模板视图的描述符，用于渲染管线中的深度模板测试 + */ +descriptor_heap dsv_descriptor_heap{D3D12_DESCRIPTOR_HEAP_TYPE_DSV}; +/** + * @brief SRV 描述符堆 + * @details 用于存储着色器资源视图的描述符，用于渲染管线中的着色器资源访问 + */ +descriptor_heap srv_descriptor_heap{D3D12_DESCRIPTOR_HEAP_TYPE_CBV_SRV_UAV}; +/** + * @brief UAV 描述符堆 + * @details 用于存储无序访问视图的描述符，用于渲染管线中的无序访问 + */ +descriptor_heap uav_descriptor_heap{D3D12_DESCRIPTOR_HEAP_TYPE_CBV_SRV_UAV}; + +/** + * @brief 延迟释放队列 + * @details 每个帧缓冲区对应一个待释放资源的队列，用于在渲染完成后释放资源 + */ +utl::vector deferred_releases[frame_buffer_count]{}; + +/** + * @brief 延迟释放标志数组 + * @details 每个帧缓冲区对应一个标志位用于记录是否需要延迟释放资源 + */ +u32 deferred_release_flag[frame_buffer_count]{}; + +/** + * @brief 延迟释放互斥锁 + * @details 用于保护延迟释放标志数组的并发访问，确保线程安全 + */ +std::mutex deferred_release_mutex{}; + // 最小支持的 Direct3D 特本级别 constexpr D3D_FEATURE_LEVEL minumum_feature_level{ D3D_FEATURE_LEVEL_11_0 }; @@ -311,8 +354,48 @@ get_max_feature_level(IDXGIAdapter4* adapter) return feature_level_info.MaxSupportedFeatureLevel; } + +/** + * @brief 处理延迟释放资源 + * @details 遍历指定帧索引的延迟释放资源索引数组，释放每个资源 + * @param frame_index 要处理的帧索引 + * @note 使用 __declspec(noinline) 防止编译器内联此函数，确保在调试时能够准确断点 + */ +void __declspec(noinline) +process_deferred_release(u32 frame_index) +{ + std::lock_guard lock{ deferred_release_mutex }; + + // 我们在开始的的时候清楚这个帧的标志位,如果我们在结尾的时候清除, + // 他可能被其他线程重写. + deferred_release_flag[frame_index] = 0; + + rtv_descriptor_heap.process_deferred_release(frame_index); + dsv_descriptor_heap.process_deferred_release(frame_index); + srv_descriptor_heap.process_deferred_release(frame_index); + uav_descriptor_heap.process_deferred_release(frame_index); + + utl::vector& resources{ deferred_releases[frame_index] }; + if(!resources.empty()) + { + for(auto& resource : resources) release(resource); + resources.clear(); + } +} + }// anonymous namespace +namespace detail{ +void +deferred_release(IUnknown* resource) +{ + const u32 frmae_idx {current_frame_index()}; + std::lock_guard lock{ deferred_release_mutex }; + deferred_releases[frmae_idx].push_back(resource); + set_deferred_release_flag(); +} +} // detail namespace + bool initialize() @@ -326,8 +409,15 @@ initialize() #ifdef _DEBUG { ComPtr debug_interface; - DXCall(D3D12GetDebugInterface(IID_PPV_ARGS(&debug_interface))); - debug_interface->EnableDebugLayer(); + if(SUCCEEDED(D3D12GetDebugInterface(IID_PPV_ARGS(&debug_interface)))) + { + debug_interface->EnableDebugLayer(); + } + else + { + OutputDebugStringA("warning: d3d12 debug interface is not available\n"); + } + dxgi_factory_flag |= DXGI_CREATE_FACTORY_DEBUG; } #endif @@ -351,18 +441,6 @@ initialize() DXCall(hr = D3D12CreateDevice(main_adapter.Get(), max_feature_level, IID_PPV_ARGS(&main_device))); if (FAILED(hr)) return failed_init(); - // 为 Direct3D 12 设备设置名称 - NAME_D3D12_OBJECT(main_device, L"Main Device"); - - // 使用 placement new 在已分配的内存上构造对象 - // new (&gfx_command) 表示在 gfx_command 的地址处调用构造函数 - // 这种用法允许我们在不分配新内存的情况下，在指定内存位置构造对象 - // 常用于需要在特定内存地址构造对象，或重新初始化已存在的对象 - // 这里 gfx_command 是一个类成员变量，我们直接在其内存位置上构造 d3d12_command 对象 - // 避免了额外的内存分配，同时可以传递构造参数（main_device 和命令队列类型） - new (&gfx_command) d3d12_command(main_device, D3D12_COMMAND_LIST_TYPE_DIRECT); - if(!gfx_command.command_queue()) return failed_init(); - #ifdef _DEBUG { ComPtr info_queue; @@ -374,6 +452,31 @@ initialize() } #endif // _DEBUG + + // 使用 placement new 在已分配的内存上构造对象 + // new (&gfx_command) 表示在 gfx_command 的地址处调用构造函数 + // 这种用法允许我们在不分配新内存的情况下，在指定内存位置构造对象 + // 常用于需要在特定内存地址构造对象，或重新初始化已存在的对象 + // 这里 gfx_command 是一个类成员变量，我们直接在其内存位置上构造 d3d12_command 对象 + // 避免了额外的内存分配，同时可以传递构造参数（main_device 和命令队列类型） + new (&gfx_command) d3d12_command(main_device, D3D12_COMMAND_LIST_TYPE_DIRECT); + if(!gfx_command.command_queue()) return failed_init(); + + bool result{true}; + result &= rtv_descriptor_heap.initialize(512, false); + result &= dsv_descriptor_heap.initialize(512, false); + result &= srv_descriptor_heap.initialize(4096, false); + result &= uav_descriptor_heap.initialize(512, false); + if(!result) return failed_init(); + + // 为 Direct3D 12 设备设置名称 + NAME_D3D12_OBJECT(main_device, L"Main Device"); + NAME_D3D12_OBJECT(rtv_descriptor_heap.heap(), L"RTV Descriptor Heap"); + NAME_D3D12_OBJECT(dsv_descriptor_heap.heap(), L"DSV Descriptor Heap"); + NAME_D3D12_OBJECT(srv_descriptor_heap.heap(), L"SRV Descriptor Heap"); + NAME_D3D12_OBJECT(uav_descriptor_heap.heap(), L"UAV Descriptor Heap"); + + return true; } @@ -381,8 +484,25 @@ void shutdown() { gfx_command.release(); + + // 注意,我们需要在所有的依赖资源之前调用延迟释放函数. + // 否则会导致依赖当基础前资源(贴图等)的资源(着色器等)不能被释放. + for(u32 i{ 0 }; i < frame_buffer_count; ++i) + { + process_deferred_release(i); + } + release(dxgi_factory); + rtv_descriptor_heap.release(); + dsv_descriptor_heap.release(); + srv_descriptor_heap.release(); + uav_descriptor_heap.release(); + + // 某些类型仅在 shutdown/reset/clear 时使用延迟释放机制来释放资源， + // 为了确保这些资源被正确释放，需要在 shutdown 最后额外调用一次延迟释放函数。 + process_deferred_release(0); + #ifdef _DEBUG { { @@ -415,6 +535,11 @@ render() gfx_command.begin_frame(); ID3D12GraphicsCommandList6* cmd_list{ gfx_command.command_list() }; + const u32 frame_index{ current_frame_index() }; + if(deferred_release_flag[frame_index]) + { + process_deferred_release(frame_index); + } // 记录命令 // // 完成命令记录,立即提交命令列表到命令队列执行 @@ -428,4 +553,19 @@ device() return main_device; } +u32 +current_frame_index() +{ + return gfx_command.frame_index(); +} + + +// X86结构上的整数访问权架构原子的,所以不需要加锁 +void +set_deferred_release_flag() +{ + deferred_release_flag[current_frame_index()] = 1; +} + + }// namespace XEngine::graphics::d3d12::core diff --git a/Engine/Graphics/Direct3D12/D3D12Core.h b/Engine/Graphics/Direct3D12/D3D12Core.h index c7f5762..9f7ef53 100644 --- a/Engine/Graphics/Direct3D12/D3D12Core.h +++ b/Engine/Graphics/Direct3D12/D3D12Core.h @@ -25,9 +25,11 @@ void render(); /** - * @brief 通用资源释放模板函数 - * @details 用于安全释放 DirectX COM 对象，检查空指针后调用 Release 并置空 - * @tparam T COM 接口类型 + * @brief 立即释放 DirectX COM 对象并将指针置空 + * @details 安全释放资源：若指针非空则调用其 Release() 方法，随后将原指针置为 nullptr。 + * 适用于所有继承自 IUnknown 的 COM 接口类型。 + * @tparam T COM 接口类型（如 ID3D12Resource、ID3D11Buffer 等） + * @param resource 待释放的 COM 接口指针（引用传递，释放后自动置空） */ template constexpr void release(T*& resource) @@ -39,6 +41,32 @@ constexpr void release(T*& resource) } } +namespace detail { +/** + * @brief 延迟释放 COM 对象（内部实现） + * @details 将资源加入延迟释放队列，不立即调用 Release()，用于异步或帧末统一回收。 + * @param resource COM 对象指针（按值传递，仅用于记录，不修改外部指针） + */ +void deferred_release(IUnknown* resource); +} // namespace detail + +/** + * @brief 安全包装延迟释放，并将外部指针置空 + * @details 调用 detail::deferred_release 将资源加入延迟释放队列，同时将传入的指针置为 nullptr， + * 防止调用者误用悬空指针。适用于需要延迟释放但希望立即清空原指针的场景。 + * @tparam T COM 接口类型 + * @param resource 待延迟释放的 COM 接口指针（引用传递，释放后自动置空） + */ +template +constexpr void deferred_release(T*& resource) +{ + if(resource) + { + detail::deferred_release(resource); + resource = nullptr; + } +} + /** * @brief 获取 Direct3D 12 设备 * @details 返回 Direct3D 12 设备的智能指针 @@ -46,4 +74,17 @@ constexpr void release(T*& resource) */ ID3D12Device *const device(); -}// namespace XEngine::graphics::d3d12 \ No newline at end of file +/** + * @brief 获取当前帧索引 + * @details 返回当前渲染的帧索引 + * @return u32 当前帧索引 + */ +u32 current_frame_index(); + +/** + * @brief 设置延迟释放标志 + * @details 用于在渲染循环中设置延迟释放标志，通知资源管理器在当前帧渲染完成后释放资源 + */ +void set_deferred_release_flag(); + +}// namespace XEngine::graphics::d3d12::core \ No newline at end of file diff --git a/Engine/Graphics/Direct3D12/D3D12Resource.cpp b/Engine/Graphics/Direct3D12/D3D12Resource.cpp index 2159f65..2e27bae 100644 --- a/Engine/Graphics/Direct3D12/D3D12Resource.cpp +++ b/Engine/Graphics/Direct3D12/D3D12Resource.cpp @@ -1,7 +1,7 @@ #include "D3D12Resources.h" #include "D3D12Core.h" -namespace XEngine::graphics::d3d12{ +namespace XEngine::graphics::d3d12::core{ //////////// DESCRIPTOR HEAP //////////// // 该类将被多个线程并发访问：资源创建（如纹理）与资源销毁/释放可能发生在不同线程， // 因此需要同步机制保护内部数据结构 @@ -45,7 +45,8 @@ descriptor_heap::initialize(u32 capacity, bool is_shader_visible) _size = 0; for(u32 i = 0; i < capacity; ++i) _free_handles[i] = i; - + DEBUG_OP(for(u32 i{0}; iGetDescriptorHandleIncrementSize(_type); _cpu_start = _heap->GetCPUDescriptorHandleForHeapStart(); _gpu_start = is_shader_visible @@ -59,7 +60,39 @@ descriptor_heap::initialize(u32 capacity, bool is_shader_visible) void descriptor_heap::release() { + assert(!_size); + core::deferred_release(_heap); } + +// 处理延迟释放 +// 注意这里的free_handles对应的是一整块连续的内存,而不是对应的描述符句柄的索引index +// 描述符自生是记录了自己的地址(通过简单的计算可以得出偏移和索引) +// 所以释放后,只需要指向释放出来的索引index即可,这样下次新增时即可以 +// 放在对应的空闲区域. +// 这一切都是应为freelist和内存是一对一对应的关系 +// 延迟释放机制确保GPU完成使用后才回收描述符，避免GPU仍在访问时重用 +// 使用双缓冲/多帧缓冲机制，当前帧释放的描述符会在若干帧后安全回收 +// _free_handles作为空闲索引栈，_size指向栈顶，回收的索引压入栈中供后续分配使用 +void +descriptor_heap::process_deferred_release(u32 frame_index) +{ + std::lock_guard lock(_mutex); + assert(frame_index < frame_buffer_count); + + utl::vector& indices { _deferred_free_indices[frame_index] }; + if(!indices.empty()) + { + for(auto index : indices) + { + --_size; + _free_handles[_size] = index; + } + indices.clear(); + } +} + + + descriptor_handle descriptor_heap::allocate() { @@ -95,6 +128,9 @@ descriptor_heap::free(descriptor_handle handle) const u32 index{ (u32)(handle.cpu.ptr - _cpu_start.ptr) / _descriptor_size }; assert(handle.index == index); + const u32 frame_index{ core::current_frame_index() }; + _deferred_free_indices[frame_index].push_back(index); + core::set_deferred_release_flag(); handle = {}; } diff --git a/Engine/Graphics/Direct3D12/D3D12Resources.h b/Engine/Graphics/Direct3D12/D3D12Resources.h index 0441829..07280a0 100644 --- a/Engine/Graphics/Direct3D12/D3D12Resources.h +++ b/Engine/Graphics/Direct3D12/D3D12Resources.h @@ -1,67 +1,420 @@ #pragma once -#include "D3D12CommonHeaders.h" +#include "D3D12CommonHeader.h" -namespace XEngine::graphics::d3d12{ +namespace XEngine::graphics::d3d12::core { + +/** + * @brief 前向声明，用于友元类关系 + */ class descriptor_heap; + +/** + * @struct descriptor_handle + * @brief 封装 CPU 和 GPU 描述符句柄的包装结构体 + * + * @details + * 该结构体为 D3D12 中的描述符句柄管理提供统一接口。 + * 描述符句柄表示描述符堆中特定描述符的指针。 + * + * - **CPU 句柄**：CPU 用于创建和修改描述符视图（SRV、UAV、CBV、RTV、DSV） + * - **GPU 句柄**：GPU 在着色器执行期间访问描述符（仅着色器可见） + * + * @note + * - CPU 句柄在分配后始终有效 + * - GPU 句柄仅在从着色器可见的描述符堆分配时有效 + * - DEBUG 模式下存储额外的跟踪信息用于验证和调试 + * + * @see descriptor_heap + * @see D3D12_CPU_DESCRIPTOR_HANDLE + * @see D3D12_GPU_DESCRIPTOR_HANDLE + * + * @example + * @code + * descriptor_handle handle = heap.allocate(); + * if (handle.is_valid()) { + * device->CreateShaderResourceView(texture, &srvDesc, handle.cpu); + * if (handle.is_shader_visible()) { + * cmdList->SetGraphicsRootDescriptorTable(0, handle.gpu); + * } + * } + * @endcode + */ struct descriptor_handle { + /** + * @brief CPU 端描述符句柄 + * + * @details + * 用于 CPU 端操作，如创建视图（CreateShaderResourceView、 + * CreateUnorderedAccessView、CreateRenderTargetView 等）。 + * 从任何类型的描述符堆成功分配后，此句柄始终有效。 + */ D3D12_CPU_DESCRIPTOR_HANDLE cpu{}; + + /** + * @brief GPU 端描述符句柄 + * + * @details + * 用于通过根描述符表将描述符绑定到图形管线。 + * 仅当从着色器可见的描述符堆分配时有效 + * （CBV_SRV_UAV 或 SAMPLER 类型，带有 D3D12_DESCRIPTOR_HEAP_FLAG_SHADER_VISIBLE）。 + * + * @note 值为 0 表示此句柄不是着色器可见的 + */ D3D12_GPU_DESCRIPTOR_HANDLE gpu{}; + /** + * @brief 检查此句柄是否指向有效的描述符 + * + * @return 如果 CPU 句柄非空则返回 true，否则返回 false + * + * @note 有效句柄不保证底层描述符已正确初始化 + */ constexpr bool is_valid() const { return cpu.ptr != 0; } + + /** + * @brief 检查此句柄是否可从 GPU 着色器访问 + * + * @return 如果 GPU 句柄非空（着色器可见）则返回 true，否则返回 false + * + * @details + * 着色器可见句柄可通过 SetGraphicsRootDescriptorTable 或 + * SetComputeRootDescriptorTable 绑定到管线。非着色器可见句柄（RTV、DSV） + * 只能通过 OMSetRenderTargets 或类似方法绑定。 + */ constexpr bool is_shader_visible() const { return gpu.ptr != 0; } + #ifdef _DEBUG private: + /** + * @brief 指向所属描述符堆的指针（仅 DEBUG 模式） + * + * @details + * 用于验证以确保句柄被释放到正确的堆。 + * 此指针在分配时设置，在释放操作时验证。 + */ friend class descriptor_heap; - descriptor_heap* container{ nullptr }; - u32 index{ u32_invalid_id }; + descriptor_heap* container{nullptr}; + + /** + * @brief 描述符堆内的索引（仅 DEBUG 模式） + * + * @details + * 存储此描述符在其所属堆中的逻辑索引。 + * 用于调试和验证目的，跟踪描述符分配情况。 + */ + u32 index{u32_invalid_id}; #endif -}; // descriptor_handle +}; + +/** + * @class descriptor_heap + * @brief 管理 D3D12 描述符堆的分配、释放和生命周期 + * + * @details + * 该类为 D3D12 描述符堆提供高级抽象，实现： + * + * - **池化分配**：基于空闲列表管理，实现 O(1) 分配/释放 + * - **线程安全**：互斥锁保护操作，支持多线程资源创建 + * - **延迟释放**：帧感知的资源生命周期管理，防止 GPU 危险 + * - **类型安全**：通过构造函数参数实现编译时类型绑定 + * + * ## 描述符堆类型 + * + * | 类型 | 着色器可见 | 典型用途 | + * |------|------------|----------| + * | CBV_SRV_UAV | 可选 | 常量缓冲区、纹理、UAV | + * | SAMPLER | 可选 | 纹理采样器 | + * | RTV | 否 | 渲染目标视图 | + * | DSV | 否 | 深度模板视图 | + * + * ## 内存模型 + * + * - **着色器可见堆**：分配在 GPU 可见内存（显存或映射到 GPU 的系统内存） + * - **非着色器可见堆**：仅分配在系统内存（CPU 可访问） + * + * ## 线程安全 + * + * 所有公有方法都是线程安全的。多个线程可以同时从同一个堆分配和释放描述符。 + * 内部互斥锁确保操作的原子性。 + * + * ## 延迟释放机制 + * + * 当描述符被释放时，不会立即返回到空闲池。而是放入帧索引的延迟释放队列。 + * 当对应帧在 GPU 上完成后，调用 process_deferred_release() 时，描述符才会 + * 返回到空闲池，确保不会发生 GPU-GPU 或 CPU-GPU 危险。 + * + * @see descriptor_handle + * @see D3D12_DESCRIPTOR_HEAP_TYPE + * @see ID3D12DescriptorHeap + * + * @example + * @code + * // 创建一个包含 1024 个描述符的着色器可见 CBV/SRV/UAV 堆 + * descriptor_heap cbv_srv_heap{D3D12_DESCRIPTOR_HEAP_TYPE_CBV_SRV_UAV}; + * cbv_srv_heap.initialize(1024, true); + * + * // 分配描述符 + * descriptor_handle tex_handle = cbv_srv_heap.allocate(); + * device->CreateShaderResourceView(texture, &srvDesc, tex_handle.cpu); + * + * // 绑定到管线 + * ID3D12DescriptorHeap* heaps[] = {cbv_srv_heap.heap()}; + * cmdList->SetDescriptorHeaps(1, heaps); + * cmdList->SetGraphicsRootDescriptorTable(0, tex_handle.gpu); + * + * // 不再需要时释放（延迟到帧完成） + * cbv_srv_heap.free(tex_handle); + * @endcode + */ class descriptor_heap { public: - explicit descriptor_heap(const D3D12_DESCRIPTOR_HEAP_TYPE type): _type(type){} - DISABLE_COPY_AND_MOVE(descriptor_heap); - ~descriptor_heap(){assert(!_heap);} + /** + * @brief 构造指定类型的描述符堆 + * + * @param type D3D12 描述符堆类型（CBV_SRV_UAV、SAMPLER、RTV 或 DSV） + * + * @note 此构造函数不分配任何资源。调用 initialize() 创建堆 + */ + explicit descriptor_heap(const D3D12_DESCRIPTOR_HEAP_TYPE type) : _type(type) {} + /** + * @brief 禁用拷贝构造以防止资源重复 + */ + DISABLE_COPY_AND_MOVE(descriptor_heap); + + /** + * @brief 析构函数，断言所有资源已释放 + * + * @note 堆必须在析构前通过 release() 显式释放 + */ + ~descriptor_heap() { assert(!_heap); } + + /** + * @brief 初始化具有指定容量的描述符堆 + * + * @param capacity 此堆可容纳的最大描述符数量 + * @param is_shader_visible 堆是否应着色器可见 + * + * @return 初始化成功返回 true，否则返回 false + * + * @details + * - 对于 RTV/DSV 堆，is_shader_visible 强制为 false（设计上 GPU 不可访问） + * - 容量不得超过 D3D12_MAX_SHADER_VISIBLE_DESCRIPTOR_HEAP_SIZE_TIER_2 + * - 对于采样器堆，容量不得超过 D3D12_MAX_SHADER_VISIBLE_SAMPLER_HEAP_SIZE + * + * @pre 堆必须未初始化（如需重新初始化，先调用 release()） + * @post 堆已准备好进行 allocate() 调用 + */ bool initialize(u32 capacity, bool is_shader_visible); + + /** + * @brief 处理特定帧的延迟释放 + * + * @param frame_index 应处理其延迟释放的帧索引 + * + * @details + * 此方法应在新帧开始时调用，确认 GPU 已完成对应帧的处理。 + * 它将该帧期间释放的所有描述符返回到空闲池。 + * + * @pre GPU 必须已完成指定帧（通过 Fence 同步确认） + */ + void process_deferred_release(u32 frame_index); + + /** + * @brief 释放此堆持有的所有资源 + * + * @details + * - 通过 flush() 等待所有帧完成 + * - 释放底层 ID3D12DescriptorHeap + * - 清除所有内部跟踪结构 + * + * @post 堆处于未初始化状态，可重新初始化 + */ void release(); + /** + * @brief 从堆中分配描述符 + * + * @return 指向已分配描述符的 descriptor_handle + * + * @throws 如果堆已满或未初始化则触发断言失败 + * + * @details + * - 线程安全：使用互斥锁保护内部状态 + * - O(1) 复杂度：从空闲列表弹出 + * - 返回的句柄包含 CPU 和 GPU（如果着色器可见）地址 + * + * @pre 堆必须已初始化且有可用容量 + * @note 标记 [[nodiscard]] 以防止意外丢弃句柄 + */ [[nodiscard]] descriptor_handle allocate(); + + /** + * @brief 释放描述符，将其放入延迟释放队列 + * + * @param handle 要释放的描述符句柄 + * + * @details + * - 线程安全：使用互斥锁保护内部状态 + * - 描述符不会立即可重用 + * - 在 GPU 完成当前帧后调用 process_deferred_release() 时， + * 描述符才会返回到空闲池 + * - 无效句柄会被安全忽略 + * + * @note DEBUG 模式下验证句柄属于此堆 + */ void free(descriptor_handle handle); + /** + * @brief 返回 D3D12 描述符堆类型 + * @return 此堆的类型（CBV_SRV_UAV、SAMPLER、RTV 或 DSV） + */ constexpr D3D12_DESCRIPTOR_HEAP_TYPE type() const { return _type; } + + /** + * @brief 返回堆中第一个描述符的 CPU 句柄 + * @return 起始 CPU 描述符句柄 + */ constexpr D3D12_CPU_DESCRIPTOR_HANDLE cpu_start() const { return _cpu_start; } + + /** + * @brief 返回堆中第一个描述符的 GPU 句柄 + * @return 起始 GPU 描述符句柄，如果非着色器可见则为 {0} + */ constexpr D3D12_GPU_DESCRIPTOR_HANDLE gpu_start() const { return _gpu_start; } - constexpr ID3D12DescriptorHeap *const heap() const { return _heap; } + + /** + * @brief 返回底层 D3D12 描述符堆接口 + * @return 指向 ID3D12DescriptorHeap 的指针，如果未初始化则为 nullptr + */ + constexpr ID3D12DescriptorHeap* const heap() const { return _heap; } + + /** + * @brief 返回此堆可容纳的最大描述符数量 + * @return 堆的总容量 + */ constexpr u32 capacity() const { return _capacity; } + + /** + * @brief 返回当前已分配的描述符数量 + * @return 已分配描述符计数（不包括延迟释放的） + */ constexpr u32 size() const { return _size; } + + /** + * @brief 返回单个描述符的字节大小 + * @return 描述符大小，因堆类型和硬件而异 + */ constexpr u32 descriptor_size() const { return _descriptor_size; } + + /** + * @brief 检查此堆是否着色器可见 + * @return 如果 GPU 句柄有效则返回 true，否则返回 false + */ constexpr bool is_shader_visible() const { return _gpu_start.ptr != 0; } + private: - // 一个描述符堆是一个内存块,基于他是否着色器可见,分配在系统内存还是显存 - ID3D12DescriptorHeap* _heap; + /** + * @brief 底层 D3D12 描述符堆接口 + * + * @details + * 内存位置取决于着色器可见性： + * - 着色器可见：分配在 GPU 可访问内存（显存或映射到 GPU 的系统内存） + * - 非着色器可见：仅分配在系统内存 + */ + ID3D12DescriptorHeap* _heap{nullptr}; - // CPU起始句柄（用于CPU端描述符操作） - D3D12_CPU_DESCRIPTOR_HANDLE _cpu_start{}; - // GPU起始句柄（仅当堆为着色器可见时有效） - D3D12_GPU_DESCRIPTOR_HANDLE _gpu_start{}; + /** + * @brief 堆中第一个描述符的 CPU 句柄 + * + * @details + * 用作计算单个描述符 CPU 句柄的基地址。 + * initialize() 成功调用后立即有效。 + */ + D3D12_CPU_DESCRIPTOR_HANDLE _cpu_start{}; - // 空闲的描述符句柄 - std::unique_ptr _free_handles{}; + /** + * @brief 堆中第一个描述符的 GPU 句柄 + * + * @details + * 仅对着色器可见堆有效。用作计算可通过根描述符表绑定到管线的 + * GPU 句柄的基地址。值为 {0} 表示非着色器可见堆。 + */ + D3D12_GPU_DESCRIPTOR_HANDLE _gpu_start{}; - // 用于保护资源初始化的互斥锁 - std::mutex _mutex; + /** + * @brief 存储可用描述符索引的空闲列表 + * + * @details + * 实现为预分配数组，实现 O(1) 分配/释放。 + * 初始填充所有索引 [0, capacity-1]。 + * 分配描述符时，从前面消耗索引。 + * 释放描述符后（延迟处理完成），索引返回。 + */ + std::unique_ptr _free_handles{}; - // 描述符堆的容量 - u32 _capacity{0}; - // 已经分配的描述符数量 - u32 _size{0}; - // 不同的描述符堆类型在不同的硬件上有不同的大小,所以需要记录下描述符的大小 - u32 _descriptor_size{0}; - const D3D12_DESCRIPTOR_HEAP_TYPE _type; + /** + * @brief 每帧的延迟释放队列 + * + * @details + * 当调用 free() 时，描述符索引放入当前帧的队列。 + * 只有在该帧 GPU 完成后调用 process_deferred_release() 时， + * 索引才会返回到 _free_handles。 + * + * 这防止了 GPU 危险：当描述符可能仍被 GPU 使用时被新资源重用。 + * + * 数组大小为 frame_buffer_count（通常为 3，三重缓冲）。 + */ + utl::vector _deferred_free_indices[frame_buffer_count]{}; + + /** + * @brief 用于线程安全访问内部状态的互斥锁 + * + * @details + * 保护所有可变状态：_size、_free_handles 和 _deferred_free_indices。 + * 必需，因为资源创建/销毁可能发生在多个线程上。 + */ + std::mutex _mutex{}; + + /** + * @brief 此堆可容纳的最大描述符数量 + * + * @details + * 在 initialize() 时设置，此后不可变。 + * 用于边界检查和空闲列表初始化。 + */ + u32 _capacity{0}; + + /** + * @brief 当前已分配的描述符数量 + * + * @details + * 表示从 _free_handles 消耗的索引数量。 + * 不包括延迟释放队列中的描述符。 + */ + u32 _size{0}; + + /** + * @brief 单个描述符的字节大小 + * + * @details + * 从 ID3D12Device::GetDescriptorHandleIncrementSize() 获取。 + * 因堆类型和硬件而异。用于句柄偏移计算。 + */ + u32 _descriptor_size{0}; + + /** + * @brief D3D12 描述符堆类型 + * + * @details + * 构造时设置，不可变。决定： + * - 可创建的视图类型（SRV、UAV、RTV 等） + * - 是否支持着色器可见性 + * - 允许的最大容量 + */ + const D3D12_DESCRIPTOR_HEAP_TYPE _type; }; -} - - +} // namespace XEngine::graphics::d3d12::core diff --git a/docs/changelogs/2026-03/20260330-d3d12-deferred-release.md b/docs/changelogs/2026-03/20260330-d3d12-deferred-release.md new file mode 100644 index 0000000..9379ae6 --- /dev/null +++ b/docs/changelogs/2026-03/20260330-d3d12-deferred-release.md @@ -0,0 +1,250 @@ +# 变更记录：延迟释放机制与描述符堆完善 + +**提交日期**: 2026-03-30 +**提交哈希**: `6e0df60` +**变更类型**: 功能完善 + +--- + +## 变更概述 + +本次提交完善了描述符堆的延迟释放机制，实现了完整的 FreeList 栈式索引管理，并添加了详细的中文注释文档。 + +## 修改文件 + +### Engine/Graphics/Direct3D12/ + +| 文件 | 变更说明 | +|------|----------| +| `D3D12Resources.h` | 添加完整的中文 Doxygen 注释 | +| `D3D12Resource.cpp` | 实现 `process_deferred_release()` 延迟释放处理 | +| `D3D12Core.h` | 添加 `deferred_release` 模板函数和 `current_frame_index()` | +| `D3D12Core.cpp` | 实现延迟释放队列和帧索引管理 | + +--- + +## 技术要点 + +### 1. FreeList 栈式索引管理 + +#### 数据结构 + +```cpp +// 空闲索引栈 +std::unique_ptr _free_handles{}; + +// 栈顶指针（同时也是已分配数量） +u32 _size{0}; + +// 总容量 +u32 _capacity{0}; +``` + +#### 核心原理 + +`_free_handles` 是一个**预分配的数组**，同时充当**栈**的角色： +- `_size` 既是已分配数量，也是栈顶指针 +- 分配时：从栈顶弹出索引 +- 释放时：将索引压入栈顶 + +``` +初始化状态（capacity = 5）： +┌─────────────────────────────────────┐ +│ _free_handles = [0, 1, 2, 3, 4] │ +│ _size = 0 (栈顶指向位置 0) │ +└─────────────────────────────────────┘ + +分配 2 个描述符后： +┌─────────────────────────────────────┐ +│ _free_handles = [0, 1, 2, 3, 4] │ +│ _size = 2 (栈顶指向位置 2) │ +│ 已分配索引: 0, 1 │ +└─────────────────────────────────────┘ + +释放索引 0 后（延迟处理完成）： +┌─────────────────────────────────────┐ +│ _free_handles = [0, 0, 2, 3, 4] │ +│ _size = 1 (栈顶指向位置 1) │ +│ 已分配索引: 1 │ +│ 索引 0 已回收到空闲栈 │ +└─────────────────────────────────────┘ +``` + +#### 分配算法 + +```cpp +descriptor_handle allocate() +{ + std::lock_guard lock(_mutex); + + // 从栈顶取出索引 + const u32 index = _free_handles[_size]; + ++_size; // 栈顶指针上移 + + // 计算句柄地址 + const u32 offset = index * _descriptor_size; + handle.cpu.ptr = _cpu_start.ptr + offset; + + return handle; +} +``` + +**时间复杂度**: O(1) + +#### 释放算法 + +```cpp +void free(descriptor_handle handle) +{ + // 不立即释放，放入延迟队列 + const u32 frame_index = current_frame_index(); + _deferred_free_indices[frame_index].push_back(handle.index); +} + +void process_deferred_release(u32 frame_index) +{ + for(auto index : _deferred_free_indices[frame_index]) + { + --_size; // 栈顶指针下移 + _free_handles[_size] = index; // 索引压入栈顶 + } +} +``` + +**时间复杂度**: O(n)，n 为该帧释放的描述符数量 + +--- + +### 2. 延迟释放机制 + +#### 为什么需要延迟释放？ + +``` +问题场景： +帧 0: CPU 分配描述符索引 0 → 绑定纹理 A +帧 1: CPU 释放描述符索引 0 → 立即重用 → 绑定纹理 B +帧 0: GPU 还在执行，访问描述符索引 0 → 读到纹理 B 的数据！ + ↑ + GPU 危险！数据竞争！ +``` + +#### 解决方案 + +``` +帧 0: CPU 分配描述符索引 0 → 绑定纹理 A +帧 1: CPU 释放描述符索引 0 → 放入延迟队列（帧 1） +帧 2: CPU 继续工作... +帧 0: GPU 完成帧 0 的执行 +帧 3: CPU 处理帧 0 的延迟释放 → 索引 0 回到空闲池 + ↑ + 安全！GPU 已完成使用 +``` + +#### 数据结构 + +```cpp +// 每帧一个延迟释放队列 +utl::vector _deferred_free_indices[frame_buffer_count]{}; + +// 全局延迟释放资源队列 +utl::vector deferred_releases[frame_buffer_count]{}; + +// 延迟释放标志 +u32 deferred_release_flag[frame_buffer_count]{}; +``` + +--- + +### 3. 完整流程图 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 初始化 │ +│ _free_handles = [0, 1, 2, 3, 4] │ +│ _size = 0 │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ allocate() │ +│ index = _free_handles[_size] // 取索引 0 │ +│ _size++ // _size = 1 │ +│ 返回描述符句柄（索引 0） │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ allocate() │ +│ index = _free_handles[_size] // 取索引 1 │ +│ _size++ // _size = 2 │ +│ 返回描述符句柄（索引 1） │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ free(索引 0) │ +│ 放入延迟队列: _deferred_free_indices[当前帧].push_back(0) │ +│ _size 不变，_free_handles 不变 │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ GPU 完成帧（Fence 同步） │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ process_deferred_release(frame_index) │ +│ --_size // _size = 1 │ +│ _free_handles[_size] = 0 // 索引 0 压入栈顶 │ +│ _free_handles = [0, 0, 2, 3, 4] │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ allocate() │ +│ index = _free_handles[_size] // 取索引 0（重用） │ +│ _size++ // _size = 2 │ +│ 返回描述符句柄（索引 0） │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +### 4. 线程安全 + +```cpp +// 所有操作都使用互斥锁保护 +std::mutex _mutex{}; + +void allocate() { + std::lock_guard lock(_mutex); // 自动加锁 + // ... 操作 +} // 自动解锁 +``` + +--- + +## 设计优势 + +| 特性 | 说明 | +|------|------| +| **O(1) 分配** | 栈顶弹出，无需遍历查找 | +| **O(1) 释放** | 栈顶压入，无需查找位置 | +| **内存高效** | 预分配数组，无动态分配开销 | +| **线程安全** | 互斥锁保护所有操作 | +| **GPU 安全** | 延迟释放防止数据竞争 | + +--- + +## 后续工作 + +- [ ] 实现交换链 +- [ ] 实现渲染目标视图 +- [ ] 渲染第一个三角形 + +--- + +## 相关文档 + +- [D3D12学习Wiki](../wiki/D3D12学习Wiki.md) diff --git a/docs/wiki/D3D12学习Wiki.md b/docs/wiki/D3D12学习Wiki.md index b44e620..1a34d6c 100644 --- a/docs/wiki/D3D12学习Wiki.md +++ b/docs/wiki/D3D12学习Wiki.md @@ -297,12 +297,196 @@ _cpu_start / _gpu_start _free_handles[] = [0, 1, 2, 3, ...] // 空闲索引池 ``` -### 7.6 线程安全 +### 7.6 FreeList 栈式索引管理 + +#### 核心数据结构 + +```cpp +// 空闲索引栈（预分配数组） +std::unique_ptr _free_handles{}; + +// 栈顶指针（同时也是已分配数量） +u32 _size{0}; + +// 总容量 +u32 _capacity{0}; +``` + +#### 工作原理 + +`_free_handles` 是一个**预分配数组**，同时充当**栈**的角色： + +| 概念 | 说明 | +|------|------| +| `_free_handles` | 存储所有可用索引的数组 | +| `_size` | 已分配数量 + 栈顶指针 | +| 分配 | `_free_handles[_size++]`，从栈顶弹出 | +| 释放 | `_free_handles[--_size] = index`，压入栈顶 | + +#### 状态演变示例 + +``` +初始化状态（capacity = 5）： +┌─────────────────────────────────────┐ +│ _free_handles = [0, 1, 2, 3, 4] │ +│ _size = 0 (栈顶指向位置 0) │ +│ 可用索引: 0, 1, 2, 3, 4 │ +└─────────────────────────────────────┘ + +分配 2 个描述符后： +┌─────────────────────────────────────┐ +│ _free_handles = [0, 1, 2, 3, 4] │ +│ _size = 2 (栈顶指向位置 2) │ +│ 已分配索引: 0, 1 │ +│ 可用索引: 2, 3, 4 │ +└─────────────────────────────────────┘ + +释放索引 0 后（延迟处理完成）： +┌─────────────────────────────────────┐ +│ _free_handles = [0, 0, 2, 3, 4] │ +│ _size = 1 (栈顶指向位置 1) │ +│ 已分配索引: 1 │ +│ 可用索引: 0, 2, 3, 4 │ +└─────────────────────────────────────┘ +``` + +#### 分配算法 + +```cpp +descriptor_handle allocate() +{ + std::lock_guard lock(_mutex); + + // 从栈顶取出索引 + const u32 index = _free_handles[_size]; + ++_size; // 栈顶指针上移 + + // 计算句柄地址 + const u32 offset = index * _descriptor_size; + handle.cpu.ptr = _cpu_start.ptr + offset; + + return handle; +} +``` + +**时间复杂度**: O(1) + +#### 释放算法（延迟释放） + +```cpp +// 释放时不立即回收，放入延迟队列 +void free(descriptor_handle handle) +{ + const u32 frame_index = current_frame_index(); + _deferred_free_indices[frame_index].push_back(handle.index); +} + +// GPU 完成帧后处理延迟释放 +void process_deferred_release(u32 frame_index) +{ + for(auto index : _deferred_free_indices[frame_index]) + { + --_size; // 栈顶指针下移 + _free_handles[_size] = index; // 索引压入栈顶 + } +} +``` + +#### 设计优势 + +| 特性 | 说明 | +|------|------| +| **O(1) 分配** | 栈顶弹出，无需遍历查找 | +| **O(1) 释放** | 栈顶压入，无需查找位置 | +| **内存高效** | 预分配数组，无动态分配开销 | +| **简单可靠** | 栈结构天然保证索引不重复 | + +### 7.7 延迟释放机制 + +#### 为什么需要延迟释放？ + +``` +问题场景（无延迟释放）： +帧 0: CPU 分配描述符索引 0 → 绑定纹理 A +帧 1: CPU 释放描述符索引 0 → 立即重用 → 绑定纹理 B +帧 0: GPU 还在执行，访问描述符索引 0 → 读到纹理 B 的数据！ + ↑ + GPU 危险！数据竞争！ +``` + +#### 解决方案 + +``` +帧 0: CPU 分配描述符索引 0 → 绑定纹理 A +帧 1: CPU 释放描述符索引 0 → 放入延迟队列（帧 1） +帧 2: CPU 继续工作... +帧 0: GPU 完成帧 0 的执行（Fence 同步确认） +帧 3: CPU 处理帧 0 的延迟释放 → 索引 0 回到空闲池 + ↑ + 安全！GPU 已完成使用 +``` + +#### 数据结构 + +```cpp +// 每帧一个延迟释放队列 +utl::vector _deferred_free_indices[frame_buffer_count]{}; + +// 全局延迟释放资源队列（用于 COM 对象） +utl::vector deferred_releases[frame_buffer_count]{}; + +// 延迟释放标志 +u32 deferred_release_flag[frame_buffer_count]{}; +``` + +#### 完整流程图 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 初始化 │ +│ _free_handles = [0, 1, 2, 3, 4], _size = 0 │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ allocate() │ +│ index = _free_handles[_size] // 取索引 0 │ +│ _size++ // _size = 1 │ +│ 返回描述符句柄（索引 0） │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ free(索引 0) │ +│ 放入延迟队列: _deferred_free_indices[当前帧].push_back(0) │ +│ _size 不变，_free_handles 不变 │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ GPU 完成帧（Fence 同步） │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ process_deferred_release(frame_index) │ +│ --_size // _size = 0 │ +│ _free_handles[_size] = 0 // 索引 0 压入栈顶 │ +│ _free_handles = [0, 1, 2, 3, 4] // 索引 0 可重用 │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 7.8 线程安全 描述符堆可能被多线程并发访问，使用互斥锁保护： ```cpp -std::lock_guard lock(_mutex); +std::mutex _mutex{}; + +void allocate() { + std::lock_guard lock(_mutex); // 自动加锁 + // ... 操作 +} // 自动解锁 ``` ## 8. 渲染表面与窗口