C Specification

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

void vkGetImageSubresourceLayout(
VkDevice                                    device,
VkImage                                     image,
const VkImageSubresource*                   pSubresource,
VkSubresourceLayout*                        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 VkImageSubresource structure selecting a specific image for the image subresource.

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

Description

If the image is linear, then the returned layout is valid for host access.

If the image’s tiling is VK_IMAGE_TILING_LINEAR and its format is a multi-planar format, then vkGetImageSubresourceLayout describes one format plane of the image. If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then vkGetImageSubresourceLayout describes one memory plane of the image. If the image’s tiling is VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and the image is non-linear, then the returned layout has an implementation-dependent meaning; the vendor of the image’s DRM format modifier may provide documentation that explains how to interpret the returned layout.

vkGetImageSubresourceLayout is invariant for the lifetime of a single image. However, the subresource layout of images in Android hardware buffer external memory is not known until the image has been bound to memory, so applications must not call vkGetImageSubresourceLayout for such an image before it has been bound.

Valid Usage
• image must have been created with tiling equal to VK_IMAGE_TILING_LINEAR or VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT

• The aspectMask member of pSubresource must only have a single bit set

• The mipLevel member of pSubresource must be less than the mipLevels specified in VkImageCreateInfo when image was created

• The arrayLayer member of pSubresource must be less than the arrayLayers specified in VkImageCreateInfo when image was created

• If the tiling of the image is VK_IMAGE_TILING_LINEAR and its format is a multi-planar format with two planes, the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_PLANE_0_BIT or VK_IMAGE_ASPECT_PLANE_1_BIT

• If the tiling of the image is VK_IMAGE_TILING_LINEAR and its format is a multi-planar format with three planes, the aspectMask member of pSubresource must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or VK_IMAGE_ASPECT_PLANE_2_BIT

• 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.

• 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 drmFormatModifierPlaneCount associated with the image’s format and drmFormatModifier.

Valid Usage (Implicit)
• device must be a valid VkDevice handle

• image must be a valid VkImage handle

• pSubresource must be a valid pointer to a valid VkImageSubresource structure

• pLayout must be a valid pointer to a VkSubresourceLayout structure

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