
# The frame meter

The frame meter is a small panel over the app with the frames a second it really draws, the average time of their build and raster, the worst frame, and a bar per frame: within the budget, up to twice it, or over. The times are Flutter's own (`FrameTiming`), on every platform the web included, so it shows on a phone what a desktop browser cannot.

## Why

An app that scrolls smoothly on a developer's laptop may drop frames on a mid-range phone, or in a phone's browser. Flutter's DevTools need a connected computer. The meter shows the truth on the device itself, in any build, and is turned on by a property: in a profile you test with, not for your users.

## Example

```yaml
# lib/resources/application-profile.yml: in profile builds only
spring:
  flutter:
    frame-meter:
      enabled: true
      position: bottom-right
      target-rate: 120      # a 120 Hz phone
```

## What it shows

- **The frames a second** the app really drew in the last moment. An app that draws nothing shows `idle`.
- **Build and raster times**, the average of the UI thread's and the raster thread's work per frame.
- **The worst frame** of the window: the longest a frame took to come once the app wanted it.
- **A bar per frame**, in the theme's `good` color within `1 / target-rate`, `warning` up to twice that, `bad` beyond.
- **A line per source of frames drawn without Flutter**, under the frames a second: `3D 60 fps · 0.9 ms` (see below).

## Frames drawn without Flutter

A 3D scene on a canvas of its own under the page has frames that are no frames of Flutter. Without a line of their own the meter would say `idle` while the scene moves at 60 a second. Each source has a line: its name, how many frames a second it drew in the last second, and what one cost the page's thread on average. A page at rest with a scene moving on it:

```text
idle
3D 60 fps · 0.9 ms
```

The line's color is the budget's, as for Flutter's frames: `good` within `1 / target-rate`, `warning` up to twice that. A scene held to 30 frames a second shows `warning` against a `target-rate` of 60: the color says how often it draws, not that it is late. A source that drew fewer than two frames in the last second has no line.

The scenes of [spring_boot_starter_flutter_scene](../spring-boot-starter-flutter-scene/speed.md) report as `3D`: their frames on `spring.flutter.scene.canvas: layer` or `engine` in a browser, and those its `slow` condition measures behind the placeholders. With `canvas: page`, and outside a browser, Flutter draws the scenes, and their frames are in Flutter's own line.

## A late frame, and a frame nobody waited for

A frame is late only when the app was waiting for it. The meter knows which: as each frame ends it notes whether the next one was asked for already.

| What draws | What the meter measures | What it shows |
|---|---|---|
| Something that moves at every frame: a scroll, a ticker, a transition | The time between the frames. Each was asked for as the one before ended | The rate in `good`, `warning` or `bad`; 20 a second here is `bad` |
| Something that asks for a frame now and then: a slow drift of the background drawn 15 times a second, a clock | What each frame cost to build and raster. Few frames are drawn because few are wanted | The rate in the plain text color, small bars |
| Nothing | Nothing | `idle` |

So a page whose theme drifts its background shows `15 fps` at rest and `60 fps` while it scrolls, and neither is a fault. Flutter draws only what changes, so a pause with nothing to draw is never a slow frame; a frame the app waited long for is late however long the wait.

The panel is drawn again at most four times a second. A frame drawn for the meter alone is not the app's: it is not counted, and it does not make the app's frames look closer to each other. Until the app shows, the meter neither shows nor counts, so it takes nothing from the splash.

## In a release

In a release build the meter can be shipped alone, with the debug module `spring.flutter.debug.frame-meter.enabled`, without the rest of the debug panel. It is shown and hidden with ⌘⇧X (Ctrl+Shift+X), or by five quick taps and a sixth held two seconds. See [the debug panel](debug-panel.md).

## The properties

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.flutter.frame-meter.enabled` | bool | `false` | Shows the meter over the app (`FrameMeter`, put there by `SpringApp`) |
| `spring.flutter.frame-meter.position` | `top-left`, `top-right`, `bottom-left`, `bottom-right` | `top-right` | The corner of the screen it shows in, inside the safe area |
| `spring.flutter.frame-meter.target-rate` | number | `60` | The frames a second the screen is meant to show: a frame within `1 / target-rate` is good, up to twice that a warning, more a drop |

The [debug panel](debug-panel.md) turns the meter on and off, and moves it, in a running app without a new build (its Frames tab).

## Its look

The look is the theme's `frame-meter`. A value left out comes from the theme's colors and typography:

```yaml
spring:
  flutter:
    theme:
      frame-meter:
        background: { color: $colors.surface, alpha: 85% }
        foreground: $colors.on-surface
        good: $colors.primary
        warning: $colors.tertiary
        bad: $colors.error
        text-style: label-small
```

| Key | Type | Default | Meaning |
|---|---|---|---|
| `frame-meter.background` | color | the surface at 85 % | The panel's fill |
| `frame-meter.foreground` | color | `on-surface` | The text |
| `frame-meter.good` | color | `primary` | Frames within the budget |
| `frame-meter.warning` | color | `tertiary` | Frames up to twice the budget |
| `frame-meter.bad` | color | `error` | Dropped frames |
| `frame-meter.text-style` | a text style of the typography, or `code` | `label-small` | The text's style |

Colors take every [color form](themes/colors.md) of the theme: names, hex, `$` references and color objects.

## In code

With the debug feature (`spring.flutter.debug.frame-meter.enabled`) the meter is a [debug overlay](overlays.md): it shares its corner with the timeline, one under the other or as pages, and can be dragged with the `drag` feature. `FrameMeterGauge` is the panel alone. `FrameMeter(position:, targetRate:, stages:, child:)` is a widget; put one over any part of the app by hand when you build your own app widget.

Code that draws frames without Flutter reports each one to `OutsideFrames`, and the meter shows the source:

```dart
final OutsideFrames _frames = OutsideFrames.of('video');

void _drew(Duration cost) => _frames.frame(cost);
```

`OutsideFrames.of(name)` is the source of that name, made the first time it is asked for; `frame(cost)` is a frame drawn now, with what it cost the page's thread; `recent` is the rate and the average cost of the last second, `null` when it drew fewer than two frames.

## See also

- [The debug panel](debug-panel.md)
- [Speed on phones (3D scenes)](../spring-boot-starter-flutter-scene/speed.md)
- [The splash and the start](splash.md)
- [Theme properties](themes/properties.md)
