C Specification
To bind one or more descriptor sets to a command buffer, call:
// Provided by VK_VERSION_1_0
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 the type of the pipeline that will use the descriptors. There is a separate set of bind points for each pipeline type, so binding one does not disturb the others. -
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 thepDescriptorSets
array. -
pDescriptorSets
is a pointer to an array of handles to VkDescriptorSet objects describing the descriptor sets to bind to. -
dynamicOffsetCount
is the number of dynamic offsets in thepDynamicOffsets
array. -
pDynamicOffsets
is a pointer to an array ofuint32_t
values specifying dynamic offsets.
Description
vkCmdBindDescriptorSets
binds descriptor sets
pDescriptorSets
[0..descriptorSetCount
-1] to set numbers
[firstSet
..firstSet
+descriptorSetCount
-1] for subsequent
bound pipeline commands set by
pipelineBindPoint
.
Any bindings that were previously applied via these sets
, or calls to vkCmdSetDescriptorBufferOffsetsEXT or
vkCmdBindDescriptorBufferEmbeddedSamplersEXT,
are no longer valid.
Once bound, a descriptor set affects rendering of subsequent commands that interact with the given pipeline type in the command buffer until either a different set is bound to the same set number, or 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 drawing or dispatching 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.
When consuming a descriptor, a descriptor is considered valid if the
descriptor is not undefined as described by
descriptor set allocation.
If the nullDescriptor
feature is enabled,
a null descriptor is also considered valid.
A descriptor that was disturbed by Pipeline
Layout Compatibility, or was never bound by vkCmdBindDescriptorSets
is not considered valid.
If a pipeline accesses a descriptor either statically or dynamically
depending on the VkDescriptorBindingFlagBits, the consuming descriptor
type in the pipeline must match the VkDescriptorType in
VkDescriptorSetLayoutCreateInfo for the descriptor to be considered
valid.
If a descriptor is a mutable descriptor, the consuming descriptor type in
the pipeline must match the active descriptor type for the descriptor to be
considered valid.
Note
Further validation may be carried out beyond validation for descriptor types, e.g. Texel Input Validation. |
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 range 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 bound pipeline
commands with that pipeline type, as defined in the
Pipeline Layout Compatibility section.
The descriptor set contents bound by a call to vkCmdBindDescriptorSets
may be consumed at the following times:
-
For descriptor bindings created with the
VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT
bit set, the contents may be consumed when the command buffer is submitted to a queue, or during shader execution of the resulting draws and dispatches, or any time in between. Otherwise, -
during host execution of the command, or during shader execution of the resulting draws and dispatches, or any time in between.
Thus, the contents of a descriptor set binding must not be altered (overwritten by an update command, or freed) between the first point in time that it may be consumed, 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.
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.