VKCMDBINDDESCRIPTORS(3)

NAME
vkCmdBindDescriptorSets - Binds descriptor sets to a command buffer.

C SPECIFICATION

To bind one or more descriptor sets to a command buffer, call:

    void vkCmdBindDescriptorSets(
        VkCommandBuffer                             commandBuffer,
        VkPipelineBindPoint                         pipelineBindPoint,
        VkPipelineLayout                            layout,
        uint32_t                                    firstSet,
        uint32_t                                    descriptorSetCount,
        const VkDescriptorSet*                      pDescriptorSets,
        uint32_t                                    dynamicOffsetCount,
        const uint32_t*                             pDynamicOffsets);

PARAMETERS

    • commandBuffer is the command buffer that the descriptor sets will be bound to.

    • pipelineBindPoint is a VkPipelineBindPoint indicating whether the descriptors will be used by graphics pipelines or compute pipelines. There is a separate set of bind points for each of graphics and compute, so binding one does not disturb the other.

    • layout is a VkPipelineLayout object used to program the bindings.

    • firstSet is the set number of the first descriptor set to be bound.

    • descriptorSetCount is the number of elements in the pDescriptorSets array.

    • pDescriptorSets is an array of handles to VkDescriptorSet objects describing the descriptor sets to write to.

    • dynamicOffsetCount is the number of dynamic offsets in the pDynamicOffsets array.

    • pDynamicOffsets is a pointer to an array of uint32_t values specifying dynamic offsets.

DESCRIPTION

vkCmdBindDescriptorSets causes the sets numbered [firstSet.. firstSet+descriptorSetCount-1] to use the bindings stored in pDescriptorSets[0..descriptorSetCount-1] for subsequent rendering commands (either compute or graphics, according to the pipelineBindPoint). Any bindings that were previously applied via these sets are no longer valid.

Once bound, a descriptor set affects rendering of subsequent graphics or compute commands in the command buffer until a different set is bound to the same set number, or else until the set is disturbed as described in Pipeline Layout Compatibility.

A compatible descriptor set must be bound for all set numbers that any shaders in a pipeline access, at the time that a draw or dispatch command is recorded to execute using that pipeline. However, if none of the shaders in a pipeline statically use any bindings with a particular set number, then no descriptor set need be bound for that set number, even if the pipeline layout includes a non-trivial descriptor set layout for that set number.

If any of the sets being bound include dynamic uniform or storage buffers, then pDynamicOffsets includes one element for each array element in each dynamic descriptor type binding in each set. Values are taken from pDynamicOffsets in an order such that all entries for set N come before set N+1; within a set, entries are ordered by the binding numbers in the descriptor set layouts; and within a binding array, elements are in order. dynamicOffsetCount must equal the total number of dynamic descriptors in the sets being bound.

The effective offset used for dynamic uniform and storage buffer bindings is the sum of the relative offset taken from pDynamicOffsets, and the base address of the buffer plus base offset in the descriptor set. The length of the dynamic uniform and storage buffer bindings is the buffer range as specified in the descriptor set.

Each of the pDescriptorSets must be compatible with the pipeline layout specified by layout. The layout used to program the bindings must also be compatible with the pipeline used in subsequent graphics or compute commands, as defined in the Pipeline Layout Compatibility section.

The descriptor set contents bound by a call to vkCmdBindDescriptorSets may be consumed during host execution of the command, or during shader execution of the resulting draws, or any time in between. Thus, the contents must not be altered (overwritten by an update command, or freed) between when the command is recorded and when the command completes executing on the queue. The contents of pDynamicOffsets are consumed immediately during execution of vkCmdBindDescriptorSets. Once all pending uses have completed, it is legal to update and reuse a descriptor set.

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • pipelineBindPoint must be a valid VkPipelineBindPoint value

    • layout must be a valid VkPipelineLayout handle

    • pDescriptorSets must be a pointer to an array of descriptorSetCount valid VkDescriptorSet handles

    • If dynamicOffsetCount is not 0, pDynamicOffsets must be a pointer to an array of dynamicOffsetCount uint32_t values

    • commandBuffer must be in the recording state

    • The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

    • descriptorSetCount must be greater than 0

    • Each of commandBuffer, layout, and the elements of pDescriptorSets must have been created, allocated, or retrieved from the same VkDevice

    • Any given element of pDescriptorSets must have been allocated with a VkDescriptorSetLayout that matches (is the same as, or defined identically to) the VkDescriptorSetLayout at set n in layout, where n is the sum of firstSet and the index into pDescriptorSets

    • dynamicOffsetCount must be equal to the total number of dynamic descriptors in pDescriptorSets

    • The sum of firstSet and descriptorSetCount must be less than or equal to VkPipelineLayoutCreateInfo::setLayoutCount provided when layout was created

    • pipelineBindPoint must be supported by the commandBuffer’s parent VkCommandPool’s queue family

    • Any given element of pDynamicOffsets must satisfy the required alignment for the corresponding descriptor binding’s descriptor type

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary Secondary | Both | GRAPHICS COMPUTE

SEE ALSO

VkCommandBuffer, VkDescriptorSet, VkPipelineBindPoint, VkPipelineLayout

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

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

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.