
# エンジンについて知っておくこと

スターターは `flutter_scene` の上に作られており、アプリのシーンは、エンジン自身のウィジェット、マテリアル、コンポーネントで書きます。エンジンについてのいくつかのことに、アプリは早い段階で出会います。このページは、それらを列挙します。

## 使う理由

どれも、エラーメッセージが自分で説明してくれるものではありません。二つのクラスである名前、淡くなる色、表示されないグロー、再び動くときに失敗するビューです。それぞれに短い答えがあります。

## Component は二つのクラス

エンジンの `Component` (ノードの振る舞い) と Spring の `@Component()` は、両方をインポートするファイルでぶつかります。Bean のファイルは、エンジンから使うものだけを取り込むか、その名前を隠します。

```dart
// エンジンには独自の Component クラスがある: ここで使うものだけを取り込む。
import 'package:flutter_scene/scene.dart' show Scene;
import 'package:spring_boot_starter_flutter_scene/spring_boot_starter_flutter_scene.dart';

@Component()
class Stage implements SceneCustomizer {
  // ...
}
```

エンジンの多くを使うファイルでは、`import 'package:flutter_scene/scene.dart' hide Component;` が同じ働きをします。

## 色はリニアライト

アプリの `Color` は、テーマが持つとおりの sRGB です。エンジンのマテリアルはリニアライトを受け取ります。そのまま渡すと、色は淡くなります。`Color` の拡張である `SceneColor` が、両方の形を与えます。

| メンバー | 型 | 意味 |
|---|---|---|
| `color.linear` | `Vector3` | リニアライトでの色: 赤、緑、青 |
| `color.linearWithAlpha` | `Vector4` | 不透明度を含む、リニアライトでの色 |

```dart
final material = UnlitMaterial()
  ..baseColorFactor = color.linearWithAlpha;
```

## 加算マテリアルはアルファを残さない

加算マテリアルはアルファを残さないため、その光はシーン自身のサーフェスの外には表示されません。ページの上のグローは、明るさをアルファとしたアルファブレンディングです。

## Safari: WebGL のフレームとそのアルファ

エンジンは、各フレームを WebGL のキャンバスのビットマップ (`transferToImageBitmap`) として Flutter に渡し、Flutter のレンダラーはそのビットマップを乗算済みとして受け取ります。WebGL のビットマップがどちらになるかは、標準がブラウザーに任せています。

| ブラウザー | WebGL のキャンバスのビットマップ | スターターがなければ |
|---|---|---|
| Chrome、Edge、Firefox | 乗算済み | 正しい |
| WebKit: Safari と、iPhone のすべてのブラウザー (Chrome、Telegram の中のもの) | 色がアルファで割られる | 半透明の光が一つの塊の単色になる |

スターターは、エンジンが起動する前に、エンジンと同じ方法で一つのピクセルを渡し、このブラウザーがどちらなのかを見ます。WebKit では、エンジンのキャンバスを乗算済みアルファなしで求めるので、バイトはそのまま Flutter に届きます。Chrome と同じフレームです。どちらの方法でもフレームを渡さないブラウザーでは何も描画されないため、起動はログの警告とともに失敗し、シーンはプレースホルダーになります ([シーンが描画されない場所](without-scenes.md))。

アプリに求めることはありません。[デバッグタブ](debug-tab.md) が、フレームがどちらの方法で渡るかを示します (エンジンの下の **Frames**)。デスクトップの Safari は iPhone と同じものを表示します。そこで誤って描画されるものは、スマートフォンなしで分かります。精度の違いは分かりません ([精度](materials.md#精度-スマートフォンで描画が変わるもの))。

## 一時停止は autoTick ではない

エンジン自身のビューは、`autoTick` が `false` から `true` に戻ると、デバッグビルドで失敗します。二つ目のティッカーを作り、Flutter がそれを拒否するからです。

スターターのビュー (`SpringSceneView`、`SceneBackdrop`) は、エンジンのビューを `autoTick: false` で作り、それを変えることはありません。フレームは、すべてのシーンに共通の一つのビートから受け取ります ([すべてのシーンに一つのビート](speed.md#すべてのシーンに一つのビート) を参照)。一時停止は、ビートから抜け、シーンのクロックを止める (`SceneClock`) ことで行います。そのため、動きを減らす設定や画面の外から戻ったシーンは、飛ぶことなく戻ります。止まっていた時間の分ではなく、一フレーム分だけ進みます。

アプリ独自の `SceneView` も、`autoTick` ではなく、同じ方法で一時停止するべきです。

```dart
final clock = SceneClock();

Widget build(BuildContext context) {
  clock.paused = paused;
  return TickerMode(
    enabled: !paused,
    child: SceneView(scene, clock: clock.clock),
  );
}
```

## フレームごとの値

フレームごとの値は、ウィジェットの再構築ではなく、コンポーネントやシーンのクロック (`SceneScope.of(context).elapsed`) のリスナーが、マテリアルやノードに設定します。エンジンのコンポーネントはシーン自身のクロックで動くので、フレームのためにウィジェットが再構築されることはありません。

```dart
import 'package:flutter_scene/scene.dart';
import 'package:vector_math/vector_math.dart';

/// Turns its node about the vertical axis.
class Spin extends Component {
  Spin({this.turnsPerSecond = 0.1, Vector3? axis})
    : axis = axis ?? Vector3(0, 1, 0);

  final double turnsPerSecond;
  final Vector3 axis;

  double _angle = 0;

  @override
  void update(double deltaSeconds) {
    _angle += deltaSeconds * turnsPerSecond * 6.283185307179586;
    node.localTransform = Matrix4.compose(
      node.localTransform.getTranslation(),
      Quaternion.axisAngle(axis, _angle),
      Vector3.all(node.localTransform.getMaxScaleOnAxis()),
    );
  }
}
```

```dart
SpringSceneModel('crate', components: [Spin(turnsPerSecond: 0.15)])
```

静止しているビュー (`render: still`) では、再構築なしに設定した値は `SpringSceneView.repaintOf(context)` でフレームを求めます ([ウィジェットとしてのシーン](scenes.md#静止フレーム) を参照)。

## 生成されるアセットは決してコミットしない

生成されるアセットは、それをコンパイルした Flutter に結び付いています。`lib/spring_gen/flutter_scene_generated/` の中身は決してコミットしません (そのフォルダー自身の `.gitignore` がそうします)。[エンジンのシェーダー](shaders.md) を参照してください。

## テストには GPU がない

テストでは `Scene` を作れません。そのため、アプリのウィジェットテストではエンジンの起動が失敗し、シーンのウィジェットはプレースホルダーになります。[テスト](testing.md) を参照してください。

## 関連項目

- [ウィジェットとしてのシーン](scenes.md)
- [ウィジェットの背後のシーン](scene-backdrop.md)
- [@Component](../spring-core-dart/beans/component.md)
