C Specification

To query the memory layout of an image subresource, call:

// Provided by VK_KHR_maintenance5
void vkGetImageSubresourceLayout2KHR(
    VkDevice                                    device,
    VkImage                                     image,
    const VkImageSubresource2KHR*               pSubresource,
    VkSubresourceLayout2KHR*                    pLayout);

or the equivalent command

// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
void vkGetImageSubresourceLayout2EXT(
    VkDevice                                    device,
    VkImage                                     image,
    const VkImageSubresource2KHR*               pSubresource,
    VkSubresourceLayout2KHR*                    pLayout);

Parameters

  • device is the logical device that owns the image.

  • image is the image whose layout is being queried.

  • pSubresource is a pointer to a VkImageSubresource2KHR structure selecting a specific image for the image subresource.

  • pLayout is a pointer to a VkSubresourceLayout2KHR structure in which the layout is returned.

Description

vkGetImageSubresourceLayout2KHR behaves similarly to vkGetImageSubresourceLayout, with the ability to specify extended inputs via chained input structures, and to return extended information via chained output structures.

It is legal to call vkGetImageSubresourceLayout2KHR with an image created with tiling equal to VK_IMAGE_TILING_OPTIMAL, but the members of VkSubresourceLayout2KHR::subresourceLayout will have undefined values in this case.

Note

Structures chained from VkImageSubresource2KHR::pNext will also be updated when tiling is equal to VK_IMAGE_TILING_OPTIMAL.
Valid Usage

  • VUID-vkGetImageSubresourceLayout2KHR-aspectMask-00997
    The aspectMask member of pSubresource must only have a single bit set

  • VUID-vkGetImageSubresourceLayout2KHR-mipLevel-01716
    The mipLevel member of pSubresource must be less than the mipLevels specified in image

  • VUID-vkGetImageSubresourceLayout2KHR-arrayLayer-01717
    The arrayLayer member of pSubresource must be less than the arrayLayers specified in image

  • VUID-vkGetImageSubresourceLayout2KHR-format-08886
    If format of the image is a color format that is not a multi-planar image format, and tiling of the image is VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_OPTIMAL, the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_COLOR_BIT

  • VUID-vkGetImageSubresourceLayout2KHR-format-04462
    If format of the image has a depth component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_DEPTH_BIT

  • VUID-vkGetImageSubresourceLayout2KHR-format-04463
    If format of the image has a stencil component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkGetImageSubresourceLayout2KHR-format-04464
    If format of the image does not contain a stencil or depth component, the aspectMask member of pSubresource must not contain VK_IMAGE_ASPECT_DEPTH_BIT or VK_IMAGE_ASPECT_STENCIL_BIT

  • VUID-vkGetImageSubresourceLayout2KHR-tiling-08717
    If the tiling of the image is VK_IMAGE_TILING_LINEAR and has a multi-planar image format, then the aspectMask member of pSubresource must be a single valid multi-planar aspect mask bit

  • VUID-vkGetImageSubresourceLayout2KHR-image-09434
    If image was created with the VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID external memory handle type, then image must be bound to memory

  • VUID-vkGetImageSubresourceLayout2KHR-tiling-09435
    If the tiling of the image is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_MEMORY_PLANE_i_BIT_EXT and the index i must be less than the VkDrmFormatModifierPropertiesEXT::drmFormatModifierPlaneCount associated with the image’s format and VkImageDrmFormatModifierPropertiesEXT::drmFormatModifier

Valid Usage (Implicit)

  • VUID-vkGetImageSubresourceLayout2KHR-device-parameter
    device must be a valid VkDevice handle

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

  • VUID-vkGetImageSubresourceLayout2KHR-pSubresource-parameter
    pSubresource must be a valid pointer to a valid VkImageSubresource2KHR structure

  • VUID-vkGetImageSubresourceLayout2KHR-pLayout-parameter
    pLayout must be a valid pointer to a VkSubresourceLayout2KHR structure

  • VUID-vkGetImageSubresourceLayout2KHR-image-parent
    image must have been created, allocated, or retrieved from device

See Also

VK_KHR_maintenance5, VkDevice, VkImage, VkImageSubresource2KHR, VkSubresourceLayout2KHR

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