Agfx Synchronization

AGFX Synchronization: Fences, Barriers & Frame Pacing

Overview

AGFX exposes one fence type (agfxFence) used identically for CPU↔GPU and GPU↔GPU synchronization, and two barrier APIs: state transitions (agfxCommandBufferTextureBarrier for textures, agfxCommandBufferMemoryBarrier for buffers and acceleration structures) and UAV hazard barriers (agfxComputePassTextureUAVBarrier/BufferUAVBarrier). The tricky part is that AGFX's Metal backend has no per-resource hazard tracking the way D3D12 and Vulkan do — barriers on Metal are stage-based and get merged into a single pending barrier, controlled by the agglomerate parameter. Getting agglomerate wrong is the single most common cross-platform bug in AGFX code: it looks completely correct on D3D12 and Vulkan (both ignore the flag and always emit the transition immediately) while producing missing barriers or corrupted output on Metal.

agfxCommandBufferMemoryBarrier takes no resource argument at all — unlike the texture barrier, it isn't scoped to one buffer or acceleration structure. Buffers and acceleration structures have no "layout" to transition (only textures do), so on D3D12 this is a global memory barrier, on Vulkan a global VkMemoryBarrier2, and on Metal it merges into the same stage-based tracker textures use; there is nothing more specific to scope it to on any backend. Calling it once orders all prior GPU access in oldState against all subsequent access in newState — if you used to barrier two buffers that transition in lockstep (e.g. an indirect bundle's commands + count buffers, see agfx-mdi), that's now one call, not two identical ones back-to-back.

The second thing to internalize is barrier scope. Metal 4 distinguishes barriers that order work against prior encoders from barriers that order work within the current encoder, and they are not interchangeable — using the wrong one produces a barrier that silently orders nothing. The two AGFX barrier APIs map onto that split: state transitions are cross-encoder, UAV barriers are intra-encoder. Pick by where the producer and consumer actually live, not by which call is more convenient.

Ownership

Owns:

• agfxFenceCreate/Destroy/Wait/Signal/GetCompletedValue
• agfxCommandQueueSignal/agfxCommandQueueWait (GPU-side queue signal/wait)
• Frames-in-flight pacing pattern (per-slot fence values, kFramesInFlight)
• agfxCommandBufferTextureBarrier/agfxCommandBufferMemoryBarrier and the agglomerate flag's Metal-vs-everyone-else semantics
• agfxComputePassTextureUAVBarrier/agfxComputePassBufferUAVBarrier (UAV read/write hazard barriers within a compute pass)
• The "drain the GPU before destroying/recreating a resource still referenced by in-flight work" rule

Doesn't own:

• Swap chain acquire/present call sequence itself → agfx-presentation-and-swapchain
• Render pass attachment state requirements (which states attachments must be in before agfxRenderPassBegin) → agfx-render-targets-and-passes (though the barriers to reach those states are documented here)
• agfxCommandBufferAliasingBarrier, placement heaps, and resource creation/residency/destruction → agfx-resources (the aliasing barrier obeys every rule here, including agglomerate, but is meaningless outside a heap)

References

Read agfx/agfx.h's agfxCommandBufferTextureBarrier doc comment carefully — it's the authoritative explanation of agglomerate. agfx_demo/agfx_demo_main.cpp's drainGPU lambda and per-frame fence-slot logic is the reference frame-pacing implementation; deferred_renderer.cpp shows barrier usage across a full G-buffer/SSAO/shadow/lighting pipeline.

Design Patterns

Frames-in-flight pacing

Don't block on every frame — only block when about to reuse a command-buffer slot whose GPU work may still be in flight:

agfxCommandBuffer* commandBuffers[kFramesInFlight];
agfxFence* frameFence = agfxFenceCreate(device);
uint64_t fenceValue = 0;
uint64_t slotFenceValues[kFramesInFlight] = {};

// Each frame:
uint32_t frameSlot = (uint32_t)(frameIndex % kFramesInFlight);
agfxFenceWait(frameFence, slotFenceValues[frameSlot], UINT64_MAX); // block only if that slot hasn't finished
agfxCommandBufferReset(commandBuffers[frameSlot]);
agfxCommandBufferBegin(commandBuffers[frameSlot]);
// ... record + submit ...
agfxCommandQueueSubmit(queue, &commandBuffers[frameSlot], 1);
agfxSwapChainPresent(swapChain);

