Function Prototype

vkGetImageSparseMemoryRequirements

Query the memory requirements for a sparse image

To query sparse memory requirements for an image, call:

void vkGetImageSparseMemoryRequirements(
    VkDevice device,
    VkImage image,
    uint32_t* pSparseMemoryRequirementCount,
    VkSparseImageMemoryRequirements* pSparseMemoryRequirements);
  • device is the logical device that owns the image.
  • image is the VkImage object to get the memory requirements for.
  • pSparseMemoryRequirementCount is a pointer to an integer related to the number of sparse memory requirements available or queried, as described below.
  • pSparseMemoryRequirements is either NULL or a pointer to an array of VkSparseImageMemoryRequirements structures.

If pSparseMemoryRequirements is NULL, then the number of sparse memory requirements available is returned in pSparseMemoryRequirementCount. Otherwise, pSparseMemoryRequirementCount must point to a variable set by the application to the number of elements in the pSparseMemoryRequirements array, and on return the variable is overwritten with the number of structures actually written to pSparseMemoryRequirements. If pSparseMemoryRequirementCount is less than the number of sparse memory requirements available, at most pSparseMemoryRequirementCount structures will be written.

If the image was not created with VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT then pSparseMemoryRequirementCount will be zero and pSparseMemoryRequirements will not be written to.

It is legal for an implementation to report a larger value in VkMemoryRequirements::size than would be obtained by adding together memory sizes for all VkSparseImageMemoryRequirements returned by vkGetImageSparseMemoryRequirements. This may occur when the implementation requires unused padding in the address range describing the resource.

Valid Usage (Implicit)

VUID-vkGetImageSparseMemoryRequirements-pSparseMemoryRequirementCount-parameter

pSparseMemoryRequirementCount must be a valid pointer to a uint32_t value

VUID-vkGetImageSparseMemoryRequirements-pSparseMemoryRequirements-parameter

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

VUID-vkGetImageSparseMemoryRequirements-image-parent

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