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