Magnum::Vk::CommandBuffer class new in Git master
#include <Magnum/Vk/CommandBuffer.h>

Command buffer.

Wraps a VkCommandBuffer. Command buffers are used to record all work done on a Vulkan device such as pipeline setup, draws, compute dispatch or data transfers.

Command buffer allocation and recycling

A command buffer instance is allocated from a CommandPool as shown below. Each command buffers is freed at the end of the CommandBuffer instance lifetime, you can also put all allocated buffers back to initial state by calling CommandPool::reset(), or alternatively reset each buffer separately using reset(), if the pool was created with CommandPoolCreateInfo::Flag::ResetCommandBuffer.

Vk::CommandPool commandPool{device, …};

Vk::CommandBuffer cmd = commandPool.allocate();

Command buffer recording and submit

A command buffer recording is initiated with begin(), after which you can execute commands that are allowed outside a render pass. A render pass is delimited with beginRenderPass() and endRenderPass(), see Render pass recording for details. Once a recording is done, call end(). You can (but don't have to) use method chaining:

cmd.begin()
   …
   .end();

Once recorded, call Queue::submit() to submit the command buffer to a compatible Queue that was set up at device creation time. Usually you'd want to wait on the submit completion with a Fence:

Vk::Queue queue{…};

Vk::Fence fence{device};
queue.submit({Vk::SubmitInfo{}.setCommandBuffers({cmd})}, fence);
fence.wait();

Public static functions

static auto wrap(Device& device, VkCommandPool pool, VkCommandBuffer handle, HandleFlags flags = {}) -> CommandBuffer
Wrap existing Vulkan handle.

Constructors, destructors, conversion operators

CommandBuffer(NoCreateT) explicit noexcept
Construct without creating the instance.
CommandBuffer(const CommandBuffer&) deleted
Copying is not allowed.
CommandBuffer(CommandBuffer&& other) noexcept
Move constructor.
~CommandBuffer()
Destructor.
operator VkCommandBuffer()

Public functions

auto operator=(const CommandBuffer&) -> CommandBuffer& deleted
Copying is not allowed.
auto operator=(CommandBuffer&& other) -> CommandBuffer& noexcept
Move assignment.
auto handle() -> VkCommandBuffer
Underlying VkCommandBuffer handle.
auto handleFlags() const -> HandleFlags
Handle flags.
auto dynamicRasterizationStates() const -> DynamicRasterizationStates
Dynamic states used by currently bound rasterization pipeline.
void reset(CommandBufferResetFlags flags = {})
Reset the command buffer.
auto release() -> VkCommandBuffer
Release the underlying Vulkan command buffer.
auto begin(const CommandBufferBeginInfo& info = CommandBufferBeginInfo{}) -> CommandBuffer&
Begin command buffer recording.
void end()
End command buffer recording.
auto beginRenderPass(const RenderPassBeginInfo& info, const SubpassBeginInfo& beginInfo = SubpassBeginInfo{}) -> CommandBuffer&
Begin a new render pass.
auto nextSubpass(const SubpassEndInfo& endInfo = SubpassEndInfo{}, const SubpassBeginInfo& beginInfo = SubpassBeginInfo{}) -> CommandBuffer&
Transition to the next subpass of a render pass.
auto nextSubpass(const SubpassBeginInfo& beginInfo) -> CommandBuffer&
auto endRenderPass(const SubpassEndInfo& endInfo = SubpassEndInfo{}) -> CommandBuffer&
Transition to the next subpass of a render pass.
auto bindPipeline(Pipeline& pipeline) -> CommandBuffer&
Bind a pipeline.
auto draw(Mesh& mesh) -> CommandBuffer&
Draw a mesh.
auto pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, Containers::ArrayView<const MemoryBarrier> memoryBarriers, Containers::ArrayView<const BufferMemoryBarrier> bufferMemoryBarriers, Containers::ArrayView<const ImageMemoryBarrier> imageMemoryBarriers, DependencyFlags dependencyFlags = {}) -> CommandBuffer&
Insert an execution barrier with optional memory dependencies.
auto pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, std::initializer_list<MemoryBarrier> memoryBarriers, std::initializer_list<BufferMemoryBarrier> bufferMemoryBarriers, std::initializer_list<ImageMemoryBarrier> imageMemoryBarriers, DependencyFlags dependencyFlags = {}) -> CommandBuffer&
auto pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, DependencyFlags dependencyFlags = {}) -> CommandBuffer&
Insert an execution barrier without memory dependencies.
auto pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, Containers::ArrayView<const MemoryBarrier> memoryBarriers, DependencyFlags dependencyFlags = {}) -> CommandBuffer&
Insert a global memory dependency.
auto pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, std::initializer_list<MemoryBarrier> memoryBarriers, DependencyFlags dependencyFlags = {}) -> CommandBuffer&
auto pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, Containers::ArrayView<const BufferMemoryBarrier> bufferMemoryBarriers, DependencyFlags dependencyFlags = {}) -> CommandBuffer&
Insert a buffer memory dependency.
auto pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, std::initializer_list<BufferMemoryBarrier> bufferMemoryBarriers, DependencyFlags dependencyFlags = {}) -> CommandBuffer&
auto pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, Containers::ArrayView<const ImageMemoryBarrier> imageMemoryBarriers, DependencyFlags dependencyFlags = {}) -> CommandBuffer&
Insert an image memory dependency.
auto pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, std::initializer_list<ImageMemoryBarrier> imageMemoryBarriers, DependencyFlags dependencyFlags = {}) -> CommandBuffer&
auto fillBuffer(VkBuffer buffer, UnsignedLong offset, UnsignedLong size, UnsignedInt value) -> CommandBuffer&
Fill a buffer region with a fixed value.
auto fillBuffer(VkBuffer buffer, UnsignedInt value) -> CommandBuffer&
Fill the whole buffer with a fixed value.
auto clearColorImage(VkImage image, ImageLayout layout, const Color4& color) -> CommandBuffer&
Clear a floating-point or normalized color image.
auto clearColorImage(VkImage image, ImageLayout layout, const Vector4i& color) -> CommandBuffer&
Clear a signed integral color image.
auto clearColorImage(VkImage image, ImageLayout layout, const Vector4ui& color) -> CommandBuffer&
Clear an unsigned integral color image.
auto clearDepthStencilImage(VkImage image, ImageLayout layout, Float depth, UnsignedInt stencil) -> CommandBuffer&
Clear a combined depth/stencil image.
auto clearDepthImage(VkImage image, ImageLayout layout, Float depth) -> CommandBuffer&
Clear a depth-only image.
auto clearStencilImage(VkImage image, ImageLayout layout, UnsignedInt stencil) -> CommandBuffer&
Clear a stencil-only image.
auto copyBuffer(const CopyBufferInfo& info) -> CommandBuffer&
Copy data between buffer regions.
auto copyImage(const CopyImageInfo& info) -> CommandBuffer&
Copy data between images.
auto copyBufferToImage(const CopyBufferToImageInfo& info) -> CommandBuffer&
Copy data from a buffer into an image.
auto copyImageToBuffer(const CopyImageToBufferInfo& info) -> CommandBuffer&
Copy image data into a buffer.

