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.
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 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
CommandBufferBuild trait to obtain a
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());
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.
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
In the Vulkan API, command buffers must be allocated from command pools.
Low-level builders that allow submitting an operation to a queue.
Functions that check the validity of commands.
Note that command buffers allocated from the default command pool (
Represents a command buffer being executed by the GPU and the moment when the execution finishes.
The dynamic state to use for a draw command.
Keep track of the state of a command buffer builder, so that you don't need to bind objects that were already bound.
Error that can happen when attempting to execute a command buffer.
Outcome of an operation.