| 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 #pragma once
6
7 #include <functional>
8 #include <memory>
9
10 #include "flutter/fml/macros.h"
11 #include "impeller/renderer/blit_pass.h"
12 #include "impeller/renderer/compute_pass.h"
13
14 namespace impeller {
15
16 class ComputePass;
17 class Context;
18 class RenderPass;
19 class RenderTarget;
20
21 namespace testing {
22 class CommandBufferMock;
23 }
24
25 //------------------------------------------------------------------------------
26 /// @brief A collection of encoded commands to be submitted to the GPU for
27 /// execution. A command buffer is obtained from a graphics
28 /// `Context`.
29 ///
30 /// To submit commands to the GPU, acquire a `RenderPass` from the
31 /// command buffer and record `Command`s into that pass. A
32 /// `RenderPass` describes the configuration of the various
33 /// attachments when the command is submitted.
34 ///
35 /// A command buffer is only meant to be used on a single thread. If
36 /// a frame workload needs to be encoded from multiple threads,
37 /// set up and record into multiple command buffers. The order of
38 /// submission of commands encoded in multiple command buffers can
39 /// be controlled via either the order in which the command buffers
40 /// were created, or, using the `ReserveSpotInQueue` command which
41 /// allows for encoding commands for submission in an order that is
42 /// different from the encoding order.
43 ///
44 class CommandBuffer {
45 friend class testing::CommandBufferMock;
46
47 public:
48 enum class Status {
49 kPending,
50 kError,
51 kCompleted,
52 };
53
54 using CompletionCallback = std::function<void(Status)>;
55
56 virtual ~CommandBuffer();
57
58 virtual bool IsValid() const = 0;
59
60 virtual void SetLabel(const std::string& label) const = 0;
61
62 //----------------------------------------------------------------------------
63 /// @brief Schedule the command encoded by render passes within this
64 /// command buffer on the GPU. The encoding of these commnands is
65 /// performed immediately on the calling thread.
66 ///
67 /// A command buffer may only be committed once.
68 ///
69 /// @param[in] callback The completion callback.
70 ///
71 [[nodiscard]] bool SubmitCommands(const CompletionCallback& callback);
72
73 [[nodiscard]] bool SubmitCommands();
74
75 //----------------------------------------------------------------------------
76 /// @brief Schedule the command encoded by render passes within this
77 /// command buffer on the GPU. The enqueing of this buffer is
78 /// performed immediately but encoding is pushed to a worker
79 /// thread if possible.
80 ///
81 /// A command buffer may only be committed once.
82 ///
83 [[nodiscard]] virtual bool SubmitCommandsAsync(
84 std::shared_ptr<RenderPass> render_pass);
85
86 //----------------------------------------------------------------------------
87 /// @brief Force execution of pending GPU commands.
88 ///
89 void WaitUntilScheduled();
90
91 //----------------------------------------------------------------------------
92 /// @brief Create a render pass to record render commands into.
93 ///
94 /// @param[in] render_target The description of the render target this pass
95 /// will target.
96 ///
97 /// @return A valid render pass or null.
98 ///
99 std::shared_ptr<RenderPass> CreateRenderPass(
100 const RenderTarget& render_target);
101
102 //----------------------------------------------------------------------------
103 /// @brief Create a blit pass to record blit commands into.
104 ///
105 /// @return A valid blit pass or null.
106 ///
107 std::shared_ptr<BlitPass> CreateBlitPass();
108
109 //----------------------------------------------------------------------------
110 /// @brief Create a compute pass to record compute commands into.
111 ///
112 /// @return A valid compute pass or null.
113 ///
114 std::shared_ptr<ComputePass> CreateComputePass();
115
116 protected:
117 std::weak_ptr<const Context> context_;
118
119 explicit CommandBuffer(std::weak_ptr<const Context> context);
120
121 virtual std::shared_ptr<RenderPass> OnCreateRenderPass(
122 RenderTarget render_target) = 0;
123
124 virtual std::shared_ptr<BlitPass> OnCreateBlitPass() = 0;
125
126 [[nodiscard]] virtual bool OnSubmitCommands(CompletionCallback callback) = 0;
127
128 virtual void OnWaitUntilScheduled() = 0;
129
130 virtual std::shared_ptr<ComputePass> OnCreateComputePass() = 0;
131
132 private:
133 FML_DISALLOW_COPY_AND_ASSIGN(CommandBuffer);
134 };
135
136 } // namespace impeller
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::CreateRenderPass
std::shared_ptr< RenderPass > CreateRenderPass(const RenderTarget &render_target)
Create a render pass to record render commands into.
Definition: command_buffer.cc:54
impeller::CommandBuffer::OnCreateRenderPass
virtual std::shared_ptr< RenderPass > OnCreateRenderPass(RenderTarget render_target)=0
impeller::CommandBuffer::SubmitCommandsAsync
virtual bool SubmitCommandsAsync(std::shared_ptr< RenderPass > render_pass)
Schedule the command encoded by render passes within this command buffer on the GPU....
Definition: command_buffer.cc:39
impeller::CommandBuffer::OnCreateComputePass
virtual std::shared_ptr< ComputePass > OnCreateComputePass()=0
impeller::CommandBuffer::CompletionCallback
std::function< void(Status)> CompletionCallback
Definition: command_buffer.h:54
impeller::CommandBuffer::CreateComputePass
std::shared_ptr< ComputePass > CreateComputePass()
Create a compute pass to record compute commands into.
Definition: command_buffer.cc:73
impeller::CommandBuffer::WaitUntilScheduled
void WaitUntilScheduled()
Force execution of pending GPU commands.
Definition: command_buffer.cc:35
impeller::CommandBuffer::context_
std::weak_ptr< const Context > context_
Definition: command_buffer.h:117
impeller::CommandBuffer::Status::kPending
@ kPending
impeller::CommandBuffer::IsValid
virtual bool IsValid() const =0
blit_pass.h
impeller::RenderTarget
Definition: render_target.h:48
impeller::CommandBuffer::SetLabel
virtual void SetLabel(const std::string &label) const =0
impeller::CommandBuffer::OnCreateBlitPass
virtual std::shared_ptr< BlitPass > OnCreateBlitPass()=0
impeller::CommandBuffer::OnWaitUntilScheduled
virtual void OnWaitUntilScheduled()=0
impeller::CommandBuffer::CreateBlitPass
std::shared_ptr< BlitPass > CreateBlitPass()
Create a blit pass to record blit commands into.
Definition: command_buffer.cc:64
impeller::CommandBuffer::Status::kCompleted
@ kCompleted
impeller::CommandBuffer::CommandBufferMock
friend class testing::CommandBufferMock
Definition: command_buffer.h:45
impeller::CommandBuffer::Status
Status
Definition: command_buffer.h:48
impeller::CommandBuffer::CommandBuffer
CommandBuffer(std::weak_ptr< const Context > context)
Definition: command_buffer.cc:14
compute_pass.h
impeller
Definition: aiks_context.cc:10
impeller::CommandBuffer
A collection of encoded commands to be submitted to the GPU for execution. A command buffer is obtain...
Definition: command_buffer.h:44
impeller::CommandBuffer::~CommandBuffer
virtual ~CommandBuffer()