VKIMAGEMEMORYBARRIER(3)

NAME
VkImageMemoryBarrier - Structure specifying the parameters of an image memory barrier

C SPECIFICATION

The VkImageMemoryBarrier structure is defined as:

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

MEMBERS

    • sType is the type of this structure.

    • pNext is NULL or a pointer to an extension-specific structure.

    • srcAccessMask is a bitmask of the classes of memory accesses performed by the first set of commands that will participate in the dependency.

    • dstAccessMask is a bitmask of the classes of memory accesses performed by the second set of commands that will participate in the dependency.

    • oldLayout describes the current layout of the image subresource(s).

    • newLayout describes the new layout of the image subresource(s).

    • srcQueueFamilyIndex is the queue family that is relinquishing ownership of the image subresource(s) to another queue, or VK_QUEUE_FAMILY_IGNORED if there is no transfer of ownership).

    • dstQueueFamilyIndex is the queue family that is acquiring ownership of the image subresource(s) from another queue, or VK_QUEUE_FAMILY_IGNORED if there is no transfer of ownership).

    • image is a handle to the image whose backing memory is affected by the barrier.

    • subresourceRange describes an area of the backing memory for image (see ??? for the description of VkImageSubresourceRange), as well as the set of image subresources whose image layouts are modified.

DESCRIPTION

If oldLayout differs from newLayout, a layout transition occurs as part of the image memory barrier, affecting the data contained in the region of the image defined by the subresourceRange. If oldLayout is VK_IMAGE_LAYOUT_UNDEFINED, then the data is undefined after the layout transition. This may allow a more efficient transition, since the data may be discarded. The layout transition must occur after all operations using the old layout are completed and before all operations using the new layout are started. This is achieved by ensuring that there is a memory dependency between previous accesses and the layout transition, as well as between the layout transition and subsequent accesses, where the layout transition occurs between the two halves of a memory dependency in an image memory barrier.

Layout transitions that are performed via image memory barriers are automatically ordered against other layout transitions, including those that occur as part of a render pass instance.

    Note

    See ??? for details on available image layouts and their usages.

Valid Usage

    • oldLayout must be VK_IMAGE_LAYOUT_UNDEFINED or the current layout of the image subresources affected by the barrier

    • newLayout must not be VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED

    • If image was created with a sharing mode of VK_SHARING_MODE_CONCURRENT, srcQueueFamilyIndex and dstQueueFamilyIndex must both be VK_QUEUE_FAMILY_IGNORED

    • If image was created with a sharing mode of VK_SHARING_MODE_EXCLUSIVE, srcQueueFamilyIndex and dstQueueFamilyIndex must either both be VK_QUEUE_FAMILY_IGNORED, or both be a valid queue family (see ???)

    • If image was created with a sharing mode of VK_SHARING_MODE_EXCLUSIVE, and srcQueueFamilyIndex and dstQueueFamilyIndex are valid queue families, at least one of them must be the same as the family of the queue that will execute this barrier

    • subresourceRange must be a valid image subresource range for the image (see ???)

    • If image has a depth/stencil format with both depth and stencil components, then aspectMask member of subresourceRange must include both VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT

    • If either oldLayout or newLayout is VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then image must have been created with VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT set

    • If either oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set

    • If either oldLayout or newLayout is VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then image must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set

    • If either oldLayout or newLayout is VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then image must have been created with VK_IMAGE_USAGE_SAMPLED_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set

    • If either oldLayout or newLayout is VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then image must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT set

    • If either oldLayout or newLayout is VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then image must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT set
Valid Usage (Implicit)

    • sType must be VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER

    • pNext must be NULL

    • srcAccessMask must be a valid combination of VkAccessFlagBits values

    • dstAccessMask must be a valid combination of VkAccessFlagBits values

    • 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

VkAccessFlags, VkImage, VkImageLayout, VkImageSubresourceRange, VkStructureType, vkCmdPipelineBarrier, vkCmdWaitEvents

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#VkImageMemoryBarrier

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

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.