
# ウィジェットとしてのシーン

`SpringSceneView` は、アプリのウィジェットの中の 3D シーンです。エンジンの `SceneView` にアプリのプロパティを適用したもので、シーンが描画されない場所では素のウィジェットになります。`SpringSceneView.declarative` は、子で記述された自分のシーンを持ちます。`const SpringSceneView()` は [アプリケーションのシーン](application-scene.md) を表示します。

## 使う理由

エンジンが与えるのは、シーンを描画するビューです。アプリは、ビューごとに同じコードをその周りに書くことになります。エンジンを起動する、その間は別のものを表示する、デバイスがそもそも描画できるかを調べる、フレームを減らす、といったコードです。`SpringSceneView` は、それを `spring.flutter.scene.*` から一度で行います。

## 例

```dart
SpringSceneView.declarative(
  name: 'showroom',                       // デバッグタブでの名前
  placeholder: const ShowroomPicture(),   // 描画されるまで、または描画できない場所で
  children: [
    SpringSceneModel('hero'),             // spring.flutter.scene.models.hero
    SceneMesh(geometry: floor, material: concrete),
  ],
)
```

子はシーンウィジェットです。エンジンのもの (`SceneNode`、`SceneMesh`、`SceneModel`、ライト) と、スターターの `SpringSceneModel` ([モデル](models.md) を参照) です。ビューは自分のシーンを持ち、ウィジェットとともに解放します。

## スターターがエンジンのビューの周りで行うこと

エンジンの `SceneView` の周りで、スターターは次のことを行います。

