VkHostImageLayoutTransitionInfo(3)

# VkHostImageLayoutTransitionInfo(3) Manual Page

## Name

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

## C Specification

The `VkHostImageLayoutTransitionInfo` structure is defined as:

    // Provided by VK_VERSION_1_4
    typedef struct VkHostImageLayoutTransitionInfo {
        VkStructureType            sType;
        const void*                pNext;
        VkImage                    image;
        VkImageLayout              oldLayout;
        VkImageLayout              newLayout;
        VkImageSubresourceRange    subresourceRange;
    } VkHostImageLayoutTransitionInfo;

    // Provided by VK_EXT_host_image_copy
    // Equivalent to VkHostImageLayoutTransitionInfo
    typedef VkHostImageLayoutTransitionInfo VkHostImageLayoutTransitionInfoEXT;

## Members

- `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.

## Description

`vkTransitionImageLayout` 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.

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 | 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.

Note | 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-VkHostImageLayoutTransitionInfo-image-09055
  `image` must have been created with the VK_IMAGE_USAGE_HOST_TRANSFER_BIT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-subresourceRange-01486
  `subresourceRange.baseMipLevel` must be less than the `mipLevels` specified in VkImageCreateInfo when `image` was created

- VUID-VkHostImageLayoutTransitionInfo-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-VkHostImageLayoutTransitionInfo-subresourceRange-01488
  If `image` is not a 3D image or was created without VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or the `maintenance9` feature is not enabled, `subresourceRange.baseArrayLayer` must be less than the `arrayLayers` specified in VkImageCreateInfo when `image` was created

- VUID-VkHostImageLayoutTransitionInfo-maintenance9-10798
  If the `maintenance9` feature is enabled and `image` is a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, `subresourceRange.baseArrayLayer` must be less than the depth computed from `baseMipLevel` and `extent.depth` specified in VkImageCreateInfo when `image` was created, according to the formula defined in Image Mip Level Sizing

- VUID-VkHostImageLayoutTransitionInfo-maintenance9-10799
  If the `maintenance9` feature is enabled and `image` is a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set and either `subresourceRange.baseArrayLayer` is not equal to 0 or `subresourceRange.layerCount` is not equal to VK_REMAINING_ARRAY_LAYERS, `subresourceRange.levelCount` must be 1

- VUID-VkHostImageLayoutTransitionInfo-subresourceRange-01725
  If `image` is not a 3D image or was created without VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or the `maintenance9` feature is not enabled, and `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-VkHostImageLayoutTransitionInfo-maintenance9-10800
  If the `maintenance9` feature is enabled, `subresourceRange.layerCount` is not VK_REMAINING_ARRAY_LAYERS, and `image` is a 3D image created with VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, `subresourceRange.baseArrayLayer` + `subresourceRange.layerCount` must be less than or equal to the depth computed from `baseMipLevel` and `extent.depth` specified in VkImageCreateInfo when `image` was created, according to the formula defined in Image Mip Level Sizing

- VUID-VkHostImageLayoutTransitionInfo-image-01932
  If `image` is non-sparse then the image or each specified disjoint plane must be bound completely and contiguously to a single `VkDeviceMemory` object

- VUID-VkHostImageLayoutTransitionInfo-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-VkHostImageLayoutTransitionInfo-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-VkHostImageLayoutTransitionInfo-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-VkHostImageLayoutTransitionInfo-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-VkHostImageLayoutTransitionInfo-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-VkHostImageLayoutTransitionInfo-image-10749
  If `image` has a depth-only format then the `aspectMask` member of `subresourceRange` must be VK_IMAGE_ASPECT_DEPTH_BIT

- VUID-VkHostImageLayoutTransitionInfo-image-10750
  If `image` has a stencil-only format then the `aspectMask` member of `subresourceRange` must be VK_IMAGE_ASPECT_STENCIL_BIT

- VUID-VkHostImageLayoutTransitionInfo-aspectMask-08702
  If the `aspectMask` member of `subresourceRange` includes VK_IMAGE_ASPECT_DEPTH_BIT, `oldLayout` and `newLayout` must not be one of VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL

- VUID-VkHostImageLayoutTransitionInfo-aspectMask-08703
  If the `aspectMask` member of `subresourceRange` includes VK_IMAGE_ASPECT_STENCIL_BIT, `oldLayout` and `newLayout` must not be one of VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL

