Vulkan-Docs/doc/specs/vulkan/man/vkGetImageSparseMemoryRequirements.txt

vkGetImageSparseMemoryRequirements(3)
=====================================

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

C Specification
---------------

include::../protos/vkGetImageSparseMemoryRequirements.txt[]

Parameters
----------

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

pname:image::
    A handle to the image to be queried.

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

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

Description
-----------

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

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

include::../structs/VkSparseImageMemoryRequirements.txt[]

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

include::../structs/VkSparseImageFormatProperties.txt[]

The pname:aspectMask member of slink: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 elink:VkImageAspectFlagBits enumeration, the definition
of which is:

include::../enums/VkImageAspectFlagBits.txt[]

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

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

include::../enums/VkSparseImageFormatFlagBits.txt[]

The meanings of each of the flags is as follows:

If ename: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 ename: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 ename: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 pname:imageGranularity do not match the
standard sparse image block dimensions for the format.

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

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

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

include::../validity/protos/vkGetImageSparseMemoryRequirements.txt[]

See Also
--------

flink:vkQueueBindSparse, flink:vkGetImageMemoryRequirements

include::footer.txt[]