Function Prototype

vkGetImageSubresourceLayout2KHR

Retrieve information about an image subresource

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

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

or the equivalent command

void vkGetImageSubresourceLayout2EXT(
    VkDevice device,
    VkImage image,
    const VkImageSubresource2KHR* pSubresource,
    VkSubresourceLayout2KHR* pLayout);
  • 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.

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.

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_PLANEiBIT_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-pSubresource-parameter

pSubresource must be a valid pointer to a valid VkImageSubresource2KHR structure

VUID-vkGetImageSubresourceLayout2KHR-image-parent

image must have been created, allocated, or retrieved from device