
# スマートフォンでの速さ

デスクトップではページの 1% しか使わないシーンでも、スマートフォンでは端末を熱くし、ページ全体をもたつかせることがあります。このページでは、スターターがそれに対して自動で行うことと、シーンのフレームをどこに描くか、いつシーンの描画を減らすかを決めるプロパティを説明します。

## 使う理由

動くシーンが二つあるページは、スマートフォンでフレームを落としていました。原因はシーンそのものではありません。毎秒 30 フレームのシーンのために Flutter がページを毎秒 60 回や 120 回描き直していたこと、ブラウザーがシーンのフレームを一枚ずつキャンバスからキャンバスへコピーしていたこと、光源がスクロールで画面に入るたびにエンジンが光源のテクスチャーを作り直していたことです。その一部は、いまはスターターが自動で避けます。残りはページとデバイスによって変わるので、設定で決めます。プロファイルのファイルに書くか、スターターがデバイス上で調べる条件に任せます。

## 例

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      canvas: engine           # ブラウザーで: すべてのシーンをエンジン自身のキャンバスに
      light-clustering: false  # 光源が少ない: 光源のテクスチャーを作り直さない
      when:
        slow: still            # このデバイスでは遅すぎる: 静止した一つのフレーム
```

```yaml
# lib/resources/application-desktop.yml: 画面が表示するだけのフレーム
spring:
  flutter:
    scene:
      max-frame-rate: 0
