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:
- By the generator, when it writes
main.spring.dart. Withfalsein 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. Runbuild_runneragain after changing it. See Modules left out of the build. - At the start. With
falsein 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):
# 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:
- the failure is logged once, as a warning: "The 3D engine (flutter_scene) did not start: scenes show their placeholders";
SceneFailedEventandSceneUnavailableEventare 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:
@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
- Native platforms: Flutter GPU, turned on per platform
- Scenes as widgets
- Testing: a test has no GPU
- All properties
- Modules left out of the build