Skip to content

Commit edcc8e3

Browse files
RickyvdBergclaude
andcommitted
[avio] RenderTargetCache ages once per raster frame
RenderTargetCache documents that textures are kept "for at least one frame" and dropped after keep-alive "frames". The code did otherwise: Start released every lease and End aged every entry, and both ran on every Canvas (Canvas::SetupRenderPass / EndReplay). Each view renders its own Canvas and toImage snapshots age the cache too, so in Avio's multi-view engine an entry died after a few foreign Canvases (status-bar offscreens were re-allocated in 60 of 319 renders at gap 0). flutter#190613 reports the same misnomer upstream. A nested Canvas's Start could also hand out a texture its outer Canvas was still rendering into. Leases and aging are separate now: - RenderTargetAllocator gains BeginScope/EndScope. A Canvas opens one lease scope in SetupRenderPass and closes it in EndReplay (or its destructor, so an abandoned replay still returns its leases). EndScope releases only that scope's leases; a nested scope never reuses a target an outer scope still leases; DisableCache counts belong to the scope that set them (fixes the nested-reset bug where an inner Canvas zeroed an outer DisableCache). - Start/End keep their documented meaning, frame boundaries: End is the one aging epoch. The Rasterizer calls it once per raster frame, after every view (Rasterizer::EndRasterFrameResources). Snapshot Canvases (DisplayListToTexture, RenderToTarget) never age. The Impeller interop toolkit's Surface::DrawDisplayList ends one epoch per draw, since no rasterizer owns its frames. - Patch 46u's usage report reads leases from the scopes. No new policy knob. Retention rises by at most the entries unused for keep-alive raster frames (about 33 ms at 120 Hz). Idle behaviour: with no raster frames nothing ages, so the last frame's entries stay until later raster frames age them out. Nothing else frees them: there is no idle release on the embedder's request, and patch 36's all-hidden trim frees idle transient attachment sets only, never this cache. Tests: - CanvasFailureTest.CanvasReplayLeasesButNeverAgesRenderTargetCache (expected red on the base by behavior: three Canvas replays dropped an unused keep-alive-0 entry) - CanvasFailureTest.DestroyedCanvasReleasesItsLeaseScope - RenderTargetCacheResourceTest: ForeignCanvasesWithinOneFrameDoNotAge, EntryUnusedForKeepAliveFramesIsDropped, ToImageCanvasDoesNotAge, NestedScopeKeepsOuterLeases, DisableCacheIsPerScope, ReportReadsLeasesFromScopes (use the new scope API; red as compile failures on the base) - The playground CachesUsedTexturesAcrossFrames* tests pass unchanged (they drive Start/End as frames). Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent b4e6e80 commit edcc8e3

11 files changed

Lines changed: 361 additions & 35 deletions

File tree

