
# A scene behind a widget

`SceneBackdrop` draws a 3D scene behind a widget: a frame of light around a panel, a glass under a card. The scene is as large as the child and `margin` pixels around it, and a pixel of the child is a pixel of the scene.

## Why

A scene behind a widget has to follow the widget's size, and its meshes have to meet the widget's edges. With the engine's view alone, that is a camera worked out by hand for every size. `SceneBackdrop` sets the camera and gives the scene the child's rectangle as a plane, so a mesh is laid out by the widget's own pixels.

## Example

```dart
SceneBackdrop(
  name: 'match-header',
  margin: 48,                              // light that reaches past the edge
  tilt: 0.7,                               // degrees, after the pointer
  placeholder: const PlainPanel(),
  scene: (context, surface) => [GlassPanel(surface), NeonEdge(surface)],
  child: const MatchHeader(),
)
```

`scene` builds the scene widgets for the child's rectangle. When the child's size changes, it is given a new surface.

## The surface

`surface` (`SceneSurface`) is the child's rectangle as a plane of the scene: 100 pixels to a unit, the origin in its middle, `+Y` up.

| Member | Meaning |
|---|---|
| `size` | The widget's size, in logical pixels |
| `pixelsPerUnit` | How many pixels a unit of the scene is: `100` |
| `width`, `height` | The size in the scene's units |
| `toScene(Offset(x, y))` | A point of the widget (pixels from its top-left corner) in the scene; `depth:` puts it that many units behind the widget's plane |
| `length(pixels)` | A length in pixels as a length of the scene |

A plate of the widget's own size, in the widget's colour:

```dart
import 'package:flutter/widgets.dart';
import 'package:flutter_scene/scene.dart';
import 'package:spring_boot_starter_flutter_scene/spring_boot_starter_flutter_scene.dart';
import 'package:vector_math/vector_math.dart' as vm;

class Plate extends StatefulWidget {
  const Plate(this.surface, {super.key, required this.color});

  final SceneSurface surface;
  final Color color;

  @override
  State<Plate> createState() => _PlateState();
}

class _PlateState extends State<Plate> {
  late Geometry _geometry = _build();
  // The engine's materials take linear light, the app's colours are sRGB.
  late final UnlitMaterial _material = UnlitMaterial()
    ..baseColorFactor = widget.color.linearWithAlpha;

  Geometry _build() => CuboidGeometry(
    vm.Vector3(widget.surface.width, widget.surface.height, 0.06),
  );

  @override
  void didUpdateWidget(Plate oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (oldWidget.surface != widget.surface) {
      _geometry = _build();
    }
  }

  @override
  Widget build(BuildContext context) => SceneMesh(
    geometry: _geometry,
    material: _material,
    position: vm.Vector3(0, 0, 0.03),
  );
}
```

```dart
const color = Color(0xFF1B2A44);

SceneBackdrop(
  name: 'plate-card',
  margin: 24,
  tilt: 4,
  padding: const EdgeInsets.all(20),
  placeholder: const ColoredBox(color: color),
  scene: (context, surface) => [Plate(surface, color: color)],
  child: const Text('The text over the plate is an ordinary widget.'),
)
```

## The parameters

| Parameter | Type | Default | Meaning |
|---|---|---|---|
| `child` | `Widget` | required | The widget in front |
| `scene` | `SceneBackdropBuilder` | required | The scene widgets behind it, for the child's `SceneSurface` |
| `name` | `String` | `'backdrop'` | What the scene is called in [the debug tab](debug-tab.md) |
| `placeholder` | `Widget?` | nothing | What stands behind the child until the scene draws, and for good where it cannot |
| `margin` | `double` | `0` | How far the scene reaches past the child's edge, in pixels |
| `padding` | `EdgeInsetsGeometry` | `EdgeInsets.zero` | Space between the child and the edge of the scene's rectangle |
| `maxFrameRate` | `double?` | the properties' | The most frames a second the scene draws, under `max-frame-rate` |
| `tilt` | `double` | `0` | How far the scene turns after the pointer, in degrees; `0` keeps it flat |
| `toneMapping` | `ToneMappingMode` | `ToneMappingMode.linear` | How colours are brought to the screen's range; `linear` keeps a colour of the theme as it is |

## What holds for it

`SceneBackdrop` is a `SpringSceneView.declarative` under the child, so everything of [Scenes as widgets](scenes.md) holds:

- where scenes do not draw, only `placeholder` and `child` are built;
- the ceiling on frames, the still frame and the pause off the screen come from the properties;
- with `tilt` the scene turns a little after the pointer over the child, and not at all when the system asks for less motion;
- the scene takes no pointer events: the child in front does.

## See also

- [Scenes as widgets](scenes.md)
- [Things of the engine to know](engine-notes.md): colours as linear light
- [Where scenes do not draw](without-scenes.md)
