
# Speed on phones

A scene that costs 1% of a desktop's page can heat a phone and make the whole page lag. This page has what the starter does about it by itself, and the properties that decide where a frame of a scene goes and when scenes draw less.

## Why

On a phone, a page with two moving scenes lost frames for reasons that were not the scenes: Flutter drew the page 60 or 120 times a second for scenes of 30, the browser copied every frame of a scene from one canvas to another, and the engine made its lamp textures anew whenever a lamp scrolled into the view. Some of it the starter now avoids by itself. The rest depends on the page and the device, so it is configuration: a profile file, or a condition the starter checks on the device.

## Example

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      canvas: engine           # in a browser: every scene on the engine's own canvas
      light-clustering: false  # a few lamps: no lamp textures made anew
      when:
        slow: still            # too slow on this device: one frame that stands
```

```yaml
# lib/resources/application-desktop.yml: as many frames as the screen shows
spring:
  flutter:
    scene:
      max-frame-rate: 0
```

## One beat for every scene

The engine's own view ticks with the display: every refresh, 60 or 120 a second, is a frame of Flutter, even when the scene draws 24 of them, and in a browser every frame of Flutter draws the whole page again. The starter's views (`SpringSceneView`, `SceneBackdrop`) do not tick. Each moving view joins one beat, the `SceneFrames` bean, with the frames a second it may draw, and on each beat it is asked whether it is due. All of them draw on the same beat, so the page is drawn once for all of them: 30 times a second for a scene of 30 and one of 24, not 60 or 120.

| Where | The beat |
|---|---|
| A browser | Its frames (`requestAnimationFrame`): the scenes draw with the page's frame, before the browser shows it |
| Elsewhere | A timer at the highest rate of the moving views |

A timer beats out of step with the screen: a beat that lands just before the browser shows a frame keeps that frame from being shown in time, and Safari fired a timer of 16 ms some 50 times a second. An iPhone scrolling a page with two scenes showed 43 frames a second on a timer's beat, 52 on the browser's frames.

Nothing is set for it. A scene that stands, or one scrolled off the screen, leaves the beat; when no scene moves there is no beat. A `SceneView` of the app's own still ticks with the display.

## The ceiling on frames

`spring.flutter.scene.max-frame-rate` is the most frames a second any scene draws, `30` by default; `maxFrameRate` on a widget asks for fewer. `0` is the screen's own rate:

| Where | `max-frame-rate: 0` |
|---|---|
| A browser | Every frame of the browser: 60, 120 or 144 a second, by the monitor |
| Elsewhere | The display's refresh rate, 60 when the system gives none |

`maxFrameRate: 0` on a widget asks for no fewer than the properties let it. Each frame of a scene costs what a frame costs, so `0` draws two to almost five times the frames of `30`. Use it where the scenes are cheap (the engine's canvas below, a desktop), and keep a ceiling on a phone, where a scene is often a background that does not need every frame.

## The canvas in a browser

`spring.flutter.scene.canvas` says where a frame of a scene goes in a browser. Elsewhere Flutter draws it, whatever the property says.

| Value | Where a frame goes | What a frame costs |
|---|---|---|
| `page` (the default) | Flutter draws it into the page, and draws the page again around it | The whole page, on every frame of the scene |
| `layer` | A canvas of the scene's own under the page; the browser hands each frame over to it (`transferToImageBitmap`) | The scene, and the hand-over: free in Chrome, read back from the GPU in Firefox, copied in WebKit |
| `engine` | The engine's own canvas, shown as it is: every scene draws into a texture of its own, and the canvas is drawn from them where the scenes stand, clipped as the page clips them (a scrolled list) | The scenes alone: nothing is handed over or copied |

With `layer` and `engine` Flutter does not draw the page for a frame of a scene. Widgets of the page over a scene still draw over it.

`layer` can be set per view (`SpringSceneView(canvas: SceneCanvas.layer)`); a view without it takes the property. Where the hand-over is free, the engine's shared canvas is no longer made anew for each scene of another size (Chrome: a beat of two scenes, 6.6 → 1.4 ms).

`engine` is the whole app's: it is set when the engine starts, and every view is on the engine's canvas whatever its own `canvas` says.

- **When the first scene of the page fills the screen** (a scene behind the whole page, such as [the application's scene](application-scene.md) under every screen), the canvas stands behind the page, and Flutter draws the page on one canvas. The theme's background around the navigator would hide it, so it draws nothing while the canvas shows (`PageUnderlay`). A screen's own background (`ThemeBackground.screen`) and an opaque one (`ThemeBackground.none`) still draw, over the scene. See [Theme background](../spring-boot-starter-flutter/themes/background.md).
- **Otherwise** the canvas stands in that first scene as a platform view, and Flutter draws the page on one canvas under it and one over it.

The canvas is as large as the first scene of the page, one that no other scene is inside. The other scenes show inside it, and only where the page draws nothing over them: on the engine's canvas a scene is under everything Flutter draws above the first scene, a card's own fill included.

Measured: a beat of two scenes on a Mac took 12 ms in Firefox and 6.6 ms in Safari with its frames handed over, 1.2 ms on the engine's canvas; an iPhone scrolling a page with two scenes showed 52 frames a second before, 60 with the canvas behind the page.

A view whose frame cannot go on its canvas reports the error once; from then on it is drawn by Flutter (`layer`) or shows its placeholder (`engine`).

### Which to pick

| The page | The canvas |
|---|---|
| Scenes that stand (`render: still`), or a few frames on a simple page | `page` |
| A moving scene with widgets of the page around it and under it, seen mostly in Chrome | `layer`, for the whole app or for that view |
| A scene behind the whole page, any others inside it; phones, Safari, every browser of an iPhone | `engine` |
| Scenes side by side, or a scene on a widget's own opaque fill | `layer`: on the engine's canvas they would show only inside the first scene, and under that fill |

## The lamps' clustering

The engine shades lamps (point, spot and area lights) through a clustering: the view is cut into cells, each with the lamps that reach it (`Scene.punctualLightClustering`, on by default). The clustering keeps its lamp lists in textures sized to the lamps in the view, and makes them all anew when a lamp comes into the view or leaves it, such as a lamp scrolled out with its card: a frame of about 30 ms on an iPhone.

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      light-clustering: false   # each mesh shades the lamps that reach it
```