‎AVIO_PATCHES.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@ already ancestors of the selected main target under their original commits.
8484
| 46u | Report-only render-resource accounting | permanent diagnostics (internal C++ API, no ABI change) | none |
8585
| 47 | RenderTargetCache complete keys and miss telemetry | upstreamable bugfix + diagnostics (offer on flutter/flutter#190613) | open: flutter/flutter#190613 |
8686
| 48 | Flip allocates a single-sample secondary | upstreamable memory fix | submit upstream |
87+
| 51 | RenderTargetCache ages once per raster frame | upstreamable correctness fix (offer on flutter/flutter#190613) | open: flutter/flutter#190613 |
8788

8889
Patch #5 also owns the later exact empty-frame and global-request corrections:
8990
global requests may not be consumed by a display-scoped frame; sibling-render,
@@ -752,6 +753,40 @@ shape (a backdrop filter inside an opacity layer, drawing after the
752753
backdrop) must equal the same picture drawn without a backdrop within
753754
1/255, and on Vulkan it must have taken the labelled secondary.
754755

756+
### Patch 51: one RenderTargetCache aging epoch per raster frame
757+
758+
The cache's header promised that textures live "for at least one frame" and
759+
die after keep-alive "frames", but `Canvas::SetupRenderPass` and
760+
`Canvas::EndReplay` called `Start`/`End` on every Canvas: every view's
761+
replay and every toImage snapshot reset every lease and aged every entry. In
762+
Avio's multi-view engine an offscreen died after a few foreign Canvases
763+
(flutter/flutter#190613 describes the same misnomer upstream). A nested
764+
Canvas could also be handed a texture its outer Canvas was still rendering
765+
into.
766+
767+
Leases and aging are now separate. A Canvas opens a lease scope in
768+
`SetupRenderPass` and closes it in `EndReplay` (or its destructor);
769+
`EndScope` releases only that scope's leases, a nested scope never reuses an
770+
outer scope's lease, and `DisableCache` counts belong to the scope that set
771+
them. The Rasterizer ages the cache once per raster frame, after every view
772+
(`End`, from `Rasterizer::EndRasterFrameResources`). Snapshot Canvases
773+
(`DisplayListToTexture`, `RenderToTarget`) never age it. The Impeller
774+
interop toolkit's `Surface::DrawDisplayList` is its own frame and ends one
775+
epoch per draw. Patch 46u's report reads leases from the scopes. No new knob
776+
is added. Retention rises by at most the entries unused for keep-alive raster
777+
frames. Idle behaviour: with no raster frames nothing ages, so the last
778+
frame's entries stay until later raster frames age them out. Nothing else
779+
frees them: the engine has no idle release on request, and patch 36's
780+
all-hidden trim frees idle transient attachment sets only, never this
781+
cache. Regressions:
782+
`CanvasFailureTest.CanvasReplayLeasesButNeverAgesRenderTargetCache`,
783+
`DestroyedCanvasReleasesItsLeaseScope`,
784+
`RenderTargetCacheResourceTest.ForeignCanvasesWithinOneFrameDoNotAge`,
785+
`EntryUnusedForKeepAliveFramesIsDropped`, `ToImageCanvasDoesNotAge`,
786+
`NestedScopeKeepsOuterLeases`, `DisableCacheIsPerScope`,
787+
`ReportReadsLeasesFromScopes`, and the unchanged playground
788+
`CachesUsedTexturesAcrossFrames*`.
789+
755790
## Known baseline debt
756791

757792
- ~~Generic embedder compositor and platform-view tests required broad

‎avio-verify-patches.sh‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -441,6 +441,13 @@ need "the RenderTargetCache size counter carries real bytes" \
441441
$F/impeller/entity/render_target_cache.cc '"real_bytes",'
442442
need "Flip allocates one single-sample secondary" \
443443
$F/impeller/entity/entity_pass_target.cc '"EntityPassTarget Secondary"'
444+
need "a Canvas replay only leases render targets" \
445+
$F/impeller/display_list/canvas.cc \
446+
'render_target_scope_ = renderer_\.GetRenderTargetCache\(\)->BeginScope\(\)'
447+
absent_in "a Canvas replay never ages the render-target cache" \
448+
$F/impeller/display_list/canvas.cc 'GetRenderTargetCache\(\)->(Start|End)\(\)'
449+
need "the rasterizer ages the render-target cache once per frame" \
450+
$F/shell/common/rasterizer.cc 'cache->End\(\);'
444451
need "Slimpeller low-memory path trims idle Impeller caches" \
445452
$F/shell/common/rasterizer.cc 'TrimIdleResourceCaches'
446453
need "explicit transient profiles bypass environment policy" \

‎engine/src/flutter/impeller/display_list/canvas.cc‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -387,6 +387,13 @@ Canvas::Canvas(ContentContext& renderer,
387387
SetupRenderPass();
388388
}
389389

390+
Canvas::~Canvas() {
391+
// A replay that never reached EndReplay still returns its leases.
392+
if (render_target_scope_.has_value()) {
393+
renderer_.GetRenderTargetCache()->EndScope(*render_target_scope_);
394+
}
395+
}
396+
390397
void Canvas::Initialize(std::optional<Rect> cull_rect) {
391398
initial_cull_rect_ = cull_rect;
392399
transform_stack_.emplace_back(CanvasStackEntry{
@@ -1633,7 +1640,10 @@ void Canvas::DrawAtlas(const std::shared_ptr<AtlasContents>& atlas_contents,
16331640
/////////////////////////////////////////
16341641

16351642
void Canvas::SetupRenderPass() {
1636-
renderer_.GetRenderTargetCache()->Start();
1643+
// One lease scope per replay. The cache ages once per raster frame (its
1644+
// owner calls End), never per Canvas.
1645+
FML_DCHECK(!render_target_scope_.has_value());
1646+
render_target_scope_ = renderer_.GetRenderTargetCache()->BeginScope();
16371647
ColorAttachment color0 = render_target_.GetColorAttachment(0);
16381648

16391649
auto& stencil_attachment = render_target_.GetStencilAttachment();
@@ -2780,7 +2790,10 @@ bool Canvas::EndReplay() {
27802790
VALIDATION_LOG << "Failed to submit command buffers";
27812791
}
27822792
render_passes_.clear();
2783-
renderer_.GetRenderTargetCache()->End();
2793+
if (render_target_scope_.has_value()) {
2794+
renderer_.GetRenderTargetCache()->EndScope(*render_target_scope_);
2795+
render_target_scope_.reset();
2796+
}
27842797
clip_geometry_.clear();
27852798

27862799
Reset();

‎engine/src/flutter/impeller/display_list/canvas.h‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ class Canvas {
145145
bool requires_readback,
146146
IRect32 cull_rect);
147147

148-
~Canvas() = default;
148+
~Canvas();
149149

150150
/// @brief Update the backdrop data used to group together backdrop filters
151151
/// within the same layer
@@ -310,6 +310,9 @@ class Canvas {
310310
bool requires_readback_;
311311
// Sticky for this replay, including subpasses removed during Restore.
312312
bool rendering_failed_ = false;
313+
// This replay's render-target lease scope, open from SetupRenderPass until
314+
// EndReplay (or destruction).
315+
std::optional<uint64_t> render_target_scope_;
313316
EntityPassClipStack clip_coverage_stack_;
314317

315318
std::deque<CanvasStackEntry> transform_stack_;

‎engine/src/flutter/impeller/display_list/canvas_unittests.cc‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
#include "impeller/display_list/dl_vertices_geometry.h"
2020
#include "impeller/entity/geometry/rect_geometry.h"
2121
#include "impeller/entity/inline_pass_context.h"
22+
#include "impeller/entity/render_target_cache.h"
2223
#include "impeller/geometry/geometry_asserts.h"
2324
#include "impeller/playground/playground.h"
2425
#include "impeller/playground/widgets.h"
@@ -179,6 +180,46 @@ TEST_F(CanvasFailureTest, FailedMipmapPassIsConsumedWithoutSubmitting) {
179180
EXPECT_TRUE(context->queued.empty());
180181
}
181182

183+
// Red before EN51: every Canvas replay started and ended an aging epoch of
184+
// the shared RenderTargetCache, so in a multi-view frame an offscreen died
185+
// after keep-alive foreign replays. A replay now only leases.
186+
TEST_F(CanvasFailureTest, CanvasReplayLeasesButNeverAgesRenderTargetCache) {
187+
auto cache = std::make_shared<RenderTargetCache>(
188+
context->GetResourceAllocator(), /*keep_alive_frame_count=*/0);
189+
ContentContext renderer(context, nullptr, cache);
190+
cache->Start();
191+
ASSERT_TRUE(cache->CreateOffscreen(*context, {64, 64}, 1).IsValid());
192+
// Release the frame lease without an aging epoch.
193+
cache->Start();
194+
ASSERT_EQ(cache->CachedTextureCount(), 1u);
195+
196+
// Three views render in one frame.
197+
for (int view = 0; view < 3; view++) {
198+
Canvas canvas(renderer, target, false, false);
199+
canvas.EndReplay();
200+
}
201+
EXPECT_EQ(cache->CachedTextureCount(), 1u);
202+
203+
// The frame's owner ages once: the entry was unused for its keep-alive.
204+
cache->End();
205+
EXPECT_EQ(cache->CachedTextureCount(), 0u);
206+
}
207+
208+
// A Canvas that is destroyed without EndReplay still returns its leases.
209+
TEST_F(CanvasFailureTest, DestroyedCanvasReleasesItsLeaseScope) {
210+
auto cache =
211+
std::make_shared<RenderTargetCache>(context->GetResourceAllocator());
212+
ContentContext renderer(context, nullptr, cache);
213+
{
214+
Canvas abandoned(renderer, target, false, false);
215+
}
216+
// A later frame-scope request reuses nothing leased by a dead scope and
217+
// closing the epoch keeps the cache consistent.
218+
ASSERT_TRUE(cache->CreateOffscreen(*context, {64, 64}, 1).IsValid());
219+
cache->End();
220+
EXPECT_EQ(cache->CachedTextureCount(), 1u);
221+
}
222+
182223
TEST_F(CanvasFailureTest, EncodeFailureStillFlushesAndNextReplayCanSucceed) {
183224
fail_encode = true;
184225
{

‎engine/src/flutter/impeller/entity/render_target_cache.cc‎

Lines changed: 61 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,8 @@ void RenderTargetCache::RecordMiss(const RenderTargetConfig& config,
7979
if (td.config == config) {
8080
// A miss with an equal key means every such entry is leased.
8181
same_key = true;
82-
} else if (!td.used_this_frame && td.config.MatchesExceptSize(config)) {
82+
} else if (td.lease_scope == kUnleased &&
83+
td.config.MatchesExceptSize(config)) {
8384
other_extent = true;
8485
}
8586
}
@@ -132,20 +133,20 @@ RenderTargetCache::RenderTargetCache(std::shared_ptr<Allocator> allocator,
132133
keep_alive_frame_count_(keep_alive_frame_count) {}
133134

134135
void RenderTargetCache::Start() {
135-
cache_disabled_count_ = 0;
136-
frame_open_ = true;
137-
for (auto& td : render_target_data_) {
138-
td.used_this_frame = false;
139-
}
136+
frame_disabled_count_ = 0;
137+
ReleaseLeases(kFrameScope);
140138
}
141139

142140
void RenderTargetCache::End() {
143-
cache_disabled_count_ = 0;
144-
frame_open_ = false;
141+
frame_disabled_count_ = 0;
142+
ReleaseLeases(kFrameScope);
145143
std::vector<RenderTargetData> retain;
146144

147145
for (RenderTargetData& td : render_target_data_) {
148-
if (td.used_this_frame) {
146+
if (td.used_this_frame || td.lease_scope != kUnleased) {
147+
// Used in this epoch (or still leased by an open scope): keep it with
148+
// its full keep-alive, and start the next epoch unused.
149+
td.used_this_frame = false;
149150
retain.push_back(td);
150151
} else if (td.keep_alive_frame_count > 0) {
151152
td.keep_alive_frame_count--;
@@ -162,8 +163,45 @@ void RenderTargetCache::End() {
162163
}
163164
}
164165

166+
uint64_t RenderTargetCache::BeginScope() {
167+
const uint64_t id = next_scope_id_++;
168+
scopes_.push_back(Scope{.id = id});
169+
return id;
170+
}
171+
172+
void RenderTargetCache::EndScope(uint64_t scope) {
173+
const auto found =
174+
std::find_if(scopes_.begin(), scopes_.end(),
175+
[scope](const Scope& open) { return open.id == scope; });
176+
FML_DCHECK(found != scopes_.end()) << "Closing a scope that is not open.";
177+
if (found == scopes_.end()) {
178+
return;
179+
}
180+
FML_DCHECK(found->disabled_count == 0u);
181+
scopes_.erase(found);
182+
ReleaseLeases(scope);
183+
}
184+
185+
uint64_t RenderTargetCache::CurrentScope() const {
186+
return scopes_.empty() ? kFrameScope : scopes_.back().id;
187+
}
188+
189+
uint32_t& RenderTargetCache::CurrentDisabledCount() {
190+
return scopes_.empty() ? frame_disabled_count_
191+
: scopes_.back().disabled_count;
192+
}
193+
194+
void RenderTargetCache::ReleaseLeases(uint64_t scope) {
195+
for (RenderTargetData& td : render_target_data_) {
196+
if (td.lease_scope == scope) {
197+
td.lease_scope = kUnleased;
198+
}
199+
}
200+
}
201+
165202
void RenderTargetCache::LeaseEntry(RenderTargetData& data) {
166203
data.used_this_frame = true;
204+
data.lease_scope = CurrentScope();
167205
data.keep_alive_frame_count = keep_alive_frame_count_;
168206
SampleLeased();
169207
}
@@ -179,6 +217,7 @@ void RenderTargetCache::InsertEntry(const RenderTargetConfig& config,
179217
.nominal_bytes = bytes.nominal, //
180218
.real_bytes = bytes.real, //
181219
.created_interval = interval_, //
220+
.lease_scope = CurrentScope(), //
182221
});
183222
created_entries_++;
184223
SampleLeased();
@@ -192,12 +231,9 @@ void RenderTargetCache::AccountErased(const RenderTargetData& data) {
192231
}
193232

194233
void RenderTargetCache::SampleLeased() {
195-
if (!frame_open_) {
196-
return;
197-
}
198234
size_t leased = 0u;
199235
for (const RenderTargetData& td : render_target_data_) {
200-
if (td.used_this_frame) {
236+
if (td.lease_scope != kUnleased) {
201237
leased += td.nominal_bytes;
202238
}
203239
}
@@ -213,7 +249,7 @@ RenderResourceUsage RenderTargetCache::ReportUsage(bool start_new_interval) {
213249
const RenderTargetData& td = render_target_data_[index];
214250
report.nominal_bytes += td.nominal_bytes;
215251
report.real_bytes += td.real_bytes;
216-
if (frame_open_ && td.used_this_frame) {
252+
if (td.lease_scope != kUnleased) {
217253
report.leased_entries++;
218254
leased_nominal_bytes += td.nominal_bytes;
219255
}
@@ -245,19 +281,21 @@ RenderResourceUsage RenderTargetCache::ReportUsage(bool start_new_interval) {
245281
}
246282

247283
void RenderTargetCache::DisableCache() {
248-
cache_disabled_count_++;
284+
CurrentDisabledCount()++;
249285
}
250286

251287
bool RenderTargetCache::CacheEnabled() const {
252-
return cache_disabled_count_ == 0;
288+
return (scopes_.empty() ? frame_disabled_count_
289+
: scopes_.back().disabled_count) == 0;
253290
}
254291

255292
void RenderTargetCache::EnableCache() {
256-
FML_DCHECK(cache_disabled_count_ > 0);
257-
if (cache_disabled_count_ == 0) {
293+
uint32_t& count = CurrentDisabledCount();
294+
FML_DCHECK(count > 0);
295+
if (count == 0) {
258296
return;
259297
}
260-
cache_disabled_count_--;
298+
count--;
261299
}
262300

263301
RenderTarget RenderTargetCache::CreateOffscreen(
@@ -294,7 +332,8 @@ RenderTarget RenderTargetCache::CreateOffscreen(
294332
if (CacheEnabled()) {
295333
for (RenderTargetData& render_target_data : render_target_data_) {
296334
const RenderTargetConfig other_config = render_target_data.config;
297-
if (!render_target_data.used_this_frame && other_config == config) {
335+
if (render_target_data.lease_scope == kUnleased &&
336+
other_config == config) {
298337
LeaseEntry(render_target_data);
299338
ColorAttachment color0 =
300339
render_target_data.render_target.GetColorAttachment(0);
@@ -357,7 +396,8 @@ RenderTarget RenderTargetCache::CreateOffscreenMSAA(
357396
if (CacheEnabled()) {
358397
for (RenderTargetData& render_target_data : render_target_data_) {
359398
const RenderTargetConfig other_config = render_target_data.config;
360-
if (!render_target_data.used_this_frame && other_config == config) {
399+
if (render_target_data.lease_scope == kUnleased &&
400+
other_config == config) {
361401
LeaseEntry(render_target_data);
362402
ColorAttachment color0 =
363403
render_target_data.render_target.GetColorAttachment(0);

0 commit comments

Comments
 (0)