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:

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.

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.

See also