Module command_buffer

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 recording command buffer, then end the recording to turn 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:

A primary command buffer can be executed on a queue, and is the main command buffer level. It cannot be executed within another command buffer.
A secondary command buffer can only be executed within a primary command buffer, not directly on a queue.

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 PrimaryAutoCommandBuffer or a SecondaryAutoCommandBuffer.

§Submitting a primary command buffer

Once a primary command buffer is recorded and built, you can submit the PrimaryAutoCommandBuffer 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, CommandBufferUsage, PrimaryCommandBufferAbstract,
    SubpassContents,
};

let mut cb = AutoCommandBufferBuilder::primary(
    command_buffer_allocator.clone(),
    queue.queue_family_index(),
    CommandBufferUsage::OneTimeSubmit,
)
.unwrap();

cb.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();
unsafe { cb.draw(vertex_buffer.len() as u32, 1, 0, 0) }.unwrap();

cb.end_render_pass(Default::default()).unwrap();

let cb = cb.build().unwrap();

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

Re-exports§

pub use self::auto::AutoCommandBufferBuilder;
pub use self::auto::PrimaryAutoCommandBuffer;
pub use self::auto::SecondaryAutoCommandBuffer;

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.

Structs§

BlitImageInfo: Parameters to blit image data.
BufferCopy: A region of data to copy between buffers.
BufferImageCopy: A region of data to copy between a buffer and an image.
ClearColorImageInfo: Parameters to clear a color image.
ClearDepthStencilImageInfo: Parameters to clear a depth/stencil image.
ClearRect: Specifies the clear region for the clear_attachments command.
CommandBuffer: A command buffer that has finished recording.
CommandBufferBeginInfo: Parameters to begin recording a command buffer.
CommandBufferExecFuture: Represents a command buffer being executed by the GPU and the moment when the execution finishes.
CommandBufferInheritanceInfo: The context that a secondary command buffer can inherit from the primary command buffer it’s executed in.
CommandBufferInheritanceRenderPassInfo: The render pass context that a secondary command buffer is created for.
CommandBufferInheritanceRenderingInfo: The dynamic rendering context that a secondary command buffer is created for.
CommandBufferState
CommandBufferSubmitInfo: Parameters for a command buffer in a queue submit operation.
CopyBufferInfo: Parameters to copy data from a buffer to another buffer.
CopyBufferInfoTyped: Parameters to copy data from a buffer to another buffer, with type information.
CopyBufferToImageInfo: Parameters to copy data from a buffer to an image.
CopyImageInfo: Parameters to copy data from an image to another image.
CopyImageToBufferInfo: Parameters to copy data from an image to a buffer.
DispatchIndirectCommand: Used as buffer contents to provide input for the AutoCommandBufferBuilder::dispatch_indirect command.
DrawIndexedIndirectCommand: Used as buffer contents to provide input for the AutoCommandBufferBuilder::draw_indexed_indirect command.
DrawIndirectCommand: Used as buffer contents to provide input for the AutoCommandBufferBuilder::draw_indirect command.
DrawMeshTasksIndirectCommand: Used as buffer contents to provide input for the AutoCommandBufferBuilder::draw_mesh_tasks_indirect command.
ImageBlit: A region of data to blit between images.
ImageCopy: A region of data to copy between images.
ImageResolve: A region of data to resolve between images.
RecordingCommandBuffer: A command buffer in the recording state.
RenderPassBeginInfo: Parameters to begin a new render pass.
RenderingAttachmentInfo: Parameters to specify properties of an attachment.
RenderingAttachmentResolveInfo: Parameters to specify the resolve behavior of an attachment.
RenderingInfo: Parameters to begin rendering.
ResolveImageInfo: Parameters to resolve image data.
ResourceUseRef
SecondaryResourceUseRef
SemaphoreSubmitInfo: Parameters for a semaphore signal or wait operation in a queue submit operation.
SubmitInfo: Parameters to submit command buffers to a queue.
SubpassBeginInfo: Parameters to begin a new subpass within a render pass.
SubpassEndInfo: Parameters to end the current subpass within a render pass.

Enums§

ClearAttachment: Clear attachment type, used in clear_attachments command.
CommandBufferExecError: Error that can happen when attempting to execute a command buffer.
CommandBufferInheritanceRenderPassType: Selects the type of render pass for command buffer inheritance.
CommandBufferLevel: Determines the kind of command buffer to create.
CommandBufferUsage: Usage flags to pass when creating a command buffer.
ResourceInCommand
SubpassContents: Describes what a subpass in a command buffer will contain.

Traits§

PrimaryCommandBufferAbstract
SecondaryCommandBufferAbstract

Module command_bufferCopy item path