VkDescriptorType - Specifies the type of a descriptor in a descriptor set

Description

• VK_DESCRIPTOR_TYPE_SAMPLER specifies a sampler descriptor.

• VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER specifies a combined image sampler descriptor.
• VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE specifies a sampled image descriptor.
• VK_DESCRIPTOR_TYPE_STORAGE_IMAGE specifies a storage image descriptor.
• VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER specifies a uniform texel buffer descriptor.
• VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER specifies a storage texel buffer descriptor.
• VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER specifies a uniform buffer descriptor.
• VK_DESCRIPTOR_TYPE_STORAGE_BUFFER specifies a storage buffer descriptor.
• VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC specifies a dynamic uniform buffer descriptor.
• VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC specifies a dynamic storage buffer descriptor.
• VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT specifies a input attachment descriptor.

When a descriptor set is updated via elements of VkWriteDescriptorSet, members of pImageInfo, pBufferInfo and pTexelBufferView are only accessed by the implementation when they correspond to descriptor type being defined - otherwise they are ignored. The members accessed are as follows for each descriptor type:

• For VK_DESCRIPTOR_TYPE_SAMPLER, only the sample member of each element of VkWriteDescriptorSet::pImageInfo is accessed.
• For VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, only the imageView and imageLayout members of each element of VkWriteDescriptorSet::pImageInfo are accessed.
• For VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, all members of each element of VkWriteDescriptorSet::pImageInfo are accessed.
• For VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, all members of each element of VkWriteDescriptorSet::pBufferInfo are accessed.
• For VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, each element of VkWriteDescriptorSet::pTexelBufferView is accessed.

See Also

VkDescriptorPoolSize, VkDescriptorSetLayoutBinding, VkDescriptorUpdateTemplateEntry, VkWriteDescriptorSet

VkDescriptorSetLayoutCreateFlagBits - Bitmask specifying descriptor set layout properties

See Also

VkDescriptorSetLayoutCreateFlags

VkDescriptorPoolCreateFlagBits - Bitmask specifying certain supported operations on a descriptor pool

See Also

VkDescriptorPoolCreateFlags

VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT specifies that descriptor sets can return their individual allocations to the pool, i.e. all of vkAllocateDescriptorSets, vkFreeDescriptorSets, and vkResetDescriptorPool are allowed. Otherwise, descriptor sets allocated from the pool must not be individually freed back to the pool, i.e. only vkAllocateDescriptorSets and vkResetDescriptorPool are allowed.

VkDescriptorPoolResetFlags - Reserved for future use

Description

VkDescriptorPoolResetFlags is a bitmask type for setting a mask, but is currently reserved for future use.

See Also

vkResetDescriptorPool

VkDescriptorSet - Opaque handle to a descriptor set object

See Also

VkCopyDescriptorSet, VkObjectTableDescriptorSetEntryNVX, VkWriteDescriptorSet, vkAllocateDescriptorSets, vkCmdBindDescriptorSets, vkFreeDescriptorSets, vkUpdateDescriptorSetWithTemplate, vkUpdateDescriptorSetWithTemplateKHR

VkDescriptorPool - Opaque handle to a descriptor pool object

See Also

VkDescriptorSetAllocateInfo, vkCreateDescriptorPool, vkDestroyDescriptorPool, vkFreeDescriptorSets, vkResetDescriptorPool

vkCreateDescriptorSetLayout - Create a new descriptor set layout

Parameters

• device is the logical device that creates the descriptor set layout.

• pCreateInfo is a pointer to an instance of the VkDescriptorSetLayoutCreateInfo structure specifying the state of the descriptor set layout object.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.
• pSetLayout points to a VkDescriptorSetLayout handle in which the resulting descriptor set layout object is returned.

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pCreateInfo must be a valid pointer to a valid VkDescriptorSetLayoutCreateInfo structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• pSetLayout must be a valid pointer to a VkDescriptorSetLayout handle

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkAllocationCallbacks, VkDescriptorSetLayout, VkDescriptorSetLayoutCreateInfo, VkDevice

