Class CommandBuffer

Class Documentation

class CommandBuffer

RAII wrapper class for VkCommandBuffer.

Todo:

Make trivially copyable (this class doesn’t really “own” the command buffer, more just an OOP wrapper).

Public Functions

CommandBuffer(const Device &device, VkCommandPool cmd_pool, std::string name)

Default constructor

Parameters

  • device – A const reference to the device wrapper class

  • cmd_pool – The command pool from which the command buffer will be allocated

  • name – The internal debug marker name of the command buffer (must not be empty)

CommandBuffer(const CommandBuffer&) = delete
CommandBuffer(CommandBuffer&&) noexcept
~CommandBuffer() = default
CommandBuffer &operator=(const CommandBuffer&) = delete
CommandBuffer &operator=(CommandBuffer&&) = delete
const CommandBuffer &begin_render_pass(const VkRenderPassBeginInfo &render_pass_bi, VkSubpassContents subpass_contents = VK_SUBPASS_CONTENTS_INLINE) const

Call vkCmdBeginRenderPass

Parameters

  • render_pass_bi – The renderpass begin info

  • subpass_contents – The subpass contents (VK_SUBPASS_CONTENTS_INLINE by default)

Returns

A const reference to the this pointer (allowing method calls to be chained)

const CommandBuffer &bind_descriptor_sets(std::span<const VkDescriptorSet> desc_sets, VkPipelineLayout layout, VkPipelineBindPoint bind_point = VK_PIPELINE_BIND_POINT_GRAPHICS, std::uint32_t first_set = 0, std::span<const std::uint32_t> dyn_offsets = {}) const

Call vkCmdBindDescriptorSets

Parameters

  • desc_sets – The descriptor sets to bind

  • layout – The pipeline layout

  • bind_point – the pipeline bind point (VK_PIPELINE_BIND_POINT_GRAPHICS by default)

  • first_set – The first descriptor set (0 by default)

  • dyn_offsets – The dynamic offset values (empty by default)

Returns

A const reference to the this pointer (allowing method calls to be chained)

const CommandBuffer &bind_index_buffer(VkBuffer buf, VkIndexType index_type = VK_INDEX_TYPE_UINT32, VkDeviceSize offset = 0) const

Call vkCmdBindIndexBuffer

Parameters

  • buf – The index buffer to bind

  • index_type – The index type to use (VK_INDEX_TYPE_UINT32 by default)

  • offset – The offset (0 by default)

Returns

A const reference to the this pointer (allowing method calls to be chained)

const CommandBuffer &bind_pipeline(VkPipeline pipeline, VkPipelineBindPoint bind_point = VK_PIPELINE_BIND_POINT_GRAPHICS) const

Call vkCmdBindPipeline

Parameters

  • pipeline – The graphics pipeline to bind

  • bind_point – The pipeline bind point (VK_PIPELINE_BIND_POINT_GRAPHICS by default)

Returns

A const reference to the this pointer (allowing method calls to be chained)

const CommandBuffer &bind_vertex_buffers(std::span<const VkBuffer> bufs, std::uint32_t first_binding = 0, std::span<const VkDeviceSize> offsets = {}) const

Call vkCmdBindVertexBuffers

Parameters

  • bufs – The vertex buffers to bind

  • first_binding – The first binding (0 by default)

  • offsets – The device offsets (empty by default)

Returns

A const reference to the this pointer (allowing method calls to be chained)

const CommandBuffer &change_image_layout(VkImage image, VkImageLayout old_layout, VkImageLayout new_layout, VkImageSubresourceRange subres_range, VkPipelineStageFlags src_mask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, VkPipelineStageFlags dst_mask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT) const

Call vkCmdPipelineBarrier

Note

The new layout must be different from the old layout!

Parameters

  • image – The image

  • old_layout – The old layout of the image

  • new_layout – The new layout of the image

  • subres_range – The image subresource range

  • src_mask – The source pipeline stage flags (VK_PIPELINE_STAGE_ALL_COMMANDS_BIT by default)

  • dst_mask – The destination pipeline stage flags (VK_PIPELINE_STAGE_ALL_COMMANDS_BIT by default)

