vkGetImageSubresourceLayout2(3)

Name

vkGetImageSubresourceLayout2 - Retrieve information about an image subresource

C Specification

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

// Provided by VK_VERSION_1_4
void vkGetImageSubresourceLayout2(
    VkDevice                                    device,
    VkImage                                     image,
    const VkImageSubresource2*                  pSubresource,
    VkSubresourceLayout2*                       pLayout);

or the equivalent command

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

or the equivalent command

// Provided by VK_EXT_host_image_copy, VK_EXT_image_compression_control
void vkGetImageSubresourceLayout2EXT(
    VkDevice                                    device,
    VkImage                                     image,
    const VkImageSubresource2*                  pSubresource,
    VkSubresourceLayout2*                       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 VkImageSubresource2 structure selecting a specific image for the image subresource.
pLayout is a pointer to a VkSubresourceLayout2 structure in which the layout is returned.

Description

vkGetImageSubresourceLayout2 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 vkGetImageSubresourceLayout2 with an image created with tiling equal to VK_IMAGE_TILING_OPTIMAL, but the members of VkSubresourceLayout2::subresourceLayout will have undefined values in this case.

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

Valid Usage

VUID-vkGetImageSubresourceLayout2-aspectMask-00997
The aspectMask member of pSubresource must only have a single bit set
VUID-vkGetImageSubresourceLayout2-mipLevel-01716
The mipLevel member of pSubresource must be less than the mipLevels specified in image
VUID-vkGetImageSubresourceLayout2-arrayLayer-01717
The arrayLayer member of pSubresource must be less than the arrayLayers specified in image
VUID-vkGetImageSubresourceLayout2-format-08886
If format of the image is a color format that is not a multi-planar 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-vkGetImageSubresourceLayout2-format-04462
If format of the image has a depth component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_DEPTH_BIT
VUID-vkGetImageSubresourceLayout2-format-04463
If format of the image has a stencil component, the aspectMask member of pSubresource must contain VK_IMAGE_ASPECT_STENCIL_BIT
VUID-vkGetImageSubresourceLayout2-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-vkGetImageSubresourceLayout2-tiling-08717
If the tiling of the image is VK_IMAGE_TILING_LINEAR and has a multi-planar format, then the aspectMask member of pSubresource must be a single valid multi-planar aspect mask bit
VUID-vkGetImageSubresourceLayout2-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-vkGetImageSubresourceLayout2-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-vkGetImageSubresourceLayout2-device-parameter
device must be a valid VkDevice handle
VUID-vkGetImageSubresourceLayout2-image-parameter
image must be a valid VkImage handle
VUID-vkGetImageSubresourceLayout2-pSubresource-parameter
pSubresource must be a valid pointer to a valid VkImageSubresource2 structure
VUID-vkGetImageSubresourceLayout2-pLayout-parameter
pLayout must be a valid pointer to a VkSubresourceLayout2 structure
VUID-vkGetImageSubresourceLayout2-image-parent
image must have been created, allocated, or retrieved from device

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.