Installation Guide

Overview

Filament can be installed via package managers for mobile platforms or built from source for desktop development. Choose the installation method that best fits your platform and use case.

Platform-Specific Installation

Maven Central (Recommended)

Android projects can declare Filament libraries as Maven dependencies. This is the easiest way to use Filament on Android.

Add Maven Central to your repositories

In your project’s build.gradle or settings.gradle:

build.gradle

repositories {
    mavenCentral()
}

Add Filament dependencies

In your app’s build.gradle:

app/build.gradle

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

Initialize Filament in your app

Before using any Filament APIs, initialize the library:

MainActivity.kt

class MainActivity : Activity() {
    companion object {
        init {
            Filament.init()
        }
    }
}

Available Libraries

All libraries are in the com.google.android.filament group:

Artifact	Version	Description
`filament-android`	1.69.4	Core Filament rendering engine
`filament-android-debug`	1.69.4	Debug version with validation
`gltfio-android`	1.69.4	glTF 2.0 loader (depends on `filament-android`)
`filament-utils-android`	1.69.4	KTX loading, Kotlin math, camera utilities
`filamat-android`	1.69.4	Runtime material compiler (large, includes full shader compiler)

Example: Full Stack

For a complete Filament setup with glTF loading and utilities:

app/build.gradle

dependencies {
    implementation 'com.google.android.filament:filament-android:1.69.4'
    implementation 'com.google.android.filament:gltfio-android:1.69.4'
    implementation 'com.google.android.filament:filament-utils-android:1.69.4'
}

Supported ABIs

The AAR contains binaries for all Android ABIs:

arm64-v8a (ARM 64-bit, recommended)
armeabi-v7a (ARM 32-bit)
x86_64 (Intel 64-bit)
x86 (Intel 32-bit)

ARM 64-bit (arm64-v8a) is the primary target and receives the most optimization. Use abiFilters in your Gradle configuration to include only the ABIs you need.

Filtering ABIs

To reduce APK size, filter specific ABIs:

app/build.gradle

android {
    defaultConfig {
        ndk {
            abiFilters 'arm64-v8a', 'armeabi-v7a'
        }
    }
}

Or use flavor dimensions:

app/build.gradle

android {
    flavorDimensions 'cpuArch'
    productFlavors {
        arm8 {
            dimension 'cpuArch'
            ndk {
                abiFilters 'arm64-v8a'
            }
        }
        arm7 {
            dimension 'cpuArch'
            ndk {
                abiFilters 'armeabi-v7a'
            }
        }
        universal {
            dimension 'cpuArch'
        }
    }
}

CocoaPods (Recommended)

The easiest way to use Filament on iOS is via CocoaPods.

Install CocoaPods

If you don’t have CocoaPods installed:

sudo gem install cocoapods

Create or update Podfile

In your iOS project directory, create a Podfile:

Podfile

platform :ios, '11.0'

target 'YourApp' do
  use_frameworks!
  pod 'Filament', '~> 1.69.4'
end

Install dependencies

pod install

Open the workspace

open YourApp.xcworkspace

Always use the .xcworkspace file, not the .xcodeproj file, when working with CocoaPods.

Requirements

iOS 11.0 or higher
Xcode (latest stable version recommended)

Backend Support

Filament on iOS supports:

Metal (preferred, best performance)
OpenGL ES 3.0+

The Metal backend is recommended for production apps as it provides better performance and is the native graphics API for iOS.

Creating a SwapChain

On iOS, pass either a CAMetalLayer or CAEAGLLayer to create the swap chain:

// Metal (recommended)
SwapChain* swapChain = engine->createSwapChain(metalLayer);

// OpenGL ES
SwapChain* swapChain = engine->createSwapChain(eaglLayer);

Sample Projects

Filament includes complete iOS sample projects. See ios/samples/ in the repository for examples including:

Hello Triangle
glTF Viewer
Material Sandbox

Prerequisites

Before building Filament on Linux, install the required dependencies:

Install build tools and dependencies

