Vulkan Swapchain Image Barriers: Explicit Layout Transitions That Work

Start with the decision that removes the failure

If you render into a swapchain image and then present it, record two explicit pipeline barriers. Transition the acquired image from VK_IMAGE_LAYOUT_UNDEFINED to VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL before color writes, and from VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL to VK_IMAGE_LAYOUT_PRESENT_SRC_KHR after the last write. Do not rely on implicit layout transitions unless a render pass explicitly owns them with initialLayout and finalLayout.

This article assumes core Vulkan 1.0 APIs plus VK_KHR_swapchain. Vulkan 1.3 adds vkCmdPipelineBarrier2 and VkImageMemoryBarrier2, but the layout and access concepts are the same.

Why the barrier is required

A Vulkan image has a layout, but the layout is only a contract about how the driver and GPU may interpret the memory. Rendering as a color attachment and presenting as a source image are different contracts. A pipeline barrier changes the contract and makes prior writes available to later stages.

The barrier has two halves. The stage mask says which earlier GPU stages must finish and which later stages must wait. The access mask says which memory accesses must be made visible. If either half is wrong, the driver may reorder or hide work incorrectly, and validation layers will usually complain.

Barriers execute on the GPU timeline inside a command buffer. They do not stall the CPU. Queue submission order, semaphores, and fences remain your responsibility.

Worked configuration

The example below uses one swapchain image, one mip level, and one array layer. Replace swapchainImage with the image handle returned by vkAcquireNextImageKHR for the current frame.

Before rendering

VkImageMemoryBarrier toColor = {
    .sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER,
    .pNext = NULL,
    .srcAccessMask = 0,
    .dstAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT,
    .oldLayout = VK_IMAGE_LAYOUT_UNDEFINED,
    .newLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
    .srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED,
    .dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED,
    .image = swapchainImage,
    .subresourceRange = {
        .aspectMask = VK_IMAGE_ASPECT_COLOR_BIT,
        .baseMipLevel = 0,
        .levelCount = 1,
        .baseArrayLayer = 0,
        .layerCount = 1
    }
};

vkCmdPipelineBarrier(
    cmd,
    VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT,
    VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT,
    0,
    0, NULL,
    0, NULL,
    1,
    &toColor
);

Use VK_IMAGE_LAYOUT_UNDEFINED only when you will overwrite every pixel. If you must preserve previous contents, use the actual previous layout or VK_IMAGE_LAYOUT_PREINITIALIZED and set srcAccessMask to the accesses that produced those contents.

After rendering, before present

VkImageMemoryBarrier toPresent = {
    .sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER,
    .pNext = NULL,
    .srcAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT,
    .dstAccessMask = 0,
    .oldLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL,
    .newLayout = VK_IMAGE_LAYOUT_PRESENT_SRC_KHR,
    .srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED,
    .dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED,
    .image = swapchainImage,
    .subresourceRange = {
        .aspectMask = VK_IMAGE_ASPECT_COLOR_BIT,
        .baseMipLevel = 0,
        .levelCount = 1,
        .baseArrayLayer = 0,
        .layerCount = 1
    }
};

vkCmdPipelineBarrier(
    cmd,
    VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT,
    VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT,
    0,
    0, NULL,
    0, NULL,
    1,
    &toPresent
);

The present transition uses dstAccessMask = 0 because the next consumer is the presentation engine, not a Vulkan pipeline stage. The barrier still makes the color writes available before the submit that calls vkQueuePresentKHR.

Implicit render pass transitions versus explicit barriers

Approach	Best fit	Main limitation
Render pass initialLayout and finalLayout	One render pass that begins and ends with the needed layouts	Does not cover reads or writes outside the render pass, or transitions between passes
Explicit vkCmdPipelineBarrier	Dynamic rendering, compute, copies, multiple passes, cross-queue ownership	Easy to mismatch stage and access masks; too many calls can create GPU bubbles

Limits and common mistakes

• Mismatched masks. A common error is using VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT to VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT for every transition. It may appear to work while destroying parallelism. Use the narrowest stages that match the real work.
• Discarding data with UNDEFINED. oldLayout = VK_IMAGE_LAYOUT_UNDEFINED tells the implementation the previous contents do not matter. For a swapchain image you usually overwrite it, but for a texture or offscreen target this can silently drop data.
• Wrong aspectMask. Color images need VK_IMAGE_ASPECT_COLOR_BIT. Depth/stencil images need the depth and stencil aspects that actually exist. Missing the stencil aspect can leave that plane in the wrong layout.
• Unbound memory. An image barrier requires the image to be bound with vkBindImageMemory and created with usage that includes the intended access. A barrier does not allocate memory or fix missing usage flags.
• Too many barriers. One vkCmdPipelineBarrier call can carry an array of image barriers, but all barriers in that call share the same source and destination stage masks. Batch only barriers with compatible masks and queue-family semantics.
• Cross-queue assumptions. If the graphics queue and present queue are different queue families, set srcQueueFamilyIndex and dstQueueFamilyIndex for ownership release and acquire, and still use a semaphore so the destination queue waits for the source queue submit. If both queues are the same family, VK_QUEUE_FAMILY_IGNORED is correct.
• Assuming a barrier is a fence. It orders GPU work inside a queue. It does not make the CPU wait and does not replace vkQueueWaitIdle, fences, or semaphores.

How to check the result

Enable the Khronos validation layer by including VK_LAYER_KHRONOS_validation in VkInstanceCreateInfo before device creation. Run the application normally; no elevated permissions are required. Look for synchronization validation messages, layout mismatch warnings, and access mask warnings. If the layer is not visible to the loader, verify the implicit layer path for your Vulkan installation.

For a frame-level check, launch the application under RenderDoc from your desktop session, capture one frame, and inspect the image resource state at barrier events. Confirm the swapchain image is in COLOR_ATTACHMENT_OPTIMAL during rendering and transitions to PRESENT_SRC_KHR before the present submit. RenderDoc changes timing, so use it to inspect state rather than to judge performance.

Finally, test on GPUs from more than one vendor. Tiled and untiled memory architectures can expose different costs for barrier placement even when the API usage is valid.

If a barrier is wrong, there is no runtime undo for an already submitted command buffer. Correct the masks or layout, re-record the command buffer, and submit again.