Function documentation

static CommandBuffer Magnum::Vk::CommandBuffer::wrap(Device& device, VkCommandPool pool, VkCommandBuffer handle, HandleFlags flags = {})

Wrap existing Vulkan handle.

Parameters
device Vulkan device the command buffer is created on
pool Command pool the buffer is allocated from
handle The VkCommandBuffer handle
flags Handle flags

The handle is expected to be of an existing Vulkan command buffer. Unlike a command buffer allocated using CommandPool::allocate(), the Vulkan command buffer is by default not deleted on destruction, use flags for different behavior.

Magnum::Vk::CommandBuffer::CommandBuffer(NoCreateT) explicit noexcept

Construct without creating the instance.

The constructed instance is equivalent to moved-from state. Useful in cases where you will overwrite the instance later anyway. Move another object over it to make it useful.

Magnum::Vk::CommandBuffer::~CommandBuffer()

Destructor.

Frees associated VkCommandBuffer handle, unless the instance was created using wrap() without HandleFlag::DestroyOnDestruction specified.

Magnum::Vk::CommandBuffer::operator VkCommandBuffer()

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

DynamicRasterizationStates Magnum::Vk::CommandBuffer::dynamicRasterizationStates() const

Dynamic states used by currently bound rasterization pipeline.

If no rasterization pipeline is bound or there are no dynamic states on the currently bound one, returns an empty set.