On Ubuntu/Debian:

sudo apt install clang-16 libglu1-mesa-dev libc++-16-dev libc++abi-16-dev \
                 ninja-build libxi-dev libxcomposite-dev libxxf86vm-dev -y

On Fedora:

sudo dnf install clang libglu-devel libcxx-devel libcxx-static libcxxabi-static \
                 ninja-build libXi-devel libXcomposite-devel libXxf86vm-devel

Verify Clang version

clang --version

You need Clang 16.0 or higher. If your distribution defaults to GCC, you may need to set environment variables:

export CC=/usr/bin/clang
export CXX=/usr/bin/clang++
export CXXFLAGS=-stdlib=libc++

Building from Source

Clone the repository

git clone https://github.com/google/filament.git
cd filament

Build release

Use the convenient build script:

./build.sh release

This builds Filament and installs it to out/release/filament/.

Optional: Install to system

To install libraries and tools system-wide:

./build.sh -i release

Manual CMake Build

For more control, you can invoke CMake directly:

mkdir out/cmake-release
cd out/cmake-release
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=../release/filament \
      -DCMAKE_C_COMPILER=clang \
      -DCMAKE_CXX_COMPILER=clang++ \
      -DCMAKE_CXX_FLAGS=-stdlib=libc++ \
      ../..
ninja
ninja install

Backend Support

Linux builds support:

OpenGL 4.1+
Vulkan 1.0
WebGPU

Additional Options

The build.sh script supports many options:

./build.sh -h                    # Show help
./build.sh -c release            # Clean build
./build.sh debug release         # Build both debug and release
./build.sh -i release            # Build and install

Prerequisites

Install Xcode

Install the latest version of Xcode from the App Store.

Install Xcode Command Line Tools

xcode-select --install

Optional: Install Vulkan SDK

If you want to use the Vulkan backend instead of Metal:

Download and install the LunarG Vulkan SDK
Enable “System Global Components” during installation
Reboot your machine

Building from Source

Clone the repository

git clone https://github.com/google/filament.git
cd filament

Build release

./build.sh release

Output will be in out/release/filament/.

Run a sample

./out/cmake-release/samples/hellotriangle

Manual CMake Build

mkdir out/cmake-release
cd out/cmake-release
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=../release/filament \
      ../..
ninja
ninja install

Backend Support

macOS builds support:

Metal (default, recommended)
OpenGL 4.1+
Vulkan 1.0 (requires LunarG SDK)
WebGPU

macOS Deployment Target

Filament requires macOS 10.15 or higher. This is set automatically in the CMake configuration.

Prerequisites

Install Visual Studio

Install Visual Studio 2019 or later with C++ development tools.

Install Windows SDK

Install the Windows SDK.You can also install it through Visual Studio: Tools → Get Tools and Features → Individual Components → Windows SDK.

Install CMake

Install CMake 3.14 or later.Make sure to add CMake to your system PATH during installation.

Install Python

Install Python 3.7 or later.

Do not enable case sensitivity in your repository. Windows treats the file system as case insensitive by default, and CMake expects this behavior.

Building from Source

Open x64 Native Tools Command Prompt

Open “x64 Native Tools Command Prompt for VS 2019” (or later) from the Start menu.

Clone the repository

git clone https://github.com/google/filament.git
cd filament

Generate Visual Studio solution

mkdir out
cd out
cmake ..

This creates TNT.sln in the out directory.

Build with Visual Studio

Open TNT.sln in Visual Studio and build the solution:

Build → Build Solution (or press Ctrl+Shift+B)

Alternatively, build from the command line:

cmake --build . --config Release

Run a sample

samples\Release\hellotriangle.exe

Building Specific Targets

To build a specific target from the command line:

cmake --build . --target gltf_viewer --config Release

Backend Support

Windows builds support:

OpenGL 4.1+
Vulkan 1.0
WebGPU

Prerequisites

First, set up your host platform (macOS or Linux) following the instructions in those tabs.