Returns

A const reference to the dereferenced this pointer (allowing for method calls to be chained)

const CommandBuffer &change_image_layout(VkImage image, VkImageLayout old_layout, VkImageLayout new_layout, std::uint32_t mip_level_count = 1, std::uint32_t array_layer_count = 1, std::uint32_t base_mip_level = 0, std::uint32_t base_array_layer = 0, VkPipelineStageFlags src_mask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, VkPipelineStageFlags dst_mask = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT) const

Call vkCmdPipelineBarrier

Parameters

  • image – The image

  • old_layout – The old layout of the image

  • new_layout – The new layout of the image

  • mip_level_count – The number of mip levels (The parameter in VkImageSubresourceRange)

  • array_layer_count – The number of array layers (The parameter in VkImageSubresourceRange)

  • base_mip_level – The base mip level index (The parameter in VkImageSubresourceRange)

  • base_array_layer – The base array layer index (The parameter in VkImageSubresourceRange)

  • src_mask – The source pipeline stage flags (VK_PIPELINE_STAGE_ALL_COMMANDS_BIT by default)

  • dst_mask – The destination pipeline stage flags (VK_PIPELINE_STAGE_ALL_COMMANDS_BIT by default)

Returns

A const reference to the dereferenced this pointer (allowing for method calls to be chained)

const CommandBuffer &copy_buffer(VkBuffer src_buf, VkBuffer dst_buf, const VkBufferCopy &copy_region) const

Call vkCmdCopyBuffer

Parameters

  • src_buf – The source buffer

  • dst_buf – The destination buffer

  • copy_region – A single buffer copy region

Returns

A const reference to the dereferenced this pointer (allowing for method calls to be chained)

const CommandBuffer &copy_buffer(VkBuffer src_buf, VkBuffer dst_buf, std::span<const VkBufferCopy> copy_regions) const

Call vkCmdCopyBuffer

Parameters

  • src_buf – The source buffer

  • dst_buf – The destination buffer

  • copy_regions – A std::span of buffer copy regions

Returns

A const reference to the dereferenced this pointer (allowing for method calls to be chained)

const CommandBuffer &copy_buffer(VkBuffer src_buf, VkBuffer dst_buf, VkDeviceSize src_buf_size) const

Call vkCmdCopyBuffer

Parameters

  • src_buf – The source buffer

  • dst_buf – The destination buffer

  • src_buf_size – The size of the source buffer

Returns

A const reference to the dereferenced this pointer (allowing for method calls to be chained)

const CommandBuffer &copy_buffer_to_image(VkBuffer src_buf, VkImage dst_img, std::span<const VkBufferImageCopy> copy_regions) const

Call vkCmdCopyBufferToImage

Note

The destination image is always expected to be in layout VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL

Parameters

  • src_buf – The source buffer

  • dst_img – The destination image

  • copy_regions – A std::span of buffer image copy regions

Returns

A const reference to the dereferenced this pointer (allowing for method calls to be chained)

const CommandBuffer &copy_buffer_to_image(VkBuffer src_buf, VkImage dst_img, const VkBufferImageCopy &copy_region) const

Call vkCmdCopyBufferToImage copy region

Note

The destination image is always expected to be in layout VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL

Parameters

  • src_buf – The source buffer

  • dst_img – The destination image

  • copy_region – The buffer image copy region

Returns

A const reference to the dereferenced this pointer (allowing for method calls to be chained)

const CommandBuffer &copy_buffer_to_image(const void *data, const VkDeviceSize data_size, VkImage dst_img, const VkBufferImageCopy &copy_region, const std::string &name) const

Call vkCmdCopyBuffer

Note

The destination image is always expected to be in layout VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL for the copy operation

Parameters

  • data – A raw pointer to the data to copy

  • data_size – The size of the data to copy

  • dst_img – The destination image (must not be VK_NULL_HANDLE)

  • name – The internal name of the staging buffer (must not be empty)