```

## すべてのシーンに一つのビート

エンジン自身のビューは、ディスプレイの更新に合わせて動きます。シーンが毎秒 24 フレームしか描かなくても、毎秒 60 回や 120 回の更新のたびに Flutter のフレームが一つ生まれ、ブラウザーでは Flutter のフレームのたびにページ全体が描き直されます。スターターのビュー (`SpringSceneView`、`SceneBackdrop`) は、ディスプレイの更新に合わせて自分でフレームを進めることはしません。動いているビューはそれぞれ、自分が描いてよい毎秒のフレーム数を持って一つのビート (`SceneFrames` Bean) に加わり、ビートのたびに、いま描く番かどうかを尋ねられます。すべてのビューが同じビートで描くので、ページは全員のために一度だけ描かれます。毎秒 30 フレームのシーンと 24 フレームのシーンがあれば、ページを描くのは毎秒 30 回で、60 回や 120 回ではありません。

| 場所 | ビート |
|---|---|
| ブラウザー | ブラウザーのフレーム (`requestAnimationFrame`)。シーンはページのフレームと一緒に、ブラウザーがそれを表示する前に描かれる |
| それ以外 | 動いているビューのうち最も高いフレーム数に合わせたタイマー |

タイマーは画面とずれて動きます。ブラウザーがフレームを表示する直前にビートが来ると、そのフレームの表示が間に合わなくなります。また Safari は、16 ms のタイマーを毎秒 50 回ほどしか呼びませんでした。シーンが二つあるページを iPhone でスクロールすると、タイマーのビートでは毎秒 43 フレーム、ブラウザーのフレームでは 52 フレームでした。

設定することは何もありません。静止したシーンや、スクロールで画面の外に出たシーンはビートから抜けます。動くシーンが一つもなければ、ビートもありません。アプリ独自の `SceneView` は、これまでどおりディスプレイの更新に合わせて動きます。

## フレームの上限

`spring.flutter.scene.max-frame-rate` は、どのシーンも一秒あたりに描く最大のフレーム数で、デフォルトは `30` です。ウィジェットの `maxFrameRate` は、それより少ないフレームを求めます。`0` は画面自身のフレーム数です。

| 場所 | `max-frame-rate: 0` |
|---|---|
| ブラウザー | ブラウザーのすべてのフレーム。モニターによって毎秒 60、120、144 |
| それ以外 | ディスプレイのリフレッシュレート。システムが値を返さなければ 60 |

ウィジェットの `maxFrameRate: 0` は、プロパティが許す数をそのまま求めます。シーンのフレームはどれも一フレーム分のコストがかかるので、`0` は `30` の 2 倍から 5 倍近いフレームを描きます。シーンが軽い場所 (後で述べるエンジンのキャンバス、デスクトップ) で使い、スマートフォンでは上限を残してください。そこではシーンは背景であることが多く、すべてのフレームは要りません。

## ブラウザーでのキャンバス

`spring.flutter.scene.canvas` は、ブラウザーでシーンのフレームをどこに描くかを決めます。それ以外の場所では、プロパティにかかわらず Flutter が描きます。

| 値 | フレームの行き先 | 一フレームのコスト |
|---|---|---|
| `page` (デフォルト) | Flutter がページの中に描き、その周りのページも描き直す | シーンのフレームごとに、ページ全体 |
| `layer` | ページの下にある、シーン専用のキャンバス。ブラウザーがフレームを一枚ずつそこへ受け渡す (`transferToImageBitmap`) | シーンと受け渡し。Chrome では無料、Firefox では GPU から読み戻し、WebKit ではコピー |
| `engine` | エンジン自身のキャンバスを、そのまま表示する。シーンはそれぞれ専用のテクスチャーに描かれ、キャンバスはシーンのある場所にそれらから描かれる。ページが切り取るとおりに切り取られる (スクロールするリストなど) | シーンだけ。受け渡しもコピーもない |

`layer` と `engine` では、シーンのフレームのために Flutter がページを描くことはありません。シーンの上にあるページのウィジェットは、これまでどおりシーンの上に描かれます。

`layer` はビューごとにも指定できます (`SpringSceneView(canvas: SceneCanvas.layer)`)。指定のないビューはプロパティに従います。受け渡しが無料のブラウザーでは、大きさの違うシーンごとにエンジンの共有キャンバスを作り直すことはもうありません (Chrome: シーン二つのビートが 6.6 → 1.4 ms)。

`engine` はアプリ全体の設定です。エンジンの起動時に決まり、ビューが自分の `canvas` に何を指定していても、すべてのビューがエンジンのキャンバスに描かれます。

- **ページの最初のシーンが画面全体を覆うとき** (ページ全体の背後にあるシーン。たとえばすべての画面の下にある [アプリケーションのシーン](application-scene.md))、キャンバスはページの背後に置かれ、Flutter はページを一枚のキャンバスに描きます。ナビゲーターの周りにあるテーマの背景はそれを隠してしまうので、キャンバスが表示されている間は何も描きません (`PageUnderlay`)。画面独自の背景 (`ThemeBackground.screen`) と不透明な背景 (`ThemeBackground.none`) は、シーンの上にこれまでどおり描かれます。[テーマの背景](../spring-boot-starter-flutter/themes/background.md) を参照してください。
- **それ以外のとき**、キャンバスは最初のシーンの中にプラットフォームビューとして置かれ、Flutter はページをその下の一枚とその上の一枚に分けて描きます。

キャンバスの大きさは、ページの最初のシーン (他のどのシーンの中にもないシーン) と同じです。他のシーンはその内側に、しかもページが上に何も描いていない場所にだけ表示されます。エンジンのキャンバスでは、最初のシーンより上に Flutter が描くものはすべてシーンの上に来ます。カード自身の塗りもそうです。

計測結果: Mac でシーン二つのビートは、フレームを受け渡すと Firefox で 12 ms、Safari で 6.6 ms かかり、エンジンのキャンバスでは 1.2 ms でした。シーンが二つあるページを iPhone でスクロールすると、それまで毎秒 52 フレームだったものが、キャンバスをページの背後に置くと 60 フレームになりました。

フレームをキャンバスに描けなかったビューは、エラーを一度だけ報告します。それ以降、そのビューは Flutter が描くか (`layer`)、プレースホルダーを表示します (`engine`)。

### どれを選ぶか

| ページ | キャンバス |
|---|---|
| 静止したシーン (`render: still`)、または単純なページで少しのフレーム | `page` |
| 周りや下にページのウィジェットがある動くシーンで、主に Chrome で見られる | `layer`。アプリ全体に、またはそのビューだけに |
| ページ全体の背後にあるシーンと、その内側にある他のシーン。スマートフォン、Safari、iPhone のすべてのブラウザー | `engine` |
| 横に並んだシーン、またはウィジェット自身の不透明な塗りの上にあるシーン | `layer`。エンジンのキャンバスでは、最初のシーンの内側にしか表示されず、その塗りの下に隠れる |

## 光源のクラスタリング

エンジンは、光源 (ポイント、スポット、エリアライト) をクラスタリングを通して陰影付けします。ビューをセルに分け、セルごとにそこへ届く光源を持たせる方式です (`Scene.punctualLightClustering`。デフォルトでオン)。クラスタリングは光源のリストを、ビューの中の光源の数に合わせた大きさのテクスチャーに保持します。そのため、光源がビューに入ったり出たりするたびに (カードと一緒にスクロールで外へ出る光源など)、テクスチャーをすべて作り直します。iPhone では約 30 ms のフレームになりました。

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      light-clustering: false   # メッシュごとに、そこへ届く光源で陰影付けする
```

