
# マテリアル

アプリ独自のマテリアルは `.fmat` ファイルです。ビルドフックがそれをコンパイルし、プロパティが名前を付け、`SpringSceneMesh` がシーンでそれを使って描画します。`SceneMaterials` Bean はそれをコードに渡します。

## 使う理由

エンジンは、コンパイル済みのマテリアルを、そのソースのパスで、独自の関数を使って読み込みます。スターターがなければ、どのアプリもパスを文字列としてコードに書き、それで描画するウィジェットごとに読み込みを待ち、シーンの時計に合わせてパラメーターを手で設定し、間違ったパスには画面上で初めて気づきます。ここでは、アプリがマテリアルに一度だけ名前を付け、スターターがそれを読み込み、時間を測り、どこで使われているかを伝え、何が間違っているかはビルドが伝えます。

## 例

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      materials:
        glass:
          source: assets/materials/glass.fmat
          preload: eager     # 未設定: spring.flutter.scene.preload と同じ
        neon:
          source: assets/materials/neon.fmat
```

```dart
SceneBackdrop(
  name: 'match-header',
  scene: (context, surface) => [
    SpringSceneMesh(
      material: 'glass',
      geometry: panel,
      parameters: (p) => p
        ..setColor('tint', tint)
        ..setFloat('strength', 0.2),
      everyFrame: (p, elapsed) =>
          p.setFloat('time', elapsed.inMicroseconds / 1e6),
    ),
  ],
  child: header,
)
```

## ファイル

`source` は、アプリのルートからの `.fmat` ファイルのパスで、`asset:` は付けません。ファイルそのものはアセットではなく、実行時には読まれません。アプリのビルドフック (`buildSceneAssets`。[エンジンのシェーダー](shaders.md) を参照) が、`assets/` の下のすべての `.fmat` ファイルを `lib/spring_gen/flutter_scene_generated/` にコンパイルし、読み込まれるのはコンパイル済みのマテリアルです。

プロパティのマテリアルが、コンパイルされたファイルの中にないとき、ビルドは失敗します。

```
Materials of the configuration that the build did not compile:
- spring.flutter.scene.materials.glass.source (lib/resources/application.yml) is assets/materials/glas.fmat
The .fmat files under assets/: assets/materials/glass.fmat, assets/materials/neon.fmat.
```

- すべてのアプリケーションファイルが確認されます。`lib/resources/application*.yml`、`.yaml`、`.properties`、プロファイルも含みます。
- プレースホルダー (`${...}`) で書かれたソースは、アプリの実行時にしか分からないため、確認されません。
- `asset:` を付けて書かれたソースは、その旨を添えて失敗します。
- `source` のないマテリアルは起動時に失敗し、設定すべきキー `spring.flutter.scene.materials.<name>.source` を示します。

## eager と lazy

- eager のマテリアル (`preload: eager`) は、スプラッシュの表示中に読み込まれ、最初の使用はそのとき作られたマテリアルを受け取ります。
- lazy のものは、シーンが最初にそれを表示するときに読み込まれます。
- 未設定のマテリアルは、`spring.flutter.scene.preload` に従います。既定は `lazy` です。

アプリの実行中に行われた最初の読み込みは、そのシーンの最初のフレームを遅らせます。ビューは読み込みを待つからです。[デバッグタブ](debug-tab.md) はそれにかかった時間を示し、そのとき 1 フレームより長くかかったマテリアルに印を付けます。そのマテリアルには `preload: eager` が向いています。この時間は読み込みの時間で (エンジンはコンパイル済みのプログラムを非同期に読みます)、ページのスレッドが止まる時間ではありません。

## シーンの中のマテリアル

`SpringSceneMesh` は、独自のマテリアルでそのジオメトリーを描画します。コンパイル済みのプログラムはそのマテリアルのすべてのメッシュで共有され、パラメーターはメッシュのものです。これはシーンのウィジェットで、`SpringSceneView` や `SceneBackdrop` (またはエンジン自身のシーンのウィジェット) の子に置きます。

| パラメーター | 型 | 意味 |
|---|---|---|
| `material` | `String` | `spring.flutter.scene.materials` でのマテリアルの名前 |
| `geometry` | `Geometry` | 描画するもの |
| `parameters` | `void Function(MaterialParameters)?` | ビルドごとにマテリアルのパラメーターを設定する |
| `everyFrame` | `void Function(MaterialParameters, Duration)?` | シーンの毎フレームに、シーンが動いた時間とともにパラメーターを設定する。ビルドはしない |
| `position`、`rotation`、`scale` | `Vector3?`、`Quaternion?`、`Vector3?` | 位置、向き、スケール |
| `visible` | `bool` | 描画するかどうか。既定は `true` |
| `components` | `List<Component>` | そのノードの振る舞い (エンジンの `Component`) |
| `children` | `List<Widget>` | そのノードの下のシーンのウィジェット |

- マテリアルがそろうまで、何も描画されません。シーンは、モデルと同じように、最初のフレームの前にそれを待つため、作りかけのシーンが表示されることはありません。
- 読み込みに失敗したマテリアルは描画されず、シーンの残りは描画されます。
- `everyFrame` は、マテリアルを動かす安価な方法です。そのフレームのパラメーターを書き込むだけで、何もビルドしません。

## コードの中のマテリアル

`SceneMaterials` (`sceneMaterials`) はマテリアルをコードに渡します。

| `SceneMaterials` のメンバー | 意味 |
|---|---|
| `materials['glass']` | マテリアルの `SceneMaterialHandle`。不明な名前は、存在する名前を示して失敗する |
| `names`、`all`、`eager` | 名前、すべてのマテリアル、スプラッシュとともに読み込まれるマテリアル |
| `contains(name)` | その名前のマテリアルがあるかどうか |

| `SceneMaterialHandle` のメンバー | 意味 |
|---|---|
| `create()` | 一つの使用のための新しいマテリアル。最初の呼び出しが一度だけ読み込み、まだ何もエンジンを起動していなければ起動する |
| `reload()` | 失敗の後にもう一度読み込む |
| `state` | `idle`、`loading`、`ready`、`failed` (`SceneMaterialState`) |
| `failure` | 失敗したとき、最初の読み込みが投げたもの |
| `took`、`loadedWithSplash` | 最初の読み込みにかかった時間と、それがスプラッシュとともにだったか、アプリの実行中だったか |
| `shading`、`opaque`、`parameters` | 照明の方式 (`unlit`、`lit` など)、ブレンドなしで描画されるかどうか、パラメーターの名前 |
| `uses`、`useCount` | いま画面上にある使用を、そのシーンの名前ごとに |
| `name`、`location`、`eager` | 名前、`.fmat` ファイル、スプラッシュとともに読み込まれるかどうか |

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

マテリアルは `sceneMaterialLoader` Bean、つまり `SceneMaterialLoader` が作ります。エンジンの `loadFmatMaterial` (`FmatMaterialLoader`) です。アプリ独自の Bean がその代わりになります。たとえばテストで。

## 精度: スマートフォンで描画が変わるもの

エンジンは、すべてのマテリアルのフラグメントコードを `precision mediump float;` で始めます。修飾子のない float は、それを守る GPU では半精度に、無視する GPU では float32 になります。

| どこで | `mediump` の float |
|---|---|
| デスクトップやノートパソコン (どのブラウザー、どの OS でも) | float32: 修飾子は無視される |
| スマートフォン: iPhone のすべてのブラウザー (Safari、Chrome、Telegram の中のもの)、Mali、Adreno | 半精度: 仮数 10 ビット、最大値 65504 |

そのため、ピクセル、秒、`sin` のハッシュで計算するマテリアルは、どのデスクトップでも正しく見え、スマートフォンでは崩れます。300 ピクセルの距離の二乗 (90000) は、すでに範囲の外です。ピクセルで測るネオンの光はシーン全体を覆う一つの光の塊になり、`fract(sin(x) * 43758.5453)` のノイズは縞になります。

フラグメントコードの最初の一行で、マテリアル全体が float32 で動きます。

```glsl
fragment {
  precision highp float;

  void Surface(inout MaterialInputs material) {
    vec2 p = GetUV0();
    // ピクセル、時間、ハッシュ: ここからは float32
  }
}
```

あるいは、必要な変数だけに `highp` を付ければ、残りは半精度のままです。

```glsl
highp vec2 p = GetUV0() * material_params.size;
highp float d = length(p - material_params.center);
```

| マテリアルが計算するもの | 精度 |
|---|---|
| 0 から 1 のテクスチャー座標、色、単位ベクトル | 既定のままでよい |
| ピクセル、画面の大きさ、それによる距離 | `highp` |
| 秒単位の時間 (際限なく増える) | `highp` |
| 大きな係数を掛けた `sin` のハッシュやノイズ | `highp` |

ビルドフックは各 `.fmat` ファイルを読んでそれを調べ、[デバッグタブ](debug-tab.md) が **Precision** に示します。`highp, float32 everywhere`、あるいは `mediump` と `highp` と書かれた箇所の数です。一つもない `mediump` は警告です。そのようなマテリアルがスマートフォンで正しいのは、小さな数だけで計算する場合に限られます。デスクトップでは違いは決して見えません。スマートフォンでマテリアルを確かめてください。

## マテリアルが失敗したとき

読み込みに失敗したマテリアルは、警告としてログに記録され、`SceneFailedEvent` (`SceneStep.material`) として発行されます。起動は続きます。失敗した eager のマテリアルは飛ばされ、そのメッシュは描画されません。ハンドルの `reload()` がもう一度試みます。

## 関連項目

- [エンジンのシェーダー](shaders.md): マテリアルをコンパイルするフック
- [モデル](models.md)
- [デバッグタブ](debug-tab.md): すべてのマテリアルを名前で、その使用、読み込み、精度とともに
- [イベントと言葉で表す起動](start.md)
