C Specification

The VkHostImageLayoutTransitionInfoEXT structure is defined as:

// Provided by VK_EXT_host_image_copy
typedef struct VkHostImageLayoutTransitionInfoEXT {
    VkStructureType            sType;
    const void*                pNext;
    VkImage                    image;
    VkImageLayout              oldLayout;
    VkImageLayout              newLayout;
    VkImageSubresourceRange    subresourceRange;
} 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

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.

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

  • VUID-VkHostImageLayoutTransitionInfoEXT-newLayout-09057
    newLayout must be one of the layouts in VkPhysicalDeviceHostImageCopyPropertiesEXT::pCopyDstLayouts

Valid Usage (Implicit)

  • VUID-VkHostImageLayoutTransitionInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_HOST_IMAGE_LAYOUT_TRANSITION_INFO_EXT

  • VUID-VkHostImageLayoutTransitionInfoEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkHostImageLayoutTransitionInfoEXT-image-parameter
    image must be a valid VkImage handle

  • VUID-VkHostImageLayoutTransitionInfoEXT-oldLayout-parameter
    oldLayout must be a valid VkImageLayout value

  • VUID-VkHostImageLayoutTransitionInfoEXT-newLayout-parameter
    newLayout must be a valid VkImageLayout value

  • VUID-VkHostImageLayoutTransitionInfoEXT-subresourceRange-parameter
    subresourceRange must be a valid VkImageSubresourceRange structure

See Also

VK_EXT_host_image_copy, VkImage, VkImageLayout, VkImageSubresourceRange, VkStructureType, vkTransitionImageLayoutEXT

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-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0