vkGetImageSparseMemoryRequirements - Query the memory requirements for a sparse image

Parameters

• device is the logical device that owns the image.

• image is the Image 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 SparseImageMemoryRequirements 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 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 MemoryRequirements::size than would be obtained by adding together memory sizes for all SparseImageMemoryRequirements returned by getImageSparseMemoryRequirements. This may occur when the implementation requires unused padding in the address range describing the resource.

Valid Usage (Implicit)

• device must be a valid Device handle

• image must be a valid Image handle
• pSparseMemoryRequirementCount must be a valid pointer to a uint32_t value
• 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 SparseImageMemoryRequirements structures
• image must have been created, allocated, or retrieved from device

See Also

Device, Image, SparseImageMemoryRequirements

vkGetPhysicalDeviceSparseImageFormatProperties - Retrieve properties of an image format applied to sparse images

Parameters

• physicalDevice is the physical device from which to query the sparse image capabilities.

• format is the image format.
• type is the dimensionality of image.
• samples is the number of samples per texel as defined in SampleCountFlagBits.
• usage is a bitmask describing the intended usage of the image.
• tiling is the tiling arrangement of the texel blocks in memory.
• pPropertyCount is a pointer to an integer related to the number of sparse format properties available or queried, as described below.
• pProperties is either NULL or a pointer to an array of SparseImageFormatProperties structures.

Description

If pProperties is NULL, then the number of sparse format properties available is returned in pPropertyCount. Otherwise, pPropertyCount must point to a variable set by the user to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If pPropertyCount is less than the number of sparse format properties available, at most pPropertyCount structures will be written.

If IMAGE_CREATE_SPARSE_RESIDENCY_BIT is not supported for the given arguments, pPropertyCount will be set to zero upon return, and no data will be written to pProperties.

Multiple aspects are returned for depth/stencil images that are implemented as separate planes by the implementation. The depth and stencil data planes each have unique SparseImageFormatProperties data.

Depth/stencil images with depth and stencil data interleaved into a single plane will return a single SparseImageFormatProperties structure with the aspectMask set to IMAGE_ASPECT_DEPTH_BIT | IMAGE_ASPECT_STENCIL_BIT.

Valid Usage

• samples must be a bit value that is set in ImageFormatProperties::sampleCounts returned by getPhysicalDeviceImageFormatProperties with format, type, tiling, and usage equal to those in this command and flags equal to the value that is set in ImageCreateInfo::flags when the image is created

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

• format must be a valid Format value
• type must be a valid ImageType value
• samples must be a valid SampleCountFlagBits value
• usage must be a valid combination of ImageUsageFlagBits values
• usage must not be 0
• tiling must be a valid ImageTiling value
• pPropertyCount must be a valid pointer to a uint32_t value
• If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount SparseImageFormatProperties structures

See Also

Format, ImageTiling, ImageType, ImageUsageFlags, PhysicalDevice, SampleCountFlagBits, SparseImageFormatProperties

vkQueueBindSparse - Bind device memory to a sparse resource object

Parameters

• queue is the queue that the sparse binding operations will be submitted to.

• bindInfoCount is the number of elements in the pBindInfo array.
• pBindInfo is a pointer to an array of BindSparseInfo structures, each specifying a sparse binding submission batch.
• fence is an optional handle to a fence to be signaled. If fence is not NULL_HANDLE, it defines a fence signal operation.

Description

queueBindSparse is a queue submission command, with each batch defined by an element of pBindInfo as a BindSparseInfo structure. Batches begin execution in the order they appear in pBindInfo, but may complete out of order.

Within a batch, a given range of a resource must not be bound more than once. Across batches, if a range is to be bound to one allocation and offset and then to another allocation and offset, then the application must guarantee (usually using semaphores) that the binding operations are executed in the correct order, as well as to order binding operations against the execution of command buffer submissions.

As no operation to queueBindSparse causes any pipeline stage to access memory, synchronization primitives used in this command effectively only define execution dependencies.

Additional information about fence and semaphore operation is described in the synchronization chapter.

Valid Usage

• If fence is not NULL_HANDLE, fence must be unsignaled

• If fence is not NULL_HANDLE, fence must not be associated with any other queue command that has not yet completed execution on that queue
• Each element of the pSignalSemaphores member of each element of pBindInfo must be unsignaled when the semaphore signal operation it defines is executed on the device
• When a semaphore wait operation referring to a binary semaphore defined by any element of the pWaitSemaphores member of any element of pBindInfo executes on queue, there must be no other queues waiting on the same semaphore.
• All elements of the pWaitSemaphores member of all elements of pBindInfo member referring to a binary semaphore must be semaphores that are signaled, or have semaphore signal operations previously submitted for execution.
• All elements of the pWaitSemaphores member of all elements of pBindInfo created with a SemaphoreType of SEMAPHORE_TYPE_BINARY must reference a semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends (if any) must have also been submitted for execution.

