C Specification

To query sparse memory requirements for an image, call:

// Provided by VK_VERSION_1_0
void vkGetImageSparseMemoryRequirements(
    VkDevice                                    device,
    VkImage                                     image,
    uint32_t*                                   pSparseMemoryRequirementCount,
    VkSparseImageMemoryRequirements*            pSparseMemoryRequirements);

Parameters

  • 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.

Description

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 user 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 set to zero and pSparseMemoryRequirements will not be written to.

Note

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-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetImageSparseMemoryRequirements-image-parameter
    image must be a valid VkImage handle

  • 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

See Also

VK_VERSION_1_0, VkDevice, VkImage, VkSparseImageMemoryRequirements

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