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

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

使う理由

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

Component は二つのクラス

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

// エンジンには独自の 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 不透明度を含む、リニアライトでの色
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 と同じフレームです。どちらの方法でもフレームを渡さないブラウザーでは何も描画されないため、起動はログの警告とともに失敗し、シーンはプレースホルダーになります (シーンが描画されない場所)。

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

一時停止は autoTick ではない

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

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

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

final clock = SceneClock();

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

フレームごとの値

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

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()),
    );
  }
}
SpringSceneModel('crate', components: [Spin(turnsPerSecond: 0.15)])

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

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

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

テストには GPU がない

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

関連項目