
# ウィジェットの背後のシーン

`SceneBackdrop` は、ウィジェットの背後に 3D シーンを描画します。パネルの周りの光の枠や、カードの下のガラスなどです。シーンの大きさは、子とその周りの `margin` ピクセルで、子の 1 ピクセルはシーンの 1 ピクセルです。

## 使う理由

ウィジェットの背後のシーンは、ウィジェットの大きさに従う必要があり、そのメッシュはウィジェットの端に合う必要があります。エンジンのビューだけでは、大きさごとにカメラを手で計算することになります。`SceneBackdrop` はカメラを設定し、子の矩形を平面としてシーンに与えるので、メッシュはウィジェット自身のピクセルで配置されます。

## 例

```dart
SceneBackdrop(
  name: 'match-header',
  margin: 48,                              // 端の外まで届く光
  tilt: 0.7,                               // 度。ポインターを追う
  placeholder: const PlainPanel(),
  scene: (context, surface) => [GlassPanel(surface), NeonEdge(surface)],
  child: const MatchHeader(),
)
```

`scene` は、子の矩形のためのシーンウィジェットを組み立てます。子の大きさが変わると、新しいサーフェスが渡されます。

## サーフェス

`surface` (`SceneSurface`) は、子の矩形をシーンの平面として表したものです。100 ピクセルが 1 単位で、原点はその中央、`+Y` が上です。

| メンバー | 意味 |
|---|---|
| `size` | ウィジェットの大きさ。論理ピクセル |
| `pixelsPerUnit` | シーンの 1 単位が何ピクセルか: `100` |
| `width`、`height` | シーンの単位での大きさ |
| `toScene(Offset(x, y))` | ウィジェットの点 (左上の角からのピクセル) のシーンでの位置。`depth:` は、その単位数だけウィジェットの平面の奥に置く |
| `length(pixels)` | ピクセルの長さを、シーンの長さとして |

ウィジェットと同じ大きさで、ウィジェットの色の板です。

```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();
  // エンジンのマテリアルはリニアライトを受け取る。アプリの色は 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.'),
)
```

## パラメーター

| パラメーター | 型 | デフォルト | 意味 |
|---|---|---|---|
| `child` | `Widget` | 必須 | 前面のウィジェット |
| `scene` | `SceneBackdropBuilder` | 必須 | その背後のシーンウィジェット。子の `SceneSurface` のために組み立てる |
| `name` | `String` | `'backdrop'` | [デバッグタブ](debug-tab.md) でのシーンの名前 |
| `placeholder` | `Widget?` | なし | シーンが描画されるまで、そして描画できない場所ではずっと、子の背後に表示されるもの |
| `margin` | `double` | `0` | シーンが子の端の外にどこまで届くか。ピクセル |
| `padding` | `EdgeInsetsGeometry` | `EdgeInsets.zero` | 子とシーンの矩形の端との間の余白 |
| `maxFrameRate` | `double?` | プロパティの値 | シーンが一秒あたりに描画する最大のフレーム数。`max-frame-rate` 以下 |
| `tilt` | `double` | `0` | シーンがポインターを追ってどこまで傾くか。度。`0` は平らなまま |
| `toneMapping` | `ToneMappingMode` | `ToneMappingMode.linear` | 色を画面の範囲に収める方法。`linear` はテーマの色をそのまま保つ |

## 当てはまること

`SceneBackdrop` は、子の下の `SpringSceneView.declarative` です。そのため、[ウィジェットとしてのシーン](scenes.md) のすべてが当てはまります。

- シーンが描画されない場所では、`placeholder` と `child` だけが組み立てられます。
- フレームの上限、静止フレーム、画面外での一時停止は、プロパティから決まります。
- `tilt` があると、シーンは子の上のポインターを追って少し傾きます。システムが動きを減らすよう求めているときは、まったく傾きません。
- シーンはポインターイベントを受け取りません。前面の子が受け取ります。

## 関連項目

- [ウィジェットとしてのシーン](scenes.md)
- [エンジンについて知っておくこと](engine-notes.md): リニアライトとしての色
- [シーンが描画されない場所](without-scenes.md)
