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

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

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

The property is read twice:

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

# 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). 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. A failed start is not a failed app:

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:

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

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

See ObjectProvider.

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