class CommandBuffer

class CommandBuffer

Defined at line 76 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

CommandBuffer is a wrapper around VkCommandBuffer, which significantly

improves upon the usability of the raw Vulkan object in a number of ways.

Most notably, CommandBuffer provides an "OpenGL-like" approach to resource

binding and pipeline generation. Users of CommandBuffer never directly deal

with VkPipelines, VkRenderPasses, VkFramebuffers, and others; these are

created behind the scenes, and cached for efficiency. For example, the exact

same shader code might require muliple VkPipeline variants to be generated,

for example if different depth-comparison ops are to be used. CommandBuffer

frees clients of the burden of manually generating and managing these

VkPipeline variants. Instead, clients simply call SetShaderProgram(), and

the appropriate variants are lazily generated when necessary, based on the

ShaderProgram and other CommandBuffer state (e.g. depth/stencil state, the

strides/formats/offsets of currently-bound vertex buffers, etc.).

NOTE: this functionality can be disabled on a per-CommandBuffer basis by calling

DisableLazyPipelineCreation(). Afterward, this will result in a failed CHECK in

any situation that would normally generate a new Pipeline or RenderPass. The app

is responsible for ensuring that all necessary pipelines are generated before

calling this function.

Another major convenience provided by CommandBuffer is life-cycle management

of resources that are no longer needed. Vulkan forbids client applications

from destroying any resource that is referenced by a "pending command buffer"

(i.e. one whose commands have not finished executing on the GPU). Instead of

being destroyed immediately, resources whose ref-counts reach zero are kept

alive until all command buffers that reference them have finished executing.

Not thread safe.

Public Methods

CommandBufferPtr NewForType (Escher * escher, Type type, bool use_protected_memory)

Constructors.

Defined at line 52 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

CommandBufferPtr NewForGraphics (Escher * escher, bool use_protected_memory)

Defined at line 68 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

CommandBufferPtr NewForCompute (Escher * escher, bool use_protected_memory)

Defined at line 75 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

CommandBufferPtr NewForTransfer (Escher * escher)

Defined at line 82 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

Type type ()

Defined at line 86 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

vk::CommandBuffer vk ()

Defined at line 88 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

vk::Device vk_device ()

Defined at line 89 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

impl::CommandBuffer * impl ()

