class new in Git master
#include <Magnum/Vk/CommandBuffer.h>
CommandBuffer 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::
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::
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::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::
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::
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_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_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_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:
- the render pass has to contain at least one SubpassDependency to itself, with scopes that are a superset of scopes defined here
bufferMemoryBarriers
has to be empty,- all images in
imageMemoryBarriers
have to be contained in both SubpassDescription::setInputAttachments() and SubpassDescription:: setColorAttachments() / SubpassDescription:: setDepthStencilAttachment(), - and old and new ImageLayout in
imageMemoryBarriers
have to be equal
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::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::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::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::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:: |
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_
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:: |
layout | Image layout. Can be either ImageLayout:: |
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::
A single VkImageSubresourceRange is passed to the command, with the following fields are set:
aspectMask
to VK_IMAGE_ ASPECT_ COLOR baseMipLevel
to0
levelCount
to VK_REMAINING_ MIP_ LEVELS baseArrayLayer
to0
layerCount
to VK_REMAINING_ ARRAY_ LAYERS
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:: |
layout | Image layout. Can be either ImageLayout:: |
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::
A single VkImageSubresourceRange is passed to the command, with the following fields are set:
aspectMask
to VK_IMAGE_ ASPECT_ DEPTH and VK_ IMAGE_ ASPECT_ STENCIL baseMipLevel
to0
levelCount
to VK_REMAINING_ MIP_ LEVELS baseArrayLayer
to0
layerCount
to VK_REMAINING_ ARRAY_ LAYERS
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:: |
layout | Image layout. Can be either ImageLayout:: |
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::
A single VkImageSubresourceRange is passed to the command, with the following fields are set:
aspectMask
to VK_IMAGE_ ASPECT_ DEPTH baseMipLevel
to0
levelCount
to VK_REMAINING_ MIP_ LEVELS baseArrayLayer
to0
layerCount
to VK_REMAINING_ ARRAY_ LAYERS
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:: |
layout | Image layout. Can be either ImageLayout:: |
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::
A single VkImageSubresourceRange is passed to the command, with the following fields set:
aspectMask
to VK_IMAGE_ ASPECT_ STENCIL baseMipLevel
to0
levelCount
to VK_REMAINING_ MIP_ LEVELS baseArrayLayer
to0
layerCount
to VK_REMAINING_ ARRAY_ LAYERS
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_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_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_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_pNext
chain in info
and its substructures has to be empty. See Copying image data for details and usage examples.