vkDestroyDescriptorSetLayout - Destroy a descriptor set layout object

Parameters

• device is the logical device that destroys the descriptor set layout.

• descriptorSetLayout is the descriptor set layout to destroy.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

• If VkAllocationCallbacks were provided when descriptorSetLayout was created, a compatible set of callbacks must be provided here

• If no VkAllocationCallbacks were provided when descriptorSetLayout was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• If descriptorSetLayout is not VK_NULL_HANDLE, descriptorSetLayout must be a valid VkDescriptorSetLayout handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• If descriptorSetLayout is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to descriptorSetLayout must be externally synchronized

See Also

VkAllocationCallbacks, VkDescriptorSetLayout, VkDevice

vkCreateDescriptorPool - Creates a descriptor pool object

Parameters

• device is the logical device that creates the descriptor pool.

• pCreateInfo is a pointer to an instance of the VkDescriptorPoolCreateInfo structure specifying the state of the descriptor pool object.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.
• pDescriptorPool points to a VkDescriptorPool handle in which the resulting descriptor pool object is returned.

Description

pAllocator controls host memory allocation as described in the Memory Allocation chapter.

The created descriptor pool is returned in pDescriptorPool.

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pCreateInfo must be a valid pointer to a valid VkDescriptorPoolCreateInfo structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• pDescriptorPool must be a valid pointer to a VkDescriptorPool handle

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_FRAGMENTATION_EXT

See Also

VkAllocationCallbacks, VkDescriptorPool, VkDescriptorPoolCreateInfo, VkDevice

vkDestroyDescriptorPool - Destroy a descriptor pool object

Parameters

• device is the logical device that destroys the descriptor pool.

• descriptorPool is the descriptor pool to destroy.
• pAllocator controls host memory allocation as described in the Memory Allocation chapter.

Description

When a pool is destroyed, all descriptor sets allocated from the pool are implicitly freed and become invalid. Descriptor sets allocated from a given pool do not need to be freed before destroying that descriptor pool.

Valid Usage

• All submitted commands that refer to descriptorPool (via any allocated descriptor sets) must have completed execution

• If VkAllocationCallbacks were provided when descriptorPool was created, a compatible set of callbacks must be provided here
• If no VkAllocationCallbacks were provided when descriptorPool was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• If descriptorPool is not VK_NULL_HANDLE, descriptorPool must be a valid VkDescriptorPool handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• If descriptorPool is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to descriptorPool must be externally synchronized

See Also

VkAllocationCallbacks, VkDescriptorPool, VkDevice

vkResetDescriptorPool - Resets a descriptor pool object

Parameters

• device is the logical device that owns the descriptor pool.

• descriptorPool is the descriptor pool to be reset.
• flags is reserved for future use.

Description

Resetting a descriptor pool recycles all of the resources from all of the descriptor sets allocated from the descriptor pool back to the descriptor pool, and the descriptor sets are implicitly freed.

Valid Usage

• All uses of descriptorPool (via any allocated descriptor sets) must have completed execution

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• descriptorPool must be a valid VkDescriptorPool handle
• flags must be 0
• descriptorPool must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to descriptorPool must be externally synchronized

• Host access to any VkDescriptorSet objects allocated from descriptorPool must be externally synchronized

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkDescriptorPool, VkDescriptorPoolResetFlags, VkDevice

vkAllocateDescriptorSets - Allocate one or more descriptor sets

Parameters

• device is the logical device that owns the descriptor pool.

• pAllocateInfo is a pointer to an instance of the VkDescriptorSetAllocateInfo structure describing parameters of the allocation.
• pDescriptorSets is a pointer to an array of VkDescriptorSet handles in which the resulting descriptor set objects are returned.

Description

The allocated descriptor sets are returned in pDescriptorSets.