With `false` every mesh shades the lamps that reach it: cheaper with a few lamps, and no textures to make anew. Keep the default for a scene with many lamps. The property is applied to the scene of every view.

## Drawing less where it costs too much

`spring.flutter.scene.when` gives every scene a mode while a condition holds: `still` (one frame that stands) or `off` (the placeholders). The least of `render` and the modes of the conditions that hold wins. A condition not named here changes nothing.

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      when:
        touch: still     # a touch screen
        slow: still      # the scenes cost this device too much
      slow:
        frame-time: 16ms # a beat of the scenes over half of it is slow
        probe: 24        # frames measured before the scenes show
        after: 3s        # slow beats, on end, after they showed
```

| Condition | Holds when | Decided |
|---|---|---|
| `touch` | The device's main pointer is a finger. In a browser, a coarse pointer (`pointer: coarse`: a phone, a tablet; not a laptop with a touch screen and a mouse); elsewhere Android and iOS | At the start |
| `slow` | The scenes cost this device too much (below) | While the first scenes load; later only at a moment nothing moves |
| an app's own | What its `SceneCondition` bean says (below) | When it says |

A profile tells a browser from an app, not a phone's browser from a desktop's: `application-web.yml` is read in both. `touch` tells them apart.

### slow

`slow` is decided by the scenes' own frames, not the page's, and never by switching a scene off in front of the user.

1. **While the first scenes load**, their placeholders show, and they draw frames nobody sees. The first 6 are left out: the engine builds its programs on them. The next `slow.probe` are measured: what a beat of every moving scene cost the page's thread. That is the scenes' own work; a page that decodes its images meanwhile is no reason to lose its 3D.
2. **When the middle beat** of those measured takes more than half of `slow.frame-time` (8 ms by default), `slow` holds, and the scenes show in the mode of `when.slow` from their first frame. Otherwise they show as they are. A measure that is slow to come (a scene drawn twice a second) ends 3 seconds after its first measured frame, with what it has.
3. **After they show**, the beats are judged 60 at a time. Slow for `slow.after` on end, they only mark the condition: it holds at the next moment no scene moves (the user left the scenes, or scrolled them off the screen), never while one moves on the screen.

Once `slow` holds, it holds for the rest of the run. It measures nothing unless `when` names it.

The measure holds back the first moving scene by about 30 beats: a second at 30 frames a second. A scene that stands does not wait for it. Step 3 counts only frames Flutter does not draw, those of `canvas: layer` and `engine` in a browser; with `canvas: page`, and outside a browser, the measure before the scenes show is what decides.

| Key | Default | Meaning |
|---|---|---|
| `spring.flutter.scene.slow.frame-time` | `16ms` | The time of a frame: a beat of the scenes over half of it is slow |
| `spring.flutter.scene.slow.probe` | `24` | How many frames of the first scenes are measured before they show, after the first few |
| `spring.flutter.scene.slow.after` | `3s` | How long beats are slow, on end, after the scenes showed, before `slow` holds at the next moment no scene moves |

### A condition of the app's own

A condition is a bean of type `SceneCondition`. Its `name` is its key under `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
```

| Member | Meaning |
|---|---|
| `name` | Its key under `spring.flutter.scene.when` |
| `holds` | Whether it holds now |
| `settled` | Whether it knows: `false` while it is still finding out |
| `state` | What it sees now, in words, for [the debug tab](debug-tab.md) |

It is a `Listenable`: it notifies its listeners when it starts or stops holding, and the scenes follow at once. The starter's `slow` waits for a moment nothing moves; an app's own condition decides that for itself.

While a condition named in `when` is not `settled`, every moving scene waits behind its placeholder and draws frames nobody sees (`SceneAvailability.deciding`). This is read whenever a view builds: a condition that goes back to `false` after the scenes showed puts the moving scenes behind their placeholders again. Settle once.

### A look at rest

`SpringSceneView.stillOf(context)` says whether the view above stands still: `render: still`, a condition of `when` that asks for it, or the system asking for less motion. A scene widget that moves by the time draws its resting look then: a neon lit, not striking. The widget that asks is built again when it changes. Without a view above, it says whether the system asks for less motion.

## The engine's marks on the timeline

The engine marks each pass of a frame on the timeline (`RenderStats.timelineEvents`). A browser keeps them even in a release build: the page kept every mark, eight a frame of two scenes, thousands in minutes. In a web release build the starter turns them off when the engine starts. Other builds keep them for DevTools.

## Seeing it

- [The frame meter](../spring-boot-starter-flutter/frame-meter.md) shows the scenes' frames on a line of their own, `3D 60 fps · 0.9 ms`: frames Flutter does not draw, how many a second, and what a beat that drew cost the page's thread. That is `canvas: layer` and `engine` in a browser, and the frames `slow` measures behind the placeholders. With `canvas: page`, and outside a browser, the scenes' frames are Flutter's, in its own line.
- [The debug tab](debug-tab.md) shows the mode with the conditions that changed it (**Render**), and each condition with what it sees (**When touch**, **When slow**).

## The beans

| Bean | Type | What it is |
|---|---|---|
| `sceneFrames` | `SceneFrames` | The beat: `rate`, the frames a second the views move at (0 when nothing moves), and `moving`, how many views move |
| `sceneTouchCondition` | `TouchSceneCondition`, a `SceneCondition` | `touch` |
| `sceneSlowCondition` | `SlowFramesSceneCondition`, a `SceneCondition` | `slow`; `middle` is the middle beat of its last measure |

`SceneAvailability` has the conditions too: `conditions`, `held` (those that hold and change the mode, each with the mode it asks for), `deciding`, and `render`, the mode now. See [Where scenes do not draw](without-scenes.md#sceneavailability).

## See also

- [What a scene costs](cost.md)
- [Scenes as widgets](scenes.md)
- [The debug tab](debug-tab.md)
- [All properties](properties.md)
- [The frame meter](../spring-boot-starter-flutter/frame-meter.md)
- [Platform profiles](../spring-boot-starter-flutter/configuration.md#platform-profiles)
