Wire up checkerboarding of raster cache images in the framework and gallery. (#6749)

bin/internal/engine.version

@@ -1 +1 @@
-16077d474b3ed44bb4aba9a90d8722c4d6591936
+84a060820a7a63d7683a4c546801ffe5c4a8f2e2

examples/flutter_gallery/lib/gallery/app.dart

@@ -29,12 +29,16 @@ class GalleryApp extends StatefulWidget {
   GalleryApp({
     this.updateUrlFetcher,
     this.enablePerformanceOverlay: true,
+    this.checkerboardRasterCacheImages: true,
     Key key}
   ) : super(key: key);
 
   final UpdateUrlFetcher updateUrlFetcher;
+
   final bool enablePerformanceOverlay;
 
+  final bool checkerboardRasterCacheImages;
+
   @override
   GalleryAppState createState() => new GalleryAppState();
 }
@@ -42,6 +46,7 @@ class GalleryApp extends StatefulWidget {
 class GalleryAppState extends State<GalleryApp> {
   bool _useLightTheme = true;
   bool _showPerformanceOverlay = false;
+  bool _checkerboardRasterCacheImages = false;
 
   TargetPlatform platform = defaultTargetPlatform;
 
@@ -60,6 +65,12 @@ class GalleryAppState extends State<GalleryApp> {
           _showPerformanceOverlay = value;
         });
       } : null,
+      checkerboardRasterCacheImages: _checkerboardRasterCacheImages,
+      onCheckerboardRasterCacheImagesChanged: config.checkerboardRasterCacheImages ? (bool value) {
+        setState(() {
+          _checkerboardRasterCacheImages = value;
+        });
+      } : null,
       onPlatformChanged: (TargetPlatform value) {
         setState(() {
           platform = value;
@@ -85,6 +96,7 @@ class GalleryAppState extends State<GalleryApp> {
       color: Colors.grey[500],
       theme: (_useLightTheme ? _kGalleryLightTheme : _kGalleryDarkTheme).copyWith(platform: platform),
       showPerformanceOverlay: _showPerformanceOverlay,
+      checkerboardRasterCacheImages: _checkerboardRasterCacheImages,
       routes: _kRoutes,
       home: home,
     );

examples/flutter_gallery/lib/gallery/drawer.dart

@@ -93,6 +93,8 @@ class GalleryDrawer extends StatelessWidget {
     this.onTimeDilationChanged,
     this.showPerformanceOverlay,
     this.onShowPerformanceOverlayChanged,
+    this.checkerboardRasterCacheImages,
+    this.onCheckerboardRasterCacheImagesChanged,
     this.onPlatformChanged,
   }) : super(key: key) {
     assert(onThemeChanged != null);
@@ -108,6 +110,9 @@ class GalleryDrawer extends StatelessWidget {
   final bool showPerformanceOverlay;
   final ValueChanged<bool> onShowPerformanceOverlayChanged;
 
+  final bool checkerboardRasterCacheImages;
+  final ValueChanged<bool> onCheckerboardRasterCacheImagesChanged;
+
   final ValueChanged<TargetPlatform> onPlatformChanged;
 
   @override
@@ -279,6 +284,23 @@ class GalleryDrawer extends StatelessWidget {
       ));
     }
 
+    if (onCheckerboardRasterCacheImagesChanged != null) {
+      allDrawerItems.insert(8, new DrawerItem(
+        icon: new Icon(Icons.assessment),
+        onPressed: () { onCheckerboardRasterCacheImagesChanged(!checkerboardRasterCacheImages); },
+        selected: checkerboardRasterCacheImages,
+        child: new Row(
+          children: <Widget>[
+            new Flexible(child: new Text('Checkerboard Raster Cache Images')),
+            new Checkbox(
+              value: checkerboardRasterCacheImages,
+              onChanged: (bool value) { onCheckerboardRasterCacheImagesChanged(!checkerboardRasterCacheImages); }
+            )
+          ]
+        )
+      ));
+    }
+
     return new Drawer(child: new Block(children: allDrawerItems));
   }
 }

examples/flutter_gallery/lib/gallery/home.dart

@@ -77,6 +77,8 @@ class GalleryHome extends StatefulWidget {
     this.onTimeDilationChanged,
     this.showPerformanceOverlay,
     this.onShowPerformanceOverlayChanged,
+    this.checkerboardRasterCacheImages,
+    this.onCheckerboardRasterCacheImagesChanged,
     this.onPlatformChanged,
   }) : super(key: key) {
     assert(onThemeChanged != null);
@@ -92,6 +94,9 @@ class GalleryHome extends StatefulWidget {
   final bool showPerformanceOverlay;
   final ValueChanged<bool> onShowPerformanceOverlayChanged;
 
+  final bool checkerboardRasterCacheImages;
+  final ValueChanged<bool> onCheckerboardRasterCacheImagesChanged;
+
   final ValueChanged<TargetPlatform> onPlatformChanged;
 
   @override
@@ -157,6 +162,8 @@ class GalleryHomeState extends State<GalleryHome> with SingleTickerProviderState
         onTimeDilationChanged: config.onTimeDilationChanged,
         showPerformanceOverlay: config.showPerformanceOverlay,
         onShowPerformanceOverlayChanged: config.onShowPerformanceOverlayChanged,
+        checkerboardRasterCacheImages: config.checkerboardRasterCacheImages,
+        onCheckerboardRasterCacheImagesChanged: config.onCheckerboardRasterCacheImagesChanged,
         onPlatformChanged: config.onPlatformChanged,
       ),
       appBar: new AppBar(

packages/flutter/lib/src/material/app.dart

@@ -57,6 +57,7 @@ class MaterialApp extends StatefulWidget {
     this.onLocaleChanged,
     this.debugShowMaterialGrid: false,
     this.showPerformanceOverlay: false,
+    this.checkerboardRasterCacheImages: false,
     this.showSemanticsDebugger: false,
     this.debugShowCheckedModeBanner: true
   }) : super(key: key) {
@@ -128,6 +129,9 @@ class MaterialApp extends StatefulWidget {
   /// https://flutter.io/debugging/#performanceoverlay
   final bool showPerformanceOverlay;
 
+  /// Turns on checkerboarding of raster cache images.
+  final bool checkerboardRasterCacheImages;
+
   /// Turns on an overlay that shows the accessibility information
   /// reported by the framework.
   final bool showSemanticsDebugger;
@@ -264,6 +268,7 @@ class _MaterialAppState extends State<MaterialApp> {
         onGenerateRoute: _onGenerateRoute,
         onLocaleChanged: config.onLocaleChanged,
         showPerformanceOverlay: config.showPerformanceOverlay,
+        checkerboardRasterCacheImages: config.checkerboardRasterCacheImages,
         showSemanticsDebugger: config.showSemanticsDebugger,
         debugShowCheckedModeBanner: config.debugShowCheckedModeBanner
       )

packages/flutter/lib/src/rendering/layer.dart

@@ -188,12 +188,13 @@ class ChildSceneLayer extends Layer {
 class PerformanceOverlayLayer extends Layer {
   /// Creates a layer that displays a performance overlay.
   PerformanceOverlayLayer({
-    this.overlayRect,
-    this.optionsMask,
-    this.rasterizerThreshold
+    @required this.overlayRect,
+    @required this.optionsMask,
+    @required this.rasterizerThreshold,
+    @required this.checkerboardRasterCacheImages,
   });
 
-  /// The rectangle in this layer's coodinate system that the overlay should occupy.
+  /// The rectangle in this layer's coordinate system that the overlay should occupy.
   Rect overlayRect;
 
   /// The mask is created by shifting 1 by the index of the specific
@@ -205,11 +206,25 @@ class PerformanceOverlayLayer extends Layer {
   /// is suitable for capturing an SkPicture trace for further analysis.
   final int rasterizerThreshold;
 
+  /// Whether the raster cache should checkerboard cached entries.
+  ///
+  /// The compositor can sometimes decide to cache certain portions of the
+  /// widget hierarchy. Such portions typically don't change often from frame to
+  /// frame and are expensive to render. This can speed up overall rendering. However,
+  /// there is certain upfront cost to constructing these cache entries. And, if
+  /// the cache entries are not used very often, this cost may not be worth the
+  /// speedup in rendering of subsequent frames. If the developer wants to be certain
+  /// that populating the raster cache is not causing stutters, this option can be
+  /// set. Depending on the observations made, hints can be provided to the compositor
+  /// that aid it in making better decisions about caching.
+  final bool checkerboardRasterCacheImages;
+
   @override
   void addToScene(ui.SceneBuilder builder, Offset layerOffset) {
     assert(optionsMask != null);
     builder.addPerformanceOverlay(optionsMask, overlayRect.shift(layerOffset));
     builder.setRasterizerTracingThreshold(rasterizerThreshold);
+    builder.setCheckerboardRasterCacheImages(checkerboardRasterCacheImages);
   }
 }
 

packages/flutter/lib/src/rendering/performance_overlay.dart

@@ -59,12 +59,19 @@ enum PerformanceOverlayOption {
 class RenderPerformanceOverlay extends RenderBox {
   /// Creates a performance overlay render object.
   ///
-  /// The [optionsMask] and [rasterizerThreshold] arguments must not be null.
+  /// The [optionsMask], [rasterizerThreshold] and [checkerboardRasterCacheImages]
+  /// arguments must not be null.
   RenderPerformanceOverlay({
     int optionsMask: 0,
-    int rasterizerThreshold: 0
+    int rasterizerThreshold: 0,
+    bool checkerboardRasterCacheImages: false,
   }) : _optionsMask = optionsMask,
-      _rasterizerThreshold = rasterizerThreshold;
+      _rasterizerThreshold = rasterizerThreshold,
+      _checkerboardRasterCacheImages = checkerboardRasterCacheImages {
+    assert(optionsMask != null);
+    assert(rasterizerThreshold != null);
+    assert(checkerboardRasterCacheImages != null);
+  }
 
   /// The mask is created by shifting 1 by the index of the specific
   /// [PerformanceOverlayOption] to enable.
@@ -91,6 +98,17 @@ class RenderPerformanceOverlay extends RenderBox {
     markNeedsPaint();
   }
 
+  /// Whether the raster cache should checkerboard cached entries.
+  bool get checkerboardRasterCacheImages => _checkerboardRasterCacheImages;
+  bool _checkerboardRasterCacheImages;
+  set checkerboardRasterCacheImages (bool checkerboard) {
+    assert(checkerboard != null);
+    if (checkerboard == _checkerboardRasterCacheImages)
+      return;
+    _checkerboardRasterCacheImages = checkerboard;
+    markNeedsPaint();
+  }
+
   @override
   bool get sizedByParent => true;
 
@@ -140,7 +158,8 @@ class RenderPerformanceOverlay extends RenderBox {
     context.addLayer(new PerformanceOverlayLayer(
       overlayRect: new Rect.fromLTWH(offset.dx, offset.dy, size.width, size.height),
       optionsMask: optionsMask,
-      rasterizerThreshold: rasterizerThreshold
+      rasterizerThreshold: rasterizerThreshold,
+      checkerboardRasterCacheImages: checkerboardRasterCacheImages,
     ));
   }
 }

packages/flutter/lib/src/widgets/app.dart

@@ -48,11 +48,13 @@ class WidgetsApp extends StatefulWidget {
     this.initialRoute,
     this.onLocaleChanged,
     this.showPerformanceOverlay: false,
+    this.checkerboardRasterCacheImages: false,
     this.showSemanticsDebugger: false,
     this.debugShowCheckedModeBanner: true
   }) : super(key: key) {
     assert(onGenerateRoute != null);
     assert(showPerformanceOverlay != null);
+    assert(checkerboardRasterCacheImages != null);
     assert(showSemanticsDebugger != null);
   }
 
@@ -86,6 +88,9 @@ class WidgetsApp extends StatefulWidget {
   /// https://flutter.io/debugging/#performanceoverlay
   final bool showPerformanceOverlay;
 
+  /// Checkerboards raster cache images.
+  final bool checkerboardRasterCacheImages;
+
   /// Turns on an overlay that shows the accessibility information
   /// reported by the framework.
   final bool showSemanticsDebugger;
@@ -197,11 +202,22 @@ class _WidgetsAppState extends State<WidgetsApp> implements WidgetsBindingObserv
         child: result
       );
     }
+
+    PerformanceOverlay performanceOverlay;
+    // We need to push a performance overlay if any of the display or checkerboarding
+    // options are set.
     if (config.showPerformanceOverlay || WidgetsApp.showPerformanceOverlayOverride) {
+      performanceOverlay = new PerformanceOverlay.allEnabled(
+                  checkerboardRasterCacheImages: config.checkerboardRasterCacheImages);
+    } else if (config.checkerboardRasterCacheImages) {
+      performanceOverlay = new PerformanceOverlay(checkerboardRasterCacheImages: true);
+    }
+
+    if (performanceOverlay != null) {
       result = new Stack(
         children: <Widget>[
           result,
-          new Positioned(top: 0.0, left: 0.0, right: 0.0, child: new PerformanceOverlay.allEnabled()),
+          new Positioned(top: 0.0, left: 0.0, right: 0.0, child: performanceOverlay),
         ]
       );
     }

packages/flutter/lib/src/widgets/performance_overlay.dart

@@ -29,12 +29,15 @@ class PerformanceOverlay extends LeafRenderObjectWidget {
   /// [StatisticOption] to enable.
   PerformanceOverlay({
     Key key,
-    this.optionsMask,
-    this.rasterizerThreshold: 0
+    this.optionsMask: 0,
+    this.rasterizerThreshold: 0,
+    this.checkerboardRasterCacheImages: false
   }) : super(key: key);
 
   /// Create a performance overlay that displays all available statistics
-  PerformanceOverlay.allEnabled({ Key key, this.rasterizerThreshold: 0 })
+  PerformanceOverlay.allEnabled({ Key key,
+                                  this.rasterizerThreshold: 0,
+                                  this.checkerboardRasterCacheImages: false })
     : optionsMask = (
         1 << PerformanceOverlayOption.displayRasterizerStatistics.index |
         1 << PerformanceOverlayOption.visualizeRasterizerStatistics.index |
@@ -75,10 +78,24 @@ class PerformanceOverlay extends LeafRenderObjectWidget {
   /// how many frame intervals).
   final int rasterizerThreshold;
 
+  /// Whether the raster cache should checkerboard cached entries.
+  ///
+  /// The compositor can sometimes decide to cache certain portions of the
+  /// widget hierarchy. Such portions typically don't change often from frame to
+  /// frame and are expensive to render. This can speed up overall rendering. However,
+  /// there is certain upfront cost to constructing these cache entries. And, if
+  /// the cache entries are not used very often, this cost may not be worth the
+  /// speedup in rendering of subsequent frames. If the developer wants to be certain
+  /// that populating the raster cache is not causing stutters, this option can be
+  /// set. Depending on the observations made, hints can be provided to the compositor
+  /// that aid it in making better decisions about caching.
+  final bool checkerboardRasterCacheImages;
+
   @override
   RenderPerformanceOverlay createRenderObject(BuildContext context) => new RenderPerformanceOverlay(
     optionsMask: optionsMask,
-    rasterizerThreshold: rasterizerThreshold
+    rasterizerThreshold: rasterizerThreshold,
+    checkerboardRasterCacheImages: checkerboardRasterCacheImages
   );
 
   @override