Structure specifying the parameters of an image memory barrier.

Description

The first access scope is limited to access to memory through the specified image subresource range, via access types in the source access mask specified by srcAccessMask. If srcAccessMask includes ACCESS_HOST_WRITE_BIT, memory writes performed by that access type are also made visible, as that access type is not performed through a resource.

The second access scope is limited to access to memory through the specified image subresource range, via access types in the destination access mask specified by dstAccessMask. If dstAccessMask includes ACCESS_HOST_WRITE_BIT or ACCESS_HOST_READ_BIT, available memory writes are also made visible to accesses of those types, as those access types are not performed through a resource.

If srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, and srcQueueFamilyIndex is equal to the current queue family, then the memory barrier defines a queue family release operation for the specified image subresource range, and the second access scope includes no access, as if dstAccessMask was 0.

If dstQueueFamilyIndex is not equal to srcQueueFamilyIndex, and dstQueueFamilyIndex is equal to the current queue family, then the memory barrier defines a queue family acquire operation for the specified image subresource range, and the first access scope includes no access, as if srcAccessMask was 0.

If the synchronization2 feature is not enabled or oldLayout is not equal to newLayout, oldLayout and newLayout define an image layout transition for the specified image subresource range.

If image has a multi-planar format and the image is disjoint, then including IMAGE_ASPECT_COLOR_BIT in the aspectMask member of subresourceRange is equivalent to including IMAGE_ASPECT_PLANE_0_BIT, IMAGE_ASPECT_PLANE_1_BIT, and (for three-plane formats only) IMAGE_ASPECT_PLANE_2_BIT.

Valid Usage

• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then image must have been created with IMAGE_USAGE_COLOR_ATTACHMENT_BIT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL then image must have been created with IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then image must have been created with IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then image must have been created with IMAGE_USAGE_SAMPLED_BIT or IMAGE_USAGE_INPUT_ATTACHMENT_BIT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then image must have been created with IMAGE_USAGE_TRANSFER_SRC_BIT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then image must have been created with IMAGE_USAGE_TRANSFER_DST_BIT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, oldLayout must be IMAGE_LAYOUT_UNDEFINED or the current layout of the image subresources affected by the barrier
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, newLayout must not be IMAGE_LAYOUT_UNDEFINED or IMAGE_LAYOUT_PREINITIALIZED
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL then image must have been created with IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL then image must have been created with IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL then image must have been created with at least one of IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, IMAGE_USAGE_SAMPLED_BIT, or IMAGE_USAGE_INPUT_ATTACHMENT_BIT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL then image must have been created with IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then image must have been created with at least one of IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, IMAGE_USAGE_SAMPLED_BIT, or IMAGE_USAGE_INPUT_ATTACHMENT_BIT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL then image must have been created with IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set
• If the synchronization2 feature is not enabled, oldLayout must not be IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR
• If the synchronization2 feature is not enabled, newLayout must not be IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_ATTACHMENT_OPTIMAL, image must have been created with IMAGE_USAGE_COLOR_ATTACHMENT_BIT or IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_READ_ONLY_OPTIMAL, image must have been created with at least one of IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, IMAGE_USAGE_SAMPLED_BIT, or IMAGE_USAGE_INPUT_ATTACHMENT_BIT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR then image must have been created with IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR set
• If image was created with a sharing mode of SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex and dstQueueFamilyIndex are not equal, srcQueueFamilyIndex must be QUEUE_FAMILY_EXTERNAL, QUEUE_FAMILY_FOREIGN_EXT, or a valid queue family
• If image was created with a sharing mode of SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex and dstQueueFamilyIndex are not equal, dstQueueFamilyIndex must be QUEUE_FAMILY_EXTERNAL, QUEUE_FAMILY_FOREIGN_EXT, or a valid queue family
• If srcQueueFamilyIndex is not equal to dstQueueFamilyIndex, at least one of srcQueueFamilyIndex or dstQueueFamilyIndex must not be QUEUE_FAMILY_EXTERNAL or QUEUE_FAMILY_FOREIGN_EXT
• If the VK_KHR_external_memory extension is not enabled, and the value of VkApplicationInfo::apiVersion used to create the VkInstance is not greater than or equal to Version 1.1, srcQueueFamilyIndex must not be QUEUE_FAMILY_EXTERNAL
• If the VK_KHR_external_memory extension is not enabled, and the value of VkApplicationInfo::apiVersion used to create the VkInstance is not greater than or equal to Version 1.1, dstQueueFamilyIndex must not be QUEUE_FAMILY_EXTERNAL
• If the VK_EXT_queue_family_foreign extension is not enabled srcQueueFamilyIndex must not be QUEUE_FAMILY_FOREIGN_EXT
• If the VK_EXT_queue_family_foreign extension is not enabled dstQueueFamilyIndex must not be QUEUE_FAMILY_FOREIGN_EXT
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR then image must have been created with IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR then image must have been created with IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR then image must have been created with IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR then image must have been created with IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR then image must have been created with IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR then image must have been created with IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR
• If srcQueueFamilyIndex and dstQueueFamilyIndex define a queue family ownership transfer or oldLayout and newLayout define an image layout transition, and oldLayout or newLayout is IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT then image must have been created with either the IMAGE_USAGE_COLOR_ATTACHMENT_BIT or IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bits, and the IMAGE_USAGE_INPUT_ATTACHMENT_BIT or IMAGE_USAGE_SAMPLED_BIT usage bits, and the IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT usage bit
• If the attachmentFeedbackLoopLayout feature is not enabled, newLayout must not be IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

