Skip to content
Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS and WASM/WebGL
C++ C Assembly Java Kotlin Objective-C++ Other
Branch: master
Clone or download

Latest commit

pixelflinger Fix refracted objects drawing order (#2577)
Refracted objects could be drawn on top of opaque objects that were
closer to the camera.

Du to a typo, we were not reusing the existing depth buffer during the
refraction pass.

Fixes #2576
Latest commit 8415d18 May 24, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Make CI scripts safer (#2456) Apr 25, 2020
android Gradle: update old property name. May 23, 2020
art first step of lispsm documentation Apr 6, 2019
assets Add Color::absorptionAtDistance() to compute absorption for refractio… Dec 11, 2019
build Enable Vulkan for Android by default. May 18, 2020
docs Clarify doc May 10, 2020
filament Fix refracted objects drawing order (#2577) May 24, 2020
ide/clion update code style / formatting clion config files Apr 26, 2019
ios/samples API BREAKAGE: this change aims to fix multi-view support (#2376) Apr 10, 2020
java add vsync timestamp to Renderer::beginFrame() API Apr 6, 2020
libs filamat: generate spirv 1.0 rather than spirv 1.3 May 21, 2020
samples Add headless support to FilamentApp and frame_generator. May 14, 2020
shaders Fix a few issues with dithering May 14, 2020
site Update WebGL docs and website. Feb 25, 2020
third_party Fix compilation issues under ubuntu 20 and latest clang (#2562) May 24, 2020
tools matinfo / matdbg: fix SPIRV version, add validation. May 19, 2020
web Tweak WebGL build settings. May 18, 2020
.gitignore Remove gltf_baker and related libraries. Apr 2, 2020
BUILDING.md Very basic SwiftShader support (#2523) May 13, 2020
CMakeLists.txt Enable Vulkan for Android by default. May 18, 2020
CODE_STYLE.md Modify incorrect static format (#979) Mar 14, 2019
CONTRIBUTING.md Rewrite Maven publish tasks to support multiple flavors (#2022) Jan 11, 2020
LICENSE Initial commit Aug 3, 2018
README.md Update README.md May 21, 2020
RELEASE_NOTES.md Update RELEASE_NOTES.md May 16, 2020
build.sh Enable Vulkan for Android by default. May 18, 2020

README.md

Filament

Android Build Status iOS Build Status Linux Build Status macOS Build Status Windows Build Status Web Build Status

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.7.0'
}

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

filament-android
The Filament rendering engine itself.

gltfio-android
A glTF 2.0 loader for Filament, depends on filament-android .

gltfio-android-lite
Trimmed version of gltfio that does not support some glTF features.

filament-utils-android
KTX loading, Kotlin math, and camera utilities, depends on gltfio-android.

filament-utils-android-lite
Trimmed version of filament-utils that does not support some glTF features.

filamat-android
A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer.

filamat-android-lite
A much smaller alternative to filamat-android that can only generate OpenGL shaders. It does not provide validation or optimizations.

Snapshots

If you prefer to live on the edge, you can download a continuous build by following the following steps:

  1. Find the commit you're interested in.
  2. Click the green check mark under the commit message.
  3. Click on the Details link for the platform you're interested in.
  4. On the top right, click on the Artifacts dropdown and choose an artifact.

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

Night scene Night scene Materials Materials Helmet Screen-space refraction

Applications

Here are a few screenshots of applications that use Filament in production:

Google Maps AR Navigation

Google Maps AR Navigation

Google Search 3D/AR Viewer on Android

Google Search 3D/AR Viewer on Android

Features

APIs

  • Native C++ API for Android, iOS, Linux, macOS and Windows
  • Java/JNI API for Android, Linux, macOS and Windows
  • 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
  • WebGL 2.0 for all platforms

Rendering

  • Clustered forward renderer
  • Cook-Torrance microfacet specular BRDF
  • Lambertian diffuse BRDF
  • HDR/linear lighting
  • Metallic workflow
  • Clear coat
  • Anisotropic lighting
  • Approximated translucent (subsurface) materials
  • Cloth 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
  • Spot and directional light shadows
  • Contact shadows
  • Screen-space ambient occlusion
  • Screen-space refraction
  • Global fog
  • HDR bloom
  • Depth of field bokeh
  • ACES-like tone-mapping
  • Temporal dithering
  • FXAA, MSAA and specular anti-aliasing
  • Dynamic resolution

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();
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 samples/app/ which contains the code that creates a native window with SDL2 and initializes the Filament engine, renderer and views.

Java on Linux, macOS and Windows

After building Filament, you can use filament-java.jar and its companion filament-jni native library to use Filament in desktop Java applications.

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

You can use Filament either with AWT or Swing, using respectively a FilamentCanvas or a FilamentPanel.

Following the steps above (how to use Filament from native code), create an Engine and a Renderer, but instead of calling beginFrame and endFrame on the renderer itself, call these methods on FilamentCanvas or FilamentPanel.

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. To make things easier we provide an Android specific API called UiHelper in the package com.google.android.filament.android. All you need to do is set a render callback on the helper and attach your SurfaceView or TextureView to it. You are still responsible for creating the swap chain in the onNativeWindowChanged() callback.

iOS

Filament is supported on iOS 12.0 and above. See ios/samples for examples of using Filament on iOS.

Filament on iOS is largely the same as native rendering with C++. A CAEAGLLayer or CAMetalLayer is passed to the createSwapChain method. Filament for iOS supports both Metal (preferred) and OpenGL ES.

Assets

To get started you can use the textures and environment maps found respectively in third_party/textures and third_party/environments. These assets are under CC0 license. Please refer to their respective URL.txt files to know more about the original authors.

How to make contributions

Please read and follow the steps in CONTRIBUTING.md. Make sure you are familiar with the code style.

Directory structure

This repository not only contains the core Filament engine, but also its supporting libraries and tools.

  • android: Android libraries and projects
    • filamat-android: Filament material generation library (AAR) for Android
    • filament-android: Filament library (AAR) for Android
    • gltfio-android: Filament glTF loading library (AAR) for Android
    • samples: Android-specific Filament samples
  • art: Source for various artworks (logos, PDF manuals, etc.)
  • assets: 3D assets to use with sample applications
  • build: CMake build scripts
  • docs: Documentation
    • math: Mathematica notebooks used to explore BRDFs, equations, etc.
  • filament: Filament rendering engine (minimal dependencies)
  • ide: Configuration files for IDEs (CLion, etc.)
  • ios: Sample projects for iOS
  • java: Java bindings for Filament libraries
  • libs: Libraries
    • bluegl: OpenGL bindings for macOS, Linux and Windows
    • bluevk: Vulkan bindings for macOS, Linux, Windows and Android
    • filabridge: Library shared by the Filament engine and host tools
    • filaflat: Serialization/deserialization library used for materials
    • filagui: Helper library for Dear ImGui
    • filamat: Material generation library
    • filameshio: Tiny filamesh parsing library (see also tools/filamesh)
    • geometry: Mesh-related utilities
    • gltfio: Loader for glTF 2.0
    • ibl: IBL generation tools
    • image: Image filtering and simple transforms
    • imageio: Image file reading / writing, only intended for internal use
    • matdbg: DebugServer for inspecting shaders at run-time (debug builds only)
    • math: Math library
    • utils: Utility library (threads, memory, data structures, etc.)
  • samples: Sample desktop applications
  • shaders: Shaders used by filamat and matc
  • third_party: External libraries and assets
    • environments: Environment maps under CC0 license that can be used with cmgen
    • models: Models under permissive licenses
    • textures: Textures under CC0 license
  • tools: Host tools
    • cmgen: Image-based lighting asset generator
    • filamesh: Mesh converter
    • glslminifier: Minifies GLSL source code
    • matc: Material compiler
    • matinfo Displays information about materials compiled with matc
    • mipgen Generates a series of miplevels from a source image
    • normal-blending: Tool to blend normal maps
    • resgen Aggregates binary blobs into embeddable resources
    • roughness-prefilter: Pre-filters a roughness map from a normal map to reduce aliasing
    • skygen: Physically-based sky environment texture generator
    • specular-color: Computes the specular color of conductors based on spectral data
  • web: JavaScript bindings, documentation, and samples

License

Please see LICENSE.

Disclaimer

This is not an officially supported Google product.

You can’t perform that action at this time.