VKQUEUEBINDSPARSE(3)

NAME
vkQueueBindSparse - Bind device memory to a sparse resource object.

C SPECIFICATION

    VkResult vkQueueBindSparse(
        VkQueue                                     queue,
        uint32_t                                    bindInfoCount,
        const VkBindSparseInfo*                     pBindInfo,
        VkFence                                     fence);

PARAMETERS

queue
    The queue upon which to perform the operation.

bindInfoCount
    The number of binding operations to perform.

pBindInfo
    A pointer to an array of bindInfoCount data structures describing the binding operations to perform.

fence
    A handle to a fence object that will be signaled when the binding operation completes.

DESCRIPTION

vkQueueBindSparse binds memory to sparse resources. The number of binding operations to perform is specified in bindInfoCount and the binding operation takes place on the queue specified in queue. queue must be the handle to a queue that is a member of a family that supports the VK_QUEUE_SPARSE_MEMMGR_BIT capability.

pBindInfo is a pointer to an array of bindInfoCount VkBindSparseInfo structures describing each of the binding operations. The definition of VkBindSparseInfo is:

    typedef struct VkBindSparseInfo {
        VkStructureType                             sType;
        const void*                                 pNext;
        uint32_t                                    waitSemaphoreCount;
        const VkSemaphore*                          pWaitSemaphores;
        uint32_t                                    bufferBindCount;
        const VkSparseBufferMemoryBindInfo*         pBufferBinds;
        uint32_t                                    imageOpaqueBindCount;
        const VkSparseImageOpaqueMemoryBindInfo*    pImageOpaqueBinds;
        uint32_t                                    imageBindCount;
        const VkSparseImageMemoryBindInfo*          pImageBinds;
        uint32_t                                    signalSemaphoreCount;
        const VkSemaphore*                          pSignalSemaphores;
    } VkBindSparseInfo;

The sType member of VkBindSparseInfo should be VK_STRUCTURE_TYPE_BIND_SPARSE_INFO. The pNext member is reserved for use by extensions and should be set to NULL.

The waitSemaphoreCount member specifies the number of semaphores that should be waited on before the binding operation takes place. pWaitSemaphores is a pointer to an array of VkSemaphore objects to wait on. If waitSemaphoreCount is zero then the value of pWaitSemaphores is ignored and the command will not wait before performing the bind operations.

The bufferBindCount parameter specifies the number of binding operations to apply to buffer objects. The pBufferBinds parameter is a pointer to an array of bufferBindCount VkSparseBufferMemoryBindInfo structures describing the binding operations for buffers to be performed by the command. The definition of VkSparseBufferMemoryBindInfo is:

    typedef struct VkSparseBufferMemoryBindInfo {
        VkBuffer                     buffer;
        uint32_t                     bindCount;
        const VkSparseMemoryBind*    pBinds;
    } VkSparseBufferMemoryBindInfo;

The buffer member of VkSparseBufferMemoryBindInfo specifies the target buffer, bindCount specifies the number of binding operations to apply to that buffer, and pBinds is a pointer to an array of VkSparseMemoryBind structures describing the bindings. If bindCount is zero then the value of pBinds is ignored and no bindings are performed. The definition of VkSparseMemoryBind is:

    typedef struct VkSparseMemoryBind {
        VkDeviceSize               resourceOffset;
        VkDeviceSize               size;
        VkDeviceMemory             memory;
        VkDeviceSize               memoryOffset;
        VkSparseMemoryBindFlags    flags;
    } VkSparseMemoryBind;

For each element of the array of VkSparseMemoryBind structures, resourceOffset and size specify the starting offset and size of the region in the buffer. Both are specified in bytes. memoryOffset specifies the offset of the region of the memory object specified by memory that is to be bound to the specified region in the buffer object. memoryOffset is also specified in bytes. resourceOffset, size and memoryOffset must each satisfy the alignment requirements of the buffer. This is returned in the alignment field of the VkMemoryRequirements structure filled by a call to vkGetBufferMemoryRequirements.

The flags member of the VkSparseMemoryBind structure is a bitfield comprising members of the VkSparseMemoryBindFlagBits enumeration, the definition of which is:

    typedef enum VkSparseMemoryBindFlagBits {
        VK_SPARSE_MEMORY_BIND_METADATA_BIT = 0x00000001,
    } VkSparseMemoryBindFlagBits;

All other bits in flags are reserved and should be set to zero.

