Module descriptor_set

Bindings between shaders and the resources they access.

Overview

In order to access a buffer or an image from a shader, that buffer or image must be put in a descriptor. Each descriptor contains one buffer or one image alongside with the way that it can be accessed. A descriptor can also be an array, in which case it contains multiple buffers or images that all have the same layout.

Descriptors are grouped in what is called descriptor sets. In Vulkan you don’t bind individual descriptors one by one, but you create then bind descriptor sets one by one. As binding a descriptor set has (small but non-null) a cost, you are encouraged to put descriptors that are often used together in the same set so that you can keep the same set binding through multiple draws.

Examples

Note: This section describes the simple way to bind resources. There are more optimized ways.

There are two steps to give access to a resource in a shader: creating the descriptor set, and passing the descriptor sets when drawing.

Creating a descriptor set

TODO: write

Passing the descriptor set when drawing

TODO: write

When drawing

When you call a function that adds a draw command to a command buffer, vulkano will check that the descriptor sets you bound are compatible with the layout of the pipeline.

TODO: talk about perfs of changing sets

Descriptor sets creation and management

There are three concepts in Vulkan related to descriptor sets:

• A VkDescriptorSetLayout is a Vulkan object that describes to the Vulkan implementation the layout of a future descriptor set. When you allocate a descriptor set, you have to pass an instance of this object. This is represented with the DescriptorSetLayout type in vulkano.
• A VkDescriptorPool is a Vulkan object that holds the memory of descriptor sets and that can be used to allocate and free individual descriptor sets. This is represented with the DescriptorPool type in vulkano.
• A VkDescriptorSet contains the bindings to resources and is allocated from a pool. This is represented with the RawDescriptorSet type in vulkano.

In addition to this, vulkano defines the following:

• The DescriptorSetAllocator trait can be implemented on types from which you can allocate and free descriptor sets. However it is different from Vulkan descriptor pools in the sense that an implementation of the DescriptorSetAllocator trait can manage multiple Vulkan descriptor pools.
• The StandardDescriptorSetAllocator type is a default implementation of the DescriptorSetAllocator trait.
• The DescriptorSet type wraps around an RawDescriptorSet a safe way. A Vulkan descriptor set is inherently unsafe, so we need safe wrappers around them.
• The DescriptorSetsCollection trait is implemented on collections of descriptor sets. It is what you pass to the bind function.

Modules

allocator

In the Vulkan API, descriptor sets must be allocated from descriptor pools.

layout

Describes the layout of all descriptors within a descriptor set.

pool

sys

Low-level descriptor set.

Structs

CopyDescriptorSet

Represents a single copy operation to the binding of a descriptor set.

DescriptorBufferInfo

Parameters to write a buffer reference to a descriptor.

DescriptorImageViewInfo

Parameters to write an image view reference to a descriptor.

DescriptorSet

An object that contains a collection of resources that will be accessible by shaders.

DescriptorSetResources

The resources that are bound to a descriptor set.

DescriptorSetWithOffsets

InvalidateDescriptorSet

Invalidates descriptors within a descriptor set. Doesn’t actually call into vulkan and only invalidates the descriptors inside vulkano’s resource tracking. Invalidated descriptors are equivalent to uninitialized descriptors, in that binding a descriptor set to a particular pipeline requires all shader-accessible descriptors to be valid.

WriteDescriptorSet

Represents a single write operation to the binding of a descriptor set.

Enums

DescriptorBindingResources

The resources that are bound to a single descriptor set binding.

WriteDescriptorSetElements

The elements held by a WriteDescriptorSet.

Traits

DescriptorSetsCollection

A collection of descriptor set objects.