
# フレームメーター

フレームメーターは、アプリの上の小さなパネルです。アプリが実際に描画する毎秒のフレーム数、そのビルドとラスターの平均時間、最悪のフレーム、そしてフレームごとのバー (予算内、その 2 倍まで、それ以上) を表示します。時間は Flutter 自身のもの (`FrameTiming`) で、Web を含むすべてのプラットフォームで計測されるため、デスクトップのブラウザーでは見えないものをスマートフォンで表示できます。

## 使う理由

開発者のノートパソコンで滑らかにスクロールするアプリも、中程度のスマートフォンや、スマートフォンのブラウザーではフレームを落とすことがあります。Flutter の DevTools には接続されたコンピューターが必要です。メーターはデバイスそのものの上で、どのビルドでも本当の値を示し、プロパティで有効にします。テストに使うプロファイルで有効にし、ユーザー向けには有効にしません。

## 例

```yaml
# lib/resources/application-profile.yml: プロファイルビルドでだけ
spring:
  flutter:
    frame-meter:
      enabled: true
      position: bottom-right
      target-rate: 120      # 120 Hz のスマートフォン
```

## 表示するもの

- 直近にアプリが実際に描画した**毎秒のフレーム数**。何も描画しないアプリは `idle` と表示します。
- **ビルドとラスターの時間**。フレームあたりの UI スレッドとラスタースレッドの処理の平均です。
- 期間内の**最悪のフレーム**。アプリがフレームを求めてから、それが来るまでにかかった最も長い時間です。
- **フレームごとのバー**。`1 / target-rate` 以内ならテーマの `good` の色、その 2 倍までなら `warning`、それを超えると `bad` です。
- **Flutter の外で描かれるフレームの、出どころごとの行**。毎秒のフレーム数の下に `3D 60 fps · 0.9 ms` のように表示されます (後述)。

## Flutter の外で描かれるフレーム

ページの下にある専用のキャンバスに描かれる 3D シーンのフレームは、Flutter のフレームではありません。専用の行がなければ、シーンが毎秒 60 フレームで動いていても、メーターは `idle` と表示してしまいます。出どころごとに一行があり、名前、直前の一秒に描いた毎秒のフレーム数、一フレームがページのスレッドで使った平均の時間を示します。ページは止まっていて、その上でシーンが動いている場合は次のようになります。

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

行の色は、Flutter のフレームと同じく予算によります。`1 / target-rate` 以内なら `good`、その 2 倍までなら `warning` です。毎秒 30 フレームに抑えたシーンは、`target-rate` が 60 なら `warning` で表示されます。この色が示すのは描く頻度で、遅れではありません。直前の一秒に描いたフレームが二つ未満の出どころには、行がありません。

[spring_boot_starter_flutter_scene](../spring-boot-starter-flutter-scene/speed.md) のシーンは `3D` として報告されます。対象は、ブラウザーで `spring.flutter.scene.canvas: layer` または `engine` のときのフレームと、条件 `slow` がプレースホルダーの後ろで計測するフレームです。`canvas: page` のとき、またブラウザー以外では、シーンを描くのは Flutter なので、そのフレームは Flutter 自身の行に含まれます。

## 遅れたフレームと、誰も待っていなかったフレーム

フレームが遅れたと言えるのは、アプリがそれを待っていたときだけです。メーターはそれを区別します。フレームが終わるたびに、次のフレームがすでに要求されているかどうかを記録します。

| 描画するもの | メーターが測るもの | 表示 |
|---|---|---|
| 毎フレーム動くもの: スクロール、ティッカー、画面遷移 | フレームとフレームの間の時間。どのフレームも、前のフレームが終わる時点で要求されています | `good`、`warning`、`bad` の色のフレーム数。ここでの毎秒 20 は `bad` です |
| ときどきフレームを要求するもの: 毎秒 15 回描画される背景のゆっくりした移動、時計 | 各フレームのビルドとラスターにかかった時間。フレームが少ないのは、少ししか求められていないからです | 通常の文字色のフレーム数と、小さなバー |
| 何もない | 何もない | `idle` |

