The engine's shaders
flutter_scene compiles every shader of its bundle before the first frame: 88 shaders, the lit materials and every effect among them. In a browser that holds the page for 0.3 to 0.7 seconds, and over 3 seconds on a first visit. An app whose scenes draw with a few of them builds a bundle of those alone, in a hook of its own.
Why
The start of the engine is a step a user waits for, with the splash or with a placeholder. It compiles every shader of the engine, also those the app never draws with. A bundle in the app's own tree takes the place of the engine's: the engine reads the app's tree first, and a package's copy never wins. So the bundle is built by the app, not by the starter: Dart runs a build hook for one package and lets it write into that package alone, and only the app knows what its scenes draw with. The starter has the function; the app's hook is the call.
Example
// hook/build.dart of the app
import 'package:hooks/hooks.dart';
import 'package:spring_boot_starter_flutter_scene/build_hooks.dart';
void main(List<String> args) async {
await build(args, (input, output) async {
await buildSceneAssets(buildInput: input, buildOutput: output);
});
}
# pubspec.yaml of the app
dependencies:
hooks: ^2.0.0
flutter:
assets:
- lib/spring_gen/flutter_scene_generated/
- path: lib/spring_gen/flutter_scene_generated/opengl_es/
platforms: [web]
buildSceneAssets
One call makes everything of the app's scenes that is made at build time.
| Parameter | Type | Default | Meaning |
|---|---|---|---|
buildInput |
BuildInput |
required | The hook's input |
buildOutput |
BuildOutputBuilder |
required | The hook's output |
shaders |
Set<String>? |
unlitSceneShaders |
The names of the engine's shaders the bundle has; null: no bundle of the app's, the engine's whole one is used |
materials |
bool |
true |
Compiles the .fmat materials under sources, and fails when a material of spring.flutter.scene.materials is not among them (see Materials) |
models |
bool |
true |
Converts the .glb and .fscene files under sources, loadable by the path of their source |
sources |
String |
assets/ |
The app's folder the materials and models are in |
buildSceneShaders is the bundle alone: the same call with materials and models off.
It is in a library of its own, package:spring_boot_starter_flutter_scene/build_hooks.dart: it runs on the Dart VM only (it reads files and runs the SDK's shader compiler), so it is not part of the starter's main library.
The list
The default list (unlitSceneShaders, six shaders) is for scenes of unlit and custom unlit (.fmat) materials:
| Shader |
|---|
UnskinnedVertex |
UnlitFragment |
FullscreenVertex |
ResolveFragment |
CopyFragment |
PrefilterRadianceCubeFragment |
A scene with lit materials (a .glb model has them) names what it needs:
await buildSceneAssets(
buildInput: input,
buildOutput: output,
shaders: {...unlitSceneShaders, 'StandardFragment'},
);
Or it keeps the engine's whole bundle by having no hook: without the hook everything works.
- A name the engine does not have fails the build, naming the shaders it has.
- A shader missing from the bundle fails at draw time with no name in the error: look at every scene after changing the list.
The generated assets
What the hook makes goes into lib/spring_gen/flutter_scene_generated/, with the rest of the generated code, as pubspec.yaml lists it above. The app's root gets no folder for it.
flutter_scene's own hooks write into a folder at the root of the app and cannot be told another place. So the starter runs them for a stand-in of the app under .dart_tool/spring_scene/ and copies their output over. At run time the engine finds its assets by the end of their address, wherever the folder is.
Generated assets are bound to the Flutter that compiled them, so what is in the folder is never committed: the two .gitignore files the build writes there ignore everything else in it. The files themselves are committed. They keep the folders in git, so the asset entries name folders that exist before the first build. An app that ignores spring_gen/ as a whole keeps this one folder:
**/spring_gen/*
!**/spring_gen/flutter_scene_generated/
A pubspec.yaml without the entry stops the build with the lines to add.
See also
- The start in events and words: the engine's start as an event, with the time it took
- What a scene costs
- The debug tab: the time of the engine's start