Structures

VkHostImageLayoutTransitionInfo

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

The VkHostImageLayoutTransitionInfo structure is defined as:

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

pub struct HostImageLayoutTransitionInfo {
    s_type: vk::StructureType,
    p_next: *const c_void,
    image: vk::Image,
    old_layout: vk::ImageLayout,
    new_layout: vk::ImageLayout,
    subresource_range: vk::ImageSubresourceRange,
}

typedef VkHostImageLayoutTransitionInfo VkHostImageLayoutTransitionInfoEXT;

type HostImageLayoutTransitionInfoEXT = vk::HostImageLayoutTransitionInfo;

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.

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.

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-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 newLayoutmust 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 newLayoutmust 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 imagemust 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 imagemust 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, oldLayoutmust 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 imagemust 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

VK_VERSION_1_4

Type

Structures

VkHostImageLayoutTransitionInfo

Valid Usage

Valid Usage (Implicit)