Structures

VkHostImageLayoutTransitionInfoEXT

Structure specifying the parameters of a host-side image layout transition

The VkHostImageLayoutTransitionInfoEXT structure is defined as:

typedef struct VkHostImageLayoutTransitionInfoEXT {
    VkStructureType sType;
    const void* pNext;
    VkImage image;
    VkImageLayout oldLayout;
    VkImageLayout newLayout;
    VkImageSubresourceRange subresourceRange;
} VkHostImageLayoutTransitionInfoEXT;
  • sType is a VkStructureType value identifying this structure.
  • pNext is NULL or a pointer to a structure extending this structure.
  • image is a handle to the image affected by this layout transition.
  • oldLayout is the old layout in an image layout transition.
  • newLayout is the new layout in an image layout transition.
  • subresourceRange describes the image subresource range within image that is affected by this layout transition.

vkTransitionImageLayoutEXT does not check whether the device memory associated with an image is currently in use before performing the layout transition. The application must guarantee that any previously submitted command that reads from or writes to this subresource has completed before the host performs the layout transition. The memory of image is accessed by the host as if coherent.

Image layout transitions performed on the host do not require queue family ownership transfers as the physical layout of the image will not vary between queue families for the layouts supported by this function.

If the device has written to the image memory, it is not automatically made available to the host. Before this command can be called, a memory barrier for this image must have been issued on the device with the second synchronization scope including VK_PIPELINE_STAGE_HOST_BIT and VK_ACCESS_HOST_READ_BIT.

Because queue submissions automatically make host memory visible to the device, there would not be a need for a memory barrier before using the results of this layout transition on the device.

Valid Usage

VUID-VkHostImageLayoutTransitionInfoEXT-image-09055

image must have been created with VK_IMAGE_USAGE_HOST_TRANSFER_BIT_EXT

VUID-VkHostImageLayoutTransitionInfoEXT-subresourceRange-01486

subresourceRange.baseMipLevel must be less than the mipLevels specified in VkImageCreateInfo when image was created

VUID-VkHostImageLayoutTransitionInfoEXT-subresourceRange-01724

If subresourceRange.levelCount is not VK_REMAINING_MIP_LEVELS, subresourceRange.baseMipLevel + subresourceRange.levelCount must be less than or equal to the mipLevels specified in VkImageCreateInfo when image was created

VUID-VkHostImageLayoutTransitionInfoEXT-subresourceRange-01488

subresourceRange.baseArrayLayer must be less than the arrayLayers specified in VkImageCreateInfo when image was created

VUID-VkHostImageLayoutTransitionInfoEXT-subresourceRange-01725

If subresourceRange.layerCount is not VK_REMAINING_ARRAY_LAYERS, subresourceRange.baseArrayLayer + subresourceRange.layerCount must be less than or equal to the arrayLayers specified in VkImageCreateInfo when image was created

VUID-VkHostImageLayoutTransitionInfoEXT-image-01932

If image is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

VUID-VkHostImageLayoutTransitionInfoEXT-image-09241

If image has a color format that is single-plane, then the aspectMask member of subresourceRange must be VK_IMAGE_ASPECT_COLOR_BIT

VUID-VkHostImageLayoutTransitionInfoEXT-image-09242

If image has a color format and is not disjoint, then the aspectMask member of subresourceRange must be VK_IMAGE_ASPECT_COLOR_BIT

VUID-VkHostImageLayoutTransitionInfoEXT-image-01672

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 VK_IMAGE_ASPECT_COLOR_BIT

VUID-VkHostImageLayoutTransitionInfoEXT-image-03320

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 VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT

VUID-VkHostImageLayoutTransitionInfoEXT-image-03319

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 VK_IMAGE_ASPECT_DEPTH_BIT and VK_IMAGE_ASPECT_STENCIL_BIT

VUID-VkHostImageLayoutTransitionInfoEXT-aspectMask-08702

If the aspectMask member of subresourceRange includes VK_IMAGE_ASPECT_DEPTH_BIT, oldLayout and newLayoutmust not be one of VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

VUID-VkHostImageLayoutTransitionInfoEXT-aspectMask-08703

If the aspectMask member of subresourceRange includes VK_IMAGE_ASPECT_STENCIL_BIT, oldLayout and newLayoutmust not be one of VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

VUID-VkHostImageLayoutTransitionInfoEXT-subresourceRange-09601

subresourceRange.aspectMask must be valid for the format the image was created with

VUID-VkHostImageLayoutTransitionInfoEXT-oldLayout-09229

oldLayout must be either VK_IMAGE_LAYOUT_UNDEFINED or the current layout of the image subresources as specified in subresourceRange

VUID-VkHostImageLayoutTransitionInfoEXT-oldLayout-09230

If oldLayout is not VK_IMAGE_LAYOUT_UNDEFINED or VK_IMAGE_LAYOUT_PREINITIALIZED, it must be one of the layouts in VkPhysicalDeviceHostImageCopyPropertiesEXT::pCopySrcLayouts