VkDescriptorPoolCreateInfo(3)

# VkDescriptorPoolCreateInfo(3) Manual Page

## Name

VkDescriptorPoolCreateInfo - Structure specifying parameters of a newly created descriptor pool

Loading… please wait.

## C Specification

Additional information about the pool is passed in a `VkDescriptorPoolCreateInfo` structure:

    // Provided by VK_VERSION_1_0
    typedef struct VkDescriptorPoolCreateInfo {
        VkStructureType                sType;
        const void*                    pNext;
        VkDescriptorPoolCreateFlags    flags;
        uint32_t                       maxSets;
        uint32_t                       poolSizeCount;
        const VkDescriptorPoolSize*    pPoolSizes;
    } VkDescriptorPoolCreateInfo;

## Members

- `sType` is the type of this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `flags` is a bitmask of VkDescriptorPoolCreateFlagBits specifying certain supported operations on the pool.

- `maxSets` is the maximum number of descriptor sets that can be allocated from the pool.

- `poolSizeCount` is the number of elements in `pPoolSizes`.

- `pPoolSizes` is a pointer to an array of VkDescriptorPoolSize structures, each containing a descriptor type and number of descriptors of that type to be allocated in the 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` bit set, descriptor pool creation may fail with the error `VK_ERROR_FRAGMENTATION` 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.

If a `pPoolSizes`[i]::`type` is `VK_DESCRIPTOR_TYPE_MUTABLE_VALVE`, a VkMutableDescriptorTypeCreateInfoVALVE struct in the `pNext` chain can be used to specify which mutable descriptor types can be allocated from the pool. If present in the `pNext` chain, VkMutableDescriptorTypeCreateInfoVALVE::`pMutableDescriptorTypeLists`[i] specifies which kind of `VK_DESCRIPTOR_TYPE_MUTABLE_VALVE` descriptors can be allocated from this pool entry. If VkMutableDescriptorTypeCreateInfoVALVE does not exist in the `pNext` chain, or VkMutableDescriptorTypeCreateInfoVALVE::`pMutableDescriptorTypeLists`[i] is out of range, the descriptor pool allocates enough memory to be able to allocate a `VK_DESCRIPTOR_TYPE_MUTABLE_VALVE` descriptor with any supported VkDescriptorType as a mutable descriptor. A mutable descriptor can be allocated from a pool entry if the type list in VkDescriptorSetLayoutCreateInfo is a subset of the type list declared in the descriptor pool, or if the pool entry is created without a descriptor type list. Multiple `pPoolSizes` entries with `VK_DESCRIPTOR_TYPE_MUTABLE_VALVE` can be declared. When multiple such pool entries are present in `pPoolSizes`, they specify sets of supported descriptor types which either fully overlap, partially overlap, or are disjoint. Two sets fully overlap if the sets of supported descriptor types are equal. If the sets are not disjoint they partially overlap. A pool entry without a `VkMutableDescriptorTypeListVALVE` assigned to it is considered to partially overlap any other pool entry which has a `VkMutableDescriptorTypeListVALVE` assigned to it. The application must ensure that partial overlap does not exist in `pPoolSizes`.

| Note The requirement of no partial overlap is intended to resolve ambiguity for validation as there is no confusion which `pPoolSizes` entries will be allocated from. An implementation is not expected to depend on this requirement.

Valid Usage

- VUID-VkDescriptorPoolCreateInfo-maxSets-00301
  `maxSets` must be greater than `0`

- VUID-VkDescriptorPoolCreateInfo-flags-04607
  If `flags` has the `VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE` bit set, then the `VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT` bit must not be set

- VUID-VkDescriptorPoolCreateInfo-mutableDescriptorType-04608
  If VkPhysicalDeviceMutableDescriptorTypeFeaturesVALVE::`mutableDescriptorType` is not enabled, `pPoolSizes` must not contain a `descriptorType` of `VK_DESCRIPTOR_TYPE_MUTABLE_VALVE`

- VUID-VkDescriptorPoolCreateInfo-flags-04609
  If `flags` has the `VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_VALVE` bit set, VkPhysicalDeviceMutableDescriptorTypeFeaturesVALVE::`mutableDescriptorType` must be enabled

- VUID-VkDescriptorPoolCreateInfo-pPoolSizes-04787
  If `pPoolSizes` contains a `descriptorType` of `VK_DESCRIPTOR_TYPE_MUTABLE_VALVE`, any other `VK_DESCRIPTOR_TYPE_MUTABLE_VALVE` element in `pPoolSizes` must not have sets of supported descriptor types which partially overlap

Valid Usage (Implicit)

- VUID-VkDescriptorPoolCreateInfo-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_CREATE_INFO`

- VUID-VkDescriptorPoolCreateInfo-pNext-pNext
  Each `pNext` member of any structure (including this one) in the `pNext` chain must be either `NULL` or a pointer to a valid instance of VkDescriptorPoolInlineUniformBlockCreateInfoEXT or VkMutableDescriptorTypeCreateInfoVALVE

- VUID-VkDescriptorPoolCreateInfo-sType-unique
  The `sType` value of each struct in the `pNext` chain must be unique

- VUID-VkDescriptorPoolCreateInfo-flags-parameter
  `flags` must be a valid combination of VkDescriptorPoolCreateFlagBits values

- VUID-VkDescriptorPoolCreateInfo-pPoolSizes-parameter
  `pPoolSizes` must be a valid pointer to an array of `poolSizeCount` valid VkDescriptorPoolSize structures

- VUID-VkDescriptorPoolCreateInfo-poolSizeCount-arraylength
  `poolSizeCount` must be greater than `0`

## See Also

VkDescriptorPoolCreateFlags, VkDescriptorPoolSize, VkStructureType, vkCreateDescriptorPool

## 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-2021 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0