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