
# 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](application-scene.md).

## 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

```dart
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](models.md)). 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-rate` frames a second (`maxFrameRate` on the widget asks for fewer; `max-frame-rate: 0` is 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](speed.md#one-beat-for-every-scene));
- draws one frame that stands with `render: still`, while a condition of `spring.flutter.scene.when` asks 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](speed.md#the-canvas-in-a-browser));
- while a condition of `spring.flutter.scene.when` is still finding out (`slow` measures 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](speed.md#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-scenes.md)).

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](debug-tab.md) |
| `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.

```dart
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

```dart
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](application-scene.md).

## See also

- [Speed on phones](speed.md)
- [A scene behind a widget](scene-backdrop.md)
- [Where scenes do not draw](without-scenes.md)
- [What a scene costs](cost.md)
- [All properties](properties.md)