- VUID-VkHostImageLayoutTransitionInfo-subresourceRange-09601
  `subresourceRange.aspectMask` must be valid for the `format` the `image` was created with

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-01208
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then `image` must have been created with the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-01209
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL then `image` must have been created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-01210
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then `image` must have been created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-01211
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then `image` must have been created with the VK_IMAGE_USAGE_SAMPLED_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-01212
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then `image` must have been created with the VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-01213
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then `image` must have been created with the VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-10767
  If the zeroInitializeDeviceMemory feature is not enabled, `oldLayout` must not be VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-10768
  If `oldLayout` is VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT, then all subresources must be included in the barrier

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-01658
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL then `image` must have been created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-01659
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL then `image` must have been created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-04065
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL then `image` must have been created with at least one of the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_SAMPLED_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage flags set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-04066
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL then `image` must have been created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-04067
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL then `image` must have been created with at least one of the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_SAMPLED_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage flags set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-04068
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL then `image` must have been created with the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-synchronization2-07793
  If the `synchronization2` feature is not enabled, `oldLayout` must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

- VUID-VkHostImageLayoutTransitionInfo-synchronization2-07794
  If the `synchronization2` feature is not enabled, `newLayout` must not be VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR or VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-03938
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL, `image` must have been created with the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-03939
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL, `image` must have been created with at least one of the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, VK_IMAGE_USAGE_SAMPLED_BIT, or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage flags set

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-02088
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR then `image` must have been created with the VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR usage flag set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-07120
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR then `image` must have been created with the VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR usage flag set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-07121
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR then `image` must have been created with the VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR usage flag set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-07122
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR then `image` must have been created with the VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR usage flag set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-07123
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR then `image` must have been created with the VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR usage flag set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-07124
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR then `image` must have been created with the VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR usage flag set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-07125
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR then `image` must have been created with the VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR usage flag set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-10287
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_VIDEO_ENCODE_QUANTIZATION_MAP_KHR then `image` must have been created with the VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR or VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR usage flags set

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-07006
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT then `image` must have been created with either the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage flags set, and the VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT or VK_IMAGE_USAGE_SAMPLED_BIT usage flags set, and the VK_IMAGE_USAGE_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT usage flag set

- VUID-VkHostImageLayoutTransitionInfo-attachmentFeedbackLoopLayout-07313
  If the `attachmentFeedbackLoopLayout` feature is not enabled, `newLayout` must not be VK_IMAGE_LAYOUT_ATTACHMENT_FEEDBACK_LOOP_OPTIMAL_EXT

- VUID-VkHostImageLayoutTransitionInfo-srcQueueFamilyIndex-09550
  If `oldLayout` or `newLayout` is VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ then `image` must have been created with either the VK_IMAGE_USAGE_STORAGE_BIT usage flag set, or with both the VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage flag and either of the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT or VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage flags set

- VUID-VkHostImageLayoutTransitionInfo-dynamicRenderingLocalRead-09551
  If the `dynamicRenderingLocalRead` feature is not enabled, `oldLayout` must not be VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ

- VUID-VkHostImageLayoutTransitionInfo-dynamicRenderingLocalRead-09552
  If the `dynamicRenderingLocalRead` feature is not enabled, `newLayout` must not be VK_IMAGE_LAYOUT_RENDERING_LOCAL_READ

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-09229
  `oldLayout` must be either VK_IMAGE_LAYOUT_UNDEFINED or the current layout of the image subresources as specified in `subresourceRange`

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-09230
  If `oldLayout` is not VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_ZERO_INITIALIZED_EXT, or VK_IMAGE_LAYOUT_PREINITIALIZED, it must be one of the layouts in VkPhysicalDeviceHostImageCopyProperties::`pCopySrcLayouts`

- VUID-VkHostImageLayoutTransitionInfo-newLayout-09057
  `newLayout` must be one of the layouts in VkPhysicalDeviceHostImageCopyProperties::`pCopyDstLayouts`

Valid Usage (Implicit)

- VUID-VkHostImageLayoutTransitionInfo-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO

- VUID-VkHostImageLayoutTransitionInfo-pNext-pNext
  `pNext` must be `NULL`

- VUID-VkHostImageLayoutTransitionInfo-image-parameter
  `image` must be a valid VkImage handle

- VUID-VkHostImageLayoutTransitionInfo-oldLayout-parameter
  `oldLayout` must be a valid VkImageLayout value

- VUID-VkHostImageLayoutTransitionInfo-newLayout-parameter
  `newLayout` must be a valid VkImageLayout value

- VUID-VkHostImageLayoutTransitionInfo-subresourceRange-parameter
  `subresourceRange` must be a valid VkImageSubresourceRange structure

## See Also

VK_EXT_host_image_copy, VK_VERSION_1_4, VkImage, VkImageLayout, VkImageSubresourceRange, VkStructureType, vkTransitionImageLayout, vkTransitionImageLayout

## 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