# vkGetImageSubresourceLayout(3) Manual Page

## Name

vkGetImageSubresourceLayout - Retrieve information about an image subresource

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

## See Also

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 (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.