When a descriptor set is allocated, the initial state is largely uninitialized and all descriptors are undefined. However, the descriptor set can be bound in a command buffer without causing errors or exceptions. For descriptor set bindings created with the VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT_EXT bit set, all descriptors in that binding that are dynamically used must have been populated before the descriptor set is consumed. For descriptor set bindings created without the VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT_EXT bit set, all descriptors in that binding that are statically used must have been populated before the descriptor set is consumed. Entries that are not used by a pipeline can have uninitialized descriptors or descriptors of resources that have been destroyed, and executing a draw or dispatch with such a descriptor set bound does not cause undefined behavior. This means applications need not populate unused entries with dummy descriptors.

If a call to vkAllocateDescriptorSets would cause the total number of descriptor sets allocated from the pool to exceed the value of VkDescriptorPoolCreateInfo::maxSets used to create pAllocateInfo→descriptorPool, then the allocation may fail due to lack of space in the descriptor pool. Similarly, the allocation may fail due to lack of space if the call to vkAllocateDescriptorSets would cause the number of any given descriptor type to exceed the sum of all the descriptorCount members of each element of VkDescriptorPoolCreateInfo::pPoolSizes with a member equal to that type. If the allocation fails due to no more space in the descriptor pool, and not because of system or device memory exhaustion, then VK_ERROR_OUT_OF_POOL_MEMORY must be returned.

vkAllocateDescriptorSets can be used to create multiple descriptor sets. If the creation of any of those descriptor sets fails, then the implementation must destroy all successfully created descriptor set objects from this command, set all entries of the pDescriptorSets array to VK_NULL_HANDLE and return the error.

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pAllocateInfo must be a valid pointer to a valid VkDescriptorSetAllocateInfo structure
• pDescriptorSets must be a valid pointer to an array of pAllocateInfo::descriptorSetCount VkDescriptorSet handles

Host Synchronization

• Host access to pAllocateInfo::descriptorPool must be externally synchronized

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_FRAGMENTED_POOL

• VK_ERROR_OUT_OF_POOL_MEMORY

See Also

VkDescriptorSet, VkDescriptorSetAllocateInfo, VkDevice

vkFreeDescriptorSets - Free one or more descriptor sets

Parameters

• device is the logical device that owns the descriptor pool.

• descriptorPool is the descriptor pool from which the descriptor sets were allocated.
• descriptorSetCount is the number of elements in the pDescriptorSets array.
• pDescriptorSets is an array of handles to VkDescriptorSet objects.

Description

After a successful call to vkFreeDescriptorSets, all descriptor sets in pDescriptorSets are invalid.

Valid Usage

• All submitted commands that refer to any element of pDescriptorSets must have completed execution

• pDescriptorSets must be a valid pointer to an array of descriptorSetCount VkDescriptorSet handles, each element of which must either be a valid handle or VK_NULL_HANDLE
• Each valid handle in pDescriptorSets must have been allocated from descriptorPool
• descriptorPool must have been created with the VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT flag

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• descriptorPool must be a valid VkDescriptorPool handle
• descriptorSetCount must be greater than 0
• descriptorPool must have been created, allocated, or retrieved from device
• Each element of pDescriptorSets that is a valid handle must have been created, allocated, or retrieved from descriptorPool

Host Synchronization

• Host access to descriptorPool must be externally synchronized

• Host access to each member of pDescriptorSets must be externally synchronized

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkDescriptorPool, VkDescriptorSet, VkDevice

vkUpdateDescriptorSets - Update the contents of a descriptor set object

Parameters

• device is the logical device that updates the descriptor sets.

• descriptorWriteCount is the number of elements in the pDescriptorWrites array.
• pDescriptorWrites is a pointer to an array of VkWriteDescriptorSet structures describing the descriptor sets to write to.
• descriptorCopyCount is the number of elements in the pDescriptorCopies array.
• pDescriptorCopies is a pointer to an array of VkCopyDescriptorSet structures describing the descriptor sets to copy between.

