Models
A model is named in the properties with its file. The starter loads it once, with the splash or when a scene first shows it, and every use of it is a clone. SpringSceneModel shows it in a scene; the SceneModels bean gives it to code.
Why
Loading a model is code every app writes again: read the file, import it, keep the result, show something meanwhile, handle a failure. And a model used in three places should be read and sent to the GPU once. Here the app names the model, and the starter does the rest.
Example
# lib/resources/application.yml
spring:
flutter:
scene:
models:
hero:
source: asset:assets/models/hero.glb
preload: eager # not set: as spring.flutter.scene.preload
SpringSceneView.declarative(
children: [
SpringSceneModel('hero', position: Vector3(0, 1, 0)),
],
)
The file
source says where the model's file is. The file is a binary glTF (.glb):
| Source | Example | How it is read |
|---|---|---|
| An asset of the app | asset:assets/models/hero.glb |
From the app's assets: the file is listed under flutter: assets: of pubspec.yaml |
| An address | https://cdn.example.com/hero.glb |
With one GET through the app's HttpTransport bean (the platform's client without one), in a browser too |
# pubspec.yaml
flutter:
assets:
- assets/models/
- Not a file of
lib/resources/: those are embedded into the app's code, a megabyte at most. - An address is
httpsonly;httpis read only withspring.remote.allow-insecure: true. - In a browser the server must allow the page's origin (CORS), and under
require-corpisolation nothing else is loaded from another origin (see What a scene costs). - A model without a
sourcefails, naming the key to set:spring.flutter.scene.models.<name>.source.
The file at an address is a RemoteModelResource. The server is asked only when the model is loaded; an answer that is not a success fails the load, naming the address and the status.
Another format is a SceneModelImporter bean of the app. It takes the place of the starter's (GlbModelImporter, the bean sceneModelImporter):
abstract interface class SceneModelImporter {
/// The template of model [name] from the [bytes] of its file.
Future<Node> import(Uint8List bytes, {required String name});
}
Eager and lazy
- An eager model (
preload: eager) is loaded while the splash shows: the first screen has it at once. - A lazy one is loaded when a scene first shows it.
- Not set, a model follows
spring.flutter.scene.preload, which islazyby default.
Either way it is loaded once and kept: a model that left the screen and came back is not imported again.
A model in a scene
SpringSceneModel('hero') shows the model in a scene: a clone of its template, so every use has its own transform and animation while the geometry, textures and materials stay shared on the GPU. It is a scene widget: it goes among the children of a SpringSceneView (or of the engine's own scene widgets), never among ordinary widgets.
| Parameter | Type | Meaning |
|---|---|---|
name (positional) |
String |
The model's name in spring.flutter.scene.models |
variant |
String? |
A material variant of the model (KHR_materials_variants) |
animations |
List<SceneAnimationSpec> |
Which of its animations play, and how |
placeholder |
WidgetBuilder? |
Scene widgets in its place while it loads |
error |
Widget Function(BuildContext, Object)? |
Scene widgets in its place when it failed to load |
onLoaded |
void Function(Node)? |
Called with the clone once it is in the scene |
position, rotation, scale |
Vector3?, Quaternion?, Vector3? |
Where it stands, how it is turned, its scale |
visible |
bool |
Whether it is drawn; true by default |
components |
List<Component> |
Behaviour on its node (the engine's Component) |
children |
List<Widget> |
Scene widgets under its node |
A view waits for its SpringSceneModel widgets before it shows, so a scene is never drawn half-built.
Models in code
SceneModels (sceneModels) gives a model to code:
@Component()
class Showroom {
Showroom(this.models);
final ObjectProvider<SceneModels> models;
// No bean when the app runs with scenes turned off.
Future<void> open() async => models.getIfAvailable()?['hero'].load();
}
Member of SceneModels |
Meaning |
|---|---|
models['hero'] |
The model's SceneModelHandle; an unknown name fails naming those there are |
names, all, eager |
The names, every model, the models loaded with the splash |
contains(name) |
Whether there is a model of that name |
Member of SceneModelHandle |
Meaning |
|---|---|
load() |
Loads the model, once: every call answers the same load. Starts the engine when nothing has yet |
reload() |
Loads it again after a failure |
state |
idle, loading, ready or failed (SceneModelState) |
template |
The loaded node tree, cloned by every use; null until state is ready |
failure |
What the load threw, when it failed |
name, location, eager |
Its name, where its file is as the properties say, whether it is loaded with the splash |
bytes, readTook, importTook |
The size of the file, the time to read it (to download, for an address) and to import it |
A handle is a ChangeNotifier: it notifies its listeners when its state changes.
When a model fails
A model that fails to load is logged as a warning and published as a SceneFailedEvent. The start goes on: an eager model that failed is skipped, and its scenes show their placeholders. reload() on its handle tries again.
See also
- Scenes as widgets
- The start in events and words: the events of a load
- The debug tab: every model by name, with what it costs
- Assets and fonts
- HTTP transport