C Specification

The VkImageMemoryBarrier2 structure is defined as:

// Provided by VK_VERSION_1_3
typedef struct VkImageMemoryBarrier2 {
    VkStructureType            sType;
    const void*                pNext;
    VkPipelineStageFlags2      srcStageMask;
    VkAccessFlags2             srcAccessMask;
    VkPipelineStageFlags2      dstStageMask;
    VkAccessFlags2             dstAccessMask;
    VkImageLayout              oldLayout;
    VkImageLayout              newLayout;
    uint32_t                   srcQueueFamilyIndex;
    uint32_t                   dstQueueFamilyIndex;
    VkImage                    image;
    VkImageSubresourceRange    subresourceRange;
} VkImageMemoryBarrier2;
// Provided by VK_KHR_synchronization2
// Equivalent to VkImageMemoryBarrier2
typedef VkImageMemoryBarrier2 VkImageMemoryBarrier2KHR;

Members

Description

This structure defines a memory dependency limited to an image subresource range, and can define a queue family ownership transfer operation and image layout transition for that subresource range.

The first synchronization scope and access scope described by this structure include only operations and memory accesses specified by the source stage mask and the source access mask.

The second synchronization scope and access scope described by this structure include only operations and memory accesses specified by the destination stage mask and the destination access mask.

Both access scopes are limited to only memory accesses to image in the subresource range defined by subresourceRange.

If image was created with VK_SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, this memory barrier defines a queue family ownership transfer operation. When executed on a queue in the family identified by srcQueueFamilyIndex, this barrier defines a queue family release operation for the specified image subresource range, and if VkDependencyInfoKHR::dependencyFlags did not include VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR, the second synchronization scope does not apply to this operation. When executed on a queue in the family identified by dstQueueFamilyIndex, this barrier defines a queue family acquire operation for the specified image subresource range, and if VkDependencyInfoKHR::dependencyFlags did not include VK_DEPENDENCY_QUEUE_FAMILY_OWNERSHIP_TRANSFER_USE_ALL_STAGES_BIT_KHR, the first synchronization scope does not apply to this operation.

A queue family ownership transfer operation is also defined if the values are not equal, and either is one of the special queue family values reserved for external memory ownership transfers, as described in https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#synchronization-queue-transfers. A queue family release operation is defined when dstQueueFamilyIndex is one of those values, and a queue family acquire operation is defined when srcQueueFamilyIndex is one of those values.

If oldLayout is not equal to newLayout, then the memory barrier defines an image layout transition for the specified image subresource range. If this memory barrier defines a queue family ownership transfer operation, the layout transition is only executed once between the queues.

If srcQueueFamilyIndex and dstQueueFamilyIndex are equal and oldLayout and newLayout are also equal, the layout values are ignored and the image contents are preserved regardless of the values of oldLayout, newLayout, and the current layout of the image.

If image is a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT and the maintenance9 feature is enabled, the baseArrayLayer and layerCount members of subresourceRange specify the subset of slices of the 3D image affected by the memory barrier, including the layout transition. Any slices of a 3D image not included in subresourceRange are not affected by the memory barrier and remain in their existing layout.

Note

Enabling the maintenance9 feature modifies the behavior of image barriers targeting 3D images created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT. Previously, a layerCount equal to 1 would cover the entire 3D image, but this has a different meaning when the maintenance9 feature is enabled. Linking this behavioral change solely to the maintenance9 feature caused an unintended break in forward-compatibility. Validation layers are expected to flag a warning for the scenario where the maintenance9 feature is not enabled, and the application uses layerCount equal to 1 on this kind of 3D image. layerCount can be set to VK_REMAINING_ARRAY_LAYERS instead, which has the same semantics with or without the extension. This validation check should make it feasible for software to avoid any breaking changes should the maintenance9 feature be enabled in the future, either explicitly by application or by a layer outside the control of the application.

If image has a multi-planar format and the image is disjoint, then including VK_IMAGE_ASPECT_COLOR_BIT in the aspectMask member of subresourceRange is equivalent to including VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT, and (for three-plane formats only) VK_IMAGE_ASPECT_PLANE_2_BIT.

Valid Usage
Valid Usage (Implicit)

  • VUID-VkImageMemoryBarrier2-sType-sType
    sType must be VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2

  • VUID-VkImageMemoryBarrier2-pNext-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkExternalMemoryAcquireUnmodifiedEXT, VkMemoryBarrierAccessFlags3KHR, or VkSampleLocationsInfoEXT

  • VUID-VkImageMemoryBarrier2-sType-unique
    The sType value of each structure in the pNext chain must be unique

  • VUID-VkImageMemoryBarrier2-srcStageMask-parameter
    srcStageMask must be a valid combination of VkPipelineStageFlagBits2 values

  • VUID-VkImageMemoryBarrier2-srcAccessMask-parameter
    srcAccessMask must be a valid combination of VkAccessFlagBits2 values

  • VUID-VkImageMemoryBarrier2-dstStageMask-parameter
    dstStageMask must be a valid combination of VkPipelineStageFlagBits2 values

  • VUID-VkImageMemoryBarrier2-dstAccessMask-parameter
    dstAccessMask must be a valid combination of VkAccessFlagBits2 values

  • VUID-VkImageMemoryBarrier2-oldLayout-parameter
    oldLayout must be a valid VkImageLayout value

  • VUID-VkImageMemoryBarrier2-newLayout-parameter
    newLayout must be a valid VkImageLayout value

  • VUID-VkImageMemoryBarrier2-image-parameter
    image must be a valid VkImage handle

  • VUID-VkImageMemoryBarrier2-subresourceRange-parameter
    subresourceRange must be a valid VkImageSubresourceRange structure

See Also

VK_KHR_synchronization2, VK_VERSION_1_3, VkAccessFlags2, VkDependencyInfo, VkImage, VkImageLayout, VkImageSubresourceRange, VkPipelineStageFlags2, VkStructureType

Document Notes

For more information, see the Vulkan Specification.

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0