`false` にすると、メッシュはそれぞれ自分に届く光源で陰影付けします。光源が少なければこちらのほうが軽く、作り直すテクスチャーもありません。光源の多いシーンでは、デフォルトのままにしてください。このプロパティは、すべてのビューのシーンに適用されます。

## コストがかかりすぎる場所で描画を減らす

`spring.flutter.scene.when` は、条件が成り立つ間、すべてのシーンにモードを与えます。`still` (静止した一つのフレーム) か `off` (プレースホルダー) です。`render` と、成り立っている条件のモードのうち、最も控えめなものが使われます。ここに書かれていない条件は何も変えません。

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      when:
        touch: still     # タッチスクリーン
        slow: still      # シーンがこのデバイスには重すぎる
      slow:
        frame-time: 16ms # シーンのビートがその半分を超えたら遅い
        probe: 24        # シーンが表示される前に計測するフレーム数
        after: 3s        # 表示された後、遅いビートがこれだけ続いたら
```

| 条件 | 成り立つとき | 判定される時 |
|---|---|---|
| `touch` | デバイスの主なポインターが指であるとき。ブラウザーでは粗いポインター (`pointer: coarse`: スマートフォン、タブレット。タッチスクリーンとマウスのあるノートパソコンは含まない)、それ以外では Android と iOS | 起動時 |
| `slow` | シーンがこのデバイスには重すぎるとき (後述) | 最初のシーンが読み込まれる間。その後は、何も動いていない瞬間だけ |
| アプリ独自の条件 | その `SceneCondition` Bean が示すとおり (後述) | その条件が知らせたとき |

プロファイルが区別できるのはブラウザーとアプリで、スマートフォンのブラウザーとデスクトップのブラウザーは区別できません。`application-web.yml` はどちらでも読まれます。それを区別するのが `touch` です。

### slow

`slow` は、ページではなくシーン自身のフレームで判定されます。ユーザーの目の前でシーンを消して判定することはありません。

1. **最初のシーンが読み込まれる間**、プレースホルダーが表示され、シーンは誰にも見えないフレームを描きます。最初の 6 フレームは除外します。エンジンがそこでプログラムをビルドするからです。続く `slow.probe` フレームを計測します。計測するのは、動いているすべてのシーンを一度ずつ描くビートが、ページのスレッドで使った時間です。これはシーン自身の処理だけで、その間にページが画像をデコードしていても、それを理由に 3D を失うことはありません。
2. **計測したビートの中央値が** `slow.frame-time` の半分 (デフォルトで 8 ms) を超えると `slow` が成り立ち、シーンは最初のフレームから `when.slow` のモードで表示されます。そうでなければ、そのまま表示されます。なかなか終わらない計測 (毎秒 2 回しか描かないシーンなど) は、最初に計測したフレームから 3 秒で、それまでの分で判定します。
3. **表示された後は**、ビートを 60 個ずつまとめて判定します。遅いビートが `slow.after` の間続いても、条件に印を付けるだけです。条件が成り立つのは、次に動くシーンが一つもなくなった瞬間 (ユーザーがシーンから離れたか、スクロールで画面の外に出したとき) で、画面の上でシーンが動いている間には決して成り立ちません。

一度成り立った `slow` は、実行が終わるまで成り立ったままです。`when` に書かれていなければ、何も計測しません。

計測のため、最初の動くシーンは約 30 ビート分だけ表示が遅れます。毎秒 30 フレームなら一秒です。静止したシーンは計測を待ちません。ステップ 3 が数えるのは、Flutter が描かないフレーム、つまりブラウザーで `canvas: layer` と `engine` のフレームだけです。`canvas: page` のとき、またブラウザー以外では、シーンが表示される前の計測だけで判定が決まります。

| キー | デフォルト | 意味 |
|---|---|---|
| `spring.flutter.scene.slow.frame-time` | `16ms` | 一フレームの時間。シーンのビートがその半分を超えたら遅い |
| `spring.flutter.scene.slow.probe` | `24` | シーンが表示される前に、最初の数フレームの後で計測する、最初のシーンのフレーム数 |
| `spring.flutter.scene.slow.after` | `3s` | シーンが表示された後、遅いビートがどれだけ続いたら、次に何も動いていない瞬間に `slow` が成り立つか |

### アプリ独自の条件

条件は `SceneCondition` 型の Bean です。その `name` が、`spring.flutter.scene.when` の下のキーになります。

```dart
@Component()
class BatterySaver extends ChangeNotifier implements SceneCondition {
  bool _on = false;

