Module vulkano::command_buffer::cb

Internals of vulkano's command buffers building.

You probably don't need to look inside this module if you're a beginner. The AutoCommandBufferBuilder provided in the parent module should be good for most needs.

Builder basics

The lowest-level command buffer types are UnsafeCommandBufferBuilder and UnsafeCommandBuffer. These two types have zero overhead over Vulkan command buffers but are very unsafe to use.

Before you can add a command to an unsafe command buffer builder, you should:

• Make sure that the buffers or images used by the command stay alive for the duration of the command buffer.
• Check that the device used by the buffers or images of the command is the same as the device of the command buffer.
• If the command buffer is inside/outside a render pass, check that the command can be executed inside/outside a render pass. Same for secondary command buffers.
• Check that the command can be executed on the queue family of the command buffer. Some queue families don't support graphics and/or compute operations .
• Make sure that when the command buffer is submitted the buffers and images of the command will be properly synchronized.
• Make sure that pipeline barriers are correctly inserted in order to avoid race conditions.

In order to allow you to customize which checks are performed, vulkano provides layers. They are structs that can be put around a command buffer builder and that will perform them. Keep in mind that all the conditions above must be respected, but if you somehow make sure at compile-time that some requirements are always correct, you can avoid paying some runtime cost by not using all layers.

Adding a command to a command buffer builder is done in two steps:

• First you must build a struct that represents the command to add. The struct's constructor can perform various checks to make sure that the command itself is valid, or it can provide an unsafe constructor that doesn't perform any check.
• Then use the AddCommand trait to add it. The trait is implemented on the command buffer builder and on the various layers, and its template parameter is the struct representing the command.

Since the UnsafeCommandBufferBuilder doesn't keep the command structs alive (as it would incur an overhead), it implements AddCommand<&T>.

The role of the CommandsListLayer and BufferedCommandsListLayer layers is to keep the commands alive. They implement AddCommand<T> if the builder they wrap around implements AddCommand<&T>. In other words they are the lowest level that you should put around an UnsafeCommandBufferBuilder.

The other layers of this module implement AddCommand<T> if the builder they wrap around implements AddCommand<T>.

Building a command buffer

Once you are satisfied with the commands you added to a builder, use the CommandBufferBuild trait to build it.

This trait is implemented on the UnsafeCommandBufferBuilder but also on all the layers. The builder's layers can choose to add layers around the finished command buffer.

The CommandsList trait

The CommandsList trait is implemented on any command buffer or command buffer builder that exposes a list of commands. It is required by some of the layers.

Structs

AbstractStorageLayer	Layer that stores commands in an abstract way.
AutoPipelineBarriersLayer
ContextCheckLayer	Layer around a command buffer builder that checks whether the commands can be executed in the given context related to render passes.
DeviceCheckLayer	Layer around a command buffer builder that checks whether the commands added to it belong to the same device as the command buffer.
QueueTyCheckLayer	Layer around a command buffer builder that checks whether the commands added to it match the type of the queue family of the underlying builder.
StateCacheLayer	Layer around a command buffer builder that caches the current state of the command buffer and avoids redundant state changes.
SubmitSyncBuilderLayer	Layers that ensures that synchronization with buffers and images between command buffers is properly handled.
SubmitSyncLayer	Layer around a command buffer that handles synchronization between command buffers.
UnsafeCommandBuffer	Command buffer that has been built.
UnsafeCommandBufferBuilder	Command buffer being built.

Enums

Flags	Flags to pass when creating a command buffer.
Kind	Determines the kind of command buffer that we want to create.
SubmitSyncBuilderLayerBehavior	How the layer behaves when it comes to image layouts.

Traits

AddCommand	Adds a command to a command buffer builder.
CommandBufferBuild	Turns a command buffer builder into a real command buffer.