VKQUEUEBINDSPARSE(3)

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

C SPECIFICATION

To submit sparse binding operations to a queue, call:

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

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 an array of VkBindSparseInfo structures, each specifying a sparse binding submission batch.

    • fence is an optional handle to a fence to be signaled. If fence is not VK_NULL_HANDLE, it defines a fence signal operation.

DESCRIPTION

vkQueueBindSparse is a queue submission command, with each batch defined by an element of pBindInfo as an instance of the VkBindSparseInfo structure.

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

    • 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

        • VK_ERROR_DEVICE_LOST

SEE ALSO

VkBindSparseInfo, VkFence, VkQueue

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkQueueBindSparse

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly.

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.