Scenes as widgets
SpringSceneView is a 3D scene among the app's widgets: the engine's SceneView with the app's properties applied, and a plain widget where scenes do not draw. SpringSceneView.declarative owns its scene, described by its children. const SpringSceneView() shows the application's scene.
Why
The engine gives a view that draws a scene. An app would write the same code around each one: start the engine, show something else meanwhile, check whether the device can draw at all, draw fewer frames. SpringSceneView does it once, from spring.flutter.scene.*.
Example
SpringSceneView.declarative(
name: 'showroom', // its name in the debug tab
placeholder: const ShowroomPicture(), // until it draws, or where it cannot
children: [
SpringSceneModel('hero'), // spring.flutter.scene.models.hero
SceneMesh(geometry: floor, material: concrete),
],
)
The children are scene widgets: the engine's (SceneNode, SceneMesh, SceneModel, lights) and the starter's SpringSceneModel (see Models). The view owns its scene and frees it with the widget.
What the starter does around the engine's view
Around the engine's SceneView the starter:
- starts the engine if nothing has, with the placeholder meanwhile;
- shows the scene once it is whole: its models loaded, and the engine asked to compile the programs of its materials beforehand (
warmUp, on by default), so no half-built scene is drawn. In a browser the first frame then built no program; on macOS the engine still reported programs built in the first frame; - draws at most
spring.flutter.scene.max-frame-rateframes a second (maxFrameRateon the widget asks for fewer;max-frame-rate: 0is as many as the screen shows), every moving scene on one beat: in a browser its frames (requestAnimationFrame), elsewhere a timer. The view does not tick with the display, so the page is drawn for the scenes' frames alone (see One beat for every scene); - draws one frame that stands with
render: still, while a condition ofspring.flutter.scene.whenasks for it, or when the system asks for less motion; - stops drawing when scrolled off the screen (
pause-off-screen); - in a browser, puts its frames on the canvas of
spring.flutter.scene.canvas: the page's, a layer of its own under the page, or the engine's own canvas (see The canvas in a browser); - while a condition of
spring.flutter.scene.whenis still finding out (slowmeasures the first scenes' frames), keeps a moving scene behind its placeholder, so it shows in the mode it keeps (see Drawing less where it costs too much); - builds only the placeholder, and nothing of the engine, where scenes do not draw (see Where scenes do not draw).
Without a placeholder the view is empty until it draws.
The parameters
Both constructors take:
| Parameter | Type | Default | Meaning |
|---|---|---|---|
name |
String |
'scene'; 'application' for SpringSceneView() |
What the view is called in the debug tab |
placeholder |
Widget? |
nothing | What stands in until the scene draws, and for good where it cannot |
camera |
Camera? |
none; for SpringSceneView() the camera of the properties |
The camera; at most one of camera and cameraBuilder |
cameraBuilder |
SceneCameraBuilder? |
none | The camera for each frame, by the time the scene has run |
maxFrameRate |
double? |
the properties' | The most frames a second this view draws, under max-frame-rate; 0 asks for no fewer than the properties let it |
pixelRatio |
double? |
the properties' pixel-ratio |
The view's own pixel ratio |
canvas |
SceneCanvas? |
the properties' canvas |
Which canvas the scene is on in a browser: SceneCanvas.page or SceneCanvas.layer, a canvas of its own under the page that each frame is handed over to. With canvas: engine in the properties every view is on the engine's canvas, whatever this says; elsewhere than in a browser Flutter draws the scene |
onTick |
SceneTickCallback? |
none | Called for each frame the view draws, with the time since the last |
loading |
ResourceGroup? |
none | Loads the view waits for before it shows, beside those of its own scene widgets (a SpringSceneModel is waited for without it) |
warmUp |
bool |
true |
Whether the engine is asked to compile the programs of the scene's materials before its first frame |
children |
List<Widget> |
none | The scene widgets |
SpringSceneView.declarative also takes what its own scene is lit and shown by:
| Parameter | Type | Default | Meaning |
|---|---|---|---|
environment |
EnvironmentMap? |
the engine's | The image the scene is lit by |
environmentIntensity |
double |
1.0 |
How strongly environment lights the scene |
exposure |
double |
1.0 |
The scene's exposure |
toneMapping |
ToneMappingMode |
ToneMappingMode.pbrNeutral |
How bright colours are brought to the screen's range |
Camera, EnvironmentMap, ResourceGroup and ToneMappingMode are the engine's types, of package:flutter_scene/scene.dart.
A still frame
With spring.flutter.scene.render: still, while a condition of spring.flutter.scene.when asks for still, or when the system asks for less motion, a view draws one frame and draws again only when what it shows changes.
- A still frame is drawn again when the view is rebuilt.
- A scene widget that changes what is drawn without a rebuild (a value set on a material in a callback) asks for a frame:
SpringSceneView.repaintOf(context). It does nothing in a view that moves anyway, or without a view above. SpringSceneView.reducedMotionOf(context)says whether the system asks for less motion.SpringSceneView.stillOf(context)says whether the view above stands still, for any of the three reasons. A scene widget that moves by the time draws its resting look then (a neon lit, not striking); the widget that asks is built again when it changes. Without a view above, it says whether the system asks for less motion.
void _recolor(BuildContext context, Color color) {
material.baseColorFactor = color.linearWithAlpha;
SpringSceneView.repaintOf(context); // a still frame shows the new colour
}
The application's scene in a view
const SpringSceneView()
This is a view of the applicationScene bean (spring.flutter.scene.app.enabled: true), seen through camera or the camera of the properties. Its children are added to that scene while the view shows. Without such a scene it is its placeholder. See The application's scene.