そのため、テーマが背景をゆっくり動かすページは、止まっているときに `15 fps`、スクロール中に `60 fps` と表示し、どちらも問題ではありません。Flutter は変わったものだけを描画するので、描画するものがない間が遅いフレームになることはありません。アプリが長く待ったフレームは、どれだけ長く待っても遅れたフレームです。

パネルは最大で 1 秒に 4 回再描画されます。メーターだけのために描画されたフレームは、アプリのものではありません。数えられず、アプリのフレーム同士の間隔を短く見せることもありません。アプリが表示されるまでは表示も計測もしないため、スプラッシュから何も奪いません。

## リリースで

リリースビルドでは、デバッグモジュール `spring.flutter.debug.frame-meter.enabled` で、デバッグパネルの残りなしにメーターだけを配布できます。⌘⇧X (Ctrl+Shift+X)、または 5 回の素早いタップと 2 秒間押し続ける 6 回目のタップで表示と非表示を切り替えます。[デバッグパネル](debug-panel.md) を参照してください。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.frame-meter.enabled` | bool | `false` | アプリの上にメーター (`SpringApp` が置く `FrameMeter`) を表示する |
| `spring.flutter.frame-meter.position` | `top-left`、`top-right`、`bottom-left`、`bottom-right` | `top-right` | 表示する画面の隅。セーフエリアの内側 |
| `spring.flutter.frame-meter.target-rate` | 数値 | `60` | 画面が表示すべき毎秒のフレーム数。`1 / target-rate` 以内のフレームは良好、その 2 倍までは警告、それ以上はドロップ |

[デバッグパネル](debug-panel.md) は、新しいビルドなしで、実行中のアプリでメーターのオンとオフを切り替え、移動します (その Frames タブ)。

## 見た目

見た目はテーマの `frame-meter` です。省略した値は、テーマの色とタイポグラフィから来ます。

```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
```

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `frame-meter.background` | 色 | 85 % の surface | パネルの塗り |
| `frame-meter.foreground` | 色 | `on-surface` | テキスト |
| `frame-meter.good` | 色 | `primary` | 予算内のフレーム |
| `frame-meter.warning` | 色 | `tertiary` | 予算の 2 倍までのフレーム |
| `frame-meter.bad` | 色 | `error` | ドロップしたフレーム |
| `frame-meter.text-style` | タイポグラフィのテキストスタイル、または `code` | `label-small` | テキストのスタイル |

色には、テーマのすべての [色の形式](themes/colors.md) を使えます。名前、16 進数、`$` の参照、色のオブジェクトです。

## コードで

デバッグ機能 (`spring.flutter.debug.frame-meter.enabled`) があると、メーターは [デバッグオーバーレイ](overlays.md) になります。タイムラインと隅を共有し、上下に並ぶかページとして表示され、`drag` 機能でドラッグできます。`FrameMeterGauge` はパネルだけです。

`FrameMeter(position:, targetRate:, stages:, child:)` はウィジェットです。独自のアプリのウィジェットを組み立てる場合は、アプリの任意の部分の上に手で置いてください。

Flutter の外でフレームを描くコードは、フレームごとに `OutsideFrames` へ報告します。メーターはその出どころを表示します。

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

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

`OutsideFrames.of(name)` はその名前の出どころで、最初に求められたときに作られます。`frame(cost)` は、いま描かれたフレームと、それがページのスレッドで使った時間です。`recent` は直前の一秒のフレーム数と平均のコストで、描いたフレームが二つ未満なら `null` です。

## 関連項目

- [デバッグパネル](debug-panel.md)
- [スマートフォンでの速さ (3D シーン)](../spring-boot-starter-flutter-scene/speed.md)
- [スプラッシュと起動](splash.md)
- [テーマのプロパティ](themes/properties.md)
