| Flutter Impeller |

Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
impeller::CommandBuffer Class Referenceabstract

A collection of encoded commands to be submitted to the GPU for execution. A command buffer is obtained from a graphics `Context`. More...

`#include <command_buffer.h>`

Inheritance diagram for impeller::CommandBuffer:

## Public Types
enum | Status { Status::kPending, Status::kError, Status::kCompleted }
using | CompletionCallback = std::function< void(Status)>

## Public Member Functions
virtual | ~CommandBuffer ()
virtual bool | IsValid () const =0
virtual void | SetLabel (const std::string &label) const =0
bool | SubmitCommands (const CompletionCallback &callback)
| Schedule the command encoded by render passes within this command buffer on the GPU. The encoding of these commnands is performed immediately on the calling thread. More...
bool | SubmitCommands ()
virtual bool | EncodeAndSubmit (const std::shared_ptr< RenderPass > &render_pass)
| Schedule the command encoded by render passes within this command buffer on the GPU. The enqueing of this buffer is performed immediately but encoding is pushed to a worker thread if possible. More...
virtual bool | EncodeAndSubmit (const std::shared_ptr< BlitPass > &blit_pass, const std::shared_ptr< Allocator > &allocator)
| Schedule the command encoded by blit passes within this command buffer on the GPU. The enqueing of this buffer is performed immediately but encoding is pushed to a worker thread if possible. More...
void | WaitUntilScheduled ()
| Force execution of pending GPU commands. More...
std::shared_ptr< RenderPass > | CreateRenderPass (const RenderTarget &render_target)
| Create a render pass to record render commands into. More...
std::shared_ptr< BlitPass > | CreateBlitPass ()
| Create a blit pass to record blit commands into. More...
std::shared_ptr< ComputePass > | CreateComputePass ()
| Create a compute pass to record compute commands into. More...

## Protected Member Functions
| CommandBuffer (std::weak_ptr< const Context > context)
virtual std::shared_ptr< RenderPass > | OnCreateRenderPass (RenderTarget render_target)=0
virtual std::shared_ptr< BlitPass > | OnCreateBlitPass ()=0
virtual bool | OnSubmitCommands (CompletionCallback callback)=0
virtual void | OnWaitUntilScheduled ()=0
virtual std::shared_ptr< ComputePass > | OnCreateComputePass ()=0

## Protected Attributes
std::weak_ptr< const Context > | context_

## Friends
class | testing::CommandBufferMock

## Detailed Description

A collection of encoded commands to be submitted to the GPU for execution. A command buffer is obtained from a graphics `Context`.

To submit commands to the GPU, acquire a `RenderPass` from the command buffer and record `Command`s into that pass. A `RenderPass` describes the configuration of the various attachments when the command is submitted.

A command buffer is only meant to be used on a single thread. If a frame workload needs to be encoded from multiple threads, set up and record into multiple command buffers. The order of submission of commands encoded in multiple command buffers can be controlled via either the order in which the command buffers were created, or, using the `ReserveSpotInQueue` command which allows for encoding commands for submission in an order that is different from the encoding order.

Definition at line 45 of file command_buffer.h.

## Member Typedef Documentation

## ◆ CompletionCallback

using impeller::CommandBuffer::CompletionCallback = std::function<void(Status)>

Definition at line 55 of file command_buffer.h.

## Member Enumeration Documentation

## ◆ Status

enum impeller::CommandBuffer::Status
| strong

Enumerator
kPending |
kError |
kCompleted |

Definition at line 49 of file command_buffer.h.

49 {
50 kPending,
51 kError,
52 kCompleted,
53 };

## Constructor & Destructor Documentation

## ◆ ~CommandBuffer()

impeller::CommandBuffer::~CommandBuffer | ( |  | ) |
| virtual default

## ◆ CommandBuffer()

impeller::CommandBuffer::CommandBuffer | ( | std::weak_ptr< const Context > | context | ) |
| explicit protected

Definition at line 14 of file command_buffer.cc.

