
# What a scene costs

Most of what a scene costs is not the scene. This page has what was measured, and the properties that lower the cost. What keeps a phone's page smooth, the canvas in a browser and the conditions under which scenes draw less, is in [Speed on phones](speed.md).

## Why

A scene that moves all the time is a standing cost: it is paid on every screen that shows it, for as long as it shows. The numbers below say where the time goes, so that the right thing is turned down.

## Example

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      max-frame-rate: 30     # the ceiling of every scene
      pixel-ratio: 1.5       # the scenes' own; not set: the device's
      pause-off-screen: true
```

```yaml
# lib/resources/application-android.yml: one frame that stands, on Android
spring:
  flutter:
    scene:
      render: still
```

## The measurements

Measured on a page of Dota Passport (Chrome, Apple M5, a release build, `canvas: page`):

- **The scene is not what costs.** It was about 1% of the page's thread. The rest is Flutter drawing the whole page again for every frame of the scene: 20% of the thread at 30 frames a second.
- **Isolation halves it.** With the page cross-origin isolated Flutter draws in a worker: 9%.
- **A debug build misleads**: several times a release's numbers. Measure a release.
- **An animation that never stops is a standing cost.** Fewer frames, a still frame and the pause off the screen are what help.
- **A canvas of their own takes the page out of it.** With `canvas: layer` or `engine` Flutter does not draw the page for a frame of a scene. On the engine's canvas nothing is handed over either: 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 with `engine`. See [The canvas in a browser](speed.md#the-canvas-in-a-browser).

## What helps

| Property | What it does |
|---|---|
| `spring.flutter.scene.max-frame-rate` | The most frames a second any scene draws, `30` by default. `maxFrameRate` on a widget asks for fewer. `0` is as many as the screen shows, 60 to 144: each of them costs a frame |
| `spring.flutter.scene.render: still` | One frame that stands, drawn again only when what it shows changes |
| `spring.flutter.scene.pause-off-screen` | A scene scrolled off the screen stops drawing; `true` by default |
| `spring.flutter.scene.pixel-ratio` | The scenes' own pixel ratio, under the device's: `1` on a screen of `3` draws a ninth of the pixels |
| `spring.flutter.scene.canvas` | In a browser, where a frame of a scene goes: `page` (the default), `layer` or `engine`. With the last two Flutter does not draw the page for it. See [The canvas in a browser](speed.md#the-canvas-in-a-browser) |
| `spring.flutter.scene.light-clustering: false` | Each mesh shades the lamps that reach it: no lamp textures made anew when a lamp comes into the view or leaves it, a frame of about 30 ms on an iPhone |
| `spring.flutter.scene.when` | `still` or `off` while a condition holds: `touch` (a touch screen), `slow` (the scenes cost this device too much, decided before they show) or one of the app's. See [Drawing less where it costs too much](speed.md#drawing-less-where-it-costs-too-much) |

When the system asks for less motion, every scene draws one frame that stands, whatever the properties say.

A value for one platform goes into its profile file, as everywhere: `render: still` in `application-android.yml`, or in the profile a debug run uses (`application-debug.yml`), where a frame costs several times a release's. See [Platform profiles](../spring-boot-starter-flutter/configuration.md#platform-profiles).

## A cross-origin isolated page

The headers are `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`. They are set on the host, and for `flutter run` under `spring.flutter.web.dev-server.headers`:

```yaml
# lib/resources/application.yml
spring:
  flutter:
    web:
      dev-server:
        headers:
          Cross-Origin-Opener-Policy: same-origin
          Cross-Origin-Embedder-Policy: require-corp
```

`require-corp` forbids cross-origin resources without CORS: the server of a model at an address must allow the page's origin (see [Models](models.md)). [The debug tab](debug-tab.md) says whether the page is isolated. See [The dev server of flutter run](../spring-boot-starter-flutter/web.md#the-dev-server-of-flutter-run).

## Where it costs most

- [The application's scene](application-scene.md) under every screen draws the whole page again for each of its frames, with `canvas: page`. With `canvas: engine` it stands behind the page, and the page is not drawn for its frames.
- The engine's start holds the page while its shaders are compiled: see [The engine's shaders](shaders.md).
- A model's cost is seen in [the debug tab](debug-tab.md), by hiding it.

## See also

- [Speed on phones](speed.md)
- [The debug tab](debug-tab.md)
- [The engine's shaders](shaders.md)
- [All properties](properties.md)
- [The frame meter](../spring-boot-starter-flutter/frame-meter.md)