slotFenceValues[frameSlot] = ++fenceValue;
agfxCommandQueueSignal(queue, frameFence, fenceValue); // GPU signals this value once this frame's work completes
frameIndex++;

Every agfxCommandQueueSignal call must use a fresh monotonically increasing value — reusing a value (or signaling out of order) means a later wait can be satisfied by an earlier, unrelated signal.

Draining the GPU before destructive operations

Any operation that destroys or recreates a resource an in-flight (submitted but not yet completed) command buffer might still reference — swap chain resize, HDR toggle, shared G-buffer/depth target resize — must fully drain first:

auto drainGPU = [&]() {
    agfxCommandQueueSignal(queue, frameFence, ++fenceValue);
    agfxFenceWait(frameFence, fenceValue, UINT64_MAX);
};

// Before: swap chain resize, swap chain recreation (HDR toggle), shared render target resize
drainGPU();
agfxSwapChainResize(device, swapChain, newWidth, newHeight);

Skipping this drain is a use-after-free/GPU-fault waiting to happen: the old resource can be destroyed while a previously-submitted, still-executing command buffer references it.

The agglomerate barrier flag

agfxCommandBufferTextureBarrier/agfxCommandBufferMemoryBarrier take an agglomerate bool with backend-divergent meaning:

• Metal: no per-resource hazard tracking exists. agglomerate = true merges this transition's producer/consumer stages into a single pending barrier, flushed automatically at the start of the next agfxComputePassBegin/agfxRenderPassBegin — or immediately, if a pass is already open when the call is made. agglomerate = false is a no-op on Metal — the barrier is silently dropped, not emitted some other way.
• D3D12 / Vulkan: the flag is ignored entirely; the transition is always emitted immediately regardless of its value (an Enhanced Barrier on D3D12, a vkCmdPipelineBarrier2 on Vulkan).

Rule of thumb:

• Ordinary resource transitions (e.g. depth texture from PIXEL_SHADER_RESOURCE to DEPTH_WRITE before a shadow pass) → pass true, so Metal actually tracks the hazard.
• Swap chain PRESENT↔RENDER_TARGET transitions around acquire/present → pass false. Presentable drawables need no explicit barrier on Metal (the display server/compositor handles it), but D3D12 and Vulkan still require the transition (on Vulkan it's a real layout transition to/from PRESENT_SRC_KHR), which happens unconditionally regardless of the flag — see agfx-presentation-and-swapchain.

// Ordinary transition: track the hazard on Metal
agfxCommandBufferTextureBarrier(cmd, depthTexture, AGFX_RESOURCE_STATE_PIXEL_SHADER_RESOURCE, AGFX_RESOURCE_STATE_DEPTH_WRITE, 0, 0, /*agglomerate=*/true);

// Present-adjacent transition: no-op on Metal, unconditional on D3D12/Vulkan
agfxCommandBufferTextureBarrier(cmd, backBuffer, AGFX_RESOURCE_STATE_PRESENT, AGFX_RESOURCE_STATE_RENDER_TARGET, 0, 0, /*agglomerate=*/false);

Both agfxRenderPassBegin and agfxComputePassBegin flush any pending agglomerated barriers automatically — you don't need (and can't) manually flush them. Calling a transition barrier while a pass is already open also works: the backend flushes it inline against the open encoder. This is what makes a mid-pass transition (e.g. a copy into a buffer, then a dispatch that reads it, both inside one compute pass) actually order correctly.

Transitions out of a read-only state are real barriers. A PIXEL_SHADER_RESOURCE → UNORDERED_ACCESS or INDIRECT_ARGUMENT → UNORDERED_ACCESS transition is a write-after-read hazard: the readers must finish before the new writer starts. The backend derives the "wait for" stages from whoever read the resource when the old state writes nothing (and symmetrically, the "must wait" stages from whoever writes when the new state only writes, e.g. RENDER_TARGET). Don't skip these on the assumption that "nothing wrote it, so there's nothing to synchronize" — that reasoning is what leaves a GPU-driven pass overwriting buffers the previous frame is still reading.