performance_overlay.dart 3.82 KB
Newer Older
1 2 3 4
// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'package:flutter/rendering.dart';
6

Adam Barth's avatar
Adam Barth committed
7
import 'framework.dart';
8

9
/// Displays performance statistics.
10 11 12 13 14 15 16 17 18 19 20 21
///
/// The overlay show two time series. The first shows how much time was required
/// on this thread to produce each frame. The second shows how much time was
/// required on the GPU thread to produce each frame. Ideally, both these values
/// would be less than the total frame budget for the hardware on which the app
/// is running. For example, if the hardware has a screen that updates at 60 Hz,
/// each thread should ideally spend less than 16 ms producing each frame. This
/// ideal condition is indicated by a green vertical line for each thread.
///
/// The simplest way to show the performance overlay is to set
/// [MaterialApp.showPerformanceOverlay] or [WidgetsApp.showPerformanceOverlay]
/// to `true`.
22
class PerformanceOverlay extends LeafRenderObjectWidget {
23 24
  // TODO(abarth): We should have a page on the web site with a screenshot and
  // an explanation of all the various readouts.
25

26
  /// Create a performance overlay that only displays specific statistics. The
27 28
  /// mask is created by shifting 1 by the index of the specific
  /// [StatisticOption] to enable.
29
  PerformanceOverlay({ this.optionsMask, this.rasterizerThreshold: 0, Key key }) : super(key: key);
30

31 32
  /// Create a performance overlay that displays all available statistics
  PerformanceOverlay.allEnabled({ Key key, this.rasterizerThreshold: 0 })
Hixie's avatar
Hixie committed
33
    : optionsMask = (
34 35 36 37
        1 << PerformanceOverlayOption.displayRasterizerStatistics.index |
        1 << PerformanceOverlayOption.visualizeRasterizerStatistics.index |
        1 << PerformanceOverlayOption.displayEngineStatistics.index |
        1 << PerformanceOverlayOption.visualizeEngineStatistics.index
Hixie's avatar
Hixie committed
38 39
      ),
      super(key: key);
40 41

  final int optionsMask;
42 43 44

  /// The rasterizer threshold is an integer specifying the number of frame
  /// intervals that the rasterizer must miss before it decides that the frame
Devon Carew's avatar
Devon Carew committed
45
  /// is suitable for capturing an SkPicture trace for further analysis.
46 47 48 49 50 51 52 53 54
  ///
  /// For example, if you want a trace of all pictures that could not be
  /// renderered by the rasterizer within the frame boundary (and hence caused
  /// jank), specify 1. Specifying 2 will trace all pictures that took more
  /// more than 2 frame intervals to render. Adjust this value to only capture
  /// the particularly expensive pictures while skipping the others. Specifying
  /// 0 disables all capture.
  ///
  /// Captured traces are placed on your device in the application documents
55
  /// directory in this form "trace_<collection_time>.skp". These can
56 57 58 59 60 61 62 63 64 65
  /// be viewed in the Skia debugger.
  ///
  /// Notes:
  /// The rasterizer only takes into account the time it took to render
  /// the already constructed picture. This include the Skia calls (which is
  /// also why an SkPicture trace is generated) but not any of the time spent in
  /// dart to construct that picture. To profile that part of your code, use
  /// the instrumentation available in observatory.
  ///
  /// To decide what threshold interval to use, count the number of horizontal
66
  /// lines displayed in the performance overlay for the rasterizer (not the
67 68
  /// engine). That should give an idea of how often frames are skipped (and by
  /// how many frame intervals).
69
  final int rasterizerThreshold;
70

71
  @override
72
  RenderPerformanceOverlay createRenderObject(BuildContext context) => new RenderPerformanceOverlay(
73 74 75
    optionsMask: optionsMask,
    rasterizerThreshold: rasterizerThreshold
  );
76

77
  @override
78
  void updateRenderObject(BuildContext context, RenderPerformanceOverlay renderObject) {
79 80 81
    renderObject
      ..optionsMask = optionsMask
      ..rasterizerThreshold = rasterizerThreshold;
82 83
  }
}