15 : context_(std::move(context)) {}

## Member Function Documentation

## ◆ CreateBlitPass()

std::shared_ptr< BlitPass > impeller::CommandBuffer::CreateBlitPass | ( |  | ) |

Create a blit pass to record blit commands into.

Returns
  A valid blit pass or null.

Definition at line 76 of file command_buffer.cc.

76 {
77 auto pass = OnCreateBlitPass();
78 if (pass && pass->IsValid()) {
79 pass->SetLabel("BlitPass");
80 return pass;
81 }
82 return nullptr;
83 }

References OnCreateBlitPass().

## ◆ CreateComputePass()

std::shared_ptr< ComputePass > impeller::CommandBuffer::CreateComputePass | ( |  | ) |

Create a compute pass to record compute commands into.

Returns
  A valid compute pass or null.

Definition at line 85 of file command_buffer.cc.

85 {
86 if (!IsValid()) {
87 return nullptr;
88 }
89 auto pass = OnCreateComputePass();
90 if (pass && pass->IsValid()) {
91 pass->SetLabel("ComputePass");
92 return pass;
93 }
94 return nullptr;
95 }

References IsValid(), and OnCreateComputePass().

## ◆ CreateRenderPass()

std::shared_ptr< RenderPass > impeller::CommandBuffer::CreateRenderPass | ( | const RenderTarget & | render_target | ) |

Create a render pass to record render commands into.

Parameters

  [in] | render_target | The description of the render target this pass will target.

Returns
  A valid render pass or null.

Definition at line 66 of file command_buffer.cc.

67 {
68 auto pass = OnCreateRenderPass(render_target);
69 if (pass && pass->IsValid()) {
70 pass->SetLabel("RenderPass");
71 return pass;
72 }
73 return nullptr;
74 }

References OnCreateRenderPass().

## ◆ EncodeAndSubmit() [1/2]

bool impeller::CommandBuffer::EncodeAndSubmit | ( | const std::shared_ptr< BlitPass > & | blit_pass,
|  | const std::shared_ptr< Allocator > & | allocator
| ) |  |
| virtual

Schedule the command encoded by blit passes within this command buffer on the GPU. The enqueing of this buffer is performed immediately but encoding is pushed to a worker thread if possible.

A command buffer may only be committed once.

Definition at line 52 of file command_buffer.cc.

54 {
55 TRACE_EVENT0("impeller", "CommandBuffer::EncodeAndSubmit");
56 if (!blit_pass->IsValid() || !IsValid()) {
57 return false;
58 }
59 if (!blit_pass->EncodeCommands(allocator)) {
60 return false;
61 }
62
63 return SubmitCommands(nullptr);
64 }

References IsValid(), and SubmitCommands().

## ◆ EncodeAndSubmit() [2/2]

bool impeller::CommandBuffer::EncodeAndSubmit | ( | const std::shared_ptr< RenderPass > & | render_pass | ) |
| virtual

Schedule the command encoded by render passes within this command buffer on the GPU. The enqueing of this buffer is performed immediately but encoding is pushed to a worker thread if possible.

A command buffer may only be committed once.

Definition at line 39 of file command_buffer.cc.

40 {
41 TRACE_EVENT0("impeller", "CommandBuffer::EncodeAndSubmit");
42 if (!render_pass->IsValid() || !IsValid()) {
43 return false;
44 }
45 if (!render_pass->EncodeCommands()) {
46 return false;
47 }
48
49 return SubmitCommands(nullptr);
50 }

References IsValid(), and SubmitCommands().

## ◆ IsValid()

virtual bool impeller::CommandBuffer::IsValid | ( |  | ) | const
| pure virtual

Referenced by CreateComputePass(), EncodeAndSubmit(), and SubmitCommands().

## ◆ OnCreateBlitPass()

virtual std::shared_ptr<BlitPass> impeller::CommandBuffer::OnCreateBlitPass | ( |  | ) |
| protected pure virtual