Description

The operations described by pDescriptorWrites are performed first, followed by the operations described by pDescriptorCopies. Within each array, the operations are performed in the order they appear in the array.

Each element in the pDescriptorWrites array describes an operation updating the descriptor set using descriptors for resources specified in the structure.

Each element in the pDescriptorCopies array is a VkCopyDescriptorSet structure describing an operation copying descriptors between sets.

If the dstSet member of any element of pDescriptorWrites or pDescriptorCopies is bound, accessed, or modified by any command that was recorded to a command buffer which is currently in the recording or executable state, and any of the descriptor bindings that are updated were not created with the VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT or VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT_EXT bits set, that command buffer becomes invalid.

Valid Usage

• Descriptor bindings updated by this command which were created without the VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT or VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT_EXT bits set must not be used by any command that was recorded to a command buffer which is in the pending state.

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• If descriptorWriteCount is not 0, pDescriptorWrites must be a valid pointer to an array of descriptorWriteCount valid VkWriteDescriptorSet structures
• If descriptorCopyCount is not 0, pDescriptorCopies must be a valid pointer to an array of descriptorCopyCount valid VkCopyDescriptorSet structures

Host Synchronization

• Host access to pDescriptorWrites[].dstSet must be externally synchronized

• Host access to pDescriptorCopies[].dstSet must be externally synchronized

See Also

VkCopyDescriptorSet, VkDevice, VkWriteDescriptorSet

VkDescriptorBufferInfo - Structure specifying descriptor buffer info

Description

Note

