Repository files navigation

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 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 particularlyimportant formatc (material compiler).

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

Android projects can simply declare Filament libraries as Maven dependencies:

repositories {// ...    mavenCentral()}dependencies {    implementation'com.google.android.filament:filament-android:1.68.2'}

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

Artifact	Description
	The Filament rendering engine itself.
	Debug version offilament-android.
	A glTF 2.0 loader for Filament, depends onfilament-android.
	KTX loading, Kotlin math, and camera utilities, depends ongltfio-android.
	A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan.
	A much smaller alternative tofilamat-android that can only generate OpenGL shaders. It does not provide validation or optimizations.

iOS projects can use CocoaPods to install the latest release:

pod'Filament','~> 1.68.2'

• Filament, an in-depth explanation ofreal-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 agood introduction to PBR for graphics programmers.
• Materials, the full referencedocumentation for our material system. This document explains our different material models, howto use the material compilermatc and how to write custom materials.
• Material Properties, a referencesheet for the standard material model.

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

• 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

• 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)

• 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

• Encodings

  • Embeded
  • Binary

• Primitive Types

  • Points
  • Lines
  • Line Loop
  • Line Strip
  • Triangles
  • Triangle Strip
  • Triangle Fan

• Animation

  • Transform animation
  • Linear interpolation
  • Morph animation
    • Sparse accessor
  • Skin animation
  • Joint animation

• Extensions

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

You must create anEngine, aRenderer and aSwapChain. TheSwapChain is created from anative 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 aView, 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 quadRenderableManager::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 generatedbymatc:

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

To learn more about materials andmatc, please refer to thematerials documentation.

To render, simply pass theView to theRenderer:

// beginFrame() returns false if we need to skip a frameif (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 filesin thesamples/ directory. These samples are all based onlibs/filamentapp/ which contains thecode 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 toBUILDING.md.

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

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

Rendering with Filament on Android is similar to rendering from native code (the APIs are largelythe same across languages). You can render into aSurface by passing aSurface to thecreateSwapChain method. This allows you to render to aSurfaceTexture, aTextureView oraSurfaceView. To make things easier we provide an Android specific API calledUiHelper in thepackagecom.google.android.filament.android. All you need to do is set a render callback on thehelper and attach yourSurfaceView orTextureView to it. You are still responsible forcreating the swap chain in theonNativeWindowChanged() callback.

Filament is supported on iOS 11.0 and above. Seeios/samples for examples of using Filament oniOS.

Filament on iOS is largely the same as native rendering with C++. ACAEAGLLayer orCAMetalLayeris passed to thecreateSwapChain method. Filament for iOS supports both Metal (preferred) andOpenGL ES.

To get started you can use the textures and environment maps found respectively inthird_party/textures andthird_party/environments. These assets are under CC0 license. Pleaserefer to their respectiveURL.txt files to know more about the original authors.

Environments must be pre-processed usingcmgen orusing thelibiblprefilter library.

Please read and follow the steps inCONTRIBUTING.md. Make sure you arefamiliar with thecode style.

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

• android: Android libraries and projects
  • filamat-android: Filament material generation library (AAR) for Android
  • filament-android: Filament library (AAR) for Android
  • filament-utils-android: Extra utilities (KTX loader, math types, etc.)
  • 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)
  • backend: Rendering backends/drivers (Vulkan, Metal, OpenGL/ES)
• ide: Configuration files for IDEs (CLion, etc.)
• ios: Sample projects for iOS
• libs: Libraries
  • bluegl: OpenGL bindings for macOS, Linux and Windows
  • bluevk: Vulkan bindings for macOS, Linux, Windows and Android
  • camutils: Camera manipulation utilities
  • filabridge: Library shared by the Filament engine and host tools
  • filaflat: Serialization/deserialization library used for materials
  • filagui: Helper library forDear ImGui
  • filamat: Material generation library
  • filamentapp: SDL2 skeleton to build sample apps
  • filameshio: Tiny filamesh parsing library (see alsotools/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
  • mathio: Math types support for output streams
  • utils: Utility library (threads, memory, data structures, etc.)
  • viewer: glTF viewer library (requires gltfio)
• samples: Sample desktop applications
• shaders: Shaders used byfilamat andmatc
• third_party: External libraries and assets
  • environments: Environment maps under CC0 license that can be used withcmgen
  • 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
  • filament-matp: Material parser
  • matinfo Displays information about materials compiled withmatc
  • 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
  • specular-color: Computes the specular color of conductors based on spectral data
• web: JavaScript bindings, documentation, and samples

Please seeLICENSE.

This is not an officially supported Google product.