void Magnum::Vk::CommandBuffer::reset(CommandBufferResetFlags flags = {})

Reset the command buffer.

This operation is allowed only if the originating CommandPool was created with CommandPoolCreateInfo::Flag::ResetCommandBuffer. If not, the only way to reset is to reset the whole command pool using CommandPool::reset().

VkCommandBuffer Magnum::Vk::CommandBuffer::release()

Release the underlying Vulkan command buffer.

Releases ownership of the Vulkan command buffer and returns its handle so vkFreeCommandBuffers() is not called on destruction. The internal state is then equivalent to moved-from state.

CommandBuffer& Magnum::Vk::CommandBuffer::begin(const CommandBufferBeginInfo& info = CommandBufferBeginInfo{})

Begin command buffer recording.

Returns Reference to self (for method chaining)

void Magnum::Vk::CommandBuffer::end()

End command buffer recording.

As this function is expected to be called last, it doesn't return a reference to self for method chaining.

CommandBuffer& Magnum::Vk::CommandBuffer::beginRenderPass(const RenderPassBeginInfo& info, const SubpassBeginInfo& beginInfo = SubpassBeginInfo{})

Begin a new render pass.

Returns Reference to self (for method chaining)

If Vulkan 1.2 is not supported and the KHR_create_renderpass2 extension is not enabled on the device, beginInfo has to have the pNext chain empty and only the contents field from it is used to begin the render pass.

CommandBuffer& Magnum::Vk::CommandBuffer::nextSubpass(const SubpassEndInfo& endInfo = SubpassEndInfo{}, const SubpassBeginInfo& beginInfo = SubpassBeginInfo{})

Transition to the next subpass of a render pass.

Returns Reference to self (for method chaining)

If Vulkan 1.2 is not supported and the KHR_create_renderpass2 extension is not enabled on the device, both endInfo and beginInfo have to have the pNext chain empty and only the contents field from beginInfo is used to begin the next subpass.

CommandBuffer& Magnum::Vk::CommandBuffer::nextSubpass(const SubpassBeginInfo& beginInfo)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CommandBuffer& Magnum::Vk::CommandBuffer::endRenderPass(const SubpassEndInfo& endInfo = SubpassEndInfo{})

Transition to the next subpass of a render pass.

Returns Reference to self (for method chaining)

If Vulkan 1.2 is not supported and the KHR_create_renderpass2 extension is not enabled on the device, endInfo has to have the pNext chain empty.

CommandBuffer& Magnum::Vk::CommandBuffer::bindPipeline(Pipeline& pipeline)

Bind a pipeline.

Returns Reference to self (for method chaining)

Can be called both inside and outside a render pass. If the pipeline is a rasterization pipeline, the set of its dynamic states is stored in dynamicRasterizationStates() for use by drawing and other commands. See Pipeline usage for a usage example.

CommandBuffer& Magnum::Vk::CommandBuffer::draw(Mesh& mesh)

Draw a mesh.

Returns Reference to self (for method chaining)

Can be only called inside a render pass with a graphics pipeline bound. See Drawing a mesh for a usage example.