Valid Usage (Implicit)

• queue must be a valid Queue handle

• If bindInfoCount is not 0, pBindInfo must be a valid pointer to an array of bindInfoCount valid BindSparseInfo structures
• If fence is not NULL_HANDLE, fence must be a valid Fence handle
• The queue must support sparse binding operations
• Both of fence, and queue that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Device

Host Synchronization

• Host access to queue must be externally synchronized

• Host access to pBindInfo[].pBufferBinds[].buffer must be externally synchronized
• Host access to pBindInfo[].pImageOpaqueBinds[].image must be externally synchronized
• Host access to pBindInfo[].pImageBinds[].image must be externally synchronized
• Host access to fence must be externally synchronized

Command Properties

'

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_DEVICE_LOST

See Also

BindSparseInfo, Fence, Queue

VkSparseImageFormatProperties - Structure specifying sparse image format properties

See Also

Extent3D, ImageAspectFlags, SparseImageFormatFlags, SparseImageFormatProperties2, SparseImageMemoryRequirements, getPhysicalDeviceSparseImageFormatProperties

VkSparseImageMemoryRequirements - Structure specifying sparse image memory requirements

See Also

DeviceSize, SparseImageFormatProperties, SparseImageMemoryRequirements2, getImageSparseMemoryRequirements

VkSparseMemoryBind - Structure specifying a sparse memory bind operation

Description

The binding range [resourceOffset, resourceOffset + size) has different constraints based on flags. If flags contains SPARSE_MEMORY_BIND_METADATA_BIT, the binding range must be within the mip tail region of the metadata aspect. This metadata region is defined by:

• metadataRegion = [base, base + imageMipTailSize)
• base = imageMipTailOffset + imageMipTailStride × n

and imageMipTailOffset, imageMipTailSize, and imageMipTailStride values are from the SparseImageMemoryRequirements corresponding to the metadata aspect of the image, and n is a valid array layer index for the image,

imageMipTailStride is considered to be zero for aspects where SparseImageMemoryRequirements::formatProperties.flags contains SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT.

If flags does not contain SPARSE_MEMORY_BIND_METADATA_BIT, the binding range must be within the range [0,MemoryRequirements::size).

Valid Usage

• If memory is not NULL_HANDLE, memory and memoryOffset must match the memory requirements of the resource, as described in section https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#resources-association

• If memory is not NULL_HANDLE, memory must not have been created with a memory type that reports MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set
• size must be greater than 0
• resourceOffset must be less than the size of the resource
• size must be less than or equal to the size of the resource minus resourceOffset
• memoryOffset must be less than the size of memory
• size must be less than or equal to the size of memory minus memoryOffset
• If memory was created with ExportMemoryAllocateInfo::handleTypes not equal to 0, at least one handle type it contained must also have been set in ExternalMemoryBufferCreateInfo::handleTypes or ExternalMemoryImageCreateInfo::handleTypes when the resource was created.
• If memory was created by a memory import operation, the external handle type of the imported memory must also have been set in ExternalMemoryBufferCreateInfo::handleTypes or ExternalMemoryImageCreateInfo::handleTypes when the resource was created.

Valid Usage (Implicit)

• If memory is not NULL_HANDLE, memory must be a valid DeviceMemory handle

• flags must be a valid combination of SparseMemoryBindFlagBits values

See Also

DeviceMemory, DeviceSize, SparseBufferMemoryBindInfo, SparseImageOpaqueMemoryBindInfo, SparseMemoryBindFlags

VkSparseImageMemoryBind - Structure specifying sparse image memory bind

Valid Usage

• If the sparse aliased residency feature is not enabled, and if any other resources are bound to ranges of memory, the range of memory being bound must not overlap with those bound ranges

