VKGETIMAGESUBRESOURC(3)

NAME
vkGetImageSubresourceLayout - Retrieve information about an image subresource.

C SPECIFICATION

    void vkGetImageSubresourceLayout(
        VkDevice                                    device,
        VkImage                                     image,
        const VkImageSubresource*                   pSubresource,
        VkSubresourceLayout*                        pLayout);

PARAMETERS

device
    A handle to the device that owns the image.

image
    A handle to the image about which to retrieve information.

pSubresource
    A pointer to a structure describing the image subresource.

pLayout
    A pointer to a structure that will receive information about the image subresource.

DESCRIPTION

vkGetImageSubresourceLayout returns information about the memory layout of an image subresource of an image. device is a handle to the device that owns image, which is the image about which to retrieve information. A description of the image subresource is passsed to the command through an instance of the VkImageSubresource structure, the address of which is passed in pSubresource. The definition of VkImageSubresource is:

    typedef struct VkImageSubresource {
        VkImageAspectFlags    aspectMask;
        uint32_t              mipLevel;
        uint32_t              arrayLayer;
    } VkImageSubresource;

Within the pSubresource structure, aspectMask is a bitfield describing the aspect of the image and is made up of a single member of the VkImageAspectFlagBits enumeration, the definition of which is:

    typedef enum VkImageAspectFlagBits {
        VK_IMAGE_ASPECT_COLOR_BIT = 0x00000001,
        VK_IMAGE_ASPECT_DEPTH_BIT = 0x00000002,
        VK_IMAGE_ASPECT_STENCIL_BIT = 0x00000004,
        VK_IMAGE_ASPECT_METADATA_BIT = 0x00000008,
    } VkImageAspectFlagBits;

The VK_IMAGE_ASPECT_COLOR_BIT aspect is valid only for image formats that are usable as color. The VK_IMAGE_ASPECT_DEPTH_BIT aspect is valid for formats containing depth information and the VK_IMAGE_ASPECT_STENCIL_BIT aspect is valid only for formats containing stencil information. Note that some formats contain both depth and stencil information, and in this case, aspectMask is used to select which to query. It is not legal to include more than one member of VkImageAspectFlagBits in aspectMask. Some formats also include metadata which may be implementation dependent but is queryable by specifying VK_IMAGE_ASPECT_METADATA_BIT.

For resources that have mipmaps or are multiple array layers, the mipLevel and arrayLayer members describe the mipmap level and array layer, respectively. For resources that do not have mipmaps or are not layered, mipLevel and arrayLayer, respectively, should be set to zero.

Information about the selected sub-resource is returned to the caller in the instance of the VkSubresourceLayout structure pointed to by pLayout. The definition of VkSubresourceLayout is:

    typedef struct VkSubresourceLayout {
        VkDeviceSize    offset;
        VkDeviceSize    size;
        VkDeviceSize    rowPitch;
        VkDeviceSize    arrayPitch;
        VkDeviceSize    depthPitch;
    } VkSubresourceLayout;

The offset member of the pLayout structure is filled with the relative offset of the start of the sub-resource from the start of the parent resource’s memory binding. The size member is the size of the sub-resource in memory. The rowPitch specifies the distance in memory of the start of each texel row of the sub-resource from the start of the previous row. The depthPitch specififes the distance in memory of the start of each slice of the sub-resource relative to the start of the previous slice. For one-dimensional resources, rowPitch is zero, and for one- and two-dimensional resources, depthPitch is zero. All four parameters are specified in bytes.

VALID USAGE

    • device must be a valid VkDevice handle

    • image must be a valid VkImage handle

    • pSubresource must be a pointer to a valid VkImageSubresource structure

    • pLayout must be a pointer to a VkSubresourceLayout structure

    • image must have been created, allocated or retrieved from device

    • Each of device and image must have been created, allocated or retrieved from the same VkPhysicalDevice

    • image must have been created with tiling equal to VK_IMAGE_TILING_LINEAR

    • The aspectMask member of pSubresource must only have a single bit set

SEE ALSO

vkGetPhysicalDeviceImageFormatProperties

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.