The application's scene
With spring.flutter.scene.app.enabled: true the app has one scene of its own, the applicationScene bean, made with the splash. It shows under every screen and in every const SpringSceneView().
Why
A backdrop that stays while the screens change cannot belong to one screen: it would be made again with each of them. The application's scene is made once, lives as long as the app, and is filled by beans.
Example
# lib/resources/application.yml
spring:
flutter:
scene:
models:
stage:
source: asset:assets/models/stage.glb
app:
enabled: true # the application's scene
placement: background # background | none
camera:
position: 0, 1.5, -4
target: 0, 1, 0
fov: 45
// The engine has a class Component of its own: only what is used here.
import 'package:flutter_scene/scene.dart' show Scene;
import 'package:spring_boot_starter_flutter_scene/spring_boot_starter_flutter_scene.dart';
@Component()
class Stage implements SceneCustomizer {
Stage(this.models);
final ObjectProvider<SceneModels> models;
@override
Future<void> customize(Scene scene) async {
scene.add((await models.getObject()['stage'].load()).clone());
}
}
The models come through an ObjectProvider: with spring.flutter.scene.enabled: false no scene bean exists, and this bean must still be made. Nothing calls customize then.
What goes into it
Every SceneCustomizer bean receives the scene once, in @Order, after the engine started and before the scene is first drawn. It adds nodes and sets the scene's light, fog and anti-aliasing.
A screen adds to the scene with the engine's SceneSubtree and takes its part away when it leaves. The children of a SpringSceneView() are added to it while that view shows.
Where it shows
spring.flutter.scene.app.placement |
The scene shows |
|---|---|
background (the default) |
Under every screen of the app, and in every SpringSceneView() |
none |
Only in the SpringSceneView() widgets of the app |
With background, the screens must not paint an opaque background of their own. The scene under the screens is a SpringSceneView named application in the debug tab, put below the app's content by a FlutterAppCustomizer (applicationSceneBackground). It takes no pointer events, and it is a plain widget where scenes do not draw.
The camera
The scene is seen through the camera of the properties where a view gives none:
| Key | Type | Default | Meaning |
|---|---|---|---|
spring.flutter.scene.app.camera.position |
x, y, z |
0, 0, -5 |
Where the camera is |
spring.flutter.scene.app.camera.target |
x, y, z |
0, 0, 0 |
What it looks at |
spring.flutter.scene.app.camera.fov |
degrees | 45 |
Its vertical field of view |
A view of its own gives another: SpringSceneView(camera: ...) or cameraBuilder:.
The bean
applicationScene (ApplicationScene, a ChangeNotifier) exists only with app.enabled: true:
| Member | Meaning |
|---|---|
scene |
The engine's Scene; null until it is made, and for good where the engine did not start |
camera |
The camera of spring.flutter.scene.app.camera |
create() |
Makes the scene, once: every call answers the same one. null when the engine did not start or a customizer failed |
The scene is made with the splash, which waits for it (see The start in events and words). A customizer that fails is logged as a warning and published as a SceneFailedEvent; the app goes on without the scene.
What it costs
This is where scenes cost most: a scene under every screen draws the whole page again for each of its frames. See What a scene costs.
In Spring (Java)
Spring Boot customizes what it makes the same way: WebServerFactoryCustomizer beans receive the web server's factory before the server is made.
See also
- Scenes as widgets
- Models
- What a scene costs
- The app widget:
FlutterAppCustomizer