When setting range to VK_WHOLE_SIZE, the effective range must not be larger than the maximum range for the descriptor type ([maxUniformBufferRange](https:/www.khronos.orgregistryvulkanspecs1.0-extensionshtml/vkspec.html#features-limits-maxUniformBufferRange) or maxStorageBufferRange). This means that VK_WHOLE_SIZE is not typically useful in the common case where uniform buffer descriptors are suballocated from a buffer that is much larger than maxUniformBufferRange.

For VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC and VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC descriptor types, offset is the base offset from which the dynamic offset is applied and range is the static size used for all dynamic offsets.

Valid Usage

• offset must be less than the size of buffer

• If range is not equal to VK_WHOLE_SIZE, range must be greater than 0
• If range is not equal to VK_WHOLE_SIZE, range must be less than or equal to the size of buffer minus offset

Valid Usage (Implicit)

• buffer must be a valid VkBuffer handle

See Also

VkBuffer, VkDeviceSize, VkWriteDescriptorSet

VkDescriptorImageInfo - Structure specifying descriptor image info

Description

Members of VkDescriptorImageInfo that are not used in an update (as described above) are ignored.

Valid Usage

• imageView must not be 2D or 2D array image view created from a 3D image

• imageLayout must match the actual VkImageLayout of each subresource accessible from imageView at the time this descriptor is accessed

• If sampler is used and enables sampler Y’CBCR conversion:

  • The format of the imageView must be the same as the VkFormat of the image
  • The aspectMask of the imageView must be VK_IMAGE_ASPECT_COLOR_BIT
  • The components.a of the imageView must be VK_COMPONENT_SWIZZLE_IDENTITY
  • The components.r of the imageView must be VK_COMPONENT_SWIZZLE_IDENTITY
  • The components.g of the imageView must be VK_COMPONENT_SWIZZLE_IDENTITY
  • The components.b of the imageView must be VK_COMPONENT_SWIZZLE_IDENTITY
  • The pNext chain of the imageView must contain a VkSamplerYcbcrConversionInfo which has a conversion which is an identically defined object to the conversion of the VkSamplerYcbcrConversionInfo which is in the pNext chain of the sampler
• If sampler is used and does not enable sampler Y’CBCR conversion and the VkFormat of the image is a multi-planar format, the image must have been created with VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, and the aspectMask of the imageView must be VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT or (for three-plane formats only) VK_IMAGE_ASPECT_PLANE_2_BIT

Valid Usage (Implicit)

• Both of imageView, and sampler that are valid handles must have been created, allocated, or retrieved from the same VkDevice

See Also

VkImageLayout, VkImageView, VkSampler, VkWriteDescriptorSet

VkWriteDescriptorSet - Structure specifying the parameters of a descriptor set write operation

Description

Only one of pImageInfo, pBufferInfo, or pTexelBufferView members is used according to the descriptor type specified in the descriptorType member of the containing VkWriteDescriptorSet structure, as specified below.

If the dstBinding has fewer than descriptorCount array elements remaining starting from dstArrayElement, then the remainder will be used to update the subsequent binding - dstBinding+1 starting at array element zero. If a binding has a descriptorCount of zero, it is skipped. This behavior applies recursively, with the update affecting consecutive bindings as needed to update all descriptorCount descriptors.

Valid Usage

• dstBinding must be less than or equal to the maximum value of binding of all VkDescriptorSetLayoutBinding structures specified when dstSet’s descriptor set layout was created

• dstBinding must be a binding with a non-zero descriptorCount
• All consecutive bindings updated via a single VkWriteDescriptorSet structure, except those with a descriptorCount of zero, must have identical descriptorType and stageFlags.
• All consecutive bindings updated via a single VkWriteDescriptorSet structure, except those with a descriptorCount of zero, must all either use immutable samplers or must all not use immutable samplers.
• descriptorType must match the type of dstBinding within dstSet
• dstSet must be a valid VkDescriptorSet handle
• The sum of dstArrayElement and descriptorCount must be less than or equal to the number of array elements in the descriptor set binding specified by dstBinding, and all applicable consecutive bindings, as described by {html_spec_relative}#descriptorsets-updates-consecutive
• If descriptorType is VK_DESCRIPTOR_TYPE_SAMPLER, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, pImageInfo must be a valid pointer to an array of descriptorCount valid VkDescriptorImageInfo structures
• If descriptorType is VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, pTexelBufferView must be a valid pointer to an array of descriptorCount valid VkBufferView handles
• If descriptorType is VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, pBufferInfo must be a valid pointer to an array of descriptorCount valid VkDescriptorBufferInfo structures
• If descriptorType is VK_DESCRIPTOR_TYPE_SAMPLER or VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and dstSet was not allocated with a layout that included immutable samplers for dstBinding with descriptorType, the sampler member of each element of pImageInfo must be a valid VkSampler object
• If descriptorType is VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the imageView and imageLayout members of each element of pImageInfo must be a valid VkImageView and VkImageLayout, respectively
• If descriptorType is VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, for each descriptor that will be accessed via load or store operations the imageLayout member for corresponding elements of pImageInfo must be VK_IMAGE_LAYOUT_GENERAL
• If descriptorType is VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the offset member of each element of pBufferInfo must be a multiple of VkPhysicalDeviceLimits::minUniformBufferOffsetAlignment
• If descriptorType is VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the offset member of each element of pBufferInfo must be a multiple of VkPhysicalDeviceLimits::minStorageBufferOffsetAlignment
• If descriptorType is VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, and the buffer member of any element of pBufferInfo is the handle of a non-sparse buffer, then that buffer must be bound completely and contiguously to a single VkDeviceMemory object
• If descriptorType is VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the buffer member of each element of pBufferInfo must have been created with VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT set
• If descriptorType is VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the buffer member of each element of pBufferInfo must have been created with VK_BUFFER_USAGE_STORAGE_BUFFER_BIT set
• If descriptorType is VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, the range member of each element of pBufferInfo, or the effective range if range is VK_WHOLE_SIZE, must be less than or equal to VkPhysicalDeviceLimits::maxUniformBufferRange
• If descriptorType is VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the range member of each element of pBufferInfo, or the effective range if range is VK_WHOLE_SIZE, must be less than or equal to VkPhysicalDeviceLimits::maxStorageBufferRange
• If descriptorType is VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER, the VkBuffer that each element of pTexelBufferView was created from must have been created with VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT set
• If descriptorType is VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, the VkBuffer that each element of pTexelBufferView was created from must have been created with VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT set
• If descriptorType is VK_DESCRIPTOR_TYPE_STORAGE_IMAGE or VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the imageView member of each element of pImageInfo must have been created with the identity swizzle
• If descriptorType is VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the imageView member of each element of pImageInfo must have been created with VK_IMAGE_USAGE_SAMPLED_BIT set
• If descriptorType is VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the imageLayout member of each element of pImageInfo must be VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL or VK_IMAGE_LAYOUT_GENERAL
• If descriptorType is VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the imageView member of each element of pImageInfo must have been created with VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set
• If descriptorType is VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, the imageView member of each element of pImageInfo must have been created with VK_IMAGE_USAGE_STORAGE_BIT set
• All consecutive bindings updated via a single VkWriteDescriptorSet structure, except those with a descriptorCount of zero, must have identical VkDescriptorBindingFlagBitsEXT.

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET

• pNext must be NULL
• descriptorType must be a valid VkDescriptorType value
• descriptorCount must be greater than 0
• Both of dstSet, and the elements of pTexelBufferView that are valid handles must have been created, allocated, or retrieved from the same VkDevice

See Also

VkBufferView, VkDescriptorBufferInfo, VkDescriptorImageInfo, VkDescriptorSet, VkDescriptorType, VkStructureType, vkCmdPushDescriptorSetKHR, vkUpdateDescriptorSets

VkCopyDescriptorSet - Structure specifying a copy descriptor set operation

Valid Usage

• srcBinding must be a valid binding within srcSet

• The sum of srcArrayElement and descriptorCount must be less than or equal to the number of array elements in the descriptor set binding specified by srcBinding, and all applicable consecutive bindings, as described by {html_spec_relative}#descriptorsets-updates-consecutive
• dstBinding must be a valid binding within dstSet
• The sum of dstArrayElement and descriptorCount must be less than or equal to the number of array elements in the descriptor set binding specified by dstBinding, and all applicable consecutive bindings, as described by {html_spec_relative}#descriptorsets-updates-consecutive
• If srcSet is equal to dstSet, then the source and destination ranges of descriptors must not overlap, where the ranges may include array elements from consecutive bindings as described by {html_spec_relative}#descriptorsets-updates-consecutive
• If srcSet’s layout was created with the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT flag set, then dstSet’s layout must also have been created with the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT flag set
• If srcSet’s layout was created without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT flag set, then dstSet’s layout must also have been created without the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT flag set
• If the descriptor pool from which srcSet was allocated was created with the VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT flag set, then the descriptor pool from which dstSet was allocated must also have been created with the VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT flag set
• If the descriptor pool from which srcSet was allocated was created without the VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT flag set, then the descriptor pool from which dstSet was allocated must also have been created without the VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT flag set

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_COPY_DESCRIPTOR_SET

• pNext must be NULL
• srcSet must be a valid VkDescriptorSet handle
• dstSet must be a valid VkDescriptorSet handle
• Both of dstSet, and srcSet must have been created, allocated, or retrieved from the same VkDevice

See Also

VkDescriptorSet, VkStructureType, vkUpdateDescriptorSets

VkDescriptorSetLayoutBinding - Structure specifying a descriptor set layout binding

Members

• binding is the binding number of this entry and corresponds to a resource of the same binding number in the shader stages.

• descriptorType is a VkDescriptorType specifying which type of resource descriptors are used for this binding.
• descriptorCount is the number of descriptors contained in the binding, accessed in a shader as an array. If descriptorCount is zero this binding entry is reserved and the resource must not be accessed from any stage via this binding within any pipeline using the set layout.

• stageFlags member is a bitmask of VkShaderStageFlagBits specifying which pipeline shader stages can access a resource for this binding. VK_SHADER_STAGE_ALL is a shorthand specifying that all defined shader stages, including any additional stages defined by extensions, can access the resource.

  If a shader stage is not included in stageFlags, then a resource must not be accessed from that stage via this binding within any pipeline using the set layout. Other than input attachments which are limited to the fragment shader, there are no limitations on what combinations of stages can use a descriptor binding, and in particular a binding can be used by both graphics stages and the compute stage.

Description

• pImmutableSamplers affects initialization of samplers. If descriptorType specifies a VK_DESCRIPTOR_TYPE_SAMPLER or VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER type descriptor, then pImmutableSamplers can be used to initialize a set of /immutable samplers/. Immutable samplers are permanently bound into the set layout; later binding a sampler into an immutable sampler slot in a descriptor set is not allowed. If pImmutableSamplers is not NULL, then it is considered to be a pointer to an array of sampler handles that will be consumed by the set layout and used for the corresponding binding. If pImmutableSamplers is NULL, then the sampler slots are dynamic and sampler handles must be bound into descriptor sets using this layout. If descriptorType is not one of these descriptor types, then pImmutableSamplers is ignored.

The above layout definition allows the descriptor bindings to be specified sparsely such that not all binding numbers between 0 and the maximum binding number need to be specified in the pBindings array. Bindings that are not specified have a descriptorCount and stageFlags of zero, and the descriptorType is treated as undefined. However, all binding numbers between 0 and the maximum binding number in the VkDescriptorSetLayoutCreateInfo::pBindings array may consume memory in the descriptor set layout even if not all descriptor bindings are used, though it should not consume additional memory from the descriptor pool.

Note

The maximum binding number specified should be as compact as possible to avoid wasted memory.

Valid Usage

• If descriptorType is VK_DESCRIPTOR_TYPE_SAMPLER or VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and descriptorCount is not 0 and pImmutableSamplers is not NULL, pImmutableSamplers must be a valid pointer to an array of descriptorCount valid VkSampler handles

• If descriptorCount is not 0, stageFlags must be a valid combination of VkShaderStageFlagBits values
• If descriptorType is VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT and descriptorCount is not 0, then stageFlags must be 0 or VK_SHADER_STAGE_FRAGMENT_BIT

Valid Usage (Implicit)

• descriptorType must be a valid VkDescriptorType value

See Also

VkDescriptorSetLayoutCreateInfo, VkDescriptorType, VkSampler, VkShaderStageFlags

VkDescriptorSetLayoutCreateInfo - Structure specifying parameters of a newly created descriptor set layout

Valid Usage

• The VkDescriptorSetLayoutBinding::binding members of the elements of the pBindings array must each have different values.

• If flags contains VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then all elements of pBindings must not have a descriptorType of VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC
• If flags contains VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR, then the total number of elements of all bindings must be less than or equal to VkPhysicalDevicePushDescriptorPropertiesKHR::maxPushDescriptors
• If any binding has the VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT bit set, flags must include VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT
• If any binding has the VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT_EXT bit set, then all bindings must not have descriptorType of VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO

• pNext must be NULL or a pointer to a valid instance of VkDescriptorSetLayoutBindingFlagsCreateInfoEXT
• flags must be a valid combination of VkDescriptorSetLayoutCreateFlagBits values
• If bindingCount is not 0, pBindings must be a valid pointer to an array of bindingCount valid VkDescriptorSetLayoutBinding structures

See Also

VkDescriptorSetLayoutBinding, VkDescriptorSetLayoutCreateFlags, VkStructureType, vkCreateDescriptorSetLayout, vkGetDescriptorSetLayoutSupport, vkGetDescriptorSetLayoutSupportKHR

VkDescriptorPoolSize - Structure specifying descriptor pool size

Valid Usage

• descriptorCount must be greater than 0

Valid Usage (Implicit)

• type must be a valid VkDescriptorType value

See Also

VkDescriptorPoolCreateInfo, VkDescriptorType

VkDescriptorPoolCreateInfo - Structure specifying parameters of a newly created descriptor pool

Description

If multiple VkDescriptorPoolSize structures appear in the pPoolSizes array then the pool will be created with enough storage for the total number of descriptors of each type.

Fragmentation of a descriptor pool is possible and may lead to descriptor set allocation failures. A failure due to fragmentation is defined as failing a descriptor set allocation despite the sum of all outstanding descriptor set allocations from the pool plus the requested allocation requiring no more than the total number of descriptors requested at pool creation. Implementations provide certain guarantees of when fragmentation must not cause allocation failure, as described below.

If a descriptor pool has not had any descriptor sets freed since it was created or most recently reset then fragmentation must not cause an allocation failure (note that this is always the case for a pool created without the VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT bit set). Additionally, if all sets allocated from the pool since it was created or most recently reset use the same number of descriptors (of each type) and the requested allocation also uses that same number of descriptors (of each type), then fragmentation must not cause an allocation failure.

If an allocation failure occurs due to fragmentation, an application can create an additional descriptor pool to perform further descriptor set allocations.

If flags has the VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT bit set, descriptor pool creation may fail with the error VK_ERROR_FRAGMENTATION_EXT if the total number of descriptors across all pools (including this one) created with this bit set exceeds maxUpdateAfterBindDescriptorsInAllPools, or if fragmentation of the underlying hardware resources occurs.

Valid Usage

• maxSets must be greater than 0

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_CREATE_INFO

• pNext must be NULL
• flags must be a valid combination of VkDescriptorPoolCreateFlagBits values
• pPoolSizes must be a valid pointer to an array of poolSizeCount valid VkDescriptorPoolSize structures
• poolSizeCount must be greater than 0

See Also

VkDescriptorPoolCreateFlags, VkDescriptorPoolSize, VkStructureType, vkCreateDescriptorPool

VkDescriptorSetAllocateInfo - Structure specifying the allocation parameters for descriptor sets

Valid Usage

• Each element of pSetLayouts must not have been created with VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR set

• If any element of pSetLayouts was created with the VK_DESCRIPTOR_SET_LAYOUT_CREATE_UPDATE_AFTER_BIND_POOL_BIT_EXT bit set, descriptorPool must have been created with the VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT flag set

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_DESCRIPTOR_SET_ALLOCATE_INFO

• pNext must be NULL or a pointer to a valid instance of VkDescriptorSetVariableDescriptorCountAllocateInfoEXT
• descriptorPool must be a valid VkDescriptorPool handle
• pSetLayouts must be a valid pointer to an array of descriptorSetCount valid VkDescriptorSetLayout handles
• descriptorSetCount must be greater than 0
• Both of descriptorPool, and the elements of pSetLayouts must have been created, allocated, or retrieved from the same VkDevice

See Also

VkDescriptorPool, VkDescriptorSetLayout, VkStructureType, vkAllocateDescriptorSets

VkDescriptorSetLayoutCreateFlags - Bitmask of VkDescriptorSetLayoutCreateFlagBits

Description

VkDescriptorSetLayoutCreateFlags is a bitmask type for setting a mask of zero or more VkDescriptorSetLayoutCreateFlagBits.

See Also

VkDescriptorSetLayoutCreateFlagBits, VkDescriptorSetLayoutCreateInfo

VkDescriptorPoolCreateFlags - Bitmask of VkDescriptorPoolCreateFlagBits

Description

VkDescriptorPoolCreateFlags is a bitmask type for setting a mask of zero or more VkDescriptorPoolCreateFlagBits.

See Also

VkDescriptorPoolCreateFlagBits, VkDescriptorPoolCreateInfo