Returns

A const reference to the dereferenced this pointer (allowing for method calls to be chained)

template<typename DataType>
inline const CommandBuffer &copy_buffer_to_image(const std::span<const DataType> data, VkImage dst_img, const VkBufferImageCopy &copy_region, const std::string &name) const

Call vkCmdCopyBuffer

Note

A staging buffer for the copy operation will be created automatically from data

Note

The destination image is always expected to be in layout VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL for the copy operation

Parameters

  • data – A std::span of the source data

  • dst_img – The destination image (must not be VK_NULL_HANDLE)

  • name – The internal name of the staging buffer (must not be empty)

Returns

A const reference to the dereferenced this pointer (allowing for method calls to be chained)

const CommandBuffer &draw(std::uint32_t vert_count, std::uint32_t inst_count = 1, std::uint32_t first_vert = 0, std::uint32_t first_inst = 0) const

Call vkCmdDraw

Parameters

  • vert_count – The number of vertices to draw

  • inst_count – The number of instances (1 by default)

  • first_vert – The index of the first vertex (0 by default)

  • first_inst – The instance ID of the first instance to draw (0 by default)

Returns

A const reference to the this pointer (allowing method calls to be chained)

const CommandBuffer &draw_indexed(std::uint32_t index_count, std::uint32_t inst_count = 1, std::uint32_t first_index = 0, std::int32_t vert_offset = 0, std::uint32_t first_inst = 0) const

Call vkCmdDrawIndexed

Parameters

  • index_count – The number of vertices to draw

  • inst_count – The number of instances to draw (1 by defaul)

  • first_index – The base index withing the index buffer (0 by default)

  • vert_offset – The value added to the vertex index before indexing into the vertex buffer (0 by default)

  • first_inst – The instance ID of the first instance to draw (0 by default)

  • index_count – The number of indices to draw

Returns

A const reference to the this pointer (allowing method calls to be chained)

const CommandBuffer &end_render_pass() const

Call vkCmdEndRenderPass

Returns

A const reference to the this pointer (allowing method calls to be chained)

inline VkResult fence_status() const
const CommandBuffer &pipeline_barrier(VkPipelineStageFlags src_stage_flags, VkPipelineStageFlags dst_stage_flags, std::span<const VkImageMemoryBarrier> img_mem_barriers, std::span<const VkMemoryBarrier> mem_barriers = {}, std::span<const VkBufferMemoryBarrier> buf_mem_barriers = {}, VkDependencyFlags dep_flags = 0) const

Call vkCmdPipelineBarrier

Note

We start with image memory barriers as no-default parameter, since it’s the most common use case

Parameters

  • src_stage_flags – The the source stage flags

  • dst_stage_flags – The destination stage flags

  • img_mem_barriers – The image memory barriers

  • mem_barriers – The memory barriers (empty by default)

  • buf_mem_barriers – The buffer memory barriers (empty by default)

  • dep_flags – The dependency flags (0 by default)

Returns

A const reference to the dereferenced this pointer (allowing for method calls to be chained)

const CommandBuffer &pipeline_image_memory_barrier(VkPipelineStageFlags src_stage_flags, VkPipelineStageFlags dst_stage_flags, const VkImageMemoryBarrier &barrier) const

Call vkCmdPipelineBarrier

Parameters

  • src_stage_flags – The the source stage flags

  • dst_stage_flags – The destination stage flags

  • barrier – The image memory barrier

Returns

A const reference to the dereferenced this pointer (allowing for method calls to be chained)

const CommandBuffer &pipeline_memory_barrier(VkPipelineStageFlags src_stage_flags, VkPipelineStageFlags dst_stage_flags, const VkMemoryBarrier &barrier) const

Call vkCmdPipelineBarrier

Parameters

  • src_stage_flags – The the source stage flags

  • dst_stage_flags – The destination stage flags

  • barrier – The memory barrier

Returns

A const reference to the dereferenced this pointer (allowing for method calls to be chained)

const CommandBuffer &full_barrier() const

