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.

Example

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 UnsafeDescriptorPool 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 DescriptorPool 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 DescriptorPool trait can manage multiple Vulkan descriptor pools.
• The StdDescriptorPool type is a default implementation of the DescriptorPool 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 SimpleDescriptorSet type is a default implementation of the DescriptorSet trait.
• 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::builder::DescriptorSetBuilder;

pub use self::persistent::PersistentDescriptorSet;

pub use self::single_layout_pool::SingleLayoutDescSetPool;

Modules

builder

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

A pool from which descriptor sets can be allocated.

single_layout_pool

sys

Low-level descriptor set.

Structs

DescriptorSetResources

The resources that are bound to a descriptor set.

DescriptorSetWithOffsets

Enums

DescriptorBindingResources

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

DescriptorSetError

Error related to descriptor sets.

MissingBufferUsage

MissingImageUsage

Traits

DescriptorSet

Trait for objects that contain a collection of resources that will be accessible by shaders.

DescriptorSetsCollection

A collection of descriptor set objects.