CommandBuffer

The CommandBuffer class offers a convenient abstraction over command recording, pipeline state and descriptor sets of Vulkan.

Setting pipeline state

The CommandBuffer encapsulates the current pipeline and descriptor state. When calling state-setting commands, the current state of the CommandBuffer is updated. The state of the CommandBuffer persists for the duration of the execution callback, and there is no state leakage between callbacks of different passes.

The various states of the pipeline can be reconfigured by calling the appropriate function, such as vuk::CommandBuffer::set_rasterization().

There is no default state - you must explicitly bind all state used for the commands recorded.

Static and dynamic state

Vulkan allows some pipeline state to be dynamic. In vuk this is exposed as an optimisation - you may let the CommandBuffer know that certain pipeline state is dynamic by calling vuk::CommandBuffer::set_dynamic_state(). This call changes which states are considered dynamic. Dynamic state is usually cheaper to change than entire pipelines and leads to fewer pipeline compilations, but may have more overhead compared to static state - use it when a state changes often. Some state can be set dynamic on some platforms without cost. As with other pipeline state, setting states to be dynamic or static persist only during the callback.

Binding pipelines & specialization constants

The CommandBuffer maintains separate bind points for compute and graphics pipelines. The CommandBuffer also maintains an internal buffer of specialization constants that are applied to the pipeline bound. Changing specialization constants will trigger a pipeline compilation when using the pipeline for the first time.

Binding descriptors & push constants

vuk allows two types of descriptors to be bound: ephemeral and persistent.

Ephemeral descriptors are bound individually to the CommandBuffer via bind_XXX() calls where XXX denotes the type of the descriptor (eg. uniform buffer). These descriptors are internally managed by the CommandBuffer and the Allocator it references. Ephemeral descriptors are very convenient to use, but they are limited in the number of bindable descriptors (VUK_MAX_BINDINGS) and they incur a small overhead on bind.

Persistent descriptors are managed by the user via allocation of a PersistentDescriptorSet from Allocator and manually updating the contents. There is no limit on the number of descriptors and binding such descriptor sets do not have an overhead over the direct Vulkan call. Large descriptor arrays (such as the ones used in “bindless” techniques) are only possible via persistent descriptor sets.

The number of bindable sets is limited by VUK_MAX_SETS. Both ephemeral descriptors and persistent descriptor sets retain their bindings until overwritten, disturbed or the the callback ends.

Push constants can be changed by calling vuk::CommandBuffer::push_constants().

Vertex buffers and attributes

While vertex buffers are waning in popularity, vuk still offers a convenient API for most attribute arrangements. If advanced addressing schemes are not required, they can be a convenient alternative to vertex pulling.

The shader declares attributes, which require a location. When binding vertex buffers, you are telling vuk where each attribute, corresponding to a location can be found. Each vuk::CommandBuffer::bind_vertex_buffer() binds a single vuk::Buffer, which can contain multiple attributes

The first two arguments to vuk::CommandBuffer::bind_vertex_buffer() specify the index of the vertex buffer binding and buffer to binding to that binding. (so if you have 1 vertex buffers, you pass 0, if you have 2 vertex buffers, you have 2 calls where you pass 0 and 1 as binding - these don’t need to start at 0 or be contiguous but they might as well be)

In the second part of the arguments you specify which attributes can be found the vertex buffer that is being bound, what is their format, and what is their offset. For convenience vuk offers a utility called vuk::Packed to describe common vertex buffers that contain interleaved attribute data.

The simplest case is a single attribute per vertex buffer, this is described by calling bind_vertex_buffer(binding, buffer, location, vuk::Packed{vuk::Format::eR32G32B32Sfloat}) - with the actual format of the attribute. Here vuk::Packed means that the formats are packed in the buffer, i.e. you have a R32G32B32, then immediately after a R32G32B32, and so on.

If there are multiple interleaved attributes in a buffer, for example it is [position, normal, position, normal], then you can describe this in a very compact way in vuk if the position attribute location and normal attribute location is consecutive: bind_vertex_buffer(binding, buffer, first_location, vuk::Packed{ vuk::Format::eR32G32B32Sfloat, vuk::Format::eR32G32B32Sfloat }). Finally, you can describe holes in your interleaving by using vuk::Ignore(byte_size) in the format list for vuk::Packed.

If your attribute scheme cannot be described like this, you can also use vuk::CommandBuffer::bind_vertex_buffer() with a manually built span<VertexInputAttributeDescription> and computed stride.

Command recording

Draws and dispatches can be recorded by calling the appropriate function. Any state changes made will be recorded into the underlying Vulkan command buffer, along with the draw or dispatch.

Error handling

The CommandBuffer implements “monadic” error handling, because operations that allocate resources might fail. In this case the CommandBuffer is moved into the error state and subsequent calls do not modify the underlying state.

Raw access

For advanced use-cases, the underlying VkCommandBuffer can be accessed via vuk::CommandBuffer::bind_compute_state()/ vuk::CommandBuffer::bind_graphics_state()/ vuk::CommandBuffer::bind_ray_tracing_state(). These functions apply the current CommandBuffer state to the underlying command buffer, so that subsequent raw Vulkan commands see the correct state. You must ensure that the command buffer state is returned to the correct state if it used again in the same pass.

API reference for CommandBuffer

struct Packed

Describes a packed vertex buffer layout with optional gaps.

Used with bind_vertex_buffer() to describe vertex attributes that are tightly or loosely packed in a buffer. Supports interleaved attributes and ignored regions.

Example:

// Vertex buffer with position (vec3), skip 4 bytes, then color (vec4)
command_buffer.bind_vertex_buffer(0, vertex_buffer, 0,
    Packed{ Format::eR32G32B32Sfloat, Ignore{4}, Format::eR32G32B32A32Sfloat });

// Tightly packed position and UV coordinates
command_buffer.bind_vertex_buffer(0, vertex_buffer, 0,
    Packed{ Format::eR32G32B32Sfloat, Format::eR32G32Sfloat });

Public Functions

inline Packed(std::initializer_list<FormatOrIgnore> ilist): Constructs a Packed object from a list of Formats or Ignore elements.

struct Ignore

Specifies a gap or ignored region in a packed vertex buffer layout.

Used with Packed to skip over unused data in vertex buffers, allowing flexible vertex layouts without requiring data to be tightly packed or reordered.

Public Functions

inline Ignore(size_t bytes): Skip a number of bytes in the vertex buffer.

inline Ignore(Format format): Skip the size of a format in the vertex buffer.

class CommandBuffer

Public Functions

inline Runtime &get_context(): Retrieve parent runtime.

inline VkCommandBuffer get_underlying() const: Gets the underlying Vulkan command buffer handle. Unsafe: use only when not setting state, eg. tracing. Otherwise use the bind_X_state functions.

const RenderPassInfo &get_ongoing_render_pass() const: Retrieve information about the current renderpass.

inline Stream &get_scheduled_stream(): Get the stream where this CommandBuffer is scheduled to execute on.

DomainFlagBits get_scheduled_domain() const: Gets the domain where this CommandBuffer will execute on.

Allocator get_allocator(): Gets the allocator associated with this object.

CommandBuffer &set_descriptor_set_strategy(DescriptorSetStrategyFlags ds_strategy_flags)

Set the strategy for allocating and updating ephemeral descriptor sets.

The default strategy is taken from the runtime when entering a new Pass

Parameters:: ds_strategy_flags – Mask of strategy options

CommandBuffer &set_dynamic_state(DynamicStateFlags dynamic_state_flags)

Set mask of dynamic state in CommandBuffer.

Parameters:: dynamic_state_flags – Mask of states (flag set = dynamic, flag clear = static)

CommandBuffer &set_viewport(unsigned index, Viewport vp)

Set the viewport transformation for the specified viewport index.

Parameters:

index – viewport index to modify
vp – Viewport to be set

CommandBuffer &set_viewport(unsigned index, Rect2D area, float min_depth = 0.f, float max_depth = 1.f)

Set the viewport transformation for the specified viewport index from a rect.

Parameters:

index – viewport index to modify
area – Rect2D extents of the Viewport
min_depth – Minimum depth of Viewport
max_depth – Maximum depth of Viewport

CommandBuffer &set_scissor(unsigned index, Rect2D area)

Set the scissor for the specified scissor index from a rect.

Parameters:

index – scissor index to modify
area – Rect2D extents of the scissor

CommandBuffer &set_rasterization(PipelineRasterizationStateCreateInfo rasterization_state): Set the rasterization state.

CommandBuffer &set_depth_stencil(PipelineDepthStencilStateCreateInfo depth_stencil_state): Set the depth/stencil state.

CommandBuffer &set_conservative(PipelineRasterizationConservativeStateCreateInfo conservative_state): Set the conservative rasterization state.

CommandBuffer &set_patch_control_points(uint32_t new_patch_control_points): Set the number of control points per patch for Tessellation pipeline.

CommandBuffer &broadcast_color_blend(PipelineColorBlendAttachmentState color_blend_state): Set one color blend state to use for all color attachments.

CommandBuffer &broadcast_color_blend(BlendPreset blend_preset): Set one color blend preset to use for all color attachments.

CommandBuffer &set_color_blend(const ImageAttachment &color_attachment, PipelineColorBlendAttachmentState color_blend_state)

Set color blend state for a specific color attachment.

Parameters:

color_attachment – the Name of the color_attachment to set the blend state for
color_blend_state – PipelineColorBlendAttachmentState to use

CommandBuffer &set_color_blend(const ImageAttachment &color_attachment, BlendPreset blend_preset)

Set color blend preset for a specific color attachment.

Parameters:

color_attachment – the Name of the color_attachment to set the blend preset for
blend_preset – BlendPreset to use

CommandBuffer &set_blend_constants(std::array<float, 4> blend_constants): Set blend constants.

CommandBuffer &bind_graphics_pipeline(PipelineBaseInfo *pipeline_base)

Bind a graphics pipeline for subsequent draws.

Parameters:: pipeline_base – pointer to a pipeline base to bind

CommandBuffer &bind_graphics_pipeline(Name named_pipeline)

Bind a named graphics pipeline for subsequent draws.

Parameters:: named_pipeline – graphics pipeline name

CommandBuffer &bind_compute_pipeline(PipelineBaseInfo *pipeline_base)

Bind a compute pipeline for subsequent dispatches.

Parameters:: pipeline_base – pointer to a pipeline base to bind

CommandBuffer &bind_compute_pipeline(Name named_pipeline)

Bind a named graphics pipeline for subsequent dispatches.

Parameters:: named_pipeline – compute pipeline name

CommandBuffer &bind_ray_tracing_pipeline(PipelineBaseInfo *pipeline_base)

Bind a ray tracing pipeline for subsequent draws.

Parameters:: pipeline_base – pointer to a pipeline base to bind

CommandBuffer &bind_ray_tracing_pipeline(Name named_pipeline)

Bind a named ray tracing pipeline for subsequent draws.

Parameters:: named_pipeline – graphics pipeline name

inline CommandBuffer &specialize_constants(uint32_t constant_id, bool value)