• subresourceRange.baseMipLevel must be less than the mipLevels specified in VkImageCreateInfo when image was created
• If subresourceRange.levelCount is not REMAINING_MIP_LEVELS, subresourceRange.baseMipLevel + subresourceRange.levelCount must be less than or equal to the mipLevels specified in VkImageCreateInfo when image was created
• subresourceRange.baseArrayLayer must be less than the arrayLayers specified in VkImageCreateInfo when image was created
• If subresourceRange.layerCount is not REMAINING_ARRAY_LAYERS, subresourceRange.baseArrayLayer + subresourceRange.layerCount must be less than or equal to the arrayLayers specified in VkImageCreateInfo when image was created
• If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object
• If image has a color format that is single-plane, then the aspectMask member of subresourceRange must be IMAGE_ASPECT_COLOR_BIT
• If image has a color format and is not disjoint, then the aspectMask member of subresourceRange must be IMAGE_ASPECT_COLOR_BIT
• If image has a multi-planar format and the image is disjoint, then the aspectMask member of subresourceRange must include at least one multi-planar aspect mask bit or IMAGE_ASPECT_COLOR_BIT
• If image has a depth/stencil format with both depth and stencil and the separateDepthStencilLayouts feature is enabled, then the aspectMask member of subresourceRange must include either or both IMAGE_ASPECT_DEPTH_BIT and IMAGE_ASPECT_STENCIL_BIT
• If image has a depth/stencil format with both depth and stencil and the separateDepthStencilLayouts feature is not enabled, then the aspectMask member of subresourceRange must include both IMAGE_ASPECT_DEPTH_BIT and IMAGE_ASPECT_STENCIL_BIT
• If the aspectMask member of subresourceRange includes IMAGE_ASPECT_DEPTH_BIT, oldLayout and newLayout must not be one of IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
• If the aspectMask member of subresourceRange includes IMAGE_ASPECT_STENCIL_BIT, oldLayout and newLayout must not be one of IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL
• If the synchronization2 feature is not enabled, and image was created with a sharing mode of SHARING_MODE_CONCURRENT, at least one of srcQueueFamilyIndex and dstQueueFamilyIndex must be QUEUE_FAMILY_IGNORED
• If the synchronization2 feature is not enabled, and image was created with a sharing mode of SHARING_MODE_CONCURRENT, srcQueueFamilyIndex must be QUEUE_FAMILY_IGNORED or QUEUE_FAMILY_EXTERNAL
• If the synchronization2 feature is not enabled, and image was created with a sharing mode of SHARING_MODE_CONCURRENT, dstQueueFamilyIndex must be QUEUE_FAMILY_IGNORED or QUEUE_FAMILY_EXTERNAL

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER
• 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 or VkSampleLocationsInfoEXT
• The sType value of each struct in the pNext chain must be unique
• oldLayout must be a valid VkImageLayout value
• newLayout must be a valid VkImageLayout value
• image must be a valid VkImage handle
• subresourceRange must be a valid VkImageSubresourceRange structure

See Also

VkImageSubresourceRange, CmdPipelineBarrier, CmdWaitEvents

Layout

struct VkImageMemoryBarrier {
    VkStructureType sType;
    void const * pNext;
    VkAccessFlags srcAccessMask;
    VkAccessFlags dstAccessMask;
    VkImageLayout oldLayout;
    VkImageLayout newLayout;
    uint32_t srcQueueFamilyIndex;
    uint32_t dstQueueFamilyIndex;
    VkImage image;
    VkImageSubresourceRange subresourceRange;
}