Module vulkano::command_buffer

Commands that the GPU will execute (includes draw commands).

With Vulkan, before the GPU can do anything you must create a CommandBuffer. A command buffer is a list of commands that will executed by the GPU. Once a command buffer is created, you can execute it. A command buffer must always be created even for the most simple tasks.

Primary and secondary command buffers.

There are three types of command buffers:

• Primary command buffers. They can contain any command. They are the only type of command buffer that can be submitted to a queue.
• Secondary "graphics" command buffers. They can only contain draw and clear commands. They can only be called from a primary command buffer when inside a render pass.
• Secondary "compute" command buffers. They can only contain non-render-pass-related commands (ie. everything but drawing, clearing, etc.) and cannot enter a render pass. They can only be called from a primary command buffer outside of a render pass.

Using secondary command buffers leads to slightly lower performance on the GPU, but they have two advantages on the CPU side:

• Building a command buffer is a single-threaded operation, but by using secondary command buffers you can build multiple secondary command buffers in multiple threads simultaneously.
• Secondary command buffers can be kept alive between frames. When you always repeat the same operations, it might be a good idea to build a secondary command buffer once at initialization and then reuse it afterwards.

The AutoCommandBufferBuilder

The most basic (and recommended) way to create a command buffer is to create a AutoCommandBufferBuilder. Then use the CommandBufferBuilder trait to add commands to it. When you are done adding commands, use the CommandBufferBuild trait to obtain a AutoCommandBuffer.

Once built, use the CommandBuffer trait to submit the command buffer. Submitting a command buffer returns an object that implements the GpuFuture trait and that represents the moment when the execution will end on the GPU.

use vulkano::command_buffer::AutoCommandBufferBuilder;
use vulkano::command_buffer::CommandBuffer;

let cb = AutoCommandBufferBuilder::new(device.clone(), queue.family()).unwrap()
    // TODO: add an actual command to this example
    .build().unwrap();

let _future = cb.execute(queue.clone());

Internal architecture of vulkano

The commands_raw and commands_extra modules contain structs that correspond to various commands that can be added to command buffer builders. A command can be added to a command buffer builder by using the AddCommand<C> trait, where C is the command struct.

The AutoCommandBufferBuilder internally uses a UnsafeCommandBufferBuilder wrapped around multiple layers. See the cb module for more information.

Command pools are automatically handled by default, but vulkano also allows you to use alternative command pool implementations and use them. See the pool module for more information.

Modules

pool	In the Vulkan API, command buffers must be allocated from command pools.
submit	Low-level builders that allow submitting an operation to a queue.
synced	Contains SyncCommandBufferBuilder and SyncCommandBuffer.
sys
validity	Functions that check the validity of commands.

Structs

AutoCommandBuffer
AutoCommandBufferBuilder	Note that command buffers allocated from the default command pool (Arc<StandardCommandPool>) don't implement the Send and Sync traits. If you use this pool, then the AutoCommandBufferBuilder will not implement Send and Sync either. Once a command buffer is built, however, it does implement Send and Sync.
CommandBufferExecFuture	Represents a command buffer being executed by the GPU and the moment when the execution finishes.
DispatchIndirectCommand
DrawIndexedIndirectCommand
DrawIndirectCommand
DynamicState	The dynamic state to use for a draw command.
StateCacher	Keep track of the state of a command buffer builder, so that you don't need to bind objects that were already bound.

Enums

AutoCommandBufferBuilderContextError
BeginRenderPassError
BlitImageError
BuildError
ClearColorImageError
CommandBufferExecError	Error that can happen when attempting to execute a command buffer.
CopyBufferError
CopyBufferImageError
CopyImageError
DispatchError
DrawError
DrawIndexedError
DrawIndexedIndirectError
DrawIndirectError
ExecuteCommandsError
FillBufferError
StateCacherOutcome	Outcome of an operation.
UpdateBufferError

Traits

CommandBuffer