filament

Filament

Filamentは、Android、iOS、Linux、macOS、Windows、WASM向けのリアルタイム物理ベースレンダリングエンジンです。できる限り小さく、Android上でできる限り効率的に動作するよう設計されています。

ダウンロード

Filamentのリリースをダウンロードして、安定版ビルドを入手してください。 Filamentのリリースアーカイブには、アセットの生成に必要なホスト側ツールが含まれています。

ランタイムライブラリと同じリリースのツールを必ず使用してください。これは特にmatc（マテリアルコンパイラー）で重要です。

Filamentを自分でビルドする場合は、ビルドマニュアルを参照してください。

Android

Androidプロジェクトでは、FilamentライブラリをMaven依存関係として宣言するだけで使用できます。

repositories {
    // ...
    mavenCentral()
}

dependencies {
    implementation 'com.google.android.filament:filament-android:1.79.0'
}

com.google.android.filamentグループで利用できるすべてのライブラリは以下のとおりです。

アーティファクト	説明
	Filamentレンダリングエンジン本体です。
	filament-androidのデバッグ版です。
	Filament用のglTF 2.0ローダーです。filament-androidに依存します。
	KTX読み込み、Kotlinの数学機能、カメラユーティリティを提供します。gltfio-androidに依存します。
	ランタイム用のマテリアルビルダー／コンパイラーです。このライブラリはサイズが大きいものの、完全なシェーダーコンパイラー／バリデーター／オプティマイザーを含み、OpenGLとVulkanの両方をサポートします。

iOS

iOSプロジェクトでは、CocoaPodsを使用して最新リリースをインストールできます。

pod 'Filament', '~> 1.79.0'

ドキュメント

• Filament：リアルタイムの物理ベースレンダリング、Filament のグラフィックス機能および実装について詳しく説明しています。 このドキュメントでは、私たちの決定のほとんどを支える数学的な根拠と考え方を説明しています。グラフィックスプログラマーが PBR を学ぶための優れた入門書です。
• Materials：マテリアルシステムの完全なリファレンスドキュメントです。このドキュメントでは、さまざまなマテリアルモデル、マテリアルコンパイラー matc の使用方法、カスタムマテリアルの作成方法を説明しています。
• Material Properties：標準マテリアルモデルのリファレンスシートです。

サンプル

機能

API

• Android、iOS、Linux、macOS、Windows 向けのネイティブ C++ API
• Android 向けの Java/JNI API
• JavaScript API

バックエンド

• Linux、macOS、Windows 向けの OpenGL 4.1 以降
• Android、iOS 向けの OpenGL ES 3.0 以降
• macOS、iOS 向けの Metal
• Android、Linux、macOS、Windows 向けの Vulkan 1.0
• Android、Linux、macOS、Windows 向けの WebGPU
• 対応するすべてのブラウザー向けの WebGL 2.0

レンダリング

• クラスタ化フォワードレンダラー
• Cook-Torrance マイクロファセット鏡面反射 BRDF
• Lambertian 拡散反射 BRDF
• カスタムライティング／サーフェスシェーディング
• HDR／リニアライティング
• メタリックワークフロー
• クリアコート
• 異方性ライティング
• 近似的な半透明（サブサーフェス）マテリアル
• 布／ファブリック／シーンシェーディング
• 法線マッピングとアンビエントオクルージョンマッピング
• イメージベースドライティング
• 物理ベースのカメラ（シャッタースピード、感度、絞り）
• 物理的な光の単位
• ポイントライト、スポットライト、ディレクショナルライト
• 鏡面反射アンチエイリアシング
• ポイントライト、スポットライト、ディレクショナルライトのシャドウ
• カスケードシャドウ
• EVSM、PCSS、DPCF、または PCF シャドウ
• 色付きペナンブラ
• 透明シャドウ
• コンタクトシャドウ
• スクリーンスペースアンビエントオクルージョン
• スクリーンスペース反射
• スクリーンスペース屈折
• グローバルフォグ
• AMD FidelityFX FSR に対応した動的解像度

ポストプロセス

• HDR ブルーム
• 被写界深度ボケ
• 複数のトーンマッパー：GT7、PBR Neutral、AgX、汎用（カスタマイズ可能）、ACES、フィルミックなど
• カラーおよびトーン管理：輝度スケーリング、色域マッピング
• カラーグレーディング：露出、夜間適応、ホワイトバランス、チャンネルミキサー、 シャドウ／中間調／ハイライト、ASC CDL、コントラスト、彩度など
• TAA、FXAA、MSAA
• スクリーンスペースレンズフレア

