VkHostImageLayoutTransitionInfoEXT(3)

# VkHostImageLayoutTransitionInfoEXT(3) Manual Page

## Name

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

Loading… please wait.

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

SPDX-License-Identifier: CC-BY-4.0