Module vulkano::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 example for: PersistentDescriptorSet::start(layout.clone()).add_buffer(data_buffer.clone())

Passing the descriptor set when drawing

TODO: write

When drawing

When you call a function that adds a draw command to a command buffer, one of the parameters corresponds to the list of descriptor sets to use. Vulkano will check that what you passed is 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 DescriptorSetLayout 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 DescriptorPool 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 DescriptorSet contains the bindings to resources and is allocated from a pool. This is represented with the [UnsafeDescriptorSet] 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 trait is implemented on types that wrap around Vulkan descriptor sets in 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 types that implement DescriptorSet. It is what you pass to the draw functions.

Re-exports

• pub use self::persistent::PersistentDescriptorSet;

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.
• persistent
  A simple, immutable descriptor set that is expected to be long-lived.
• 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.
• DescriptorSetResources
  The resources that are bound to a descriptor set.
• DescriptorSetWithOffsets
• 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

• DescriptorSet
  Trait for objects that contain a collection of resources that will be accessible by shaders.
• DescriptorSetsCollection
  A collection of descriptor set objects.