Module vulkano::command_buffer

source ·
Expand description

Recording commands to execute on the device.

With Vulkan, to get the device to perform work, even relatively simple tasks, you must create a command buffer. A command buffer is a list of commands that will executed by the device. You must first record commands to a command buffer builder, then build it into an actual command buffer, and then it can be used. Depending on how a command buffer is created, it can be used only once, or reused many times.

Command pools and allocators

Command buffers are allocated from command pools. A command pool holds memory that is used to record the sequence of commands in a command buffer. Command pools are not thread-safe, and therefore commands cannot be recorded to a single command buffer from multiple threads at a time.

Raw command pools are unsafe to use, so Vulkano uses [command buffer allocators] to manage command buffers and pools, to ensure their memory is used efficiently, and to protect against invalid usage. Vulkano provides the StandardCommandBufferAllocator for this purpose, but you can also create your own by implementing the CommandBufferAllocator trait.

Primary and secondary command buffers

There are two levels of command buffers:

Using secondary command buffers, there is slightly more overhead than using primary command buffers alone, but there are also advantages. A single command buffer cannot be recorded from multiple threads at a time, so if you want to divide the recording work among several threads, each thread must record its own command buffer. While it is possible for these to be all primary command buffers, there are limitations: a render pass or query cannot span multiple primary command buffers, while secondary command buffers can inherit this state from their parent primary command buffer. Therefore, to have a single render pass or query that is shared across all the command buffers, you must record secondary command buffers.

Recording a command buffer

To record a new command buffer, the most direct way is to create a new AutoCommandBufferBuilder. You can then call methods on this object to record new commands to the command buffer. When you are done recording, you call build to finalise the command buffer and turn it into either a PrimaryCommandBufferAbstract or a SecondaryCommandBufferAbstract.

Submitting a primary command buffer

Once primary a command buffer is recorded and built, you can use the PrimaryCommandBufferAbstract trait to submit the command buffer to a queue. 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::CommandBufferUsage;
use vulkano::command_buffer::PrimaryCommandBufferAbstract;
use vulkano::command_buffer::SubpassContents;


let cb = AutoCommandBufferBuilder::primary(
    &command_buffer_allocator,
    queue.queue_family_index(),
    CommandBufferUsage::MultipleSubmit
).unwrap()
.begin_render_pass(render_pass_begin_info, Default::default()).unwrap()
.bind_pipeline_graphics(graphics_pipeline.clone()).unwrap()
.bind_vertex_buffers(0, vertex_buffer.clone()).unwrap()
.draw(vertex_buffer.len() as u32, 1, 0, 0).unwrap()
.end_render_pass(Default::default()).unwrap()
.build().unwrap();

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

Re-exports

Modules

  • allocator
    Traits and types for managing the allocation of command buffers and command pools.
  • auto
    Contains AutoCommandBufferBuilder and the built types PrimaryCommandBuffer and SecondaryCommandBuffer.
  • pool
    Memory and resource pool for recording command buffers.
  • sys

Structs

Enums

Traits