モデル
モデルは、プロパティでそのファイルとともに名前を付けます。スターターは、スプラッシュとともに、またはシーンが最初に表示するときに一度だけ読み込み、使うたびにクローンを作ります。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/
lib/resources/のファイルではありません。それらはアプリのコードに埋め込まれ、最大でも 1 メガバイトです。- アドレスは
httpsだけです。httpはspring.remote.allow-insecure: trueのときだけ読まれます。 - ブラウザーでは、サーバーがページのオリジンを許可する必要があります (CORS)。また、
require-corpの分離のもとでは、それ以外のものは別のオリジンから読み込まれません (シーンのコスト を参照)。 sourceのないモデルは、設定すべきキーspring.flutter.scene.models.<name>.sourceを示して失敗します。
アドレスにあるファイルは 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
- eager なモデル (
preload: eager) は、スプラッシュの表示中に読み込まれます。最初の画面は、それをすぐに持っています。 - lazy なモデルは、シーンが最初にそれを表示するときに読み込まれます。
- 設定されていなければ、モデルは
spring.flutter.scene.preloadに従います。そのデフォルトは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() がもう一度試します。
関連項目
- ウィジェットとしてのシーン
- イベントと言葉で表す起動: 読み込みのイベント
- デバッグタブ: すべてのモデルを名前で、そのコストとともに
- アセットとフォント
- HTTP トランスポート