Call vkCmdPipelineBarrier to place a full memory barrier

Warning

You should avoid full barriers since they are not the most performant solution in most cases

const CommandBuffer &push_constants(VkPipelineLayout layout, VkShaderStageFlags stage, std::uint32_t size, const void *data, VkDeviceSize offset = 0) const

Call vkCmdPushConstants

Parameters

  • layout – The pipeline layout

  • stage – The shader stage that will be accepting the push constants

  • size – The size of the push constant data in bytes

  • data – A pointer to the push constant data

  • offset – The offset value (0 by default)

Returns

A const reference to the this pointer (allowing method calls to be chained)

template<typename T>
inline const CommandBuffer &push_constant(const VkPipelineLayout layout, const T &data, const VkShaderStageFlags stage, const VkDeviceSize offset = 0) const

Call vkCmdPushConstants

Template Parameters

T – the data type of the push constant

Parameters

  • layout – The pipeline layout

  • data – A const reference to the data

  • stage – The shader stage that will be accepting the push constants

  • offset – The offset value (0 by default)

Returns

A const reference to the this pointer (allowing method calls to be chained)

inline VkCommandBuffer get() const
inline const Fence &get_wait_fence() const
inline const VkCommandBuffer *ptr() const
const CommandBuffer &reset_fence() const

Call the reset method of the Fence member.

const CommandBuffer &submit(std::span<const VkSubmitInfo> submit_infos) const

Call vkQueueSubmit

Parameters

submit_infos – The submit infos

const CommandBuffer &submit(VkSubmitInfo submit_infos) const

Call vkQueueSubmit

Parameters

submit_info – The submit info

const CommandBuffer &submit() const

Call vkQueueSubmit.

const CommandBuffer &submit_and_wait(std::span<const VkSubmitInfo> submit_infos) const

Call vkQueueSubmit and use a fence to wait for command buffer submission and execution to complete

Parameters

submit_infos – The submit infos

const CommandBuffer &submit_and_wait(VkSubmitInfo submit_info) const

Call vkQueueSubmit and use a fence to wait for command buffer submission and execution to complete

Parameters

submit_info – The submit info

const CommandBuffer &submit_and_wait() const

Call vkQueueSubmit and use a fence to wait for command buffer submission and execution to complete.

Private Functions

const CommandBuffer &begin_command_buffer(VkCommandBufferUsageFlags flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT) const

Call vkBeginCommandBuffer

Parameters

flags – The command buffer usage flags, VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT by default

inline VkBuffer create_staging_buffer(const void *data, const VkDeviceSize data_size, const std::string &name) const

Create a new staging buffer which will be stored internally for a copy operation

Parameters

  • data – A raw pointer to the data to copy (must not be nullptr)

  • data_size – The size of the data to copy (must be greater than 0)

  • name – The internal name of the staging buffer (must not be empty)

Returns

A VkBuffer which contains the staging buffer data

template<typename DataType>
inline VkBuffer create_staging_buffer(const std::span<const DataType> data, const std::string &name) const

Create a new staging buffer which will be stored internally for a copy operation

Template Parameters

The – data type of the staging buffer

Parameters

  • data – A std::span of the source data

  • name – The internal name of the staging buffer (must not be empty)

Returns

The staging buffer’s VkBuffer

const CommandBuffer &end_command_buffer() const

Call vkEndCommandBuffer

Returns

A const reference to the this pointer (allowing method calls to be chained)

Private Members

VkCommandBuffer m_command_buffer = {VK_NULL_HANDLE}
const Device &m_device
std::string m_name
std::unique_ptr<Fence> m_wait_fence
mutable std::vector<GPUMemoryBuffer> m_staging_bufs

The staging buffers which are maybe used in the command buffer This vector of staging buffers will be cleared every time begin_command_buffer is called

Note

We are not recycling staging buffers. Once they are used and the command buffer handle has reached the end of its lifetime, the staging bufers will be cleared. We trust Vulkan Memory Allocator (VMA) in managing the memory for staging buffers.

Friends

friend class Device
friend class CommandPool