  @override
  String get name => 'battery';

  @override
  bool get holds => _on;

  @override
  bool get settled => true;

  @override
  String get state => _on ? 'battery saver on' : 'battery saver off';

  void changed(bool on) {
    _on = on;
    notifyListeners();
  }
}
```

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      when:
        battery: still
```

| メンバー | 意味 |
|---|---|
| `name` | `spring.flutter.scene.when` の下のキー |
| `holds` | いま成り立っているかどうか |
| `settled` | 判定が済んでいるかどうか。まだ調べている間は `false` |
| `state` | いま見ているもの。[デバッグタブ](debug-tab.md) のための言葉 |

条件は `Listenable` です。成り立ち始めたとき、成り立たなくなったときにリスナーに知らせ、シーンはすぐにそれに従います。スターターの `slow` は何も動いていない瞬間を待ちますが、アプリ独自の条件では、それをどうするかは条件自身が決めます。

`when` に書かれた条件が `settled` でない間、動くシーンはすべてプレースホルダーの後ろで待ち、誰にも見えないフレームを描きます (`SceneAvailability.deciding`)。これはビューが組み立てられるたびに読まれます。シーンが表示された後で `false` に戻った条件は、動くシーンを再びプレースホルダーの後ろに隠します。判定は一度で済ませてください。

### 静止したときの見た目

`SpringSceneView.stillOf(context)` は、上にあるビューが静止しているかどうかを返します。`render: still` のとき、`when` の条件がそれを求めているとき、またはシステムが動きを減らすよう求めているときです。時間で動くシーンウィジェットは、そのとき静止した見た目を描きます。点滅するネオンではなく、点いたままのネオンです。これを尋ねたウィジェットは、値が変わると組み立て直されます。上にビューがなければ、システムが動きを減らすよう求めているかどうかを返します。

## タイムライン上のエンジンの印

エンジンは、フレームのパスごとにタイムラインへ印を付けます (`RenderStats.timelineEvents`)。ブラウザーはリリースビルドでもそれを捨てず、ページはすべての印を持ち続けました。シーン二つでフレームごとに八つ、数分で数千になります。Web のリリースビルドでは、スターターがエンジンの起動時にこの印をオフにします。それ以外のビルドでは、DevTools のために残ります。

## 確かめる

- [フレームメーター](../spring-boot-starter-flutter/frame-meter.md) は、シーンのフレームを専用の行に表示します: `3D 60 fps · 0.9 ms`。Flutter が描かないフレームの毎秒の数と、描いたビートがページのスレッドで使った時間です。対象は、ブラウザーでの `canvas: layer` と `engine` のフレーム、そして `slow` がプレースホルダーの後ろで計測するフレームです。`canvas: page` のとき、またブラウザー以外では、シーンのフレームは Flutter のフレームなので、Flutter 自身の行に含まれます。
- [デバッグタブ](debug-tab.md) は、モードとそれを変えた条件 (**Render**)、そして各条件と、それがいま見ているもの (**When touch**、**When slow**) を表示します。

## Bean

| Bean | 型 | 内容 |
|---|---|---|
| `sceneFrames` | `SceneFrames` | ビート。`rate` はビューが動いている毎秒のフレーム数 (何も動いていなければ 0)、`moving` は動いているビューの数 |
| `sceneTouchCondition` | `TouchSceneCondition`。`SceneCondition` | `touch` |
| `sceneSlowCondition` | `SlowFramesSceneCondition`。`SceneCondition` | `slow`。`middle` は最後の計測でのビートの中央値 |

`SceneAvailability` も条件を持っています。`conditions`、`held` (成り立っていてモードを変えている条件と、それぞれが求めるモード)、`deciding`、そしていまのモードである `render` です。[シーンが描画されない場所](without-scenes.md#sceneavailability) を参照してください。

## 関連項目

- [シーンのコスト](cost.md)
- [ウィジェットとしてのシーン](scenes.md)
- [デバッグタブ](debug-tab.md)
- [すべてのプロパティ](properties.md)
- [フレームメーター](../spring-boot-starter-flutter/frame-meter.md)
- [プラットフォームのプロファイル](../spring-boot-starter-flutter/configuration.md#プラットフォームのプロファイル)
