Magnum::Vk::DescriptorPool class new in Git master
#include <Magnum/Vk/DescriptorPool.h>

Descriptor pool.

Wraps VkDescriptorPool, which is used for allocating descriptor sets.

Descriptor pool creation

The DescriptorPoolCreateInfo class takes a maximum number of descriptor sets that can be allocated from a pool and then a list of total available descriptor counts for desired DescriptorTypes. The following snippet creates a pool allowing to allocate at most 8 descriptor sets with 24 sampler bindings and 16 uniform bindings:

#include <Magnum/Vk/DescriptorPoolCreateInfo.h>

…

Vk::DescriptorPool pool{device, Vk::DescriptorPoolCreateInfo{8, {
    {Vk::DescriptorType::UniformBuffer, 24},
    {Vk::DescriptorType::CombinedImageSampler, 16}
}}};

With a descriptor pool created, you can allocate descriptor sets from it. See the DescriptorSet class for details.

Public static functions

static auto wrap(Device& device, VkDescriptorPool handle, HandleFlags flags = {}) -> DescriptorPool: Wrap existing Vulkan handle.

Constructors, destructors, conversion operators

DescriptorPool(Device& device, const DescriptorPoolCreateInfo& info) explicit: Constructor.
DescriptorPool(NoCreateT) explicit: Construct without creating the fence.
DescriptorPool(const DescriptorPool&) deleted: Copying is not allowed.
DescriptorPool(DescriptorPool&& other) noexcept: Move constructor.
~DescriptorPool(): Destructor.
operator VkDescriptorPool()

Public functions

auto operator=(const DescriptorPool&) -> DescriptorPool& deleted: Copying is not allowed.
auto operator=(DescriptorPool&& other) -> DescriptorPool& noexcept: Move assignment.
auto handle() -> VkDescriptorPool: Underlying VkDescriptorPool handle.
auto handleFlags() const -> HandleFlags: Handle flags.
auto allocate(VkDescriptorSetLayout layout) -> DescriptorSet: Allocate a single descriptor set.
auto tryAllocate(VkDescriptorSetLayout layout) -> Containers::Optional<DescriptorSet>: Try to allocate a single descriptor set.
auto allocate(VkDescriptorSetLayout layout, UnsignedInt variableDescriptorCount) -> DescriptorSet: Allocate a single descriptor set with a variable descriptor count.
auto tryAllocate(VkDescriptorSetLayout layout, UnsignedInt variableDescriptorCount) -> Containers::Optional<DescriptorSet>: Try to allocate a single descriptor set with a variable descriptor count.
void reset(): Reset the pool.
auto release() -> VkDescriptorPool: Release the underlying Vulkan descriptor pool.

Function documentation

static DescriptorPool Magnum::Vk::DescriptorPool::wrap(Device& device, VkDescriptorPool handle, HandleFlags flags = {})

Wrap existing Vulkan handle.

Parameters
device	Vulkan device the descriptor pool is created on
handle	The VkDescriptorPool handle
flags	Handle flags

The handle is expected to be originating from device. Unlike a descriptor pool created using a constructor, the Vulkan descriptor pool is by default not deleted on destruction, use flags for different behavior.

Magnum::Vk::DescriptorPool::DescriptorPool(Device& device, const DescriptorPoolCreateInfo& info) explicit

Constructor.

Parameters
device	Vulkan device to create the descriptor pool on
info	Descriptor pool creation info

Magnum::Vk::DescriptorPool::DescriptorPool(NoCreateT) explicit

Construct without creating the fence.

The constructed instance is equivalent to moved-from state. Useful in cases where you will overwrite the instance later anyway. Move another object over it to make it useful.

Magnum::Vk::DescriptorPool::~DescriptorPool()

Destructor.

Destroys associated VkDescriptorPool handle, unless the instance was created using wrap() without HandleFlag::DestroyOnDestruction specified.

Magnum::Vk::DescriptorPool::operator VkDescriptorPool()

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

DescriptorSet Magnum::Vk::DescriptorPool::allocate(VkDescriptorSetLayout layout)

Allocate a single descriptor set.

If layout contains a binding with DescriptorSetLayoutBinding::Flag::VariableDescriptorCount set, the allocated descriptor count will be 0. Use allocate(VkDescriptorSetLayout, UnsignedInt) in that case instead.

If allocation fails due to exhaustion of pool memory or due to fragmentation, the function aborts with an error message. For graceful handling of such failures use tryAllocate(VkDescriptorSetLayout) instead.

Containers::Optional<DescriptorSet> Magnum::Vk::DescriptorPool::tryAllocate(VkDescriptorSetLayout layout)

Try to allocate a single descriptor set.

Compared to allocate(VkDescriptorSetLayout), if the allocation fails with Result::ErrorOutOfPoolMemory or Result::ErrorFragmentedPool, Containers::NullOpt is returned instead of aborting to allow the application to recover and choose a different strategy.

If Vulkan 1.1 is not supported by the device and the KHR_maintenance1 extension isn't enabled on the device, allocation failures are treated as user error the driver is free to do basically anything. Fortunately most implementations support this extension nowadays and so it should be safe to assume Result::ErrorOutOfPoolMemory gets properly returned in case of a failure.

DescriptorSet Magnum::Vk::DescriptorPool::allocate(VkDescriptorSetLayout layout, UnsignedInt variableDescriptorCount)

Allocate a single descriptor set with a variable descriptor count.

Compared to allocate(VkDescriptorSetLayout), the variableDescriptorCount is used for a binding that was created with DescriptorSetLayoutBinding::Flag::VariableDescriptorCount and is expected to not be larger than the the count specified in the layout.

Containers::Optional<DescriptorSet> Magnum::Vk::DescriptorPool::tryAllocate(VkDescriptorSetLayout layout, UnsignedInt variableDescriptorCount)

Try to allocate a single descriptor set with a variable descriptor count.

Compared to allocate(VkDescriptorSetLayout, UnsignedInt), if the allocation fails with Result::ErrorOutOfPoolMemory or Result::ErrorFragmentedPool, Containers::NullOpt is returned instead of aborting to allow the application to recover and choose a different strategy.

void Magnum::Vk::DescriptorPool::reset()

Reset the pool.

Frees all descriptor sets allocated from this pool, making it empty again.

VkDescriptorPool Magnum::Vk::DescriptorPool::release()

Release the underlying Vulkan descriptor pool.

Releases ownership of the Vulkan descriptor pool and returns its handle so vkDestroyDescriptorPool() is not called on destruction. The internal state is then equivalent to moved-from state.