Module vulkano::command_buffer [−] [src]

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 performances 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::CommandBufferBuilder;
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

cb	Internals of vulkano's command buffers building.
commands_extra	Additional commands built on top of core commands.
commands_raw	All the commands used in the internals of vulkano.
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.

Structs

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.

Enums

CommandAddError	Error that can happen when adding a command to a command buffer builder.
CommandBufferBuilderError	Error that can happen when adding a command to a command buffer builder.
CommandBufferExecError	Error that can happen when attempting to execute a command buffer.

Traits

CommandBuffer
CommandBufferBuild	Turns a command buffer builder into a real command buffer.
CommandBufferBuilder	Note: This trait is just a utility trait. Do not implement it yourself. Instead implement the `AddCommand` and `CommandBufferBuild` traits.