
# spring_boot_starter_flutter_scene

`spring_boot_starter_flutter_scene` は、[spring_boot_starter_flutter](../spring-boot-starter-flutter/index.md) の上に作られた Flutter アプリに 3D シーンを追加します。エンジンはパッケージ `flutter_scene` です。ブラウザーでは WebGL2、それ以外では Impeller を使います。シーンは、アプリのウィジェットの中の一つのウィジェットです。エンジンがいつ起動するか、何が読み込まれるか、シーンが何フレーム描画するかは `spring.flutter.scene.*` から決まります。

## 使う理由

エンジンが与えるのは、シーンを描画するビューです。アプリには、その周りにさらに必要なものがあります。エンジンの一度きりの起動、デバイスが描画できない場所で表示するもの、フレームの制限、モデルの読み込み、そしてシーンのコストを示す数値です。スターターはこれを設定から行います。

- **ウィジェットであるシーン**: アプリのウィジェットの中の `SpringSceneView` と、ウィジェットの背後の `SceneBackdrop`。シーンが描画されない場所 (オフにした場合、WebGL2 がない場合、エンジンが失敗した場合) では、プレースホルダーを表示する素のウィジェットになります。アプリのコードに、そのための分岐はありません。
- **プロパティから決まるシーンのコスト**: フレームの上限、静止フレーム、画面外での一時停止、シーン独自のピクセル比。
- **エンジンの一度きりの起動**: スプラッシュとともに、または最初のシーンが表示されるときに。スプラッシュは eager なものを待ちます。
- **プロパティからのモデル**: `spring.flutter.scene.models.<name>`。一度だけ読み込まれ、使うたびにクローンされます。
- **プロパティからのマテリアル**: `spring.flutter.scene.materials.<name>`。ビルドフックがコンパイルする `.fmat` ファイルで、`SpringSceneMesh` がそれで描画します。コンパイルされていないものがあるとビルドは失敗します。
- **アプリケーションのシーン**: アプリ全体のための一つのシーン。すべての画面の下にあります。
- **イベントと言葉で表す起動**: いま何が読み込まれているか。ローダーが言葉で伝えられます。
- **デバッグパネルのタブ**: すべてのシーンとモデルを名前で、そのコストとともに。

## セットアップ

```yaml
# pubspec.yaml
environment:
  sdk: ^3.14.0
  flutter: '>=3.50.0'

dependencies:
  flutter:
    sdk: flutter
  spring_boot_starter_flutter_scene: ^0.9.0
  # エンジン自身のシーンウィジェットとジオメトリ (SceneNode、SceneMesh、
  # マテリアル)。アプリのコードがそれらの名前を使う場合。
  flutter_scene: ^0.24.3

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
```

スターターは `spring_boot_starter_flutter` を連れてきて再エクスポートします。アプリは代わりにこのパッケージを列挙します。エンジンは再エクスポートしません。エンジンのシーンウィジェットの名前をコードで使うアプリは `flutter_scene` も列挙し、自分で書くベクトルのために `vector_math` も列挙します。

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

Flutter のスターターと同じく、Flutter 3.50 以降 (Dart 3.14) が必要です。`flutter_scene` は、アプリのビルド時に SDK のシェーダーコンパイラーでシェーダーをコンパイルします。その後 `dart run build_runner build` を実行します。ジェネレーターがスターターを見つけ、その Bean を `lib/spring_gen/main.spring.dart` に追加します。

ブラウザーでは、これ以上必要なものはありません。それ以外のすべてのプラットフォームでは、プラットフォーム自身のファイルの中の一行で、Flutter GPU を一度オンにします。[ネイティブプラットフォーム](native-platforms.md) を参照してください。それがなければ、そこではエンジンが起動せず、シーンはプレースホルダーになります。

## 例

プロパティで名前を付けたモデルを独自のシーンに表示し、いま何が読み込まれているかを一行で伝えます。

```properties
# lib/resources/application.properties
spring.flutter.app.title=Showroom
spring.flutter.scene.max-frame-rate=30
spring.flutter.scene.models.hero.source=asset:assets/models/hero.glb
```

```yaml
# lib/resources/application.yml での同じ内容
spring:
  flutter:
    app:
      title: Showroom
    scene:
      max-frame-rate: 30
      models:
        hero:
          source: asset:assets/models/hero.glb
```

```yaml
# pubspec.yaml: モデルのファイルはアプリのアセット
flutter:
  assets:
    - assets/models/
```

