VKGETIMAGESPARSEMEMO(3)

NAME
vkGetImageSparseMemoryRequirements - Query the memory requirements for a sparse image.

C SPECIFICATION

    void vkGetImageSparseMemoryRequirements(
        VkDevice                                    device,
        VkImage                                     image,
        uint32_t*                                   pSparseMemoryRequirementCount,
        VkSparseImageMemoryRequirements*            pSparseMemoryRequirements);

PARAMETERS

device
    A handle to the device that owns the image being queried.

image
    A handle to the image to be queried.

pSparseMemoryRequirementCount
    On input, a pointer to a variable containing the number of elements in the array pointed to by pSparseMemoryRequirements. On output, this variable is overwritten with the number of elements written into pSparseMemoryRequirements.

pSparseMemoryRequirements
    A pointer to an array of structures that will be filled with the requested information.

DESCRIPTION

vkGetImageSparseMemoryRequirements queries the device specified in device for the memory requirements of the sparse image specified in image, which must be a handle to a sparse image.

pSparseMemoryRequirementCount is a pointer to a variable which, on input to the command contains the number of elements in the array pointed to by pSparseMemoryRequirements. This is an array of VkSparseImageMemoryRequirements structures, the definition of which is:

    typedef struct VkSparseImageMemoryRequirements {
        VkSparseImageFormatProperties    formatProperties;
        uint32_t                         imageMipTailFirstLod;
        VkDeviceSize                     imageMipTailSize;
        VkDeviceSize                     imageMipTailOffset;
        VkDeviceSize                     imageMipTailStride;
    } VkSparseImageMemoryRequirements;

Within VkSparseImageMemoryRequirements, the formatProperties member is an instance of the VkSparseImageFormatProperties structure, the definition of which is:

    typedef struct VkSparseImageFormatProperties {
        VkImageAspectFlags          aspectMask;
        VkExtent3D                  imageGranularity;
        VkSparseImageFormatFlags    flags;
    } VkSparseImageFormatProperties;

The aspectMask member of VkSparseImageFormatProperties specifies the image aspect or aspects to which the remainder of the properties apply. This is a bitfield made up from members 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;

For each unique aspect of the image, an instance of VkSparseImageFormatProperties is returned. The imageGranularity member specifies the size, in texels, of the smallest region that may be uniquely bound within the image specified by image. Binding is affected by calling vkQueueBindSparse. It is an instance of the VkExtent3D structure which contains the size of the sparse binding regions, expressed in texels.

The flags member is a bitfield made up from members of the VkSparseImageFormatFlagBits enumeration and describes additional requirements for sparse memory binding. The definition of which is:

    typedef enum VkSparseImageFormatFlagBits {
        VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT = 0x00000001,
        VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT = 0x00000002,
        VK_SPARSE_IMAGE_FORMAT_NONSTANDARD_BLOCK_SIZE_BIT = 0x00000004,
    } VkSparseImageFormatFlagBits;

The meanings of each of the flags is as follows:

If VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT is set, the image combines mulitple levels at the tail of the mip chain into a single residency state for array textures. Otherwise, mip tail is individually addressable for each array layer.

If VK_SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT is set, then each mip level outside the tail has dimensions that are integer multiples of the sparse image block dimensions.

If VK_SPARSE_IMAGE_FORMAT_NONSTANDARD_BLOCK_SIZE_BIT is set, then the format has non-standard sparse image block dimensions and the members of the imageGranularity do not match the standard sparse image block dimensions for the format.

The imageMipTailStartLod member of the VkSparseImageMemoryRequirements structure contains the level-of-detail at which the mip tail begins for the image specified in image.

imageMipTailSize contains the size of the mip tail, imageMipTailOffset contains its offset, and imageMipTailStride contains the stride between layers in the

tail for array textures. All three members are expressed in bytes.

VALID USAGE

    • device must be a valid VkDevice handle

    • image must be a valid VkImage handle

    • pSparseMemoryRequirementCount must be a pointer to a uint32_t value

    • If the value referenced by pSparseMemoryRequirementCount is not 0, and pSparseMemoryRequirements is not NULL, pSparseMemoryRequirements must be a pointer to an array of pSparseMemoryRequirementCount VkSparseImageMemoryRequirements structures

    • 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

SEE ALSO

vkQueueBindSparse, vkGetImageMemoryRequirements

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.