
# Where scenes do not draw

Scenes do not draw everywhere: an app may turn them off, a browser may have no WebGL2, the engine may fail to start. There the scene widgets are plain widgets over their placeholders, and the app goes on.

## Why

Without this, every place that shows a scene would ask "can this device draw it?" and build something else. The starter asks once. The widgets need no check, and the app's code has no branch for it.

## The three cases

| When | What the widgets do | The beans |
|---|---|---|
| `spring.flutter.scene.enabled: false` | their placeholders | none exists; in the application's own configuration the build leaves the module out |
| `render: off` | their placeholders | exist; the engine is never started |
| The engine did not start (no WebGL2, no Flutter GPU, a browser that does not pass a frame of WebGL to the page) | their placeholders | exist; `SceneUnavailableEvent` says why, once |

A condition of `spring.flutter.scene.when` that asks for `off` does what `render: off` does, while it holds (see [Drawing less where it costs too much](speed.md#drawing-less-where-it-costs-too-much)).

A `SpringSceneView` builds its `placeholder` and nothing of the engine. A `SceneBackdrop` builds its `placeholder` and its `child`. A view without a placeholder is empty.

## Scenes turned off

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      enabled: false
```

The property is read twice:

- **By the generator**, when it writes `main.spring.dart`. With `false` in the application's own configuration the build leaves the starter's module out: the app has none of its beans. Not set, the module is in every build. Run `build_runner` again after changing it. See [Modules left out of the build](../spring-core-dart-generator/optimizations/build-conditions.md).
- **At the start.** With `false` in a profile file, none of the starter's beans is made in a running app whose build has them.

The scene widgets stay in the app's code and still name the engine, so the engine's code stays in the build.

`render: off` is the lighter switch: the beans exist, the engine is never started, the widgets show their placeholders. A value for one platform goes into its profile file (see [Platform profiles](../spring-boot-starter-flutter/configuration.md#platform-profiles)):

```yaml
# lib/resources/application-android.yml
spring:
  flutter:
    scene:
      render: off
```

## The engine did not start

The engine starts once for the app (see [The start in events and words](start.md)). Where it cannot draw (a browser without WebGL2, a native platform where Flutter GPU is not turned on) the start fails. Outside a browser, Flutter GPU is turned on with a line in the platform's own file: see [Native platforms](native-platforms.md). A failed start is not a failed app:

- the failure is logged once, as a warning: "The 3D engine (flutter_scene) did not start: scenes show their placeholders";
- `SceneFailedEvent` and `SceneUnavailableEvent` are published;
- every scene widget shows its placeholder.

## A scene bean that may be absent

With scenes turned off no scene bean exists. The app's own code that wants one takes it as a bean that may be absent:

```dart
@Component()
class Showroom {
  Showroom(this.models);

  final ObjectProvider<SceneModels> models;

  Future<void> open() async => models.getIfAvailable()?['hero'].load();
}
```

A widget asks the context the same way:

```dart
final status = context.springContext
    .getBeanProvider<SceneStatus>()
    .getIfAvailable();
```

See [ObjectProvider](../spring-core-dart/beans/object-provider.md).

## SceneAvailability

`SceneAvailability` (`sceneAvailability`) is the one place that knows whether scenes draw here. Every scene widget of the starter reads it. It is a `ChangeNotifier`: it notifies its listeners when the engine's start moves, and when a condition of `spring.flutter.scene.when` starts or stops holding.

| Member | Meaning |
|---|---|
| `draws` | Whether scenes draw, now or once the engine has started |
| `isReady` | Whether a scene can be drawn this moment |
| `reason` | Why scenes do not draw: `SceneUnavailable.off` (`render: off`, or a condition of `when` that asks for `off`) or `SceneUnavailable.engine` (the engine did not start); `null` when they do |
| `render` | How scenes draw now: `render`, or less while a condition of `when` holds |
| `animates` | Whether scenes move; `false` for one frame that stands |
| `frameRate([asked])` | The frames a second of a scene that asks for `asked`: never over `max-frame-rate`; with `max-frame-rate: 0` the screen's rate |
| `conditions` | The conditions the scenes follow (`SceneCondition` beans) |
| `held` | The conditions that hold now and change the mode, each with the mode it asks for |
| `deciding` | Whether a condition named in `when` is still finding out: a moving scene stays behind its placeholder meanwhile |
| `engine` | The `SceneEngine`: its `state` (`idle`, `starting`, `ready`, `failed`), `failure`, `took` |

With `spring.flutter.scene.enabled: false` this bean does not exist either: code that needs it takes an `ObjectProvider<SceneAvailability>`.

## See also

- [Native platforms](native-platforms.md): Flutter GPU, turned on per platform
- [Scenes as widgets](scenes.md)
- [Testing](testing.md): a test has no GPU
- [All properties](properties.md)
- [Modules left out of the build](../spring-core-dart-generator/optimizations/build-conditions.md)
