vkGetImageSparseMemoryRequirements - Query the memory requirements for a sparse image

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

VK_VERSION_1_0, Device, Image, SparseImageMemoryRequirements

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

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 application 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 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 valid SampleCountFlagBits value that is set in ImageFormatProperties::sampleCounts returned by getPhysicalDeviceImageFormatProperties with format, type, tiling, and usage equal to those in this command

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

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

vkQueueBindSparse - Bind device memory to a sparse resource object

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 referring to a semaphore 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 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 QUEUE_SPARSE_BINDING_BIT 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 if it was not created with DEVICE_QUEUE_CREATE_INTERNALLY_SYNCHRONIZED_BIT_KHR

• Host access to fence must be externally synchronized

Command Properties

'

Return Codes

Success

• SUCCESS

Failure

• ERROR_DEVICE_LOST
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_OUT_OF_HOST_MEMORY
• ERROR_UNKNOWN
• ERROR_VALIDATION_FAILED

See Also

VK_VERSION_1_0, BindSparseInfo, Fence, Queue

VkSparseImageFormatProperties - Structure specifying sparse image format properties

See Also

VK_VERSION_1_0, Extent3D, ImageAspectFlags, SparseImageFormatFlags, SparseImageFormatProperties2, SparseImageMemoryRequirements, getPhysicalDeviceSparseImageFormatProperties

VkSparseImageMemoryRequirements - Structure specifying sparse image memory requirements

See Also

VK_VERSION_1_0, DeviceSize, SparseImageFormatProperties, SparseImageMemoryRequirements2, getImageSparseMemoryRequirements

VkImageSubresource - Structure specifying an image subresource

Valid Usage (Implicit)

See Also

VK_VERSION_1_0, ImageAspectFlags, ImageSubresource2, SparseImageMemoryBind, getImageSubresourceLayout

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://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#resources-association

• If the resource being bound is a Buffer, resourceOffset, memoryOffset and size must be an integer multiple of the alignment of the MemoryRequirements structure returned from a call to getBufferMemoryRequirements with the buffer resource
• If the resource being bound is a Image, resourceOffset and memoryOffset must be an integer multiple of the alignment of the MemoryRequirements structure returned from a call to getImageMemoryRequirements with the image resource
• 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

VK_VERSION_1_0, DeviceMemory, DeviceSize, SparseBufferMemoryBindInfo, SparseImageOpaqueMemoryBindInfo, SparseMemoryBindFlags

VkSparseImageMemoryBind - Structure specifying sparse image memory bind

Valid Usage

• If the sparseResidencyAliased 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://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#resources-association
• offset.x must be a multiple of the sparse image block width (SparseImageFormatProperties::imageGranularity.width) of the image
• extent.width must be greater than 0
• 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 be greater than 0
• 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 be greater than 0
• 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

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

VkSparseBufferMemoryBindInfo - Structure specifying a sparse buffer memory bind operation

Valid Usage (Implicit)

See Also

VK_VERSION_1_0, BindSparseInfo, Buffer, SparseMemoryBind

VkSparseImageOpaqueMemoryBindInfo - Structure specifying sparse image opaque memory bind information

Description

This structure is normally used to bind memory to fully-resident sparse images or for mip tail regions of partially resident images. However, it can also be used to bind memory for the entire binding range of partially resident images.

If the pBinds[i].flags of an element i of pBinds does not contain SPARSE_MEMORY_BIND_METADATA_BIT, the resourceOffset is in the range [0, MemoryRequirements::size), This range includes data from all aspects of the image, including metadata. For most implementations this will probably mean that the resourceOffset is a simple device address offset within the resource. It is possible for an application to bind a range of memory that includes both resource data and metadata. However, the application would not know what part of the image the memory is used for, or if any range is being used for metadata.

If the pBinds[i].flags of an element i of pBinds contains SPARSE_MEMORY_BIND_METADATA_BIT, the binding range specified must be within the mip tail region of the metadata aspect. In this case the resourceOffset is not required to be a simple device address offset within the resource. However, it is defined to be within [imageMipTailOffset, imageMipTailOffset + imageMipTailSize) for the metadata aspect. See SparseMemoryBind for the full constraints on binding region with this flag present.

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

VK_VERSION_1_0, BindSparseInfo, Image, SparseMemoryBind

VkSparseImageMemoryBindInfo - Structure specifying sparse image memory bind information

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
• The subresource.aspectMask member of each element of pBinds must be valid for the format specified in ImageCreateInfo when image was created
• image must have been created with IMAGE_CREATE_SPARSE_RESIDENCY_BIT set

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

VK_VERSION_1_0, BindSparseInfo, Image, SparseImageMemoryBind

VkBindSparseInfo - Structure specifying a sparse binding operation

Description

The first synchronization scope of each semaphore signal operation defined by this structure includes all sparse binding operations defined by this structure.

The second synchronization scope of each semaphore wait operation defined by this structure includes all sparse binding operations defined by this structure.

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
• If the pNext chain of this structure includes a FrameBoundaryTensorsARM structure then it must also include a FrameBoundaryEXT structure

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, FrameBoundaryEXT, FrameBoundaryTensorsARM, or TimelineSemaphoreSubmitInfo
• The sType value of each structure 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

VK_VERSION_1_0, Semaphore, SparseBufferMemoryBindInfo, SparseImageMemoryBindInfo, SparseImageOpaqueMemoryBindInfo, StructureType, queueBindSparse

VkImageAspectFlagBits - Bitmask specifying which aspects of an image are included in a view

Description

• IMAGE_ASPECT_NONE specifies no image aspect, or the image aspect is not applicable.

• IMAGE_ASPECT_COLOR_BIT specifies the color aspect.
• IMAGE_ASPECT_DEPTH_BIT specifies the depth aspect.
• IMAGE_ASPECT_STENCIL_BIT specifies the stencil aspect.
• IMAGE_ASPECT_METADATA_BIT specifies the metadata aspect used for sparse resource operations.
• IMAGE_ASPECT_PLANE_0_BIT specifies plane 0 of a multi-planar image format.
• IMAGE_ASPECT_PLANE_1_BIT specifies plane 1 of a multi-planar image format.
• IMAGE_ASPECT_PLANE_2_BIT specifies plane 2 of a multi-planar image format.
• IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT specifies memory plane 0.
• IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT specifies memory plane 1.
• IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT specifies memory plane 2.
• IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT specifies memory plane 3.

See Also

VK_VERSION_1_0, BindImagePlaneMemoryInfo, DeviceImageMemoryRequirements, ExportMetalTextureInfoEXT, ImageAspectFlags, ImagePlaneMemoryRequirementsInfo, ImportMetalTextureInfoEXT

VkSparseImageFormatFlagBits - Bitmask specifying additional information about a sparse image resource

Description

• SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT specifies that the image uses a single mip tail region for all array layers.

• SPARSE_IMAGE_FORMAT_ALIGNED_MIP_SIZE_BIT specifies that the first mip level whose dimensions are not integer multiples of the corresponding dimensions of the sparse image block begins the mip tail region.
• SPARSE_IMAGE_FORMAT_NONSTANDARD_BLOCK_SIZE_BIT specifies that the image uses non-standard sparse image block dimensions, and the imageGranularity values do not match the standard sparse image block dimensions for the given format.

See Also

VK_VERSION_1_0, SparseImageFormatFlags

VkSparseMemoryBindFlagBits - Bitmask specifying usage of a sparse memory binding operation

Description

• SPARSE_MEMORY_BIND_METADATA_BIT specifies that the memory being bound is only for the metadata aspect.

See Also

VK_VERSION_1_0, SparseMemoryBindFlags