glTF 2.0

• エンコーディング

  • 埋め込み
  • バイナリ

• プリミティブ型

  • 点
  • 線
  • ラインループ
  • ラインストリップ
  • 三角形
  • トライアングルストリップ
  • トライアングルファン

• アニメーション

  • トランスフォームアニメーション
  • 線形補間
  • モーフアニメーション
    • スパースアクセサー
  • スキンアニメーション
  • ジョイントアニメーション

• 拡張機能

  • KHR_draco_mesh_compression
  • KHR_lights_punctual
  • KHR_materials_clearcoat
  • KHR_materials_dispersion
  • KHR_materials_emissive_strength
  • KHR_materials_ior
  • KHR_materials_pbrSpecularGlossiness
  • KHR_materials_sheen
  • KHR_materials_specular
  • KHR_materials_transmission
  • KHR_materials_unlit
  • KHR_materials_variants
  • KHR_materials_volume
  • KHR_mesh_quantization
  • KHR_texture_basisu
  • KHR_texture_transform
  • EXT_meshopt_compression

Filament によるレンダリング

ネイティブの Linux、macOS、Windows

Engine、Renderer、SwapChain を作成する必要があります。SwapChain はネイティブウィンドウのポインターから作成します（たとえば、macOS では NSView、Windows では HWND です）。

Engine* engine = Engine::create();
SwapChain* swapChain = engine->createSwapChain(nativeWindow);
Renderer* renderer = engine->createRenderer();

フレームをレンダリングするには、続けて View、Scene、Camera を作成します。

Camera* camera = engine->createCamera(EntityManager::get().create());
View* view = engine->createView();
Scene* scene = engine->createScene();

view->setCamera(camera);
view->setScene(scene);

レンダリング可能なオブジェクトをシーンに追加します。

Entity renderable = EntityManager::get().create();
// build a quad
RenderableManager::Builder(1)
        .boundingBox({{ -1, -1, -1 }, { 1, 1, 1 }})
        .material(0, materialInstance)
        .geometry(0, RenderableManager::PrimitiveType::TRIANGLES, vertexBuffer, indexBuffer, 0, 6)
        .culling(false)
        .build(*engine, renderable);
scene->addEntity(renderable);

マテリアルインスタンスは、マテリアルから取得します。マテリアルは matc で生成されたバイナリ blob から読み込みます。

Material* material = Material::Builder()
        .package((void*) BAKED_MATERIAL_PACKAGE, sizeof(BAKED_MATERIAL_PACKAGE))
        .build(*engine);
MaterialInstance* materialInstance = material->createInstance();

マテリアルと matc の詳細については、マテリアルのドキュメントを参照してください。

レンダリングするには、View を Renderer に渡すだけです。

// beginFrame() returns false if we need to skip a frame
if (renderer->beginFrame(swapChain)) {
    // for each View
    renderer->render(view);
    renderer->endFrame();
}

Linux、macOS、Windows 向けの Filament アプリケーションの完全な例については、samples/ ディレクトリ内のソースファイルを参照してください。これらのサンプルはすべて libs/filamentapp/ をベースにしています。このディレクトリには、SDL2 でネイティブウィンドウを作成し、Filament のエンジン、レンダラー、ビューを初期化するコードが含まれています。

イメージベースドライティング用の環境マップを準備する方法の詳細については、BUILDING.mdを参照してください。

Android

Android で Filament を使用する例については、android/samples を参照してください。

Filament を使用する前に、必ず Filament.init() を呼び出して初期化してください。

Android での Filament のレンダリングは、ネイティブコードからのレンダリングと似ています（API は言語間でほぼ共通です）。Surface を createSwapChain メソッドに渡すと、その Surface にレンダリングできます。これにより、SurfaceTexture、TextureView、SurfaceView にレンダリングできます。簡単に利用できるように、com.google.android.filament.android パッケージには、Android 専用 API の UiHelper が用意されています。ヘルパーにレンダリングコールバックを設定し、SurfaceView または TextureView をアタッチするだけです。onNativeWindowChanged() コールバック内でのスワップチェーンの作成は、引き続きご自身で行う必要があります。

iOS

Filament は iOS 11.0 以降でサポートされています。iOS で Filament を使用する例については、ios/samples を参照してください。

