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