• memory and memoryOffset must match the memory requirements of the calling command’s image, as described in section https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#resources-association
• subresource must be a valid image subresource for image (see https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#resources-image-views)
• offset.x must be a multiple of the sparse image block width (SparseImageFormatProperties::imageGranularity.width) of the image
• extent.width must either be a multiple of the sparse image block width of the image, or else (extent.width + offset.x) must equal the width of the image subresource
• offset.y must be a multiple of the sparse image block height (SparseImageFormatProperties::imageGranularity.height) of the image
• extent.height must either be a multiple of the sparse image block height of the image, or else (extent.height + offset.y) must equal the height of the image subresource
• offset.z must be a multiple of the sparse image block depth (SparseImageFormatProperties::imageGranularity.depth) of the image
• extent.depth must either be a multiple of the sparse image block depth of the image, or else (extent.depth + offset.z) must equal the depth of the image subresource
• If memory was created with ExportMemoryAllocateInfo::handleTypes not equal to 0, at least one handle type it contained must also have been set in ExternalMemoryImageCreateInfo::handleTypes when the image was created.
• If memory was created by a memory import operation, the external handle type of the imported memory must also have been set in ExternalMemoryImageCreateInfo::handleTypes when image was created.

Valid Usage (Implicit)

• subresource must be a valid ImageSubresource structure

• If memory is not NULL_HANDLE, memory must be a valid DeviceMemory handle
• flags must be a valid combination of SparseMemoryBindFlagBits values

See Also

DeviceMemory, DeviceSize, Extent3D, ImageSubresource, Offset3D, SparseImageMemoryBindInfo, SparseMemoryBindFlags

VkSparseBufferMemoryBindInfo - Structure specifying a sparse buffer memory bind operation

Valid Usage (Implicit)

See Also

BindSparseInfo, Buffer, SparseMemoryBind

VkSparseImageOpaqueMemoryBindInfo - Structure specifying sparse image opaque memory bind info

Valid Usage

• If the flags member of any element of pBinds contains SPARSE_MEMORY_BIND_METADATA_BIT, the binding range defined must be within the mip tail region of the metadata aspect of image

Valid Usage (Implicit)

• image must be a valid Image handle

• pBinds must be a valid pointer to an array of bindCount valid SparseMemoryBind structures
• bindCount must be greater than 0

See Also

BindSparseInfo, Image, SparseMemoryBind

VkSparseImageMemoryBindInfo - Structure specifying sparse image memory bind info

Valid Usage

• The subresource.mipLevel member of each element of pBinds must be less than the mipLevels specified in ImageCreateInfo when image was created

• The subresource.arrayLayer member of each element of pBinds must be less than the arrayLayers specified in ImageCreateInfo when image was created

Valid Usage (Implicit)

• image must be a valid Image handle

• pBinds must be a valid pointer to an array of bindCount valid SparseImageMemoryBind structures
• bindCount must be greater than 0

See Also

BindSparseInfo, Image, SparseImageMemoryBind

VkBindSparseInfo - Structure specifying a sparse binding operation

Valid Usage

• If any element of pWaitSemaphores or pSignalSemaphores was created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE then the pNext chain must include a TimelineSemaphoreSubmitInfo structure

• If the pNext chain of this structure includes a TimelineSemaphoreSubmitInfo structure and any element of pWaitSemaphores was created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE then its waitSemaphoreValueCount member must equal waitSemaphoreCount
• If the pNext chain of this structure includes a TimelineSemaphoreSubmitInfo structure and any element of pSignalSemaphores was created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE then its signalSemaphoreValueCount member must equal signalSemaphoreCount
• For each element of pSignalSemaphores created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE the corresponding element of TimelineSemaphoreSubmitInfo::pSignalSemaphoreValues must have a value greater than the current value of the semaphore when the semaphore signal operation is executed
• For each element of pWaitSemaphores created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE the corresponding element of TimelineSemaphoreSubmitInfo::pWaitSemaphoreValues must have a value which does not differ from the current value of the semaphore or from the value of any outstanding semaphore wait or signal operation on that semaphore by more than maxTimelineSemaphoreValueDifference.
• For each element of pSignalSemaphores created with a SemaphoreType of SEMAPHORE_TYPE_TIMELINE the corresponding element of TimelineSemaphoreSubmitInfo::pSignalSemaphoreValues must have a value which does not differ from the current value of the semaphore or from the value of any outstanding semaphore wait or signal operation on that semaphore by more than maxTimelineSemaphoreValueDifference.

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_BIND_SPARSE_INFO

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of DeviceGroupBindSparseInfo or TimelineSemaphoreSubmitInfo
• The sType value of each struct in the pNext chain must be unique
• If waitSemaphoreCount is not 0, pWaitSemaphores must be a valid pointer to an array of waitSemaphoreCount valid Semaphore handles
• If bufferBindCount is not 0, pBufferBinds must be a valid pointer to an array of bufferBindCount valid SparseBufferMemoryBindInfo structures
• If imageOpaqueBindCount is not 0, pImageOpaqueBinds must be a valid pointer to an array of imageOpaqueBindCount valid SparseImageOpaqueMemoryBindInfo structures
• If imageBindCount is not 0, pImageBinds must be a valid pointer to an array of imageBindCount valid SparseImageMemoryBindInfo structures
• If signalSemaphoreCount is not 0, pSignalSemaphores must be a valid pointer to an array of signalSemaphoreCount valid Semaphore handles
• Both of the elements of pSignalSemaphores, and the elements of pWaitSemaphores that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Device

See Also

Semaphore, SparseBufferMemoryBindInfo, SparseImageMemoryBindInfo, SparseImageOpaqueMemoryBindInfo, StructureType, queueBindSparse