モデル

モデルは、プロパティでそのファイルとともに名前を付けます。スターターは、スプラッシュとともに、またはシーンが最初に表示するときに一度だけ読み込み、使うたびにクローンを作ります。SpringSceneModel はそれをシーンに表示し、SceneModels Bean はそれをコードに渡します。

使う理由

モデルの読み込みは、どのアプリも繰り返し書くコードです。ファイルを読み、インポートし、結果を保持し、その間は何かを表示し、失敗を処理します。そして、三か所で使うモデルは、一度だけ読み、一度だけ GPU に送るべきです。ここでは、アプリがモデルに名前を付け、残りはスターターが行います。

例

# lib/resources/application.yml
spring:
  flutter:
    scene:
      models:
        hero:
          source: asset:assets/models/hero.glb
          preload: eager     # 未設定: spring.flutter.scene.preload と同じ
SpringSceneView.declarative(
  children: [
    SpringSceneModel('hero', position: Vector3(0, 1, 0)),
  ],
)

ファイル

source は、モデルのファイルの場所を示します。ファイルはバイナリー glTF (.glb) です。

ソース 例 読み方
アプリのアセット asset:assets/models/hero.glb アプリのアセットから。ファイルは pubspec.yaml の flutter: assets: の下に列挙する
アドレス https://cdn.example.com/hero.glb アプリの HttpTransport Bean (なければプラットフォームのクライアント) を通じた一度の GET で。ブラウザーでも同じ
# pubspec.yaml
flutter:
  assets:
    - assets/models/

アドレスにあるファイルは RemoteModelResource です。サーバーへの問い合わせは、モデルが読み込まれるときだけ行われます。成功でない応答は、アドレスとステータスを示して読み込みを失敗させます。

別の形式は、アプリの SceneModelImporter Bean です。スターターのもの (GlbModelImporter、Bean sceneModelImporter) の代わりになります。

abstract interface class SceneModelImporter {
  /// The template of model [name] from the [bytes] of its file.
  Future<Node> import(Uint8List bytes, {required String name});
}

eager と lazy

どちらの場合も、一度だけ読み込まれて保持されます。画面から消えて戻ってきたモデルが、もう一度インポートされることはありません。

シーンの中のモデル

SpringSceneModel('hero') は、モデルをシーンに表示します。テンプレートのクローンなので、使うたびに独自の変換とアニメーションを持ち、ジオメトリ、テクスチャ、マテリアルは GPU 上で共有されたままです。これはシーンウィジェットです。SpringSceneView (またはエンジン自身のシーンウィジェット) の子の中に置き、通常のウィジェットの中には置きません。

パラメーター 型 意味
name (位置引数) String spring.flutter.scene.models でのモデルの名前
variant String? モデルのマテリアルバリアント (KHR_materials_variants)
animations List<SceneAnimationSpec> どのアニメーションを、どのように再生するか
placeholder WidgetBuilder? 読み込み中に、その場所に置くシーンウィジェット
error Widget Function(BuildContext, Object)? 読み込みに失敗したときに、その場所に置くシーンウィジェット
onLoaded void Function(Node)? クローンがシーンに入ったときに、クローンとともに呼ばれる
position、rotation、scale Vector3?、Quaternion?、Vector3? 位置、向き、スケール
visible bool 描画されるかどうか。デフォルトは true
components List<Component> そのノードの振る舞い (エンジンの Component)
children List<Widget> そのノードの下のシーンウィジェット

ビューは、表示の前に自分の SpringSceneModel ウィジェットを待ちます。そのため、作りかけのシーンが描画されることはありません。

コードの中のモデル

SceneModels (sceneModels) は、モデルをコードに渡します。

@Component()
class Showroom {
  Showroom(this.models);

  final ObjectProvider<SceneModels> models;

  // シーンをオフにしてアプリが動くときは Bean がない。
  Future<void> open() async => models.getIfAvailable()?['hero'].load();
}
SceneModels のメンバー 意味
models['hero'] モデルの SceneModelHandle。未知の名前は、存在する名前を示して失敗する
names、all、eager 名前、すべてのモデル、スプラッシュとともに読み込まれるモデル
contains(name) その名前のモデルがあるかどうか
SceneModelHandle のメンバー 意味
load() モデルを一度だけ読み込む。どの呼び出しも同じ読み込みを返す。まだ起動していなければエンジンを起動する
reload() 失敗の後に、もう一度読み込む
state idle、loading、ready、failed (SceneModelState)
template 読み込まれたノードツリー。使うたびにクローンされる。state が ready になるまでは null
failure 読み込みが失敗したときに投げられたもの
name、location、eager 名前、プロパティが示すファイルの場所、スプラッシュとともに読み込まれるかどうか
bytes、readTook、importTook ファイルの大きさ、読む (アドレスならダウンロードする) のにかかった時間、インポートにかかった時間

ハンドルは ChangeNotifier です。state が変わるとリスナーに通知します。

モデルが失敗したとき

読み込みに失敗したモデルは、警告としてログに出て、SceneFailedEvent として発行されます。起動は続きます。失敗した eager なモデルは飛ばされ、そのシーンはプレースホルダーを表示します。ハンドルの reload() がもう一度試します。

関連項目