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

# 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
# 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.

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.

# 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.

# 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:

@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();
  }
}
# 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

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

See also