```dart
// lib/main.dart
import 'package:flutter/widgets.dart';
import 'package:spring_boot_starter_flutter_scene/spring_boot_starter_flutter_scene.dart';

import 'spring_gen/main.spring.dart';

@SpringBootApplication()
void main() => runApp(
  SpringApplicationWidget(
    application: () => springApplication,
    home: const Showroom(),
  ),
);

class Showroom extends StatelessWidget {
  const Showroom({super.key});

  @override
  Widget build(BuildContext context) {
    // spring.flutter.scene.enabled=false でアプリが動くときは Bean がない:
    // 下のシーンはプレースホルダーになり、ステータスもない。
    final status = context.springContext
        .getBeanProvider<SceneStatus>()
        .getIfAvailable();
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        const SizedBox(
          width: 320,
          height: 320,
          // 自分のシーンを持つビュー。シーンが描画されない場所では、
          // プレースホルダーだけが組み立てられる。
          child: SpringSceneView.declarative(
            name: 'showroom',
            placeholder: Center(child: Text('hero')),
            // spring.flutter.scene.models.hero: 一度だけ読み込まれ、ここではクローン。
            children: [SpringSceneModel('hero')],
          ),
        ),
        if (status != null)
          ValueListenableBuilder(
            valueListenable: status,
            // "Compiling shaders"、"Loading hero, 1 of 1"、その後は何もなし。
            builder: (context, step, _) => Text(status.text ?? ''),
          ),
      ],
    );
  }
}

// シーンの起動の各ステップはアプリケーションイベント。
@Service()
class LoadedModels {
  final List<String> names = [];

  @EventListener()
  void onLoaded(SceneModelLoadedEvent event) => names.add(event.name);
}
```

## 実行する

```bash
dart run build_runner build   # スターターの Bean を main.spring.dart に追加する
flutter run -d chrome
```

- 最初に表示されるシーンがエンジンを起動し、その間はプレースホルダーが表示されます。モデル `hero` は、シーンが最初にそれを表示するときに一度だけ読み込まれます。
- シーンは、全体がそろってから表示されます。モデルが読み込まれ、マテリアルのプログラムを前もってコンパイルするようエンジンに求めた後です。
- シーンが描画されない場所 (`spring.flutter.scene.enabled=false`、WebGL2 のないブラウザー) では、同じアプリがプレースホルダーを表示し、ステータスは表示しません。コードに、そのための分岐はありません。
- デバッグビルドでは、デバッグパネル (⌘⇧D、それ以外では Ctrl+Shift+D) に "Scenes" タブがあり、シーンとモデルを名前で示します。

## 内容

- [ネイティブプラットフォーム](native-platforms.md): iOS、macOS、Android、Linux、Windows でオンにする Flutter GPU。
- [ウィジェットとしてのシーン](scenes.md): `SpringSceneView`、スターターがエンジンのビューの周りで行うこと、静止フレーム。
- [ウィジェットの背後のシーン](scene-backdrop.md): `SceneBackdrop` と `SceneSurface`。
- [シーンが描画されない場所](without-scenes.md): オフにしたシーン、WebGL2 がない場合、失敗した起動。存在しないかもしれない Bean。
- [モデル](models.md): `spring.flutter.scene.models.*`、`SpringSceneModel`、`SceneModels`。
- [アプリケーションのシーン](application-scene.md): すべての画面の下の一つのシーン、`SceneCustomizer`。
- [イベントと言葉で表す起動](start.md): `SceneEvent`、`SceneStatus`、スプラッシュが待つもの。
- [シーンのコスト](cost.md): 計測結果と、役に立つもの。
- [エンジンのシェーダー](shaders.md): アプリのフックで組み立てる、アプリ独自のシェーダーバンドル。
- [デバッグタブ](debug-tab.md): すべてのシーンとモデルを名前で。
- [エンジンのログ](engine-log.md): アプリケーションのログの中のエンジンのメッセージ。
- [エンジンについて知っておくこと](engine-notes.md): `Component`、リニアライトの色、フレームごとの値。
- [テスト](testing.md): GPU のない、ウィジェットテストでのシーン。
- [すべてのプロパティ](properties.md): スターターのすべてのキー。

## Spring (Java) との対応

Spring には 3D シーンも、このスターターに相当するものもありません。形は Spring のものです。依存関係にあることで機能を追加するスターター、その Bean を持つ自動構成、カスタマイザーの Bean (`SceneCustomizer`。Spring Boot の `WebServerFactoryCustomizer` と同じ形)、起動のステップのためのアプリケーションイベント、そして存在しないかもしれない Bean のための `ObjectProvider` です。

## 関連項目

- [spring_boot_starter_flutter](../spring-boot-starter-flutter/index.md)
- [スプラッシュと起動](../spring-boot-starter-flutter/splash.md)
- [デバッグパネル](../spring-boot-starter-flutter/debug-panel.md)
- [すべてのプロパティ](properties.md)
- [ビルドに含まれるもの](optimizations.md)