TODO(https://fxbug.dev/42151125): deprecated from the get-go.

Defined at line 91 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

bool use_protected_memory ()

Defined at line 93 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

size_t NumWaitSemaphores ()

Defined at line 95 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

size_t NumSignalSemaphores ()

Defined at line 96 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

bool Submit (CommandBufferFinishedCallback callback)

Submits the command buffer on the appropriate queue: the main queue for

graphics and compute tasks, and the transfer queue for dedicated transfer

operations.

TODO(https://fxbug.dev/42151125): this is a placeholder; the submission API will be refined.

Defined at line 99 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void DisableLazyPipelineCreation ()

See class comment. This function makes it illegal to trigger creation of a new pipeline;

it is the app's responsibility to ensure that all required pipelines are generated in advance.

Defined at line 100 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void KeepAlive (Resource * resource)

These resources will be retained until the command-buffer is finished

running on the GPU.

Defined at line 104 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

template <typename ResourceT>
void KeepAlive (const fxl::RefPtr<ResourceT> & ptr)

Defined at line 106 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

uint64_t sequence_number ()

Each CommandBuffer that is obtained from a CommandBufferPool is given a

monotonically-increasing sequence number. This number is globally unique

(per Escher instance), even across multiple CommandBufferPools.

Defined at line 113 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void AddWaitSemaphore (SemaphorePtr semaphore, vk::PipelineStageFlags stage)

During Submit(), these semaphores will be added to the vk::SubmitInfo.

No-op if semaphore is null

Defined at line 117 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void AddSignalSemaphore (SemaphorePtr semaphore)

During Submit(), these semaphores will be added to the vk::SubmitInfo.

No-op if semaphore is null.

Defined at line 123 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

bool ContainsSignalSemaphore (const SemaphorePtr & semaphore)

Checks to see if the provided semaphore is part of the command buffer's vector

of signal semaphores.

Defined at line 127 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void TransitionImageLayout (const ImagePtr & image, vk::ImageLayout old_layout, vk::ImageLayout new_layout, uint32_t src_queue_family_index, uint32_t dst_queue_family_index)

Transition the image between the two layouts; see section 11.4 of the

Vulkan spec. Retain image in used_resources.

Defined at line 133 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void BeginRenderPass (const RenderPassInfo & info)

Wraps vkCmdBeginRenderPass(). Uses |info| to obtain a cached VkRenderPass

and VkFramebuffer.

Defined at line 144 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

bool Submit (vk::Queue queue, CommandBufferFinishedCallback callback)

Defined at line 147 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

template <typename StructT>
void PushConstants (const StructT * data, vk::DeviceSize offset)

Defined at line 175 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

template <typename StructT>
void PushConstants (const StructT & data, vk::DeviceSize offset)

Defined at line 179 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void BindTexture (unsigned int set, unsigned int binding, const TexturePtr & texture)

Defined at line 196 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void BindInputAttachment (unsigned int set, unsigned int binding, const ImageViewPtr & view)

Defined at line 202 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void BindVertices (uint32_t binding, const BufferPtr & buffer, vk::DeviceSize offset, vk::DeviceSize stride, vk::VertexInputRate step_rate)

Defined at line 215 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void EndRenderPass ()

Wraps vkCmdEndRenderPass().

Defined at line 219 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void SetVertexAttributes (uint32_t binding, uint32_t attrib, vk::Format format, uint32_t offset)

Set/dirty the attributes that will be used to interpret the vertex buffer

at |binding| (see BindVertices() above) when the next draw call is made.

Defined at line 230 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void BufferBarrier (const BufferPtr & buffer, vk::PipelineStageFlags src_stages, vk::AccessFlags src_access, vk::PipelineStageFlags dst_stages, vk::AccessFlags dst_access)

Wraps vkCmdPipelineBarrier(), using a barrier consisting of a single

VkBufferMemoryBarrier. Keeps |buffer| alive while command buffer is pending.

Defined at line 247 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void ImageBarrier (const ImagePtr & image, vk::ImageLayout old_layout, vk::ImageLayout new_layout, vk::PipelineStageFlags src_stages, vk::AccessFlags src_access, vk::PipelineStageFlags dst_stages, vk::AccessFlags dst_access, uint32_t src_queue_family_index, uint32_t dst_queue_family_index)

Wraps vkCmdPipelineBarrier(), using a barrier consisting of a single

VkImageMemoryBarrier. Keeps |image| alive while command buffer is pending.

Defined at line 264 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void SetShaderProgram (const ShaderProgramPtr & program, const SamplerPtr & immutable_sampler)

Defined at line 281 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void PushConstants (const void * data, vk::DeviceSize offset, vk::DeviceSize range)

Defers call to vkCmdPushConstants() via kDirtyPushConstantsBit.

Defined at line 299 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void BindUniformBuffer (uint32_t set, uint32_t binding, const BufferPtr & buffer)

Set/dirty a uniform buffer binding that will later be flushed, causing

descriptor sets to be written/bound as necessary. Keeps |buffer| alive

while command buffer is pending.

Defined at line 305 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void BindUniformBuffer (uint32_t set, uint32_t binding, const BufferPtr & buffer, vk::DeviceSize offset, vk::DeviceSize range)

Defined at line 309 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void BindUniformBuffer (uint32_t set, uint32_t binding, Buffer * buffer, vk::DeviceSize offset, vk::DeviceSize range)

Defined at line 314 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void BindTexture (unsigned int set, unsigned int binding, const Texture * texture)

Set/dirty a texture binding that will later be flushed, causing descriptor

sets to be written/bound as necessary. Keeps |texture| alive while command

buffer is pending.

Defined at line 331 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void BindInputAttachment (unsigned int set_index, unsigned int binding, const ImageView * view)

Set/dirty an input attachment binding, for use with subpasses.

Defined at line 363 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void BindVertices (uint32_t binding, vk::Buffer buffer, vk::DeviceSize offset, vk::DeviceSize stride, vk::VertexInputRate step_rate)

Set/dirty a vertex buffer binding that will later be flushed, causing

descriptor sets to be written/bound as necessary.

Defined at line 403 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void BindVertices (uint32_t binding, Buffer * buffer, vk::DeviceSize offset, vk::DeviceSize stride, vk::VertexInputRate step_rate)

These two variants keep |buffer| alive while the command buffer is pending;

the one above makes this the responsibility of the caller.

Defined at line 413 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void BindIndices (vk::Buffer buffer, vk::DeviceSize offset, vk::IndexType index_type)

Sets the current index buffer binding; this happens immediately because

index buffer changes never require descriptor sets to be written or new

pipelines to be generated.

Defined at line 419 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void BindIndices (const BufferPtr & buffer, vk::DeviceSize offset, vk::IndexType index_type)

This variant keeps |buffer| alive while command buffer is pending.

Defined at line 436 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void DrawIndexed (uint32_t index_count, uint32_t instance_count, uint32_t first_index, int32_t vertex_offset, uint32_t first_instance)

Wraps vkCmdDrawIndexed(), first flushing any dirty render state; this may

cause descriptor sets to be written/bound, or a new pipeline to be created.

Defined at line 442 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void Draw (uint32_t vertex_count, uint32_t instance_count, uint32_t first_vertex, uint32_t first_instance)

Wraps vkCmdDraw() which is able to render raw vertices without using an index buffer.

Defined at line 456 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void Dispatch (uint32_t groupXCount, uint32_t groupYCount, uint32_t groupZCount)

Wraps vkCmdDispatch().

Defined at line 468 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void ClearAttachmentRect (uint32_t subpass_color_attachment_index, const vk::ClearRect & rect, const vk::ClearValue & value, vk::ImageAspectFlags aspect)

Wraps vkCmdClearAttachments(). Clears the specified rectangle of the

specified attachment (see RenderPassInfo), filling it with the specified

values.

Defined at line 858 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void ClearColorAttachmentRect (uint32_t subpass_color_attachment_index, vk::Offset2D offset, vk::Extent2D extent, const vk::ClearColorValue & value)

Convenient version of ClearAttachmentRect() for color attachments.

NOTE: uses baseArrayLayer == 0 and layerCount == 1.

Defined at line 868 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void ClearDepthStencilAttachmentRect (vk::Offset2D offset, vk::Extent2D extent, const vk::ClearDepthStencilValue & value, vk::ImageAspectFlags aspect)

Convenient version of ClearAttachmentRect() for depth/stencil attachments.

NOTE: uses baseArrayLayer == 0 and layerCount == 1.

Defined at line 877 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void Blit (const ImagePtr & src_image, vk::Offset2D src_offset, vk::Extent2D src_extent, const ImagePtr & dst_image, vk::Offset2D dst_offset, vk::Extent2D dst_extent, vk::Filter filter)

Simple blit between base layers of two images.

Defined at line 885 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void SetToDefaultState (DefaultState state)

Defined at line 770 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void SetShaderProgram (ShaderProgram * program, const SamplerPtr & immutable_sampler)

Set the ShaderProgram that will be used to obtain the VkPipeline to be used

by the next draw-call or compute dispatch. If a valid vk::Sampler object is

passed in, that sampler will be used as the immutable sampler for every

sampler descriptor set in the associated PipelineLayout.

TODO(https://fxbug.dev/42152423): This code-flow assumes that ShaderPrograms source from, at

most, a single sampler. This is a blocking bug for implementing, e.g.,

https://fxbug.dev/42151968.

Defined at line 908 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void SetViewport (const vk::Viewport & viewport)

Set the viewport. Must be called within a render pass.

Defined at line 618 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetScissor (const vk::Rect2D & rect)

Set the scissor rect. Must be called within a render pass.

Defined at line 627 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetBlendConstants (const float[4] blend_constants)

The following functions set static state that might result in generation of

a new pipeline variant.

Defined at line 732 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetBlendEnable (bool blend_enable)

Defined at line 649 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetBlendFactors (vk::BlendFactor src_color_blend, vk::BlendFactor src_alpha_blend, vk::BlendFactor dst_color_blend, vk::BlendFactor dst_alpha_blend)

Defined at line 651 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetBlendFactors (vk::BlendFactor src_blend, vk::BlendFactor dst_blend)

Defined at line 661 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetBlendOp (vk::BlendOp color_blend_op, vk::BlendOp alpha_blend_op)

Defined at line 665 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetBlendOp (vk::BlendOp blend_op)

Defined at line 670 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetColorWriteMask (uint32_t color_write_mask)

Packs vk::ColorComponentFlags for many color attachments into a 32-bit int.

Each attachment uses 4 bits, one for each of the RGBA components, for a

maximum of 8 attachments. Not coincidentally, this is the value of

VulkanLimits::kNumColorAttachments. Color attachment #0 is stored in the

least-significant 4 bits.

Defined at line 672 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetCullMode (vk::CullModeFlags cull_mode)

Defined at line 728 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetDepthBias (bool depth_bias_enable)

Defined at line 676 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetDepthBias (float depth_bias_constant, float depth_bias_slope)

Defined at line 739 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetDepthCompareOp (vk::CompareOp depth_compare)

Defined at line 645 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetDepthTestAndWrite (bool depth_test, bool depth_write)

Defined at line 638 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetFrontFace (vk::FrontFace front_face)

Defined at line 724 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetMultisampleState (bool alpha_to_coverage, bool alpha_to_one, bool sample_shading)

Defined at line 717 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetStencilBackOps (vk::CompareOp stencil_back_compare_op, vk::StencilOp stencil_back_pass, vk::StencilOp stencil_back_fail, vk::StencilOp stencil_back_depth_fail)

Defined at line 692 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetStencilBackReference (uint8_t back_compare_mask, uint8_t back_write_mask, uint8_t back_reference)

Defined at line 752 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetStencilFrontOps (vk::CompareOp stencil_front_compare_op, vk::StencilOp stencil_front_pass, vk::StencilOp stencil_front_fail, vk::StencilOp stencil_front_depth_fail)

Defined at line 682 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetStencilFrontReference (uint8_t front_compare_mask, uint8_t front_write_mask, uint8_t front_reference)

Defined at line 744 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetStencilOps (vk::CompareOp stencil_compare_op, vk::StencilOp stencil_pass, vk::StencilOp stencil_fail, vk::StencilOp stencil_depth_fail)

Defined at line 702 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetStencilTest (bool stencil_test)

Defined at line 680 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetPrimitiveRestart (bool primitive_restart)

Defined at line 713 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetPrimitiveTopology (vk::PrimitiveTopology primitive_topology)

Defined at line 709 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void SetWireframe (bool wireframe)

Defined at line 643 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

void NextSubpass ()

Sets the next subpass for the render pass we are currently in.

Defined at line 240 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void SaveState (SavedStateFlags flags, SavedState * state)

Defined at line 775 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

void RestoreState (const CommandBuffer::SavedState & state)

Defined at line 805 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.cc

Enumerations

enum class Type
Name Value
kGraphics 0
kCompute 1
kTransfer 2
kEnumCount 3

Defined at line 78 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

enum SavedStateBits
Name Value
kSavedBindingsBit0 1u << 0
kSavedBindingsBit1 1u << 1
kSavedBindingsBit2 1u << 2
kSavedBindingsBit3 1u << 3
kSavedViewportBit 1u << 4
kSavedScissorBit 1u << 5
kSavedRenderStateBit 1u << 6
kSavedPushConstantBit 1u << 7

Flags that identify the specific state that is saved in a SavedState (any

other state is undefined and should not be used).

Defined at line 405 of file ../../src/ui/lib/escher/third_party/granite/vk/command_buffer.h

Records

Friends

class VulkanTester