CommandBuffer& Magnum::Vk::CommandBuffer::pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, Containers::ArrayView<const MemoryBarrier> memoryBarriers, Containers::ArrayView<const BufferMemoryBarrier> bufferMemoryBarriers, Containers::ArrayView<const ImageMemoryBarrier> imageMemoryBarriers, DependencyFlags dependencyFlags = {})

Insert an execution barrier with optional memory dependencies.

Parameters
sourceStages Source stages. Has to contain at least one stage.
destinationStages Destination stages. Has to contain at least one stage.
memoryBarriers Global memory barriers, affecting all memory
bufferMemoryBarriers Buffer memory barriers, restricted to a particular buffer
imageMemoryBarriers Image memory barriers, restricted to a particular image. These are also used for performing ImageLayout transitions.
dependencyFlags Dependency flags
Returns Reference to self (for method chaining)

Can be called both inside and outside a render pass. When called inside a render pass:

See Copying buffer data, Clearing image data and Copying image data for usage examples.

CommandBuffer& Magnum::Vk::CommandBuffer::pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, std::initializer_list<MemoryBarrier> memoryBarriers, std::initializer_list<BufferMemoryBarrier> bufferMemoryBarriers, std::initializer_list<ImageMemoryBarrier> imageMemoryBarriers, DependencyFlags dependencyFlags = {})

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CommandBuffer& Magnum::Vk::CommandBuffer::pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, DependencyFlags dependencyFlags = {})

Insert an execution barrier without memory dependencies.

Returns Reference to self (for method chaining)

Equivalent to calling pipelineBarrier(PipelineStages, PipelineStages, Containers::ArrayView<const MemoryBarrier>, Containers::ArrayView<const BufferMemoryBarrier>, Containers::ArrayView<const ImageMemoryBarrier>, DependencyFlags) with empty memoryBarriers, bufferBarriers and imageBarriers. Useful when an execution barrier is enough, for example when you need reads from one stage to finish before another stage starts writing to the same location.

CommandBuffer& Magnum::Vk::CommandBuffer::pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, Containers::ArrayView<const MemoryBarrier> memoryBarriers, DependencyFlags dependencyFlags = {})

Insert a global memory dependency.

Returns Reference to self (for method chaining)

Equivalent to calling pipelineBarrier(PipelineStages, PipelineStages, Containers::ArrayView<const MemoryBarrier>, Containers::ArrayView<const BufferMemoryBarrier>, Containers::ArrayView<const ImageMemoryBarrier>, DependencyFlags) with empty bufferBarriers and imageBarriers.

CommandBuffer& Magnum::Vk::CommandBuffer::pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, std::initializer_list<MemoryBarrier> memoryBarriers, DependencyFlags dependencyFlags = {})

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CommandBuffer& Magnum::Vk::CommandBuffer::pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, Containers::ArrayView<const BufferMemoryBarrier> bufferMemoryBarriers, DependencyFlags dependencyFlags = {})

Insert a buffer memory dependency.

Returns Reference to self (for method chaining)

Equivalent to calling pipelineBarrier(PipelineStages, PipelineStages, Containers::ArrayView<const MemoryBarrier>, Containers::ArrayView<const BufferMemoryBarrier>, Containers::ArrayView<const ImageMemoryBarrier>, DependencyFlags) with empty memoryBarriers and imageBarriers. See Copying buffer data for usage examples.

CommandBuffer& Magnum::Vk::CommandBuffer::pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, std::initializer_list<BufferMemoryBarrier> bufferMemoryBarriers, DependencyFlags dependencyFlags = {})

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CommandBuffer& Magnum::Vk::CommandBuffer::pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, Containers::ArrayView<const ImageMemoryBarrier> imageMemoryBarriers, DependencyFlags dependencyFlags = {})

Insert an image memory dependency.

Returns Reference to self (for method chaining)

Equivalent to calling pipelineBarrier(PipelineStages, PipelineStages, Containers::ArrayView<const MemoryBarrier>, Containers::ArrayView<const BufferMemoryBarrier>, Containers::ArrayView<const ImageMemoryBarrier>, DependencyFlags) with empty memoryBarriers and bufferBarriers. See Clearing image data and Copying image data for usage examples.