- まだ起動していなければエンジンを起動し、その間はプレースホルダーを表示します。
- シーンは、全体がそろってから表示します。モデルが読み込まれ、マテリアルのプログラムを前もってコンパイルするようエンジンに求めた後です (`warmUp`。デフォルトでオン)。そのため、作りかけのシーンが描画されることはありません。ブラウザーでは、そのとき最初のフレームでビルドされたプログラムはありませんでした。macOS では、エンジンは最初のフレームでビルドされたプログラムをなお報告しました。
- 一秒あたり最大で `spring.flutter.scene.max-frame-rate` フレームを描画します (ウィジェットの `maxFrameRate` は、それより少ないフレームを求めます。`max-frame-rate: 0` なら画面が表示するだけのフレームです)。動くシーンはすべて一つのビートで描かれます。ブラウザーではブラウザーのフレーム (`requestAnimationFrame`)、それ以外ではタイマーです。ビューはディスプレイの更新に合わせて動かないので、ページはシーンのフレームのためだけに描かれます ([すべてのシーンに一つのビート](speed.md#すべてのシーンに一つのビート) を参照)。
- `render: still` のとき、`spring.flutter.scene.when` の条件がそれを求めている間、またはシステムが動きを減らすよう求めているときは、静止した一つのフレームを描画します。
- スクロールで画面の外に出ると、描画を止めます (`pause-off-screen`)。
- ブラウザーでは、`spring.flutter.scene.canvas` のキャンバスにフレームを描きます。ページのキャンバス、ページの下にあるシーン専用のレイヤー、またはエンジン自身のキャンバスです ([ブラウザーでのキャンバス](speed.md#ブラウザーでのキャンバス) を参照)。
- `spring.flutter.scene.when` の条件がまだ調べている間 (`slow` は最初のシーンのフレームを計測します)、動くシーンをプレースホルダーの後ろに置いておきます。そのため、シーンは最初から最後まで同じモードで表示されます ([コストがかかりすぎる場所で描画を減らす](speed.md#コストがかかりすぎる場所で描画を減らす) を参照)。
- シーンが描画されない場所では、プレースホルダーだけを組み立て、エンジンのものは何も組み立てません ([シーンが描画されない場所](without-scenes.md) を参照)。

プレースホルダーがなければ、ビューは描画されるまで空です。

## パラメーター

どちらのコンストラクターも、次のものを受け取ります。

| パラメーター | 型 | デフォルト | 意味 |
|---|---|---|---|
| `name` | `String` | `'scene'`。`SpringSceneView()` では `'application'` | [デバッグタブ](debug-tab.md) でのビューの名前 |
| `placeholder` | `Widget?` | なし | シーンが描画されるまで、そして描画できない場所ではずっと、代わりに表示されるもの |
| `camera` | `Camera?` | なし。`SpringSceneView()` ではプロパティのカメラ | カメラ。`camera` と `cameraBuilder` はどちらか一つまで |
| `cameraBuilder` | `SceneCameraBuilder?` | なし | シーンが動いてきた時間に応じた、フレームごとのカメラ |
| `maxFrameRate` | `double?` | プロパティの値 | このビューが一秒あたりに描画する最大のフレーム数。`max-frame-rate` 以下。`0` はプロパティが許す数をそのまま求める |
| `pixelRatio` | `double?` | プロパティの `pixel-ratio` | ビュー独自のピクセル比 |
| `canvas` | `SceneCanvas?` | プロパティの `canvas` | ブラウザーでシーンが描かれるキャンバス。`SceneCanvas.page`、または `SceneCanvas.layer` (ページの下にあるシーン専用のキャンバスで、フレームが一枚ずつ受け渡される)。プロパティが `canvas: engine` なら、これが何であってもすべてのビューがエンジンのキャンバスに描かれる。ブラウザー以外では Flutter がシーンを描く |
| `onTick` | `SceneTickCallback?` | なし | ビューが描画するフレームごとに、前のフレームからの時間とともに呼ばれる |
| `loading` | `ResourceGroup?` | なし | ビューが表示の前に待つ読み込み。自分のシーンウィジェットの読み込みに加えて待つ (`SpringSceneModel` はこれがなくても待たれる) |
| `warmUp` | `bool` | `true` | シーンのマテリアルのプログラムを、最初のフレームの前にコンパイルするようエンジンに求めるかどうか |
| `children` | `List<Widget>` | なし | シーンウィジェット |

`SpringSceneView.declarative` は、自分のシーンを照らし、表示するためのものも受け取ります。

| パラメーター | 型 | デフォルト | 意味 |
|---|---|---|---|
| `environment` | `EnvironmentMap?` | エンジンのもの | シーンを照らす画像 |
| `environmentIntensity` | `double` | `1.0` | `environment` がシーンを照らす強さ |
| `exposure` | `double` | `1.0` | シーンの露出 |
| `toneMapping` | `ToneMappingMode` | `ToneMappingMode.pbrNeutral` | 明るい色を画面の範囲に収める方法 |

`Camera`、`EnvironmentMap`、`ResourceGroup`、`ToneMappingMode` はエンジンの型で、`package:flutter_scene/scene.dart` のものです。

## 静止フレーム

`spring.flutter.scene.render: still` のとき、`spring.flutter.scene.when` の条件が `still` を求めている間、またはシステムが動きを減らすよう求めているとき、ビューは一つのフレームを描画し、表示するものが変わったときだけ描画し直します。

- 静止フレームは、ビューが再構築されると描画し直されます。
- 再構築なしに描画内容を変えるシーンウィジェット (コールバックの中でマテリアルに値を設定する場合など) は、フレームを求めます: `SpringSceneView.repaintOf(context)`。もともと動いているビューでは、また上にビューがなければ、何もしません。
- `SpringSceneView.reducedMotionOf(context)` は、システムが動きを減らすよう求めているかどうかを返します。
- `SpringSceneView.stillOf(context)` は、上にあるビューが、この三つの理由のどれかで静止しているかどうかを返します。時間で動くシーンウィジェットは、そのとき静止した見た目を描きます (点滅するネオンではなく、点いたままのネオン)。これを尋ねたウィジェットは、値が変わると組み立て直されます。上にビューがなければ、システムが動きを減らすよう求めているかどうかを返します。

```dart
void _recolor(BuildContext context, Color color) {
  material.baseColorFactor = color.linearWithAlpha;
  SpringSceneView.repaintOf(context); // 静止フレームが新しい色を表示する
}
```

## ビューの中のアプリケーションのシーン

```dart
const SpringSceneView()
```

これは `applicationScene` Bean (`spring.flutter.scene.app.enabled: true`) のビューで、`camera` またはプロパティのカメラを通して見たものです。その `children` は、ビューが表示されている間、そのシーンに追加されます。そのようなシーンがなければ、プレースホルダーになります。[アプリケーションのシーン](application-scene.md) を参照してください。

## 関連項目

- [スマートフォンでの速さ](speed.md)
- [ウィジェットの背後のシーン](scene-backdrop.md)
- [シーンが描画されない場所](without-scenes.md)
- [シーンのコスト](cost.md)
- [すべてのプロパティ](properties.md)
