vkGetImageSubresourceLayout2KHR(3)

# vkGetImageSubresourceLayout2KHR(3) Manual Page

## Name

vkGetImageSubresourceLayout2KHR - Retrieve information about an image subresource

Loading… please wait.

## 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 a `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