
# エンジンのシェーダー

`flutter_scene` は、最初のフレームの前に、バンドルのすべてのシェーダーをコンパイルします。88 個のシェーダーで、ライティングのあるマテリアルとすべてのエフェクトを含みます。ブラウザーでは、これがページを 0.3 から 0.7 秒止め、初回の訪問では 3 秒を超えます。そのうちのいくつかだけで描画するアプリは、それらだけのバンドルを独自のフックで組み立てます。

## 使う理由

エンジンの起動は、スプラッシュやプレースホルダーとともにユーザーが待つステップです。そこでは、アプリが描画に使わないものも含めて、エンジンのすべてのシェーダーがコンパイルされます。アプリ自身のツリーにあるバンドルは、エンジンのバンドルの代わりになります。エンジンはアプリのツリーを先に読み、パッケージのコピーが優先されることはありません。そのため、バンドルを組み立てるのはスターターではなくアプリです。Dart はビルドフックを一つのパッケージのために実行し、そのパッケージの中にだけ書き込ませます。そして、シーンが何で描画するかを知っているのはアプリだけです。スターターには関数があり、アプリのフックはその呼び出しです。

## 例

```dart
// アプリの hook/build.dart
import 'package:hooks/hooks.dart';
import 'package:spring_boot_starter_flutter_scene/build_hooks.dart';

void main(List<String> args) async {
  await build(args, (input, output) async {
    await buildSceneAssets(buildInput: input, buildOutput: output);
  });
}
```

```yaml
# アプリの pubspec.yaml
dependencies:
  hooks: ^2.0.0
flutter:
  assets:
    - lib/spring_gen/flutter_scene_generated/
    - path: lib/spring_gen/flutter_scene_generated/opengl_es/
      platforms: [web]
```

## buildSceneAssets

一度の呼び出しで、アプリのシーンのうちビルド時に作られるものをすべて作ります。`shaders` に `null` を渡すと、アプリ独自のバンドルは作られず、エンジンのバンドル全体が使われます。`materials` (既定で `true`) は `sources` の下の `.fmat` マテリアルをコンパイルし ( `spring.flutter.scene.materials` のマテリアルがその中にないとビルドは失敗します。[マテリアル](materials.md) を参照)、`models` (既定で `true`) は `sources` の下の `.glb` と `.fscene` を変換します。`sources` の既定は `assets/` です。`buildSceneShaders` はバンドルだけを作ります。`materials` と `models` を切った同じ呼び出しです。

| パラメーター | 型 | デフォルト | 意味 |
|---|---|---|---|
| `buildInput` | `BuildInput` | 必須 | フックの入力 |
| `buildOutput` | `BuildOutputBuilder` | 必須 | フックの出力 |
| `shaders` | `Set<String>` | `unlitSceneShaders` | バンドルに入れる、エンジンのシェーダーの名前 |

これは独自のライブラリ `package:spring_boot_starter_flutter_scene/build_hooks.dart` にあります。Dart VM でだけ動く (ファイルを読み、SDK のシェーダーコンパイラーを実行する) ため、スターターのメインライブラリには含まれません。

## リスト

デフォルトのリスト (`unlitSceneShaders`。6 個のシェーダー) は、ライティングのないマテリアルと、ライティングのないカスタム (`.fmat`) マテリアルのシーンのためのものです。

| シェーダー |
|---|
| `UnskinnedVertex` |
| `UnlitFragment` |
| `FullscreenVertex` |
| `ResolveFragment` |
| `CopyFragment` |
| `PrefilterRadianceCubeFragment` |

ライティングのあるマテリアルを持つシーン (`.glb` モデルはそれを持ちます) は、必要なものを指定します。

```dart
await buildSceneAssets(
  buildInput: input,
  buildOutput: output,
  shaders: {...unlitSceneShaders, 'StandardFragment'},
);
```

または、フックを持たないことで、エンジンのバンドル全体を保ちます。フックがなくても、すべてが動きます。

- エンジンにない名前は、エンジンが持つシェーダーを示してビルドを失敗させます。
- バンドルにないシェーダーは、描画時に失敗し、エラーに名前はありません。リストを変えた後は、すべてのシーンを見てください。

## 生成されるアセット

フックが作るものは、上の `pubspec.yaml` が列挙するとおり、ほかの生成コードと同じ `lib/spring_gen/flutter_scene_generated/` に入ります。アプリのルートにそのためのフォルダーはできません。

`flutter_scene` 自身のフックは、アプリのルートにあるフォルダーに書き込み、別の場所を指定できません。そのため、スターターはそれらを `.dart_tool/spring_scene/` の下にあるアプリの代役に対して実行し、出力をコピーします。実行時には、エンジンはアセットをアドレスの末尾で見つけるので、フォルダーがどこにあってもかまいません。

生成されるアセットは、それをコンパイルした Flutter に結び付いているため、フォルダーの中身は決してコミットしません。ビルドがそこに書く二つの `.gitignore` ファイルが、ほかのすべてを無視します。この二つのファイル自体はコミットします。フォルダーを git に残すので、アセットのエントリーは、最初のビルドの前から存在するフォルダーを指します。`spring_gen/` 全体を無視するアプリは、このフォルダーだけを残します。

```
**/spring_gen/*
!**/spring_gen/flutter_scene_generated/
```

エントリーのない `pubspec.yaml` は、追加する行を示してビルドを止めます。

## 関連項目

- [イベントと言葉で表す起動](start.md): イベントとしてのエンジンの起動と、かかった時間
- [シーンのコスト](cost.md)
- [デバッグタブ](debug-tab.md): エンジンの起動の時間
