Skip to content

Commit 1cc08bf

Browse files
authored
[Flutter GPU] End each pass when the next command is recorded (flutter#194167)
Fixes flutter#193867. Part of flutter#188474. A command buffer now records one pass at a time, so it can hold any number of passes on every backend. Before, every pass stayed open until submit, which on Metal limited a command buffer to one render pass. - Creating the next pass, recording a copy, or submitting ends the open pass, and `RenderPass.end()` ends it explicitly. On Metal and Vulkan the pass is encoded at that point. - Using an ended pass, or recording into a submitted command buffer, throws a `StateError` that says why. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [ ] All existing and new tests are passing. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
1 parent 084e608 commit 1cc08bf

8 files changed

Lines changed: 639 additions & 14 deletions

File tree

‎engine/src/flutter/lib/gpu/command_buffer.cc‎

Lines changed: 50 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -39,24 +39,62 @@ std::shared_ptr<impeller::CommandBuffer> CommandBuffer::GetCommandBuffer() {
3939
return command_buffer_;
4040
}
4141

42-
void CommandBuffer::AddRenderPass(
43-
std::shared_ptr<impeller::RenderPass> render_pass) {
42+
std::shared_ptr<impeller::RenderPass> CommandBuffer::CreateRenderPass(
43+
const impeller::RenderTarget& render_target) {
44+
if (!EndOpenPass()) {
45+
return nullptr;
46+
}
47+
auto render_pass = command_buffer_->CreateRenderPass(render_target);
48+
if (!render_pass) {
49+
return nullptr;
50+
}
4451
Encodable encodable;
45-
encodable.render_pass = std::move(render_pass);
52+
encodable.render_pass = render_pass;
4653
encodables_.push_back(std::move(encodable));
54+
has_open_pass_ = true;
55+
return render_pass;
56+
}
57+
58+
bool CommandBuffer::EndRenderPass(const impeller::RenderPass* render_pass) {
59+
if (!render_pass || !has_open_pass_ ||
60+
encodables_.back().render_pass.get() != render_pass) {
61+
return true;
62+
}
63+
return EndOpenPass();
64+
}
65+
66+
bool CommandBuffer::EndOpenPass() {
67+
if (!has_open_pass_) {
68+
return true;
69+
}
70+
has_open_pass_ = false;
71+
// GLES passes are encoded at submit, on the raster thread.
72+
if (context_->GetBackendType() == impeller::Context::BackendType::kOpenGLES) {
73+
return true;
74+
}
75+
if (!encodables_.back().EncodeCommands()) {
76+
encoding_failed_ = true;
77+
return false;
78+
}
79+
return true;
4780
}
4881

4982
std::shared_ptr<impeller::BlitPass> CommandBuffer::GetOrCreateBlitPass() {
50-
if (!encodables_.empty() && encodables_.back().blit_pass) {
83+
// Consecutive copies share one blit pass.
84+
if (has_open_pass_ && encodables_.back().blit_pass) {
5185
return encodables_.back().blit_pass;
5286
}
87+
if (!EndOpenPass()) {
88+
return nullptr;
89+
}
5390
auto blit_pass = command_buffer_->CreateBlitPass();
5491
if (!blit_pass) {
5592
return nullptr;
5693
}
5794
Encodable encodable;
5895
encodable.blit_pass = blit_pass;
5996
encodables_.push_back(std::move(encodable));
97+
has_open_pass_ = true;
6098
return blit_pass;
6199
}
62100

@@ -126,6 +164,10 @@ bool CommandBuffer::Submit(
126164
}
127165
submitted_ = true;
128166

167+
// On Metal and Vulkan this encodes the last pass. Every earlier pass was
168+
// encoded when it ended.
169+
EndOpenPass();
170+
129171
std::vector<impeller::CommandBuffer::CompletionCallback> callbacks =
130172
std::move(completion_callbacks_);
131173
if (completion_callback) {
@@ -172,10 +214,11 @@ bool CommandBuffer::Submit(
172214
return true;
173215
}
174216

175-
for (auto& encodable : encodables_) {
176-
if (!encodable.EncodeCommands()) {
177-
return false;
217+
if (encoding_failed_) {
218+
if (combined_completion_callback) {
219+
combined_completion_callback(impeller::CommandBuffer::Status::kError);
178220
}
221+
return false;
179222
}
180223

181224
auto status = context_->GetCommandQueue()->Submit(

‎engine/src/flutter/lib/gpu/command_buffer.h‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,18 @@ class CommandBuffer : public RefCountedDartWrappable<CommandBuffer> {
3333

3434
std::shared_ptr<impeller::CommandBuffer> GetCommandBuffer();
3535

36-
void AddRenderPass(std::shared_ptr<impeller::RenderPass> render_pass);
36+
/// Ends the open pass, then creates a render pass for [render_target] and
37+
/// makes it the open pass. Returns null if either step fails.
38+
///
39+
/// The open pass is ended before the new backend pass is created, because
40+
/// the Metal and Vulkan render pass constructors begin encoding, and Metal
41+
/// allows one active encoder per command buffer.
42+
std::shared_ptr<impeller::RenderPass> CreateRenderPass(
43+
const impeller::RenderTarget& render_target);
44+
45+
/// Ends [render_pass] if it is the open pass. Does nothing if it was
46+
/// already ended by a later command.
47+
bool EndRenderPass(const impeller::RenderPass* render_pass);
3748

3849
bool AddCompletionCallback(
3950
impeller::CommandBuffer::CompletionCallback completion_callback);
@@ -73,9 +84,19 @@ class CommandBuffer : public RefCountedDartWrappable<CommandBuffer> {
7384
bool EncodeCommands() const;
7485
};
7586

87+
/// Ends the pass that is recording, if any. On Metal and Vulkan the pass is
88+
/// encoded now, which ends its backend encoder. On OpenGL ES every pass is
89+
/// encoded in creation order at submit, on the raster thread.
90+
bool EndOpenPass();
91+
7692
std::shared_ptr<impeller::BlitPass> GetOrCreateBlitPass();
7793

94+
// Every pass in creation order, which is also execution order. Only the
95+
// last one can be open.
7896
std::vector<Encodable> encodables_;
97+
bool has_open_pass_ = false;
98+
// Set when a pass fails to encode as it ends, so that Submit fails.
99+
bool encoding_failed_ = false;
79100
std::vector<impeller::CommandBuffer::CompletionCallback>
80101
completion_callbacks_;
81102
bool submitted_ = false;

‎engine/src/flutter/lib/gpu/command_buffer_unittests.cc‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77
#include <memory>
88
#include <vector>
99

10+
#include "flutter/lib/gpu/render_pass.h"
11+
#include "flutter/lib/gpu/texture.h"
12+
#include "fml/memory/ref_ptr.h"
1013
#include "fml/status.h"
1114
#include "gmock/gmock.h"
1215
#include "gtest/gtest.h"
@@ -15,11 +18,16 @@
1518
namespace flutter::gpu {
1619
namespace {
1720

21+
using ::impeller::testing::MockBlitPass;
1822
using ::impeller::testing::MockCommandBuffer;
1923
using ::impeller::testing::MockCommandQueue;
2024
using ::impeller::testing::MockImpellerContext;
25+
using ::impeller::testing::MockRenderPass;
26+
using ::impeller::testing::MockTexture;
2127
using ::testing::_;
2228
using ::testing::DoAll;
29+
using ::testing::InSequence;
30+
using ::testing::NiceMock;
2331
using ::testing::Return;
2432

2533
TEST(FlutterGpuCommandBufferTest,
@@ -106,5 +114,182 @@ TEST(FlutterGpuCommandBufferTest,
106114
EXPECT_EQ(statuses[0], impeller::CommandBuffer::Status::kError);
107115
}
108116

117+
// The pass lifecycle tests heap-allocate the command buffer, since it is
118+
// ref-counted and asserts in debug builds when destroyed without a reference.
119+
class FlutterGpuPassLifecycleTest : public ::testing::Test {
120+
protected:
121+
void SetUp() override {
122+
context_ = std::make_shared<NiceMock<MockImpellerContext>>();
123+
impeller_command_buffer_ =
124+
std::make_shared<NiceMock<MockCommandBuffer>>(context_);
125+
command_queue_ = std::make_shared<NiceMock<MockCommandQueue>>();
126+
ON_CALL(*context_, GetBackendType)
127+
.WillByDefault(Return(impeller::Context::BackendType::kMetal));
128+
ON_CALL(*context_, GetCommandQueue).WillByDefault(Return(command_queue_));
129+
command_buffer_ =
130+
fml::MakeRefCounted<CommandBuffer>(context_, impeller_command_buffer_);
131+
132+
impeller::TextureDescriptor texture_desc;
133+
texture_desc.format = impeller::PixelFormat::kR8G8B8A8UNormInt;
134+
texture_desc.size = impeller::ISize(4, 4);
135+
auto texture = std::make_shared<NiceMock<MockTexture>>(texture_desc);
136+
ON_CALL(*texture, GetSize).WillByDefault(Return(impeller::ISize(4, 4)));
137+
texture_ = fml::MakeRefCounted<Texture>(texture);
138+
}
139+
140+
std::shared_ptr<MockRenderPass> MakeRenderPass() {
141+
auto pass = std::make_shared<NiceMock<MockRenderPass>>(
142+
context_, impeller::RenderTarget());
143+
ON_CALL(*pass, IsValid).WillByDefault(Return(true));
144+
return pass;
145+
}
146+
147+
std::shared_ptr<MockBlitPass> MakeBlitPass() {
148+
auto pass = std::make_shared<NiceMock<MockBlitPass>>();
149+
ON_CALL(*pass, IsValid).WillByDefault(Return(true));
150+
ON_CALL(*pass, OnCopyTextureToTextureCommand).WillByDefault(Return(true));
151+
return pass;
152+
}
153+
154+
bool Copy() {
155+
return command_buffer_->CopyTextureToTexture(
156+
*texture_, *texture_, impeller::IRect::MakeXYWH(0, 0, 1, 1),
157+
impeller::IPoint(1, 1));
158+
}
159+
160+
std::shared_ptr<NiceMock<MockImpellerContext>> context_;
161+
std::shared_ptr<NiceMock<MockCommandBuffer>> impeller_command_buffer_;
162+
std::shared_ptr<NiceMock<MockCommandQueue>> command_queue_;
163+
fml::RefPtr<CommandBuffer> command_buffer_;
164+
fml::RefPtr<Texture> texture_;
165+
};
166+
167+
TEST_F(FlutterGpuPassLifecycleTest,
168+
EachCommandEndsTheOpenPassBeforeTheNextPassIsCreated) {
169+
auto blit_a = MakeBlitPass();
170+
auto render_a = MakeRenderPass();
171+
auto render_b = MakeRenderPass();
172+
auto blit_b = MakeBlitPass();
173+
{
174+
InSequence sequence;
175+
EXPECT_CALL(*impeller_command_buffer_, OnCreateBlitPass)
176+
.WillOnce(Return(blit_a));
177+
EXPECT_CALL(*blit_a, OnCopyTextureToTextureCommand);
178+
// A render pass ends the copies before it.
179+
EXPECT_CALL(*blit_a, EncodeCommands).WillOnce(Return(true));
180+
EXPECT_CALL(*impeller_command_buffer_, OnCreateRenderPass)
181+
.WillOnce(Return(render_a));
182+
// A render pass ends the render pass before it.
183+
EXPECT_CALL(*render_a, OnEncodeCommands).WillOnce(Return(true));
184+
EXPECT_CALL(*impeller_command_buffer_, OnCreateRenderPass)
185+
.WillOnce(Return(render_b));
186+
// A copy ends the render pass before it, and consecutive copies share
187+
// one blit pass.
188+
EXPECT_CALL(*render_b, OnEncodeCommands).WillOnce(Return(true));
189+
EXPECT_CALL(*impeller_command_buffer_, OnCreateBlitPass)
190+
.WillOnce(Return(blit_b));
191+
EXPECT_CALL(*blit_b, OnCopyTextureToTextureCommand).Times(2);
192+
// Submit ends the last pass only.
193+
EXPECT_CALL(*blit_b, EncodeCommands).WillOnce(Return(true));
194+
EXPECT_CALL(*command_queue_, Submit).WillOnce(Return(fml::Status()));
195+
}
196+
197+
EXPECT_TRUE(Copy());
198+
EXPECT_EQ(command_buffer_->CreateRenderPass(impeller::RenderTarget()),
199+
render_a);
200+
EXPECT_EQ(command_buffer_->CreateRenderPass(impeller::RenderTarget()),
201+
render_b);
202+
EXPECT_TRUE(Copy());
203+
EXPECT_TRUE(Copy());
204+
EXPECT_TRUE(command_buffer_->Submit());
205+
}
206+
207+
TEST_F(FlutterGpuPassLifecycleTest, EndEncodesThePassOnce) {
208+
auto render_a = MakeRenderPass();
209+
{
210+
InSequence sequence;
211+
EXPECT_CALL(*impeller_command_buffer_, OnCreateRenderPass)
212+
.WillOnce(Return(render_a));
213+
EXPECT_CALL(*render_a, OnEncodeCommands).WillOnce(Return(true));
214+
EXPECT_CALL(*command_queue_, Submit).WillOnce(Return(fml::Status()));
215+
}
216+
217+
auto pass = fml::MakeRefCounted<RenderPass>();
218+
ASSERT_TRUE(pass->Begin(*command_buffer_));
219+
EXPECT_TRUE(pass->End());
220+
EXPECT_TRUE(pass->End());
221+
EXPECT_TRUE(command_buffer_->Submit());
222+
}
223+
224+
TEST_F(FlutterGpuPassLifecycleTest,
225+
EndingAPassEndedByALaterCommandDoesNothing) {
226+
auto render_a = MakeRenderPass();
227+
auto render_b = MakeRenderPass();
228+
{
229+
InSequence sequence;
230+
EXPECT_CALL(*impeller_command_buffer_, OnCreateRenderPass)
231+
.WillOnce(Return(render_a));
232+
EXPECT_CALL(*render_a, OnEncodeCommands).WillOnce(Return(true));
233+
EXPECT_CALL(*impeller_command_buffer_, OnCreateRenderPass)
234+
.WillOnce(Return(render_b));
235+
EXPECT_CALL(*render_b, OnEncodeCommands).WillOnce(Return(true));
236+
EXPECT_CALL(*command_queue_, Submit).WillOnce(Return(fml::Status()));
237+
}
238+
239+
auto pass_a = fml::MakeRefCounted<RenderPass>();
240+
auto pass_b = fml::MakeRefCounted<RenderPass>();
241+
ASSERT_TRUE(pass_a->Begin(*command_buffer_));
242+
ASSERT_TRUE(pass_b->Begin(*command_buffer_));
243+
// pass_b is still open, so this must not end it.
244+
EXPECT_TRUE(pass_a->End());
245+
EXPECT_TRUE(command_buffer_->Submit());
246+
}
247+
248+
TEST_F(FlutterGpuPassLifecycleTest, OpenGLESDefersEncodingToSubmit) {
249+
ON_CALL(*context_, GetBackendType)
250+
.WillByDefault(Return(impeller::Context::BackendType::kOpenGLES));
251+
auto render_a = MakeRenderPass();
252+
auto blit_a = MakeBlitPass();
253+
auto render_b = MakeRenderPass();
254+
EXPECT_CALL(*impeller_command_buffer_, OnCreateRenderPass)
255+
.WillOnce(Return(render_a))
256+
.WillOnce(Return(render_b));
257+
EXPECT_CALL(*impeller_command_buffer_, OnCreateBlitPass)
258+
.WillOnce(Return(blit_a));
259+
EXPECT_CALL(*render_a, OnEncodeCommands).Times(0);
260+
EXPECT_CALL(*blit_a, EncodeCommands).Times(0);
261+
EXPECT_CALL(*render_b, OnEncodeCommands).Times(0);
262+
263+
// Submit posts to the raster thread, which needs a running isolate, so
264+
// this only checks that ending passes does not encode them on GLES.
265+
auto pass = fml::MakeRefCounted<RenderPass>();
266+
ASSERT_TRUE(pass->Begin(*command_buffer_));
267+
EXPECT_TRUE(Copy());
268+
EXPECT_TRUE(Copy());
269+
EXPECT_EQ(command_buffer_->CreateRenderPass(impeller::RenderTarget()),
270+
render_b);
271+
EXPECT_TRUE(pass->End());
272+
}
273+
274+
TEST_F(FlutterGpuPassLifecycleTest, FailingToEncodeAnEndedPassFailsSubmit) {
275+
auto render_a = MakeRenderPass();
276+
EXPECT_CALL(*impeller_command_buffer_, OnCreateRenderPass)
277+
.WillOnce(Return(render_a));
278+
EXPECT_CALL(*render_a, OnEncodeCommands).WillOnce(Return(false));
279+
EXPECT_CALL(*command_queue_, Submit).Times(0);
280+
281+
EXPECT_EQ(command_buffer_->CreateRenderPass(impeller::RenderTarget()),
282+
render_a);
283+
EXPECT_FALSE(Copy());
284+
285+
std::vector<impeller::CommandBuffer::Status> statuses;
286+
EXPECT_FALSE(command_buffer_->Submit(
287+
[&statuses](impeller::CommandBuffer::Status status) {
288+
statuses.push_back(status);
289+
}));
290+
ASSERT_EQ(statuses.size(), 1u);
291+
EXPECT_EQ(statuses[0], impeller::CommandBuffer::Status::kError);
292+
}
293+
109294
} // namespace
110295
} // namespace flutter::gpu

0 commit comments

Comments
 (0)