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:

See also