vkQueueBindSparse(3)

# vkQueueBindSparse(3) Manual Page

## Name

vkQueueBindSparse - Bind device memory to a sparse resource object

Loading… please wait.

## C Specification

To submit sparse binding operations to a queue, call:

    // Provided by VK_VERSION_1_0
    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 a pointer to 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 a VkBindSparseInfo 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 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

- VUID-vkQueueBindSparse-fence-01113
  If `fence` is not VK_NULL_HANDLE, `fence` must be unsignaled

- VUID-vkQueueBindSparse-fence-01114
  If `fence` is not VK_NULL_HANDLE, `fence` must not be associated with any other queue command that has not yet completed execution on that queue

- VUID-vkQueueBindSparse-pSignalSemaphores-01115
  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

- VUID-vkQueueBindSparse-pWaitSemaphores-01116
  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

- VUID-vkQueueBindSparse-pWaitSemaphores-03245
  All elements of the `pWaitSemaphores` member of all elements of `pBindInfo` referring to a semaphore created with a VkSemaphoreType of `VK_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)

- VUID-vkQueueBindSparse-queue-parameter
  `queue` must be a valid VkQueue handle

- VUID-vkQueueBindSparse-pBindInfo-parameter
  If `bindInfoCount` is not `0`, `pBindInfo` must be a valid pointer to an array of `bindInfoCount` valid VkBindSparseInfo structures

- VUID-vkQueueBindSparse-fence-parameter
  If `fence` is not VK_NULL_HANDLE, `fence` must be a valid VkFence handle

- VUID-vkQueueBindSparse-queuetype
  The `queue` must support sparse binding operations

- VUID-vkQueueBindSparse-commonparent
  Both of `fence`, and `queue` that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

- Host access to `queue` must be externally synchronized

- Host access to `fence` must be externally synchronized

Command Properties

Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type
--- | --- | --- | --- | ---
- | - | - | 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

VK_VERSION_1_0, VkBindSparseInfo, VkFence, VkQueue

## Document Notes

For more information, see the Vulkan Specification

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

## Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0