- ×
Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS and WASM/WebGL
Filed under images › 3d graphicsShow AllFilament
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.42.2' }
Here are all the libraries available in the group
com.google.android.filament
:iOS
iOS projects can use CocoaPods to install the latest release:
pod 'Filament', '~> 1.42.2'
Snapshots
If you prefer to live on the edge, you can download a continuous build by following the following steps:
- Find the commit you're interested in.
- Click the green check mark under the commit message.
- Click on the Details link for the platform you're interested in.
- On the top left click Summary, then in the Artifacts section choose the desired 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
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
- WebGL 2.0 for all platforms
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: 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_emissive_strength
- [x] KHR_materials_ior
- [x] KHR_materials_pbrSpecularGlossiness
- [x] KHR_materials_sheen
- [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
, aRenderer
and aSwapChain
. TheSwapChain
is created from a native window pointer (anNSView
on macOS or aHWND
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
, aScene
and aCamera
: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 theRenderer
:// 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 onlibs/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 aSurface
to thecreateSwapChain
method. This allows you to render to aSurfaceTexture
, aTextureView
or aSurfaceView
. To make things easier we provide an Android specific API calledUiHelper
in the packagecom.google.android.filament.android
. All you need to do is set a render callback on the helper and attach yourSurfaceView
orTextureView
to it. You are still responsible for creating the swap chain in theonNativeWindowChanged()
callback.iOS
Filament is supported on iOS 11.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
orCAMetalLayer
is passed to thecreateSwapChain
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
andthird_party/environments
. These assets are under CC0 license. Please refer to their respectiveURL.txt
files to know more about the original authors.Environments must be pre-processed using
cmgen
or using thelibiblprefilter
library.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 projectsfilamat-android
: Filament material generation library (AAR) for Androidfilament-android
: Filament library (AAR) for Androidfilament-utils-android
: Extra utilities (KTX loader, math types, etc.)gltfio-android
: Filament glTF loading library (AAR) for Androidsamples
: Android-specific Filament samples
art
: Source for various artworks (logos, PDF manuals, etc.)assets
: 3D assets to use with sample applicationsbuild
: CMake build scriptsdocs
: Documentationmath
: Mathematica notebooks used to explore BRDFs, equations, etc.
filament
: Filament rendering engine (minimal dependencies)backend
: Rendering backends/drivers (Vulkan, Metal, OpenGL/ES)
ide
: Configuration files for IDEs (CLion, etc.)ios
: Sample projects for iOSlibs
: Librariesbluegl
: OpenGL bindings for macOS, Linux and Windowsbluevk
: Vulkan bindings for macOS, Linux, Windows and Androidcamutils
: Camera manipulation utilitiesfilabridge
: Library shared by the Filament engine and host toolsfilaflat
: Serialization/deserialization library used for materialsfilagui
: Helper library for Dear ImGuifilamat
: Material generation libraryfilamentapp
: SDL2 skeleton to build sample appsfilameshio
: Tiny filamesh parsing library (see alsotools/filamesh
)geometry
: Mesh-related utilitiesgltfio
: Loader for glTF 2.0ibl
: IBL generation toolsimage
: Image filtering and simple transformsimageio
: Image file reading / writing, only intended for internal usematdbg
: DebugServer for inspecting shaders at run-time (debug builds only)math
: Math librarymathio
: Math types support for output streamsutils
: Utility library (threads, memory, data structures, etc.)viewer
: glTF viewer library (requires gltfio)
samples
: Sample desktop applicationsshaders
: Shaders used byfilamat
andmatc
third_party
: External libraries and assetsenvironments
: Environment maps under CC0 license that can be used withcmgen
models
: Models under permissive licensestextures
: Textures under CC0 license
tools
: Host toolscmgen
: Image-based lighting asset generatorfilamesh
: Mesh converterglslminifier
: Minifies GLSL source codematc
: Material compilermatinfo
Displays information about materials compiled withmatc
mipgen
Generates a series of miplevels from a source imagenormal-blending
: Tool to blend normal mapsresgen
Aggregates binary blobs into embeddable resourcesroughness-prefilter
: Pre-filters a roughness map from a normal map to reduce aliasingspecular-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.