iOS での Filament は、C++ によるネイティブレンダリングとほぼ同じです。CAEAGLLayer または CAMetalLayer を createSwapChain メソッドに渡します。iOS 版 Filament は Metal（推奨）と OpenGL ES の両方をサポートしています。

アセット

まずは、third_party/textures と third_party/environments にあるテクスチャと環境マップをそれぞれ使用できます。これらのアセットは CC0 ライセンスです。元の作者について詳しくは、それぞれの URL.txt ファイルを参照してください。

環境マップは、cmgen または libiblprefilter ライブラリを使って事前処理する必要があります。

貢献方法

CONTRIBUTING.md の手順を読み、それに従ってください。コードスタイルを確認してください。脆弱性の報告については、セキュリティポリシーを参照してください。

ディレクトリ構成

このリポジトリには、Filament のコアエンジンだけでなく、それを支えるライブラリやツールも含まれています。

• android: Android ライブラリとプロジェクト
  • filamat-android: Android 向け Filament マテリアル生成ライブラリ（AAR）
  • filament-android: Android 向け Filament ライブラリ（AAR）
  • filament-utils-android: 各種ユーティリティ（KTX ローダー、数学型など）
  • gltfio-android: Android 向け Filament glTF 読み込みライブラリ（AAR）
  • samples: Android 向け Filament サンプル
• art: 各種アートワークのソース（ロゴ、PDF マニュアルなど）
• assets: サンプルアプリケーションで使用する 3D アセット
• build: CMake ビルドスクリプト
• docs: ドキュメント
  • math: BRDF や方程式などの調査に使用する Mathematica ノートブック
• filament: Filament レンダリングエンジン（依存関係は最小限）
  • backend: レンダリングバックエンド／ドライバー（Vulkan、Metal、OpenGL/ES）
• ide: IDE 用設定ファイル（CLion など）
• ios: iOS 用サンプルプロジェクト
• libs: ライブラリ
  • bluegl: macOS、Linux、Windows 向け OpenGL バインディング
  • bluevk: macOS、Linux、Windows、Android 向け Vulkan バインディング
  • camutils: カメラ操作ユーティリティ
  • filabridge: Filament エンジンとホストツールで共有されるライブラリ
  • filaflat: マテリアルに使用するシリアライズ／デシリアライズライブラリ
  • filagui: Dear ImGui 用ヘルパーライブラリ
  • filamat: マテリアル生成ライブラリ
  • filamentapp: サンプルアプリを構築するための SDL2 スケルトン
  • filameshio: 軽量な filamesh 解析ライブラリ（tools/filamesh も参照）
  • geometry: メッシュ関連ユーティリティ
  • gltfio: glTF 2.0 ローダー
  • ibl: IBL 生成ツール
  • image: 画像フィルタリングと簡単な変換
  • imageio: 画像ファイルの読み書き（内部使用のみを想定）
  • matdbg: 実行時にシェーダーを調査するための DebugServer（デバッグビルドのみ）
  • math: 数学ライブラリ
  • mathio: 出力ストリーム向けの数学型サポート
  • utils: ユーティリティライブラリ（スレッド、メモリ、データ構造など）
  • viewer: glTF ビューアライブラリ（gltfio が必要）
• samples: デスクトップアプリケーションのサンプル
• shaders: filamat と matc で使用するシェーダー
• third_party: 外部ライブラリとアセット
  • environments: cmgen で使用できる CC0 ライセンスの環境マップ
  • models: 寛容なライセンスのモデル
  • textures: CC0 ライセンスのテクスチャ
• tools: ホストツール
  • cmgen: イメージベースドライティング用アセット生成ツール
  • filamesh: メッシュコンバーター
  • glslminifier: GLSL ソースコードを圧縮
  • matc: マテリアルコンパイラー
  • matedit: コンパイル済みマテリアル用マテリアルエディター
  • matinfo matc でコンパイルしたマテリアルの情報を表示
  • mipgen ソース画像から一連のミップレベルを生成
  • normal-blending: 法線マップをブレンドするツール
  • resgen バイナリデータを集約し、埋め込み可能なリソースを生成
  • roughness-prefilter: エイリアシングを軽減するため、法線マップから粗さマップを事前フィルタリング
  • specular-color: スペクトルデータに基づいて導体の鏡面反射色を計算
• web: JavaScript バインディング、ドキュメント、サンプル

ライセンス

LICENSE を参照してください。

免責事項

これは Google が公式にサポートしている製品ではありません。