vkAllocateDescriptorSets(3)

# vkAllocateDescriptorSets(3) Manual Page

## Name

vkAllocateDescriptorSets - Allocate one or more descriptor sets

Loading… please wait.

## C Specification

To allocate descriptor sets from a descriptor pool, call:

    // Provided by VK_VERSION_1_0
    VkResult vkAllocateDescriptorSets(
        VkDevice                                    device,
        const VkDescriptorSetAllocateInfo*          pAllocateInfo,
        VkDescriptorSet*                            pDescriptorSets);

## Parameters

- `device` is the logical device that owns the descriptor pool.

- `pAllocateInfo` is a pointer to a 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, with the exception that samplers with a non-null `pImmutableSamplers` are initialized on allocation. Descriptors also become undefined if the underlying resource or view object is destroyed. Descriptor sets containing undefined descriptors can still be bound and used, subject to the following conditions:

- For descriptor set bindings created with the `VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT` 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` bit set, all descriptors in that binding that are statically used must have been populated before the descriptor set is consumed.

- Descriptor bindings with descriptor type of `VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK` can be undefined when the descriptor set is consumed; though values in that block will be undefined.

- Entries that are not used by a pipeline can have undefined 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 `type` equal to that type.

Additionally, the allocation may also fail if a call to `vkAllocateDescriptorSets` would cause the total number of inline uniform block bindings allocated from the pool to exceed the value of VkDescriptorPoolInlineUniformBlockCreateInfo::`maxInlineUniformBlockBindings` used to create the descriptor pool.

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)

- VUID-vkAllocateDescriptorSets-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkAllocateDescriptorSets-pAllocateInfo-parameter
  `pAllocateInfo` must be a valid pointer to a valid VkDescriptorSetAllocateInfo structure

- VUID-vkAllocateDescriptorSets-pDescriptorSets-parameter
  `pDescriptorSets` must be a valid pointer to an array of `pAllocateInfo->descriptorSetCount` VkDescriptorSet handles

- VUID-vkAllocateDescriptorSets-pAllocateInfo::descriptorSetCount-arraylength
  `pAllocateInfo->descriptorSetCount` must be greater than `0`

Host Synchronization

- Host access to `pAllocateInfo->descriptorPool` must be externally synchronized

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_FRAGMENTED_POOL`

  - `VK_ERROR_OUT_OF_POOL_MEMORY`

## See Also

VK_VERSION_1_0, VkDescriptorSet, VkDescriptorSetAllocateInfo, VkDevice

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