Install Emscripten SDK

Download and install Emscripten

cd <your chosen parent folder>
curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.60.zip > emsdk.zip
unzip emsdk.zip
mv emsdk-* emsdk
cd emsdk

Install and activate Emscripten

python ./emsdk.py install latest
python ./emsdk.py activate latest
source ./emsdk_env.sh

Set EMSDK environment variable

export EMSDK=<your chosen folder>/emsdk

Add this to your shell profile (.bashrc, .zshrc, etc.) to make it permanent.

Building for WebGL

Navigate to Filament directory

cd filament

Build for WebGL

export EMSDK=<path to emsdk>
./build.sh -p webgl release

This creates WebAssembly binaries and samples in out/cmake-webgl-release/web/samples/.

Run a local web server

You cannot open the HTML files directly due to CORS restrictions. Use emrun:

emrun out/cmake-webgl-release/web/samples --no_browser --port 8000

Then open http://localhost:8000/suzanne.html in your browser.

Alternative: Using live-server

If you have Node.js installed:

npm install -g live-server
cd out/cmake-webgl-release/web/samples
live-server --port=8000

The live-server package automatically refreshes the page when files change, which is useful during development.

Binary Releases

Download Pre-built Releases

For desktop platforms, you can download pre-built binaries instead of building from source:

Visit the Filament Releases page
Download the archive for your platform
Extract the archive

Release archives contain:

Host-side tools (matc, cmgen, filamesh, etc.)
Libraries for your platform
Header files
Sample applications

Always use tools from the same release as your runtime library. This is particularly important for matc (material compiler), as material formats can change between versions.

Essential Tools

Filament includes several command-line tools for asset preparation:

matc (Material Compiler)

Compiles material definitions into optimized shader packages:

matc -o output.filamat input.mat

Location after build: out/release/filament/bin/matc

cmgen (Cubemap Generator)

Generates image-based lighting assets from environment maps:

cmgen -x ./ibls/ -f ktx environment.hdr

Location after build: out/release/filament/bin/cmgen

filamesh (Mesh Converter)

Converts OBJ/FBX files to Filament’s native mesh format:

filamesh model.obj model.filamesh

Location after build: out/release/filament/bin/filamesh

gltf_viewer

A complete glTF 2.0 viewer for testing models:

gltf_viewer model.gltf

Location after build: out/cmake-release/samples/gltf_viewer

All tools support the --help flag to display usage information and available options.

Build Options

CMake Options

Filament supports several CMake options to customize your build:

Option	Description	Default
`FILAMENT_ENABLE_LTO`	Enable link-time optimizations	OFF
`FILAMENT_BUILD_FILAMAT`	Build filamat and JNI bindings	ON
`FILAMENT_SUPPORTS_OPENGL`	Include OpenGL backend	ON
`FILAMENT_SUPPORTS_METAL`	Include Metal backend	ON (macOS/iOS)
`FILAMENT_SUPPORTS_VULKAN`	Include Vulkan backend	ON
`FILAMENT_SKIP_SAMPLES`	Don’t build sample apps	OFF

To set an option:

cmake -DFILAMENT_ENABLE_LTO=ON -DFILAMENT_SKIP_SAMPLES=ON ..

build.sh Options

The build.sh script accepts several useful flags:

./build.sh [options] <build_type>

Common options:

-c: Clean build (removes out/ directory)
-i: Install to out/release/ or out/debug/
-p <platform>: Target platform (android, ios, webgl)
-q <abi>: Android ABI (arm64-v8a, armeabi-v7a, x86_64, x86)
-k <name>: Build specific sample (e.g., sample-hello-triangle)
-h: Show all available options

Example: Build Android Sample

./build.sh -p android -q arm64-v8a -k sample-hello-triangle release

Output APK: android/samples/sample-hello-triangle/build/outputs/apk/release/

Verifying Installation

Desktop (Linux/macOS/Windows)

After building, verify the installation:

# Check that tools are available
ls out/release/filament/bin/

