Flutter Impeller
command_buffer.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef FLUTTER_IMPELLER_RENDERER_COMMAND_BUFFER_H_
6 #define FLUTTER_IMPELLER_RENDERER_COMMAND_BUFFER_H_
7 
8 #include <functional>
9 #include <memory>
10 
13 
14 namespace impeller {
15 
16 class ComputePass;
17 class Context;
18 class RenderPass;
19 class RenderTarget;
20 class CommandQueue;
21 
22 namespace testing {
23 class CommandBufferMock;
24 }
25 
26 //------------------------------------------------------------------------------
27 /// @brief A collection of encoded commands to be submitted to the GPU for
28 /// execution. A command buffer is obtained from a graphics
29 /// `Context`.
30 ///
31 /// To submit commands to the GPU, acquire a `RenderPass` from the
32 /// command buffer and record `Command`s into that pass. A
33 /// `RenderPass` describes the configuration of the various
34 /// attachments when the command is submitted.
35 ///
36 /// A command buffer is only meant to be used on a single thread. If
37 /// a frame workload needs to be encoded from multiple threads,
38 /// set up and record into multiple command buffers. The order of
39 /// submission of commands encoded in multiple command buffers can
40 /// be controlled via either the order in which the command buffers
41 /// were created, or, using the `ReserveSpotInQueue` command which
42 /// allows for encoding commands for submission in an order that is
43 /// different from the encoding order.
44 ///
47 
48  public:
49  enum class Status {
50  kPending,
51  kError,
52  kCompleted,
53  };
54 
55  using CompletionCallback = std::function<void(Status)>;
56 
57  virtual ~CommandBuffer();
58 
59  virtual bool IsValid() const = 0;
60 
61  virtual void SetLabel(std::string_view label) const = 0;
62 
63  //----------------------------------------------------------------------------
64  /// @brief Block the current thread until the GPU has completed execution
65  /// of the commands.
66  ///
67  void WaitUntilCompleted();
68 
69  //----------------------------------------------------------------------------
70  /// @brief Block the current thread until the GPU has completed
71  /// scheduling execution of the commands.
72  ///
73  void WaitUntilScheduled();
74 
75  //----------------------------------------------------------------------------
76  /// @brief Create a render pass to record render commands into.
77  ///
78  /// @param[in] render_target The description of the render target this pass
79  /// will target.
80  ///
81  /// @return A valid render pass or null.
82  ///
83  std::shared_ptr<RenderPass> CreateRenderPass(
84  const RenderTarget& render_target);
85 
86  //----------------------------------------------------------------------------
87  /// @brief Create a blit pass to record blit commands into.
88  ///
89  /// @return A valid blit pass or null.
90  ///
91  std::shared_ptr<BlitPass> CreateBlitPass();
92 
93  //----------------------------------------------------------------------------
94  /// @brief Create a compute pass to record compute commands into.
95  ///
96  /// @return A valid compute pass or null.
97  ///
98  std::shared_ptr<ComputePass> CreateComputePass();
99 
100  protected:
101  std::weak_ptr<const Context> context_;
102 
103  explicit CommandBuffer(std::weak_ptr<const Context> context);
104 
105  virtual std::shared_ptr<RenderPass> OnCreateRenderPass(
106  RenderTarget render_target) = 0;
107 
108  virtual std::shared_ptr<BlitPass> OnCreateBlitPass() = 0;
109 
110  /// @brief Submit the command buffer to the GPU for execution.
111  ///
112  /// See also: [SubmitCommands].
113  [[nodiscard]] virtual bool OnSubmitCommands(bool block_on_schedule,
114  CompletionCallback callback) = 0;
115 
116  virtual void OnWaitUntilCompleted() = 0;
117 
118  virtual void OnWaitUntilScheduled() = 0;
119 
120  virtual std::shared_ptr<ComputePass> OnCreateComputePass() = 0;
121 
122  private:
123  friend class CommandQueue;
124 
125  //----------------------------------------------------------------------------
126  /// @brief Schedule the command encoded by render passes within this
127  /// command buffer on the GPU. The encoding of these commnands is
128  /// performed immediately on the calling thread.
129  ///
130  /// A command buffer may only be committed once.
131  /// @param[in] block_on_schedule If true, this function will not return
132  /// until the command buffer has been scheduled. This only impacts
133  /// the Metal backend.
134  /// @param[in] callback The completion callback.
135  ///
136  [[nodiscard]] bool SubmitCommands(bool block_on_schedule,
137  const CompletionCallback& callback);
138 
139  [[nodiscard]] bool SubmitCommands(bool block_on_schedule);
140 
141  CommandBuffer(const CommandBuffer&) = delete;
142 
143  CommandBuffer& operator=(const CommandBuffer&) = delete;
144 };
145 
146 } // namespace impeller
147 
148 #endif // FLUTTER_IMPELLER_RENDERER_COMMAND_BUFFER_H_
A collection of encoded commands to be submitted to the GPU for execution. A command buffer is obtain...
std::shared_ptr< BlitPass > CreateBlitPass()
Create a blit pass to record blit commands into.
virtual void OnWaitUntilCompleted()=0
std::shared_ptr< ComputePass > CreateComputePass()
Create a compute pass to record compute commands into.
CommandBuffer(std::weak_ptr< const Context > context)
virtual bool OnSubmitCommands(bool block_on_schedule, CompletionCallback callback)=0
Submit the command buffer to the GPU for execution.
virtual bool IsValid() const =0
virtual std::shared_ptr< ComputePass > OnCreateComputePass()=0
std::function< void(Status)> CompletionCallback
virtual std::shared_ptr< RenderPass > OnCreateRenderPass(RenderTarget render_target)=0
void WaitUntilCompleted()
Block the current thread until the GPU has completed execution of the commands.
virtual void SetLabel(std::string_view label) const =0
std::shared_ptr< RenderPass > CreateRenderPass(const RenderTarget &render_target)
Create a render pass to record render commands into.
virtual void OnWaitUntilScheduled()=0
virtual std::shared_ptr< BlitPass > OnCreateBlitPass()=0
std::weak_ptr< const Context > context_
friend class testing::CommandBufferMock
void WaitUntilScheduled()
Block the current thread until the GPU has completed scheduling execution of the commands.
An interface for submitting command buffers to the GPU for encoding and execution.
Definition: command_queue.h:17