CommandBuffer& Magnum::Vk::CommandBuffer::pipelineBarrier(PipelineStages sourceStages, PipelineStages destinationStages, std::initializer_list<ImageMemoryBarrier> imageMemoryBarriers, DependencyFlags dependencyFlags = {})

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CommandBuffer& Magnum::Vk::CommandBuffer::fillBuffer(VkBuffer buffer, UnsignedLong offset, UnsignedLong size, UnsignedInt value)

Fill a buffer region with a fixed value.

Parameters
buffer Source Buffer or a raw Vulkan buffer handle to fill. Expected to have been created with BufferUsage::TransferDestination.
offset Offset of the region to fill, in bytes
size Size of the region to fill, in bytes
value A 4-byte value to repeat in the region, interpreted accoding to the machine endianness. If size is not divisible by 4, the last remaining bytes are not filled.
Returns Reference to self (for method chaining)

Allowed only outside of a render pass. See Clearing / filling buffer data for a usage example.

CommandBuffer& Magnum::Vk::CommandBuffer::fillBuffer(VkBuffer buffer, UnsignedInt value)

Fill the whole buffer with a fixed value.

Returns Reference to self (for method chaining)

Allowed only outside of a render pass. Equivalent to fillBuffer(VkBuffer, UnsignedLong, UnsignedLong, UnsignedInt) with offset set to 0 and size to VK_WHOLE_SIZE.

CommandBuffer& Magnum::Vk::CommandBuffer::clearColorImage(VkImage image, ImageLayout layout, const Color4& color)

Clear a floating-point or normalized color image.

Parameters
image An Image or a raw Vulkan image handle to clear. Expected to have been created with ImageUsage::TransferDestination and a floating-point or normalized non-compressed PixelFormat usable for transfer destination.
layout Image layout. Can be either ImageLayout::General or ImageLayout::TransferDestination.
color Color to clear the image with
Returns Reference to self (for method chaining)

Allowed only outside of a render pass. For clearing inside a render pass you can either specify AttachmentLoadOperation::Clear for a particular attachment, which will clear it on render pass begin (see Render pass recording for an example), or use vkCmdClearAttachments() which allows you to clear at any time inside a render pass. See Clearing image data for a usage example.

A single VkImageSubresourceRange is passed to the command, with the following fields are set:

CommandBuffer& Magnum::Vk::CommandBuffer::clearColorImage(VkImage image, ImageLayout layout, const Vector4i& color)

Clear a signed integral color image.

Returns Reference to self (for method chaining)

Allowed only outside of a render pass. Behaves like clearColorImage(VkImage, ImageLayout, const Color4&), except that it's meant for images with a signed integral non-compressed PixelFormat.

CommandBuffer& Magnum::Vk::CommandBuffer::clearColorImage(VkImage image, ImageLayout layout, const Vector4ui& color)

Clear an unsigned integral color image.

Returns Reference to self (for method chaining)

Allowed only outside of a render pass. Behaves like clearColorImage(VkImage, ImageLayout, const Color4&), except that it's meant for images with an unsigned integral non-compressed PixelFormat.

CommandBuffer& Magnum::Vk::CommandBuffer::clearDepthStencilImage(VkImage image, ImageLayout layout, Float depth, UnsignedInt stencil)

Clear a combined depth/stencil image.

Parameters
image An Image or a raw Vulkan image handle to clear. Expected to have been be created with ImageUsage::TransferDestination and a combined depth/stencil PixelFormat usable for transfer destination.
layout Image layout. Can be either ImageLayout::General or ImageLayout::TransferDestination.
depth Depth value to clear with
stencil Stencil value to clear with
Returns Reference to self (for method chaining)

