Module vulkano::command_buffer
source · [−]Expand description
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 record commands to it.
When you are done adding commands, build it to obtain either a PrimaryAutoCommandBuffer
or
SecondAutoCommandBuffer
.
Once built, use the PrimaryCommandBuffer
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::CommandBufferUsage;
use vulkano::command_buffer::PrimaryCommandBuffer;
use vulkano::command_buffer::SubpassContents;
let cb = AutoCommandBufferBuilder::primary(
device.clone(),
queue.family(),
CommandBufferUsage::MultipleSubmit
).unwrap()
.begin_render_pass(render_pass_begin_info, SubpassContents::Inline).unwrap()
.bind_pipeline_graphics(graphics_pipeline.clone())
.bind_vertex_buffers(0, vertex_buffer.clone())
.draw(vertex_buffer.len() as u32, 1, 0, 0).unwrap()
.end_render_pass().unwrap()
.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
In the Vulkan API, command buffers must be allocated from command pools.
Low-level builders that allow submitting an operation to a queue.
Contains SyncCommandBufferBuilder
and SyncCommandBuffer
.
Structs
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
.
Parameters to blit image data.
A region of data to copy between buffers.
A region of data to copy between a buffer and an image.
Parameters to clear a color image.
Parameters to clear a depth/stencil image.
Specifies the clear region for the clear_attachments
command.
Represents a command buffer being executed by the GPU and the moment when the execution finishes.
The context that a secondary command buffer can inherit from the primary command buffer it’s executed in.
The render pass context that a secondary command buffer is created for.
The dynamic rendering context that a secondary command buffer is created for.
Parameters to copy data from a buffer to another buffer.
Parameters to copy data from a buffer to another buffer, with type information.
Parameters to copy data from a buffer to an image.
Parameters to copy data from an image to another image.
Parameters to copy data from an image to a buffer.
Parameters to fill a region of a buffer with repeated copies of a value.
A region of data to blit between images.
A region of data to copy between images.
A region of data to resolve between images.
Parameters to begin a new render pass.
Parameters to specify properties of an attachment.
Parameters to specify the resolve behavior of an attachment.
Parameters to begin rendering.
Parameters to resolve image data.
Prototype for a vkCmdExecuteCommands
.
Enums
Error that can happen when checking descriptor sets validity.
Error that can happen when checking dispatch command validity.
Error that can happen when validating dynamic states.
Error that can happen when checking whether binding an index buffer is valid.
Error that can happen when checking whether binding an indirect buffer is valid.
Error that can happen when checking whether the pipeline is valid.
Error that can happen when checking push constants validity.
Error that can happen when checking whether the vertex buffers are valid.
Clear attachment type, used in clear_attachments
command.
Error that can happen when beginning recording of a command buffer.
Error that can happen when attempting to execute a command buffer.
Selects the type of render pass for command buffer inheritance.
Determines the kind of command buffer to create.
Usage flags to pass when creating a command buffer.
Error that can happen when recording a copy command.
Indicates which resource a CopyError
applies to.
Error that can happen when recording a debug utils command.
Error that can happen when executing a secondary command buffer.
Error that can happen when calling a query command.
Error that can happen when recording a render pass command.
Describes what a subpass in a command buffer will contain.