XCEngine/docs/api/rhi/d3d12/d3d12-fence.md

D3D12Fence

DirectX 12 栅栏同步对象的 D3D12 实现，封装了 ID3D12Fence。

头文件

#include <XCEngine/RHI/D3D12/D3D12Fence.h>

继承关系

RHIFence (interface)
└── D3D12Fence (implementation)

公共成员函数

构造函数与析构函数

D3D12Fence()

默认构造函数。

~D3D12Fence() override

析构函数，确保调用 Shutdown()。

初始化与销毁

bool Initialize(ID3D12Device* device, uint64_t initialValue = 0)

初始化栅栏。

• device: D3D12 设备
• initialValue: 初始信号值
• 返回: 初始化是否成功

void Shutdown() override

关闭栅栏并释放事件句柄。

信号操作

void Signal() override

发送信号，将值增加 1。

void Signal(uint64_t value) override

发送信号，设置指定值。

void Wait(uint64_t value) override

等待栅栏达到指定值。

uint64_t GetCompletedValue() const override

获取当前完成值。

bool IsSignaled() const override

检查是否已达到信号值。

void* GetEventHandle()

获取事件句柄，用于自定义等待。

原生接口

void* GetNativeHandle() override { return m_fence.Get(); }

ID3D12Fence* GetFence() const

获取底层 ID3D12Fence 指针。

内部成员

成员	类型	描述
m_fence	ComPtr<ID3D12Fence>	D3D12 栅栏对象
m_eventHandle	void*	同步事件句柄
m_signalValue	uint64_t	最后信号值

使用示例

D3D12Fence fence;
fence.Initialize(device->GetDevice());

// CPU-GPU 同步
cmdQueue->Signal(fence.GetFence(), 1);
fence.Wait(1);

// 多帧同步
uint64_t frameFenceValues[3] = {0, 0, 0};
int frameIndex = 0;

void RenderFrame() {
    uint64_t fenceValue = frameIndex + 1;
    cmdQueue->Signal(fence.GetFence(), fenceValue);
    
    // Wait for this frame's previous render to complete
    if (fence.GetCompletedValue() < frameFenceValues[frameIndex]) {
        fence.Wait(frameFenceValues[frameIndex]);
    }
    
    frameFenceValues[frameIndex] = fenceValue;
    frameIndex = (frameIndex + 1) % 3;
}

备注

• 栅栏用于 CPU-GPU 和 GPU-GPU 同步
• 事件句柄可用于 WaitForSingleObject 等 Win32 API
• 多帧缓冲时常用栅栏确保帧间资源安全