VKALLOCATEDESCRIPTOR(3)

NAME
vkAllocateDescriptorSets - Allocate one or more descriptor sets.

C SPECIFICATION

To allocate descriptor sets from a descriptor pool, call:

    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 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. The array must be at least the length specified by the descriptorSetCount member of pAllocateInfo.

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. All entries that are statically used by a pipeline in a drawing or dispatching command must have been populated before the descriptor set is bound for use by that command. Entries that are not statically 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 an allocation fails due to fragmentation, an indeterminate error is returned with an unspecified error code. Any returned error other than VK_ERROR_FRAGMENTED_POOL does not imply its usual meaning: applications should assume that the allocation failed due to fragmentation, and create a new descriptor pool.

    Note

    Applications should check for a negative return value when allocating new descriptor sets, assume that any error effectively means VK_ERROR_FRAGMENTED_POOL, and try to create a new descriptor pool. If VK_ERROR_FRAGMENTED_POOL is the actual return value, it adds certainty to that decision.

    The reason for this is that VK_ERROR_FRAGMENTED_POOL was only added in a later revision of the 1.0 specification, and so drivers may return other errors if they were written against earlier revisions. To ensure full compatibility with earlier patch revisions, these other errors are allowed.

VALID USAGE

    • device must be a valid VkDevice handle

    • pAllocateInfo must be a pointer to a valid VkDescriptorSetAllocateInfo structure

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

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

SEE ALSO

VkDescriptorSet, VkDescriptorSetAllocateInfo, VkDevice

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

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

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.