Allowed only outside of a render pass. For clearing inside a render pass you can either specify AttachmentLoadOperation::Clear for a particular attachment, which will clear it on render pass begin (see Render pass recording for an example), or use vkCmdClearAttachments() which allows you to clear at any point inside a render pass. For clearing a depth-only or a stencil-only image (or just a depth orstencil buffer of a combined depth/stencil image) use clearDepthImage() or clearStencilImage() instead. See Clearing image data for a usage example.

A single VkImageSubresourceRange is passed to the command, with the following fields are set:

CommandBuffer& Magnum::Vk::CommandBuffer::clearDepthImage(VkImage image, ImageLayout layout, Float depth)

Clear a depth-only image.

Parameters
image An Image or a raw Vulkan image handle to clear. Expected to have been be created with ImageUsage::TransferDestination and a depth-only PixelFormat usable for transfer destination.
layout Image layout. Can be either ImageLayout::General or ImageLayout::TransferDestination.
depth Depth value to clear with
Returns Reference to self (for method chaining)

Allowed only outside of a render pass. For clearing inside a render pass you can either specify AttachmentLoadOperation::Clear for a particular attachment, which will clear it on render pass begin (see Render pass recording for an example), or use vkCmdClearAttachments() which allows you to clear at any point inside a render pass. For clearing a combined depth/stencil image use clearDepthStencilImage(), for clearing a stencil-only image or just the stencil buffer of a combined depth/stencil image use clearStencilImage() instead. See Clearing image data for a usage example.

A single VkImageSubresourceRange is passed to the command, with the following fields are set:

CommandBuffer& Magnum::Vk::CommandBuffer::clearStencilImage(VkImage image, ImageLayout layout, UnsignedInt stencil)

Clear a stencil-only image.

Parameters
image An Image or a raw Vulkan image handle to clear. Expected to have been be created with ImageUsage::TransferDestination and a stencil-only PixelFormat usable for transfer destination.
layout Image layout. Can be either ImageLayout::General or ImageLayout::TransferDestination.
stencil Stencil value to clear with
Returns Reference to self (for method chaining)

Allowed only outside of a render pass. For clearing inside a render pass you can either specify AttachmentLoadOperation::Clear for a particular attachment, which will clear it on render pass begin (see Render pass recording for an example), or use vkCmdClearAttachments() which allows you to clear at any point inside a render pass. For clearing a combined depth/stencil image use clearDepthStencilImage(), for clearing a depth-only image or just the depth buffer of a combined depth/stencil image use clearDepthImage() instead. See Clearing image data for a usage example.

A single VkImageSubresourceRange is passed to the command, with the following fields set:

CommandBuffer& Magnum::Vk::CommandBuffer::copyBuffer(const CopyBufferInfo& info)

Copy data between buffer regions.

Returns Reference to self (for method chaining)

Allowed only outside of a render pass. If the KHR_copy_commands2 extension is not supported and enabled on the device, the pNext chain in info and its substructures has to be empty. See Copying buffer data for details and usage examples.

CommandBuffer& Magnum::Vk::CommandBuffer::copyImage(const CopyImageInfo& info)

Copy data between images.

Returns Reference to self (for method chaining)

Allowed only outside of a render pass. If the KHR_copy_commands2 extension is not supported and enabled on the device, the pNext chain in info and its substructures has to be empty. See Copying image data for details and usage examples.

CommandBuffer& Magnum::Vk::CommandBuffer::copyBufferToImage(const CopyBufferToImageInfo& info)

Copy data from a buffer into an image.

Returns Reference to self (for method chaining)

Allowed only outside of a render pass. If the KHR_copy_commands2 extension is not supported and enabled on the device, the pNext chain in info and its substructures has to be empty. See Copying image data for details and usage examples.

CommandBuffer& Magnum::Vk::CommandBuffer::copyImageToBuffer(const CopyImageToBufferInfo& info)

Copy image data into a buffer.

Returns Reference to self (for method chaining)

Allowed only outside of a render pass. If the KHR_copy_commands2 extension is not supported and enabled on the device, the pNext chain in info and its substructures has to be empty. See Copying image data for details and usage examples.