Referenced by CreateBlitPass().

## ◆ OnCreateComputePass()

virtual std::shared_ptr<ComputePass> impeller::CommandBuffer::OnCreateComputePass | ( |  | ) |
| protected pure virtual

Referenced by CreateComputePass().

## ◆ OnCreateRenderPass()

virtual std::shared_ptr<RenderPass> impeller::CommandBuffer::OnCreateRenderPass | ( | RenderTarget | render_target | ) |
| protected pure virtual

Referenced by CreateRenderPass().

## ◆ OnSubmitCommands()

virtual bool impeller::CommandBuffer::OnSubmitCommands | ( | CompletionCallback | callback | ) |
| protected pure virtual

Referenced by SubmitCommands().

## ◆ OnWaitUntilScheduled()

virtual void impeller::CommandBuffer::OnWaitUntilScheduled | ( |  | ) |
| protected pure virtual

Referenced by WaitUntilScheduled().

## ◆ SetLabel()

virtual void impeller::CommandBuffer::SetLabel | ( | const std::string & | label | ) | const
| pure virtual

## ◆ SubmitCommands() [1/2]

bool impeller::CommandBuffer::SubmitCommands | ( |  | ) |

Definition at line 31 of file command_buffer.cc.

31 {
32 return SubmitCommands(nullptr);
33 }

Referenced by EncodeAndSubmit().

## ◆ SubmitCommands() [2/2]

bool impeller::CommandBuffer::SubmitCommands | ( | const CompletionCallback & | callback | ) |

Schedule the command encoded by render passes within this command buffer on the GPU. The encoding of these commnands is performed immediately on the calling thread.

A command buffer may only be committed once.

Parameters

  [in] | callback | The completion callback.

Definition at line 19 of file command_buffer.cc.

19 {
20 TRACE_EVENT0("impeller", "CommandBuffer::SubmitCommands");
21 if (!IsValid()) {
22 // Already committed or was never valid. Either way, this is caller error.
23 if (callback) {
24 callback(Status::kError);
25 }
26 return false;
27 }
28 return OnSubmitCommands(callback);
29 }

References IsValid(), kError, and OnSubmitCommands().

## ◆ WaitUntilScheduled()

void impeller::CommandBuffer::WaitUntilScheduled | ( |  | ) |

Force execution of pending GPU commands.

Definition at line 35 of file command_buffer.cc.

35 {
36 return OnWaitUntilScheduled();
37 }

References OnWaitUntilScheduled().

## Friends And Related Function Documentation

## ◆ testing::CommandBufferMock

friend class testing::CommandBufferMock
| friend

Definition at line 46 of file command_buffer.h.

## Member Data Documentation

## ◆ context_

std::weak_ptr<const Context> impeller::CommandBuffer::context_
| protected

Definition at line 130 of file command_buffer.h.

The documentation for this class was generated from the following files:

- impeller/renderer/command_buffer.h
- impeller/renderer/command_buffer.cc

impeller::CommandBuffer::Status::kError
@ kError
impeller::CommandBuffer::SubmitCommands
bool SubmitCommands()
Definition: command_buffer.cc:31
impeller::CommandBuffer::OnSubmitCommands
virtual bool OnSubmitCommands(CompletionCallback callback)=0
impeller::CommandBuffer::OnCreateRenderPass
virtual std::shared_ptr< RenderPass > OnCreateRenderPass(RenderTarget render_target)=0
impeller::CommandBuffer::OnCreateComputePass
virtual std::shared_ptr< ComputePass > OnCreateComputePass()=0
impeller::CommandBuffer::context_
std::weak_ptr< const Context > context_
Definition: command_buffer.h:130
impeller::CommandBuffer::IsValid
virtual bool IsValid() const =0
impeller::CommandBuffer::OnCreateBlitPass
virtual std::shared_ptr< BlitPass > OnCreateBlitPass()=0
impeller::CommandBuffer::OnWaitUntilScheduled
virtual void OnWaitUntilScheduled()=0