# Should show: matc, cmgen, filamesh, and other tools

# Run a sample
./out/cmake-release/samples/hellotriangle

Android

Verify your Gradle dependencies:

./gradlew app:dependencies | grep filament

You should see:

+--- com.google.android.filament:filament-android:1.69.4

iOS

Verify CocoaPods installation:

pod list | grep Filament

You should see:

Filament (1.69.4)

Troubleshooting

Android: “Filament not initialized”

Make sure you call Filament.init() before using any Filament APIs:

companion object {
    init {
        Filament.init()
    }
}

Linux: Compiler errors with GCC

Filament requires Clang. Set the compiler explicitly:

export CC=/usr/bin/clang
export CXX=/usr/bin/clang++
export CXXFLAGS=-stdlib=libc++

macOS: Vulkan not found

Install the LunarG Vulkan SDK and enable “System Global Components”, then reboot.

Windows: CMake cannot find Visual Studio

Use the “x64 Native Tools Command Prompt” instead of the regular command prompt.

WebAssembly: CORS errors

Don’t open HTML files directly from the file system. Always use a local web server (emrun or live-server).

Next Steps

Quick Start

Build your first Filament application with the Hello Triangle example

API Reference

Explore the complete API documentation

Materials Guide

Learn how to create and compile materials

Samples

Browse example applications and code snippets

Getting Started

Core Concepts

Platform Guides

Material System

Rendering Features

Asset Pipeline

Tools

Advanced Topics

​Overview

​Platform-Specific Installation

​Maven Central (Recommended)

​Available Libraries

​Example: Full Stack

​Supported ABIs

​Filtering ABIs

​CocoaPods (Recommended)

​Requirements

​Backend Support

​Creating a SwapChain

​Sample Projects

​Prerequisites

​Building from Source

​Manual CMake Build

​Backend Support

​Additional Options

​Prerequisites

​Building from Source

​Manual CMake Build

​Backend Support

​macOS Deployment Target

​Prerequisites

​Building from Source

​Building Specific Targets

​Backend Support

​Prerequisites

​Install Emscripten SDK

​Building for WebGL

​Alternative: Using live-server

​Binary Releases

​Download Pre-built Releases

​Essential Tools

​matc (Material Compiler)

​cmgen (Cubemap Generator)

​filamesh (Mesh Converter)

​gltf_viewer

​Build Options

​CMake Options

​build.sh Options

​Example: Build Android Sample

​Verifying Installation

​Desktop (Linux/macOS/Windows)

​Android

​iOS

​Troubleshooting

​Android: “Filament not initialized”

​Linux: Compiler errors with GCC

​macOS: Vulkan not found

​Windows: CMake cannot find Visual Studio

​WebAssembly: CORS errors

​Next Steps

Quick Start

API Reference

Materials Guide

Samples

Build docs developers (and LLMs) love

Overview

Platform-Specific Installation

Maven Central (Recommended)

Available Libraries

Example: Full Stack

Supported ABIs

Filtering ABIs

CocoaPods (Recommended)

Requirements

Backend Support

Creating a SwapChain

Sample Projects

Prerequisites

Building from Source

Manual CMake Build

Backend Support

Additional Options

Prerequisites

Building from Source

Manual CMake Build

Backend Support

macOS Deployment Target

Prerequisites

Building from Source

Building Specific Targets

Backend Support

Prerequisites

Install Emscripten SDK

Building for WebGL

Alternative: Using live-server

Binary Releases

Download Pre-built Releases

Essential Tools

matc (Material Compiler)

cmgen (Cubemap Generator)

filamesh (Mesh Converter)

gltf_viewer

Build Options

CMake Options

build.sh Options

Example: Build Android Sample

Verifying Installation

Desktop (Linux/macOS/Windows)

Android

iOS

Troubleshooting

Android: “Filament not initialized”

Linux: Compiler errors with GCC

macOS: Vulkan not found

Windows: CMake cannot find Visual Studio

WebAssembly: CORS errors

Next Steps