vkGetImageSubresourceLayout(3)

# vkGetImageSubresourceLayout(3) Manual Page

## Name

vkGetImageSubresourceLayout - Retrieve information about an image subresource

Loading… please wait.

## C Specification

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

    // Provided by VK_VERSION_1_0
    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 subresource from the image.

- `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 or QNX Screen 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

- VUID-vkGetImageSubresourceLayout-image-07790
  `image` must have been created with `tiling` equal to `VK_IMAGE_TILING_LINEAR` or `VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT`

- VUID-vkGetImageSubresourceLayout-aspectMask-00997
  The `aspectMask` member of `pSubresource` must only have a single bit set

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

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

- VUID-vkGetImageSubresourceLayout-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-vkGetImageSubresourceLayout-format-04462
  If `format` of the `image` has a depth component, the `aspectMask` member of `pSubresource` must contain `VK_IMAGE_ASPECT_DEPTH_BIT`

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

- VUID-vkGetImageSubresourceLayout-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-vkGetImageSubresourceLayout-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-vkGetImageSubresourceLayout-image-09432
  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-vkGetImageSubresourceLayout-tiling-09433
  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-vkGetImageSubresourceLayout-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkGetImageSubresourceLayout-image-parameter
  `image` must be a valid VkImage handle

- VUID-vkGetImageSubresourceLayout-pSubresource-parameter
  `pSubresource` must be a valid pointer to a valid VkImageSubresource structure

- VUID-vkGetImageSubresourceLayout-pLayout-parameter
  `pLayout` must be a valid pointer to a VkSubresourceLayout structure

- VUID-vkGetImageSubresourceLayout-image-parent
  `image` must have been created, allocated, or retrieved from `device`

## See Also

VK_VERSION_1_0, VkDevice, VkImage, VkImageSubresource, VkSubresourceLayout

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