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
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:
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),
);
}
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 |
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 holds:
- where scenes do not draw, only
placeholderandchildare built; - the ceiling on frames, the still frame and the pause off the screen come from the properties;
- with
tiltthe 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
- Things of the engine to know: colours as linear light
- Where scenes do not draw