Filament

Filament is a real-time physically based rendering engine for Android, iOS, Linux, macOS, Windows, and WebGL. It is designed to be as small as possible and as efficient as possible on Android.

Download

Download Filament releases to access stable builds. Filament release archives contains host-side tools that are required to generate assets.

Make sure you always use tools from the same release as the runtime library. This is particularly important for matc (material compiler).

If you'd rather build Filament yourself, please refer to our build manual.

Android

Android projects can simply declare Filament libraries as Maven dependencies:

repositories {
    // ...
    mavenCentral()
}

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

Here are all the libraries available in the group com.google.android.filament:

| Artifact | Description | | ------------- | ------------- | | | The Filament rendering engine itself. | | | Debug version of filament-android. | | | A glTF 2.0 loader for Filament, depends on filament-android. | | | KTX loading, Kotlin math, and camera utilities, depends on gltfio-android. | | | A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan. |

iOS

iOS projects can use CocoaPods to install the latest release:

pod 'Filament', '~> 1.70.0'

Documentation

• Filament, an in-depth explanation of real-time physically based rendering, the graphics capabilities and implementation of Filament. This document explains the math and reasoning behind most of our decisions. This document is a good introduction to PBR for graphics programmers.
• Materials, the full reference documentation for our material system. This document explains our different material models, how to use the material compiler matc and how to write custom materials.
• Material Properties, a reference sheet for the standard material model.

Examples

Features

APIs

• Native C++ API for Android, iOS, Linux, macOS and Windows
• Java/JNI API for Android
• JavaScript API

Backends

• OpenGL 4.1+ for Linux, macOS and Windows
• OpenGL ES 3.0+ for Android and iOS
• Metal for macOS and iOS
• Vulkan 1.0 for Android, Linux, macOS, and Windows
• WebGPU for Android, Linux, macOS, and Windows
• WebGL 2.0 for all browsers supporting it

Rendering

• Clustered forward renderer
• Cook-Torrance microfacet specular BRDF
• Lambertian diffuse BRDF
• Custom lighting/surface shading
• HDR/linear lighting
• Metallic workflow
• Clear coat
• Anisotropic lighting
• Approximated translucent (subsurface) materials
• Cloth/fabric/sheen shading
• Normal mapping & ambient occlusion mapping
• Image-based lighting
• Physically-based camera (shutter speed, sensitivity and aperture)
• Physical light units
• Point lights, spot lights, and directional light
• Specular anti-aliasing
• Point, spot, and directional light shadows
• Cascaded shadows
• EVSM, PCSS, DPCF, or PCF shadows
• Transparent shadows
• Contact shadows
• Screen-space ambient occlusion
• Screen-space reflections
• Screen-space refraction
• Global fog
• Dynamic resolution (with support for AMD FidelityFX FSR)

Post processing

• HDR bloom
• Depth of field bokeh
• Multiple tone mappers: PBR Neutral, AgX, generic (customizable), ACES, filmic, etc.
• Color and tone management: luminance scaling, gamut mapping
• Color grading: exposure, night adaptation, white balance, channel mixer, shadows/mid-tones/highlights, ASC CDL, contrast, saturation, etc.
• TAA, FXAA, MSAA
• Screen-space lens flares

glTF 2.0

• Encodings

  • [x] Embeded
  • [x] Binary

• Primitive Types

  • [x] Points
  • [x] Lines
  • [ ] Line Loop
  • [x] Line Strip
  • [x] Triangles
  • [x] Triangle Strip
  • [ ] Triangle Fan

• Animation

  • [x] Transform animation
  • [x] Linear interpolation
  • [x] Morph animation
    • [x] Sparse accessor
  • [x] Skin animation
  • [x] Joint animation

• Extensions

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

Rendering with Filament

Native Linux, macOS and Windows

You must create an Engine, a Renderer and a SwapChain. The SwapChain is created from a native window pointer (an NSView on macOS or a HWND on Windows for instance):

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

To render a frame you must then create a View, a Scene and a Camera:

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

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

Renderables are added to the 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);

The material instance is obtained from a material, itself loaded from a binary blob generated by matc:

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

To learn more about materials and matc, please refer to the materials documentation.

To render, simply pass the View to the Renderer:

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

For complete examples of Linux, macOS and Windows Filament applications, look at the source files in the samples/ directory. These samples are all based on libs/filamentapp/ which contains the code that creates a native window with SDL2 and initializes the Filament engine, renderer and views.

For more information on how to prepare environment maps for image-based lighting please refer to BUILDING.md.

Android

See android/samples for examples of how to use Filament on Android.

You must always first initialize Filament by calling Filament.init().

Rendering with Filament on Android is similar to rendering from native code (the APIs are largely the same across languages). You can render into a Surface by passing a Surface to the createSwapChain method. This allows you to render to a SurfaceTexture, a TextureView or a SurfaceView.