The imageOpaqueBindCount member specifies the number of opaque image memory binding operations to execute and pImageOpaqueBinds is a pointer to an array of imageOpaqueBindCount VkSparseImageOpaqueMemoryBindInfo structures describing those operations. If imageOpaqueBindCount is zero then the value of pImageOpaqueBinds is ignored and no binding operations are performed. The definition of VkSparseImageOpaqueMemoryBindInfo is:

    typedef struct VkSparseImageOpaqueMemoryBindInfo {
        VkImage                      image;
        uint32_t                     bindCount;
        const VkSparseMemoryBind*    pBinds;
    } VkSparseImageOpaqueMemoryBindInfo;

The image member of the VkSparseImageOpaqueMemoryBindInfo structure specifies the image that is the target of the binding operation. bindCount specifies the number of binding operations to be applied to image and pBinds is a pointer to an array of VkSparseMemoryBind structures describing those operations. If bindCount is zero then the value of pBinds is ignored. Opaque memory binding operations are expressed in terms of byte offsets. The VkSparseMemoryBind structures pointed to by the pBinds member of VkSparseImageOpaqueMemoryBindInfo are interpreted as described for buffers above.

The imageBindCount member of the VkBindSparseInfo specifies the number of non-opaque image bindings to perform, and the pImageBinds member of the structure is a pointer to an array of imageBindCount VkSparseImageMemoryBindInfo structures describing those operations. If imageBindCount is zero then the value of pImageBinds is ignored. The definition of VkSparseImageMemoryBindInfo is:

    typedef struct VkSparseImageMemoryBindInfo {
        VkImage                           image;
        uint32_t                          bindCount;
        const VkSparseImageMemoryBind*    pBinds;
    } VkSparseImageMemoryBindInfo;

Within VkSparseImageMemoryBindInfo, the image member specifies the image that is to be the target of the binding operation. bindCount specifies the number of binding operations to execute and pBinds is a pointer to an array of bindCount VkSparseImageMemoryBind structes describing those operations. The definition of VkSparseImageMemoryBind is:

    typedef struct VkSparseImageMemoryBind {
        VkImageSubresource         subresource;
        VkOffset3D                 offset;
        VkExtent3D                 extent;
        VkDeviceMemory             memory;
        VkDeviceSize               memoryOffset;
        VkSparseMemoryBindFlags    flags;
    } VkSparseImageMemoryBind;

The subresource member of VkSparseImageMemoryBind specifies the image subresource within the image to bind memory to. The offset and extent members specify the region within the image subresource to bind memory to. offset and extent are instances of the VkOffset3D and VkExtent3D structures, respectively, and are expressed in texels. The memoryOffset member specifies the offset within the memory object specified by memory from which to bind memory. memoryOffset is expressed in bytes. Its value and the values contained in offset and extent must satisfy device-specific alignment requirements.

The flags member within VkSparseImageMemoryBind has the same interpretation as the similarly named member in VkSparseMemoryBind.

The signalSemaphoreCount parameter specifies the number of semaphores to signal after the binding operations are complete. pSignalSemaphores is a pointer to an array of signalSemaphoreCount VkSemaphore objects to signal at this point. If signalSemaphoreCount is zero then the value of pSignalSemaphores is ignored and no semaphores are signaled as a result of the operation.

VALID USAGE

    • queue must be a valid VkQueue handle

    • If bindInfoCount is not 0, pBindInfo must be a pointer to an array of bindInfoCount valid VkBindSparseInfo structures

    • If fence is not VK_NULL_HANDLE, fence must be a valid VkFence handle

    • The queue must support sparse binding operations

    • Each of queue and fence that are valid handles must have been created, allocated or retrieved from the same VkDevice

    • fence must be unsignaled

    • fence must not be associated with any other queue command that has not yet completed execution on that queue

HOST SYNCHRONIZATION

    • Host access to queue must be externally synchronized

    • Host access to pBindInfo[].pWaitSemaphores[] must be externally synchronized

    • Host access to pBindInfo[].pSignalSemaphores[] 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
Command Buffer Levels | Render Pass Scope | Supported Queue Types
- | - | SPARSE_BINDING

RETURN CODES

On success, this command returns

        • VK_SUCCESS

On failure, this command returns

        • VK_ERROR_OUT_OF_HOST_MEMORY

        • VK_ERROR_OUT_OF_DEVICE_MEMORY

SEE ALSO

vkQueueSubmit, vkBindBufferMemory, vkGetBufferMemoryRequirements, vkGetImageMemoryRequirements, vkBindImageMemory

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.