マテリアル

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

使う理由

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

例

# 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
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。エンジンのシェーダー を参照) が、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.

eager と lazy

アプリの実行中に行われた最初の読み込みは、そのシーンの最初のフレームを遅らせます。ビューは読み込みを待つからです。デバッグタブ はそれにかかった時間を示し、そのとき 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> そのノードの下のシーンのウィジェット

コードの中のマテリアル

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 で動きます。

fragment {
  precision highp float;

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

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

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

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

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

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

関連項目