Things of the engine to know
The starter is built on flutter_scene, and the app's scenes are written with the engine's own widgets, materials and components. A few things of the engine meet an app early. This page lists them.
Why
None of these is an error message that explains itself: a name that is two classes, a colour that comes out pale, a glow that does not show, a view that fails when it moves again. Each has a short answer.
Component is two classes
The engine's Component (behaviour on a node) and Spring's @Component() meet in a file that imports both. The file of a bean takes from the engine only what it uses, or hides the name:
// 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 {
// ...
}
import 'package:flutter_scene/scene.dart' hide Component; does the same for a file that uses much of the engine.
Colours are linear light
A Color of the app is sRGB, as the theme has it. The engine's materials take linear light: given as it is, a colour comes out pale. SceneColor, an extension on Color, gives both forms:
| Member | Type | Meaning |
|---|---|---|
color.linear |
Vector3 |
The colour in linear light: red, green, blue |
color.linearWithAlpha |
Vector4 |
The colour in linear light with its opacity |
final material = UnlitMaterial()
..baseColorFactor = color.linearWithAlpha;
An additive material leaves no alpha
An additive material leaves no alpha, so its light does not show outside the scene's own surfaces. A glow over the page is alpha blending with the brightness as alpha.
Safari: a frame of WebGL and its alpha
The engine hands every frame to Flutter as a bitmap of its WebGL canvas (transferToImageBitmap), and Flutter's renderer takes the bitmap as premultiplied. Which a bitmap of WebGL is, the standard leaves to the browser:
| Browser | A bitmap of a WebGL canvas | Without the starter |
|---|---|---|
| Chrome, Edge, Firefox | premultiplied | right |
| WebKit: Safari, and every browser of an iPhone (Chrome, Telegram's) | the colour divided by the alpha | a half-transparent glow comes out as one block of solid colour |
The starter passes one pixel the engine's way before the engine starts and sees which this browser does. For WebKit it asks for the engine's canvas without premultiplied alpha, and the bytes then reach Flutter unchanged: the same frame as in Chrome. A browser that passes a frame neither way would draw nothing: the start fails with a warning in the log, and the scenes are their placeholders (Where scenes do not draw).
Nothing is asked of the app. The debug tab says which way the frames go (Frames under the engine). A desktop Safari shows the same as an iPhone: what is drawn wrong there is seen without a phone. A difference of precision is not (Precision).
A pause is not autoTick
The engine's own view fails in a debug build when its autoTick goes from false back to true: it makes a second ticker, which Flutter refuses.
The starter's views (SpringSceneView, SceneBackdrop) make the engine's view with autoTick: false and never change it: they take their frames from one beat for every scene (see One beat for every scene). They pause by leaving the beat and stopping the scene's clock (SceneClock). So a scene comes back from less motion or from off the screen without a jump: it moves on by one frame, not by the time it stood.
A SceneView of the app's own should pause the same way, not by its autoTick:
final clock = SceneClock();
Widget build(BuildContext context) {
clock.paused = paused;
return TickerMode(
enabled: !paused,
child: SceneView(scene, clock: clock.clock),
);
}
Per-frame values
Per-frame values are set on a material or a node by a component or a listener of the scene's clock (SceneScope.of(context).elapsed), not by rebuilding widgets. A component of the engine runs on the scene's own clock, so no widget is rebuilt for a frame:
import 'package:flutter_scene/scene.dart';
import 'package:vector_math/vector_math.dart';
/// Turns its node about the vertical axis.
class Spin extends Component {
Spin({this.turnsPerSecond = 0.1, Vector3? axis})
: axis = axis ?? Vector3(0, 1, 0);
final double turnsPerSecond;
final Vector3 axis;
double _angle = 0;
@override
void update(double deltaSeconds) {
_angle += deltaSeconds * turnsPerSecond * 6.283185307179586;
node.localTransform = Matrix4.compose(
node.localTransform.getTranslation(),
Quaternion.axisAngle(axis, _angle),
Vector3.all(node.localTransform.getMaxScaleOnAxis()),
);
}
}
SpringSceneModel('crate', components: [Spin(turnsPerSecond: 0.15)])
In a view that stands still (render: still), a value set without a rebuild asks for a frame with SpringSceneView.repaintOf(context) (see Scenes as widgets).
Generated assets are never committed
Generated assets are bound to the Flutter that compiled them: what is in lib/spring_gen/flutter_scene_generated/ is never committed (its own .gitignore sees to it). See The engine's shaders.
A test has no GPU
A Scene cannot be made in a test, so in a widget test of the app the engine fails to start and the scene widgets are their placeholders. See Testing.